tabsail 0.1.0__tar.gz

tabsail-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

tabsail-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: tabsail
+Version: 0.1.0
+Summary: Official async Python SDK for TabSail
+Project-URL: Documentation, https://tabsail.com/docs/sdks/
+Project-URL: Homepage, https://tabsail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: certifi>=2026.10.19
+Requires-Dist: httpx<0.29,>=0.28.1
+Description-Content-Type: text/markdown
+
+# TabSail Python SDK
+
+Hosted endpoint: `https://tabsail.com`. Set `TABSAIL_BASE_URL=https://tabsail.com` and `TABSAIL_API_KEY` to your project key. For local or separate deployments, use that instance's root URL.
+
+An asynchronous, typed Python >=3.12 client for TabSail v1 session, file, handoff and Profile resources. Distribution `tabsail`, import `tabsail`, version `0.1.0`. It requires httpx, and does not install Playwright, a model provider, Chromium or Docker.
+
+Fund the Tenant through the console before creating a browser. At the base rate of 100 credits/hour, each billable session rounds up to whole credits (minimum 1 credit, or one per started 36 seconds). The maximum-duration budget is also rounded up before reservation; unused credits are released and platform failures are free. Raw duration remains measured in milliseconds; $1 purchases 1,000 credits. `402 INSUFFICIENT_CREDITS` and `403 BILLING_FROZEN` never enter capacity waiting. Projects and Keys share their Tenant's credits and concurrency.
+
+Install from PyPI:
+
+```sh
+uv add "tabsail==0.1.0"
+```
+
+```python
+from tabsail import AsyncTabSail, RequestOptions
+
+async with AsyncTabSail(base_url="https://tabsail.com", api_key="PROJECT_KEY") as client:
+    async with client.with_session(
+        timeout_seconds=900,
+        options=RequestOptions(idempotency_key="your-task-id"),
+    ) as session:
+        grant = await client.sessions.connections.create(session.id, type="cdp")
+        # Pass grant.url to your native async Playwright connect_over_cdp().
+        # Reuse the browser's existing context/page; actions belong to Playwright.
+```
+
+The base URL is the instance root; trailing slashes are removed and `/v1` is appended. Explicit configuration overrides `TABSAIL_BASE_URL` and `TABSAIL_API_KEY`. No `.env` or consumer filesystem secrets are searched. Redirects are not followed, so the Project Key is not forwarded to another origin. Treat grant URLs as credentials; their model repr hides the URL.
+
+`client.aclose()` closes local HTTP connections. CDP disconnect does not release the remote browser. `with_session()` creates and owns one BrowserSession, waits for ready and yields that resource; it does not create a Playwright Browser. On exit it closes its session and waits for non-null `released_at`. Explicitly created sessions are caller-owned and are never closed by the client's HTTP context. Failed status alone does not prove resource/quota release.
+
+All SDK timeouts are named with `_ms`: `request_timeout_ms` bounds one HTTP attempt; `RequestOptions(timeout_ms=...)` bounds one logical HTTP operation including retry/backoff; lifecycle `timeout_ms` bounds the entire polling operation including requests and sleeps. `timeout_seconds` is the server's browser lifetime, independent of HTTP/wait deadlines. Omitted server creation fields remain omitted. Default request timeout is 15,000 ms, lifecycle polling 500 ms, ready/released wait 60,000 ms, handoff wait 300,000 ms. Capacity errors return immediately with default `max_retries=0`. Explicit retries are limited to 10; only GET, keyed create/handoff create and state-idempotent close/complete can replay. Exponential backoff starts with a 250 ms window capped at 5 seconds, randomly waiting between half and all of that window after the full Retry-After minimum. A deadline can end the call before another retry; the server minimum is never shortened. Grants and uploads never replay automatically.
+
+`with_session(wait_for_capacity=True)` waits for `503 NO_CAPACITY/STARTUP_BUSY` and `429 CREATE_RATE_LIMITED` using one idempotency key and unchanged creation parameters. Its backoff window grows from 250 ms to 10 seconds, randomized after Retry-After. The default total create + ready deadline is 300,000 ms; override it with `RequestOptions(timeout_ms=...)`. Startup retains its separate ready limit and task cancellation interrupts waiting. Tenant concurrency limits, insufficient credits and billing freezes are not capacity waits. This helper does not promise a queue position or eventual allocation, and never replays your business code.
+
+```python
+from tabsail import HandoffCheckpoint
+
+stable = await client.sessions.get(session.id)  # ready + automation, one snapshot
+checkpoint = HandoffCheckpoint.from_session(stable)
+resumed = await client.sessions.wait_for_handoff(session.id, after=checkpoint)
+# resumed.latest_handoff.status == "completed", resumed.controller == "automation"
+checkpoint = HandoffCheckpoint.from_session(resumed)
+# Request a new CDP grant, reconnect the SAME session and retrieve fresh context/page.
+# Observe human modifications before choosing the next action.
+```
+
+`wait_for_handoff` compares arbitrary-size decimal epochs as integers and requires a new latest Handoff ID. It detects a completed handoff between observations, never consumes the old completion again, and waits through consecutive handoffs until the current latest handoff is completed with automation control in the same snapshot. The checkpoint must originate from stable ready + automation; do not capture it during human control. This helper returns a BrowserSession; known IDs can use `handoffs.wait_until_completed(id, handoff_id)`, which returns a Handoff. Completion payload `returning` is pending even if an older server returns HTTP 200. Session termination, cancellation and cancelled handoffs are explicit errors. The SDK does not reconnect Playwright or replay webpage actions/callbacks. Natural CDP disconnect without an epoch change is not an observed handoff.
+
+Lifecycle helpers use an authenticated SSE snapshot subscription after the initial GET. Reconnects read the latest complete state. Older servers without this endpoint retain polling compatibility; `poll_interval_ms` controls fallback and reconnect backoff. No action or callback is replayed.
+
+```python
+from contextlib import aclosing
+
+async with aclosing(client.sessions.watch(session.id, timeout_ms=300000)) as updates:
+    async for snapshot in updates:
+        print(snapshot.status, snapshot.controller)
+        if snapshot.released_at:
+            break
+```
+
+`aclosing` releases the local subscription on early exit. It does not close the remote browser. Native asyncio cancellation and total wait deadlines remain supported.
+
+Resources: `sessions.create/get/list/close`, `sessions.connections.create(type="cdp" or "live", mode="view" or "control", handoff_id=...)`, `sessions.handoffs.create/get/complete`, `sessions.files.upload/list/get/download/delete`. Request fields use Python snake_case and serialize to the existing camelCase HTTP contract. List methods return `Page(items, next_cursor)`; pass its cursor explicitly for the next page. Models reject unknown state values with ProtocolError and tolerate extra response fields.
+
+```python
+from pathlib import Path
+
+file = await client.sessions.files.upload(session.id, Path("报告.bin"))
+async with client.sessions.files.download(session.id, file.id) as download:
+    with Path("retrieved.bin").open("wb") as output:
+        async for chunk in download.aiter_bytes():
+            output.write(chunk)
+await client.sessions.files.delete(session.id, file.id)  # 204 has no JSON body
+```
+
+Uploads accept bytes, Path or a binary file object and use multipart; callers close their own file objects. A Path is opened and closed by the SDK. Downloads are streamed and must be used with `async with`; cancellation or early context exit closes the local response. The entire HTTP attempt, including headers and stream reads, shares `request_timeout_ms`; an optional `timeout_ms` additionally limits the logical operation including retries. Each read checks the remaining absolute deadline. Processing a yielded chunk does not arm a timer that cancels your task; if processing uses the remaining budget, the next read raises RequestTimeoutError and closes the stream. `browser_path` is remote, and files must be retrieved before closing the session. No durable file hosting or resume is promised.
+
+Errors distinguish configuration, network, HTTP request timeout, wait deadline, asyncio cancellation, API errors, protocol errors and unknown mutation outcomes. SDK error fields include `status`, `code`, `retryable`, `request_id`, `retry_after`, `session_id`. Unknown API codes remain APIError. Gateway HTML/empty 502 responses retain bounded sanitized HTTP context. Raw credentials/grant URLs do not appear in SDK exception messages.
+
+Session/handoff creation generates one Idempotency-Key per logical call; supply `RequestOptions(idempotency_key=...)` for cross-process recovery. Replay can return an old starting snapshot; always GET/wait for current state. Mutation 5xx errors can follow a commit and are ResultUnknownError with their original APIError/status/request ID; explicit `NO_CAPACITY` and `STARTUP_BUSY` rejection remain APIError. A failed/lost upload response is ResultUnknownError: inspect files instead of blindly uploading again.
+
+Owned creation cancelled before sending is not transmitted. Once creation outcome is unknown, cleanup uses the same key within an independent `cleanup_timeout_ms` budget (30,000 ms by default), obtains the unique ID, closes and confirms release. If the original request never arrived, this recovery may briefly create then close a new session. Cancellation never cancels this shielded cleanup, and business code is not retried. A primary exception remains primary; cleanup failure is attached as `.cleanup_error`, with `.session_id` and `.idempotency_key` for manual recovery. Without a primary failure, CleanupError is raised. Never reuse the recovery key with a changed creation body.
+
+Development: `uv sync --group dev`, `uv run pytest`, `uv run mypy`, `uv run ruff check src tests`, `uv build`. `uv run python tests/pack_consumer.py` builds wheel/sdist, installs each in a clean external environment (rebuilding the sdist wheel), checks typed imports and runs a real loopback HTTP consumer. These local tests do not claim PG/Steel/CDP qualification; that evidence belongs to the repository's separate isolated SDK acceptance suite.
+
+For elastic capacity, use `client.with_session(wait_for_capacity=True, options=RequestOptions(timeout_ms=300000))`. Enabling it defaults the total acquisition budget to five minutes, including capacity retries and readiness. Only confirmed `NO_CAPACITY` / `STARTUP_BUSY` refusals wait; tenant quota failures return immediately. The same idempotency key and request are retained. Browser lifetime and the context body have separate budgets.
+
+## Browser region
+
+Creation defaults to automatic selection from the API caller's public egress IP: Asia/Oceania use `asia`, other or unknown locations use `west`. Override when a backend's location differs from the desired browser location.
+
+```python
+async with client.with_session(region="asia", wait_for_capacity=True) as session:
+    print(session.region)  # actual "asia" or "west"
+```
+
+`await client.sessions.create(region="west")` also accepts the override. Region stays fixed across idempotent retries and the session lifetime. Capacity waiting does not switch regions; use a new request and idempotency key to change region. Use the returned CDP/Live connection URL.
+
+## Browser settings, lifetime, and Profiles
+
+With an initialized client:
+
+```python
+profile = await client.profiles.create("Report login")
+async with client.with_session(
+    browser={"locale": "en-US", "timezone": "Asia/Tokyo", "headless": True},
+    idle_timeout_seconds=120,
+    profile={"id": profile.id, "persistOnClose": True},
+) as session:
+    await client.sessions.update(session.id, timeout_seconds=1200)
+    await client.sessions.touch(session.id)
+    # Connect and perform your task. The scope closes and releases the browser.
+```
+
+Nested `browser` and `profile` dictionaries use the HTTP field names shown above. `timeout_seconds` in an update is the new total lifetime from `started_at`, not extra seconds. It cannot decrease; extra budget is reserved atomically. Omit `idle_timeout_seconds` to leave it unchanged; pass `None` to disable idle expiry. GET, SSE and read-only Live do not renew idle activity.
+
+Profiles support `create`, `list`, `get`, and `delete`. One unreleased session may use a Profile. Normal close/expiry saves cookies and localStorage when `persistOnClose` is true; inspect the ended session's `profile["saveStatus"]`. A failed save preserves the previous version. Profiles exclude downloads, page memory, and Agent history.

