@apifuse/provider-sdk 2.2.0-beta.12 → 2.2.0-beta.14

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
-import { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, } from "../errors.js";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -33,6 +33,8 @@ import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -320,25 +322,27 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
+    const observability = errorObservabilityDetails(error);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
                 code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
                 message: "Stateful forwarding deadline expired.",
                 ...(requestId ? { requestId } : {}),
-                details: { retryable: false },
+                retryable: observability.retryable,
             },
         };
     }
     if (isProviderError(error)) {
-        const details = publicProviderErrorDetails(error);
+        const details = error.details;
         return {
             error: {
                 code: error.code ?? "provider_error",
                 message: publicProviderErrorMessage(error),
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 ...(error.fix ? { fix: error.fix } : {}),
-                ...(details ? { details } : {}),
+                ...(details !== undefined ? { details } : {}),
             },
         };
     }
@@ -348,6 +352,7 @@ function toErrorResponse(error, requestId) {
                 code: "invalid_request",
                 message: "Invalid request body",
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 details: zodDetails(error),
             },
         };
@@ -363,6 +368,7 @@ function toErrorResponse(error, requestId) {
             code: "internal_error",
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
+            retryable: observability.retryable,
             details: {
                 retryable: false,
                 category: "internal_error",
@@ -371,26 +377,6 @@ function toErrorResponse(error, requestId) {
         },
     };
 }
-function publicProviderErrorDetails(error) {
-    const providerDetails = error.details;
-    const observabilityDetails = providerObservabilityDetails(error);
-    if (providerDetails === undefined) {
-        return observabilityDetails;
-    }
-    if (observabilityDetails === undefined) {
-        return providerDetails;
-    }
-    if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
-        return { ...providerDetails, ...observabilityDetails };
-    }
-    return {
-        provider: providerDetails,
-        observability: observabilityDetails,
-    };
-}
-function isPlainRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 // Accepts `unknown` so the branded guards narrow cleanly from the top: the
 // subtype error classes are structurally compatible with ProviderError, so
 // narrowing from a ProviderError-typed value would collapse the negative branch
