Skip to content

Storage

StorageModule

Module for managing browser cookies.

Commands
  • get_cookies — gets cookies from a context
  • set_cookie — creates or updates a cookie
  • delete_cookies — deletes cookies by filter
  • delete_cookie — deletes a single cookie by name
Example

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

await client.storage.set_cookie( context, cookie=Cookie(name="session", value="abc123", domain="example.com"), )

Source code in bidiwave/modules/storage.py 
 19
 20
 21
 22
 23
 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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class StorageModule:
    """Module for managing browser cookies.

    Commands:
        - get_cookies — gets cookies from a context
        - set_cookie — creates or updates a cookie
        - delete_cookies — deletes cookies by filter
        - delete_cookie — deletes a single cookie by name

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

        await client.storage.set_cookie(
            context,
            cookie=Cookie(name="session", value="abc123", domain="example.com"),
        )
    """

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

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

        Args:
            context: BrowsingContext or context ID.
            filter: Optional filter dict (e.g. {"name": "session"}).
            partition_key: Optional partition key with userContext/sourceOrigin.

        Returns:
            List of Cookie.
        """
        ctx_id = context.id if hasattr(context, "id") else context
        params: dict[str, Any] = {"context": ctx_id}
        if filter is not None:
            params["filter"] = filter
        if partition_key is not None:
            params["partitionKey"] = partition_key
        result = await self._connection.send_command(
            STORAGE_GET_COOKIES, params
        )
        parsed = GetCookiesResult.model_validate(result)
        return parsed.cookies

    async def set_cookie(
        self,
        context: BrowsingContext | str,
        cookie: Cookie,
        partition_key: dict[str, Any] | None = None,
    ) -> None:
        """Creates or updates a cookie in a browsing context.

        Args:
            context: BrowsingContext or context ID.
            cookie: Cookie to set.
            partition_key: Optional partition key with userContext/sourceOrigin.
        """
        ctx_id = context.id if hasattr(context, "id") else context
        cookie_dict = cookie.model_dump(by_alias=True, exclude_none=True)
        cookie_dict["value"] = {"type": "string", "value": cookie_dict["value"]}
        params: dict[str, Any] = {
            "context": ctx_id,
            "cookie": cookie_dict,
        }
        if partition_key is not None:
            params["partitionKey"] = partition_key
        await self._connection.send_command(STORAGE_SET_COOKIE, params)

    async def delete_cookies(
        self,
        context: BrowsingContext | str,
        name: str | None = None,
        domain: str | None = None,
        path: str | None = None,
        partition_key: dict[str, Any] | None = None,
    ) -> None:
        """Deletes cookies from a browsing context.

        If name, domain or path are not specified, deletes all cookies.

        Args:
            context: BrowsingContext or context ID.
            name: Name of the cookie to delete. None = all.
            domain: Domain of cookies to delete.
            path: Path of cookies to delete.
            partition_key: Optional partition key with userContext/sourceOrigin.
        """
        ctx_id = context.id if hasattr(context, "id") else context
        params: dict[str, Any] = {"context": ctx_id}
        if name is not None:
            params["name"] = name
        if domain is not None:
            params["domain"] = domain
        if path is not None:
            params["path"] = path
        if partition_key is not None:
            params["partitionKey"] = partition_key
        await self._connection.send_command(STORAGE_DELETE_COOKIES, params)

    async def delete_cookie(
        self,
        context: BrowsingContext | str,
        name: str,
    ) -> None:
        """Deletes a single cookie by name from a browsing context.

        Convenience wrapper around delete_cookies with a name filter.

        Args:
            context: BrowsingContext or context ID.
            name: Name of the cookie to delete.
        """
        ctx_id = context.id if hasattr(context, "id") else context
        await self._connection.send_command(
            STORAGE_DELETE_COOKIES,
            {"context": ctx_id, "name": name},
        )

get_cookies async 

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

Gets cookies from a browsing context, optionally filtered.

Parameters:

Name Type Description Default
context BrowsingContext | str

BrowsingContext or context ID.

 required
filter dict[str, Any] | None

Optional filter dict (e.g. {"name": "session"}).

 None
partition_key dict[str, Any] | None

Optional partition key with userContext/sourceOrigin.

 None

Returns:

Type Description
list[Cookie]

List of Cookie.
Source code in bidiwave/modules/storage.py 
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
async def get_cookies(
    self,
    context: BrowsingContext | str,
    filter: dict[str, Any] | None = None,
    partition_key: dict[str, Any] | None = None,
) -> list[Cookie]:
    """Gets cookies from a browsing context, optionally filtered.

    Args:
        context: BrowsingContext or context ID.
        filter: Optional filter dict (e.g. {"name": "session"}).
        partition_key: Optional partition key with userContext/sourceOrigin.

    Returns:
        List of Cookie.
    """
    ctx_id = context.id if hasattr(context, "id") else context
    params: dict[str, Any] = {"context": ctx_id}
    if filter is not None:
        params["filter"] = filter
    if partition_key is not None:
        params["partitionKey"] = partition_key
    result = await self._connection.send_command(
        STORAGE_GET_COOKIES, params
    )
    parsed = GetCookiesResult.model_validate(result)
    return parsed.cookies

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

Creates or updates a cookie in a browsing context.

Parameters:

Name Type Description Default
context BrowsingContext | str

BrowsingContext or context ID.

 required
cookie Cookie

Cookie to set.

 required
partition_key dict[str, Any] | None

Optional partition key with userContext/sourceOrigin.

 None
Source code in bidiwave/modules/storage.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
async def set_cookie(
    self,
    context: BrowsingContext | str,
    cookie: Cookie,
    partition_key: dict[str, Any] | None = None,
) -> None:
    """Creates or updates a cookie in a browsing context.

    Args:
        context: BrowsingContext or context ID.
        cookie: Cookie to set.
        partition_key: Optional partition key with userContext/sourceOrigin.
    """
    ctx_id = context.id if hasattr(context, "id") else context
    cookie_dict = cookie.model_dump(by_alias=True, exclude_none=True)
    cookie_dict["value"] = {"type": "string", "value": cookie_dict["value"]}
    params: dict[str, Any] = {
        "context": ctx_id,
        "cookie": cookie_dict,
    }
    if partition_key is not None:
        params["partitionKey"] = partition_key
    await self._connection.send_command(STORAGE_SET_COOKIE, params)

delete_cookies async 

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

Deletes cookies from a browsing context.

If name, domain or path are not specified, deletes all cookies.

Parameters:

Name Type Description Default
context BrowsingContext | str

BrowsingContext or context ID.

 required
name str | None

Name of the cookie to delete. None = all.

 None
domain str | None

Domain of cookies to delete.

 None
path str | None

Path of cookies to delete.

 None
partition_key dict[str, Any] | None

Optional partition key with userContext/sourceOrigin.

 None
Source code in bidiwave/modules/storage.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
async def delete_cookies(
    self,
    context: BrowsingContext | str,
    name: str | None = None,
    domain: str | None = None,
    path: str | None = None,
    partition_key: dict[str, Any] | None = None,
) -> None:
    """Deletes cookies from a browsing context.

    If name, domain or path are not specified, deletes all cookies.

    Args:
        context: BrowsingContext or context ID.
        name: Name of the cookie to delete. None = all.
        domain: Domain of cookies to delete.
        path: Path of cookies to delete.
        partition_key: Optional partition key with userContext/sourceOrigin.
    """
    ctx_id = context.id if hasattr(context, "id") else context
    params: dict[str, Any] = {"context": ctx_id}
    if name is not None:
        params["name"] = name
    if domain is not None:
        params["domain"] = domain
    if path is not None:
        params["path"] = path
    if partition_key is not None:
        params["partitionKey"] = partition_key
    await self._connection.send_command(STORAGE_DELETE_COOKIES, params)

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

Deletes a single cookie by name from a browsing context.

Convenience wrapper around delete_cookies with a name filter.

Parameters:

Name Type Description Default
context BrowsingContext | str

BrowsingContext or context ID.

 required
name str

Name of the cookie to delete.

 required
Source code in bidiwave/modules/storage.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
async def delete_cookie(
    self,
    context: BrowsingContext | str,
    name: str,
) -> None:
    """Deletes a single cookie by name from a browsing context.

    Convenience wrapper around delete_cookies with a name filter.

    Args:
        context: BrowsingContext or context ID.
        name: Name of the cookie to delete.
    """
    ctx_id = context.id if hasattr(context, "id") else context
    await self._connection.send_command(
        STORAGE_DELETE_COOKIES,
        {"context": ctx_id, "name": name},
    )

Cookie

Bases: BaseModel

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

Source code in bidiwave/protocol/results.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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")