@apifuse/provider-sdk 2.1.0-beta.3 → 2.1.0-beta.5

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

@@ -12,6 +12,23 @@ bun run submit-check
 ```
 
 
+## Module layout
+
+The generated provider uses the recommended split layout:
+
+```text
+index.ts              # composition root: defineProvider() and wiring only
+meta.ts               # provider metadata
+operations/           # APIFuse operation contracts and handlers
+schemas/              # public input/output schemas near operations
+upstream/             # upstream ceremony: clients, auth, request builders
+mappers/              # upstream-to-APIFuse normalization helpers
+domain/               # shared provider-specific business ceremony
+```
+
+Small providers may stay in one file, but larger providers are easier to
+review when `index.ts` remains a short composition root.
+
 ## Pre-submission report
 
 Before posting bounty evidence, run:
@@ -93,18 +110,18 @@ Structured errors return an `error` object with `code`, `message`,
   `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`.
-- TLS/browser runtime: if Bun blocks native dependency lifecycle scripts, run
-  `bun pm untrusted` and trust SDK dependencies such as `koffi` before debugging
-  `ctx.tls`; for TypeScript browser Providers use
-  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only),
-  then install local Chromium with `bunx playwright install chromium` or set
-  `CDP_POOL_URL`.
+- 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
+  `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.tls`, record a fixture with:
+   `ctx.stealth`, 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.
@@ -123,3 +140,21 @@ 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:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  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" };
+      }
+    },
+  }],
+}
+```

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

@@ -2,4 +2,4 @@ import { startDevServer } from "@apifuse/provider-sdk";
 
 import provider from "./index";
 
-startDevServer(provider, { port: Number(process.env.PORT) || 3900 });
+startDevServer(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3900 });

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

@@ -0,0 +1,3 @@
+# Domain
+
+Put provider-specific business ceremony here when it is shared across operations and too complex to live inside one operation module.

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

@@ -1,23 +1,7 @@
-import { defineProvider, z } from "@apifuse/provider-sdk";
+import { defineProvider } from "@apifuse/provider-sdk/provider";
 
-const InputSchema = z
-  .object({
-    value: z
-      .string()
-      .describe("Sample input value used to verify the generated provider scaffold is wired correctly."),
-  })
-  .describe("Input payload for the generated ping operation.");
-
-const OutputSchema = z
-  .object({
-    ok: z
-      .boolean()
-      .describe("Whether the generated provider handled the sample request successfully."),
-    message: z
-      .string()
-      .describe("Human-readable confirmation that the generated provider round-tripped the sample payload."),
-  })
-  .describe("Output payload returned by the generated ping operation.");
+import { providerMeta } from "./meta";
+import { operations } from "./operations";
 
 export default defineProvider({
   id: "{{PROVIDER_ID}}",
@@ -26,32 +10,6 @@ export default defineProvider({
   allowedHosts: ["api.example.com"],
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
-  meta: {
-    displayName: "{{DISPLAY_NAME}}",
-    description: "{{DISPLAY_NAME}} provider starter for ApiFuse community contributions.",
-    category: "{{CATEGORY}}",
-    tags: ["{{PROVIDER_ID}}", "starter", "community"],
-  },
-  operations: {
-    ping: {
-      description:
-        "Confirms the generated provider wiring is operational by echoing a small sample payload through the ApiFuse runtime contract. Use when validating local development, baseline checks, or first-pass bounty scaffolds. Do NOT use for production data retrieval or upstream-specific workflows because this starter operation exists only to prove the generated project compiles, serves, and round-trips input/output correctly. Returns a success flag plus a message containing the supplied value.",
-      input: InputSchema,
-      output: OutputSchema,
-      handler: async (_ctx, input) => {
-        return {
-          ok: true,
-          message: "{{DISPLAY_NAME}} received: " + input.value,
-        };
-      },
-      fixtures: {
-        request: { value: "hello" },
-        response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
-      },
-      healthCheckUnsupported: {
-        reason:
-          "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
-      },
-    },
-  },
+  meta: providerMeta,
+  operations: operations,
 });

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

@@ -0,0 +1,3 @@
+# Mappers
+
+Put normalization helpers here when upstream responses need to become public APIFuse operation outputs.

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

@@ -0,0 +1,7 @@
+export const providerMeta = {
+  displayName: "{{PROVIDER_ID}}",
+  displayNameKey: "meta.displayName",
+  descriptionKey: "meta.description",
+  category: "{{CATEGORY}}",
+  tags: ["{{PROVIDER_ID}}", "starter", "community"],
+} as const;

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

@@ -0,0 +1,5 @@
+import { pingOperation } from "./ping";
+
+export const operations = {
+  ping: pingOperation,
+};

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

@@ -0,0 +1,23 @@
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+
+import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
+
+export const pingOperation = defineOperation({
+  descriptionKey: "operations.ping.description",
+  input: pingInputSchema,
+  output: pingOutputSchema,
+  handler: async (_ctx, input) => {
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value,
+    };
+  },
+  fixtures: {
+    request: { value: "hello" },
+    response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
+  },
+  healthCheckUnsupported: {
+    reason:
+      "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+  },
+});

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

@@ -0,0 +1,16 @@
+import { describeKey, z } from "@apifuse/provider-sdk/provider";
+
+export const pingInputSchema = describeKey(
+  z.object({
+    value: describeKey(z.string(), "schemaDescriptions.input.value"),
+  }),
+  "schemaDescriptions.input.root",
+);
+
+export const pingOutputSchema = describeKey(
+  z.object({
+    ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
+    message: describeKey(z.string(), "schemaDescriptions.output.message"),
+  }),
+  "schemaDescriptions.output.root",
+);

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

@@ -2,4 +2,4 @@ import { serve } from "@apifuse/provider-sdk";
 
 import provider from "./index";
 
-await serve(provider, { port: Number(process.env.PORT) || 3000 });
+await serve(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3000 });

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

@@ -0,0 +1,3 @@
+# Upstream
+
+Put upstream HTTP clients, auth ceremony helpers, request builders, and protocol-specific types here once the provider talks to the real upstream service.