tabsail-0.1.0/README.md

@@ -0,0 +1,118 @@
+# TabSail Python SDK
+
+Hosted endpoint: `https://tabsail.com`. Set `TABSAIL_BASE_URL=https://tabsail.com` and `TABSAIL_API_KEY` to your project key. For local or separate deployments, use that instance's root URL.
+
+An asynchronous, typed Python >=3.12 client for TabSail v1 session, file, handoff and Profile resources. Distribution `tabsail`, import `tabsail`, version `0.1.0`. It requires httpx, and does not install Playwright, a model provider, Chromium or Docker.
+
+Fund the Tenant through the console before creating a browser. At the base rate of 100 credits/hour, each billable session rounds up to whole credits (minimum 1 credit, or one per started 36 seconds). The maximum-duration budget is also rounded up before reservation; unused credits are released and platform failures are free. Raw duration remains measured in milliseconds; $1 purchases 1,000 credits. `402 INSUFFICIENT_CREDITS` and `403 BILLING_FROZEN` never enter capacity waiting. Projects and Keys share their Tenant's credits and concurrency.
+
+Install from PyPI:
+
+```sh
+uv add "tabsail==0.1.0"
+```
+
+```python
+from tabsail import AsyncTabSail, RequestOptions
+
+async with AsyncTabSail(base_url="https://tabsail.com", api_key="PROJECT_KEY") as client:
+    async with client.with_session(
+        timeout_seconds=900,
+        options=RequestOptions(idempotency_key="your-task-id"),
+    ) as session:
+        grant = await client.sessions.connections.create(session.id, type="cdp")
+        # Pass grant.url to your native async Playwright connect_over_cdp().
+        # Reuse the browser's existing context/page; actions belong to Playwright.
+```
+
+The base URL is the instance root; trailing slashes are removed and `/v1` is appended. Explicit configuration overrides `TABSAIL_BASE_URL` and `TABSAIL_API_KEY`. No `.env` or consumer filesystem secrets are searched. Redirects are not followed, so the Project Key is not forwarded to another origin. Treat grant URLs as credentials; their model repr hides the URL.
+
+`client.aclose()` closes local HTTP connections. CDP disconnect does not release the remote browser. `with_session()` creates and owns one BrowserSession, waits for ready and yields that resource; it does not create a Playwright Browser. On exit it closes its session and waits for non-null `released_at`. Explicitly created sessions are caller-owned and are never closed by the client's HTTP context. Failed status alone does not prove resource/quota release.
+
+All SDK timeouts are named with `_ms`: `request_timeout_ms` bounds one HTTP attempt; `RequestOptions(timeout_ms=...)` bounds one logical HTTP operation including retry/backoff; lifecycle `timeout_ms` bounds the entire polling operation including requests and sleeps. `timeout_seconds` is the server's browser lifetime, independent of HTTP/wait deadlines. Omitted server creation fields remain omitted. Default request timeout is 15,000 ms, lifecycle polling 500 ms, ready/released wait 60,000 ms, handoff wait 300,000 ms. Capacity errors return immediately with default `max_retries=0`. Explicit retries are limited to 10; only GET, keyed create/handoff create and state-idempotent close/complete can replay. Exponential backoff starts with a 250 ms window capped at 5 seconds, randomly waiting between half and all of that window after the full Retry-After minimum. A deadline can end the call before another retry; the server minimum is never shortened. Grants and uploads never replay automatically.
+
+`with_session(wait_for_capacity=True)` waits for `503 NO_CAPACITY/STARTUP_BUSY` and `429 CREATE_RATE_LIMITED` using one idempotency key and unchanged creation parameters. Its backoff window grows from 250 ms to 10 seconds, randomized after Retry-After. The default total create + ready deadline is 300,000 ms; override it with `RequestOptions(timeout_ms=...)`. Startup retains its separate ready limit and task cancellation interrupts waiting. Tenant concurrency limits, insufficient credits and billing freezes are not capacity waits. This helper does not promise a queue position or eventual allocation, and never replays your business code.
+
+```python
+from tabsail import HandoffCheckpoint
+
+stable = await client.sessions.get(session.id)  # ready + automation, one snapshot
+checkpoint = HandoffCheckpoint.from_session(stable)
+resumed = await client.sessions.wait_for_handoff(session.id, after=checkpoint)
+# resumed.latest_handoff.status == "completed", resumed.controller == "automation"
+checkpoint = HandoffCheckpoint.from_session(resumed)
+# Request a new CDP grant, reconnect the SAME session and retrieve fresh context/page.
+# Observe human modifications before choosing the next action.
+```
+
+`wait_for_handoff` compares arbitrary-size decimal epochs as integers and requires a new latest Handoff ID. It detects a completed handoff between observations, never consumes the old completion again, and waits through consecutive handoffs until the current latest handoff is completed with automation control in the same snapshot. The checkpoint must originate from stable ready + automation; do not capture it during human control. This helper returns a BrowserSession; known IDs can use `handoffs.wait_until_completed(id, handoff_id)`, which returns a Handoff. Completion payload `returning` is pending even if an older server returns HTTP 200. Session termination, cancellation and cancelled handoffs are explicit errors. The SDK does not reconnect Playwright or replay webpage actions/callbacks. Natural CDP disconnect without an epoch change is not an observed handoff.
+
+Lifecycle helpers use an authenticated SSE snapshot subscription after the initial GET. Reconnects read the latest complete state. Older servers without this endpoint retain polling compatibility; `poll_interval_ms` controls fallback and reconnect backoff. No action or callback is replayed.
+
+```python
+from contextlib import aclosing
+
+async with aclosing(client.sessions.watch(session.id, timeout_ms=300000)) as updates:
+    async for snapshot in updates:
+        print(snapshot.status, snapshot.controller)
+        if snapshot.released_at:
+            break
+```
+
+`aclosing` releases the local subscription on early exit. It does not close the remote browser. Native asyncio cancellation and total wait deadlines remain supported.
+
+Resources: `sessions.create/get/list/close`, `sessions.connections.create(type="cdp" or "live", mode="view" or "control", handoff_id=...)`, `sessions.handoffs.create/get/complete`, `sessions.files.upload/list/get/download/delete`. Request fields use Python snake_case and serialize to the existing camelCase HTTP contract. List methods return `Page(items, next_cursor)`; pass its cursor explicitly for the next page. Models reject unknown state values with ProtocolError and tolerate extra response fields.
+
+```python
+from pathlib import Path
+
+file = await client.sessions.files.upload(session.id, Path("报告.bin"))
+async with client.sessions.files.download(session.id, file.id) as download:
+    with Path("retrieved.bin").open("wb") as output:
+        async for chunk in download.aiter_bytes():
+            output.write(chunk)
+await client.sessions.files.delete(session.id, file.id)  # 204 has no JSON body
+```
+
+Uploads accept bytes, Path or a binary file object and use multipart; callers close their own file objects. A Path is opened and closed by the SDK. Downloads are streamed and must be used with `async with`; cancellation or early context exit closes the local response. The entire HTTP attempt, including headers and stream reads, shares `request_timeout_ms`; an optional `timeout_ms` additionally limits the logical operation including retries. Each read checks the remaining absolute deadline. Processing a yielded chunk does not arm a timer that cancels your task; if processing uses the remaining budget, the next read raises RequestTimeoutError and closes the stream. `browser_path` is remote, and files must be retrieved before closing the session. No durable file hosting or resume is promised.
+
+Errors distinguish configuration, network, HTTP request timeout, wait deadline, asyncio cancellation, API errors, protocol errors and unknown mutation outcomes. SDK error fields include `status`, `code`, `retryable`, `request_id`, `retry_after`, `session_id`. Unknown API codes remain APIError. Gateway HTML/empty 502 responses retain bounded sanitized HTTP context. Raw credentials/grant URLs do not appear in SDK exception messages.
+
+Session/handoff creation generates one Idempotency-Key per logical call; supply `RequestOptions(idempotency_key=...)` for cross-process recovery. Replay can return an old starting snapshot; always GET/wait for current state. Mutation 5xx errors can follow a commit and are ResultUnknownError with their original APIError/status/request ID; explicit `NO_CAPACITY` and `STARTUP_BUSY` rejection remain APIError. A failed/lost upload response is ResultUnknownError: inspect files instead of blindly uploading again.
+
+Owned creation cancelled before sending is not transmitted. Once creation outcome is unknown, cleanup uses the same key within an independent `cleanup_timeout_ms` budget (30,000 ms by default), obtains the unique ID, closes and confirms release. If the original request never arrived, this recovery may briefly create then close a new session. Cancellation never cancels this shielded cleanup, and business code is not retried. A primary exception remains primary; cleanup failure is attached as `.cleanup_error`, with `.session_id` and `.idempotency_key` for manual recovery. Without a primary failure, CleanupError is raised. Never reuse the recovery key with a changed creation body.
+
+Development: `uv sync --group dev`, `uv run pytest`, `uv run mypy`, `uv run ruff check src tests`, `uv build`. `uv run python tests/pack_consumer.py` builds wheel/sdist, installs each in a clean external environment (rebuilding the sdist wheel), checks typed imports and runs a real loopback HTTP consumer. These local tests do not claim PG/Steel/CDP qualification; that evidence belongs to the repository's separate isolated SDK acceptance suite.
+
+For elastic capacity, use `client.with_session(wait_for_capacity=True, options=RequestOptions(timeout_ms=300000))`. Enabling it defaults the total acquisition budget to five minutes, including capacity retries and readiness. Only confirmed `NO_CAPACITY` / `STARTUP_BUSY` refusals wait; tenant quota failures return immediately. The same idempotency key and request are retained. Browser lifetime and the context body have separate budgets.
+
+## Browser region
+
+Creation defaults to automatic selection from the API caller's public egress IP: Asia/Oceania use `asia`, other or unknown locations use `west`. Override when a backend's location differs from the desired browser location.
+
+```python
+async with client.with_session(region="asia", wait_for_capacity=True) as session:
+    print(session.region)  # actual "asia" or "west"
+```
+
+`await client.sessions.create(region="west")` also accepts the override. Region stays fixed across idempotent retries and the session lifetime. Capacity waiting does not switch regions; use a new request and idempotency key to change region. Use the returned CDP/Live connection URL.
+
+## Browser settings, lifetime, and Profiles
+
+With an initialized client:
+
+```python
+profile = await client.profiles.create("Report login")
+async with client.with_session(
+    browser={"locale": "en-US", "timezone": "Asia/Tokyo", "headless": True},
+    idle_timeout_seconds=120,
+    profile={"id": profile.id, "persistOnClose": True},
+) as session:
+    await client.sessions.update(session.id, timeout_seconds=1200)
+    await client.sessions.touch(session.id)
+    # Connect and perform your task. The scope closes and releases the browser.
+```
+
+Nested `browser` and `profile` dictionaries use the HTTP field names shown above. `timeout_seconds` in an update is the new total lifetime from `started_at`, not extra seconds. It cannot decrease; extra budget is reserved atomically. Omit `idle_timeout_seconds` to leave it unchanged; pass `None` to disable idle expiry. GET, SSE and read-only Live do not renew idle activity.
+
+Profiles support `create`, `list`, `get`, and `delete`. One unreleased session may use a Profile. Normal close/expiry saves cookies and localStorage when `persistOnClose` is true; inspect the ended session's `profile["saveStatus"]`. A failed save preserves the previous version. Profiles exclude downloads, page memory, and Agent history.

