Skip to content

Storage

StorageModule

Cookie storage operations.

Source code in bidiwave/modules/storage.py 
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
class StorageModule:
    """Cookie storage operations."""

    def __init__(self, connection: Connection) -> None:
        self._connection = connection

    async def get_cookies(
        self,
        context: Any | None = None,
        filter: dict[str, Any] | None = None,
        partition: dict[str, Any] | None = None,
    ) -> list[Cookie]:
        """Gets cookies, optionally filtered.

        Args:
            context: Context to scope to (mapped to a context partition).
            filter: CookieFilter dict, e.g. {"name": "...", "domain": "..."}.
            partition: PartitionDescriptor dict
                ({"type": "context", ...} or {"type": "storageKey", ...}).
        """
        params: dict[str, Any] = {}
        if filter is not None:
            params["filter"] = filter
        if partition is not None:
            params["partition"] = partition
        elif context is not None:
            ctx_id = context.id if hasattr(context, "id") else str(context)
            params["partition"] = {"type": "context", "context": ctx_id}
        result = await self._connection.send_command(STORAGE_GET_COOKIES, params)
        parsed = GetCookiesResult.model_validate(result)
        return parsed.cookies

    async def set_cookie(
        self,
        context: Any | None,
        cookie: Cookie,
        partition: dict[str, Any] | None = None,
    ) -> None:
        """Sets a cookie.

        Args:
            context: Context to scope to (ignored when `partition` is given).
            cookie: Cookie model to store.
            partition: PartitionDescriptor dict.
        """
        cookie_dict = cookie.model_dump(by_alias=True, exclude_none=True)
        # Spec: cookie value is a network.BytesValue, not a raw string.
        cookie_dict["value"] = {"type": "string", "value": cookie.value}
        params: dict[str, Any] = {"cookie": cookie_dict}
        if partition is not None:
            params["partition"] = partition
        elif context is not None:
            ctx_id = context.id if hasattr(context, "id") else str(context)
            params["partition"] = {"type": "context", "context": ctx_id}
        await self._connection.send_command(STORAGE_SET_COOKIE, params)

    async def delete_cookies(
        self,
        context: Any | None = None,
        name: str | None = None,
        domain: str | None = None,
        path: str | None = None,
        partition: dict[str, Any] | None = None,
    ) -> None:
        """Deletes cookies matching the filter.

        Args:
            context: Context to scope to (ignored when `partition` is given).
            name: Delete only cookies with this name.
            domain: Delete only cookies for this domain.
            path: Delete only cookies with this path.
            partition: PartitionDescriptor dict.
        """
        params: dict[str, Any] = {}
        cookie_filter = {
            k: v
            for k, v in {"name": name, "domain": domain, "path": path}.items()
            if v is not None
        }
        if cookie_filter:
            params["filter"] = cookie_filter
        if partition is not None:
            params["partition"] = partition
        elif context is not None:
            ctx_id = context.id if hasattr(context, "id") else str(context)
            params["partition"] = {"type": "context", "context": ctx_id}
        await self._connection.send_command(STORAGE_DELETE_COOKIES, params)

    async def delete_cookie(self, context: Any | None, name: str) -> None:
        """Deletes a single cookie by name."""
        await self.delete_cookies(context, name=name)

get_cookies async 

get_cookies(context: Any | None = None, filter: dict[str, Any] | None = None, partition: dict[str, Any] | None = None) -> list[Cookie]

Gets cookies, optionally filtered.

Parameters:

Name Type Description Default
context Any | None

Context to scope to (mapped to a context partition).

 None
filter dict[str, Any] | None

CookieFilter dict, e.g. {"name": "...", "domain": "..."}.

 None
partition dict[str, Any] | None

PartitionDescriptor dict ({"type": "context", ...} or {"type": "storageKey", ...}).

 None
Source code in bidiwave/modules/storage.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
async def get_cookies(
    self,
    context: Any | None = None,
    filter: dict[str, Any] | None = None,
    partition: dict[str, Any] | None = None,
) -> list[Cookie]:
    """Gets cookies, optionally filtered.

    Args:
        context: Context to scope to (mapped to a context partition).
        filter: CookieFilter dict, e.g. {"name": "...", "domain": "..."}.
        partition: PartitionDescriptor dict
            ({"type": "context", ...} or {"type": "storageKey", ...}).
    """
    params: dict[str, Any] = {}
    if filter is not None:
        params["filter"] = filter
    if partition is not None:
        params["partition"] = partition
    elif context is not None:
        ctx_id = context.id if hasattr(context, "id") else str(context)
        params["partition"] = {"type": "context", "context": ctx_id}
    result = await self._connection.send_command(STORAGE_GET_COOKIES, params)
    parsed = GetCookiesResult.model_validate(result)
    return parsed.cookies

set_cookie(context: Any | None, cookie: Cookie, partition: dict[str, Any] | None = None) -> None

Sets a cookie.

Parameters:

Name Type Description Default
context Any | None

Context to scope to (ignored when partition is given).

 required
cookie Cookie

Cookie model to store.

 required
