@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.8

package/src/server/serve.ts

@@ -42,6 +42,11 @@ import {
 	PROXY_POOL_EXHAUSTED_CODE,
 } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import {
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "../runtime/secrets.js";
 import {
 	createProviderRuntimeStateFromEnv,
 	createUnsupportedProviderRuntimeState,
@@ -408,6 +413,12 @@ export type ProviderServerLogEvent =
 			retryable?: boolean;
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
+	| {
+			level: "warn";
+			event: "provider_secrets_missing";
+			providerId: string;
+			missingSecrets: string[];
+	  }
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";
@@ -558,6 +569,18 @@ function providerObservabilityDetails(error: unknown):
 			retryable: error.options?.retryable ?? false,
 		};
 	}
+	// Missing-secret errors carry the canonical credential_unavailable category
+	// so Gateway/observability can attribute the failure to provisioning, not
+	// the upstream. Matched by code (not constructor) so both the SDK-owned
+	// runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+	// serialize identically, including across duplicate SDK module instances.
+	if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+		return {
+			category: error.options?.category ?? "credential_unavailable",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
 	if (!isTransportError(error)) {
 		return undefined;
 	}
@@ -628,6 +651,10 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 			case "AUTH_REQUIRED":
 			case "reauth_required":
 				return 401;
+			// Unprovisioned declared secret: a deployment/config defect, never an
+			// upstream failure — explicit 400 (was only reached via fallthrough).
+			case MISSING_SECRET_CODE:
+				return 400;
 			case "NOT_FOUND":
 			case "not_found":
 			case "NO_DATA":
@@ -1224,8 +1251,16 @@ async function handleAuthFlow(
 		});
 	}
 
+	// Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+	// depend on declared secrets (client ids/secrets), so fail structured before
+	// any flow code runs instead of at whatever point the ceremony first reads
+	// the env. `abort` stays exempt: a user must always be able to cancel a
+	// stranded flow even when provisioning is broken.
 	const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
 	try {
+		if (route !== "abort") {
+			assertRequiredSecretsPresent(provider, context.env);
+		}
 		const result =
 			route === "start"
 				? await flow.start(context)
@@ -1280,6 +1315,24 @@ export function createServerApp(
 			allowMemoryFallback: options.allowMemoryStateFallback === true,
 		});
 
+	// Boot-time visibility for unprovisioned declared secrets: emit a structured
+	// warn so deploy tooling/alerting sees the gap the moment the pod boots,
+	// instead of discovering it request-by-request. Deliberately log-only — a
+	// boot crash would trade a structured MISSING_SECRET signal for
+	// CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+	const missingSecretsAtBoot = listMissingRequiredSecrets(
+		provider,
+		createEnvContext(provider.secrets?.map((secret) => secret.name)),
+	);
+	if (missingSecretsAtBoot.length > 0) {
+		logger({
+			level: "warn",
+			event: "provider_secrets_missing",
+			providerId: provider.id,
+			missingSecrets: missingSecretsAtBoot,
+		});
+	}
+
 	app.notFound((c) =>
 		c.json(
 			{

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;

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