@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/dist/server/serve-implementation.d.ts

@@ -0,0 +1,210 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { type ProviderErrorCategory } from "../observability.js";
+import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
+import type { SelfTestCancellationLogEvent } from "./self-test.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;
+export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
+type ProviderRequestCost = {
+    durationMs: number;
+    cpuUserMicros: number;
+    cpuSystemMicros: number;
+    cpuTotalMicros: number;
+};
+type ProviderServerLogEventBase = ProviderRequestCost & {
+    providerId: string;
+    kind: "operation" | "auth";
+    route: string;
+    requestId?: string;
+    status: number;
+};
+export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
+    level: "info";
+    event: "provider_request_completed";
+}) | (ProviderServerLogEventBase & {
+    level: "warn" | "error";
+    event: "provider_request_failed";
+    code: string;
+    errorClass: string;
+    message: string;
+    upstreamStatus?: number;
+    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: "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";
+    providerId: string;
+    kind: "operation" | "auth";
+    route: string;
+    requestId?: string;
+    resource: "browser" | "stealth";
+    errorClass: string;
+    message: string;
+} | {
+    level: "error";
+    event: "provider_shutdown_hook_failed";
+    providerId: string;
+    hookIndex: number;
+    errorClass: string;
+    message: string;
+} | SelfTestCancellationLogEvent;
+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 OCR override for tests or custom hosts; local/prod normally resolves from env. */
+    ocr?: OcrContext;
+    /** Optional resolver override for tests or custom hosts; local/prod normally resolves from env. */
+    resolver?: ResolverContext;
+    /** 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;
+    };
+};
+/**
+ * Primary, cross-runtime app factory. Declared capability ESM is preloaded
+ * asynchronously, so this path works on Bun and every supported Node release.
+ */
+export declare function createServerAppAsync(provider: ProviderDefinition, options?: ProviderServerOptions): Promise<Hono>;
+/**
+ * Synchronous compatibility factory. Standard providers remain synchronous on
+ * every runtime because they load no capability modules. Providers declaring a
+ * capability require Bun or Node >=22.12; older Node releases receive an
+ * actionable error directing them to createServerAppAsync().
+ */
+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;
+    /**
+     * Port for the internal self-test listener (default 3001 or
+     * APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT). The listener only starts
+     * when APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET is present.
+     */
+    selfTestPort?: number;
+}
+export declare function serve(provider: ProviderDefinition, options?: ServeOptions): Promise<ProviderServerHandle>;
+export {};