partition dict[str, Any] | None

PartitionDescriptor dict.

 None
Source code in bidiwave/modules/storage.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
async def set_cookie(
    self,
    context: Any | None,
    cookie: Cookie,
    partition: dict[str, Any] | None = None,
) -> None:
    """Sets a cookie.

    Args:
        context: Context to scope to (ignored when `partition` is given).
        cookie: Cookie model to store.
        partition: PartitionDescriptor dict.
    """
    cookie_dict = cookie.model_dump(by_alias=True, exclude_none=True)
    # Spec: cookie value is a network.BytesValue, not a raw string.
    cookie_dict["value"] = {"type": "string", "value": cookie.value}
    params: dict[str, Any] = {"cookie": cookie_dict}
    if partition is not None:
        params["partition"] = partition
    elif context is not None:
        ctx_id = context.id if hasattr(context, "id") else str(context)
        params["partition"] = {"type": "context", "context": ctx_id}
    await self._connection.send_command(STORAGE_SET_COOKIE, params)

delete_cookies async 

delete_cookies(context: Any | None = None, name: str | None = None, domain: str | None = None, path: str | None = None, partition: dict[str, Any] | None = None) -> None

Deletes cookies matching the filter.

Parameters:

Name Type Description Default
context Any | None

Context to scope to (ignored when partition is given).

 None
name str | None

Delete only cookies with this name.

 None
domain str | None

Delete only cookies for this domain.

 None
path str | None

Delete only cookies with this path.

 None
partition dict[str, Any] | None

PartitionDescriptor dict.

 None
Source code in bidiwave/modules/storage.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
async def delete_cookies(
    self,
    context: Any | None = None,
    name: str | None = None,
    domain: str | None = None,
    path: str | None = None,
    partition: dict[str, Any] | None = None,
) -> None:
    """Deletes cookies matching the filter.

    Args:
        context: Context to scope to (ignored when `partition` is given).
        name: Delete only cookies with this name.
        domain: Delete only cookies for this domain.
        path: Delete only cookies with this path.
        partition: PartitionDescriptor dict.
    """
    params: dict[str, Any] = {}
    cookie_filter = {
        k: v
        for k, v in {"name": name, "domain": domain, "path": path}.items()
        if v is not None
    }
    if cookie_filter:
        params["filter"] = cookie_filter
    if partition is not None:
        params["partition"] = partition
    elif context is not None:
        ctx_id = context.id if hasattr(context, "id") else str(context)
        params["partition"] = {"type": "context", "context": ctx_id}
    await self._connection.send_command(STORAGE_DELETE_COOKIES, params)

delete_cookie(context: Any | None, name: str) -> None

Deletes a single cookie by name.

Source code in bidiwave/modules/storage.py 
112
113
114
async def delete_cookie(self, context: Any | None, name: str) -> None:
    """Deletes a single cookie by name."""
    await self.delete_cookies(context, name=name)

Cookie

Bases: BaseModel

Browser cookie (storage.getCookies / storage.setCookie).

Source code in bidiwave/protocol/results.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class Cookie(BaseModel):
    """Browser cookie (storage.getCookies / storage.setCookie)."""

    model_config = ConfigDict(extra="allow", populate_by_name=True)

    name: str
    value: str
    domain: str | None = None
    path: str = "/"
    size: int | None = None
    http_only: bool = Field(default=False, alias="httpOnly")
    secure: bool = False
    same_site: str | None = Field(default=None, alias="sameSite")
    expires: int | None = Field(default=None, alias="expiry")
    priority: str | None = None
    same_party: bool | None = Field(default=None, alias="sameParty")
    source_scheme: str | None = Field(default=None, alias="sourceScheme")
    source_port: int | None = Field(default=None, alias="sourcePort")

    @field_validator("value", mode="before")
    @classmethod
    def normalize_value(cls, v: Any) -> str:
        if isinstance(v, dict):
            return str(v.get("value", ""))
        return str(v)

    @field_validator("same_site", mode="before")
    @classmethod
    def normalize_same_site(cls, v: Any) -> Any:
        if isinstance(v, str):
            return v.lower()
        return v

Get cookies

cookies = await client.storage.get_cookies(context)
for cookie in cookies:
    print(f"{cookie.name}={cookie.value} (domain={cookie.domain})")

from bidiwave import Cookie

await client.storage.set_cookie(
    context,
    cookie=Cookie(
        name="session",
        value="abc123",
        domain="example.com",
        path="/",
        http_only=True,
        secure=True,
        same_site="strict",
        expires=1735689600,
    ),
)

Delete cookies

# Delete all cookies
await client.storage.delete_cookies(context)

# Delete a specific cookie by name
await client.storage.delete_cookies(context, name="session")

# Delete cookies by domain
await client.storage.delete_cookies(context, domain="example.com")

# Delete cookies by name, domain, and path
await client.storage.delete_cookies(
    context,
    name="session",
    domain="example.com",
    path="/app",
)

# Delete one cookie by name (targeted, no filter)
await client.storage.delete_cookie(context, "session")