@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.10

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

@@ -8,6 +8,65 @@ Generated with `apifuse create`.
 bun run dev
 bun run check
 bun run test
+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:
+
+```bash
+bun run submit-check
+```
+
+This writes `submission-report.md` with a review-readiness score, blockers,
+warnings, health coverage notes, fixture/schema evidence, and remediation. A
+score is not a payout guarantee; blockers must be fixed before maintainer
+review. The generated `ping` starter intentionally warns until you replace it
+with real upstream-backed Operations. The full public-only checklist is shipped
+in `node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
+
+
+## Operation guide
+
+### Parameters
+
+Starter `ping` accepts `{ "value": string }`. Replace this section with each
+real operation's input schema, required fields, formats, limits, and examples
+before submitting bounty evidence.
+
+### Response
+
+Starter `ping` returns `{ "ok": boolean, "message": string }`. Replace this
+section with the normalized response fields, units, enum values, pagination,
+and upstream caveats for each real operation.
+
+### Example
+
+```json
+{
+	"requestId": "req_local_ping",
+	"input": { "value": "hello" },
+	"headers": {}
+}
 ```
 
 ## Provider server contract
@@ -21,13 +80,55 @@ bun run test
 - `POST /auth/poll`
 - `POST /auth/disconnect`
 
+## Local smoke
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
+```
+
+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.
+
+Structured errors return an `error` object with `code`, `message`,
+`requestId`, and optional `details`; validation failures include field paths in
+`details`, and the `apifuse dev` terminal prints a structured provider log.
+
+## Debugging checklist
+
+- `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`.
+- 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
+  `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
+
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
-2. Record a real fixture with `bun run record:sample` or a provider-specific equivalent.
+2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
+   `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.
 
+`apifuse record` is not expected to work with the generated local-only `ping`
+operation because it intentionally has no upstream response to capture.
+
 ## Health-check authorship
 
 Every operation must declare exactly one of:
@@ -39,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,24 +1,7 @@
-import { defineProvider, z } from "@apifuse/provider-sdk";
+import { defineProvider } from "@apifuse/provider-sdk/provider";
 
-const InputSchema = z
-  .object({
-    value: z
-      .string()
-      .default("hello")
-      .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}}",
@@ -27,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,24 @@
+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 ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
+    };
+  },
+  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,24 @@
+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"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
+  }),
+  "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.