tabsail-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tabsail"
+version = "0.1.0"
+description = "Official async Python SDK for TabSail"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.28.1,<0.29", "certifi>=2026.10.19"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed"]
+
+[project.urls]
+Documentation = "https://tabsail.com/docs/sdks/"
+Homepage = "https://tabsail.com"
+
+[dependency-groups]
+dev = ["pytest>=8.4,<9", "pytest-asyncio>=1.2,<2", "mypy>=1.18,<2", "ruff>=0.14,<0.15"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tabsail"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/tabsail"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100

tabsail-0.1.0/src/tabsail/__init__.py

@@ -0,0 +1,69 @@
+"""TabSail v1 asynchronous SDK; browser actions belong to your CDP client."""
+
+from .client import AsyncTabSail, OwnedSession
+from .errors import (
+    APIError,
+    CleanupError,
+    ConfigurationError,
+    HandoffCancelledError,
+    NetworkError,
+    ProtocolError,
+    RequestCancelledError,
+    RequestTimeoutError,
+    ResultUnknownError,
+    SDKError,
+    SessionTerminatedError,
+    WaitTimeoutError,
+)
+from .models import (
+    BrowserSession,
+    Profile,
+    ConnectionGrant,
+    Controller,
+    FileOrigin,
+    FileStatus,
+    Handoff,
+    HandoffCheckpoint,
+    HandoffStatus,
+    HandoffSummary,
+    Page,
+    ResourceError,
+    SessionFile,
+    SessionStatus,
+)
+from .resources import DownloadStream
+from .transport import RequestOptions
+
+__version__ = "0.1.0"
+__all__ = [
+    "AsyncTabSail",
+    "OwnedSession",
+    "RequestOptions",
+    "BrowserSession",
+    "Profile",
+    "ConnectionGrant",
+    "Handoff",
+    "HandoffSummary",
+    "HandoffCheckpoint",
+    "SessionFile",
+    "Page",
+    "ResourceError",
+    "SessionStatus",
+    "Controller",
+    "HandoffStatus",
+    "FileStatus",
+    "FileOrigin",
+    "DownloadStream",
+    "SDKError",
+    "APIError",
+    "ConfigurationError",
+    "NetworkError",
+    "RequestTimeoutError",
+    "WaitTimeoutError",
+    "ProtocolError",
+    "RequestCancelledError",
+    "ResultUnknownError",
+    "SessionTerminatedError",
+    "HandoffCancelledError",
+    "CleanupError",
+]

tabsail-0.1.0/src/tabsail/client.py

@@ -0,0 +1,286 @@
+"""Async HTTP client and ownership scoped session context."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from copy import deepcopy
+import math
+import os
+import time
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from .errors import (
+    APIError,
+    CleanupError,
+    ConfigurationError,
+    ProtocolError,
+    ResultUnknownError,
+    WaitTimeoutError,
+)
+from .models import BrowserSession
+from .resources import Profiles, Sessions, keyed
+from .transport import RequestOptions, Transport
+
+
+class AsyncTabSail:
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        request_timeout_ms: float = 15000,
+        max_retries: int = 0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        base_url = base_url if base_url is not None else os.environ.get("TABSAIL_BASE_URL")
+        api_key = api_key if api_key is not None else os.environ.get("TABSAIL_API_KEY")
+        if not base_url or not api_key:
+            raise ConfigurationError(
+                "Set base_url and api_key or TABSAIL_BASE_URL and TABSAIL_API_KEY."
+            )
+        self._transport = Transport(base_url, api_key, request_timeout_ms, max_retries, transport)
+        self.sessions = Sessions(self._transport)
+        self.profiles = Profiles(self._transport)
+
+    def __repr__(self) -> str:
+        return "<AsyncTabSail credentials=[REDACTED]>"
+
+    async def __aenter__(self) -> AsyncTabSail:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close local HTTP connections; remote BrowserSessions are unchanged."""
+        await self._transport.aclose()
+
+    def with_session(
+        self,
+        *,
+        timeout_seconds: int | None = None,
+        viewport: dict[str, int] | None = None,
+        metadata: dict[str, str] | None = None,
+        region: Literal["auto", "west", "asia"] | None = None,
+        options: RequestOptions | None = None,
+        ready_timeout_ms: float = 60000,
+        cleanup_timeout_ms: float = 30000,
+        poll_interval_ms: float = 500,
+        wait_for_capacity: bool = False,
+        idle_timeout_seconds: int | None = None,
+        browser: dict[str, Any] | None = None,
+        profile: dict[str, Any] | None = None,
+    ) -> OwnedSession:
+        return OwnedSession(
+            self,
+            timeout_seconds,
+            viewport,
+            metadata,
+            region,
+            options,
+            ready_timeout_ms,
+            cleanup_timeout_ms,
+            poll_interval_ms,
+            wait_for_capacity,
+            idle_timeout_seconds,
+            browser,
+            profile,
+        )
+
+
+class OwnedSession:
+    def __init__(
+        self,
+        client: AsyncTabSail,
+        timeout_seconds: int | None,
+        viewport: dict[str, int] | None,
+        metadata: dict[str, str] | None,
+        region: Literal["auto", "west", "asia"] | None,
+        options: RequestOptions | None,
+        ready_timeout_ms: float,
+        cleanup_timeout_ms: float,
+        poll_interval_ms: float,
+        wait_for_capacity: bool,
+        idle_timeout_seconds: int | None = None,
+        browser: dict[str, Any] | None = None,
+        profile: dict[str, Any] | None = None,
+    ) -> None:
+        if any(
+            not math.isfinite(v) or v <= 0
+            for v in (ready_timeout_ms, cleanup_timeout_ms, poll_interval_ms)
+        ):
+            raise ConfigurationError(
+                "Session wait and cleanup budgets must be finite positive milliseconds."
+            )
+        self._client = client
+        self._timeout_seconds = timeout_seconds
+        self._idle_timeout_seconds = idle_timeout_seconds
+        self._browser = deepcopy(browser)
+        self._profile = deepcopy(profile)
+        self._viewport = deepcopy(viewport)
+        self._metadata = deepcopy(metadata)
+        self._region = region
+        self._options = keyed(options)
+        if wait_for_capacity and self._options.timeout_ms is None:
+            self._options = replace(self._options, timeout_ms=300000)
+        self._wait_for_capacity = wait_for_capacity
+        self._ready_timeout_ms = ready_timeout_ms
+        self._cleanup_timeout_ms = cleanup_timeout_ms
+        self._poll_interval_ms = poll_interval_ms
+        self.session_id: str | None = None
+        self._unknown = False
+        self._entered = False
+
+    async def __aenter__(self) -> BrowserSession:
+        if self._entered:
+            raise ConfigurationError("An owned session context may only be entered once.")
+        self._entered = True
+        try:
+            # Cancellation here proves creation was not sent.
+            await asyncio.sleep(0)
+            started = time.monotonic()
+            capacity_attempt = 0
+            while True:
+                remaining_create = (
+                    None if self._options.timeout_ms is None
+                    else self._options.timeout_ms - (time.monotonic() - started) * 1000
+                )
+                if remaining_create is not None and remaining_create <= 0:
+                    raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT")
+                try:
+                    session = await self._client.sessions.create(
+                        timeout_seconds=self._timeout_seconds,
+                        idle_timeout_seconds=self._idle_timeout_seconds,
+                        browser=self._browser,
+                        profile=self._profile,
+                        viewport=self._viewport,
+                        metadata=self._metadata,
+                        region=self._region,
+                        options=replace(self._options, timeout_ms=remaining_create),
+                    )
+                    break
+                except APIError as error:
+                    if not (
+                        self._wait_for_capacity and error.retryable and (
+                            (error.status == 503 and error.code in ("NO_CAPACITY", "STARTUP_BUSY"))
+                            or (error.status == 429 and error.code == "CREATE_RATE_LIMITED")
+                        )
+                    ):
+                        raise
+                    assert self._options.timeout_ms is not None
+                    left = self._options.timeout_ms - (time.monotonic() - started) * 1000
+                    if left <= 0:
+                        raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT") from None
+                    delay = self._client._transport._delay(capacity_attempt, error.retry_after, 10.0)
+                    capacity_attempt += 1
+                    await asyncio.sleep(min(left / 1000, delay))
+                    if delay >= left / 1000:
+                        raise WaitTimeoutError("Browser capacity wait timed out.", code="CAPACITY_WAIT_TIMEOUT") from None
+            self.session_id = session.id
+            remaining = self._ready_timeout_ms
+            if self._options.timeout_ms is not None:
+                remaining = min(
+                    remaining, self._options.timeout_ms - (time.monotonic() - started) * 1000
+                )
+            if remaining <= 0:
+                raise WaitTimeoutError(
+                    "The owned session readiness deadline elapsed.", session_id=session.id
+                )
+            return await self._client.sessions.wait_until_ready(
+                session.id,
+                timeout_ms=remaining,
+                poll_interval_ms=self._poll_interval_ms,
+                options=self._options,
+            )
+        except BaseException as primary:
+            self._unknown = isinstance(primary, (ResultUnknownError, ProtocolError)) or getattr(
+                primary, "result_unknown", False
+            )
+            if self.session_id is not None or self._unknown:
+                await self._finish(primary)
+            raise
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        await self._finish(exc)
+        return False
+
+    async def _cleanup(self) -> None:
+        # This deadline covers recovery, close, all requests/retries and released confirmation.
+        async with asyncio.timeout(self._cleanup_timeout_ms / 1000):
+            options = replace(
+                self._options,
+                timeout_ms=None,
+                max_retries=2,
+                request_timeout_ms=min(self._cleanup_timeout_ms, 5000),
+            )
+            if self.session_id is None:
+                recovered = await self._client.sessions.create(
+                    timeout_seconds=self._timeout_seconds,
+                    idle_timeout_seconds=self._idle_timeout_seconds,
+                        browser=self._browser,
+                        profile=self._profile,
+                    viewport=self._viewport,
+                    metadata=self._metadata,
+                        region=self._region,
+                    options=options,
+                )
+                self.session_id = recovered.id
+            await self._client.sessions.close(self.session_id, options=options)
+            await self._client.sessions.wait_until_released(
+                self.session_id,
+                timeout_ms=self._cleanup_timeout_ms,
+                poll_interval_ms=self._poll_interval_ms,
+                options=options,
+            )
+
+    async def _finish(self, primary: BaseException | None) -> None:
+        task = asyncio.create_task(self._cleanup())
+        cancellation: asyncio.CancelledError | None = None
+        # Shield makes business cancellation independent of the bounded cleanup task.
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError as error:
+                if task.done():
+                    break
+                cancellation = cancellation or error
+                continue
+            except BaseException:
+                break
+        cleanup_error: BaseException | None
+        try:
+            task.result()
+            cleanup_error = None
+        except BaseException as error:
+            cleanup_error = CleanupError(
+                error,
+                session_id=self.session_id,
+                idempotency_key=self._options.idempotency_key or "",
+            )
+        original = primary or cancellation
+        if original is not None:
+            original.session_id = self.session_id  # type: ignore[attr-defined]
+            original.idempotency_key = self._options.idempotency_key  # type: ignore[attr-defined]
+            if cleanup_error is not None:
+                original.cleanup_error = cleanup_error  # type: ignore[attr-defined]
+                original.add_note(
+                    "Owned session cleanup failed; see cleanup_error and session_id/idempotency_key."
+                )
+            if primary is None:
+                raise original
+        elif cleanup_error is not None:
+            raise cleanup_error from None