@hunt-labs/bytekit-sdk 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -8,6 +8,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This file records only the delta between versions. For how to use the package
 today, see [README.md](./README.md), which remains the authoritative usage guide.
 
+## [0.7.0] - 2026-08-11
+
+### Added
+
+- **Every outbound request now carries `X-ByteKit-Client: sdk_ts/<version>`.** The SDK identifies
+  itself with the sanctioned `client_surface` marker (issue #2905, slice 2 of #2701), so requests
+  made through `@hunt-labs/bytekit-sdk` are distinguishable from raw API calls in ByteKit's own
+  analytics instead of all resolving to `api_direct`. `sdk_ts` is a member of the closed
+  `client_surface` vocabulary declared in issue #2904; the version affix is this package's own
+  version, baked in at build time from `package.json`.
+
+  Set at exactly ONE place — the header literal inside the private transport every request funnels
+  through — so it rides on the JSON path, the raw `/v1/fetch` path and every resource method
+  alike. **Nothing else about a request changed:** same `Authorization` and `Content-Type`, same
+  body bytes, same client-side abort budget, same error taxonomy, same return shapes. The marker
+  carries no caller data and cannot be set, overridden or read by callers — there is no
+  `headers` option on `ByteKitOptions` or `RequestOptions`.
+
+  Minor rather than patch because the wire format of every request changes, even though no
+  documented API does. A gateway that does not yet recognize the header ignores it.
+
+- `SDK_VERSION` — an internal, build-time-generated constant (`src/version.ts`, written by
+  `pnpm gen:version` from `package.json` and gated by `src/__tests__/version-parity.test.ts`).
+  It backs the marker's version affix. **Not part of the public export surface**;
+  `package.json`'s `version` field remains the only version consumers should read.
+
+### Unchanged
+
+- **Still ZERO runtime dependencies.** The `client_surface` vocabulary lives in an internal,
+  unpublished workspace package, so the emitted value is a string literal here and the binding to
+  that registry is a test-only import. `dependencies` stays empty, asserted by
+  `src/__tests__/package-manifest.test.ts`.
+
+## [0.6.2] - 2026-08-11 [NEVER PUBLISHED]
+
+**This version was cut but NEVER PUBLISHED — npm `latest` went from 0.6.1 straight to 0.7.0.**
+The two documentation/regeneration changes below reached consumers in the **0.7.0** artifact,
+which contains all of them. Nothing under this heading is missing from 0.7.0, and nothing is
+installable at 0.6.2: `npm i @hunt-labs/bytekit-sdk@0.6.2` fails.
+
+Why it was stranded: 0.6.2 was cut for two `src/generated/api.d.ts` regenerations, and the next
+change (issue #2905's new outbound request header) altered the wire format of every request —
+additive behavior that belongs at a MINOR, not a patch. Folding it into the still-unpublished
+0.6.2 would have shipped a new request header to consumers pinning `^0.6.1` unannounced, so 0.7.0
+was cut instead and this heading annotated per `ci/scripts/check-release-drift.sh`'s
+reconciliation form (#2680).
+
+### Documentation
+
+- **`AccountSessionResponse.has_activity` now documents what it actually means.** The generated
+  type's JSDoc previously said the flag was true once the account had "ever recorded billable
+  activity", which read as "ever made a request". It is true only once a request has
+  **successfully completed and been charged credits** — a request that failed does not flip it,
+  even when its bandwidth was billed (issue #2890). The doc comment also now states the
+  all-time (never windowed) scope and the up-to-one-rollup lag, so a caller polling it after a
+  first request knows `false` can mean "not visible yet" rather than "never made a request".
+  Regenerated from `docs/api/openapi.yaml`; the emitted TYPE is unchanged
+  (`has_activity: boolean`), so this release is source-compatible in both directions.
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` from `docs/api/openapi.yaml` after issue #2904 declared the
+  optional `X-ByteKit-Client` request header as `components.parameters.ClientSurfaceMarker`. The
+  regeneration is ADDITIVE and touches no method signature: one entry appears under
+  `components["parameters"]`, because the parameter is deliberately `$ref`-ed from no operation.
+  **No consumer-visible change** — no exported function, type or runtime behavior differs from
+  0.6.1. The entry exists because `check-release-drift` (#2680) requires a version bump for any
+  post-release change to a shipped file, and the publish pipeline is version-gated.
+
+  Documented under 0.6.2 alongside the #2890 regeneration above, rather than under a 0.6.3 of its
+  own, because 0.6.2 has been CUT BUT NOT PUBLISHED (npm `latest` is 0.6.1). Both regenerations
+  therefore ship in the same single artifact. Numbering this 0.6.3 would leave 0.6.2 documented and
+  unpublishable — the version-gated pipeline would publish 0.6.3 and skip it — which is precisely
+  the phantom-version class #2680 exists to kill, and `check-release-drift` rejects it by name.
+
 ## [0.6.1] - 2026-08-10
 
 ### Changed

package/dist/client.js

@@ -8,6 +8,7 @@ import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
 import { UsageResource } from './resources/usage.js';
 import { WebhooksResource } from './resources/webhooks.js';
+import { SDK_VERSION } from './version.js';
 const DEFAULT_BASE_URL = 'https://api.bytekit.com';
 /**
  * Default client-side request timeout (2 minutes).
@@ -362,6 +363,20 @@ export class ByteKit {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`,
                 'Content-Type': 'application/json',
+                // The client_surface marker (issue #2905, slice 2 of #2701). Its NAME is
+                // `CLIENT_SURFACE_HEADER` and its `<surface>/<version>` shape and closed vocabulary
+                // `CLIENT_SURFACES` are declared in `@bytekit/analytics-contract` — deliberately
+                // spelled as literals HERE and not imported, because this package publishes with ZERO
+                // runtime dependencies and a `workspace:*` dependency on that private, unpublished
+                // package would break the published artifact. The binding to the registry is a
+                // TEST-ONLY import, in `client-surface-marker.test.ts`.
+                //
+                // This is the SINGLE emit site by construction: `send()` is the one transport both
+                // `request()` and `requestRaw()` funnel through, so a per-resource or per-method emit
+                // would be a duplicate rather than a completeness fix (#2905 E4). The ticket's pre-merge
+                // gate 1 counts occurrences of the header name in non-test `src/` and expects exactly
+                // one — the line below — which is why the prose above names the constant instead.
+                'X-ByteKit-Client': `sdk_ts/${SDK_VERSION}`,
             },
         };
         if (body !== undefined) {

package/dist/generated/api.d.ts

@@ -2495,7 +2495,7 @@ export interface components {
             terms_version: string;
             /** Format: date-time */
             created_at: string;
-            /** @description True once the account has ever recorded billable activity (any successful scrape/screenshot/fetch/… request, regardless of whether it was authenticated with a Clerk session or an API key). Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. */
+            /** @description True once the account has SUCCESSFULLY COMPLETED at least one billable request (a scrape/screenshot/fetch/… that settled and was charged credits), regardless of whether it was authenticated with a Clerk session or an API key. All-time — never windowed. A request that failed does not flip it, even when its bandwidth was billed: the monitor terminal-preflight-failure path records bytes without credits, and only the credited settlement counts here. Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. Lags by up to one usage rollup: the completion service writes the row after the response is returned, so a just-completed first request may still read false for a moment. Treat that as "not visible yet", never as "this account has never made a request". */
             has_activity: boolean;
         };
         /** @description Partial update payload for PATCH /v1/account. All fields are optional; at least one of name, email, or notifications must be provided. */
@@ -2551,6 +2551,22 @@ export interface components {
     };
     responses: never;
     parameters: {
+        /**
+         * @description Optional. Identifies which published ByteKit client sent the request, as
+         *     `<surface>/<version>`. The surface comes from a closed set — `api_direct`, `sdk_ts`,
+         *     `sdk_python`, `cli`, `mcp` — and the version affix is the emitting client's own version.
+         *
+         *     You do not need to send this. ByteKit's own clients set it for you, and a request that
+         *     omits it is authenticated, rate-limited, quota-checked, billed and answered exactly as one
+         *     that sends it. Requests without the header are attributed to `api_direct`.
+         *
+         *     A header that is absent, unrecognized or malformed is attributed to `api_direct` and the
+         *     value you sent is discarded — never stored and never logged. The header never changes how a
+         *     request is routed, priced or prioritised, and `User-Agent` is never used as a substitute
+         *     for it.
+         * @example sdk_ts/1.4.0
+         */
+        ClientSurfaceMarker: string;
         FetchUrl: string;
         FetchFormat: "markdown" | "html";
         FetchCountry: string;

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The published version of `@hunt-labs/bytekit-sdk`, baked in at build time.
+ *
+ * Used for the version affix of the client-surface marker (`sdk_ts/<version>`) that every
+ * 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.7.0";

package/dist/version.js

@@ -0,0 +1,12 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerate with `pnpm --filter @hunt-labs/bytekit-sdk gen:version` (also chained into `build`).
+// Source of truth: this package's `package.json` "version" field.
+// Guarded by `src/__tests__/version-parity.test.ts` (issue #2905, failure mode E5).
+/**
+ * The published version of `@hunt-labs/bytekit-sdk`, baked in at build time.
+ *
+ * Used for the version affix of the client-surface marker (`sdk_ts/<version>`) that every
+ * 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.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",
@@ -48,8 +48,9 @@
     "url": "https://bytekit.com/contact"
   },
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/api.d.ts dist/generated/api.d.ts",
+    "build": "pnpm gen:version && rm -rf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/api.d.ts dist/generated/api.d.ts",
     "gen:types": "openapi-typescript ../../docs/api/openapi.yaml -o src/generated/api.d.ts",
+    "gen:version": "tsx scripts/gen-version.ts",
     "gen:types-check": "pnpm gen:types && git diff --exit-code src/generated/api.d.ts",
     "generate:docs": "tsx scripts/generate-docs.ts",
     "typecheck": "tsc --noEmit",