@hunt-labs/bytekit-sdk 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -10,6 +10,29 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-09-21
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` (#4732): the `422` responses of `GET /v1/fetch` and
+  `POST /v1/fetch` declare the optional `X-Fetch-ID` header, present when the failed request was
+  recorded and naming its row in Logs (`sc_<hex>` for the header's `ft_<hex>`). Doc comments
+  only; no SDK signature moves.
+
+## [0.11.3] - 2026-09-21
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` (#4669): `GET /v1/fetch` and `POST /v1/fetch` document a
+  second `422` condition. A fetch whose retries were exhausted against the target used to answer
+  `503` with code `internal_error` and the message "Fetch service unavailable.", which read as an
+  outage of the API; it now answers `422` with code `blocked` when the target's bot protection
+  refused every attempt and `upstream_error` (message "Failed to fetch URL.") otherwise, and it is
+  still charged nothing. A client that matched that `503` must match `422` and the code instead;
+  the `503` `internal_error` remains only for a deployment whose fetch service endpoint or
+  internal token is not configured.
+  Doc comments only; no SDK signature moves.
+
 ## [0.11.2] - 2026-09-18
 
 ### Changed

package/dist/generated/api.d.ts

@@ -4110,9 +4110,31 @@ export interface operations {
                 };
             };
             402: components["responses"]["PaymentRequired"];
-            /** @description Validation error (e.g. slow-path-only field). */
+            /**
+             * @description Validation error (e.g. slow-path-only field), or a fetch that failed for a
+             *     target-side reason.
+             *
+             *     Two distinct conditions answer `422`. Read `error.code` to tell them apart.
+             *
+             *     - **`validation_error`** — the request itself was rejected.
+             *     - **`blocked`** or **`upstream_error`** — the fetch ran and the target could not
+             *       be read. `blocked` means the target's bot protection refused every attempt;
+             *       `upstream_error` (message `Failed to fetch URL.`) is any other exhausted-retries
+             *       failure, such as a host that does not resolve. This is a result about the URL,
+             *       not an outage of this API, so it is a `4xx` rather than `502` or `503`. No
+             *       upstream HTTP status was received, so `error.http_status` reports `422`,
+             *       mirroring what was served — unlike the relayed `upstream_error` under `502`
+             *       below, whose status is the target's own. The request transfers no billable
+             *       bytes and is charged nothing (#4669).
+             */
             422: {
                 headers: {
+                    /**
+                     * @description Optional; present only when the failed request was recorded. Names the failed
+                     *     row: it appears in Logs under the same hex, rendered `sc_<hex>` (`ft_` in this
+                     *     header, `sc_` in Logs).
+                     */
+                    "X-Fetch-ID": components["headers"]["XFetchID"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -4157,10 +4179,12 @@ export interface operations {
              *       the **true upstream status**, `502` — not `503` — and is the only surviving
              *       record of what the target answered, so the body rather than the HTTP status is
              *       authoritative here (#3355).
-             *     - **`internal_error`** (message `Fetch service unavailable.`) — the fetch service
-             *       could not be reached at all. There is no upstream status to preserve: the `503`
-             *       is this API's own choice of wire status, so the body's `error.http_status`
-             *       reports `503`, mirroring what was served (#3373).
+             *     - **`internal_error`** (message `Fetch service unavailable.`) — no fetch service
+             *       endpoint could be resolved on this deployment, a fault of this API and not of the
+             *       target. There is no upstream status to preserve: the `503` is this API's own
+             *       choice of wire status, so the body's `error.http_status` reports `503`, mirroring
+             *       what was served (#3373). A fetch that ran and failed for a target-side reason
+             *       answers `422` instead (#4669).
              */
             503: {
                 headers: {
@@ -4236,9 +4260,31 @@ export interface operations {
                 };
             };
             402: components["responses"]["PaymentRequired"];
-            /** @description Validation error (e.g. malformed JSON, unsupported fetch format, or slow-path-only field). */
+            /**
+             * @description Validation error (e.g. malformed JSON, unsupported fetch format, or slow-path-only
+             *     field), or a fetch that failed for a target-side reason.
+             *
+             *     Two distinct conditions answer `422`. Read `error.code` to tell them apart.
+             *
+             *     - **`validation_error`** — the request itself was rejected.
+             *     - **`blocked`** or **`upstream_error`** — the fetch ran and the target could not
+             *       be read. `blocked` means the target's bot protection refused every attempt;
+             *       `upstream_error` (message `Failed to fetch URL.`) is any other exhausted-retries
+             *       failure, such as a host that does not resolve. This is a result about the URL,
+             *       not an outage of this API, so it is a `4xx` rather than `502` or `503`. No
+             *       upstream HTTP status was received, so `error.http_status` reports `422`,
+             *       mirroring what was served — unlike the relayed `upstream_error` under `502`
+             *       below, whose status is the target's own. The request transfers no billable
+             *       bytes and is charged nothing (#4669).
+             */
             422: {
                 headers: {
+                    /**
+                     * @description Optional; present only when the failed request was recorded. Names the failed
+                     *     row: it appears in Logs under the same hex, rendered `sc_<hex>` (`ft_` in this
+                     *     header, `sc_` in Logs).
+                     */
+                    "X-Fetch-ID": components["headers"]["XFetchID"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -4283,10 +4329,12 @@ export interface operations {
              *       the **true upstream status**, `502` — not `503` — and is the only surviving
              *       record of what the target answered, so the body rather than the HTTP status is
              *       authoritative here (#3355).
-             *     - **`internal_error`** (message `Fetch service unavailable.`) — the fetch service
-             *       could not be reached at all. There is no upstream status to preserve: the `503`
-             *       is this API's own choice of wire status, so the body's `error.http_status`
-             *       reports `503`, mirroring what was served (#3373).
+             *     - **`internal_error`** (message `Fetch service unavailable.`) — no fetch service
+             *       endpoint could be resolved on this deployment, a fault of this API and not of the
+             *       target. There is no upstream status to preserve: the `503` is this API's own
+             *       choice of wire status, so the body's `error.http_status` reports `503`, mirroring
+             *       what was served (#3373). A fetch that ran and failed for a target-side reason
+             *       answers `422` instead (#4669).
              */
             503: {
                 headers: {

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export declare const SDK_VERSION = "0.11.2";
+export declare const SDK_VERSION = "0.11.4";

package/dist/version.js

@@ -9,4 +9,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export const SDK_VERSION = '0.11.2';
+export const SDK_VERSION = '0.11.4';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",