@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/server/serve.d.ts

@@ -1,7 +1,65 @@
 import { Hono } from "hono";
-import { type ProviderErrorCategory } from "../observability";
-import type { ProviderDefinition, ProviderRuntimeState, SttContext } from "../types";
-import { type OperationRequest } from "./types";
+import { z } from "zod";
+import { type ProviderErrorCategory } from "../observability.js";
+import type { ProviderContext, ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
+import { type OperationRequest } from "./types.js";
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+    category: ProviderErrorCategory;
+    taxonomyVersion: string;
+    retryable: boolean;
+    upstreamStatus?: number;
+};
+export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    providerId: z.ZodString;
+    operationId: z.ZodString;
+    sessionKey: z.ZodString;
+    connectionId: z.ZodString;
+    serviceAccountId: z.ZodString;
+    ownerPodId: z.ZodString;
+    generation: z.ZodNumber;
+    sourcePodId: z.ZodString;
+    forwardedAt: z.ZodString;
+    deadlineAt: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    operationRequest: z.ZodObject<{
+        requestId: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        connectionId: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        connection: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            mode: z.ZodEnum<{
+                none: "none";
+                credentials: "credentials";
+                oauth2: "oauth2";
+                "platform-managed": "platform-managed";
+                oauth2_proxied: "oauth2_proxied";
+            }>;
+            secrets: z.ZodRecord<z.ZodString, z.ZodString>;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            externalRef: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ProviderServerStatefulForwardEnvelope = Readonly<z.infer<typeof ProviderServerStatefulForwardEnvelopeSchema>>;
+export type ProviderServerStatefulOwnerFence = Readonly<Pick<ProviderServerStatefulForwardEnvelope, "providerId" | "sessionKey" | "ownerPodId" | "generation" | "sourcePodId" | "forwardedAt" | "requestId" | "idempotencyKey">>;
+export type ProviderServerStatefulOwnerFenceValidator = (fence: ProviderServerStatefulOwnerFence, signal: AbortSignal) => boolean | Promise<boolean>;
+export type ProviderServerOperationExecutorInput = {
+    readonly provider: ProviderDefinition;
+    readonly operationId: string;
+    readonly ctx: ProviderContext;
+    readonly request: OperationRequest & {
+        readonly deadlineAt?: string;
+    };
+    readonly signal?: AbortSignal;
+    readonly internalStatefulForward?: ProviderServerStatefulForwardEnvelope;
+};
+export type ProviderServerOperationExecutor = (input: ProviderServerOperationExecutorInput) => Promise<unknown>;
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
 type ProviderRequestCost = {
     durationMs: number;
@@ -29,12 +87,19 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     errorCategory?: ProviderErrorCategory;
     taxonomyVersion?: string;
     retryable?: boolean;
+    signal?: "unregistered_provider_error_code";
+    signalFix?: string;
     issues?: Array<{
         path: string;
         code: string;
         message: string;
     }>;
 }) | {
+    level: "warn";
+    event: "provider_secrets_missing";
+    providerId: string;
+    missingSecrets: string[];
+} | {
     level: "warn";
     event: "provider_cleanup_failed";
     providerId: string;
@@ -44,18 +109,65 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     resource: "browser" | "stealth";
     errorClass: string;
     message: string;
+} | {
+    level: "error";
+    event: "provider_shutdown_hook_failed";
+    providerId: string;
+    hookIndex: number;
+    errorClass: string;
+    message: string;
 };
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 export type ProviderServerOptions = {
     logger?: ProviderServerLogger;
+    /** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
+    operationExecutor?: ProviderServerOperationExecutor;
+    /** Optional signed internal executor for stateful owner forwarding. */
+    internalOperationExecutor?: ProviderServerOperationExecutor;
+    statefulForwarding?: {
+        readonly secret: string;
+        readonly maxSkewMs?: number;
+        readonly replayCacheMaxEntries?: number;
+        /** Required fail-closed check against the SDK/runtime owner registry. */
+        readonly validateOwnerFence: ProviderServerStatefulOwnerFenceValidator;
+    };
     /** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
     stt?: SttContext;
     /** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
     state?: ProviderRuntimeState;
     /** Allow process-local runtime state only for local development and tests. */
     allowMemoryStateFallback?: boolean;
+    /**
+     * Graceful process shutdown. Hooks run in declaration order after listeners stop accepting work.
+     *
+     * @example
+     * ```ts
+     * await serve(provider, {
+     *	 shutdown: {
+     *		 hooks: [
+     *			 async () => { await emitter.flush(); },
+     *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+     *			 async () => { await lease.release(); },
+     *			 async () => { await router.close(); },
+     *		 ],
+     *	 },
+     * });
+     * ```
+     */
+    shutdown?: {
+        readonly hooks?: Array<() => Promise<void>>;
+        readonly signals?: boolean | NodeJS.Signals[];
+        readonly timeoutMs?: number;
+    };
 };
 export declare function createServerApp(provider: ProviderDefinition, options?: ProviderServerOptions): Hono;
+export type ProviderServerCloseOptions = {
+    readonly timeoutMs?: number;
+};
+export type ProviderServerHandle = {
+    readonly port: number;
+    close(options?: ProviderServerCloseOptions): Promise<void>;
+};
 export interface ServeOptions extends ProviderServerOptions {
     host?: string;
     port?: number;
@@ -66,5 +178,5 @@ export interface ServeOptions extends ProviderServerOptions {
      */
     selfTestPort?: number;
 }
-export declare function serve(provider: ProviderDefinition, options?: ServeOptions): Promise<void>;
+export declare function serve(provider: ProviderDefinition, options?: ServeOptions): Promise<ProviderServerHandle>;
 export {};