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

package/src/cli/resolver-runtime.ts

@@ -0,0 +1,72 @@
+import {
+	compileProcessDiagnosticSensitiveValues,
+	createDiagnosticRedactor,
+} from "../runtime/diagnostic-redactor.js";
+import {
+	createResolverClientFromEnv,
+	createUnsupportedResolverClient,
+} from "../runtime/resolver.js";
+import {
+	createResolverRuntimeOptions,
+	resolveNativeProxyPolicy,
+} from "../runtime/resolver-runtime-options.js";
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import { collectStaticDiagnosticSensitiveValues } from "../server/sensitive-values.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+import type { ProviderCache, ProviderDefinition, ResolverContext } from "../types.js";
+
+export interface CliResolverRuntime {
+	readonly resolver: ResolverContext;
+	/** Per-context sink; `toLogPayload()` is the `resolver` sibling of the server request log. */
+	readonly resolverTelemetry: ResolverTelemetryCollector;
+	/**
+	 * Extend the collector's redaction with values learned after construction (request-scoped
+	 * `sensitiveParams` the recorder captures); the collector redacts at record time, before it
+	 * truncates, so values must be registered before the vendor call that may echo them.
+	 */
+	readonly registerSensitiveValues: (values: readonly string[]) => void;
+}
+
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export function createCliResolverRuntime(
+	provider: ProviderDefinition,
+	cache: ProviderCache,
+): CliResolverRuntime {
+	const sensitiveValues = createDiagnosticRedactor(
+		[],
+		compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider)),
+	);
+	const resolverTelemetry = new ResolverTelemetryCollector({ redact: sensitiveValues.redact });
+	const registerSensitiveValues = (values: readonly string[]) => sensitiveValues.add(values);
+	if (!provider.resolver) {
+		return {
+			resolver: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+			resolverTelemetry,
+			registerSensitiveValues,
+		};
+	}
+	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+	return {
+		resolver: createResolverClientFromEnv(
+			provider.resolver,
+			process.env,
+			createResolverRuntimeOptions(
+				provider,
+				cache,
+				undefined,
+				resolveNativeProxyPolicy(provider),
+				{ upstream: { proxy: provider.proxy } },
+				stealthProfile,
+				resolverTelemetry,
+			),
+		),
+		resolverTelemetry,
+		registerSensitiveValues,
+	};
+}

package/src/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -1,37 +1,145 @@
 ---
 name: health-checks-and-fail-closed
-description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+description: Writing health checks the platform monitor actually executes, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
 ---
 
 # Health checks and fail-closed guards
 
-## Health checks that can actually fail
-`Array.isArray(data.items)` alone can never fail. Every list operation's
-health check must be able to detect the zero-rows regression.
+## Only `scenario` is monitored in production
 
-Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
-(recorded as `down`); return `{ status: "degraded", label }` to flag without
-failing; return nothing for `ok`. There is no `"down"` return value.
+A `healthCheck` case takes one of two mutually exclusive shapes, and they do
+not run in the same place:
+
+| field | executed by | when |
+|---|---|---|
+| `scenario` | the platform health monitor | every suite interval, in production |
+| `assertions` | the provider runtime's own self-test | only when that endpoint is called |
+
+The monitor runs a case's SERIALIZED scenario and nothing else: a closure
+cannot cross the registry's serialization boundary. A case that carries only
+`assertions` is still published as a probe, but its outcome is permanently
+`unknown` / `monitoring_unavailable` — the operation reads as monitored on the
+status page while nothing is ever checked. `apifuse check` warns about this
+(`health-check-assertions-not-monitored`).
+
+Anything that must be caught in production belongs in `scenario`. Keep
+`assertions` for a local self-test, or drop it.
+
+## A scenario that can actually fail
+
+`Array.isArray(data.items)` alone can never fail. Every list operation's probe
+must be able to detect the zero-rows regression AND a mapper regression that
+empties fields on a present row.
+
+Step kinds: `operation` invokes, `assert` FAILS the probe (recorded `down`),
+`guard` DEGRADES without failing it.
+
+```ts
+// health-scenarios.ts
+import { type AssertionExpression, defineHealthScenario } from "@apifuse/provider-sdk/provider";
+
+export const PROBE_INPUT = { district: "<a guaranteed-dense, stable id>" } as const;
+
+const response = (path: readonly (string | number)[]) => ({
+  ref: { namespace: "steps" as const, binding: "response", path: [...path] },
+});
+
+const evidence: AssertionExpression = {
+  kind: "all",
+  clauses: [
+    { kind: "predicate", operator: "status_2xx", actual: response(["status_code"]) },
+    // Dense query MUST return rows; zero rows = upstream contract drift.
+    { kind: "predicate", operator: "array_length_gte", actual: response(["data", "items"]), expected: 1 },
+    // A semantic field on a real row, so an emptying mapper regression fails too.
+    { kind: "predicate", operator: "non_empty", actual: response(["data", "items", 0, "name"]) },
+  ],
+};
+
+export const listItemsScenario = defineHealthScenario({
+  scenarioVersion: 2,
+  id: "list-items.dense-district",
+  display: {
+    titleKey: "health.operations.list-items.dense-district.title",
+    descriptionKey: "health.operations.list-items.dense-district.description",
+  },
+  schedule: { kind: "interval", intervalMs: 60 * 60_000, jitterMs: 0 },
+  timeoutMs: 15_000,
+  coversOperations: ["list-items"],
+  credentialRefs: [],
+  steps: [
+    { id: "read", result: "response", kind: "operation", operationId: "list-items", inputTemplate: { ...PROBE_INPUT } },
+    { id: "verify", result: "verified", kind: "assert", coversOperations: ["list-items"], expression: evidence },
+  ],
+});
+```
 
 ```ts
-assertions: ({ status, data }) => {
-  if (status !== 200) {
-    throw new Error(`<op> request failed with status ${status}`);
-  }
-  if (!Array.isArray(data.items)) {
-    throw new Error("<op> missing items array");
-  }
-  // Dense query MUST return rows; zero rows = upstream contract drift
-  if (data.items.length === 0) {
-    return { status: "degraded", label: "<op> dense query returned 0 rows" };
-  }
+// operations/list-items.ts
+healthCheck: {
+  interval: "1h",
+  timeoutMs: 15_000,
+  cases: [{ name: "dense-district", input: { ...PROBE_INPUT }, scenario: listItemsScenario }],
 }
 ```
 
