@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/dist/testing/run.js

@@ -1,19 +1,14 @@
 import { describe, expect, it } from "bun:test";
-import { createProviderCache } from "../runtime/cache";
-import { createTestProviderChoiceContext } from "../runtime/choice";
-import { createMemoryProviderRuntimeState } from "../runtime/state";
-import { createUnsupportedSttClient } from "../runtime/stt";
-import { safeParseSchemaSync } from "../schema";
+import { createProviderCache } from "../runtime/cache.js";
+import { createTestProviderChoiceContext } from "../runtime/choice.js";
+import { createMemoryProviderRuntimeState } from "../runtime/state.js";
+import { createUnsupportedSttClient } from "../runtime/stt.js";
+import { safeParseSchemaSync } from "../schema.js";
 // Mirrors CONNECTOR_ID_REGEX in ../define.ts, which defineProvider() enforces.
 // A single lowercase segment (no hyphen) is a valid id, so the trailing group
 // is optional (`*`), matching providers like `kakaomap`, `kstartup`, `triple`.
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
-const VALID_AUTH_MODES = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 function isFixtureEnvelope(value) {
     return (value !== null &&
@@ -60,21 +55,23 @@ function inferFixtureDir(providerId) {
         .map((line) => line.match(/\(?((?:file:\/\/)?[^():]+\.test\.ts)/)?.[1])
         .find((file) => file !== undefined);
     if (testFile) {
-        const pathname = testFile.startsWith("file://")
-            ? new URL(testFile).pathname
-            : testFile;
+        const pathname = testFile.startsWith("file://") ? new URL(testFile).pathname : testFile;
         return `${pathname.replace(/\/[^/]+$/, "")}/../__fixtures__`;
     }
     return `providers/${providerId}/__fixtures__`;
 }
 function jsonResponse(data) {
+    const body = JSON.stringify(data);
+    const bodyBytes = new TextEncoder().encode(body);
     return {
         status: 200,
         ok: true,
         headers: {},
         data,
         json: async () => JSON.parse(JSON.stringify(data)),
-        text: async () => JSON.stringify(data),
+        text: async () => body,
+        arrayBuffer: async () => bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength),
+        bytes: async () => bodyBytes.slice(0),
     };
 }
 function unsupported(name) {

package/dist/types.d.ts

@@ -268,8 +268,16 @@ export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
     interval: Iso8601Duration;
+    randomize?: HealthScheduleRandomization;
     jitter?: Iso8601Duration;
 }
+export type HealthScheduleRandomization = {
+    mode: "centered";
+    maxOffset: Iso8601Duration;
+} | {
+    mode: "delayed";
+    maxDelay: Iso8601Duration;
+};
 export interface HealthJourneyStep {
     id: string;
     description?: string;
@@ -511,6 +519,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
     /** Polling interval for the suite. All cases share this cadence. */
     interval: ProbeInterval;
+    schedule?: {
+        randomize?: HealthScheduleRandomization;
+    };
     /** Per-case timeout in milliseconds. Default: 30000. */
     timeoutMs?: number;
     /** Default degradation threshold for cases in this suite. Default: runtime threshold. */
@@ -583,6 +594,13 @@ export interface ProviderHealthMonitorConfig {
      */
     serviceAccount?: string;
 }
+/**
+ * New name for `ProviderHealthMonitorConfig` as part of the health dependency
+ * inversion (`healthMonitor` → `healthProbe`). Both provider-level fields are
+ * accepted transitionally with identical validation; declaring both is a
+ * `ValidationError`.
+ */
+export type ProviderHealthProbeConfig = ProviderHealthMonitorConfig;
 export interface HealthMonitorProbeOverride {
     /** Optional runtime interval override as a positive `ms`-style duration string. */
     interval?: ProbeInterval;
@@ -632,7 +650,25 @@ export type ConnectionMode = AuthMode;
 export type ProviderReviewed = "first-party" | "community" | "staging";
 export type ProviderAccessVisibility = "public" | "early_access";
 export type ProviderProxyMode = "disabled" | "optional" | "required";
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *   endpoints). This is our own vendor. It is NOT the company formerly named
+ *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *   credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *   username params. A different company from `smartproxy` above.
+ *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
 export interface ProviderProxyPolicy {
     /**
@@ -640,7 +676,18 @@ export interface ProviderProxyPolicy {
      * certificate verification, and vendor allocator endpoints are SDK-owned.
      */
     mode: ProviderProxyMode;
+    /**
+     * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+     * chain. A single-element `providers` list is equivalent to this field.
+     */
     provider?: ProviderProxyProvider;
+    /**
+     * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+     * fails over to the next when a vendor lacks credentials or its allocation /
+     * transport is exhausted. When omitted, `provider` (or the platform default)
+     * is used as a single-vendor chain.
+     */
+    providers?: ProviderProxyProvider[];
     geo?: {
         /** ISO 3166-1 alpha-2 country code, for example KR or US. */
         country?: Iso3166Alpha2CountryCode;
@@ -805,6 +852,7 @@ export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PU
 export interface StealthFetchOptions extends RequestOptions {
     method?: HttpMethod;
     body?: string | Buffer;
+    redirect?: "follow" | "manual" | "error";
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -829,9 +877,19 @@ export interface CookieJar {
     toString(): string;
     find?(predicate: (cookie: string) => boolean): string | undefined;
 }
+export interface StealthSessionCookies extends CookieJar {
+    has(name: string): boolean;
+    setFromCookieStrings(cookieStrings: readonly string[]): void;
+    toHeader(): string;
+    snapshot(): Record<string, string>;
+    restore(cookies: Record<string, string>): void;
+    clear(): void;
+}
 export interface DeclarativeStealthResponse {
     status: number;
     ok: boolean;
+    url?: string;
+    redirected?: boolean;
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
@@ -851,8 +909,30 @@ export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
 };
+export interface StealthRedirectHop {
+    url: string;
+    status: number;
+    method: string;
+    location?: string;
+    nextUrl?: string;
+}
+export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "redirect"> {
+    url: string;
+    maxHops?: number;
+    stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
+}
+export interface StealthRedirectRunResult {
+    final: StealthResponse;
+    hops: StealthRedirectHop[];
+    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    cookies: Record<string, string>;
+}
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    cookies: StealthSessionCookies;
+    redirects: {
+        run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
+    };
     close(): void;
 }
 export interface ApiFuseResponse<T> {
@@ -873,6 +953,8 @@ export interface HttpResponse<T = unknown> {
     data: T;
     json<U = T>(): Promise<U>;
     text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
 }
 export interface HttpStreamResponse {
     status: number;
@@ -983,6 +1065,32 @@ export interface BrowserFrame {
     evaluate<T>(fn: string | (() => T)): Promise<T>;
     locator(selector: string): BrowserLocator;
 }
+export type BrowserResourceMethod = "GET" | "HEAD";
+export type BrowserResourceRequest = {
+    readonly url: string;
+    readonly method: BrowserResourceMethod;
+    readonly resourceType?: string;
+    readonly headers: Readonly<Record<string, string>>;
+};
+export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
+export type BrowserResourceDecision = {
+    readonly action: "fulfill";
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: BrowserResourceBody;
+} | {
+    readonly action: "block";
+    readonly reason?: string;
+};
+export type BrowserResourceRoute = {
+    readonly match: string | RegExp | ((request: BrowserResourceRequest) => boolean);
+    readonly handle: (request: BrowserResourceRequest) => Promise<BrowserResourceDecision> | BrowserResourceDecision;
+};
+export type BrowserResourcePolicy = {
+    readonly defaultAction?: "block";
+    readonly allowedMethods?: readonly BrowserResourceMethod[];
+    readonly routes: readonly BrowserResourceRoute[];
+};
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
     fill(selector: string, text: string): Promise<void>;
@@ -997,6 +1105,7 @@ export interface BrowserPage extends BrowserFrame {
         timeout?: number;
     }): Promise<void>;
     frames(): Promise<BrowserFrame[]>;
+    withResourcePolicy<T>(policy: BrowserResourcePolicy, run: () => Promise<T>): Promise<T>;
 }
 export type BrowserChallengeRequest = {
     type: "recaptcha";
@@ -1137,6 +1246,73 @@ export interface ContextScratchpad {
     toJSON(): Record<string, unknown>;
 }
 export type FlowContextStore = ContextScratchpad;
+export type AuthSafeJson = string | number | boolean | null | readonly AuthSafeJson[] | {
+    readonly [key: string]: AuthSafeJson;
+};
+export type AuthSafeData = {
+    readonly [key: string]: AuthSafeJson;
+};
+export type AuthAbortRetry = "never" | "retry" | "after_user_action";
+export type AuthAbortData = Record<string, unknown> & {
+    readonly code: string;
+    readonly message?: string;
+    readonly retry?: AuthAbortRetry;
+    readonly actionHint?: AuthSafeJson;
+    readonly fieldErrors?: {
+        readonly [field: string]: string;
+    };
+    readonly details?: AuthSafeData;
+};
+export interface AuthFlowTerminalContext {
+    readonly signal?: AbortSignal;
+    readonly deadline?: string;
+    complete<TCredential extends Record<string, string>>(options: {
+        readonly credential: TCredential;
+        readonly metadata?: AuthSafeData;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+    }): AuthTurn;
+    abort(options: {
+        readonly code: string;
+        readonly message?: string;
+        readonly retry?: AuthAbortRetry;
+        readonly actionHint?: AuthSafeJson;
+        readonly fieldErrors?: {
+            readonly [field: string]: string;
+        };
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+    }): AuthTurn;
+    nextForm(options: {
+        readonly hintKey?: ProviderLocaleKeyInput;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+        readonly timing?: AuthTurn["timing"];
+    } & ({
+        readonly fields: Record<string, {
+            readonly type?: "string" | "email" | "password" | "otp";
+            readonly labelKey?: ProviderLocaleKeyInput;
+            readonly descriptionKey?: ProviderLocaleKeyInput;
+            readonly placeholderKey?: ProviderLocaleKeyInput;
+            readonly required?: boolean;
+            readonly sensitive?: boolean;
+        }>;
+        readonly expectedInput?: never;
+    } | {
+        readonly expectedInput: Record<string, unknown>;
+        readonly fields?: never;
+    })): AuthTurn;
+    nextPoll(options?: {
+        readonly hintKey?: ProviderLocaleKeyInput;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+        readonly timing?: AuthTurn["timing"];
+    }): AuthTurn;
+}
 export interface FlowContext {
     connectionId?: string;
     externalRef?: string;
@@ -1148,6 +1324,7 @@ export interface FlowContext {
     credential?: CredentialContext;
     context: ContextScratchpad;
     stt: SttContext;
+    auth: AuthFlowTerminalContext;
 }
 export interface AuthTurn {
     kind: string;
@@ -1270,6 +1447,19 @@ export interface OperationContractMetadata {
     deprecation?: OperationDeprecationMetadata;
 }
 export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
+    /**
+     * Short English display title for the operation. The SDK passes it through
+     * verbatim; the APIFuse registry derives the operation's en locale title
+     * baseline from it (`docs.titleKey` remains available as an explicit key
+     * override).
+     */
+    title?: string;
+    /**
+     * Raw English operation description. The SDK passes it through verbatim;
+     * keyed descriptions via `descriptionKey` remain the primary flow, and
+     * provider lint rules for raw prose descriptions still apply.
+     */
+    description?: string;
     descriptionKey?: ProviderLocaleKeyInput;
     docs?: OperationDocMeta;
     whenToUseKeys?: readonly ProviderLocaleKeyInput[];
@@ -1299,10 +1489,54 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     healthCheck?: HealthCheckSuite<InferSchemaOutput<TInput>, InferSchemaOutput<TOutput>>;
     healthCheckUnsupported?: HealthCheckUnsupported;
 }
+/**
+ * Author-declared deployment overrides accepted as the optional top-level
+ * `deployment` key on `defineProvider()`.
+ *
+ * The SDK passes this object through VERBATIM onto the returned provider
+ * definition — it is typed here but deliberately not deep-validated: the
+ * APIFuse registry builder owns deployment validation and resolves omitted
+ * fields against the runtime deployment profiles. The shape mirrors the
+ * registry's `ProviderDeploymentOverrides` contract; every field is
+ * optional. Note that the deployment `runtime` axis
+ * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
+ * `runtime` (`standard`/`shared`/`browser`).
+ */
+export interface ProviderDeploymentOverrides {
+    runtime?: "shared" | "dedicated" | "browser";
+    language?: "typescript" | "python";
+    replicas?: number;
+    hpa?: {
+        enabled: boolean;
+        minReplicas?: number;
+        maxReplicas?: number;
+        targetCPUUtilizationPercentage?: number;
+    };
+    resources?: {
+        cpu: string;
+        memory: string;
+    };
+    cache?: {
+        redis?: {
+            enabled: boolean;
+            url?: string;
+        };
+    };
+    network?: {
+        additionalTcpPorts?: number[];
+    };
+    buildContext?: string;
+}
 export interface ProviderDefinition {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * Optional deployment overrides, passed through verbatim from
+     * `defineProvider({ deployment })`. Validation and profile resolution are
+     * owned by the APIFuse registry builder, not the SDK.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
     stealth?: {
         profile: string;
@@ -1322,5 +1556,7 @@ export interface ProviderDefinition {
     meta: ProviderMeta;
     operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
     healthMonitor?: ProviderHealthMonitorConfig;
+    /** Transitional alias for `healthMonitor`; `defineProvider` mirrors both. */
+    healthProbe?: ProviderHealthProbeConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }

package/dist/user-input.d.ts

@@ -0,0 +1,30 @@
+export declare const NEEDS_INPUT_STATUS: "needs_input";
+export interface ProviderSelectionOption {
+    readonly selection_value: string;
+    readonly label: string;
+    readonly [extra: string]: unknown;
+}
+export interface ProviderRequiredSelection {
+    readonly selection_key: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly selection_type?: string;
+    readonly valid_options: readonly ProviderSelectionOption[];
+    readonly [extra: string]: unknown;
+}
+export interface ProviderSelectedOption {
+    readonly selection_key: string;
+    readonly selection_value: string;
+    /** Free-text answer for text-kind selections. */
+    readonly text?: string;
+    /** Quantity for quantity-kind selections. */
+    readonly quantity?: number;
+}
+export interface ProviderNeedsInputPayload {
+    readonly status: typeof NEEDS_INPUT_STATUS;
+    readonly required_selections: readonly ProviderRequiredSelection[];
+    readonly selected_options?: readonly ProviderSelectedOption[];
+    /** Provider-specific fresh state token(s), e.g. `reservation_state`. */
+    readonly [extra: string]: unknown;
+}
+export declare function isProviderNeedsInputPayload(value: unknown): value is ProviderNeedsInputPayload;

package/dist/user-input.js

@@ -0,0 +1,66 @@
+// Official cross-provider contract for user-input round-trips.
+//
+// Doctrine (born from the 2026-07-20 CatchTable reserve incident): an
+// operation MUST NOT dead-end on a problem the end user can resolve by
+// choosing among live options. Instead of throwing, the provider returns a
+// SUCCESSFUL payload with `status: "needs_input"` that carries everything a
+// consumer-side agent needs to relay the choice verbatim and retry:
+//
+// - `required_selections`: only the still-pending questions, each with
+//   human-readable `label`s and `valid_options` the agent shows the user
+//   as-is. The agent never chooses on the user's behalf.
+// - `selected_options`: selections already settled, echoed so the follow-up
+//   call keeps them without the agent reconstructing anything.
+// - a fresh provider-specific state token (e.g. `reservation_state`) minted
+//   at response time, so the retry never races an expired token.
+//
+// Keeping this success-shaped (instead of error `details`) is deliberate:
+// consumer error-shaping layers routinely strip error metadata, and a model
+// that only sees "error" narrates failure to the user. Complex recovery
+// logic belongs to the system, not the model.
+//
+// Deliberately ABSENT: retry templates, next-action routing, or any other
+// agent choreography. Provider payloads carry upstream-backed data only; how
+// to phrase the ask and shape the retry call is the consumer's contract
+// (apifuse#1030). The retry is fully determined by data: copy the echoed
+// selected_options, add the user's new answers, resend with the fresh state.
+export const NEEDS_INPUT_STATUS = "needs_input";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSelectionOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_value === "string" &&
+        typeof value.label === "string");
+}
+function isRequiredSelection(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.label === "string" &&
+        typeof value.required === "boolean" &&
+        Array.isArray(value.valid_options) &&
+        value.valid_options.every(isSelectionOption));
+}
+function isSelectedOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.selection_value === "string");
+}
+export function isProviderNeedsInputPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.status !== NEEDS_INPUT_STATUS ||
+        !Array.isArray(value.required_selections) ||
+        !value.required_selections.every(isRequiredSelection)) {
+        return false;
+    }
+    // A needs_input with nothing to ask AND nothing settled to echo is a
+    // no-op dead end — reject it so providers cannot ship it accidentally.
+    if (value.required_selections.length > 0) {
+        return true;
+    }
+    return (Array.isArray(value.selected_options) &&
+        value.selected_options.length > 0 &&
+        value.selected_options.every(isSelectedOption));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
+	"version": "2.2.0-beta.10",
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.9",
 	"private": false,
 	"type": "module",
 	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
@@ -50,6 +50,12 @@
 			"import": "./dist/contract.js",
 			"default": "./dist/contract.js"
 		},
+		"./auth-turn": {
+			"types": "./dist/auth-turn/index.d.ts",
+			"import": "./dist/auth-turn/index.js",
+			"default": "./dist/auth-turn/index.js"
+		},
+		"./auth-turn/auth-turn.v1.schema.json": "./dist/auth-turn/auth-turn.v1.schema.json",
 		"./server": {
 			"types": "./dist/server/index.d.ts",
 			"import": "./dist/server/index.js",
@@ -69,25 +75,30 @@
 	"scripts": {
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
+		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
 		"format": "biome format --write",
-		"type-check": "tsgo --noEmit",
+		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
+		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
 		"release:guard": "bun scripts/guard-release-pr.ts",
 		"format:check": "biome format .",
-		"build": "tsgo -p tsconfig.build.json"
+		"build": "tsc -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"@typescript/native-preview": "7.0.0-dev.20260419.1"
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
+		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
+		"acorn": "^8.17.0",
 		"ajv": "^8.17",
 		"hono": "^4.12.25",
 		"impit": "0.14.1",

package/src/auth-turn/auth-turn.v1.schema.json

@@ -0,0 +1,89 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://apifuse.com/contracts/auth-turn/v1",
+	"title": "APIFuse AuthTurn envelope v1",
+	"description": "Protocol message exchanged during auth.flow ceremonies. kind is an open string; known kinds are tooling metadata, not a wire constraint.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["kind", "turnId"],
+	"properties": {
+		"kind": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Open turn kind. Known kinds are listed in the TURN_KINDS registry; unknown kinds remain valid on the wire."
+		},
+		"turnId": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Provider-scoped identifier of this turn."
+		},
+		"expiresAt": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Turn expiry timestamp as an ISO 8601 / RFC 3339 string."
+		},
+		"data": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "Kind-specific payload. Terminal kinds carry the payloads described in $defs."
+		},
+		"expectedInput": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "JSON Schema describing the input expected next."
+		},
+		"hint": {
+			"type": "string",
+			"description": "Deprecated but load-bearing human-readable hint materialized from provider locale catalogs."
+		},
+		"hintKey": {
+			"type": "string",
+			"description": "Provider locale catalog key for the turn hint."
+		},
+		"timing": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Client pacing guidance for poll-style turns.",
+			"properties": {
+				"suggestedPollIntervalMs": {
+					"type": "number",
+					"minimum": 1
+				},
+				"maxWaitMs": {
+					"type": "number",
+					"minimum": 1
+				}
+			}
+		}
+	},
+	"$defs": {
+		"completeTurnData": {
+			"title": "Terminal payload for kind \"complete\"",
+			"description": "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.",
+			"type": "object",
+			"additionalProperties": true,
+			"required": ["credential"],
+			"properties": {
+				"credential": {
+					"type": "object",
+					"additionalProperties": true
+				},
+				"metadata": {
+					"type": "object",
+					"additionalProperties": true
+				}
+			}
+		},
+		"abortTurnData": {
+			"title": "Terminal payload for kind \"abort\"",
+			"description": "data payload of an abort turn. code, when present, is the machine-readable abort reason.",
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"code": {
+					"type": "string"
+				}
+			}
+		}
+	}
+}

package/src/auth-turn/fixtures/invalid/empty-kind.json

@@ -0,0 +1,4 @@
+{
+	"kind": "",
+	"turnId": "fixture.invalid.empty-kind"
+}

package/src/auth-turn/fixtures/invalid/expires-at-not-string.json

@@ -0,0 +1,5 @@
+{
+	"kind": "challenge",
+	"turnId": "fixture.invalid.expires-at-not-string",
+	"expiresAt": 1767225600000
+}

package/src/auth-turn/fixtures/invalid/missing-kind.json

@@ -0,0 +1,3 @@
+{
+	"turnId": "fixture.invalid.missing-kind"
+}

package/src/auth-turn/fixtures/invalid/missing-turn-id.json

@@ -0,0 +1,3 @@
+{
+	"kind": "form"
+}