@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/dist/runtime/stt.js

@@ -1,4 +1,5 @@
 import { ProviderError, TransportError, ValidationError } from "../errors.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -112,12 +113,6 @@ function warnOrThrowUnsupportedOption(request, message) {
 function normalizeCloudflareLanguage(language) {
     return language?.split("-")[0]?.toLowerCase();
 }
-function isTimeoutLikeError(error) {
-    return (error instanceof Error &&
-        (error.name === "AbortError" ||
-            error.name === "TimeoutError" ||
-            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
-}
 function toSttTransportError(error) {
     if (error instanceof TransportError)
         return error;
@@ -134,12 +129,6 @@ function toSttTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function createTimeoutController(signalTimeoutMs) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-    timeout.unref?.();
-    return { controller, clear: () => clearTimeout(timeout) };
-}
 function toCloudflareInput(request) {
     const prompt = resolveSttPrompt(request);
     const input = {

package/dist/runtime/timeout.d.ts

@@ -0,0 +1,5 @@
+export declare function isTimeoutLikeError(error: unknown): error is Error;
+export declare function createTimeoutController(signalTimeoutMs: number): {
+    controller: AbortController;
+    clear: () => void;
+};

package/dist/runtime/timeout.js

@@ -0,0 +1,12 @@
+export function isTimeoutLikeError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" ||
+            error.name === "TimeoutError" ||
+            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
+}
+export function createTimeoutController(signalTimeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+    timeout.unref?.();
+    return { controller, clear: () => clearTimeout(timeout) };
+}

package/dist/runtime/trace-config.d.ts

@@ -0,0 +1,12 @@
+import type { TraceConfig } from "../types.js";
+/** SDK-owned environment variable names for server trace output. */
+export declare const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export declare const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export declare function resolveTraceConfigFromEnv(env?: EnvLike): TraceConfig | undefined;
+export {};

package/dist/runtime/trace-config.js

@@ -0,0 +1,61 @@
+/** SDK-owned environment variable names for server trace output. */
+export const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+const TRACE_EXPORTER_LOOKUP = {
+    console: true,
+    json: true,
+    none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+const emittedWarnings = new Set();
+function warnOnce(key, message) {
+    if (emittedWarnings.has(key))
+        return;
+    emittedWarnings.add(key);
+    console.warn(message);
+}
+function parseEnabled(raw) {
+    if (raw === undefined)
+        return undefined;
+    switch (raw.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+            return true;
+        case "0":
+        case "false":
+        case "no":
+        case "off":
+            return false;
+        default:
+            warnOnce(APIFUSE__TRACE__ENABLED, "[apifuse] Invalid APIFUSE__TRACE__ENABLED; falling back to disabled tracing.");
+            return false;
+    }
+}
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export function resolveTraceConfigFromEnv(env = process.env) {
+    const enabledRaw = env[APIFUSE__TRACE__ENABLED];
+    const exporterRaw = env[APIFUSE__TRACE__EXPORTER];
+    if (enabledRaw === undefined && exporterRaw === undefined) {
+        return undefined;
+    }
+    const enabled = parseEnabled(enabledRaw);
+    const normalizedExporter = exporterRaw?.trim().toLowerCase();
+    const exporter = TRACE_EXPORTERS.has(normalizedExporter)
+        ? normalizedExporter
+        : exporterRaw === undefined
+            ? undefined
+            : "none";
+    if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
+        warnOnce(APIFUSE__TRACE__EXPORTER, `[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}" (OTLP is unsupported for server output); supported exporters are "console", "json", and "none"; falling back to exporter "none".`);
+    }
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(exporter !== undefined ? { exporter } : {}),
+    };
+}

package/dist/serve.d.ts

@@ -1 +1 @@
-export { createServerApp, type ServeOptions, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, type ServeOptions, serve, } from "./server/serve.js";

package/dist/serve.js

@@ -1 +1 @@
-export { createServerApp, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, serve, } from "./server/serve.js";

package/dist/server/index.d.ts

@@ -1,6 +1,8 @@
-export { createServerApp, type ServeOptions, serve } from "./serve.js";
-export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
+export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
+export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
-export { createServerApp, serve } from "./serve.js";
-export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
+export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

package/dist/server/self-test-input-tokens.d.ts

@@ -1 +1,2 @@
-export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date): unknown;
+export type InputDateTokenCalendar = "KST" | "UTC";
+export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date, calendar?: InputDateTokenCalendar): unknown;

