@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.64

package/dist/cli/migrate-provider-shape.d.ts

@@ -24,7 +24,11 @@ export type ProviderShapeKind =
 "single-phase-default-export"
 /** `const p = defineProvider({ ..., operations }); export default p;` */
  | "single-phase-variable-export"
-/** `const p = defineProvider({ ..., operations }); export default { ...p, deployment };` */
+/**
+ * `const p = defineProvider({ ..., operations }); export default { ...p, extra };`
+ * — extras stay on the spread export; a `deployment` extra is a legacy
+ * surface that `apifuse migrate-deployment` hoists into the declaration.
+ */
  | "single-phase-variable-spread-export"
 /** Already `const b = defineProvider(...); export default b({ operations })` */
  | "two-phase";

package/dist/cli/migrate-provider-shape.js

@@ -218,7 +218,7 @@ function defaultExportCallsBuilder(exportAssignment, declarationCall) {
  * resolves to a builder-call result. Covers the three migrated layouts —
  * `export default buildProvider({...})`, an intermediate
  * `const provider = buildProvider({...}); export default provider;`, and the
- * spread export `export default { ...provider, deployment }` over such a
+ * spread export `export default { ...provider, ...extras }` over such a
  * binding. Without the latter two, re-running the transform on its own
  * spread-shape output reports "ambiguous" instead of "unchanged", which
  * breaks idempotency for repeated fan-out runs.
@@ -376,7 +376,9 @@ function rewriteDefaultExport(source, exportAssignment, shape, builderName, oper
         ];
     }
     // Spread export: re-introduce the provider binding so the extra properties
-    // (currently `deployment`) still spread over a built provider.
+    // (e.g. `healthAccountSeedInputs`, or a legacy `deployment` that
+    // `apifuse migrate-deployment` later hoists) still spread over a built
+    // provider.
     const providerName = shape.variableName ?? "provider";
     const extras = shape.spreadExportExtras ?? "";
     const rebuilt = extras.length > 0

package/dist/cli/resolver-runtime.d.ts

@@ -0,0 +1,21 @@
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import type { ProviderCache, ProviderDefinition, ResolverContext } from "../types.js";
+export interface CliResolverRuntime {
+    readonly resolver: ResolverContext;
+    /** Per-context sink; `toLogPayload()` is the `resolver` sibling of the server request log. */
+    readonly resolverTelemetry: ResolverTelemetryCollector;
+    /**
+     * Extend the collector's redaction with values learned after construction (request-scoped
+     * `sensitiveParams` the recorder captures); the collector redacts at record time, before it
+     * truncates, so values must be registered before the vendor call that may echo them.
+     */
+    readonly registerSensitiveValues: (values: readonly string[]) => void;
+}
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export declare function createCliResolverRuntime(provider: ProviderDefinition, cache: ProviderCache): CliResolverRuntime;

package/dist/cli/resolver-runtime.js

@@ -0,0 +1,31 @@
+import { compileProcessDiagnosticSensitiveValues, createDiagnosticRedactor, } from "../runtime/diagnostic-redactor.js";
+import { createResolverClientFromEnv, createUnsupportedResolverClient, } from "../runtime/resolver.js";
+import { createResolverRuntimeOptions, resolveNativeProxyPolicy, } from "../runtime/resolver-runtime-options.js";
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import { collectStaticDiagnosticSensitiveValues } from "../server/sensitive-values.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export function createCliResolverRuntime(provider, cache) {
+    const sensitiveValues = createDiagnosticRedactor([], compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider)));
+    const resolverTelemetry = new ResolverTelemetryCollector({ redact: sensitiveValues.redact });
+    const registerSensitiveValues = (values) => sensitiveValues.add(values);
+    if (!provider.resolver) {
+        return {
+            resolver: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+            resolverTelemetry,
+            registerSensitiveValues,
+        };
+    }
+    const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+    return {
+        resolver: createResolverClientFromEnv(provider.resolver, process.env, createResolverRuntimeOptions(provider, cache, undefined, resolveNativeProxyPolicy(provider), { upstream: { proxy: provider.proxy } }, stealthProfile, resolverTelemetry)),
+        resolverTelemetry,
+        registerSensitiveValues,
+    };
+}