@@ -449,6 +435,48 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
+function errorObservabilityDetails(error) {
+    const providerDetails = providerObservabilityDetails(error);
+    if (providerDetails)
+        return providerDetails;
+    if (error instanceof z.ZodError || isValidationError(error)) {
+        return {
+            category: isProviderError(error) && error.options?.category
+                ? error.options.category
+                : "input_validation",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+        };
+    }
+    if (error instanceof StatefulRoutingDeadlineError) {
+        return {
+            category: "timeout",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: false,
+        };
+    }
+    if (isProviderError(error)) {
+        return {
+            category: error.options?.category ?? "provider_error",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: error.options?.retryable ?? false,
+        };
+    }
+    return {
+        category: "internal_error",
+        taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+        retryable: false,
+    };
+}
+function responseWithErrorObservability(response, error) {
+    const headers = new Headers(response.headers);
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
 function publicProviderErrorMessage(error) {
     if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
@@ -481,9 +509,6 @@ function toStatusCode(error) {
     if (error instanceof StatefulRoutingDeadlineError) {
         return 504;
     }
-    if (isTransportError(error)) {
-        return error.code === "transport_timeout" ? 504 : 502;
-    }
     if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
@@ -509,10 +534,87 @@ function toStatusCode(error) {
             case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
                 return 503;
         }
-        return 400;
+        if (isTransportError(error)) {
+            return error.code === "transport_timeout" ? 504 : 502;
+        }
+        if (isValidationError(error)) {
+            return error.options?.category === "output_validation" ? 500 : 400;
+        }
+        return 500;
     }
     return 500;
 }
+// Codes emitted by SDK-owned paths must never be attributed to provider
+// authors by the unregistered-code signal, even when their intentional status
+// is 500. Provider-authored codes not in this registry retain the signal.
+const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+    "AUTH_PROMPT_UNAVAILABLE",
+    "BROWSER_CDP_POOL_REQUIRED",
+    "BROWSER_RUNTIME_UNSUPPORTED",
+    "STEALTH_RUNTIME_UNSUPPORTED",
+    "SSE_EVENT_UNDECLARED",
+    "STREAM_EVENT_TOO_LARGE",
+    "STREAM_CHUNK_TOO_LARGE",
+    "SSE_RESULT_UNSUPPORTED",
+    "STREAM_RESULT_UNSUPPORTED",
+    "AUTH_FLOW_NOT_CONFIGURED",
+    "refresh_not_supported",
+    "RUNTIME_UNSUPPORTED",
+    "PROVIDER_STATE_UNSUPPORTED",
+    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+    "CHOICE_STATE_UNAVAILABLE",
+    "CHOICE_CONTEXT_REQUIRED",
+    "unsupported_stealth_cookie_store_version",
+    "provider_secret_error",
+    "credential_key_error",
+    "credential_mode_error",
+    "flow_expired",
+    "turn_validation_error",
+    "context_access_error",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "STT_AUDIO_TOO_LARGE",
+    "STT_UPSTREAM_FAILED",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "retry_invalid_policy",
+    "retry_unsafe_method",
+    "stealth_cookie_store_serialize_failed",
+    "response_too_large",
+    "transport_stream_unavailable",
+    "transport_invalid_method",
+    "http_transport_override_unsupported",
+    "transport_invalid_url",
+    "retry_exhausted",
+    "auth_abort_unsafe_data",
+    "credentials_auth_missing_credential_keys",
+    "credentials_auth_missing_credential",
+    "credentials_auth_invalid_login_result",
+    "credentials_auth_unknown_challenge",
+    "credentials_auth_unknown_pending_challenge",
+    "STATEFUL_FORWARDING_NOT_CONFIGURED",
+    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
+    "STATEFUL_FORWARDING_NONCE_INVALID",
+    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
+    "STATEFUL_FORWARDING_REPLAY_DETECTED",
+    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+    "STATEFUL_FORWARDING_REQUEST_FAILED",
+    "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_BAD_RESPONSE",
+    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -530,7 +632,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+    const details = errorObservabilityDetails(error);
+    const isUnregisteredProviderErrorCode = status === 500 &&
+        isProviderError(error) &&
+        !isValidationError(error) &&
+        typeof error.code === "string" &&
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -544,15 +651,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(isTransportError(error) && error.upstreamStatus
-            ? { upstreamStatus: error.upstreamStatus }
-            : {}),
-        ...(details
-            ? {
-                errorCategory: details.category,
-                taxonomyVersion: details.taxonomyVersion,
-                retryable: details.retryable,
-            }
+        ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+        errorCategory: details.category,
+        taxonomyVersion: details.taxonomyVersion,
+        retryable: details.retryable,
+        ...(isUnregisteredProviderErrorCode
+            ? { signal: "unregistered_provider_error_code" }
             : {}),
         ...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
     });
@@ -1150,12 +1254,10 @@ export function createServerApp(provider, options = {}) {
             missingSecrets: missingSecretsAtBoot,
         });
     }
