@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.64

package/dist/server/types.d.ts

@@ -38,6 +38,7 @@ export declare const OperationRequestSchema: z.ZodObject<{
         metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         externalRef: z.ZodString;
     }, z.core.$strip>>;
+    tenantId: z.ZodOptional<z.ZodString>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;

package/dist/server/types.js

@@ -21,6 +21,13 @@ export const OperationRequestSchema = z.object({
     input: z.record(z.string(), z.unknown()),
     connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
+    /**
+     * Gateway-asserted principal scope: the organization id for customer
+     * subjects, the service-account id for platform service accounts. Absent
+     * on direct calls and self-test. Trusted exactly like `connectionId`; it is
+     * never derived from caller headers or `input`.
+     */
+    tenantId: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),
 });

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

@@ -145,6 +145,7 @@ function buildForwardingEnvelope(input) {
             requestId: input.request.requestId,
             input: input.request.input,
             connection: metadata.connection,
+            ...(metadata.tenantId ? { tenantId: metadata.tenantId } : {}),
             headers: sanitizeForwardedHeaders(metadata.headers),
             ...(metadata.trace ? { trace: metadata.trace } : {}),
         },
@@ -160,12 +161,33 @@ function forwardedMetadata(request) {
     }
     const operationRequest = forwardingContext.operationRequest;
     const connection = OperationConnectionSchema.parse(operationRequest?.connection);
+    const tenantId = forwardedTenantId(operationRequest?.tenantId);
     return {
         connection,
+        ...(tenantId !== undefined ? { tenantId } : {}),
         ...(operationRequest?.headers ? { headers: operationRequest.headers } : {}),
         ...(operationRequest?.trace ? { trace: operationRequest.trace } : {}),
     };
 }