package/dist/define.d.ts

@@ -54,6 +54,9 @@ export interface ProviderDeclaration {
      * provider definition. The SDK types this field but does not deep-validate
      * it — the APIFuse registry builder owns deployment validation and
      * resolves omitted fields against the runtime deployment profiles.
+     *
+     * This is the only authored deployment surface (no standalone
+     * `deploy.ts`); declare only the fields that differ from the profile.
      */
     deployment?: ProviderDeploymentOverrides;
     /** Declares the HTTP capability binding. A bare object states use without configuration. */

package/dist/define.js

@@ -636,6 +636,11 @@ function validateProviderImplementationShape(config) {
 }
 function validateProviderProxy(config) {
     for (const secret of config.secrets ?? []) {
+        if (secret.issuer !== undefined &&
+            secret.issuer !== "apifuse" &&
+            secret.issuer !== "contributor") {
+            throw new ValidationError(`Provider "${config.id}" secret "${secret.name}" has invalid issuer "${String(secret.issuer)}"`, { fix: `Set issuer to "apifuse" or "contributor", or omit it.` });
+        }
         const engineName = engineOwnedResolverCredentialTarget(secret.name);
         if (engineName !== undefined) {
             throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`, {

package/dist/dev.d.ts

@@ -1,10 +1,12 @@
-import type { ProviderEngine } from "./engine.js";
+import type { ProviderEngine, ProviderEngineMode } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 export interface DevServerOptions {
     port?: number;
     sessionDbPath?: string;
     /** Override the default in-process engine attachment. */
     engine?: ProviderEngine;
+    /** Explicit engine mode; `APIFUSE__ENGINE__MODE` outranks it when both are set. */
+    engineMode?: ProviderEngineMode;
 }
 export declare function createDevServer(provider: ProviderDefinition, options?: DevServerOptions): {
     start: () => void;

package/dist/dev.js

@@ -5,7 +5,12 @@ export function createDevServer(provider, options) {
         start: () => {
             // Local development has no Redis by default; handles (ADR-0012) need a
             // state backend, so fall back to memory state when none is configured.
-            void serve(provider, { port, engine: options?.engine, allowMemoryStateFallback: true });
+            void serve(provider, {
+                port,
+                engine: options?.engine,
+                engineMode: options?.engineMode,
+                allowMemoryStateFallback: true,
+            });
             console.log(`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -2,6 +2,25 @@ import type { HandleContext } from "./handle.js";
 import type { AuthContext, BrowserClient, CredentialContext, EnvContext, HttpClient, NativeContext, OcrContext, ProviderCache, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRequestContext, ProviderRuntimeState, ResolverContext, StealthClient, SttContext, TraceContext } from "./types.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export declare const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
+/**
+ * How a provider process attaches its capability bindings: `"in-process"` today,
+ * `"remote"` for the authenticated engine (ADR-0011).
+ *
+ * The union is intentionally open so further lanes (for example a provider hosted
+ * inside the engine) can be named without a breaking change. Unknown values are
+ * rejected at runtime, not by the type.
+ */
+export type ProviderEngineMode = "in-process" | "remote" | (string & {});
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
 export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
@@ -89,7 +108,22 @@ export interface ProviderEngineAttachmentInput {
 }
 /** Attachment boundary shared by in-process development and remote RPC bridges. */
 export interface ProviderEngine {
+    /**
+     * Which attachment this engine performs. Lets the server report a truthful
+     * mode at boot and compare an explicit engine object against a requested
+     * `engineMode`; omit for opaque host engines (reported as `custom`).
+     */
+    readonly kind?: ProviderEngineMode;
     attach<TDeclaration extends object = Record<string, unknown>>(input: ProviderEngineAttachmentInput): ProviderContext<TDeclaration>;
 }
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
 export declare function createInProcessProviderEngine(): ProviderEngine;

package/dist/engine.js

@@ -4,6 +4,16 @@ import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__AP
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, } from "./runtime/otlp.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
     "APIFUSE__PROXY__SMARTPROXY_APP_KEY",
@@ -184,7 +194,16 @@ function attachInProcess(input) {
         },
     });
 }
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
 export function createInProcessProviderEngine() {
-    return { attach: attachInProcess };
+    return { kind: "in-process", attach: attachInProcess };
 }

