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

package/dist/schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { ValidationError } from "./errors";
-import { providerLocaleKey } from "./i18n/keys";
+import { ValidationError } from "./errors.js";
+import { providerLocaleKey } from "./i18n/keys.js";
 export { z };
 function isFailureResult(result) {
     return "issues" in result;
@@ -99,21 +99,15 @@ export function field(schema, options = {}) {
     const metadata = described.meta() ?? {};
     return described.meta({
         ...metadata,
-        ...((options.sensitive ?? true)
-            ? { [APIFUSE_SENSITIVE_META_KEY]: true }
-            : {}),
-        ...(options.kind
-            ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind }
-            : {}),
+        ...((options.sensitive ?? true) ? { [APIFUSE_SENSITIVE_META_KEY]: true } : {}),
+        ...(options.kind ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind } : {}),
     });
 }
 export function sensitive(schema, kind) {
     return field(schema, { sensitive: true, kind });
 }
 function sensitiveString(kind, description, options = {}) {
-    const schema = options.minLength === undefined
-        ? z.string()
-        : z.string().min(options.minLength);
+    const schema = options.minLength === undefined ? z.string() : z.string().min(options.minLength);
     return field(schema, {
         kind,
         description: options.description ?? description,
@@ -132,8 +126,7 @@ export const fields = {
 };
 export function isSensitiveSchema(schema) {
     const metadata = readZodMetadata(schema);
-    return (metadata !== undefined &&
-        Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true);
+    return metadata !== undefined && Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true;
 }
 export function collectSensitivePaths(schema) {
     const out = [];
@@ -217,8 +210,7 @@ function pathMatches(path, patterns) {
 }
 function isReservedSensitiveKey(key) {
     const normalized = key.toLowerCase().replace(/[-_\s]/g, "");
-    return (RESERVED_SENSITIVE_KEYS.has(normalized) ||
-        RESERVED_SENSITIVE_KEYS.has(key.toLowerCase()));
+    return RESERVED_SENSITIVE_KEYS.has(normalized) || RESERVED_SENSITIVE_KEYS.has(key.toLowerCase());
 }
 function readZodMetadata(schema) {
     if (!schema || typeof schema !== "object" || !("meta" in schema)) {

package/dist/serve.d.ts

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

package/dist/serve.js

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

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-export { createServerApp, type ServeOptions, serve } from "./serve";
-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";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
-export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction";
-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";
-export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types";
-export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";
+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 { 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";
+export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
-export { createServerApp, serve } from "./serve";
-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";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
-export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction";
-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";
-export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";
+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 { 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-redaction.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderDefinition } from "../types";
+import type { ProviderDefinition } from "../types.js";
 export declare const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
 /** Maximum length of any string echoed in a self-test response. */
 export declare const SELF_TEST_MAX_TEXT_LENGTH = 300;

package/dist/server/self-test-redaction.js

@@ -1,4 +1,4 @@
-import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token";
+import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token.js";
 export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
 /** Maximum length of any string echoed in a self-test response. */
 export const SELF_TEST_MAX_TEXT_LENGTH = 300;

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

@@ -1,8 +1,8 @@
 import { Hono } from "hono";
 import { z } from "zod";
-import type { OperationDefinition, ProviderDefinition } from "../types";
-import { type SelfTestMasterSecrets } from "./self-test-token";
-import type { OperationConnection } from "./types";
+import type { OperationDefinition, ProviderDefinition } from "../types.js";
+import { type SelfTestMasterSecrets } from "./self-test-token.js";
+import type { OperationConnection } from "./types.js";
 export declare const SELF_TEST_SCHEMA_VERSION: 1;
 export declare const SELF_TEST_PATH = "/internal/health/self-test";
 export declare const SELF_TEST_HEALTHZ_PATH = "/healthz";

package/dist/server/self-test.js

@@ -2,9 +2,9 @@ import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { Hono } from "hono";
 import { z } from "zod";
-import { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
-import { collectSelfTestSensitiveValues, redactSelfTestText } from "./self-test-redaction";
-import { DEFAULT_SELF_TEST_PORT, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, verifySelfTestAuthorization, } from "./self-test-token";
+import { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+import { collectSelfTestSensitiveValues, redactSelfTestText } from "./self-test-redaction.js";
+import { DEFAULT_SELF_TEST_PORT, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, verifySelfTestAuthorization, } from "./self-test-token.js";
 export const SELF_TEST_SCHEMA_VERSION = 1;
 export const SELF_TEST_PATH = "/internal/health/self-test";
 export const SELF_TEST_HEALTHZ_PATH = "/healthz";

package/dist/server/serve.d.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
-import { type ProviderErrorCategory } from "../observability";
-import type { ProviderDefinition, ProviderRuntimeState, SttContext } from "../types";
-import { type OperationRequest } from "./types";
+import { type ProviderErrorCategory } from "../observability.js";
+import type { ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
+import { type OperationRequest } from "./types.js";
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
 type ProviderRequestCost = {
     durationMs: number;

package/dist/server/serve.js

@@ -2,32 +2,32 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
-import { AuthAbortError, createAuthFlowHelpers } from "../auth";
-import { AuthError, ProviderError, SessionExpiredError, TransportError, } from "../errors";
-import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog";
-import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability";
-import { createScratchpad } from "../runtime/auth-flow";
-import { createBrowserClient } from "../runtime/browser";
-import { createProviderCache } from "../runtime/cache";
-import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice";
-import { createCredentialContext } from "../runtime/credential";
-import { createEnvContext } from "../runtime/env";
-import { executeOperation } from "../runtime/executor";
-import { createHttpClient } from "../runtime/http";
-import { wrapWithInstrumentation } from "../runtime/instrumentation";
-import { getProviderBaseUrl } from "../runtime/provider";
-import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors";
-import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry";
-import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state";
-import { createStealthClient } from "../runtime/stealth";
-import { createSttClientFromEnv } from "../runtime/stt";
-import { createTraceContext } from "../runtime/trace";
-import { parseSchema } from "../schema";
-import { getStealthProfile } from "../stealth/profiles";
-import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream";
-import { createSelfTestApp, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test";
-import { resolveSelfTestMasterSecrets } from "./self-test-token";
-import { AuthFlowRequestSchema, OperationRequestSchema, } from "./types";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, 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";
+import { createBrowserClient } from "../runtime/browser.js";
+import { createProviderCache } from "../runtime/cache.js";
+import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice.js";
+import { createCredentialContext } from "../runtime/credential.js";
+import { createEnvContext } from "../runtime/env.js";
+import { executeOperation } from "../runtime/executor.js";
+import { createHttpClient } from "../runtime/http.js";
+import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import { getProviderBaseUrl } from "../runtime/provider.js";
+import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
+import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
+import { createStealthClient } from "../runtime/stealth.js";
+import { createSttClientFromEnv } from "../runtime/stt.js";
+import { createTraceContext } from "../runtime/trace.js";
+import { parseSchema } from "../schema.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
+import { createSelfTestApp, createSelfTestInvoke, resolveSelfTestPort } from "./self-test.js";
+import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
+import { AuthFlowRequestSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
@@ -93,9 +93,7 @@ function getProviderStealthBaseUrl(provider) {
     return firstHost ? `https://${firstHost}` : undefined;
 }
 function getProviderStealthProfile(provider) {
-    return provider.stealth?.profile
-        ? getStealthProfile(provider.stealth.profile)
-        : undefined;
+    return provider.stealth?.profile ? getStealthProfile(provider.stealth.profile) : undefined;
 }
 function isProductionProviderBrowserMode(provider, env = process.env) {
     if (provider.runtime !== "browser") {
@@ -104,13 +102,11 @@ function isProductionProviderBrowserMode(provider, env = process.env) {
     if (env.APIFUSE__PROVIDER__RUNTIME === "browser") {
         return true;
     }
-    return (env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id);
+    return env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id;
 }
 export function resolveProviderProxyAffinityKey(provider, request, operationId) {
     const connectionKey = resolveOperationConnectionId(request) ?? request.connection?.externalRef;
-    const affinity = typeof provider.proxy === "object"
-        ? provider.proxy.session?.affinity
-        : undefined;
+    const affinity = typeof provider.proxy === "object" ? provider.proxy.session?.affinity : undefined;
     if (affinity === "operation") {
         return `${provider.id}/${operationId}`;
     }
@@ -293,7 +289,7 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         const details = publicProviderErrorDetails(error);
         return {
             error: {
@@ -343,20 +339,25 @@ function publicProviderErrorDetails(error) {
 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
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
 function providerObservabilityDetails(error) {
     // Session-expiry surfaces the credential_expired category + the opt-in
     // retryable signal so Gateway/Credential Service can refresh and re-drive the
     // operation (see design.md §4.3 D3). Without this branch the auth error would
     // serialize as a bare 401 with no retryable/category, losing the refresh
     // signal for exactly the retryOnAuthRefresh operations it is meant to enable.
-    if (error instanceof SessionExpiredError) {
+    if (isSessionExpiredError(error)) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: error.options?.retryable ?? false,
         };
     }
-    if (!(error instanceof TransportError)) {
+    if (!isTransportError(error)) {
         return undefined;
     }
     const isProxyPoolCode = error.code === PROXY_POOL_EXHAUSTED_CODE ||
@@ -385,7 +386,7 @@ function providerObservabilityDetails(error) {
     };
 }
 function publicProviderErrorMessage(error) {
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
             return error.message;
         }
@@ -413,10 +414,10 @@ function toStatusCode(error) {
     if (error instanceof z.ZodError) {
         return 400;
     }
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         return error.code === "transport_timeout" ? 504 : 502;
     }
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -448,16 +449,14 @@ function extractRequestId(raw) {
     return typeof value === "string" ? value : undefined;
 }
 function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
-    const code = error instanceof ProviderError
+    const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
             ? "invalid_request"
             : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = error instanceof ProviderError
-        ? providerObservabilityDetails(error)
-        : undefined;
+    const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -471,7 +470,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(error instanceof TransportError && error.upstreamStatus
+        ...(isTransportError(error) && error.upstreamStatus
             ? { upstreamStatus: error.upstreamStatus }
             : {}),
         ...(details
@@ -594,8 +593,7 @@ async function validateSseEvent(operation, event) {
     const transport = getSseTransport(operation);
     const schema = transport?.events?.[event.event];
     if (!schema) {
-        if (event.event === APIFUSE_STREAM_ERROR_EVENT ||
-            event.event === APIFUSE_STREAM_DONE_EVENT) {
+        if (event.event === APIFUSE_STREAM_ERROR_EVENT || event.event === APIFUSE_STREAM_DONE_EVENT) {
             return event;
         }
         throw new ProviderError(`SSE event "${event.event}" is not declared in operation transport.events.`, {
@@ -714,8 +712,7 @@ function enforceStreamChunkLimit(body, maxChunkBytes) {
 }
 function toStreamingResponse(operation, result, cleanup, requestId) {
     const transport = operation.transport?.kind ?? "json";
-    if (transport === "sse" &&
-        (result instanceof Response || result instanceof ReadableStream)) {
+    if (transport === "sse" && (result instanceof Response || result instanceof ReadableStream)) {
         void cleanup();
         throw new ProviderError("SSE operations must return an AsyncIterable of typed stream.event(...) values.", {
             code: "SSE_RESULT_UNSUPPORTED",
@@ -726,9 +723,7 @@ function toStreamingResponse(operation, result, cleanup, requestId) {
     }
     if (result instanceof Response) {
         const httpTransport = getHttpStreamTransport(operation);
-        if (httpTransport &&
-            result.body &&
-            httpTransport?.maxChunkBytes !== undefined) {
+        if (httpTransport && result.body && httpTransport?.maxChunkBytes !== undefined) {
             return responseWithCleanup(new Response(enforceStreamChunkLimit(result.body, httpTransport.maxChunkBytes), {
                 headers: result.headers,
                 status: result.status,
@@ -747,8 +742,7 @@ function toStreamingResponse(operation, result, cleanup, requestId) {
                 ? { "Content-Type": "text/event-stream; charset=utf-8" }
                 : {
                     "Content-Type": operation.transport?.kind === "http-stream"
-                        ? (operation.transport.contentType ??
-                            "application/octet-stream")
+                        ? (operation.transport.contentType ?? "application/octet-stream")
                         : "application/octet-stream",
                 },
         }), cleanup);
@@ -766,9 +760,7 @@ function getSseTransport(operation) {
     return operation.transport?.kind === "sse" ? operation.transport : undefined;
 }
 function getHttpStreamTransport(operation) {
-    return operation.transport?.kind === "http-stream"
-        ? operation.transport
-        : undefined;
+    return operation.transport?.kind === "http-stream" ? operation.transport : undefined;
 }
 function toAuthFlowResponse(result, contextPatch) {
     if (result instanceof Response) {
@@ -796,7 +788,7 @@ function isAuthFlowLocale(value) {
     return value === "en" || value === "ko" || value === "ja";
 }
 function isAuthTurn(value) {
-    return (!!value && typeof value === "object" && "kind" in value && "turnId" in value);
+    return !!value && typeof value === "object" && "kind" in value && "turnId" in value;
 }
 function loadAuthFlowLocaleCatalogs(provider) {
     for (const providerDir of [

package/dist/server/types.js

@@ -1,11 +1,6 @@
 import { z } from "zod";
-import { HttpRetryPreset } from "../types";
-export const ConnectionModeSchema = z.enum([
-    "oauth2",
-    "credentials",
-    "platform-managed",
-    "none",
-]);
+import { HttpRetryPreset } from "../types.js";
+export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
 export const OperationConnectionSchema = z.object({
     id: z.string(),
     mode: ConnectionModeSchema,

package/dist/stealth/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { StealthProfile } from "../types";
+import type { StealthProfile } from "../types.js";
 export declare function generateLayer2Headers(profile: StealthProfile): Record<string, string>;
 export declare function getStealthProfile(name: string): StealthProfile;
 export declare function listStealthProfiles(): string[];

package/dist/stealth/profiles.js

@@ -1,4 +1,4 @@
-import { SDKError } from "../errors";
+import { SDKError } from "../errors.js";
 const CHROMIUM_HEADER_ORDER = [
     ":method",
     ":authority",
@@ -74,12 +74,8 @@ function createProfile(name, definition) {
         tlsClientIdentifier: definition.tlsClientIdentifier,
         ja3: definition.ja3,
         ja4: definition.ja4,
-        h2Settings: definition.h2Settings
-            ? { ...definition.h2Settings }
-            : undefined,
-        headerOrder: definition.headerOrder
-            ? [...definition.headerOrder]
-            : undefined,
+        h2Settings: definition.h2Settings ? { ...definition.h2Settings } : undefined,
+        headerOrder: definition.headerOrder ? [...definition.headerOrder] : undefined,
     };
 }
 function extractBrowserMajorVersion(profile) {
@@ -120,9 +116,7 @@ export function generateLayer2Headers(profile) {
             : `"Chromium";v="${majorVersion}", "Google Chrome";v="${majorVersion}", "Not)A;Brand";v="99"`;
         headers["Sec-Ch-Ua-Platform"] = toPlatformHeaderValue(profile.platform);
         headers["Sec-Ch-Ua-Mobile"] =
-            profile.platform === "android" || profile.platform === "ios"
-                ? "?1"
-                : "?0";
+            profile.platform === "android" || profile.platform === "ios" ? "?1" : "?0";
     }
     return headers;
 }
@@ -252,8 +246,5 @@ export function getStealthProfile(name) {
     };
 }
 export function listStealthProfiles() {
-    return [
-        ...Object.keys(STEALTH_PROFILES),
-        ...Object.keys(STEALTH_PROFILE_ALIASES),
-    ];
+    return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
 }

package/dist/stream.d.ts

@@ -1,4 +1,4 @@
-import type { SseMessage } from "./types";
+import type { SseMessage } from "./types.js";
 export interface SseEvent<TData = unknown> {
     event: string;
     data: TData;

package/dist/testing/index.d.ts

@@ -1,2 +1,2 @@
-export { describeTransform, snapshotTransform, toMatchShape } from "./helpers";
-export { runStandardTests } from "./run";
+export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { runStandardTests } from "./run.js";

package/dist/testing/index.js

@@ -1,2 +1,2 @@
-export { describeTransform, snapshotTransform, toMatchShape } from "./helpers";
-export { runStandardTests } from "./run";
+export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { runStandardTests } from "./run.js";

package/dist/testing/run.d.ts

@@ -1,4 +1,4 @@
-import type { AuthMode, ProviderDefinition } from "../types";
+import type { AuthMode, ProviderDefinition } from "../types.js";
 export interface StandardTestsManifest {
     id?: string;
     displayName?: string;

package/dist/testing/run.js

@@ -1,19 +1,14 @@
 import { describe, expect, it } from "bun:test";
-import { createProviderCache } from "../runtime/cache";
-import { createTestProviderChoiceContext } from "../runtime/choice";
-import { createMemoryProviderRuntimeState } from "../runtime/state";
-import { createUnsupportedSttClient } from "../runtime/stt";
-import { safeParseSchemaSync } from "../schema";
+import { createProviderCache } from "../runtime/cache.js";
+import { createTestProviderChoiceContext } from "../runtime/choice.js";
+import { createMemoryProviderRuntimeState } from "../runtime/state.js";
+import { createUnsupportedSttClient } from "../runtime/stt.js";
+import { safeParseSchemaSync } from "../schema.js";
 // Mirrors CONNECTOR_ID_REGEX in ../define.ts, which defineProvider() enforces.
 // A single lowercase segment (no hyphen) is a valid id, so the trailing group
 // is optional (`*`), matching providers like `kakaomap`, `kstartup`, `triple`.
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
-const VALID_AUTH_MODES = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 function isFixtureEnvelope(value) {
     return (value !== null &&
@@ -60,9 +55,7 @@ function inferFixtureDir(providerId) {
         .map((line) => line.match(/\(?((?:file:\/\/)?[^():]+\.test\.ts)/)?.[1])
         .find((file) => file !== undefined);
     if (testFile) {
-        const pathname = testFile.startsWith("file://")
-            ? new URL(testFile).pathname
-            : testFile;
+        const pathname = testFile.startsWith("file://") ? new URL(testFile).pathname : testFile;
         return `${pathname.replace(/\/[^/]+$/, "")}/../__fixtures__`;
     }
     return `providers/${providerId}/__fixtures__`;

package/dist/types.d.ts

@@ -1418,6 +1418,19 @@ export interface OperationContractMetadata {
     deprecation?: OperationDeprecationMetadata;
 }
 export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
+    /**
+     * Short English display title for the operation. The SDK passes it through
+     * verbatim; the APIFuse registry derives the operation's en locale title
+     * baseline from it (`docs.titleKey` remains available as an explicit key
+     * override).
+     */
+    title?: string;
+    /**
+     * Raw English operation description. The SDK passes it through verbatim;
+     * keyed descriptions via `descriptionKey` remain the primary flow, and
+     * provider lint rules for raw prose descriptions still apply.
+     */
+    description?: string;
     descriptionKey?: ProviderLocaleKeyInput;
     docs?: OperationDocMeta;
     whenToUseKeys?: readonly ProviderLocaleKeyInput[];
@@ -1447,10 +1460,54 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     healthCheck?: HealthCheckSuite<InferSchemaOutput<TInput>, InferSchemaOutput<TOutput>>;
     healthCheckUnsupported?: HealthCheckUnsupported;
 }
+/**
+ * Author-declared deployment overrides accepted as the optional top-level
+ * `deployment` key on `defineProvider()`.
+ *
+ * The SDK passes this object through VERBATIM onto the returned provider
+ * definition — it is typed here but deliberately not deep-validated: the
+ * APIFuse registry builder owns deployment validation and resolves omitted
+ * fields against the runtime deployment profiles. The shape mirrors the
+ * registry's `ProviderDeploymentOverrides` contract; every field is
+ * optional. Note that the deployment `runtime` axis
+ * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
+ * `runtime` (`standard`/`shared`/`browser`).
+ */
+export interface ProviderDeploymentOverrides {
+    runtime?: "shared" | "dedicated" | "browser";
+    language?: "typescript" | "python";
+    replicas?: number;
+    hpa?: {
+        enabled: boolean;
+        minReplicas?: number;
+        maxReplicas?: number;
+        targetCPUUtilizationPercentage?: number;
+    };
+    resources?: {
+        cpu: string;
+        memory: string;
+    };
+    cache?: {
+        redis?: {
+            enabled: boolean;
+            url?: string;
+        };
+    };
+    network?: {
+        additionalTcpPorts?: number[];
+    };
+    buildContext?: string;
+}
 export interface ProviderDefinition {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * Optional deployment overrides, passed through verbatim from
+     * `defineProvider({ deployment })`. Validation and profile resolution are
+     * owned by the APIFuse registry builder, not the SDK.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
     stealth?: {
         profile: string;

package/dist/user-input.d.ts

@@ -0,0 +1,30 @@
+export declare const NEEDS_INPUT_STATUS: "needs_input";
+export interface ProviderSelectionOption {
+    readonly selection_value: string;
+    readonly label: string;
+    readonly [extra: string]: unknown;
+}
+export interface ProviderRequiredSelection {
+    readonly selection_key: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly selection_type?: string;
+    readonly valid_options: readonly ProviderSelectionOption[];
+    readonly [extra: string]: unknown;
+}
+export interface ProviderSelectedOption {
+    readonly selection_key: string;
+    readonly selection_value: string;
+    /** Free-text answer for text-kind selections. */
+    readonly text?: string;
+    /** Quantity for quantity-kind selections. */
+    readonly quantity?: number;
+}
+export interface ProviderNeedsInputPayload {
+    readonly status: typeof NEEDS_INPUT_STATUS;
+    readonly required_selections: readonly ProviderRequiredSelection[];
+    readonly selected_options?: readonly ProviderSelectedOption[];
+    /** Provider-specific fresh state token(s), e.g. `reservation_state`. */
+    readonly [extra: string]: unknown;
+}
+export declare function isProviderNeedsInputPayload(value: unknown): value is ProviderNeedsInputPayload;