-    app.notFound((c) => c.json({
-        error: {
-            code: "not_found",
-            message: "Not found",
-        },
-    }, 404));
+    app.notFound((c) => {
+        const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+        return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+    });
     app.get("/health", (c) => c.json({
         status: "ok",
         provider: provider.id,
@@ -1272,7 +1374,7 @@ export function createServerApp(provider, options = {}) {
             }
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1306,7 +1408,7 @@ export function createServerApp(provider, options = {}) {
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/start", async (c) => {
@@ -1326,7 +1428,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/continue", async (c) => {
@@ -1346,7 +1448,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/poll", async (c) => {
@@ -1366,7 +1468,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/refresh", async (c) => {
@@ -1386,7 +1488,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/disconnect", async (c) => {
@@ -1406,7 +1508,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     return app;

package/dist/server/types.d.ts

@@ -42,6 +42,7 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodBoolean;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -84,6 +85,7 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -121,6 +123,7 @@ export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -21,6 +21,7 @@ export const ErrorEnvelopeSchema = z.object({
     code: z.string(),
     message: z.string(),
     requestId: z.string().optional(),
+    retryable: z.boolean(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });

package/dist/stateful/stateful-provider-owner-forwarder.js

@@ -9,6 +9,14 @@ export const STATEFUL_FORWARDING_NONCE_HEADER = "x-apifuse-stateful-nonce";
 export const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
 const MAX_FORWARDED_HEADERS = 32;
 const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+    error: OperationErrorResponseSchema.shape.error.extend({
+        retryable: z.boolean().optional().default(false),
+    }),
+});
 const SENSITIVE_HEADER_NAMES = new Set([
     "authorization",
     "cookie",
@@ -183,7 +191,7 @@ async function parseForwardedResponse(response) {
     if (response.ok && success.success) {
         return { output: success.data.data };
     }
-    const error = OperationErrorResponseSchema.safeParse(body);
+    const error = ForwardedOperationErrorResponseSchema.safeParse(body);
     if (error.success) {
         throw new StatefulOwnerForwardingError({
             code: error.data.error.code,

package/dist/stream-evidence.d.ts

@@ -0,0 +1,74 @@
+import { type JsonValue } from "./contract-json.js";
+import type { HttpStreamResponse } from "./types.js";
+export declare const STREAM_PREVIEW_BYTES = 4096;
+export declare const STREAM_FINALIZE_TIMEOUT_MS = 30000;
+declare const STREAM_EVIDENCE_HEADER_NAMES: readonly ["content-disposition", "content-length", "content-type"];
+type StreamEvidenceHeaderName = (typeof STREAM_EVIDENCE_HEADER_NAMES)[number];
+export type StreamEvidenceHeaders = Partial<Record<StreamEvidenceHeaderName, string>>;
+export interface StreamEvidenceRequest {
+    ordinal: number;
+    method: string;
+    path: string;
+}
+declare const STREAM_EVIDENCE_REDACTION_REASONS: readonly ["high-entropy-token", "malformed-json", "pem-private-key", "sanitized-preview-too-large", "sanitizer-output-invalid", "sensitive-delimited-column", "textual-xml", "truncated-form", "truncated-json", "undecodable-text"];
+export type StreamEvidenceRedactionReason = (typeof STREAM_EVIDENCE_REDACTION_REASONS)[number];
+export interface StreamEvidenceRecord {
+    __apifuse_stream__: true;
+    status: number;
+    ok: boolean;
+    headers: StreamEvidenceHeaders;
+    body_sha256: string;
+    body_bytes: number;
+    body_preview_base64: string;
+    request?: StreamEvidenceRequest;
+    preview_sanitized?: true;
+    preview_redaction_reason?: StreamEvidenceRedactionReason;
+}
+export type StreamEvidenceReplayResponse = HttpStreamResponse & {
+    evidence_only: true;
+    body_sha256: string;
+    body_bytes: number;
+    preview_sanitized?: true;
+    preview_redaction_reason?: StreamEvidenceRedactionReason;
+};
+export interface StreamEvidenceCapture {
+    response: HttpStreamResponse;
+    getEvidence(): Promise<StreamEvidenceRecord>;
+}
+export type StreamCaptureGroupItem = {
+    kind: "stream";
+    evidence: StreamEvidenceRecord;
+} | {
+    kind: "response";
+    value: JsonValue;
+};
+export interface StreamCaptureGroup {
+    items: StreamCaptureGroupItem[];
+}
+export interface StreamCaptureEnvelope {
+    __apifuse_capture__: true;
+    items: StreamCaptureGroupItem[];
+}
+export type StreamEvidenceCaptureOptions = {
+    requestUrl: string;
+    sanitizeFixture?: (value: JsonValue) => JsonValue;
+    request?: StreamEvidenceRequest;
+    finalizeTimeoutMs?: number;
+};
+export declare function parseStreamEvidenceRecord(value: unknown): StreamEvidenceRecord;
+export declare function isStreamEvidenceRecord(value: unknown): value is StreamEvidenceRecord;
+export declare function findStreamEvidenceRecord(value: unknown): StreamEvidenceRecord | undefined;
+/**
+ * Selects every stream captured by the latest recording invocation, in stream call order.
+ * Evidence without request ordinals uses the legacy latest-record-only behavior.
+ */
+export declare function findStreamEvidenceRecords(value: unknown): StreamEvidenceRecord[];
+/** Returns a tagged latest mixed response group used by evidence-only snapshot replay. */
+export declare function findStreamCaptureGroup(value: unknown): StreamCaptureGroup | undefined;
+/** Creates a discriminated invocation envelope so ordinary arrays cannot mimic capture timelines. */
+export declare function createStreamCaptureEnvelope(items: StreamCaptureGroupItem[]): StreamCaptureEnvelope;
+export declare function isStreamEvidenceReplayResponse(response: HttpStreamResponse): response is StreamEvidenceReplayResponse;
+export declare function captureStreamEvidence(response: HttpStreamResponse, options: StreamEvidenceCaptureOptions): StreamEvidenceCapture;
+export declare function replayStreamEvidence(evidence: StreamEvidenceRecord): StreamEvidenceReplayResponse;
+export declare function hasStreamEvidenceMarker(value: unknown): boolean;
+export {};