package/dist/error-resolution.d.ts

@@ -2,3 +2,4 @@ import type { ProviderErrorStatus } from "./types.js";
 export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
 export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
 export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;
+export declare const SDK_CANONICAL_ERROR_CODE_RETRYABILITY: ReadonlyMap<string, boolean>;

package/dist/error-resolution.js

@@ -18,6 +18,14 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "refresh_not_supported",
     "RUNTIME_UNSUPPORTED",
     "PROVIDER_STATE_UNSUPPORTED",
+    // Engine attachment (ADR-0011). Registered here so an engine failure is served
+    // as a known SDK code instead of raising a false
+    // `unregistered_provider_error_code` signal on a 500.
+    "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+    "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+    "PROVIDER_ENGINE_UNAVAILABLE",
+    "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+    "PROVIDER_EGRESS_DENIED",
     "HANDLE_INVALID",
     "HANDLE_NOT_FOUND",
     "HANDLE_EXPIRED",
@@ -57,6 +65,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "http_redirect_missing_location",
     "http_redirect_loop",
     "transport_invalid_url",
+    "http_header_factory_failed",
     "EGRESS_LEASE_INVALID",
     "EGRESS_LEASE_BINDING_INVALID",
     "EGRESS_LEASE_KEY_MISSING",
@@ -84,6 +93,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
     "STATEFUL_FORWARDING_REQUEST_FAILED",
     "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_CONTEXT_INVALID",
     "STATEFUL_FORWARDING_BAD_RESPONSE",
     "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
     "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
@@ -144,9 +154,53 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
     ["HANDLE_BUSY", 409],
     ["UPSTREAM_ERROR", 502],
     ["BLOCKED", 502],
+    // Fleet-consensus provider codes. These are thrown by provider code, not
+    // by the SDK, so they are registered here (status mapping) and not in
+    // SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+    // exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+    // them stops the fleet from re-declaring the same three rows on every
+    // operation, and stops an undeclared throw from being served as 500.
+    //
+    // A platform-managed upstream service key the upstream refuses. With
+    // `auth.mode: "platform-managed"` the caller holds no credential, so 401
+    // ("re-authenticate") tells the caller to do something it cannot do, and
+    // 502 ("upstream is sick") promises a recovery that will never come. It is
+    // a deployment/config defect — the same class as MISSING_SECRET above,
+    // which is already an explicit 400 for that reason.
+    ["UPSTREAM_AUTH_ERROR", 400],
+    // The upstream changed its response shape and the provider cannot
+    // normalize it. 502 because the fault is upstream of us, non-retryable
+    // because a retry returns the same broken payload.
+    ["UPSTREAM_SCHEMA_ERROR", 502],
+    // Caller-side bad input rejected by the provider. The minority spellings
+    // (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are deliberately not
+    // registered: they migrate to this spelling on the contract track, and
+    // registering them here would freeze the divergence.
+    ["INVALID_REQUEST", 400],
     ["OCR_UNAVAILABLE", 503],
     ["UNSUPPORTED_OCR_BACKEND", 503],
     ["STT_UNAVAILABLE", 503],
     ["UNSUPPORTED_STT_BACKEND", 503],
     ["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+    // The engine is reachable-in-principle but not now: retryable, so the
+    // caller may retry once the engine recovers. Authentication, protocol
+    // mismatch, an unsupported mode and denied egress stay unmapped (500) and
+    // non-retryable: they are deployment or provider faults that no caller
+    // retry can clear, and a retryable 5xx there would turn one bad rollout
+    // into gateway-driven load.
+    ["PROVIDER_ENGINE_UNAVAILABLE", 503],
+]);
+// Canonical retryability for the fleet-consensus codes registered above.
+//
+// Runtime retryability still resolves as `instance option ?? declared ??
+// false`, so this map changes no served response: an undeclared throw already
+// defaults to false, which is what every entry here says. It exists so the
+// authoring lint can tell a provider that its declared `retryable` contradicts
+// the registered meaning of the code, instead of the fleet quietly shipping two
+// answers for the same code. Only codes whose retryability was fixed as part of
+// registration belong here — do not backfill opinions the SDK never made.
+export const SDK_CANONICAL_ERROR_CODE_RETRYABILITY = new Map([
+    ["UPSTREAM_AUTH_ERROR", false],
+    ["UPSTREAM_SCHEMA_ERROR", false],
+    ["INVALID_REQUEST", false],
 ]);

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
+import type { ProviderErrorMessageParams } from "./i18n/error-messages.js";
 import type { ProviderErrorCategory } from "./observability.js";
