@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/AUTHORING.md

@@ -264,6 +264,140 @@ deployment projection checks, and release workflows.
 - Credential-backed smoke requests pass local-only credential material in
   `connection.secrets`. Keep real values in shell env or `.env`, never in source
   or fixtures.
+- Hand-written auth flows should use `ctx.auth` helpers and return exactly one
+  terminal/next turn from each handler: `ctx.auth.nextForm(...)` or
+  `ctx.auth.nextPoll(...)` to ask Gateway for the next user/system step,
+  `ctx.auth.complete(...)` to finish with `data.credential`, or
+  `ctx.auth.abort(...)` to stop safely. Keep abort `data` and `actionHint`
+  JSON-safe and secret-free; never include raw cookies, credentials, headers,
+  HTML, or upstream `Error` objects.
+
+```ts
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: {
+    mode: "credentials",
+    flow: {
+      async start(ctx) {
+        return ctx.auth.nextForm({
+          fields: {
+            email: { type: "email", labelKey: "auth.email.label" },
+            password: { type: "password", labelKey: "auth.password.label" },
+          },
+          hintKey: "auth.signIn",
+        });
+      },
+      async continue(ctx, input) {
+        const result = await loginWithSubmittedFields(ctx, input);
+        if (result.blocked) {
+          return ctx.auth.abort({
+            code: "account_action_required",
+            retry: "after_user_action",
+            actionHint: { kind: "open_provider_app" },
+            message: "Approve the login in the provider app.",
+          });
+        }
+        return ctx.auth.complete({
+          credential: { cookie: result.cookie },
+          metadata: { accountId: result.accountId },
+        });
+      },
+    },
+  },
+  credential: { keys: ["cookie"] },
+  // ...metadata and operations
+});
+```
+
+- Credentials auth providers should use `defineCredentialsAuth()` instead of
+  hand-writing `auth.flow.start/continue`. The helper exposes one happy path:
+  declare form `fields`, declare `credentialKeys`, and put upstream login/session
+  creation in `login(ctx, input)`. It returns both `auth` and `credential` for
+  `defineProvider()` and builds the complete turn as `data.credential`, which is
+  the only value Gateway persists onto the connection.
+
+```ts
+import { defineCredentialsAuth, defineProvider } from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email", labelKey: "auth.email.label" },
+    password: { type: "password", labelKey: "auth.password.label" },
+  },
+  credentialKeys: ["cookie"] as const,
+  storesReusableSecret: true,
+  justification: "Session cookie is required for authenticated operations.",
+  async login(ctx, input) {
+    const cookie = await loginAndBuildSessionCookie(ctx, input);
+    return { credential: { cookie } };
+  },
+});
+
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: credentialsAuth.auth,
+  credential: credentialsAuth.credential,
+  context: credentialsAuth.context,
+  // ...metadata and operations
+});
+```
+
+For OTP, MFA, CAPTCHA handoff, or user-approved login, return a challenge from
+`login()` instead of hand-writing `contextPatch`, `poll`, and final credential
+turns. SDK stores the pending challenge in auth-flow context, returns the next
+form/pending turn, and still persists only the final `data.credential`.
+
+```ts
+import {
+  credentialsAuthChallenge,
+  defineCredentialsAuth,
+} from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email" },
+    password: { type: "password" },
+  },
+  credentialKeys: ["cookie"] as const,
+  async login(ctx, input) {
+    const result = await passwordLogin(ctx, input);
+    if (result.otpRequired) {
+      return credentialsAuthChallenge("otp", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.otp.prompt",
+      });
+    }
+    if (result.manualApprovalRequired) {
+      return credentialsAuthChallenge("manualApproval", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.manualApproval.openApp",
+        timing: { suggestedPollIntervalMs: 3000, maxWaitMs: 120000 },
+      });
+    }
+    return { credential: { cookie: result.cookie } };
+  },
+  challenges: {
+    otp: {
+      fields: { otp: { type: "otp", labelKey: "auth.otp.label" } },
+      async verify(ctx, input, state) {
+        const result = await verifyOtp(ctx, state.transactionId, input.otp);
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+    manualApproval: {
+      async poll(ctx, state) {
+        const result = await checkApproval(ctx, state.transactionId);
+        if (!result.approved) return null;
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+  },
+});
+```
 - Auth-flow debugging starts with `/auth/start`, continues with
   `/auth/continue`, and carries returned `contextPatch` values into the next
   request's `context`.

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.2
+
+- Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.
+
+## 2.2.0-beta.1
+
+- Release candidate for main commit 5056b8c89fe0fa8f10bafcd30f83bcc421d4b5c5.
+
+## 2.1.0-beta.22
+
+- Release candidate for main commit af84b1e91c408b69773468fdaef80a01a36707cf.
+
+## 2.1.0-beta.21
+
+- Release candidate for main commit 8124b3eb150cc7a73a86a95266b3747763a494ae.
+
+## 2.1.0-beta.20
+
+- Release candidate for main commit 2a07cc5aef0d517c3b01d20445105f1669446bd3.
+
+## 2.1.0-beta.19
+
+- Release candidate for main commit 71d76385f722b1202880f26b14ea3916a07852eb.
+
+## 2.1.0-beta.18
+
+- Release candidate for main commit 46f93ecf8c2c8aab1afd0f23f5f62a87cbb45f6d.
+
+## 2.1.0-beta.17
+
+- Release candidate for main commit c4466ffc8a30cb99740b50687a62b92cec9ba10e.
+
+## 2.1.0-beta.16
+
+- Release candidate for main commit c0d8a1c4be519e1c1abc59e0304efc64f371634d.
+
+## Unreleased
+
+- Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
+- Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
+
+## 2.1.0-beta.15
+
+- Release candidate for main commit 4f51232d87828082f117dcc9f0c257a46f37c040.
+
+## 2.1.0-beta.14
+
+- Release candidate for main commit 6eb132be6abf34ad9a70bfe28c6d26b36348ff4a.
+
+## 2.1.0-beta.13
+
+- Release candidate for main commit d7b12716f54781df3e40206144c167844a485f8f.
+
+## 2.1.0-beta.12
+
+- Release candidate for main commit 2bc1061c6a68facaa2efde08bee31bf5cd96945e.
+
+## 2.1.0-beta.11
+
+- Release candidate for main commit b98ddc5024698f8c79e05e3295f7c8c8e8fe5a8a.
+
 ## 2.1.0-beta.9
 
 - Preserve raw stealth response bytes through the public SDK response wrapper.