-- Choose health-check inputs that are guaranteed-dense (major city district,
-  a stable well-known entity id). Verify the id still exists when picking it.
-- Also assert one semantic field on the first row (e.g. `items[0].name` is a
-  non-empty string) so a mapper regression that empties fields degrades too.
+- Choose probe inputs that are guaranteed-dense (major city district, a stable
+  well-known entity id). Verify the id still exists when picking it.
+- `scenario.coversOperations` may only name the operation that owns the case.
+
+## Stale-if-error serves must be guarded, or an outage reads green
+
+If the operation reads its upstream through `ctx.cache.getOrSet(..., {
+staleIfErrorMs })`, an upstream outage is answered with HTTP 200 and a
+well-formed, fully schema-valid body for the whole stale window. Every clause
+over `status_code` and `data` still passes, so the probe rolls up `ok` while
+the upstream is down, and only flips to `down` after the window expires — the
+first minutes of every outage are reported as healthy.
+
+`served_stale_cache` on the operation step result is the only operand that
+separates a stale serve from a live read. It is always present, so the
+reference resolves to `false` rather than raising `reference_unresolvable`.
+Add ONE guard step per stale-if-error probe:
+
+```ts
+{
+  id: "guard-list-items-freshness",
+  result: "freshness-guarded",
+  kind: "guard",
+  condition: {
+    kind: "predicate",
+    operator: "not_equals",
+    actual: { ref: { namespace: "steps" as const, binding: "response", path: ["served_stale_cache"] } },
+    expected: true,
+  },
+  onFail: {
+    attribute: [
+      {
+        operationId: "list-items",
+        status: "degraded",
+        reasonCode: "served_stale_cache",
+        reasonKey: "health.operations.list-items.dense-district.servedStaleCache",
+      },
+    ],
+    stop: "scenario",
+  },
+}
+```
+
+- `degraded`, not `down`: the cache policy is behaving as promised and callers
+  are still served; it is the upstream that is unavailable, and that has to be
+  visible instead of green.
+- `served_stale_cache`, not `expected_absence`: the platform publishes a
+  stale serve as `degraded` (an upstream fault that opens incidents), while
+  `expected_absence` is published as a non-incident status — neither ok nor
+  degraded, excluded from uptime — for an absence the provider declares in
+  advance (no alert today, a closed shelf, a feed outside its hours). The
+  tenant-facing wording lives in the localized `reasonKey`.
+- Place the freshness guard BEFORE any row or emptiness guard. A stale serve
+  that happens to be empty would otherwise be attributed to the emptiness
+  reason, which is a confident answer to the wrong question.
+- Do not change the handler for this. The envelope's `meta.stale` is written
+  by the serve layer, so `return result.value` discarding `result.meta` does
+  not suppress the signal.
 
 ## Fail-closed: envelope level
 - Upstream error headers/codes → structured `ProviderError` with a stable
@@ -51,6 +159,14 @@ array is non-empty, but every row normalizes to nothing.
 - Regression-test both layers separately: a bad envelope AND a good envelope
   with unmappable rows.
 
+## Self-test assertions (optional, not monitored)
+A case without a `scenario` may carry an `assertions` lambda, executed only by
+the provider runtime's own self-test. THROW to fail the case (recorded
+`down`); return `{ status: "degraded", label }` to flag without failing;
+return nothing for `ok`. There is no `"down"` return value. It MUST NOT touch
+the scheduler, recorder, or any runtime type. Never use it as the only check
+on an operation you need monitored.
+
 ## Error message hygiene
 `ProviderError.message` reaches the tenant verbatim. Never interpolate
 upstream free text that may contain personal data (names, phone numbers,
@@ -58,8 +174,10 @@ addresses); allowlist known code tokens and keep raw bodies in server-side
 details/logs only.
 
 ## Checklist
-- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] Every monitored operation's case carries `scenario` (not only `assertions`)
+- [ ] Every list op probe fails on 0 rows for a dense query
 - [ ] One semantic field asserted on a real row
+- [ ] Every `staleIfErrorMs` read has a `served_stale_cache` guard, placed first
 - [ ] Swallowed-error test exists (non-ok mock → handler rejects)
 - [ ] Non-empty upstream → zero normalized rows throws
 - [ ] No upstream free text in customer-facing error messages

package/src/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

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

@@ -97,9 +97,21 @@ The `POST /v1/{operation}` body is a request envelope:
 - `requestId` is required and can be any unique local debugging string.
 - `input` contains the operation input shape.
 - `headers` is optional.
-- `connection` is optional; omit it for no-auth/public operations. For
-  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
-  "externalRef" }` with local-only secret values.
+- `connectionId` is optional connection identity only and does not include
+  credentials. The gateway sends it for `optional` connection mode, and only
+  when the caller supplied a connection that passed authorization. It is
+  exposed as `ctx.request.connectionId`.
+- `connection` is optional credential-bearing connection data. The gateway
+  sends it for `required` connection mode; omit it for no-auth/public (`none`
+  mode) operations. For local debugging, pass
+  `{ "id", "mode", "secrets", "metadata", "externalRef" }` with local-only
+  secret values.
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Structured errors return an `error` object with `code`, `message`,
 `requestId`, and optional `details`; validation failures include field paths in
@@ -109,22 +121,24 @@ Structured errors return an `error` object with `code`, `message`,
 
 - `invalid_request`: include `requestId` and `input`; omit `connection` for
   public/no-auth operations and never send `connection: null`.
-- Credentials: declare `credential.keys`, pass local-only values through
-  `connection.secrets`, and read them with `ctx.credential`.
+- Credentials: declare `credential.keys` unless `auth.mode` is `platform-managed`;
+  that mode implies an unfiltered credential capability and forbids key declarations.
+  Pass local-only values through `connection.secrets` and read them with
+  `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
-- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
-  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
-  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
-  (`nodriver` is Python-runtime only), then install local Chromium with
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with
+  structured SDK `stealth: { browser, os }` selection; the TypeScript stealth runtime uses
+  `wreq-js` internally and supports Chrome, Firefox, and Safari. Use `ctx.browser` only when
+  the provider needs browser execution; TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
-2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
-   `ctx.stealth`, record a fixture with:
+2. Once the real operation calls the upstream through `ctx.http` or `ctx.stealth`
+   (absolute URLs, or relative ones under its `upstream.baseUrl`), record a fixture with:
    `bun run record -- --operation <operation> --params '<json-input>'`.
 3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
 4. Extend tests and operation metadata until the provider is bounty-ready.
@@ -144,8 +158,14 @@ Every operation must declare exactly one of:
 The generated `ping` operation uses `healthCheckUnsupported` only because it is
 a local scaffold check, not a real upstream API probe.
 
-`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
-`data` is the parsed operation output. Use this shape in real operations:
+A case carries either `scenario` or `assertions`, and only `scenario` is
+executed in production: the platform health monitor runs a case's serialized
+scenario and nothing else, because a closure cannot cross the registry's
+serialization boundary. A case with only `assertions` still publishes a probe,
+but its outcome is permanently `unknown` / `monitoring_unavailable` — the
+operation reads as monitored while nothing is checked, and `apifuse check`
+warns about it (`health-check-assertions-not-monitored`). Use this shape in
+real operations:
 
 ```ts
 healthCheck: {
@@ -153,11 +173,13 @@ healthCheck: {
   cases: [{
     name: "lookup baseline",
     input: { q: "btc" },
-    assertions: ({ data, status, durationMs }) => {
-      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
-        return { status: "degraded", label: "lookup baseline changed" };
-      }
-    },
+    scenario: lookupBaselineScenario, // defineHealthScenario({ ... })
   }],
 }
 ```
+
+If the operation reads through `ctx.cache.getOrSet(..., { staleIfErrorMs })`,
+add a guard step on the operation step result's `served_stale_cache` as well —
+otherwise an upstream outage is answered with a schema-valid 200 and the probe
+reports `ok` for the whole stale window. See
+`.agents/skills/health-checks-and-fail-closed/SKILL.md` for both shapes.

package/src/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,11 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
+  connectionMode: "none",
+  riskClass: "read",
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/src/cli/templates/provider/provider.json.tpl

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "providerId": "{{PROVIDER_ID}}",
+  "owner": "bounty",
+  "lifecycle": "draft"
+}