+/**
+ * The runtime context is consumer-supplied and typed `unknown`, and only its
+ * `requestId` is guarded on read. A malformed principal scope must fail at the
+ * source with a forwarding error — the owner would otherwise reject the whole
+ * forwarded operation, and dropping it silently would downgrade a per-principal
+ * policy to the shared scope. `""` is not a principal (same rule as ids on the
+ * ingress envelope), so it is absent rather than invalid.
+ */
+function forwardedTenantId(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new StatefulOwnerForwardingError({
+            code: "STATEFUL_FORWARDING_CONTEXT_INVALID",
+            message: "Stateful operation forwarding requires a string tenantId when it is present.",
+        });
+    }
+    return value;
+}
 function sanitizeForwardedHeaders(headers) {
     if (!headers)
         return {};

package/dist/stateful/stateful-provider-runtime-context.d.ts

@@ -5,6 +5,8 @@ export interface StatefulForwardingRuntimeContext {
     readonly operationRequest?: {
         readonly requestId: string;
         readonly connection?: unknown;
+        /** Gateway-asserted principal scope; forwarded verbatim to the owner pod. */
+        readonly tenantId?: string;
         readonly headers?: Record<string, string>;
         readonly trace?: Record<string, string>;
     };
@@ -24,6 +26,7 @@ export declare function withStatefulLocalProviderContext(providerContext: unknow
 export declare function statefulForwardingContextFromProviderRequest(request: {
     readonly requestId: string;
     readonly connection?: unknown;
+    readonly tenantId?: string;
     readonly headers?: Record<string, string>;
     readonly trace?: Record<string, string>;
 }): StatefulForwardingRuntimeContext;

package/dist/stateful/stateful-provider-runtime-context.js

@@ -16,6 +16,7 @@ export function statefulForwardingContextFromProviderRequest(request) {
         operationRequest: {
             requestId: request.requestId,
             ...(request.connection !== undefined ? { connection: request.connection } : {}),
+            ...(request.tenantId ? { tenantId: request.tenantId } : {}),
             ...(request.headers ? { headers: request.headers } : {}),
             ...(request.trace ? { trace: request.trace } : {}),
         },

package/dist/types.d.ts

@@ -198,6 +198,25 @@ export interface OcrCaptchaResult {
     readonly model: string;
 }
 export interface OcrContext {
+    /**
+     * Whether this context is backed by a configured OCR backend.
+     *
+     * The SDK owns this verdict: clients built by `createOcrClientFromEnv` for a
+     * configured backend report `true`; the unsupported/error clients handed to
+     * undeclared or misconfigured providers report `false`. Providers branch on
+     * this flag (for example, "require manual CAPTCHA input") instead of probing
+     * the engine-owned `APIFUSE__OCR__*` environment names themselves.
+     *
+     * `true` promises a configured backend, not a successful call: upstream
+     * failures still surface as errors from `recognize` / `extractCaptchaText`.
+     *
+     * Implementations must expose this as an own enumerable data property (not a
+     * getter or prototype member) so that wrappers which spread the context, such
+     * as `bindOcrTelemetry`, preserve it. Custom `OcrContext` overrides passed to
+     * `serve({ ocr })`, `createFlowContext({ ocr })`, or test contexts must set it
+     * explicitly.
+     */
+    readonly available: boolean;
     recognize(request: OcrRecognizeRequest): Promise<OcrResult>;
     extractCaptchaText(image: OcrImageInput, options?: OcrCaptchaOptions): Promise<OcrCaptchaResult>;
 }
@@ -670,6 +689,16 @@ export type HealthCheckCase<TInput = unknown, TOutput = unknown> = {
      *
      * MUST NOT access scheduler, recorder, or any runtime type — pure data
      * + lambda only.
+     *
+     * NOTE: a closure cannot cross the registry's serialization boundary, so
+     * the platform health monitor cannot execute this hook — it runs a case's
+     * serialized `scenario` and nothing else. A case that carries only
+     * `assertions` is still published as a probe, but its outcome is
+     * permanently `unknown` / `monitoring_unavailable`, so the operation
+     * reads as monitored while nothing is being checked. This hook runs only
+     * in the provider runtime's own self-test
+     * (`/internal/health/self-test`). Express anything that must be
+     * monitored in production as a `scenario`.
      */
     assertions: (ctx: HealthCheckAssertionContext<TOutput>) => void | Promise<void> | HealthCheckCaseResult | Promise<HealthCheckCaseResult>;
     /** Declarative scenarios replace the imperative preparation and assertion hooks. */
@@ -782,8 +811,17 @@ export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number
 export interface OperationErrorCode {
     code: string;
     status?: ProviderErrorStatus;
+    /** Developer-facing English prose for docs and MCP tool text. Never localized. */
     description: string;
     retryable?: boolean;
+    /**
+     * Locale catalog key for the client-facing `message` of every error thrown
+     * with this `code`. A throw site's own `messageKey` wins; when neither is
+     * present the SDK derives `errors.<code>.message`.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Derived default: `errors.<code>.fix`. */
+    fixKey?: ProviderLocaleKeyInput;
 }
 export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
 export type StealthBrowser = "chrome" | "firefox" | "safari";
@@ -1039,8 +1077,44 @@ export interface HttpRetrySummary {
     lastErrorCode?: string;
     lastStatus?: number;
 }
+/** Per-attempt input for a `RequestOptions.headers` factory. */
+export interface HttpAttemptContext {
+    /**
+     * 1-based number of this request build: the first request is `1`, its first
+     * retry `2`. Only attempts that reach header resolution count; a failed
+     * proxy allocation or a skipped duplicate proxy offset builds no request
+     * and is not numbered.
+     */
+    attempt: number;
+    /**
+     * Resolved request URL: `baseUrl` + path + `params` + `sensitiveParams`.
+     * It is the exact URL the attempt is issued against, so bind signature
+     * targets to it rather than to a URL the caller rebuilds. Strip the query
+     * and fragment for fields that are defined without them — RFC 9449 §4.2
+     * requires that of DPoP `htu`. It carries any sensitive query values, so
+     * never log it and never copy it verbatim into a signed field that a
+     * verifier logs.
+     */
+    url: string;
+    /** Normalized upper-case HTTP method of the request. */
+    method: Uppercase<HttpMethod>;
+}
+/**
+ * Builds the request headers for one issued attempt. Managed retry calls it
+ * again for every retry, so request-bound single-use proofs (DPoP `jti`,
+ * HTTP message signatures, HMAC nonces) can be re-minted instead of replayed.
+ * A throw is raised as a non-retryable `TransportError` with code
+ * `http_header_factory_failed`.
+ */
+export type HttpHeadersFactory = (attempt: HttpAttemptContext) => Record<string, string> | Promise<Record<string, string>>;
 export interface RequestOptions {
-    headers?: Record<string, string>;
+    /**
+     * Request headers, or a factory resolved once per issued attempt (see
+     * `HttpHeadersFactory`). The factory runs after proxy resolution, before the
+     * first redirect hop of that attempt; redirect hops reuse the attempt's
+     * headers. `ctx.stealth` declares its own header option and is not affected.
+     */
+    headers?: Record<string, string> | HttpHeadersFactory;
     params?: RequestParams;
     /**
      * Query parameters whose values contain credentials or other secret material.
@@ -1048,7 +1122,23 @@ export interface RequestOptions {
      */
     sensitiveParams?: Record<string, string>;
     proxy?: string;
+    /**
+     * Per-attempt timeout for the response-header phase. It is disarmed once a
+     * successful response's headers arrive, so it never bounds consumption of
+     * that body — on the buffered path as well as on streams; use `signal` for
+     * that. A non-2xx body the transport discards on the caller's behalf is
+     * still drained under this deadline, so a wedged error body cannot hang the
+     * attempt.
+     */
     timeout?: number;
+    /**
+     * Cancels this request only — its retries, its backoff sleep and its
+     * response-body consumption — leaving the client's other in-flight requests
+     * untouched. Merged with the client-level `signal`, so a rejection reads as
+     * `transport_cancelled` either way; inspect `signal.reason` to tell a
+     * per-request abort from a fleet-wide one.
+     */
+    signal?: AbortSignal;
     /**
      * Defaults to true. Set to false when callers need to inspect upstream
      * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1073,6 +1163,13 @@ export interface HttpRedirectPolicy {
 export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
 export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+    /**
+     * Not supported by the stealth transport, which observes only the
+     * client-level `signal` passed to `createStealthClient`. Typed as `never` so
+     * a per-request signal fails to compile instead of being silently ignored;
+     * threading one through the stealth session is a separate change.
+     */
+    signal?: never;
     /**
      * Defaults to true. Set to false when callers need to inspect upstream
      * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1659,6 +1756,16 @@ export interface CredentialContext {
 }
 export interface ProviderRequestContext {
     connectionId?: string;
+    /**
+     * Gateway-asserted principal scope of the operation request: the
+     * organization id for customer subjects, the service-account id for
+     * platform service accounts. `undefined` on direct calls and self-test
+     * (unlike `FlowContext.tenantId`, which is coerced to `""`); an empty
+     * string on the wire is normalised to `undefined` like `connectionId`.
+     * Key per-principal policy (quota, fairness, correlation) for
+     * connectionless operations on it. It does not scope `ctx.state`.
+     */
+    tenantId?: string;
     headers: Record<string, string>;
 }
 export interface ContextScratchpad {
@@ -1915,10 +2022,17 @@ export interface AuthConfig {
     proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
+/** Who provisions a declared secret: the platform (`apifuse`) or the provider author (`contributor`). */
+export type ProviderSecretIssuer = "apifuse" | "contributor";
 export interface ProviderSecretDeclaration {
     name: string;
     description?: string;
     required?: boolean;
+    /**
+     * Optional today; ADR-0011 D3 makes it required once every deployed provider
+     * declares it. Metadata only: it does not change which secrets are projected.
+     */
+    issuer?: ProviderSecretIssuer;
 }
 export interface CredentialDeclaration {
     keys: string[];
@@ -2000,6 +2114,14 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
  * optional. Note that the deployment `runtime` axis
  * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
  * `runtime` (`standard`/`shared`/`browser`).
+ *
+ * This key is the ONLY authored deployment surface. Declare it inside the
+ * `defineProvider({...})` literal, not on a spread default export and not
+ * in a standalone `deploy.ts` (legacy; `apifuse migrate-deployment` hoists
+ * and deletes it). Write only what differs from the runtime profile —
+ * shared `25m/128Mi`, browser `200m/256Mi`, `language: "typescript"`,
+ * `replicas: 1`, HPA enabled 1-1 at 70% CPU — so most providers declare
+ * nothing and `apifuse check` warns on restated defaults.
  */
 export interface ProviderDeploymentOverrides {
     runtime?: "shared" | "dedicated" | "browser";

package/dist/typescript-module.d.ts

@@ -0,0 +1,39 @@
+/** The TypeScript compiler API surface the source-level lint rules parse with. */
+export type TypeScriptModule = typeof import("typescript");
+/**
+ * What a caller hands over as a compiler module. Typed structurally so the
+ * option does not depend on which `typescript` package the caller's own type
+ * resolution lands on: under a `typescript@7` pin `typeof import("typescript")`
+ * is the native shell's version module, not the compiler API. The members are
+ * optional for the same reason — the shell has none of them — and
+ * `isTypeScriptCompilerModule` decides at runtime whether the module can parse.
+ */
+export type TypeScriptCompilerModuleLike = {
+    readonly createSourceFile?: (...parameters: never[]) => unknown;
+    readonly ScriptTarget?: object;
+    readonly version?: string;
+};
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export declare const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS: readonly ["typescript", "@typescript/typescript6"];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export declare function isTypeScriptCompilerModule(candidate: unknown): candidate is TypeScriptModule;
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export declare function loadTypeScriptModule(load: (specifier: string) => unknown, specifiers?: readonly string[]): TypeScriptModule;
+export declare function getTypeScript(): TypeScriptModule;

package/dist/typescript-module.js

@@ -0,0 +1,72 @@
+import { createRequire } from "node:module";
+const requireModule = createRequire(import.meta.url);
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS = [
+    "typescript",
+    "@typescript/typescript6",
+];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export function isTypeScriptCompilerModule(candidate) {
+    return (typeof candidate === "object" &&
+        candidate !== null &&
+        typeof candidate.createSourceFile === "function" &&
+        typeof candidate.ScriptTarget === "object");
+}
+function describeCandidate(candidate) {
+    if (typeof candidate === "object" && candidate !== null) {
+        const version = candidate.version;
+        if (typeof version === "string")
+            return `resolved ${version} without a compiler API`;
+    }
+    return "resolved without a compiler API";
+}
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export function loadTypeScriptModule(load, specifiers = TYPESCRIPT_COMPILER_MODULE_SPECIFIERS) {
+    const attempts = [];
+    for (const specifier of specifiers) {
+        let candidate;
+        try {
+            candidate = load(specifier);
+        }
+        catch {
+            attempts.push(`${specifier}: not resolvable`);
+            continue;
+        }
+        if (isTypeScriptCompilerModule(candidate))
+            return candidate;
+        attempts.push(`${specifier}: ${describeCandidate(candidate)}`);
+    }
+    throw new Error(`The provider source lint needs the TypeScript compiler API (createSourceFile) and none of the resolvable packages provide it — ${attempts.join("; ")}. Install typescript 6.x as a devDependency, or @typescript/typescript6 next to a typescript 7 toolchain, in the dependency tree that installs @apifuse/provider-sdk.`);
+}
+/**
+ * Lazily loaded TypeScript compiler API shared by the source-level lint rules.
+ *
+ * `typeof import(...)` keeps the type without emitting a static import: the
+ * typescript package is a devDependency of the SDK and only the CLI and the
+ * lint rules need it at runtime, which the typescript-import-boundary test
+ * enforces for production sources. Resolution starts at the installed SDK, so
+ * the caller's dependency tree must provide one of
+ * `TYPESCRIPT_COMPILER_MODULE_SPECIFIERS`.
+ */
+let typeScriptModule;
+export function getTypeScript() {
+    typeScriptModule ??= loadTypeScriptModule(requireModule);
+    return typeScriptModule;
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.62",
+	"version": "2.2.0-beta.64",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -15,9 +15,14 @@
 		"src",
 		"!src/__tests__",
 		"!src/__tests__/**",
+		"!src/**/__tests__",
+		"!src/**/__tests__/**",
 		"!src/**/*.test.ts",
+		"!src/**/*.spec.ts",
 		"!src/index.test.ts",
 		"bin",
+		"!bin/__tests__",
+		"!bin/__tests__/**",
 		"README.md",
 		"AUTHORING.md",
 		"CHANGELOG.md",

package/src/cli/commands.ts

@@ -5,6 +5,7 @@ export type ApifuseCommandName =
 	| "sync-assets"
 	| "migrate-shape"
 	| "migrate-operation-declaration"
+	| "migrate-deployment"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -76,6 +77,18 @@ export const COMMAND_MANIFEST: Record<
 		],
 		modulePath: "./apifuse-migrate-operation-declaration",
 	},
+	"migrate-deployment": {
+		name: "migrate-deployment",
+		summary:
+			"Retire a legacy deploy.ts: hoist its non-default values into the defineProvider() deployment key and delete the file.",
+		usage:
+			"apifuse migrate-deployment [path] [--check] [--json] [--drop-codeowners-lock]",
+		examples: [
+			"apifuse migrate-deployment .",
+			"apifuse migrate-deployment . --check --json",
+		],
+		modulePath: "./apifuse-migrate-deployment",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -136,6 +149,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"sync-assets",
 	"migrate-shape",
 	"migrate-operation-declaration",
+	"migrate-deployment",
 	"submit-check",
 	"record",
 	"test",