package/README.md

@@ -56,7 +56,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
-bun run submit-check
+bun run submit-check -- --smoke
 bun run dev
 ```
 
@@ -120,16 +120,28 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
   `.env`, and read only those names through `ctx.env.get("NAME")`.
+- **Credentials auth flows**: prefer `defineCredentialsAuth()` over hand-written
+  `auth.flow`. Declare the form fields and credential keys once, then put the
+  upstream login/session creation in `login(ctx, input)`. Return
+  `credentialsAuthChallenge("otp" | "manualApproval" | ...)` for MFA, CAPTCHA
+  handoff, or user-approved login branches. The helper returns
+  `{ auth, credential, context }` for `defineProvider()` and always completes
+  with `data.credential`, which is the value Gateway persists onto the
+  connection.
 - **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
   `flowId`; preserve any returned `contextPatch` in the next local request's
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
-  `ctx.stealth.fetch()` when you need browser-like session or cookie control. `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and accepts request
-  controls for `params`, `proxy`, `timeout`, `profile`, `throwOnHttpError`, and
-  `stealth.insecureSkipVerify`. Select an SDK stealth `profile` such as
-  `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or pseudo-header order in
-  provider code. Chrome/Firefox-style profiles are supported; use `ctx.browser`
-  when Safari-specific behavior is required.
+  `ctx.stealth.fetch()` when you need browser-like session or cookie control.
+  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
+  accepts request controls for `params`, `proxy`, `timeout`, `profile`,
+  `redirect`, `throwOnHttpError`, and `stealth.insecureSkipVerify`. For login
+  flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
+  a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
+  inspect accumulated cookies through `session.cookies`. Select an SDK stealth
+  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
+  pseudo-header order in provider code. Chrome/Firefox-style profiles are
+  supported; use `ctx.browser` when Safari-specific behavior is required.
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when
@@ -233,10 +245,10 @@ be replaced before recording fixtures.
 Standalone providers include a pre-submission script:
 
 ```bash
