@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/stateful-signing.d.ts

@@ -0,0 +1,18 @@
+export declare const STATEFUL_SIGNATURE_HEADER = "x-apifuse-stateful-signature";
+export declare const STATEFUL_TIMESTAMP_HEADER = "x-apifuse-stateful-timestamp";
+export declare const STATEFUL_NONCE_HEADER = "x-apifuse-stateful-nonce";
+export type StatefulSigningInput = {
+    readonly secret: string;
+    readonly timestamp: string;
+    readonly rawBody: string;
+    readonly method: string;
+    readonly path: string;
+    readonly nonce: string;
+};
+export declare function signStatefulRequestBody(input: StatefulSigningInput): string;
+export declare function verifyStatefulRequestSignature(input: StatefulSigningInput & {
+    readonly signature: string;
+}): boolean;
+export declare function statefulSignedHeaders(input: Omit<StatefulSigningInput, "nonce"> & {
+    readonly nonce?: string;
+}): Record<string, string>;

package/dist/stateful-signing.js

@@ -0,0 +1,27 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+export const STATEFUL_SIGNATURE_HEADER = "x-apifuse-stateful-signature";
+export const STATEFUL_TIMESTAMP_HEADER = "x-apifuse-stateful-timestamp";
+export const STATEFUL_NONCE_HEADER = "x-apifuse-stateful-nonce";
+export function signStatefulRequestBody(input) {
+    return `v1=${createHmac("sha256", input.secret)
+        .update(`v1:${input.method.toUpperCase()}:${input.path}:${input.timestamp}:${input.nonce}.${input.rawBody}`)
+        .digest("hex")}`;
+}
+export function verifyStatefulRequestSignature(input) {
+    return safeEqualAscii(input.signature, signStatefulRequestBody(input));
+}
+export function statefulSignedHeaders(input) {
+    const nonce = input.nonce ?? randomUUID();
+    return {
+        [STATEFUL_SIGNATURE_HEADER]: signStatefulRequestBody({ ...input, nonce }),
+        [STATEFUL_TIMESTAMP_HEADER]: input.timestamp,
+        [STATEFUL_NONCE_HEADER]: nonce,
+    };
+}
+function safeEqualAscii(actual, expected) {
+    const actualBytes = Buffer.from(actual);
+    const expectedBytes = Buffer.from(expected);
+    if (actualBytes.byteLength !== expectedBytes.byteLength)
+        return false;
+    return timingSafeEqual(actualBytes, expectedBytes);
+}

package/dist/stealth/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { StealthProfile } from "../types";
+import type { StealthProfile } from "../types.js";
 export declare function generateLayer2Headers(profile: StealthProfile): Record<string, string>;
 export declare function getStealthProfile(name: string): StealthProfile;
 export declare function listStealthProfiles(): string[];

package/dist/stealth/profiles.js

@@ -1,4 +1,4 @@
-import { SDKError } from "../errors";
+import { SDKError } from "../errors.js";
 const CHROMIUM_HEADER_ORDER = [
     ":method",
     ":authority",
@@ -74,12 +74,8 @@ function createProfile(name, definition) {
         tlsClientIdentifier: definition.tlsClientIdentifier,
         ja3: definition.ja3,
         ja4: definition.ja4,
-        h2Settings: definition.h2Settings
-            ? { ...definition.h2Settings }
-            : undefined,
-        headerOrder: definition.headerOrder
-            ? [...definition.headerOrder]
-            : undefined,
+        h2Settings: definition.h2Settings ? { ...definition.h2Settings } : undefined,
+        headerOrder: definition.headerOrder ? [...definition.headerOrder] : undefined,
     };
 }
 function extractBrowserMajorVersion(profile) {
@@ -120,9 +116,7 @@ export function generateLayer2Headers(profile) {
             : `"Chromium";v="${majorVersion}", "Google Chrome";v="${majorVersion}", "Not)A;Brand";v="99"`;
         headers["Sec-Ch-Ua-Platform"] = toPlatformHeaderValue(profile.platform);
         headers["Sec-Ch-Ua-Mobile"] =
-            profile.platform === "android" || profile.platform === "ios"
-                ? "?1"
-                : "?0";
+            profile.platform === "android" || profile.platform === "ios" ? "?1" : "?0";
     }
     return headers;
 }
@@ -252,8 +246,5 @@ export function getStealthProfile(name) {
     };
 }
 export function listStealthProfiles() {
-    return [
-        ...Object.keys(STEALTH_PROFILES),
-        ...Object.keys(STEALTH_PROFILE_ALIASES),
-    ];
+    return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
 }

package/dist/stream.d.ts

@@ -1,4 +1,4 @@
-import type { SseMessage } from "./types";
+import type { SseMessage } from "./types.js";
 export interface SseEvent<TData = unknown> {
     event: string;
     data: TData;

package/dist/testing/index.d.ts

@@ -1,2 +1,2 @@
-export { describeTransform, snapshotTransform, toMatchShape } from "./helpers";
-export { runStandardTests } from "./run";
+export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { runStandardTests } from "./run.js";

package/dist/testing/index.js

@@ -1,2 +1,2 @@
-export { describeTransform, snapshotTransform, toMatchShape } from "./helpers";
-export { runStandardTests } from "./run";
+export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { runStandardTests } from "./run.js";

package/dist/testing/run.d.ts

@@ -1,4 +1,4 @@
-import type { AuthMode, ProviderDefinition } from "../types";
+import type { AuthMode, ProviderDefinition } from "../types.js";
 export interface StandardTestsManifest {
     id?: string;
     displayName?: string;

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,9 +55,7 @@ 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__`;

package/dist/types.d.ts

@@ -650,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 {
     /**
@@ -658,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;
@@ -1418,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[];
@@ -1447,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;

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,5 +1,5 @@
 {
-	"version": "2.2.0-beta.1",
+	"version": "2.2.0-beta.11",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -61,6 +61,11 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./stateful": {
+			"types": "./dist/stateful/index.d.ts",
+			"import": "./dist/stateful/index.js",
+			"default": "./dist/stateful/index.js"
+		},
 		"./testing": {
 			"types": "./dist/testing/index.d.ts",
 			"import": "./dist/testing/index.js",
@@ -75,24 +80,28 @@
 	"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 && 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"
+		"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",

package/src/auth-turn/index.ts

@@ -1,4 +1,4 @@
-import type { AuthTurn } from "../types";
+import type { AuthTurn } from "../types.js";
 
 export type { AuthTurn };