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

{bytekit_sdk-0.3.2 → bytekit_sdk-0.3.5}/.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.5/CHANGELOG.md

@@ -0,0 +1,321 @@
+# Changelog
+
+All notable changes to the ByteKit Python SDK are documented here.
+PyPI distribution: `bytekit-sdk`. Import name: `bytekit`.
+
+## 0.3.5
+
+### Breaking
+
+- **`AuthenticatedClient` takes no positional arguments.** `token`, `prefix` and
+  `auth_header_name` are now keyword-only, joining `base_url`, `timeout`,
+  `raise_on_unexpected_status` and the rest — so `AuthenticatedClient(...)` accepts keywords
+  only. Before 0.3.0 the first positional argument was `base_url`, which made
+  `AuthenticatedClient("https://api-stg.bytekit.com", "sk_live_…")` a documented call. When
+  0.3.0 made `base_url` a defaulted keyword argument, that call stopped meaning what it said
+  and started **binding the URL to `token` and the API key to `prefix`** — sending
+  `Authorization: sk_live_… https://api-stg.bytekit.com` to the _default_ host,
+  `https://api.bytekit.com`, with nothing raised and nothing warned. It now raises
+  `TypeError`. Migration is mechanical:
+  `AuthenticatedClient(base_url="https://api-stg.bytekit.com", token="sk_live_…")`. Keyword
+  construction — the form the README, the docs site and every example already use — is
+  entirely unchanged, including `prefix=`/`auth_header_name=` overrides and the
+  `with_headers`/`with_cookies`/`with_timeout` helpers. The unauthenticated `Client` was
+  already keyword-only and is unaffected.
+
+### Fixed
+
+- **A schema-drifted response body no longer crashes with a bare `KeyError`.** A generated
+  model's `from_dict` trusts the `required` keys the OpenAPI spec declared when the client
+  was generated, so a server that renamed, dropped or retyped a field leaked the generator's
+  own internal exception straight to the caller — `KeyError: 'schema_version'` from
+  `create_scrape`, `KeyError: 'period_start'` from `get_usage`, `KeyError: 'data'` from
+  `list_monitors`, plus `TypeError`/`ValueError` for non-object and nested-drift bodies. It
+  happened on a **documented** status (a `200`/`202`), in **both** raise modes, and no row of
+  the documented error table covered it, so a caller who handled that table faithfully still
+  had no branch for it. Schema drift now takes exactly the same two arms as a non-JSON body:
+  `errors.UnexpectedStatus` (carrying `.status_code` and the raw `.content`, with the
+  original parse failure attached as `__cause__`) in the default mode, and `None` under
+  `raise_on_unexpected_status=False`. Deliberately **no new exception type** — a new class
+  would be one every existing `except errors.UnexpectedStatus` silently fails to catch, i.e.
+  the same untyped crash in a different costume. Bodies that match the documented schema
+  parse exactly as before, and a genuinely optional key that is absent still yields `UNSET`.
+- **`client.search()` never returns a silent `None`.** Its 200 body is parsed through the
+  same shared guard the generated operations use, which honors
+  `raise_on_unexpected_status` — so an opt-out client got `None` handed back from a non-JSON
+  200 or a schema-drifted one, contradicting both the method's non-`Optional` return
+  annotation and its own docstring. `search()` now raises `errors.UnexpectedStatus` in
+  **both** raise modes. `raise_on_unexpected_status` configures the generated two-tier
+  contract, whose signatures are `Optional[...]`; `search()` was never part of it — it
+  already raises on documented error statuses that the generated `create_search` returns as
+  a typed `Error` model. A well-formed 200 still returns the parsed
+  `CreateSearchResponse200` in either mode.
+- **A non-IANA HTTP status no longer crashes every operation with a bare `ValueError`.**
+  Each generated operation built its `Response` with
+  `status_code=HTTPStatus(response.status_code)` evaluated _before_ the response was
+  parsed, so any status outside Python's `http.HTTPStatus` — Cloudflare's `520`–`530`
+  family, nginx's `499` — raised `ValueError: 520 is not a valid HTTPStatus` from inside
+  the SDK. This happened in **both** raise modes: the default
+  `raise_on_unexpected_status=True` never got to raise its `errors.UnexpectedStatus`, and
+  `raise_on_unexpected_status=False`, which promises `None`, raised the `ValueError` too.
+  `api.bytekit.com` is served through Cloudflare, so this was exactly the edge/CDN failure
+  class the typed-error contract exists for. All 29 operations now behave as documented:
+  `errors.UnexpectedStatus` (carrying `.status_code` and the raw `.content`) in the default
+  mode, a `Response` with `.parsed is None` in the opt-out mode. The hand-written
+  `client.search()` wrapper was never affected and is unchanged.
+
+### Changed
+
+- **`Response.status_code` is a plain `int` for a status `http.HTTPStatus` does not know.**
+  This is the contract decision behind the fix above, recorded here because it is the one
+  observable difference in the typed surface. Concretely:
+  - Every status the stdlib enum **does** know — documented by the API or not, `200` as
+    much as `503` — still comes back as a real `http.HTTPStatus` member, so
+    `response.status_code.phrase`, `.name`, and identity comparisons such as
+    `response.status_code is HTTPStatus.OK` keep working exactly as before.
+  - A status the enum does **not** know (`499`, `520`, `521`, `522`, `530`, …) comes back
+    as the plain `int` the wire carried. `int` comparisons (`response.status_code == 520`,
+    `>= 500`) work; enum-only attributes (`.phrase`, `.name`) do not exist on it. The
+    alternatives were rejected deliberately: a synthetic `IntEnum` member would invent a
+    `.phrase`/`.name` no registry backs, and raising before the `Response` is constructed
+    is the bug itself — it is precisely what `raise_on_unexpected_status=False` promises
+    not to do.
+  - The **declared** annotation on `Response.status_code` is unchanged (`HTTPStatus`), so
+    this release adds no type errors to existing consumer code; widening it to
+    `Union[HTTPStatus, int]` would make `.phrase`/`.name` a type error on _every_ response,
+    including the IANA ones, which is a far larger break than the residual it would close.
+    Reach for `.phrase`/`.name` only after an `isinstance(..., HTTPStatus)` check if you
+    handle edge statuses off a non-raising client.
+
+  In the default (raising) mode this is largely invisible: a non-IANA status raises
+  `errors.UnexpectedStatus` before any `Response` is returned, and
+  `UnexpectedStatus.status_code` has always been a plain `int`.
+
+### Documentation
+
+- The "Error handling" example in the README now requests `formats=[…MARKDOWN]` explicitly.
+  Run literally, its success arm printed `<bytekit.types.Unset object at 0x…>`: the snippet
+  built `ScrapeRequest(url=...)` with no `formats`, so the server applied its `raw_html`
+  default and `result.formats.markdown` was legitimately unset. The same class of defect
+  0.3.3 fixed in the quick start, in the block directly beneath it. The README's error table
+  gains the schema-drift row, a note that `search()` is outside the two-tier contract, and a
+  migration note for the keyword-only constructor.
+
+## 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.
+
+- If you are upgrading from 0.3.2 or earlier, note that **0.3.3 also carried a breaking model
+  removal** that went undocumented at the time — see the "Breaking" entry under 0.3.3 below
+  (`CreateFetchBulkBodyMetadata` and `CreateScrapeBulkBodyItemsItemMetadata`).
+
+## 0.3.3 [NEVER PUBLISHED]
+
+> **Never published to PyPI.** This version was cut in-tree but no `bytekit-sdk` 0.3.3 artifact
+> exists — `pip install bytekit-sdk==0.3.3` fails. Everything below shipped to users in **0.3.4**,
+> which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
+
+### Breaking
+
+- **`CreateFetchBulkBodyMetadata` and `CreateScrapeBulkBodyItemsItemMetadata` were removed;
+  both fields now use the shared `Metadata` model.** This landed with the default-stripping
+  traversal fix listed under "Fixed" below (issue #2592) and was not recorded at the time.
+  Once server defaults stopped being materialized into the request-direction schemas, the two
+  per-body `metadata` objects became structurally identical to the shared `Metadata`
+  component, and the code generator emits one model per distinct schema — so
+  `bytekit.models.create_fetch_bulk_body_metadata` and
+  `bytekit.models.create_scrape_bulk_body_items_item_metadata` no longer exist and importing
+  either raises `ModuleNotFoundError`. `CreateFetchBulkBody.metadata` and
+  `CreateScrapeBulkBodyItemsItem.metadata` are now typed `Union[Unset, Metadata]`. The wire
+  format is **unchanged** — the same JSON object is sent either way — so the migration is
+  purely at the import site: `from bytekit.models.metadata import Metadata`, then
+  `Metadata(...)` (or `Metadata.from_dict({...})`) wherever you constructed one of the two
+  removed classes.
+
+### 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 [NEVER PUBLISHED]
+
+> **Never published to PyPI.** This version was cut in-tree but no `bytekit-sdk` 0.3.1 artifact
+> exists — `pip install bytekit-sdk==0.3.1` fails. Everything below shipped to users in **0.3.2**,
+> which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
+
+### 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.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bytekit-sdk
-Version: 0.3.2
+Version: 0.3.5
 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)
 ```
 
@@ -64,13 +72,22 @@ See [Error handling](#error-handling) for what `result` can be when the request
 ### Error handling
 
 The SDK has a **two-tier** error contract. Both tiers are safe: an operation never raises
-a bare `json.JSONDecodeError`, even when a server returns an HTML error page.
-
-| Situation                                                                                                                   | What you get                                                                                                                                                                       |
-| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body     | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
-| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body) | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
-| Either of the above, with `raise_on_unexpected_status=False`                                                                | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+a bare `json.JSONDecodeError` or a bare `KeyError`, even when a server returns an HTML error
+page or a payload whose shape has drifted from the spec.
+
+| Situation                                                                                                                                       | What you get                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body of the documented shape | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
+| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body)                     | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
+| A **documented status whose JSON body does not match the documented schema** — a field the server renamed, dropped or retyped                   | `errors.UnexpectedStatus` is **raised**, same shape as the row above. The underlying parse failure (e.g. `KeyError: 'schema_version'`) is attached as `__cause__` for diagnosis.   |
+| Any of the above, with `raise_on_unexpected_status=False`                                                                                       | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+
+The table describes the **generated operations** (`create_scrape.sync`, `get_usage.sync`, …),
+whose return types are `Optional[...]` accordingly. The hand-written
+`AuthenticatedClient.search(...)` convenience method is deliberately outside it: it returns a
+non-`Optional` `CreateSearchResponse200` and raises `errors.UnexpectedStatus` on anything else
+— including documented error statuses, and including a malformed `200` — **in both raise
+modes**. `raise_on_unexpected_status` does not apply to it.
 
 ```python
 from bytekit import AuthenticatedClient
