@apifuse/provider-sdk 2.2.0-beta.29 → 2.2.0-beta.30

package/src/server/serve-implementation.ts

@@ -728,6 +728,12 @@ function createProviderContext(
 			request: requestContext,
 			credential,
 			state: requestState,
+			onTelemetry: (event) =>
+				(options.logger ?? defaultProviderServerLogger)({
+					level: "info",
+					event: "provider_choice_token",
+					...event,
+				}),
 		}),
 	});
 	wrappedContext = context;
@@ -948,6 +954,18 @@ export type ProviderServerLogEvent =
 			providerId: string;
 			missingSecrets: string[];
 	  }
+	| {
+			level: "info";
+			event: "provider_choice_token";
+			providerId: string;
+			purpose: string;
+			operation: "parse" | "consume";
+			format: "word" | "legacy";
+			outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
+			consumeMode: "never" | "on-parse" | "explicit";
+			consumed: boolean;
+			replay: boolean;
+	  }
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";

package/src/types.ts

@@ -1892,6 +1892,28 @@ export interface ProviderChoiceBindingOptions {
 	credentialKeys?: readonly string[];
 }
 
+export type ProviderChoiceConsumeMode = "never" | "on-parse" | "explicit";
+
+export type ProviderChoiceConsumeResult =
+	| { readonly status: "consumed" }
+	| { readonly status: "already-consumed" }
+	| { readonly status: "unsupported" };
+
+export type ProviderChoiceExplicitParseResult =
+	| {
+			readonly status: "active";
+			readonly payload: Record<string, unknown>;
+			/** Stable, opaque key for provider-owned idempotency records. */
+			readonly replayKey: string;
+			/** Atomically claims a word token. Legacy managed tokens report unsupported. */
+			consume(): Promise<ProviderChoiceConsumeResult>;
+	  }
+	| {
+			readonly status: "consumed";
+			/** Use this key to read the provider-owned result before returning an error. */
+			readonly replayKey: string;
+	  };
+
 export type ProviderChoiceStorageOptions =
 	| {
 			readonly mode: "inline";
@@ -1925,6 +1947,8 @@ export interface ProviderChoiceIssueOptions<
 	ttlMs: number;
 	nowMs?: number;
 	bind?: ProviderChoiceBindingOptions;
+	/** Server storage only: standard emits four words; high emits five. */
+	strength?: "standard" | "high";
 	storage?: ProviderChoiceStorageOptions;
 }
 
@@ -1937,6 +1961,8 @@ export interface ProviderChoiceParseOptions {
 	futureToleranceMs?: number;
 	bind?: ProviderChoiceBindingOptions;
 	storage?: ProviderChoiceStorageOptions;
+	/** Defaults to never, matching legacy managed-token parse semantics. */
+	consume?: ProviderChoiceConsumeMode;
 }
 
 export interface ProviderChoiceContext {
@@ -1964,6 +1990,9 @@ export interface ProviderChoiceContext {
 	issue<TPayload extends Record<string, unknown>>(
 		options: ProviderChoiceIssueOptions<TPayload>,
 	): string | Promise<string>;
+	parse(
+		options: ProviderChoiceParseOptions & { readonly consume: "explicit" },
+	): Promise<ProviderChoiceExplicitParseResult>;
 	parse(
 		options: ProviderChoiceParseOptions & {
 			readonly storage?: { readonly mode: "inline" };
@@ -1985,7 +2014,11 @@ export interface ProviderChoiceContext {
 			>;
 		},
 	): Record<string, unknown> | Promise<Record<string, unknown>>;
-	parse(options: ProviderChoiceParseOptions): Record<string, unknown>;
+	parse(
+		options: ProviderChoiceParseOptions,
+	):
+		| Record<string, unknown>
+		| Promise<Record<string, unknown> | ProviderChoiceExplicitParseResult>;
 }
 
 export interface ContextScratchpad {