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

package/src/dev.ts

@@ -1,5 +1,5 @@
-import { serve } from "./server/serve";
-import type { ProviderDefinition } from "./types";
+import { serve } from "./server/serve.js";
+import type { ProviderDefinition } from "./types.js";
 
 export interface DevServerOptions {
 	port?: number;
@@ -18,17 +18,12 @@ export function createDevServer(
 			console.log(
 				`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`,
 			);
-			console.log(
-				`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`,
-			);
+			console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
 			console.log(`[apifuse dev] Health: http://localhost:${port}/health`);
 		},
 	};
 }
 
-export function startDevServer(
-	provider: ProviderDefinition,
-	options?: DevServerOptions,
-): void {
+export function startDevServer(provider: ProviderDefinition, options?: DevServerOptions): void {
 	createDevServer(provider, options).start();
 }

package/src/errors.ts

@@ -1,4 +1,41 @@
-import type { ProviderErrorCategory } from "./observability";
+import type { ProviderErrorCategory } from "./observability.js";
+
+// Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
+// any copy/entrypoint of this SDK major version, so an error created by a
+// duplicate module instance (e.g. the packaged CLI's src/* server vs a
+// provider's dist/* import) still carries a brand the server can recognize even
+// though `instanceof` splits across the two constructors. The `@1` suffix lets a
+// future breaking change to this contract mint a distinct key.
+const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
+const PROVIDER_ERROR_BRAND_VALUE = 1;
+const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
+const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+
+// Defines a non-enumerable, non-writable, non-configurable own data property.
+// Immutable + own means a guard can trust it via a single descriptor read
+// without invoking attacker-controlled getters or accepting inherited brands.
+function defineErrorBrand(target: object, brand: symbol, value: number | true): void {
+	Object.defineProperty(target, brand, {
+		value,
+		enumerable: false,
+		writable: false,
+		configurable: false,
+	});
+}
+
+// Recognizes an own data-property brand with the expected value. Rejects
+// missing brands (unbranded lookalikes), accessor brands (no own `value`
+// slot — the getter is never called), and inherited brands (own-descriptor
+// lookup returns undefined on the child).
+function hasOwnBrand(value: unknown, brand: symbol, expected: number | true): boolean {
+	if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+		return false;
+	}
+	const descriptor = Object.getOwnPropertyDescriptor(value, brand);
+	return (
+		descriptor !== undefined && Object.hasOwn(descriptor, "value") && descriptor.value === expected
+	);
+}
 
 export type ProviderErrorOptions = {
 	fix?: string;
@@ -19,6 +56,7 @@ export class ProviderError extends Error {
 		if (options?.cause) {
 			this.cause = options.cause;
 		}
+		defineErrorBrand(this, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
 	}
 
 	get fix(): string | undefined {
@@ -49,10 +87,7 @@ export class AuthError extends ProviderError {
 }
 
 export class SessionExpiredError extends AuthError {
-	constructor(
-		message = "Provider session expired",
-		options?: ProviderErrorOptions,
-	) {
+	constructor(message = "Provider session expired", options?: ProviderErrorOptions) {
 		super(message, {
 			code: "reauth_required",
 			category: "credential_expired",
@@ -60,6 +95,7 @@ export class SessionExpiredError extends AuthError {
 			...options,
 		});
 		this.name = "SessionExpiredError";
+		defineErrorBrand(this, SESSION_EXPIRED_BRAND, true);
 	}
 }
 
@@ -91,9 +127,26 @@ export class TransportError extends ProviderError {
 		this.name = "TransportError";
 		this.status = options?.status;
 		this.upstreamStatus = options?.upstreamStatus ?? options?.status;
+		defineErrorBrand(this, TRANSPORT_BRAND, true);
 	}
 }
 
+// Cross-module type guards. Prefer these over `instanceof` at any boundary that
+// may receive an error from a different copy/entrypoint of the SDK (see the HTTP
+// server error boundary). They recognize branded errors regardless of which
+// module instance constructed them, while rejecting unbranded lookalikes.
+export function isProviderError(value: unknown): value is ProviderError {
+	return hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
+}
+
+export function isSessionExpiredError(value: unknown): value is SessionExpiredError {
+	return isProviderError(value) && hasOwnBrand(value, SESSION_EXPIRED_BRAND, true);
+}
+
+export function isTransportError(value: unknown): value is TransportError {
+	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
+}
+
 export class ProviderSecretError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, { code: "provider_secret_error", ...options });

package/src/i18n/catalog.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { AuthTurn } from "../types";
+import type { AuthTurn } from "../types.js";
 import {
 	getProviderLocalePath,
 	isProviderLocaleValue,
@@ -10,12 +10,9 @@ import {
 	type ProviderLocaleKey,
 	type ProviderLocaleValue,
 	providerLocaleKey,
-} from "./keys";
+} from "./keys.js";
 
-export type ProviderLocaleCatalogMap = Record<
-	ProviderLocale,
-	ProviderLocaleCatalog
->;
+export type ProviderLocaleCatalogMap = Record<ProviderLocale, ProviderLocaleCatalog>;
 
 export interface LoadProviderLocaleCatalogsOptions {
 	providerDir: string;
@@ -58,9 +55,7 @@ export function resolveProviderLocaleValue(
 	);
 }
 
-function asStringValue(
-	value: ProviderLocaleValue | undefined,
-): string | undefined {
+function asStringValue(value: ProviderLocaleValue | undefined): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
 
@@ -82,9 +77,7 @@ function localizeAuthInputSchema(
 	},
 ): Record<string, unknown> | undefined {
 	if (!expectedInput) return undefined;
-	const schema = isRecord(expectedInput.schema)
-		? expectedInput.schema
-		: expectedInput;
+	const schema = isRecord(expectedInput.schema) ? expectedInput.schema : expectedInput;
 	const localizedSchema = localizeAuthSchemaObject(schema, options);
 	if (localizedSchema === schema) return undefined;
 	return isRecord(expectedInput.schema)
@@ -104,21 +97,16 @@ function localizeAuthSchemaObject(
 		fallbackLocale: ProviderLocale;
 	},
 ): Record<string, unknown> {
-	const properties = isRecord(schema.properties)
-		? schema.properties
-		: undefined;
+	const properties = isRecord(schema.properties) ? schema.properties : undefined;
 	if (!properties) return schema;
 
 	let changed = false;
 	const localizedProperties = Object.fromEntries(
 		Object.entries(properties).map(([fieldName, property]) => {
 			if (!isRecord(property)) return [fieldName, property];
-			const nameKey =
-				typeof property.nameKey === "string" ? property.nameKey : undefined;
+			const nameKey = typeof property.nameKey === "string" ? property.nameKey : undefined;
 			const descriptionKey =
-				typeof property.descriptionKey === "string"
-					? property.descriptionKey
-					: undefined;
+				typeof property.descriptionKey === "string" ? property.descriptionKey : undefined;
 			const title = nameKey
 				? asStringValue(
 						resolveProviderLocaleValue(
@@ -166,12 +154,7 @@ export function localizeAuthTurn(
 	const fallbackLocale = options.fallbackLocale ?? "en";
 	const hint = turn.hintKey
 		? asStringValue(
-				resolveProviderLocaleValue(
-					options.catalogs,
-					turn.hintKey,
-					options.locale,
-					fallbackLocale,
-				),
+				resolveProviderLocaleValue(options.catalogs, turn.hintKey, options.locale, fallbackLocale),
 			)
 		: undefined;
 	const expectedInput = localizeAuthInputSchema(turn.expectedInput, {
@@ -184,12 +167,7 @@ export function localizeAuthTurn(
 		? Object.fromEntries(
 				Object.entries(fieldErrorKeys).flatMap(([fieldName, key]) => {
 					const message = asStringValue(
-						resolveProviderLocaleValue(
-							options.catalogs,
-							key,
-							options.locale,
-							fallbackLocale,
-						),
+						resolveProviderLocaleValue(options.catalogs, key, options.locale, fallbackLocale),
 					);
 					return message ? [[fieldName, message]] : [];
 				}),

package/src/i18n/index.ts

@@ -1,2 +1,2 @@
-export * from "./catalog";
-export * from "./keys";
+export * from "./catalog.js";
+export * from "./keys.js";

package/src/i18n/keys.ts

@@ -1,6 +1,6 @@
-import type { ProviderLocaleKey } from "../types";
+import type { ProviderLocaleKey } from "../types.js";
 
-export type { ProviderLocale, ProviderLocaleKey } from "../types";
+export type { ProviderLocale, ProviderLocaleKey } from "../types.js";
 
 const PROVIDER_LOCALE_KEY_RE =
 	/^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*|\.[0-9]+)*$/;
@@ -10,15 +10,11 @@ export function providerLocaleKey(key: string): ProviderLocaleKey {
 	return key;
 }
 
-export function isProviderLocaleKey(
-	value: unknown,
-): value is ProviderLocaleKey {
+export function isProviderLocaleKey(value: unknown): value is ProviderLocaleKey {
 	return typeof value === "string" && PROVIDER_LOCALE_KEY_RE.test(value);
 }
 
-export function assertProviderLocaleKey(
-	value: unknown,
-): asserts value is ProviderLocaleKey {
+export function assertProviderLocaleKey(value: unknown): asserts value is ProviderLocaleKey {
 	if (!isProviderLocaleKey(value)) {
 		throw new Error(
 			`Provider locale key must be a dot path such as "meta.description" or "operations.search.description"; received ${JSON.stringify(value)}`,
@@ -50,9 +46,7 @@ export function getProviderLocalePath(
 export type ProviderLocaleValue = string | readonly string[];
 export type ProviderLocaleCatalog = Record<string, unknown>;
 
-export function isProviderLocaleValue(
-	value: unknown,
-): value is ProviderLocaleValue {
+export function isProviderLocaleValue(value: unknown): value is ProviderLocaleValue {
 	return (
 		typeof value === "string" ||
 		(Array.isArray(value) && value.every((entry) => typeof entry === "string"))

package/src/index.ts

@@ -1,15 +1,15 @@
 // @apifuse/provider-sdk
 
-export * from "./auth";
-export * from "./ceremonies";
-export * from "./choice-token";
+export * from "./auth.js";
+export * from "./ceremonies/index.js";
+export * from "./choice-token.js";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,
 	ProxyConfig,
 	SessionConfig,
-} from "./config/loader";
-export { defineConfig, loadApiFuseConfig } from "./config/loader";
+} from "./config/loader.js";
+export { defineConfig, loadApiFuseConfig } from "./config/loader.js";
 export {
 	canonicalJson,
 	digestProviderContract,
@@ -19,7 +19,7 @@ export {
 	PROVIDER_CONTRACT_SCHEMA_VERSION,
 	type ProviderContractOperation,
 	type ProviderContractSnapshot,
-} from "./contract";
+} from "./contract.js";
 export {
 	centered,
 	delayed,
@@ -30,54 +30,55 @@ export {
 	defineStreamOperation,
 	every,
 	type ProviderConfig,
-} from "./define";
-export type { DevServerOptions } from "./dev";
-export { createDevServer, startDevServer } from "./dev";
-export * from "./errors";
-export * from "./i18n";
+} from "./define.js";
+export type { DevServerOptions } from "./dev.js";
+export { createDevServer, startDevServer } from "./dev.js";
+export * from "./errors.js";
+export * from "./user-input.js";
+export * from "./i18n/index.js";
 export {
 	type LintDiagnostic,
 	lintOperation,
 	lintProvider,
-} from "./lint";
-export * from "./recipes/gov-api";
-export * from "./recipes/rest-api";
-export { createFlowContext, createScratchpad } from "./runtime/auth-flow";
-export type { BrowserClientOptions } from "./runtime/browser";
-export { BrowserClient, createBrowserClient } from "./runtime/browser";
+} from "./lint.js";
+export * from "./recipes/gov-api.js";
+export * from "./recipes/rest-api.js";
+export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
+export type { BrowserClientOptions } from "./runtime/browser.js";
+export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
 export {
 	createBypassProviderCache,
 	createProviderCache,
 	type ProviderCacheOptions,
 	resetProviderCacheForTests,
-} from "./runtime/cache";
+} from "./runtime/cache.js";
 export {
 	type CreateProviderChoiceContextOptions,
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "./runtime/choice";
+} from "./runtime/choice.js";
 export {
 	type CreateCredentialContextOptions,
 	createCredentialContext,
-} from "./runtime/credential";
-export { createEnvContext } from "./runtime/env";
-export { executeOperation } from "./runtime/executor";
-export { createHttpClient } from "./runtime/http";
-export type { Insight, InsightSeverity } from "./runtime/insights";
-export { generateInsights } from "./runtime/insights";
+} from "./runtime/credential.js";
+export { createEnvContext } from "./runtime/env.js";
+export { executeOperation } from "./runtime/executor.js";
+export { createHttpClient } from "./runtime/http.js";
+export type { Insight, InsightSeverity } from "./runtime/insights.js";
+export { generateInsights } from "./runtime/insights.js";
 export {
 	type InstrumentationOptions,
 	type InstrumentedProviderContext,
 	wrapWithInstrumentation,
-} from "./runtime/instrumentation";
-export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate";
-export { getProviderBaseUrl } from "./runtime/provider";
+} from "./runtime/instrumentation.js";
+export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
+export { getProviderBaseUrl } from "./runtime/provider.js";
 export {
 	createUnsupportedProviderRuntimeState,
 	UnsupportedProviderStateError,
-} from "./runtime/state";
-export { createStealthClient } from "./runtime/stealth";
+} from "./runtime/state.js";
+export { createStealthClient } from "./runtime/stealth.js";
 export {
 	APIFUSE__STT__BACKEND_ENV,
 	APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV,
@@ -86,13 +87,13 @@ export {
 	createUnsupportedSttClient,
 	extractVerificationCode,
 	resolveSttPrompt,
-} from "./runtime/stt";
+} from "./runtime/stt.js";
 export {
 	type CreateTraceContextOptions,
 	createTraceContext,
 	type Span,
 	type TraceContext,
-} from "./runtime/trace";
+} from "./runtime/trace.js";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
@@ -109,10 +110,10 @@ export {
 	type SensitivePath,
 	sensitive,
 	z,
-} from "./schema";
-export { createServerApp, type ServeOptions, serve } from "./server";
-export { getStealthProfile, listStealthProfiles } from "./stealth/profiles";
-export * from "./stream";
+} from "./schema.js";
+export { createServerApp, type ServeOptions, serve } from "./server/index.js";
+export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
+export * from "./stream.js";
 export type {
 	ApiFuseResponse,
 	AuthConfig,
@@ -201,6 +202,7 @@ export type {
 	ProviderChoiceParseOptions,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderHealthProbeConfig,
 	ProviderLocale,
@@ -263,7 +265,7 @@ export type {
 	VerificationCodeCandidate,
 	VerificationCodeCandidateSource,
 	VerificationCodeExtractionResult,
-} from "./types";
+} from "./types.js";
 export {
 	DEFAULT_OPERATION_TRANSPORT,
 	HttpRetryAfterPolicy,
@@ -280,8 +282,8 @@ export {
 	STREAM_IDLE_TIMEOUT_MS_MIN,
 	STREAM_MAX_DURATION_MS_MAX,
 	STREAM_MAX_DURATION_MS_MIN,
-} from "./types";
-export * from "./utils/date";
-export * from "./utils/parse";
-export * from "./utils/text";
-export * from "./utils/transform";
+} from "./types.js";
+export * from "./utils/date.js";
+export * from "./utils/parse.js";
+export * from "./utils/text.js";
+export * from "./utils/transform.js";