bytekit-sdk 0.5.2__tar.gz → 0.6.0__tar.gz

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/CHANGELOG.md

@@ -5,6 +5,98 @@ PyPI distribution: `bytekit-sdk`. Import name: `bytekit`.
 
 ## Unreleased
 
+## 0.6.0
+
+_Release cut 2026-09-11._
+
+### Changed
+
+- **`create_scrape` now raises on a terminal scrape failure, even though it arrives on a
+  `200`** (#1870). The synchronous `POST /v1/scrape` used to answer an unreachable host, a
+  refused connection, or a bot-protection block that defeated every proxy tier with a `503`.
+  It now answers `200` carrying the canonical `failed` envelope, because a failed fetch is a
+  result rather than a transport error. Left alone, the generated union would have parsed that
+  envelope and RETURNED it on the same arm a caller reads `.formats` from, so the most common
+  first-call shape — "it returned, so it worked" — would have silently succeeded on a failed
+  scrape. `create_scrape.sync` / `.sync_detailed` / `.asyncio` / `.asyncio_detailed` therefore
+  raise `errors.UnexpectedStatus` with `.status_code` `200` and `.code` / `.message` read off
+  the envelope's `error`; under `raise_on_unexpected_status=False` they return `None`, as for
+  any other unusable body.
+
+  The carve-out is that one call site. `get_scrape` still RETURNS the identical envelope as a
+  typed `ScrapeErrorEnvelope` — polling a job that failed is a successful poll — and every
+  documented 4xx/5xx on `create_scrape` still returns its typed `Error` model.
+
+  **Upgrading:** if you inspected the result of `create_scrape` for `status == "failed"`, move
+  that handling into an `except errors.UnexpectedStatus` block. Code that already caught
+  `UnexpectedStatus` needs no change.
+
+## 0.5.4 [NEVER PUBLISHED]
+
+_Release cut 2026-09-06._
+
+> **Never published to PyPI.** Publication is triggered by CI on `main` from the version
+> `pyproject.toml` declares, and 0.6.0 (#1870) superseded 0.5.4 in the tree before any release
+> reached `main` — no `bytekit-sdk` 0.5.4 artifact exists, so `pip install bytekit-sdk==0.5.4`
+> fails. Everything below shipped to users in **0.6.0**, the first published release containing
+> it.
+
+### Added
+
+- Bulk fetch, scrape, and mixed-result models now publish cursor pagination, stable item
+  identities, whole-job counters, exact mixed artifact keys, artifact warnings, bounded
+  webhook recovery metadata, and the `artifact_unavailable` error contract (#3717).
+  Generated bulk read functions accept optional `cursor`, `limit`, and `status` parameters.
+
+### Fixed
+
+- Corrected the artifact-URL fallback docstrings on `list_bulk_screenshots` (`image_url`,
+  `content_url`, `markdown_url`) and the `/v1/logs` row model (`artifact_url`) (#3717). Those
+  fields were documented as null-plus-`artifact_unavailable` when no signature can be minted;
+  the servers have always returned the row's stored value unchanged instead — `None` while
+  nothing is stored, and otherwise the private unsigned storage URL, which answers `401` — and
+  raise no warning. `get_fetch_bulk` does null the field and report `artifact_unavailable`, and
+  its docstring is unchanged. No server behaviour changed and no model moved; only the
+  documentation on them did.
+
+### Changed
+
+- Regenerated `GetUsageResponse200` against the corrected `topup_balance_bytes` description
+  (#4251). The field's docstring read "Remaining purchased top-up bytes", which contradicted its
+  own "Equal to `topup_bytes`" clause: the value covers purchased top-up lots and the one-time
+  starter grant, which is what the endpoint has always returned. The clause recording that the
+  figure is already net of consumed overage, and the "Present only in dual/bytes billing mode"
+  clause, are both unchanged and still true. Types are unchanged and no server value changed;
+  only the documentation on them moved.
+- Regenerated `ScrapeSuccessEnvelope` against the clarified `cache_age_s` description (#4237).
+  The field's docstring now records that `GET /v1/scrape/{id}` reports `cache: hit` without
+  `cache_age_s`: the age is a property of the replay that happened at completion time, is not
+  persisted on the row, and cannot be derived honestly afterwards. The one-directional
+  "Present only on `cache: hit`" clause is unchanged and still true. Types are unchanged; only
+  the documentation on them moved.
+- Regenerated `ScrapeSuccessEnvelope` against the completed `cache` presence list (#4203).
+  The field's description now names `GET /v1/scrape/{id}` as a third delivery path, alongside
+  the synchronous response and webhook delivery: a polled scrape now reports the cache
+  disposition its row recorded, and omits the field — rather than defaulting it to `miss` — for
+  a row that recorded none. Types are unchanged; only the documentation on them moved.
+- Regenerated `MonitorCreateRequestScrapeOptions` against the corrected `scrape_options`
+  documentation (#4024). The description no longer lists `headers` among the accepted
+  fields — `POST /v1/monitors` never honoured a caller-supplied `headers` option and now
+  rejects it with the same 400 every other capture endpoint returns for the field. Types are
+  unchanged; only the documentation on them moved.
+
+## 0.5.3
+
+_Release cut 2026-09-05._
+
+### Changed
+
+- Regenerated `ScrapeQueuedEnvelope` against the corrected `status_url` documentation (#3925).
+  `status_url` is a root-relative path, never an absolute URI: join it onto the API base URL you
+  called (`https://api.bytekit.com`, no trailing slash) to get the URL to poll. The spec had
+  declared it `format: uri` with an absolute example, which no server has ever emitted; the
+  emitted value is unchanged, so no client behaviour moves.
+
 ## 0.5.2
 
 _Release cut 2026-09-03._

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bytekit-sdk
-Version: 0.5.2
+Version: 0.6.0
 Summary: Official Python SDK for the ByteKit API
 Project-URL: Homepage, https://bytekit.com
 Project-URL: Repository, https://github.com/Hunt-Labs-Inc/ByteKit
@@ -75,12 +75,19 @@ The SDK has a **two-tier** error contract. Both tiers are safe: an operation nev
 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`.                                                                                                                                   |
+| 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.                                                     |
+| A **`200` from `create_scrape` carrying a `status: "failed"` envelope** — a terminal upstream failure (unreachable host, refused connection, bot protection that defeats every proxy tier) | `errors.UnexpectedStatus` is **raised**, with `.status_code` `200` and `.code` / `.message` read off the envelope's `error`. `get_scrape` is unchanged: polling a job that failed still **returns** the typed `ScrapeErrorEnvelope`. |
+| Any of the above, with `raise_on_unexpected_status=False`                                                                                                                                  | Nothing is raised; the operation returns `None`.                                                                                                                                                                                     |
+
+A failed scrape is a _result_, not a transport error, so the API reports it on a `200` rather
+than a 5xx — but a returned failure is exactly the shape a first call misreads as success
+(`result.formats` on a `ScrapeErrorEnvelope` is an `AttributeError`). `create_scrape` therefore
+raises it. The carve-out is that one call: the identical envelope from `get_scrape` is the
+correct answer to "how did that job end?" and is still returned.
 
 The table describes the **generated operations** (`create_scrape.sync`, `get_usage.sync`, …),
 whose return types are `Optional[...]` accordingly. The hand-written
@@ -111,7 +118,8 @@ try:
         ),
     )
 except UnexpectedStatus as err:
-    # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
+    # Undocumented status, a non-JSON body on a documented one, or a 200 whose envelope
+    # says the scrape itself failed. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
 else:
     if isinstance(result, Error):

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/README.md

@@ -49,12 +49,19 @@ The SDK has a **two-tier** error contract. Both tiers are safe: an operation nev
 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`.                                                                                                                                   |
+| 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.                                                     |
+| A **`200` from `create_scrape` carrying a `status: "failed"` envelope** — a terminal upstream failure (unreachable host, refused connection, bot protection that defeats every proxy tier) | `errors.UnexpectedStatus` is **raised**, with `.status_code` `200` and `.code` / `.message` read off the envelope's `error`. `get_scrape` is unchanged: polling a job that failed still **returns** the typed `ScrapeErrorEnvelope`. |
+| Any of the above, with `raise_on_unexpected_status=False`                                                                                                                                  | Nothing is raised; the operation returns `None`.                                                                                                                                                                                     |
+
+A failed scrape is a _result_, not a transport error, so the API reports it on a `200` rather
+than a 5xx — but a returned failure is exactly the shape a first call misreads as success
+(`result.formats` on a `ScrapeErrorEnvelope` is an `AttributeError`). `create_scrape` therefore
+raises it. The carve-out is that one call: the identical envelope from `get_scrape` is the
+correct answer to "how did that job end?" and is still returned.
 
 The table describes the **generated operations** (`create_scrape.sync`, `get_usage.sync`, …),
 whose return types are `Optional[...]` accordingly. The hand-written
@@ -85,7 +92,8 @@ try:
         ),
     )
 except UnexpectedStatus as err:
-    # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
+    # Undocumented status, a non-JSON body on a documented one, or a 200 whose envelope
+    # says the scrape itself failed. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
 else:
     if isinstance(result, Error):

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/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.5.2"
+version = "0.6.0"
 description = "Official Python SDK for the ByteKit API"
 readme = "README.md"
 requires-python = ">=3.10"

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/src/bytekit/api/bulk/create_bulk.py

@@ -76,6 +76,9 @@ def sync_detailed(
     Provide `urls` (simple list) or `items` (per-item config), not both.
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
+    The body follows `BulkCompletedWebhook`: at most 500 complete items and
+    1 MiB, followed by cursor recovery through the existing mixed-item route
+    whenever `recovery_required` is true.
 
     **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
@@ -140,6 +143,9 @@ def sync(
     Provide `urls` (simple list) or `items` (per-item config), not both.
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
+    The body follows `BulkCompletedWebhook`: at most 500 complete items and
+    1 MiB, followed by cursor recovery through the existing mixed-item route
+    whenever `recovery_required` is true.
 
     **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
@@ -199,6 +205,9 @@ async def asyncio_detailed(
     Provide `urls` (simple list) or `items` (per-item config), not both.
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
+    The body follows `BulkCompletedWebhook`: at most 500 complete items and
+    1 MiB, followed by cursor recovery through the existing mixed-item route
+    whenever `recovery_required` is true.
 
     **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
@@ -261,6 +270,9 @@ async def asyncio(
     Provide `urls` (simple list) or `items` (per-item config), not both.
     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
     receivers can dispatch on the header without parsing the body shape.
+    The body follows `BulkCompletedWebhook`: at most 500 complete items and
+    1 MiB, followed by cursor recovery through the existing mixed-item route
+    whenever `recovery_required` is true.
 
     **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

bytekit_sdk-0.6.0/src/bytekit/api/bulk/list_bulk_screenshots.py

@@ -0,0 +1,294 @@
+from typing import Any, Optional, Union
+from urllib.parse import quote  # BYTEKIT-PATH-QUOTE
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.list_bulk_screenshots_response_200 import ListBulkScreenshotsResponse200
+from ...models.list_bulk_screenshots_status import ListBulkScreenshotsStatus
+from ...types import UNSET, Response, Unset
+
+
+def _get_kwargs(
+    id: str,
+    *,
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = UNSET,
+    status: Union[Unset, ListBulkScreenshotsStatus] = UNSET,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+
+    params["cursor"] = cursor
+
+    params["limit"] = limit
+
+    json_status: Union[Unset, str] = UNSET
+    if not isinstance(status, Unset):
+        json_status = status.value
+
+    params["status"] = json_status
+
+    params = {k: v for k, v in params.items() if v is not UNSET and v is not None}
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/v1/bulk/{id}/screenshots".format(id=quote(str(id), safe="")),
+        "params": params,
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Optional[ListBulkScreenshotsResponse200]:
+    if response.status_code == 200:
+        response_200 = errors.bytekit_parse(ListBulkScreenshotsResponse200.from_dict, client=client, response=response)
+
+        return response_200
+    if client.raise_on_unexpected_status:
+        raise errors.bytekit_unexpected(response)  # BYTEKIT-OP-GUARD
+    else:
+        return None
+
+
+def _build_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Response[ListBulkScreenshotsResponse200]:
+    return Response(
+        status_code=errors.bytekit_status_code(response.status_code),  # BYTEKIT-STATUS-COERCE
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = UNSET,
+    status: Union[Unset, ListBulkScreenshotsStatus] = UNSET,
+) -> Response[ListBulkScreenshotsResponse200]:
+    """List bulk job items
+
+     Returns the bulk job's items, discriminated by `type`.
+
+    **Downloading item artifacts.** For a `completed` item with a storage key,
+    `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+    (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+    this endpoint and valid for **600 seconds (10 minutes)** —
+    the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
+    Download inside that window, or re-poll this endpoint for a fresh
+    signature.
+
+    **When no signature is minted.** Three cases mint none: an item that is not
+    `completed`, a `completed` item with no storage key, and a `completed` item
+    whose object could not be signed — during an object-storage outage, for
+    instance. In all three the item's stored value is returned unchanged: `null`
+    while nothing has been stored, and otherwise a **private, unsigned**
+    object-storage URL that answers `401`. These fields are neither nulled nor
+    flagged in that case, so treat an artifact URL as usable only once you have
+    downloaded it, and re-poll for a fresh signature otherwise.
+    `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+    `artifacts` object on `type: scrape` items only — they say nothing about
+    `image_url`, `content_url`, or `markdown_url`.
+
+    Args:
+        id (str):
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):
+        status (Union[Unset, ListBulkScreenshotsStatus]):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ListBulkScreenshotsResponse200]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+        cursor=cursor,
+        limit=limit,
+        status=status,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = UNSET,
+    status: Union[Unset, ListBulkScreenshotsStatus] = UNSET,
+) -> Optional[ListBulkScreenshotsResponse200]:
+    """List bulk job items
+
+     Returns the bulk job's items, discriminated by `type`.
+
+    **Downloading item artifacts.** For a `completed` item with a storage key,
+    `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+    (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+    this endpoint and valid for **600 seconds (10 minutes)** —
+    the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
+    Download inside that window, or re-poll this endpoint for a fresh
+    signature.
+
+    **When no signature is minted.** Three cases mint none: an item that is not
+    `completed`, a `completed` item with no storage key, and a `completed` item
+    whose object could not be signed — during an object-storage outage, for
+    instance. In all three the item's stored value is returned unchanged: `null`
+    while nothing has been stored, and otherwise a **private, unsigned**
+    object-storage URL that answers `401`. These fields are neither nulled nor
+    flagged in that case, so treat an artifact URL as usable only once you have
+    downloaded it, and re-poll for a fresh signature otherwise.
+    `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+    `artifacts` object on `type: scrape` items only — they say nothing about
+    `image_url`, `content_url`, or `markdown_url`.
+
+    Args:
+        id (str):
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):
+        status (Union[Unset, ListBulkScreenshotsStatus]):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ListBulkScreenshotsResponse200
+    """
+
+    return sync_detailed(
+        id=id,
+        client=client,
+        cursor=cursor,
+        limit=limit,
+        status=status,
+    ).parsed
+
+
+async def asyncio_detailed(
+    id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = UNSET,
+    status: Union[Unset, ListBulkScreenshotsStatus] = UNSET,
+) -> Response[ListBulkScreenshotsResponse200]:
+    """List bulk job items
+
+     Returns the bulk job's items, discriminated by `type`.
+
+    **Downloading item artifacts.** For a `completed` item with a storage key,
+    `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+    (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+    this endpoint and valid for **600 seconds (10 minutes)** —
+    the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
+    Download inside that window, or re-poll this endpoint for a fresh
+    signature.
+
+    **When no signature is minted.** Three cases mint none: an item that is not
+    `completed`, a `completed` item with no storage key, and a `completed` item
+    whose object could not be signed — during an object-storage outage, for
+    instance. In all three the item's stored value is returned unchanged: `null`
+    while nothing has been stored, and otherwise a **private, unsigned**
+    object-storage URL that answers `401`. These fields are neither nulled nor
+    flagged in that case, so treat an artifact URL as usable only once you have
+    downloaded it, and re-poll for a fresh signature otherwise.
+    `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+    `artifacts` object on `type: scrape` items only — they say nothing about
+    `image_url`, `content_url`, or `markdown_url`.
+
+    Args:
+        id (str):
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):
+        status (Union[Unset, ListBulkScreenshotsStatus]):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ListBulkScreenshotsResponse200]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+        cursor=cursor,
+        limit=limit,
+        status=status,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    id: str,
+    *,
+    client: Union[AuthenticatedClient, Client],
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = UNSET,
+    status: Union[Unset, ListBulkScreenshotsStatus] = UNSET,
+) -> Optional[ListBulkScreenshotsResponse200]:
+    """List bulk job items
+
+     Returns the bulk job's items, discriminated by `type`.
+
+    **Downloading item artifacts.** For a `completed` item with a storage key,
+    `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+    (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+    this endpoint and valid for **600 seconds (10 minutes)** —
+    the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
+    Download inside that window, or re-poll this endpoint for a fresh
+    signature.
+
+    **When no signature is minted.** Three cases mint none: an item that is not
+    `completed`, a `completed` item with no storage key, and a `completed` item
+    whose object could not be signed — during an object-storage outage, for
+    instance. In all three the item's stored value is returned unchanged: `null`
+    while nothing has been stored, and otherwise a **private, unsigned**
+    object-storage URL that answers `401`. These fields are neither nulled nor
+    flagged in that case, so treat an artifact URL as usable only once you have
+    downloaded it, and re-poll for a fresh signature otherwise.
+    `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+    `artifacts` object on `type: scrape` items only — they say nothing about
+    `image_url`, `content_url`, or `markdown_url`.
+
+    Args:
+        id (str):
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):
+        status (Union[Unset, ListBulkScreenshotsStatus]):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ListBulkScreenshotsResponse200
+    """
+
+    return (
+        await asyncio_detailed(
+            id=id,
+            client=client,
+            cursor=cursor,
+            limit=limit,
+            status=status,
+        )
+    ).parsed

{bytekit_sdk-0.5.2 → bytekit_sdk-0.6.0}/src/bytekit/api/fetch_bulk/create_fetch_bulk.py

@@ -74,6 +74,10 @@ def sync_detailed(
 
      Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
     Does not support options that require page rendering (wait_for_selector, etc.).
+    Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+    `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+    followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+    `recovery_required` is true.
 
     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
     with no `Content-Length` header is capped at 2 MB before your API key
@@ -117,6 +121,10 @@ def sync(
 
      Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
     Does not support options that require page rendering (wait_for_selector, etc.).
+    Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+    `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+    followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+    `recovery_required` is true.
 
     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
     with no `Content-Length` header is capped at 2 MB before your API key
@@ -155,6 +163,10 @@ async def asyncio_detailed(
 
      Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
     Does not support options that require page rendering (wait_for_selector, etc.).
+    Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+    `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+    followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+    `recovery_required` is true.
 
     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
     with no `Content-Length` header is capped at 2 MB before your API key
@@ -196,6 +208,10 @@ async def asyncio(
 
      Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
     Does not support options that require page rendering (wait_for_selector, etc.).
+    Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+    `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+    followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+    `recovery_required` is true.
 
     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
     with no `Content-Length` header is capped at 2 MB before your API key