bytekit-sdk 0.3.2__tar.gz → 0.3.4__tar.gz

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/.gitignore

@@ -47,6 +47,14 @@ packages/http-fetcher/server
 packages/http-fetcher/browserforge-bench
 __pycache__/
 *.pyc
+# ruff's incremental cache. Written by the openapi-python-client post-hooks INSIDE the
+# generated output dir (packages/sdk-python/src/bytekit/.ruff_cache/). ruff already drops a
+# self-ignoring `.gitignore` containing `*` in there, which is exactly why the directory went
+# unnoticed for so long — `git status` never mentions it. This entry is belt-and-braces so the
+# by-product is ignored even if ruff stops self-ignoring. The reproducibility gate
+# (ci/scripts/check-sdk-python-regen.sh) excludes it from BOTH of its diffs: cache entry names
+# are hashes of the absolute path, so two clean-room generates differ by construction.
+.ruff_cache/
 # Generated artifact — reproduced via `pnpm --filter @rapidcrawl/sdk-python generate`
 packages/sdk-python/filtered-openapi.yaml
 # NOTE: the MCP server's generated docs JSON (see packages/mcp-server/src) is intentionally

bytekit_sdk-0.3.4/CHANGELOG.md

@@ -0,0 +1,192 @@
+# Changelog
+
+All notable changes to the ByteKit Python SDK are documented here.
+PyPI distribution: `bytekit-sdk`. Import name: `bytekit`.
+
+## 0.3.4
+
+### Breaking
+
+- **`CreateBulkBody`, `CreateBulkBodyDefaults`, `CreateBulkBodyItemsItem`, and
+  `CreateFetchBulkBodyUrlsItemType1` lost their additional-properties mapping API.**
+  `docs/api/openapi.yaml`'s `/v1/bulk` request schema declares `additionalProperties: false`
+  on the top-level body, `items[]`, and `defaults` (issue #2641), and `/v1/fetch/bulk`'s
+  per-item override schema inside `urls[]` declares the same (issue #2648), matching the
+  gateway's own `.strict()` validators. The code generator responds to
+  `additionalProperties: false` by omitting the catch-all mapping it otherwise attaches to
+  every generated model, so these four models no longer expose `additional_properties`, the
+  `additional_keys` property, `__getitem__`, `__setitem__`, `__delitem__`, or `__contains__`.
+  Code that did `body["some_key"] = value`, `"some_key" in body`, or read
+  `body.additional_keys` on any of these four models will now raise
+  `AttributeError`/`TypeError` instead. Use the model's declared `attrs` fields directly
+  instead (e.g. `CreateBulkBodyItemsItem(url=..., type=...)`,
+  `CreateFetchBulkBodyUrlsItemType1(url=..., format_=...)`); the server itself now rejects
+  unrecognized keys on these endpoints with `422 validation_error`, so the removed escape
+  hatch could never have reached the API successfully anyway. This is scoped to the four
+  `create_bulk_body*` / `create_fetch_bulk_body_urls_item_type_1` models — no other generated
+  model is affected.
+
+## 0.3.3
+
+### Security
+
+- **Path parameters are now percent-encoded.** All 13 operations that interpolate an id into
+  their URL (`get_scrape`, `get_screenshot`, `get_bulk`, `delete_bulk`,
+  `list_bulk_screenshots`, `get_scrape_bulk`, `get_fetch_bulk`, `get_monitor`,
+  `update_monitor`, `delete_monitor`, `list_monitor_captures`, `get_sitemap`,
+  `retry_webhook_delivery`) previously interpolated the value raw, so an id containing `/`,
+  `?`, `#` or traversal segments could retarget the request to a **different path on the same
+  authenticated host** — e.g. a `DELETE /v1/bulk/{id}` becoming a delete against another
+  resource. Values are now encoded with `quote(str(value), safe="")`. This is **not** a
+  breaking change for any id the API issues: hex and `sc_`/`ss_`/`mon_`/`sm_`/`bulk_`-prefixed
+  ids contain no reserved characters, so the resulting URL is byte-identical to before.
+  No id-format validation was added — the client does not reject id shapes.
+
+### Fixed
+
+- **Reusing one client across several `asyncio.run(...)` calls no longer raises
+  `RuntimeError: Event loop is closed`.** An `httpx.AsyncClient`'s connection pool belongs to
+  the event loop that created it, and the SDK cached its internal async client
+  unconditionally. It now tracks which loop that client was built on and transparently
+  rebuilds it when the running loop changes, re-applying `base_url`, headers, timeout,
+  `httpx_args` and authentication. Behavior is unchanged when no loop is running, and a client
+  you supply via `set_async_httpx_client(...)` is **never** rebuilt or closed — it stays yours
+  to manage. See the README's new "Clients and event loops" section.
+- **The README quick start now prints markdown instead of an `Unset` placeholder.** It
+  requested no `formats`, so the server applied its `raw_html` default and
+  `result.formats.markdown` was legitimately unset. It now asks for
+  `formats=[ScrapeRequestFormatsItem.MARKDOWN]` — note `formats` takes enum members, not plain
+  strings.
+- **`client.search(type="images")` no longer crashes with a bare `KeyError: 'snippet'`.**
+  The OpenAPI spec's search result-item schema declared `snippet` as `required` while its
+  own description said the key is omitted for `images` results — a self-contradiction the
+  code generator trusted literally, so `CreateSearchResponse200ResultsItem.from_dict`
+  unconditionally did `d.pop("snippet")`. `snippet` (like `date`) is now `Union[Unset, str]`,
+  matching the real gateway behavior (`web`/`news` results still always carry `snippet`;
+  `images` results omit it entirely) — fixed at the spec level (`docs/api/openapi.yaml`) and
+  regenerated, not patched in the generated model. (Issue #2579.)
+- **Server defaults are no longer materialized into request wire bodies/query strings
+  for inline request bodies and `$ref`'d parameters.** `scripts/filter-spec.ts`'s
+  default-stripping traversal previously only followed `$ref`'d request-body component
+  schemas, so `ScrapeRequest`/`FetchRequest` were clean but every other request-direction
+  shape kept baking in server defaults: `/v1/search`'s fully-inline body (`type`,
+  `limit`, `country`, `language`, `date_range`), all three bulk endpoints' bodies and
+  their nested `Defaults`/`ItemsItem` models, and `$ref`'d query parameters
+  (`GET /v1/fetch`'s `country`/`timeout_ms`/`cache_ttl`, `list_monitors`'
+  `limit`/`status`, `list_webhook_deliveries`'/`list_monitor_captures`' `limit`,
+  `create_screenshot`'s `async`). The traversal now walks inline request bodies AND
+  parameters (both operation-level and shared path-item-level, `$ref`'d or inline)
+  before generation, so an omitted optional field always serializes to nothing and
+  the server's own default applies — caller-supplied values are unaffected and still
+  serialize exactly as given (issue #2592).
+- `tests/test_no_materialized_defaults.py` rewritten to enumerate every
+  request-direction model and operation parameter programmatically (walking the
+  generated `bytekit.api`/`bytekit.models` trees) instead of sampling two known-clean
+  models, so a newly introduced leaker is caught automatically.
+
+### Changed
+
+- **The source distribution no longer ships `tests/`.** The bundled suite could not be
+  collected from an unpacked sdist: 12 of its 27 modules require the repository's codegen
+  scripts or the canonical OpenAPI spec, neither of which belongs in a published
+  distribution, and three of them build distributions of the package itself. Nothing
+  importable was removed — the **wheel is unchanged**, `py.typed` included, so
+  `pip install bytekit-sdk` is unaffected.
+
+### Internal
+
+- CI now proves the committed client is reproducible from the canonical OpenAPI spec, and that
+  the generation chain is deterministic (generating twice yields byte-identical output). This
+  closes the gap where a spec change could land with a TypeScript-only regeneration and leave
+  the Python client silently stranded on an older spec.
+- `ruff` is now pinned to an exact version alongside the code generator. The generator runs
+  `ruff` over everything it emits, so it — not the generator alone — determines the committed
+  bytes; the generator itself accepts any `ruff<0.13`, which meant a fresh install could
+  reformat the whole tree. Bumping the pin is a deliberate, reviewed reformat.
+- The PEP 561 `py.typed` marker is now emitted by the post-generation injector rather than
+  hand-maintained inside the generated tree (the generator omits it under `--meta none`).
+
+## 0.3.2
+
+### Added
+
+- **`bytekit.__version__`** reports the installed distribution version, resolved at import
+  time from `importlib.metadata` (so it can never drift from `pyproject.toml`'s
+  `[project].version`). When the package is imported from a source tree with no installed
+  distribution it reads `0.0.0.dev0` rather than raising. The dead version override in
+  `sdk-python-config.yaml` — inert under `--meta none` and contradicting the real
+  version — has been removed, leaving one authoritative version.
+
+### Fixed
+
+- **`AuthenticatedClient.search()` is now visible to type checkers.** It was attached to the
+  class after creation, so despite the package shipping a `py.typed` marker, `mypy` and
+  `pyright` reported `"AuthenticatedClient" has no attribute "search"`. It is now declared as a
+  real method in the class body that delegates to the same implementation: **runtime behavior,
+  arguments, return type and raised errors are unchanged** — only the static surface is fixed.
+
+## 0.3.1
+
+### Fixed
+
+- **The "never a bare `json.JSONDecodeError`" guarantee is now package-wide across all
+  generated operations**, not only the `AuthenticatedClient.search()` wrapper. Every
+  generated operation previously called `response.json()` unconditionally on a
+  DOCUMENTED status, so a `500`/`502` serving an HTML load-balancer page raised a bare
+  `json.JSONDecodeError` from inside the SDK. All operations now parse documented
+  statuses through a shared guard: a non-JSON body raises the typed
+  `errors.UnexpectedStatus` (or returns `None` when
+  `raise_on_unexpected_status=False`), carrying the status code and the raw body.
+- **`errors.UnexpectedStatus.code` / `.message` are now populated for generated
+  operations too**, from the documented `Error` envelope — previously they were always
+  `None` outside `search()`. A string-valued `error` (the masked search-provider `502`)
+  still never enriches, so the upstream provider's identity is never surfaced.
+- Behavior on JSON bodies is unchanged: JSON success bodies still parse into their typed
+  success models, documented JSON error bodies are still **returned** as typed `Error`
+  models rather than raised, and `raise_on_unexpected_status` semantics are untouched.
+  The documented non-JSON success paths — `get_fetch`/`post_fetch`'s raw-text `200` and
+  `delete_monitor`'s empty `204` — are likewise unaffected.
+- **README error documentation corrected.** The quick-start example wrapped a call in
+  `try/except UnexpectedStatus` and then read `response.formats.markdown`, but a
+  documented `4xx` _returns_ a typed `Error` model without raising — so the documented
+  example failed with `AttributeError: 'Error' object has no attribute 'formats'`. The
+  README now documents the real two-tier contract, and the snippet is executed by
+  `tests/test_readme_examples.py` so it cannot silently drift again.
+
+### Documentation
+
+- Removed the contributor-only `Publishing`, `Regenerating`, and `Development` sections
+  from the published README (the PyPI long description) — they described internal CI
+  mechanics and a monorepo-contributor workflow that do not belong on a public package
+  index. The regeneration/development knowledge is preserved in-repo in
+  `packages/sdk-python/CLAUDE.md` (not shipped in the distribution).
+- Added a `## License` section and a `LICENSE` file, matching the npm sibling packages.
+
+## 0.3.0
+
+### Breaking
+
+- **PyPI distribution renamed `bytekit` -> `bytekit-sdk`.** PyPI administratively
+  denylists the bare name `bytekit`, so the package installs as
+  `pip install bytekit-sdk`. The **import name is unchanged** — `import bytekit`
+  still works, and no module path moved. Nothing was ever published under the old
+  distribution name, so there is no migration for existing installs.
+- **`raise_on_unexpected_status` now defaults to `True`.** Undocumented response
+  statuses now raise `errors.UnexpectedStatus` instead of silently returning `None`.
+  Callers that relied on the old `None`-return behavior must pass
+  `raise_on_unexpected_status=False` explicitly to opt out.
+- **`base_url` is now a keyword-only argument.** It gained a default
+  (`https://api.bytekit.com`), and to satisfy attrs field ordering it became
+  keyword-only. Any caller passing `base_url` positionally must switch to the
+  `base_url=` keyword form. (`base_url=` was already the documented usage.)
+
+### Added
+
+- `AuthenticatedClient(token=...)` now works out of the box against production:
+  `base_url` defaults to `https://api.bytekit.com`.
+- Finite default request timeout of `120s` (`httpx.Timeout(120.0)`) — requests no
+  longer hang indefinitely. Override with `timeout=`.
+- `errors.UnexpectedStatus` now carries optional `.code` / `.message` attributes.
+  The `AuthenticatedClient.search()` wrapper populates them from the documented
+  `Error` envelope, and safely raises a typed error (never a bare
+  `json.JSONDecodeError`) on a non-JSON documented-status body such as an HTML 502.

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bytekit-sdk
-Version: 0.3.2
+Version: 0.3.4
 Summary: Official Python SDK for the ByteKit API
 Project-URL: Homepage, https://bytekit.com
 Project-URL: Repository, https://github.com/Hunt-Labs-Inc/ByteKit
@@ -46,16 +46,24 @@ The installed version is available as `bytekit.__version__`.
 from bytekit import AuthenticatedClient
 from bytekit.api.scrape import create_scrape
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
 from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 # base_url defaults to https://api.bytekit.com, so only the token is required.
 client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
-result = create_scrape.sync(client=client, body=ScrapeRequest(url="https://example.com"))
+result = create_scrape.sync(
+    client=client,
+    body=ScrapeRequest(
+        url="https://example.com",
+        # Ask for markdown explicitly. `formats` is a list of enum members, not plain
+        # strings. Omit it and the server returns raw HTML instead, leaving
+        # `formats.markdown` unset.
+        formats=[ScrapeRequestFormatsItem.MARKDOWN],
+    ),
+)
 
 if isinstance(result, ScrapeSuccessEnvelope):
-    # formats.markdown is str | Unset — only set when "markdown" was among the
-    # requested formats.
     print(result.formats.markdown)
 ```
 
@@ -127,6 +135,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Clients and event loops
+
+An `httpx.AsyncClient` — and therefore its connection pool — belongs to the event loop that
+created it. The recommended shape is a context manager, which scopes the client to exactly one
+loop:
+
+```python
+async def main():
+    async with AuthenticatedClient(token="sk_live_your_api_key_here") as client:
+        ...
+```
+
+Two rules cover everything else:
+
+- **A client the SDK builds for you is rebuilt automatically.** If you reuse one client across
+  several `asyncio.run(...)` calls, the SDK notices the running loop has changed and transparently
+  replaces its internal `AsyncClient`. Your `base_url`, headers, timeout, `httpx_args` and
+  authentication are all re-applied, so this is invisible apart from a new connection. Calling
+  `get_async_httpx_client()` outside any running loop returns the cached client unchanged.
+- **A client you pass to `set_async_httpx_client(...)` is yours.** The SDK never rebuilds or
+  closes it, so a client you supply must be created and used on the same loop — that is the one
+  case where crossing loops is still your responsibility.
+
 ## Available operations
 
 | Module            | Method                                                                                                        | Description                                |

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/README.md

@@ -20,16 +20,24 @@ The installed version is available as `bytekit.__version__`.
 from bytekit import AuthenticatedClient
 from bytekit.api.scrape import create_scrape
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
 from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 # base_url defaults to https://api.bytekit.com, so only the token is required.
 client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
-result = create_scrape.sync(client=client, body=ScrapeRequest(url="https://example.com"))
+result = create_scrape.sync(
+    client=client,
+    body=ScrapeRequest(
+        url="https://example.com",
+        # Ask for markdown explicitly. `formats` is a list of enum members, not plain
+        # strings. Omit it and the server returns raw HTML instead, leaving
+        # `formats.markdown` unset.
+        formats=[ScrapeRequestFormatsItem.MARKDOWN],
+    ),
+)
 
 if isinstance(result, ScrapeSuccessEnvelope):
-    # formats.markdown is str | Unset — only set when "markdown" was among the
-    # requested formats.
     print(result.formats.markdown)
 ```
 
@@ -101,6 +109,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Clients and event loops
+
+An `httpx.AsyncClient` — and therefore its connection pool — belongs to the event loop that
+created it. The recommended shape is a context manager, which scopes the client to exactly one
+loop:
+
+```python
+async def main():
+    async with AuthenticatedClient(token="sk_live_your_api_key_here") as client:
+        ...
+```
+
+Two rules cover everything else:
+
+- **A client the SDK builds for you is rebuilt automatically.** If you reuse one client across
+  several `asyncio.run(...)` calls, the SDK notices the running loop has changed and transparently
+  replaces its internal `AsyncClient`. Your `base_url`, headers, timeout, `httpx_args` and
+  authentication are all re-applied, so this is invisible apart from a new connection. Calling
+  `get_async_httpx_client()` outside any running loop returns the cached client unchanged.
+- **A client you pass to `set_async_httpx_client(...)` is yours.** The SDK never rebuilds or
+  closes it, so a client you supply must be created and used on the same loop — that is the one
+  case where crossing loops is still your responsibility.
+
 ## Available operations
 
 | Module            | Method                                                                                                        | Description                                |

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/pyproject.toml

@@ -7,7 +7,7 @@
 # `pip install bytekit-sdk` yields a working `import bytekit`. Mirrors the npm sibling
 # @hunt-labs/bytekit-sdk.
 name = "bytekit-sdk"
-version = "0.3.2"
+version = "0.3.4"
 description = "Official Python SDK for the ByteKit API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,6 +57,22 @@ Documentation = "https://bytekit.com/docs"
 [dependency-groups]
 dev = [
     "openapi-python-client==0.25.3",
+    # THE FORMATTER IS PART OF THE CODEGEN CONTRACT (#2593). openapi-python-client's DEFAULT
+    # post_hooks are `ruff check . --fix --extend-select=I` and `ruff format .`, run with
+    # cwd = --output-path (see openapi_python_client/config.py) — and sdk-python-config.yaml
+    # sets no `post_hooks` override, so they apply. ruff therefore decides the BYTES of every
+    # emitted module, which makes pinning the generator alone insufficient.
+    #
+    # The generator's own metadata only asks for `ruff<0.13,>=0.2`, so a fresh
+    # `pip install openapi-python-client==0.25.3` resolves 0.12.x — nine minor versions above
+    # the version that actually produced the committed tree. Left unpinned, the reproducibility
+    # gate (ci/scripts/check-sdk-python-regen.sh) would red a CORRECT tree, and no regen would
+    # stably fix it. 0.3.7 is measured to reproduce all 221 committed modules byte-for-byte.
+    #
+    # Bumping this pin is a DELIBERATE, REVIEWED 221-file reformat — exactly like bumping the
+    # generator pin above — never an incidental upgrade. The gate reads this pin, so there is
+    # no second copy of the version to keep in sync.
+    "ruff==0.3.7",
     # Read by scripts/prune-stale-api.py (parses filtered-openapi.yaml to derive which
     # api/ group dirs the spec still produces) and by tests/conftest.py. Generation-time
     # and test-time only — never a runtime dependency of the published client.
@@ -82,9 +98,23 @@ testpaths = ["tests"]
 pythonpath = ["src"]
 
 [tool.hatch.build.targets.sdist]
+# The test tree was REMOVED from this allowlist in #2593 (the pre-merge grep gate asserts the
+# glob appears zero times in this file, so a reintroduction is caught even inside a comment —
+# hence the prose here names it in words). The shipped suite could not collect: 12 of 27 modules need
+# `scripts/` (contributor-only codegen tooling) or the canonical `docs/api/openapi.yaml` (which
+# lives two directories above this package), and three of them build distributions of this
+# package — incoherent from inside an unpacked sdist. Verified from the built artifact:
+# `FileNotFoundError: .../scripts/inject-handwritten.py` interrupted collection.
+#
+# Dropped rather than made self-contained: vendoring `scripts/` + a copy of the spec into a
+# public distribution would breach the same published-content boundary that keeps CLAUDE.md out.
+# A test tree that cannot run is worse than none — it reads as a promise to downstream packagers
+# that running it validates the install. Pinned by tests/test_sdist_excludes_tests.
+#
+# The WHEEL is untouched (see [tool.hatch.build.targets.wheel] above): no importable module is
+# removed from what users install.
 include = [
     "src/bytekit/**",
-    "tests/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/src/bytekit/api/account/get_account.py

@@ -7,6 +7,7 @@ from ... import errors
 from ...client import AuthenticatedClient, Client
 from ...models.account_bearer_response import AccountBearerResponse
 from ...models.account_session_response import AccountSessionResponse
+from ...models.error import Error
 from ...types import Response
 
 
@@ -21,7 +22,7 @@ def _get_kwargs() -> dict[str, Any]:
 
 def _parse_response(
     *, client: Union[AuthenticatedClient, Client], response: httpx.Response
-) -> Optional[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Optional[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     if response.status_code == 200:
 
         def _parse_response_200(
@@ -44,6 +45,10 @@ def _parse_response(
         response_200 = errors.bytekit_parse(_parse_response_200, client=client, response=response)
 
         return response_200
+    if response.status_code == 429:
+        response_429 = errors.bytekit_parse(Error.from_dict, client=client, response=response)
+
+        return response_429
     if client.raise_on_unexpected_status:
         raise errors.bytekit_unexpected(response)  # BYTEKIT-OP-GUARD
     else:
@@ -52,7 +57,7 @@ def _parse_response(
 
 def _build_response(
     *, client: Union[AuthenticatedClient, Client], response: httpx.Response
-) -> Response[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Response[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     return Response(
         status_code=HTTPStatus(response.status_code),
         content=response.content,
@@ -64,7 +69,7 @@ def _build_response(
 def sync_detailed(
     *,
     client: AuthenticatedClient,
-) -> Response[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Response[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     """Get account details
 
      Returns account, plan, and current API key details, including the
@@ -75,7 +80,7 @@ def sync_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Union['AccountBearerResponse', 'AccountSessionResponse']]
+        Response[Union[Error, Union['AccountBearerResponse', 'AccountSessionResponse']]]
     """
 
     kwargs = _get_kwargs()
@@ -90,7 +95,7 @@ def sync_detailed(
 def sync(
     *,
     client: AuthenticatedClient,
-) -> Optional[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Optional[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     """Get account details
 
      Returns account, plan, and current API key details, including the
@@ -101,7 +106,7 @@ def sync(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Union['AccountBearerResponse', 'AccountSessionResponse']
+        Union[Error, Union['AccountBearerResponse', 'AccountSessionResponse']]
     """
 
     return sync_detailed(
@@ -112,7 +117,7 @@ def sync(
 async def asyncio_detailed(
     *,
     client: AuthenticatedClient,
-) -> Response[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Response[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     """Get account details
 
      Returns account, plan, and current API key details, including the
@@ -123,7 +128,7 @@ async def asyncio_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Union['AccountBearerResponse', 'AccountSessionResponse']]
+        Response[Union[Error, Union['AccountBearerResponse', 'AccountSessionResponse']]]
     """
 
     kwargs = _get_kwargs()
@@ -136,7 +141,7 @@ async def asyncio_detailed(
 async def asyncio(
     *,
     client: AuthenticatedClient,
-) -> Optional[Union["AccountBearerResponse", "AccountSessionResponse"]]:
+) -> Optional[Union[Error, Union["AccountBearerResponse", "AccountSessionResponse"]]]:
     """Get account details
 
      Returns account, plan, and current API key details, including the
@@ -147,7 +152,7 @@ async def asyncio(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Union['AccountBearerResponse', 'AccountSessionResponse']
+        Union[Error, Union['AccountBearerResponse', 'AccountSessionResponse']]
     """
 
     return (

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.4}/src/bytekit/api/bulk/create_bulk.py

@@ -74,12 +74,38 @@ def sync_detailed(
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
 
+    **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+    with no `Content-Length` header is capped at 4 MB before your API key
+    is checked; a body that declares `Content-Length` is instead bounded
+    there by a 32 MB fail-safe (not the real limit — see below), since
+    that branch reads nothing until your key is verified. Once your key
+    is verified, a second check re-gates the body against your account's
+    own `max_bulk_size` (at this endpoint's richer per-item override
+    budget), which reaches 28.7 MB for the largest documented account. A
+    standard-plan account's effective ceiling is 4 MB; either tier's
+    overrun returns a `400` with error code `request_too_large`.
+
     Args:
         body (CreateBulkBody): Provide `urls` (simple list) OR `items` (per-item config), not
             both. `type` selects the capture kind per entry — only
             `screenshot` and `scrape` are accepted (`recording` is
             deactivated). Behaviour fields may be set per item or via
             `defaults`; a per-item value overrides the matching default.
+            This includes `type`: an entry with no `type` of its own
+            inherits `defaults.type`, falling back to `screenshot` only
+            when neither is set.
+
+            The top-level object, each `items[]` entry, and `defaults`
+            each reject unrecognized keys with a 422 `validation_error`
+            (the offending key name appears in the error's `details`
+            message text) rather than silently discarding them.
+            `items[]` and `defaults` do not share one field set:
+            `device_scale_factor` is accepted only under `defaults` (a
+            per-item value 422s), and `duration`/`scenario` are accepted
+            only per item (a `defaults` value 422s). `metadata` is
+            different from those three: it is valid both at the top
+            level of the body and per item, but rejected with a 422 if
+            placed under `defaults`. See the `422` response below.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -112,12 +138,38 @@ def sync(
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
 
+    **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+    with no `Content-Length` header is capped at 4 MB before your API key
+    is checked; a body that declares `Content-Length` is instead bounded
+    there by a 32 MB fail-safe (not the real limit — see below), since
+    that branch reads nothing until your key is verified. Once your key
+    is verified, a second check re-gates the body against your account's
+    own `max_bulk_size` (at this endpoint's richer per-item override
+    budget), which reaches 28.7 MB for the largest documented account. A
+    standard-plan account's effective ceiling is 4 MB; either tier's
+    overrun returns a `400` with error code `request_too_large`.
+
     Args:
         body (CreateBulkBody): Provide `urls` (simple list) OR `items` (per-item config), not
             both. `type` selects the capture kind per entry — only
             `screenshot` and `scrape` are accepted (`recording` is
             deactivated). Behaviour fields may be set per item or via
             `defaults`; a per-item value overrides the matching default.
+            This includes `type`: an entry with no `type` of its own
+            inherits `defaults.type`, falling back to `screenshot` only
+            when neither is set.
+
+            The top-level object, each `items[]` entry, and `defaults`
+            each reject unrecognized keys with a 422 `validation_error`
+            (the offending key name appears in the error's `details`
+            message text) rather than silently discarding them.
+            `items[]` and `defaults` do not share one field set:
+            `device_scale_factor` is accepted only under `defaults` (a
+            per-item value 422s), and `duration`/`scenario` are accepted
+            only per item (a `defaults` value 422s). `metadata` is
+            different from those three: it is valid both at the top
+            level of the body and per item, but rejected with a 422 if
+            placed under `defaults`. See the `422` response below.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -145,12 +197,38 @@ async def asyncio_detailed(
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
 
+    **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+    with no `Content-Length` header is capped at 4 MB before your API key
+    is checked; a body that declares `Content-Length` is instead bounded
+    there by a 32 MB fail-safe (not the real limit — see below), since
+    that branch reads nothing until your key is verified. Once your key
+    is verified, a second check re-gates the body against your account's
+    own `max_bulk_size` (at this endpoint's richer per-item override
+    budget), which reaches 28.7 MB for the largest documented account. A
+    standard-plan account's effective ceiling is 4 MB; either tier's
+    overrun returns a `400` with error code `request_too_large`.
+
     Args:
         body (CreateBulkBody): Provide `urls` (simple list) OR `items` (per-item config), not
             both. `type` selects the capture kind per entry — only
             `screenshot` and `scrape` are accepted (`recording` is
             deactivated). Behaviour fields may be set per item or via
             `defaults`; a per-item value overrides the matching default.
+            This includes `type`: an entry with no `type` of its own
+            inherits `defaults.type`, falling back to `screenshot` only
+            when neither is set.
+
+            The top-level object, each `items[]` entry, and `defaults`
+            each reject unrecognized keys with a 422 `validation_error`
+            (the offending key name appears in the error's `details`
+            message text) rather than silently discarding them.
+            `items[]` and `defaults` do not share one field set:
+            `device_scale_factor` is accepted only under `defaults` (a
+            per-item value 422s), and `duration`/`scenario` are accepted
+            only per item (a `defaults` value 422s). `metadata` is
+            different from those three: it is valid both at the top
+            level of the body and per item, but rejected with a 422 if
+            placed under `defaults`. See the `422` response below.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -181,12 +259,38 @@ async def asyncio(
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
 
+    **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+    with no `Content-Length` header is capped at 4 MB before your API key
+    is checked; a body that declares `Content-Length` is instead bounded
+    there by a 32 MB fail-safe (not the real limit — see below), since
+    that branch reads nothing until your key is verified. Once your key
+    is verified, a second check re-gates the body against your account's
+    own `max_bulk_size` (at this endpoint's richer per-item override
+    budget), which reaches 28.7 MB for the largest documented account. A
+    standard-plan account's effective ceiling is 4 MB; either tier's
+    overrun returns a `400` with error code `request_too_large`.
+
     Args:
         body (CreateBulkBody): Provide `urls` (simple list) OR `items` (per-item config), not
             both. `type` selects the capture kind per entry — only
             `screenshot` and `scrape` are accepted (`recording` is
             deactivated). Behaviour fields may be set per item or via
             `defaults`; a per-item value overrides the matching default.
+            This includes `type`: an entry with no `type` of its own
+            inherits `defaults.type`, falling back to `screenshot` only
+            when neither is set.
+
+            The top-level object, each `items[]` entry, and `defaults`
+            each reject unrecognized keys with a 422 `validation_error`
+            (the offending key name appears in the error's `details`
+            message text) rather than silently discarding them.
+            `items[]` and `defaults` do not share one field set:
+            `device_scale_factor` is accepted only under `defaults` (a
+            per-item value 422s), and `duration`/`scenario` are accepted
+            only per item (a `defaults` value 422s). `metadata` is
+            different from those three: it is valid both at the top
+            level of the body and per item, but rejected with a 422 if
+            placed under `defaults`. See the `422` response below.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.