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

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

@@ -4,8 +4,8 @@ You are building an APIFuse provider. APIFuse turns messy upstream APIs into
 normalized, typed, evidence-backed public APIs. A provider that merely proxies
 the upstream is a failed provider, even if every check passes.
 
-This file is the core contract. Detailed procedures live in `skills/` — load
-the matching skill BEFORE working on that area (index at the bottom).
+This file is the core contract. Detailed procedures live in `.agents/skills/` —
+load the matching skill BEFORE working on that area (index at the bottom).
 
 ## Non-negotiable principles
 
@@ -75,13 +75,22 @@ bun run submit-check # structural score; a high score does NOT prove quality
 `submit-check` is a structural gate. Every principle above can be violated
 while scoring 95/100 — reviewers and CI audit for exactly these classes.
 
+## Managed prompt assets
+
+`AGENTS.md` and `.agents/skills/**` are generated by the SDK; `CLAUDE.md`,
+`.claude`, and `.codex` are symlinks onto them so every agent CLI reads the
+same contract. Do not hand-edit these files — regenerate them with
+`bun run sync-assets` (or `bunx apifuse sync-assets .`). `apifuse check` and
+`submit-check` enforce a freshness gate: stale or modified prompt assets
+(tracked in `.apifuse/prompt-assets.json`) block submission until re-synced.
+
 ## Skill index — load before working on:
 
 | Area | Load |
 | --- | --- |
-| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
-| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
-| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
-| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
-| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
-| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |
+| Output schemas, mappers, field naming, timestamps, enums | `.agents/skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `.agents/skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `.agents/skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `.agents/skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `.agents/skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `.agents/skills/upstream-notes/` (read every file) |

package/src/index.ts

@@ -74,6 +74,11 @@ export {
 } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export {
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "./runtime/secrets.js";
 export {
 	createUnsupportedProviderRuntimeState,
 	UnsupportedProviderStateError,

package/src/runtime/executor.ts

@@ -1,6 +1,7 @@
 import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
 import { parseSchema } from "../schema.js";
 import type { ProviderContext, ProviderDefinition } from "../types.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 
 export function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean {
 	const kind = provider.operations[operationId]?.transport?.kind ?? "json";
@@ -34,6 +35,13 @@ export async function executeOperation(
 		});
 	}
 
+	// SDK-owned secret presence gate (single source of truth): declared
+	// `required: true` secrets are validated here, before input parsing and the
+	// handler, so every invocation path (serve /v1, self-test probes, perf,
+	// record) fails with the same structured MISSING_SECRET error instead of a
+	// handler-specific crash. Providers must not re-check presence locally.
+	assertRequiredSecretsPresent(provider, ctx.env);
+
 	const validatedInput = await parseSchema(
 		operation.input,
 		input,

package/src/runtime/secrets.ts

@@ -0,0 +1,64 @@
+import { ProviderSecretError } from "../errors.js";
+import type { EnvContext, ProviderDefinition } from "../types.js";
+
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(
+	provider: ProviderDefinition,
+	env: EnvContext,
+): string[] {
+	const missing: string[] = [];
+	for (const secret of provider.secrets ?? []) {
+		if (secret.required !== true) {
+			continue;
+		}
+		const value = env.get(secret.name);
+		if (value === undefined || value.trim() === "") {
+			missing.push(secret.name);
+		}
+	}
+	return missing;
+}
+
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(
+	provider: ProviderDefinition,
+	env: EnvContext,
+): void {
+	const missing = listMissingRequiredSecrets(provider, env);
+	if (missing.length === 0) {
+		return;
+	}
+	const names = missing.join(", ");
+	throw new ProviderSecretError(
+		`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`,
+		{
+			code: MISSING_SECRET_CODE,
+			category: "credential_unavailable",
+			retryable: false,
+			fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+		},
+	);
+}

package/src/server/index.ts

@@ -2,15 +2,20 @@ export { createServerApp, type ServeOptions, serve } from "./serve.js";
 export {
 	computeSelfTestPlanDigest,
 	createSelfTestApp,
+	createSelfTestAuthFlowInvoke,
 	createSelfTestInvoke,
 	DEFAULT_SELF_TEST_REQUEST_BUDGET_MS,
 	isSelfTestReadOnlyOperation,
 	PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV,
 	resolveSelfTestPort,
+	SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON,
+	SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON,
 	SELF_TEST_HEALTHZ_PATH,
 	SELF_TEST_PATH,
 	SELF_TEST_SCHEMA_VERSION,
 	type SelfTestAppOptions,
+	type SelfTestAuthFlowInvoke,
+	type SelfTestAuthFlowRoute,
 	type SelfTestCaseResult,
 	type SelfTestCaseStatus,
 	type SelfTestOperationInvoke,