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

package/src/stealth/profiles.ts

@@ -1,5 +1,5 @@
-import { SDKError } from "../errors";
-import type { StealthPlatform, StealthProfile } from "../types";
+import { SDKError } from "../errors.js";
+import type { StealthPlatform, StealthProfile } from "../types.js";
 
 type StealthProfileDefinition = Omit<StealthProfile, "name" | "platform"> & {
 	platform: StealthPlatform;
@@ -81,10 +81,7 @@ const FIREFOX_JA3 =
 const SAFARI_JA3 =
 	"771,4865-4866-4867-49196-49195-52393-49200-49199-49188-49192-159-158-107-103-57-51-157-156-61-60-53-47-255,0-23-65281-10-11-16-5-13-18-51-45-43-27,29-23-24-25,0";
 
-function createProfile(
-	name: string,
-	definition: StealthProfileDefinition,
-): StealthProfile {
+function createProfile(name: string, definition: StealthProfileDefinition): StealthProfile {
 	return {
 		name,
 		platform: definition.platform,
@@ -93,12 +90,8 @@ function createProfile(
 		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,
 	};
 }
 
@@ -108,8 +101,7 @@ function extractBrowserMajorVersion(profile: StealthProfile): string {
 		return chromeVersion;
 	}
 
-	const identifierVersion =
-		profile.tlsClientIdentifier?.match(/(\d+)(?!.*\d)/)?.[1];
+	const identifierVersion = profile.tlsClientIdentifier?.match(/(\d+)(?!.*\d)/)?.[1];
 	if (identifierVersion) {
 		return identifierVersion;
 	}
@@ -132,9 +124,7 @@ function toPlatformHeaderValue(platform: StealthPlatform): string {
 	}
 }
 
-export function generateLayer2Headers(
-	profile: StealthProfile,
-): Record<string, string> {
+export function generateLayer2Headers(profile: StealthProfile): Record<string, string> {
 	const headers: Record<string, string> = {
 		"Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8",
 	};
@@ -143,16 +133,13 @@ export function generateLayer2Headers(
 	const majorVersion = extractBrowserMajorVersion(profile);
 
 	if (identifier.startsWith("chrome_") || identifier.startsWith("edge_")) {
-		const isEdge =
-			identifier.startsWith("edge_") || /\bEdg\//.test(profile.userAgent);
+		const isEdge = identifier.startsWith("edge_") || /\bEdg\//.test(profile.userAgent);
 		headers["Sec-Ch-Ua"] = isEdge
 			? `"Chromium";v="${majorVersion}", "Microsoft Edge";v="${majorVersion}", "Not)A;Brand";v="99"`
 			: `"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;
@@ -301,8 +288,5 @@ export function getStealthProfile(name: string): StealthProfile {
 }
 
 export function listStealthProfiles(): string[] {
-	return [
-		...Object.keys(STEALTH_PROFILES),
-		...Object.keys(STEALTH_PROFILE_ALIASES),
-	];
+	return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
 }

package/src/stream.ts

@@ -1,4 +1,4 @@
-import type { SseMessage } from "./types";
+import type { SseMessage } from "./types.js";
 
 export interface SseEvent<TData = unknown> {
 	event: string;
@@ -61,8 +61,7 @@ export function done<TData>(
 
 export function encodeSseEvent(input: SseEvent): string {
 	const lines: string[] = [];
-	if (input.id !== undefined)
-		lines.push(`id: ${sseFieldValue(input.id, "id")}`);
+	if (input.id !== undefined) lines.push(`id: ${sseFieldValue(input.id, "id")}`);
 	if (input.event) lines.push(`event: ${sseFieldValue(input.event, "event")}`);
 	if (input.retry !== undefined) {
 		if (!Number.isInteger(input.retry) || input.retry < 0) {
@@ -70,8 +69,7 @@ export function encodeSseEvent(input: SseEvent): string {
 		}
 		lines.push(`retry: ${input.retry}`);
 	}
-	const data =
-		typeof input.data === "string" ? input.data : JSON.stringify(input.data);
+	const data = typeof input.data === "string" ? input.data : JSON.stringify(input.data);
 	for (const line of data.split(/\r?\n/)) {
 		lines.push(`data: ${line}`);
 	}
@@ -85,9 +83,7 @@ function sseFieldValue(value: string, field: "event" | "id"): string {
 	return value;
 }
 
-export async function* readableBytes(
-	body: ReadableStream<Uint8Array>,
-): AsyncIterable<Uint8Array> {
+export async function* readableBytes(body: ReadableStream<Uint8Array>): AsyncIterable<Uint8Array> {
 	const reader = body.getReader();
 	try {
 		for (;;) {
@@ -100,9 +96,7 @@ export async function* readableBytes(
 	}
 }
 
-export async function* readableTextChunks(
-	body: ReadableStream<Uint8Array>,
-): AsyncIterable<string> {
+export async function* readableTextChunks(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
 	const decoder = new TextDecoder();
 	for await (const chunk of readableBytes(body)) {
 		yield decoder.decode(chunk, { stream: true });
@@ -111,9 +105,7 @@ export async function* readableTextChunks(
 	if (tail) yield tail;
 }
 
-export async function* readableLines(
-	body: ReadableStream<Uint8Array>,
-): AsyncIterable<string> {
+export async function* readableLines(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
 	let buffer = "";
 	for await (const chunk of readableTextChunks(body)) {
 		buffer += chunk;
@@ -121,8 +113,7 @@ export async function* readableLines(
 			const index = buffer.search(/\r?\n/);
 			if (index < 0) break;
 			const line = buffer.slice(0, index);
-			const newlineLength =
-				buffer[index] === "\r" && buffer[index + 1] === "\n" ? 2 : 1;
+			const newlineLength = buffer[index] === "\r" && buffer[index + 1] === "\n" ? 2 : 1;
 			buffer = buffer.slice(index + newlineLength);
 			yield line;
 		}
@@ -150,9 +141,7 @@ function parseJson<T>(data: string): T {
 	return JSON.parse(data);
 }
 
-export async function* parseSseStream(
-	body: ReadableStream<Uint8Array>,
-): AsyncIterable<SseMessage> {
+export async function* parseSseStream(body: ReadableStream<Uint8Array>): AsyncIterable<SseMessage> {
 	let eventName = "message";
 	let dataLines: string[] = [];
 	let id: string | undefined;

package/src/testing/index.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/src/testing/run.ts

@@ -1,28 +1,23 @@
 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";
 import type {
 	AuthMode,
 	CredentialContext,
 	HttpResponse,
 	ProviderContext,
 	ProviderDefinition,
-} from "../types";
+} from "../types.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",
-] as const;
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 
 export interface StandardTestsManifest {
@@ -118,9 +113,7 @@ function inferFixtureDir(providerId: string): string {
 		.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__`;
 	}
 
@@ -138,10 +131,7 @@ function jsonResponse(data: unknown): HttpResponse {
 		json: async <_T = unknown>() => JSON.parse(JSON.stringify(data)),
 		text: async () => body,
 		arrayBuffer: async () =>
-			bodyBytes.buffer.slice(
-				bodyBytes.byteOffset,
-				bodyBytes.byteOffset + bodyBytes.byteLength,
-			),
+			bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength),
 		bytes: async () => bodyBytes.slice(0),
 	};
 }
@@ -184,16 +174,14 @@ function createSnapshotContext(rawFixture: unknown): ProviderContext {
 			engine: "playwright-stealth",
 			newPage: async () => unsupported("ctx.browser.newPage"),
 			rawPage: async () => unsupported("ctx.browser.rawPage"),
-			withIsolatedContext: async () =>
-				unsupported("ctx.browser.withIsolatedContext"),
+			withIsolatedContext: async () => unsupported("ctx.browser.withIsolatedContext"),
 			solveChallenge: async () => unsupported("ctx.browser.solveChallenge"),
 		},
 		trace: {
 			span: async (_name, fn) => fn(),
 		},
 		auth: {
-			requestField: async (name) =>
-				unsupported(`ctx.auth.requestField(${name})`),
+			requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`),
 		},
 		stt: createUnsupportedSttClient(
 			"Standard test snapshot context does not support ctx.stt.transcribe",
@@ -292,11 +280,7 @@ function parseSchemaFixture(
 		operationName,
 		fieldName,
 		fixture,
-		safeParseSchemaSync(
-			schema,
-			fixture,
-			`operations.${operationName}.fixtures.${fieldName}`,
-		),
+		safeParseSchemaSync(schema, fixture, `operations.${operationName}.fixtures.${fieldName}`),
 	);
 }
 
@@ -322,40 +306,20 @@ export function runStandardTests(
 
 		for (const [operationName, op] of operations) {
 			if (op.fixtures?.request !== undefined) {
-				parseSchemaFixture(
-					operationName,
-					"request",
-					op.input,
-					op.fixtures.request,
-				);
+				parseSchemaFixture(operationName, "request", op.input, op.fixtures.request);
 			}
 
 			if (op.fixtures?.response !== undefined) {
-				parseSchemaFixture(
-					operationName,
-					"response",
-					op.output,
-					op.fixtures.response,
-				);
+				parseSchemaFixture(operationName, "response", op.output, op.fixtures.response);
 			}
 
 			if (isFixtureEnvelope(rawFixture)) {
 				if (rawFixture.request !== undefined) {
-					parseSchemaFixture(
-						operationName,
-						"request",
-						op.input,
-						rawFixture.request,
-					);
+					parseSchemaFixture(operationName, "request", op.input, rawFixture.request);
 				}
 
 				if (rawFixture.response !== undefined) {
-					parseSchemaFixture(
-						operationName,
-						"response",
-						op.output,
-						rawFixture.response,
-					);
+					parseSchemaFixture(operationName, "response", op.output, rawFixture.response);
 				}
 			}
 		}
@@ -411,21 +375,11 @@ export function runStandardTests(
 		it("operation schemas can parse fixture data", () => {
 			for (const [operationName, op] of operations) {
 				if (op.fixtures?.request !== undefined && op.input) {
-					parseSchemaFixture(
-						operationName,
-						"request",
-						op.input,
-						op.fixtures.request,
-					);
+					parseSchemaFixture(operationName, "request", op.input, op.fixtures.request);
 				}
 
 				if (op.fixtures?.response !== undefined && op.output) {
-					parseSchemaFixture(
-						operationName,
-						"response",
-						op.output,
-						op.fixtures.response,
-					);
+					parseSchemaFixture(operationName, "response", op.output, op.fixtures.response);
 				}
 
 				expect(operationName).toBeTruthy();
@@ -471,9 +425,7 @@ export function runStandardTests(
 					await Bun.write(snapshotPath, serialized);
 				}
 
-				const expected: unknown = JSON.parse(
-					await Bun.file(snapshotPath).text(),
-				);
+				const expected: unknown = JSON.parse(await Bun.file(snapshotPath).text());
 				expect(actual).toEqual(expected);
 			});
 		}

package/src/types.ts

@@ -1759,6 +1759,19 @@ 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[];
@@ -1797,10 +1810,55 @@ export interface OperationDefinition<
 	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/src/user-input.ts

@@ -0,0 +1,118 @@
+// Official cross-provider contract for user-input round-trips.
+//
+// Doctrine (born from the 2026-07-20 CatchTable reserve incident): an
+// operation MUST NOT dead-end on a problem the end user can resolve by
+// choosing among live options. Instead of throwing, the provider returns a
+// SUCCESSFUL payload with `status: "needs_input"` that carries everything a
+// consumer-side agent needs to relay the choice verbatim and retry:
+//
+// - `required_selections`: only the still-pending questions, each with
+//   human-readable `label`s and `valid_options` the agent shows the user
+//   as-is. The agent never chooses on the user's behalf.
+// - `selected_options`: selections already settled, echoed so the follow-up
+//   call keeps them without the agent reconstructing anything.
+// - a fresh provider-specific state token (e.g. `reservation_state`) minted
+//   at response time, so the retry never races an expired token.
+//
+// Keeping this success-shaped (instead of error `details`) is deliberate:
+// consumer error-shaping layers routinely strip error metadata, and a model
+// that only sees "error" narrates failure to the user. Complex recovery
+// logic belongs to the system, not the model.
+//
+// Deliberately ABSENT: retry templates, next-action routing, or any other
+// agent choreography. Provider payloads carry upstream-backed data only; how
+// to phrase the ask and shape the retry call is the consumer's contract
+// (apifuse#1030). The retry is fully determined by data: copy the echoed
+// selected_options, add the user's new answers, resend with the fresh state.
+
+export const NEEDS_INPUT_STATUS = "needs_input" as const;
+
+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;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSelectionOption(value: unknown): value is ProviderSelectionOption {
+	return (
+		isRecord(value) &&
+		typeof value.selection_value === "string" &&
+		typeof value.label === "string"
+	);
+}
+
+function isRequiredSelection(
+	value: unknown,
+): value is ProviderRequiredSelection {
+	return (
+		isRecord(value) &&
+		typeof value.selection_key === "string" &&
+		typeof value.label === "string" &&
+		typeof value.required === "boolean" &&
+		Array.isArray(value.valid_options) &&
+		value.valid_options.every(isSelectionOption)
+	);
+}
+
+function isSelectedOption(value: unknown): value is ProviderSelectedOption {
+	return (
+		isRecord(value) &&
+		typeof value.selection_key === "string" &&
+		typeof value.selection_value === "string"
+	);
+}
+
+export function isProviderNeedsInputPayload(
+	value: unknown,
+): value is ProviderNeedsInputPayload {
+	if (!isRecord(value)) {
+		return false;
+	}
+	if (
+		value.status !== NEEDS_INPUT_STATUS ||
+		!Array.isArray(value.required_selections) ||
+		!value.required_selections.every(isRequiredSelection)
+	) {
+		return false;
+	}
+	// A needs_input with nothing to ask AND nothing settled to echo is a
+	// no-op dead end — reject it so providers cannot ship it accidentally.
+	if (value.required_selections.length > 0) {
+		return true;
+	}
+	return (
+		Array.isArray(value.selected_options) &&
+		value.selected_options.length > 0 &&
+		value.selected_options.every(isSelectedOption)
+	);
+}