@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

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

@@ -769,7 +769,25 @@ export type ProviderAccessVisibility = "public" | "early_access";
 
 export type ProviderProxyMode = "disabled" | "optional" | "required";
 
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *   endpoints). This is our own vendor. It is NOT the company formerly named
+ *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *   credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *   username params. A different company from `smartproxy` above.
+ *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 
 export type ProviderProxySessionAffinity =
 	| "request"
@@ -783,7 +801,18 @@ export interface ProviderProxyPolicy {
 	 * certificate verification, and vendor allocator endpoints are SDK-owned.
 	 */
 	mode: ProviderProxyMode;
+	/**
+	 * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+	 * chain. A single-element `providers` list is equivalent to this field.
+	 */
 	provider?: ProviderProxyProvider;
+	/**
+	 * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+	 * fails over to the next when a vendor lacks credentials or its allocation /
+	 * transport is exhausted. When omitted, `provider` (or the platform default)
+	 * is used as a single-vendor chain.
+	 */
+	providers?: ProviderProxyProvider[];
 	geo?: {
 		/** ISO 3166-1 alpha-2 country code, for example KR or US. */
 		country?: Iso3166Alpha2CountryCode;
@@ -1759,6 +1788,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 +1839,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)
+	);
+}

package/dist/cli/templates/provider/CLAUDE.md.tpl

@@ -1 +0,0 @@
-@AGENTS.md

package/src/cli/templates/provider/CLAUDE.md.tpl

@@ -1 +0,0 @@
-@AGENTS.md