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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.62
+
+- Release candidate for main commit 98c623f799268b6d13ce59844b2b33ed78dcd0c3.
+
 ## 2.2.0-beta.61
 
 - Release candidate for main commit 8ba435285f6f448bb1b8d01b1d65d2e1a4b42aaa.

package/bin/apifuse-pack-types.ts

@@ -451,25 +451,29 @@ const NEGATIVE_CONTROLS = [
 		].join("\n"),
 	},
 	{
-		filename: "negative-control-native-telemetry-description.ts",
+		filename: "negative-control-http-telemetry-free-text.ts",
 		expectedCode: "TS2322",
-		description: "native gateway telemetry rejects free-string diagnostic fields",
+		description: "HTTP gateway telemetry rejects a free-string diagnostic field",
 		source: [
-			'import type { GatewayIngestible, NativeTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
-			"type UnsafeHeader = NativeTelemetryHeaderPayload & { vendorErrorMessage: string };",
-			"declare const header: NativeTelemetryHeaderPayload;",
-			'export const mustNotCompile: GatewayIngestible<UnsafeHeader> = { ...header, vendorErrorMessage: "free text stays log-only" };',
+			'import type { HttpTelemetryHeaderPayload, GatewayIngestible } from "@apifuse/provider-sdk";',
+			"type UnsafeHttpHeader = HttpTelemetryHeaderPayload & { message: string };",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			'export const mustNotCompile: GatewayIngestible<UnsafeHttpHeader> = { ...header, message: "upstream free text" };',
+			"",
 		].join("\n"),
 	},
 	{
-		filename: "positive-control-native-telemetry-contributor.ts",
+		filename: "positive-control-http-telemetry-contributor.ts",
 		expectedCode: "",
-		description: "native telemetry contributor satisfies the gateway-ingestible contract",
+		description: "HTTP contributor satisfies the gateway and tenant projection contracts",
 		source: [
-			'import { NativeTelemetryCollector, type GatewayIngestible, type NativeTelemetryHeaderPayload, type NativeTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
-			"export const native: TelemetryContributor<NativeTelemetryLogPayload, NativeTelemetryHeaderPayload> = new NativeTelemetryCollector();",
-			"declare const header: NativeTelemetryHeaderPayload;",
-			"export const ingestible: GatewayIngestible<NativeTelemetryHeaderPayload> = header;",
+			'import { HttpTelemetryCollector, type HttpTelemetryHeaderPayload, type HttpTelemetryLogPayload, type HttpTelemetryRetryPayload, type GatewayIngestible, type TenantNeutral, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			'import { HttpTelemetryCollector as ServerHttpCollector } from "@apifuse/provider-sdk/server";',
+			"export const http: TelemetryContributor<HttpTelemetryLogPayload, HttpTelemetryHeaderPayload> = new HttpTelemetryCollector();",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<HttpTelemetryHeaderPayload> = header;",
+			"export const retry: TenantNeutral<HttpTelemetryRetryPayload> | undefined = new ServerHttpCollector().toTenantRetryPayload();",
+			"",
 		].join("\n"),
 	},
 ] as const;

package/dist/handle-meta.d.ts

@@ -9,12 +9,18 @@
 export declare const APIFUSE_HANDLE_META_KEY: "x-apifuse-handle";
 export type HandleKindType = "cursor" | "draft";
 export type HandleAccess = "bound" | "public";