@@ -78,12 +95,21 @@ from bytekit.api.scrape import create_scrape
 from bytekit.errors import UnexpectedStatus
 from bytekit.models.error import Error
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
 from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
 try:
-    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 — omit `formats` and the server returns raw HTML,
+            # leaving `formats.markdown` unset.
+            formats=[ScrapeRequestFormatsItem.MARKDOWN],
+        ),
+    )
 except UnexpectedStatus as err:
     # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
@@ -110,6 +136,22 @@ The client ships with production-ready defaults so `AuthenticatedClient(token=..
 
 Explicit constructor arguments always win over these defaults (explicit arg > default).
 
+#### Every constructor argument is keyword-only
+
+`AuthenticatedClient` accepts **no positional arguments**. `token`, `base_url`, `prefix`,
+`auth_header_name` and the rest are all passed by name:
+
+```python
+client = AuthenticatedClient(base_url="https://api.bytekit.com", token="sk_live_your_api_key_here")
+```
+
+**Migrating from a pre-0.3.0 positional call.** `base_url` used to be the first positional
+argument, so `AuthenticatedClient("https://…", "sk_live_…")` was a documented call. Once
+`base_url` became a defaulted keyword argument, that same call silently bound the **URL to
+`token`** and the **API key to `prefix`** — producing an `Authorization: sk_live_… https://…`
+header sent to the _default_ host, i.e. a wrong credential against production with nothing
+raised. Since 0.3.5 it raises `TypeError` instead. Add the keywords; nothing else changes.
+
 ## Async usage
 
 ```python
@@ -127,6 +169,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.5}/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)
 ```
 