-import type { HttpRedirectFailureReason } from "./types.js";
+import type { HttpRedirectFailureReason, ProviderLocaleKeyInput } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -9,6 +10,25 @@ export type ProviderErrorOptions = {
     retryable?: boolean;
     /** Provider-authored, bounded metadata safe for operational logs and error headers. */
     observability?: ProviderErrorObservability;
+    /**
+     * Locale catalog key for the client-facing `message`, e.g.
+     * `"errors.upstreamSchema.message"`. Resolved at serve time against the
+     * provider's `locales/{en,ko,ja}.json` with the caller's `Accept-Language`,
+     * falling back to `en` and then to the positional `message`.
+     *
+     * The positional `message` stays English: it is what `error.message`, cause
+     * frames, logs and OTLP attributes carry. Only the response envelope is
+     * localized.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Same resolution as {@link ProviderErrorOptions.messageKey}. */
+    fixKey?: ProviderLocaleKeyInput;
+    /**
+     * Values substituted into `{name}` placeholders of the resolved text.
+     * Strings and finite numbers only; string values are scrubbed and length
+     * capped before substitution because upstream text routinely lands here.
+     */
+    params?: ProviderErrorMessageParams;
 };
 /**
  * Provider-authored error diagnostics whose runtime values are validated before emission.
@@ -33,6 +53,24 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export declare class ProviderEngineProtocolVersionError extends SDKError {
+    readonly receivedVersion: unknown;
+    readonly expectedVersion: string;
+    constructor(receivedVersion: unknown, expectedVersion: string);
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export declare class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message?: string, options?: ProviderErrorOptions);
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export declare class ProviderEngineUnavailableError extends SDKError {
+    constructor(message?: string, cause?: Error);
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export declare class ProviderEgressDeniedError extends ProviderError {
+    constructor(message: string, details?: unknown);
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export declare class StealthCookieStoreVersionError extends SDKError {
     readonly version: unknown;

package/dist/errors.js

@@ -59,6 +59,56 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export class ProviderEngineProtocolVersionError extends SDKError {
+    receivedVersion;
+    expectedVersion;
+    constructor(receivedVersion, expectedVersion) {
+        super(`Provider engine protocol version mismatch: expected ${expectedVersion}, received ${String(receivedVersion)}`, {
+            code: "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+            details: { receivedVersion, expectedVersion },
+            fix: "Update @apifuse/provider-sdk or use a compatible APIFuse provider engine.",
+        });
+        this.receivedVersion = receivedVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = "ProviderEngineProtocolVersionError";
+    }
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message = "Provider engine authentication failed", options) {
+        super(message, {
+            code: "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+            fix: "Set APIFUSE__ENGINE__API_KEY to the workspace API key from your APIFuse bounty dashboard.",
+            ...options,
+        });
+        this.name = "ProviderEngineAuthenticationError";
+    }
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export class ProviderEngineUnavailableError extends SDKError {
+    constructor(message = "The remote APIFuse provider engine is unavailable", cause) {
+        super(message, {
+            code: "PROVIDER_ENGINE_UNAVAILABLE",
+            retryable: true,
+            fix: "Check network access and the provider engine endpoint, then retry.",
+            ...(cause ? { cause } : {}),
+        });
+        this.name = "ProviderEngineUnavailableError";
+    }
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export class ProviderEgressDeniedError extends ProviderError {
+    constructor(message, details) {
+        super(message, {
+            code: "PROVIDER_EGRESS_DENIED",
+            retryable: false,
+            details,
+            fix: "Use a host in the provider's pinned allowedHosts declaration, or request a trusted pin update.",
+        });
+        this.name = "ProviderEgressDeniedError";
+    }
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export class StealthCookieStoreVersionError extends SDKError {
     version;

package/dist/handle-meta.d.ts

@@ -15,25 +15,60 @@ export type HandleAccess = "bound" | "public";
  * `search-address` and `reverse-geocode` both issuing `location_token`).
  */
 export type HandleIssuedBy = string | readonly string[];