+/**
+ * Operation key(s) that issue a handle. A single string is the common case; a
+ * list names every operation whose output carries the field (for example
+ * `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. */
 export interface HandleFieldMeta {
     readonly kind: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Structural view of a handle kind as seen by the provider declaration
@@ -26,10 +32,20 @@ export interface HandleKindDeclaration {
     readonly type: HandleKindType;
     readonly fieldName: string;
     readonly access: HandleAccess;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }
 /** 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. */
+export declare function isHandleIssuedBy(value: unknown): value is HandleIssuedBy;
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export declare function handleIssuerList(issuedBy: HandleIssuedBy | undefined): readonly string[];
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export declare function formatHandleIssuers(issuedBy: HandleIssuedBy | undefined): string | undefined;
 export declare function isHandleFieldMeta(value: unknown): value is HandleFieldMeta;
 /**
  * The SDK-owned description `kind.field()` emits. Lint exempts a handle field

package/dist/handle-meta.js

@@ -9,6 +9,33 @@
 export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle";
 /** 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. */
+export function isHandleIssuedBy(value) {
+    if (typeof value === "string")
+        return true;
+    return (Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string"));
+}
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export function handleIssuerList(issuedBy) {
+    if (issuedBy === undefined)
+        return [];
+    return typeof issuedBy === "string" ? [issuedBy] : issuedBy;
+}
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export function formatHandleIssuers(issuedBy) {
+    const issuers = handleIssuerList(issuedBy).map((operation) => `\`${operation}\``);
+    if (issuers.length === 0)
+        return undefined;
+    if (issuers.length === 1)
+        return issuers[0];
+    if (issuers.length === 2)
+        return `${issuers[0]} or ${issuers[1]}`;
+    return `${issuers.slice(0, -1).join(", ")}, or ${issuers[issuers.length - 1]}`;
+}
 export function isHandleFieldMeta(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -16,7 +43,7 @@ export function isHandleFieldMeta(value) {
     return (typeof record.kind === "string" &&
         (record.type === "cursor" || record.type === "draft") &&
         typeof record.fieldName === "string" &&
-        (record.issuedBy === undefined || typeof record.issuedBy === "string"));
+        (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
 }
 /**
  * The SDK-owned description `kind.field()` emits. Lint exempts a handle field
@@ -24,6 +51,7 @@ export function isHandleFieldMeta(value) {
  * provider override re-enters the localization rules.
  */
 export function handleFieldDescription(meta) {
-    const origin = meta.issuedBy ? ` issued by \`${meta.issuedBy}\`` : "";
+    const issuers = formatHandleIssuers(meta.issuedBy);
+    const origin = issuers ? ` issued by ${issuers}` : "";
     return `Opaque handle${origin}. Copy it exactly as returned; do not edit or shorten it.`;
 }

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 HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
+import { type HandleAccess, type HandleFieldMeta, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
 import type { ProviderStateDurationString } from "./types.js";
-export type { HandleAccess, HandleFieldMeta, HandleKindDeclaration, HandleKindType };
+export type { HandleAccess, HandleFieldMeta, 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;
@@ -41,7 +41,10 @@ export interface CursorKind<TSchema extends ZodType = ZodType> extends HandleKin
 }
 export interface DraftKind<TSchema extends ZodType = ZodType, TResultSchema extends ZodType | undefined = ZodType | undefined> extends HandleKindBase<TSchema> {
     readonly type: "draft";
-    readonly access: "bound";
+    /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+    readonly access: HandleAccess;
+    /** Public only; `"high"` forces 5 words. Always `"standard"` for bound drafts. */
+    readonly strength: HandleStrength;
     readonly ttl: {
         readonly idle: ProviderStateDurationString;
         readonly max: ProviderStateDurationString;
@@ -52,7 +55,6 @@ export interface DraftKind<TSchema extends ZodType = ZodType, TResultSchema exte
     readonly resultTtlMs: number;
     /** Optional schema describing the commit result; type-level only at runtime. */
     readonly result: TResultSchema | undefined;
-    readonly wordCount: 2;
 }
 export type HandleKind = CursorKind<any> | DraftKind<any, any>;
 /** Stored record data type (schema output); what `read`, `update`, and `commit` callbacks receive. */
@@ -79,6 +81,12 @@ export interface HandleCommitResult<K extends HandleKind> {
 export interface HandleContext {
     /** Validates `data` with `kind.schema`, stores it, and returns the canonical handle. */
     create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string>;
+    /**
+     * Same as `create` but returns the full record (`handle`, `status`, `data`,
+     * `createdAt`, `expiresAt`) so a provider can expose `expires_at` without
+     * recomputing ttl math. `create` is the string-returning shortcut.
+     */
+    createRecord<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<HandleRecord<K>>;
     /** Tolerantly parses `handle`, loads the record; drafts get their idle TTL touched. */
     read<K extends HandleKind>(kind: K, handle: string): Promise<HandleRecord<K>>;
     /** CAS update of an active draft (3 retries) with sliding TTL. */
@@ -123,7 +131,7 @@ export declare function isHandleError(value: unknown): value is HandleError;
  */
 export declare function handleRecoverySentence(kind: {
     readonly fieldName: string;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }): string;
 /** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
 export declare function parseHandleDurationMs(value: ProviderStateDurationString, label: string): number;
@@ -142,8 +150,8 @@ export interface DefineCursorOptions<TSchema extends ZodType> {
     readonly maxValueBytes?: number;
     /** Public only; `"high"` forces 5 words. Auto-high when ttl > 1h. */
     readonly strength?: HandleStrength;
-    /** Operation key that issues this handle; used in error text and lint. */
-    readonly issuedBy?: string;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema extends ZodType | undefined> {
     readonly name: string;
@@ -157,15 +165,28 @@ export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema exten
     };
     /** How long a committed record stays for replay. Default "24h". */
     readonly resultTtl?: ProviderStateDurationString;
-    /** Default 200 per connection. */
+    /**
+     * `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped
+     * draft for connectionless providers (`auth: none`), 4-5 words, `maxEntries`
+     * required; every lookup failure collapses to `HANDLE_INVALID`.
+     */
+    readonly access?: HandleAccess;
+    /** Required when public. Bound default 200 per connection. */
     readonly maxEntries?: number;
     /** Default 64,000. */
     readonly maxValueBytes?: number;
-    readonly issuedBy?: string;
+    /** Public only; `"high"` forces 5 words. Auto-high when ttl.max > 1h. */
+    readonly strength?: HandleStrength;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 /** Defines an immutable cursor kind (pagination, offered option lists). */
 export declare function defineCursor<TSchema extends ZodType>(options: DefineCursorOptions<TSchema>): CursorKind<TSchema>;
-/** Defines a mutable, always-bound draft kind (multi-turn forms with one-shot commit). */
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
 export declare function defineDraft<TSchema extends ZodType, TResultSchema extends ZodType | undefined = undefined>(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema>;
 export declare function isDraftKind(kind: HandleKind): kind is DraftKind<any, any>;
 export declare function isCursorKind(kind: HandleKind): kind is CursorKind<any>;
@@ -174,8 +195,8 @@ export interface PickOptions<T> {
     readonly field: string;
     /** Item property compared against `value`. Default = `field`. */
     readonly by?: keyof T & string;
-    /** Operation that listed the items; used in the error message when known. */
-    readonly issuedBy?: string;
+    /** Operation(s) that listed the items; used in the error message when known. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Chooses one offered item by a plain value the LLM copied from the offer.

package/dist/handle.js

@@ -9,9 +9,9 @@
  */
 import { z } from "zod";
 import { brandHandleError, hasHandleErrorBrand, ProviderError, } from "./errors.js";
-import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, HIGH_PUBLIC_HANDLE_WORD_COUNT, PUBLIC_HANDLE_WORD_COUNT, } from "./runtime/handle-wordlist.js";
-/** Public cursors whose ttl exceeds this are issued with five words (auto-high). */
+/** Public kinds whose (max) ttl exceeds this are issued with five words (auto-high). */
 const AUTO_HIGH_TTL_MS = 3_600_000;
 const DEFAULT_BOUND_MAX_ENTRIES = 200;
 const DEFAULT_CURSOR_MAX_VALUE_BYTES = 16_000;
@@ -63,8 +63,9 @@ export function isHandleError(value) {
  * knows the next action without provider-specific wording.
  */
 export function handleRecoverySentence(kind) {
-    if (kind.issuedBy) {
-        return `Call \`${kind.issuedBy}\` again and pass the new \`${kind.fieldName}\` exactly as returned.`;
+    const issuers = formatHandleIssuers(kind.issuedBy);
+    if (issuers) {
+        return `Call ${issuers} again and pass the new \`${kind.fieldName}\` exactly as returned.`;
     }
     return `Request a new \`${kind.fieldName}\` and pass it exactly as returned.`;
 }
@@ -120,6 +121,38 @@ function assertPositiveInteger(value, label, define) {
         throw new Error(`${define}: ${label} must be a positive integer; received ${String(value)}.`);
     }
 }
+function assertAccess(value, define) {
+    if (value !== "bound" && value !== "public") {
+        throw new Error(`${define}: access must be "bound" or "public"; received ${String(value)}.`);
+    }
+}
+function assertStrength(value, define) {
+    if (value !== "standard" && value !== "high") {
+        throw new Error(`${define}: strength must be "standard" or "high"; received ${String(value)}.`);
+    }
+}
+/** Validates `issuedBy` and returns a frozen copy for lists; `undefined` stays undefined. */
+function normalizeIssuedBy(value, define, name) {
+    if (value === undefined)
+        return undefined;
+    if (!isHandleIssuedBy(value) || (typeof value === "string" ? value.length === 0 : false)) {
+        throw new Error(`${define}: "${name}" issuedBy must be an operation key or a non-empty list of operation keys; received ${JSON.stringify(value)}.`);
+    }
+    if (typeof value === "string")
+        return value;
+    if (value.some((operation) => operation.length === 0)) {
+        throw new Error(`${define}: "${name}" issuedBy must not contain empty operation keys.`);
+    }
+    return Object.freeze([...value]);
+}
+/** Word count for a kind: 2 bound; public 4, or 5 when high strength or the lifetime exceeds 1h. */
+function wordCountFor(access, strength, lifetimeMs) {
+    if (access === "bound")
+        return BOUND_HANDLE_WORD_COUNT;
+    return strength === "high" || lifetimeMs > AUTO_HIGH_TTL_MS
+        ? HIGH_PUBLIC_HANDLE_WORD_COUNT
+        : PUBLIC_HANDLE_WORD_COUNT;
+}
 function createHandleField(meta) {
     const described = z.string().min(1).describe(handleFieldDescription(meta));
     // zod v4 `.meta()` replaces the registry entry, so carry the description over.
@@ -133,14 +166,11 @@ export function defineCursor(options) {
     const fieldName = options.fieldName ?? `${options.name}_token`;
     assertFieldName(fieldName, define);
     const access = options.access ?? "bound";
-    if (access !== "bound" && access !== "public") {
-        throw new Error(`${define}: access must be "bound" or "public"; received ${String(access)}.`);
-    }
+    assertAccess(access, define);
     const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
     const strength = options.strength ?? "standard";
-    if (strength !== "standard" && strength !== "high") {
-        throw new Error(`${define}: strength must be "standard" or "high"; received ${String(strength)}.`);
-    }
+    assertStrength(strength, define);
+    const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
     if (access === "public" && options.maxEntries === undefined) {
         throw new Error(`${define}: public cursor "${options.name}" must declare maxEntries (provider-wide live-entry quota).`);
     }
@@ -148,23 +178,19 @@ export function defineCursor(options) {
     assertPositiveInteger(maxEntries, "maxEntries", define);
     const maxValueBytes = options.maxValueBytes ?? DEFAULT_CURSOR_MAX_VALUE_BYTES;
     assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
-    const wordCount = access === "bound"
-        ? BOUND_HANDLE_WORD_COUNT
-        : strength === "high" || ttlMs > AUTO_HIGH_TTL_MS
-            ? HIGH_PUBLIC_HANDLE_WORD_COUNT
-            : PUBLIC_HANDLE_WORD_COUNT;
+    const wordCount = wordCountFor(access, strength, ttlMs);
     const meta = {
         kind: options.name,
         type: "cursor",
         fieldName,
-        ...(options.issuedBy ? { issuedBy: options.issuedBy } : {}),
+        ...(issuedBy ? { issuedBy } : {}),
     };
     return Object.freeze({
         name: options.name,
         type: "cursor",
         fieldName,
         access,
-        issuedBy: options.issuedBy,
+        issuedBy,
         schema: options.schema,
         ttl: options.ttl,
         ttlMs,
@@ -175,7 +201,11 @@ export function defineCursor(options) {
         field: () => createHandleField(meta),
     });
 }
-/** Defines a mutable, always-bound draft kind (multi-turn forms with one-shot commit). */
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
 export function defineDraft(options) {
     const define = "defineDraft";
     assertKindName(options.name, define);
@@ -191,22 +221,36 @@ export function defineDraft(options) {
     }
     const resultTtl = options.resultTtl ?? DEFAULT_RESULT_TTL;
     const resultTtlMs = parseHandleDurationMs(resultTtl, `"${options.name}" resultTtl`);
+    const access = options.access ?? "bound";
+    assertAccess(access, define);
+    const strength = options.strength ?? "standard";
+    assertStrength(strength, define);
+    if (access === "bound" && strength !== "standard") {
+        throw new Error(`${define}: draft "${options.name}" strength applies to public drafts only; bound drafts are always two words.`);
+    }
+    const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
+    if (access === "public" && options.maxEntries === undefined) {
+        throw new Error(`${define}: public draft "${options.name}" must declare maxEntries (provider-wide live-entry quota).`);
+    }
     const maxEntries = options.maxEntries ?? DEFAULT_BOUND_MAX_ENTRIES;
     assertPositiveInteger(maxEntries, "maxEntries", define);
     const maxValueBytes = options.maxValueBytes ?? DEFAULT_DRAFT_MAX_VALUE_BYTES;
     assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
+    // A public draft's guessable lifetime is its hard `max` ttl (idle only shortens it).
+    const wordCount = wordCountFor(access, strength, maxTtlMs);
     const meta = {
         kind: options.name,
         type: "draft",
         fieldName,
-        ...(options.issuedBy ? { issuedBy: options.issuedBy } : {}),
+        ...(issuedBy ? { issuedBy } : {}),
     };
     return Object.freeze({
         name: options.name,
         type: "draft",
         fieldName,
-        access: "bound",
-        issuedBy: options.issuedBy,
+        access,
+        strength,
+        issuedBy,
         schema: options.schema,
         result: options.result,
         ttl: options.ttl,
@@ -216,7 +260,7 @@ export function defineDraft(options) {
         resultTtlMs,
         maxEntries,
         maxValueBytes,
-        wordCount: BOUND_HANDLE_WORD_COUNT,
+        wordCount,
         field: () => createHandleField(meta),
     });
 }
@@ -247,8 +291,9 @@ export function pick(items, value, options) {
     if (loose.length === 1)
         return loose[0];
     const allowed = items.map(keyOf);
-    const listed = options.issuedBy
-        ? ` Use the values exactly as listed by \`${options.issuedBy}\`.`
+    const issuers = formatHandleIssuers(options.issuedBy);
+    const listed = issuers
+        ? ` Use the values exactly as listed by ${issuers}.`
         : " Use the values exactly as listed.";
     throw new HandleError("PICK_NOT_OFFERED", `\`${options.field}\` must be one of: ${allowed.join(", ")}.${listed}`, { details: { field: options.field, allowed } });
 }

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, } from "./runtime/cache.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
@@ -41,7 +42,7 @@ export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
 export type { ResolverPaidUsageContext, ResolverVendorTransport, ResolverVendorUnavailableReason, } from "./runtime/resolver-vendors/types.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
-export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
@@ -56,4 +57,5 @@ export * from "./utils/date.js";
 export * from "./utils/parse.js";
 export * from "./utils/text.js";
 export * from "./utils/transform.js";
+export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "./runtime/http-telemetry.js";
 export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "./runtime/native-telemetry.js";

package/dist/index.js

@@ -17,6 +17,7 @@ export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, } from "./runtime/cache.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
 export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
@@ -32,7 +33,7 @@ export { ResolverTelemetryCollector, } from "./runtime/resolver-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
-export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.js";
@@ -45,4 +46,5 @@ export * from "./utils/date.js";
 export * from "./utils/parse.js";
 export * from "./utils/text.js";
 export * from "./utils/transform.js";
+export { HttpTelemetryCollector, } from "./runtime/http-telemetry.js";
 export { NativeTelemetryCollector, } from "./runtime/native-telemetry.js";

package/dist/lint.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
-import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, handleIssuerList, isHandleIssuedBy, isHandleFieldMeta, } from "./handle-meta.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 const requireModule = createRequire(import.meta.url);
@@ -1204,14 +1204,15 @@ function readHandleKindDeclarations(value) {
         return (typeof record.name === "string" &&
             (record.type === "cursor" || record.type === "draft") &&
             typeof record.fieldName === "string" &&
-            (record.issuedBy === undefined || typeof record.issuedBy === "string"));
+            (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
     });
 }
 /**
  * ADR-0012 handle rules: every `x-apifuse-handle` schema field must belong to
  * a declared kind under its declared property key; every declared kind must be
- * both issued (some output) and accepted (some input); `issuedBy` must name an
- * operation whose output carries the field; and `ctx.handle` needs `state`.
+ * both issued (some output) and accepted (some input); every `issuedBy` entry
+ * must be an operation key and at least one of them must output the field; and
+ * `ctx.handle` needs `state`.
  */
 function lintHandleDeclarations(provider) {
     const diagnostics = [];
@@ -1292,20 +1293,39 @@ function lintHandleDeclarations(provider) {
         }
         if (kind.issuedBy === undefined)
             continue;
-        if (!Object.hasOwn(operations, kind.issuedBy)) {
+        const issuers = handleIssuerList(kind.issuedBy);
+        const known = issuers.filter((operationKey) => Object.hasOwn(operations, operationKey));
+        for (const operationKey of issuers) {
+            if (known.includes(operationKey))
+                continue;
+            diagnostics.push({
+                rule: "handle-issued-by",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${operationKey}", which is not an operation key.`,
+            });
+        }
+        if (known.length === 0)
+            continue;
+        const issuing = known.filter((operationKey) => outputKindsByOperation.get(operationKey)?.has(kind.name));
+        if (issuing.length > 0)
+            continue;
+        if (known.length === 1) {
             diagnostics.push({
                 rule: "handle-issued-by",
                 level: "error",
                 field,
-                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", which is not an operation key.`,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${known[0]}", but that operation's output has no "${kind.fieldName}" handle field.`,
             });
         }
-        else if (!outputKindsByOperation.get(kind.issuedBy)?.has(kind.name)) {
+        else {
             diagnostics.push({
                 rule: "handle-issued-by",
                 level: "error",
                 field,
-                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", but that operation's output has no "${kind.fieldName}" handle field.`,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy ${known
+                    .map((operationKey) => `"${operationKey}"`)
+                    .join(", ")}, but none of those operations' outputs has a "${kind.fieldName}" handle field. At least one listed issuer must output it.`,
             });
         }
     }

package/dist/provider.d.ts

@@ -11,7 +11,9 @@ export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_
 export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, untrustedContent, z, } from "./schema.js";
 export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";

package/dist/provider.js

@@ -6,7 +6,9 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";