package/dist/server/self-test-input-tokens.js

@@ -1,20 +1,20 @@
 /**
- * Relative-KST date token resolution for health-check case inputs, ported from
- * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
- * so provider self-tests resolve durable probe inputs identically.
+ * Relative date-token resolution for health-check case inputs and fixture
+ * requests. The calendar defaults to KST; callers that need UTC must opt in
+ * explicitly so UTC and KST do not silently disagree from 15:00–23:59 UTC.
  *
- * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead).
  */
-const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
-function dateFromKstDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD") {
-    const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
-    const date = new Date(Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead));
+const RELATIVE_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+function dateFromDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD", calendar = "KST") {
+    const calendarNow = new Date(now.getTime() + (calendar === "KST" ? 9 * 60 * 60 * 1000 : 0));
+    const date = new Date(Date.UTC(calendarNow.getUTCFullYear(), calendarNow.getUTCMonth(), calendarNow.getUTCDate() + daysAhead));
     const isoDate = date.toISOString().slice(0, 10);
     return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
 }
-export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
+export function resolveHealthCheckInputDateTokens(value, now = new Date(), calendar = "KST") {
     if (typeof value === "string") {
-        const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+        const relative = value.match(RELATIVE_DATE_TOKEN);
         if (!relative)
             return value;
         const daysAhead = Number(relative[1]);
@@ -22,16 +22,20 @@ export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
             return value;
         }
         const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
-        return dateFromKstDaysAhead(daysAhead, now, format);
+        return dateFromDaysAhead(daysAhead, now, format, calendar);
     }
     if (Array.isArray(value)) {
-        return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+        const resolved = value.map((entry) => resolveHealthCheckInputDateTokens(entry, now, calendar));
+        return resolved.some((entry, index) => entry !== value[index]) ? resolved : value;
     }
     if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        const resolved = Object.fromEntries(Object.entries(value).map(([key, entry]) => [
             key,
-            resolveHealthCheckInputDateTokens(entry, now),
+            resolveHealthCheckInputDateTokens(entry, now, calendar),
         ]));
+        return Object.entries(resolved).some(([key, entry]) => entry !== Reflect.get(value, key))
+            ? resolved
+            : value;
     }
     return value;
 }

package/dist/server/self-test.d.ts

@@ -51,25 +51,80 @@ export interface SelfTestResponse {
     result?: SelfTestCaseResult;
     results: SelfTestCaseResult[];
 }
+export interface SelfTestCancellationLogEvent {
+    level: "info";
+    event: "self_test_run_cancelled";
+    providerId: string;
+    requestId: string;
+    operationId: string;
+    caseName: string;
+    reason: string;
+}
 export type SelfTestOperationInvoke = (args: {
     operationId: string;
     input: unknown;
     connection?: OperationConnection;
     requestId: string;
+    signal?: AbortSignal;
 }) => Promise<{
     status: number;
     data: unknown;
     meta?: Record<string, unknown>;
 }>;