-bun run submit-check
+bun run submit-check -- --smoke
 ```
 
-This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, and remediation. Blockers override the score; fix them before posting bounty evidence. The command is offline-safe by default and does not execute arbitrary upstream calls. Add local smoke notes to your assigned workspace PR after testing `/health` and `POST /v1/{operation}`. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, measured smoke details, and remediation. Blockers override the score; fix them before posting bounty evidence. `--smoke` boots the local dev server, checks `/health`, and POSTs every operation fixture. Set `APIFUSE__PROVIDER__*` env vars when live upstream credentials are available; without them, structured provider errors can still earn runtime-path smoke credit. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
 
 ## Scope boundary
 

package/SUBMISSION.md

@@ -9,11 +9,11 @@ bunx @apifuse/provider-sdk@beta create my-provider --yes
 cd my-provider
 bun run check
 bun run test
-bun run submit-check
+bun run submit-check -- --smoke
 bun run dev
 ```
 
-`bun run submit-check` runs `apifuse submit-check . --markdown submission-report.md` in generated Providers.
+`bun run submit-check -- --smoke` runs the generated `apifuse submit-check . --markdown submission-report.md` script with measured smoke enabled.
 
 ## What submit-check scores
 
@@ -52,20 +52,19 @@ Fix all blockers before submitting:
 
 Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
 
-## Safe local smoke evidence
+## Measured local smoke
 
-`submit-check` does not call arbitrary live upstream APIs by default. After replacing starter logic, run the Provider locally and record a short evidence note:
+`submit-check` does not call live upstream APIs by default. For smoke scoring,
+run measured smoke so the CLI boots the Provider, checks `/health`, and POSTs
+each operation fixture:
 
 ```bash
-bun run dev
-curl -s http://localhost:3900/health
-curl -s -X POST http://localhost:3900/v1/<operation> \
-  -H 'Content-Type: application/json' \
-  -d '{"requestId":"req_local_smoke","input":{...},"headers":{}}'
-
-bun run submit-check -- --smoke-note "GET /health and POST /v1/<operation> passed locally with redacted input."
+bun run submit-check -- --smoke
 ```
 
+`APIFUSE__PROVIDER__*` env vars enable live upstream calls. Their absence can
+still produce 7/10 smoke credit when every operation routes and returns a
+structured provider error envelope, but zero schema-valid successes are observed.
 Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into workspace PR comments, chat, or reports.
 
 ## Submission evidence checklist

package/bin/apifuse-pack-check.ts

@@ -36,6 +36,9 @@ const requiredPaths = [
 	"bin/apifuse-submit-check.ts",
 	"SUBMISSION.md",
 	"src/cli/create.ts",
+	"src/cli/templates/provider/.dockerignore.tpl",
+	"src/cli/templates/provider/.gitignore.tpl",
+	"src/cli/templates/provider/Dockerfile.tpl",
 	"src/cli/templates/provider/index.ts.tpl",
 	"src/cli/templates/provider/README.md.tpl",
 	"src/cli/templates/provider/meta.ts.tpl",
@@ -45,6 +48,25 @@ const requiredPaths = [
 	"src/cli/templates/provider/operations/ping.ts.tpl",
 	"src/cli/templates/provider/schemas/ping.ts.tpl",
 	"src/cli/templates/provider/upstream/README.md.tpl",
+	"dist/cli/templates/provider/.dockerignore.tpl",
+	"dist/cli/templates/provider/.gitignore.tpl",
+	"dist/cli/templates/provider/Dockerfile.tpl",
+	"dist/cli/templates/provider/index.ts.tpl",
+	"dist/cli/templates/provider/README.md.tpl",
+	"dist/cli/templates/provider/meta.ts.tpl",
+	"dist/cli/templates/provider/domain/README.md.tpl",
+	"dist/cli/templates/provider/mappers/README.md.tpl",
+	"dist/cli/templates/provider/operations/index.ts.tpl",
+	"dist/cli/templates/provider/operations/ping.ts.tpl",
+	"dist/cli/templates/provider/schemas/ping.ts.tpl",
+	"dist/cli/templates/provider/upstream/README.md.tpl",
+	"dist/auth-turn/index.js",
+	"dist/auth-turn/index.d.ts",
+	"dist/auth-turn/auth-turn.v1.schema.json",
+	"dist/auth-turn/fixtures/valid/abort.json",
+	"dist/auth-turn/fixtures/valid/complete.json",
+	"dist/auth-turn/fixtures/invalid/unknown-top-level-field.json",
+	"src/auth-turn/auth-turn.v1.schema.json",
 ];
 const forbiddenMatches = filePaths.filter(
 	(path) =>