@@ -38,13 +46,22 @@ See [Error handling](#error-handling) for what `result` can be when the request
 ### Error handling
 
 The SDK has a **two-tier** error contract. Both tiers are safe: an operation never raises
-a bare `json.JSONDecodeError`, even when a server returns an HTML error page.
-
-| Situation                                                                                                                   | What you get                                                                                                                                                                       |
-| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body     | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
-| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body) | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
-| Either of the above, with `raise_on_unexpected_status=False`                                                                | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+a bare `json.JSONDecodeError` or a bare `KeyError`, even when a server returns an HTML error
+page or a payload whose shape has drifted from the spec.
+
+| Situation                                                                                                                                       | What you get                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body of the documented shape | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
+| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body)                     | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
+| A **documented status whose JSON body does not match the documented schema** — a field the server renamed, dropped or retyped                   | `errors.UnexpectedStatus` is **raised**, same shape as the row above. The underlying parse failure (e.g. `KeyError: 'schema_version'`) is attached as `__cause__` for diagnosis.   |
+| Any of the above, with `raise_on_unexpected_status=False`                                                                                       | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+
+The table describes the **generated operations** (`create_scrape.sync`, `get_usage.sync`, …),
+whose return types are `Optional[...]` accordingly. The hand-written
+`AuthenticatedClient.search(...)` convenience method is deliberately outside it: it returns a
+non-`Optional` `CreateSearchResponse200` and raises `errors.UnexpectedStatus` on anything else
+— including documented error statuses, and including a malformed `200` — **in both raise
+modes**. `raise_on_unexpected_status` does not apply to it.
 
 ```python
 from bytekit import AuthenticatedClient
@@ -52,12 +69,21 @@ from bytekit.api.scrape import create_scrape
 from bytekit.errors import UnexpectedStatus
 from bytekit.models.error import Error
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
 from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
 try:
-    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 — omit `formats` and the server returns raw HTML,
+            # leaving `formats.markdown` unset.
+            formats=[ScrapeRequestFormatsItem.MARKDOWN],
+        ),
+    )
 except UnexpectedStatus as err:
     # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
@@ -84,6 +110,22 @@ The client ships with production-ready defaults so `AuthenticatedClient(token=..
 
 Explicit constructor arguments always win over these defaults (explicit arg > default).
 
+#### Every constructor argument is keyword-only
+
+`AuthenticatedClient` accepts **no positional arguments**. `token`, `base_url`, `prefix`,
+`auth_header_name` and the rest are all passed by name:
+
+```python
+client = AuthenticatedClient(base_url="https://api.bytekit.com", token="sk_live_your_api_key_here")
+```
+
+**Migrating from a pre-0.3.0 positional call.** `base_url` used to be the first positional
+argument, so `AuthenticatedClient("https://…", "sk_live_…")` was a documented call. Once
+`base_url` became a defaulted keyword argument, that same call silently bound the **URL to
+`token`** and the **API key to `prefix`** — producing an `Authorization: sk_live_… https://…`
+header sent to the _default_ host, i.e. a wrong credential against production with nothing
+raised. Since 0.3.5 it raises `TypeError` instead. Add the keywords; nothing else changes.
+
 ## Async usage
 
 ```python
@@ -101,6 +143,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                                |