-/** Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field. */
+/** The schema side a handle field appears on. */
+export type HandleFieldDirection = "input" | "output";
+/**
+ * Direction-specific property keys for one handle kind, for the operations
+ * whose caller-facing contract names the same handle differently coming in and
+ * going out (the platform canon's `cursor` in, `next_cursor` out). The two keys
+ * are two spellings of ONE handle: the value a caller reads from `output` is
+ * the value it must send back under `input`, unedited.
+ */
+export interface HandleFieldNames {
+    readonly input: string;
+    readonly output: string;
+}
+/**
+ * Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field.
+ *
+ * `fieldName` is the INPUT property key — the name a caller sends the handle
+ * back under, and the name every runtime error message quotes. `outputFieldName`
+ * is present only when the output key differs, so a kind with one name emits
+ * exactly the meta it always did.
+ */
 export interface HandleFieldMeta {
     readonly kind: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Structural view of a handle kind as seen by the provider declaration
  * (`handle: [WaitingDraft, PageCursor]`), lint, and the registry. The runtime
  * kinds returned by `defineCursor` / `defineDraft` satisfy this shape.
+ *
+ * `fieldName` / `outputFieldName` follow the {@link HandleFieldMeta} rule:
+ * `fieldName` is the input key, `outputFieldName` is set only when the output
+ * key differs.
  */
 export interface HandleKindDeclaration {
     readonly name: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly access: HandleAccess;
     readonly issuedBy?: HandleIssuedBy;
 }
+/**
+ * The property key a handle kind claims on one side of an operation.
+ *
+ * This is the single place that resolves a direction to a key, so lint, the
+ * runtime, and error text cannot disagree about which name belongs where.
+ */
+export declare function handleFieldNameFor(kind: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">, direction: HandleFieldDirection): string;
+/** True when a kind names the same handle differently on input and output. */
+export declare function handleHasDirectionalFieldNames(kind: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">): boolean;
 /** Kind names are lowercase letters only so they never fuse with the word body. */
 export declare const HANDLE_KIND_NAME_PATTERN: RegExp;
 /** True for a single operation key or a non-empty list of operation keys. */

package/dist/handle-meta.js

@@ -7,6 +7,21 @@
  */
 /** JSON Schema meta key placed on every schema field created by `kind.field()`. */
 export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle";
+/**
+ * The property key a handle kind claims on one side of an operation.
+ *
+ * This is the single place that resolves a direction to a key, so lint, the
+ * runtime, and error text cannot disagree about which name belongs where.
+ */
+export function handleFieldNameFor(kind, direction) {
+    if (direction === "input")
+        return kind.fieldName;
+    return kind.outputFieldName ?? kind.fieldName;
+}
+/** True when a kind names the same handle differently on input and output. */
+export function handleHasDirectionalFieldNames(kind) {
+    return kind.outputFieldName !== undefined && kind.outputFieldName !== kind.fieldName;
+}
 /** Kind names are lowercase letters only so they never fuse with the word body. */
 export const HANDLE_KIND_NAME_PATTERN = /^[a-z]{2,12}$/;
 /** True for a single operation key or a non-empty list of operation keys. */
@@ -43,6 +58,7 @@ export function isHandleFieldMeta(value) {
     return (typeof record.kind === "string" &&
         (record.type === "cursor" || record.type === "draft") &&
         typeof record.fieldName === "string" &&
+        (record.outputFieldName === undefined || typeof record.outputFieldName === "string") &&
         (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
 }
 /**

package/dist/handle.d.ts

@@ -9,9 +9,9 @@
  */
 import { type ZodString, type ZodType, z } from "zod";
 import { ProviderError, type ProviderErrorOptions } from "./errors.js";
-import { type HandleAccess, type HandleFieldMeta, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
+import { type HandleAccess, type HandleFieldDirection, type HandleFieldMeta, type HandleFieldNames, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
 import type { ProviderStateDurationString } from "./types.js";
-export type { HandleAccess, HandleFieldMeta, HandleIssuedBy, HandleKindDeclaration, HandleKindType, };
+export type { HandleAccess, HandleFieldDirection, HandleFieldMeta, HandleFieldNames, HandleIssuedBy, HandleKindDeclaration, HandleKindType, };
 export type HandleStrength = "standard" | "high";
 /** Words issued per handle: 2 for bound kinds, 4 for public, 5 for high-strength public. */
 export type HandleWordCount = 2 | 4 | 5;
@@ -30,6 +30,10 @@ export interface HandleKindBase<TSchema extends ZodType = ZodType> extends Handl
     /**
      * Schema for the handle field, usable in output and input positions. Carries
      * the `x-apifuse-handle` meta and an SDK-owned English description.
+     *
+     * One schema serves both directions even when the kind declares separate
+     * `input` / `output` property keys: the meta carries both names and lint
+     * checks the key against the side the field actually appears on.
      */
     field(): ZodString;
 }
@@ -131,6 +135,7 @@ export declare function isHandleError(value: unknown): value is HandleError;
  */
 export declare function handleRecoverySentence(kind: {
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly issuedBy?: HandleIssuedBy;
 }): string;
 /** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
@@ -138,8 +143,16 @@ export declare function parseHandleDurationMs(value: ProviderStateDurationString
 export interface DefineCursorOptions<TSchema extends ZodType> {
     /** Kind name, `/^[a-z]{2,12}$/`; becomes the handle prefix. */
     readonly name: string;
-    /** Schema property key carrying the handle. Default `${name}_token`. */
-    readonly fieldName?: string;
+    /**
+     * Schema property key carrying the handle. Default `${name}_token`.
+     *
+     * Pass `{ input, output }` when the caller-facing contract names the same
+     * handle differently in each direction — the canon's `{ input: "cursor",
+     * output: "next_cursor" }`. Both keys must be given; the handle's identity
+     * stays the kind, so a value issued under `output` is still only valid when
+     * sent back under `input`.
+     */
+    readonly fieldName?: string | HandleFieldNames;
     readonly schema: TSchema;
     readonly ttl: ProviderStateDurationString;
     /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
@@ -155,7 +168,12 @@ export interface DefineCursorOptions<TSchema extends ZodType> {
 }
 export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema extends ZodType | undefined> {
     readonly name: string;
-    readonly fieldName?: string;
+    /**
+     * Schema property key carrying the handle. Default `${name}_token`. Accepts
+     * `{ input, output }` for a contract that names the handle differently in
+     * each direction; see {@link DefineCursorOptions.fieldName}.
+     */
+    readonly fieldName?: string | HandleFieldNames;
     readonly schema: TSchema;
     /** Optional schema of the commit result (type-level). */
     readonly result?: TResultSchema;