+export type SelfTestAuthFlowRoute = "start" | "continue";
+/**
+ * In-process driver for the tenant app's /auth pipeline. Self-test uses it to
+ * materialize `requiresConnection` credentials through the provider's declared
+ * auth flow — the exact path production connections take — instead of
+ * injecting raw credential inputs as connection secrets.
+ */
+export type SelfTestAuthFlowInvoke = (args: {
+    route: SelfTestAuthFlowRoute;
+    requestId: string;
+    flowId: string;
+    /** Stable per-credential connection id — keeps login on the probe's affinity. */
+    connectionId?: string;
+    /** The probe connection's externalRef — flows reading ctx.externalRef see the same identity. */
+    externalRef?: string;
+    input?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+/**
+ * Skip reason reported when a declared auth flow does not complete in a single
+ * continue (OTP, retry loop). Cross-repo contract: the health-monitor maps
+ * this exact string to `self_test_incapable`; never vary it.
+ */
+export declare const SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON = "auth_flow_multi_turn";
+/**
+ * A `retry` turn after credential submission: the flow REJECTED the
+ * configured inputs (bad password, exchange failure). Distinct from the
+ * multi-turn gap so monitoring surfaces it as a real credential outage, and
+ * memoized like multi-turn so the probe does not re-submit rejected
+ * credentials every cycle (lockout safety).
+ */
+export declare const SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON = "auth_flow_rejected";
 export interface SelfTestAppOptions {
     /** Derived-token verification secrets; without them every self-test route 404s. */
     secrets?: SelfTestMasterSecrets;
     /** In-process invoke bound to the tenant-facing app's /v1 pipeline. */
     invoke: SelfTestOperationInvoke;
+    /**
+     * In-process auth-flow driver bound to the tenant-facing app's /auth
+     * pipeline. Required for providers that declare `auth.mode: "credentials"`
+     * with a flow; without it their requiresConnection cases report a visible
+     * auth_flow_unavailable error instead of probing with raw inputs.
+     */
+    authFlow?: SelfTestAuthFlowInvoke;
     /** Overall request budget; defaults to env / 120s. */
     requestBudgetMs?: number;
     /** Env override for secret collection + budget resolution (tests). */
     env?: Readonly<Record<string, string | undefined>>;
+    /** Structured server logger; defaults to the same JSON console shape as the provider server. */
+    logger?: (event: SelfTestCancellationLogEvent) => void;
 }
 /**
  * Stable sha256 over the provider's declared health plan (operations, case
@@ -88,6 +143,65 @@ export declare function isSelfTestReadOnlyOperation(operation: OperationDefiniti
 export declare function createSelfTestInvoke(app: {
     request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
 }): SelfTestOperationInvoke;
+/** Binds the self-test auth-flow driver to a tenant app's /auth pipeline in-process. */
+export declare function createSelfTestAuthFlowInvoke(app: {
+    request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
+}): SelfTestAuthFlowInvoke;
+/**
+ * How long a memoized multi-turn flow outcome suppresses re-driving the auth
+ * flow. Generous on purpose: a multi-turn ceremony (OTP, device approval) is a
+ * provider property that changes on the timescale of releases, not probe
+ * cycles, and every re-drive is a REAL upstream login submission. The cache is
+ * in-process, so a pod restart also clears the entry.
+ */
+export declare const SELF_TEST_MULTI_TURN_RETRY_AFTER_MS: number;
+/**
+ * Age bound for POSITIVE cached credentials. Expiry modes that never produce
+ * a 401/403 (a 200 login page, an assertion failure) would otherwise replay
+ * the same stale session until pod restart — one re-login per day is the
+ * upstream-safe recovery for them.
+ */
+export declare const SELF_TEST_CREDENTIAL_MAX_AGE_MS: number;
+export type SelfTestCredentialSessionEntry = 
+/** Flow-materialized credential reused across probe cycles. */
+{
+    kind: "credential";
+    credential: Record<string, string>;
+    cachedAtMs: number;
+}
+/**
+ * Negative entry: the flow did not complete in a single continue turn
+ * (`auth_flow_multi_turn`). Memoized so subsequent cycles report the skip
+ * WITHOUT contacting the upstream again — the first attempt already
+ * submitted real credentials (and may have triggered an OTP send).
+ */
+ | {
+    kind: "multi_turn";
+    cachedAtMs: number;
+}
+/**
+ * Negative entry: the flow REJECTED the submitted credential inputs
+ * (`retry` turn after continue — bad password, exchange failure).
+ * Memoized so the probe does not re-submit rejected credentials every
+ * cycle; a new entry is attempted when the inputs rotate (new hash),
+ * the TTL lapses, or the process restarts.
+ */
+ | {
+    kind: "rejected";
+    cachedAtMs: number;
+};
+/**
+ * In-process cache of per-(providerId + stable hash of credentialInputs) auth
+ * flow outcomes, so consecutive probe cycles reuse the session — or the
+ * memoized multi-turn skip — instead of logging in every cycle (upstream
+ * account safety, DR-7). Credential entries are invalidated on a probe auth
+ * failure, at most once; multi-turn entries expire after
+ * `SELF_TEST_MULTI_TURN_RETRY_AFTER_MS` or on process restart. Flow ERRORS
+ * (transport/protocol failures, thrown start/continue) are deliberately NEVER
+ * cached: they are typically transient, and retrying a failed request next
+ * cycle is not a repeated login submission.
+ */
+export type SelfTestCredentialSessionCache = Map<string, SelfTestCredentialSessionEntry>;
 export declare function resolveSelfTestPort(env?: Readonly<Record<string, string | undefined>>): number;
 /**
  * Builds the internal self-test Hono app. This app is served on a SEPARATE