@tapi-dev/sdk 0.1.17 → 0.1.20

package/README.md

@@ -10,167 +10,266 @@ npm install @tapi-dev/sdk
 
 This package is ESM-first and works in runtimes with `fetch`, including modern Node.js and browser-like server runtimes.
 
-## Developer Flow
-
-Tapi Studio is launched from the developer app repo. The repo's `.tapi/project.json`
-is the project binding, so one developer can work on multiple Tapi projects from
-different directories without a global Studio project picker.
-
-```bash
-npm install @tapi-dev/sdk
-npx tapi init --project brokerage
-npx tapi studio
-```
-
-`tapi studio` checks the required local `tapi-service`, installs it when needed,
-downloads the portable Studio server release when the channel manifest uses
-`installerKind: portable-server`, starts Studio locally, and opens the browser.
-If the channel still publishes a legacy NSIS desktop Studio manifest and no
-Studio executable is installed yet, `tapi studio` runs the installer first, then
-opens Studio. The normal developer path is the portable server launched by the
-CLI.
-
-By default, Studio downloads and extracted portable server releases live under
-the user's local app data directory. On Windows that is usually
-`%LOCALAPPDATA%\Tapi\Studio`. To keep the whole Studio install on another drive,
-set `TAPI_STUDIO_HOME` before launching:
-
-```powershell
-$env:TAPI_STUDIO_HOME="F:\Tapi\Studio"
-npx tapi studio
-```
-
-For separate paths, use `--cache-dir` for downloaded zip artifacts and
-`--install-dir` for extracted portable Studio server releases.
-
-After a successful install, the CLI prunes older Tapi-managed download artifacts
-from the cache and older SDK-marked release folders from the install directory.
-The current artifact and current release are kept.
-
-Useful commands:
-
-```bash
-npx tapi init --project brokerage
-npx tapi link --project brokerage
-npx tapi studio
-npx tapi service install --channel pilot
-npx tapi service status
-npx tapi apis generate
-npx tapi publish
-```
-
-Local authoring files live in the app repo:
-
-```text
-.tapi/project.json
-.tapi/sitemaps/<site>.json
-.tapi/apis/<site>/<api>.json
-.tapi/generated/catalog.json
-src/tapi.generated.ts
-```
-
-Drafts are local. `tapi publish` uploads local sitemaps and API contracts, marks
-ready requests as published, and activates one immutable server release. Runtime
-SDK calls read the active release catalog, not mutable Studio drafts.
-
-```bash
-TAPI_API_KEY=tapi_project_key npx tapi publish
-TAPI_API_KEY=tapi_project_key npx tapi apis generate
+The CLI command is `tapi`. If your package manager only installed the SDK
+locally and `tapi` is not on `PATH`, use `npx tapi` as a fallback.
+
+## Developer Flow
+
+Tapi Studio is launched from the developer app repo. The repo's `.tapi/project.json`
+is the project binding, so one developer can work on multiple Tapi projects from
+different directories without a global Studio project picker.
+
+```bash
+npm install @tapi-dev/sdk
+tapi init --project brokerage
+tapi studio
+```
+
+`tapi studio` checks the required local `tapi-service`, installs it when needed,
+downloads the portable Studio server release when the channel manifest uses
+`installerKind: portable-server`, starts Studio locally, and opens the browser.
+If the channel still publishes a legacy NSIS desktop Studio manifest and no
+Studio executable is installed yet, `tapi studio` runs the installer first, then
+opens Studio. The normal developer path is the portable server launched by the
+CLI.
+
+By default, Studio downloads and extracted portable server releases live under
+the user's local app data directory. On Windows that is usually
+`%LOCALAPPDATA%\Tapi\Studio`. To keep the whole Studio install on another drive,
+set `TAPI_STUDIO_HOME` before launching:
+
+```powershell
+$env:TAPI_STUDIO_HOME="F:\Tapi\Studio"
+tapi studio
+```
+
+For separate paths, use `--cache-dir` for downloaded zip artifacts and
+`--install-dir` for extracted portable Studio server releases.
+
+After a successful install, the CLI prunes older Tapi-managed download artifacts
+from the cache and older SDK-marked release folders from the install directory.
+The current artifact and current release are kept.
+
+Useful commands:
+
+```bash
+tapi init --project brokerage
+tapi link --project brokerage
+tapi studio
+tapi service install --channel pilot
+tapi service status
+tapi apis generate
+tapi sessions
+tapi publish
+```
+
+Local authoring files live in the app repo:
+
+```text
+.tapi/project.json
+.tapi/sitemaps/<site>.json
+.tapi/apis/<site>/<api>.json
+.tapi/generated/catalog.json
+src/tapi.generated.ts
+```
+
+Drafts are local. `tapi publish` uploads local sitemaps and API contracts, marks
+ready requests as published, and activates one immutable server release. Runtime
+SDK calls read the active release catalog, not mutable Studio drafts.
+
+```bash
+TAPI_API_KEY=tapi_project_key tapi publish
+TAPI_API_KEY=tapi_project_key tapi apis generate
+```
+
+## Quick Start
+
+Create one TAPI client in server-side app code. Use a project-scoped API key and
+the same project id from `.tapi/project.json`.
+
+```ts
+import { TapiClient } from "@tapi-dev/sdk";
+
+export const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+});
+```
+
+Production is the default mode. Unknown website states fail the run instead of
+holding a browser open:
+
+```ts
+const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+  dev: false,
+});
+```
+
+During development, set `dev: true`. If a website reaches an unknown state,
+Tapi preserves the browser session for takeover instead of turning it into a
+production failure:
+
+```ts
+const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+  dev: true,
+});
+```
+
+Inspect preserved sessions from the repo:
+
+```bash
+tapi sessions
+tapi sessions --json
+tapi sessions open <session-id>
 ```
 
-## Quick Start
-
-Create one TAPI client in server-side app code. Use a project-scoped API key and
-the same project id from `.tapi/project.json`.
-
-```ts
-import { TapiClient } from "@tapi-dev/sdk";
-
-export const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  projectId: process.env.TAPI_PROJECT_ID!,
-});
-```
+`tapi sessions open` reuses the matching Studio window for the current repo when
+one is already running; otherwise it installs/starts Studio and opens directly
+to that session.
 
 Generated website APIs are authored visually in Tapi Studio by setting workflow
 bounds, selecting inputs/outputs, and publishing an API. The SDK sees the public
 operation name:
-
-```text
-<namespace>.<operation>
-```
-
-```ts
-const operation = await tapi.websiteApis.describe("schwab.place_order");
-
-const run = await tapi.websiteApis.run("schwab.place_order", {
-  inputs: {
-    symbol: "AAPL",
-    side: "buy",
-    quantity: 10,
-    orderType: "limit",
-    limitPrice: 190,
-  },
-});
-
-const completedRun = await tapi.runs.wait(run.id);
-console.log(completedRun.status, completedRun.result);
-```
-
-## API-Call Triggers
-
-Triggers are scheduled calls to published website APIs. Keep trigger definitions
-in the app repo and sync them after publishing the API catalog:
-
-```ts
-// tapi.config.ts
-export default {
-  triggers: {
-    nightlyBalance: {
-      apiRequest: "schwab.get_balance",
-      schedule: { cron: "0 9 * * MON-FRI" },
-      inputs: { accountId: "main" },
-      runtime: { profileRef: "perm_default" },
-    },
-  },
-};
-```
-
-```bash
-TAPI_API_KEY=tapi_project_key npx tapi triggers sync
-```
-
-`triggers sync` upserts by trigger name for the current `.tapi/project.json`
-project. Schedules support standard five-field cron strings or intervals as
-numbers of seconds / strings like `30s`, `15m`, `2h`, and `1d`.
-
-You can also manage triggers directly:
-
-```ts
-await tapi.triggers.create({
-  name: "nightlyBalance",
-  apiRequest: "schwab.get_balance",
-  schedule: { cron: "0 9 * * MON-FRI" },
-  inputs: { accountId: "main" },
-  runtime: { profileRef: "perm_default" },
-});
-
-await tapi.triggers.fire("act_123");
-await tapi.triggers.disable("act_123");
-```
-
-You can inspect the same input/output contract from the CLI:
-
-```bash
-npx tapi apis describe schwab.place_order \
-  --api-base-url "$TAPI_BASE_URL" \
-  --api-key "$TAPI_API_KEY" \
-  --project "$TAPI_PROJECT_ID"
-```
-
-Do not expose `TAPI_API_KEY` in public browser bundles. Put the SDK behind your
-own backend route, server action, or job worker when using secret API keys.
+
+```text
+<namespace>.<operation>
+```
+
+```ts
+const operation = await tapi.websiteApis.describe("schwab.place_order");
+
+const run = await tapi.websiteApis.run("schwab.place_order", {
+  inputs: {
+    symbol: "AAPL",
+    side: "buy",
+    quantity: 10,
+    orderType: "limit",
+    limitPrice: 190,
+  },
+});
+
+const completedRun = await tapi.runs.wait(run.id);
+console.log(completedRun.status, completedRun.result);
+```
+
+## Late Inputs
+
+Most API inputs are known before the run starts. Use `lateInput()` when the
+workflow needs a value later, after earlier browser steps have triggered work
+somewhere else.
+
+For example, state 4 might submit a login form and trigger a one-time code by
+email or SMS. State 5 needs that code, but your app can only retrieve it after
+state 4 runs. Declare the input up front with the API call, then resolve it
+from your own code:
+
+```ts
+import { lateInput } from "@tapi-dev/sdk";
+
+const verificationCode = lateInput<string>({
+  resolve: async () => {
+    return await waitForVerificationCodeFromEmail();
+  },
+  timeoutMs: 180_000,
+});
+
+const run = await tapi.websiteApis.run("walmart.login", {
+  inputs: {
+    email: "buyer@example.com",
+    password: process.env.WALMART_PASSWORD!,
+    verificationCode,
+  },
+});
+
+await verificationCode.waitForProvides();
+
+const completedRun = await tapi.runs.wait(run.id);
+```
+
+You can also provide the value manually. This is useful when another callback,
+worker, webhook, or polling loop finds the value:
+
+```ts
+const verificationCode = lateInput<string>({ timeoutMs: 180_000 });
+
+const run = await tapi.websiteApis.run("walmart.login", {
+  inputs: { email: "buyer@example.com", verificationCode },
+});
+
+const code = await waitForVerificationCodeFromWebhook();
+await verificationCode.set(code);
+
+const completedRun = await tapi.runs.wait(run.id);
+```
+
+Tapi only waits when the runner reaches the action bound to that input. If your
+app resolves the value early, Tapi stores it and uses it later. If the value is
+not provided before `timeoutMs`, the run fails instead of guessing or using the
+recorded default.
+
+Late inputs are for values produced outside the website flow. Values read from
+the website itself should stay as normal API outputs.
+
+## API-Call Triggers
+
+Triggers are scheduled calls to published website APIs. Keep trigger definitions
+in the app repo and sync them after publishing the API catalog:
+
+```ts
+// tapi.config.ts
+export default {
+  triggers: {
+    nightlyBalance: {
+      apiRequest: "schwab.get_balance",
+      schedule: { cron: "0 9 * * MON-FRI" },
+      inputs: { accountId: "main" },
+      runtime: { profileRef: "perm_default" },
+    },
+  },
+};
+```
+
+```bash
+TAPI_API_KEY=tapi_project_key tapi triggers sync
+```
+
+`triggers sync` upserts by trigger name for the current `.tapi/project.json`
+project. Schedules support standard five-field cron strings or intervals as
+numbers of seconds / strings like `30s`, `15m`, `2h`, and `1d`.
+
+You can also manage triggers directly:
+
+```ts
+await tapi.triggers.create({
+  name: "nightlyBalance",
+  apiRequest: "schwab.get_balance",
+  schedule: { cron: "0 9 * * MON-FRI" },
+  inputs: { accountId: "main" },
+  runtime: { profileRef: "perm_default" },
+});
+
+await tapi.triggers.fire("act_123");
+await tapi.triggers.disable("act_123");
+```
+
+You can inspect the same input/output contract from the CLI:
+
+```bash
+tapi apis describe schwab.place_order \
+  --api-base-url "$TAPI_BASE_URL" \
+  --api-key "$TAPI_API_KEY" \
+  --project "$TAPI_PROJECT_ID"
+```
+
+Do not expose `TAPI_API_KEY` in public browser bundles. Put the SDK behind your
+own backend route, server action, or job worker when using secret API keys.
 
 ## Runtime Profiles and Proxies
 
@@ -241,17 +340,17 @@ const tapi = new TapiClient({
 });
 ```
 
-## Configuration
-
-```env
-TAPI_BASE_URL=https://your-tapi-api-host
-TAPI_API_KEY=tapi_project_key
-TAPI_PROJECT_ID=brokerage
-```
-
-`projectId` is optional only when the API key itself is project-scoped. If
-provided, the SDK sends it as the `X-Tapi-Project` header and the server rejects
-mismatches.
+## Configuration
+
+```env
+TAPI_BASE_URL=https://your-tapi-api-host
+TAPI_API_KEY=tapi_project_key
+TAPI_PROJECT_ID=brokerage
+```
+
+`projectId` is optional only when the API key itself is project-scoped. If
+provided, the SDK sends it as the `X-Tapi-Project` header and the server rejects
+mismatches.
 
 ## Common Project Setup
 
@@ -267,12 +366,12 @@ src/
 // src/lib/tapi.ts
 import { TapiClient } from "@tapi-dev/sdk";
 
-export const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  projectId: process.env.TAPI_PROJECT_ID!,
-});
-```
+export const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+});
+```
 
 Application code should import this shared client instead of constructing a new client in every file.
 
@@ -297,126 +396,127 @@ const run = await tapi.websiteApis.run("apiName.requestKey", {
 });
 
 await tapi.runs.get(run.id);
-await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
-await tapi.runs.cancel(run.id);
-```
-
-## Cloud Batch Runs
-
-Cloud runs are requested from the SDK, but VM provisioning, service
-installation, worker leases, browser internals, and AWS cleanup stay on the
-Tapi server. The SDK is only the front door.
-
-Keep this code server-side. Do not put `TAPI_API_KEY` in a browser bundle and
-do not wire AWS or Stripe from the developer's app. The app sends its own user
-identity to Tapi, and Tapi handles prepaid Stripe checkout, credit accounting,
-AWS worker provisioning, and cleanup.
-
-The minimum developer flow is:
-
-1. App user clicks a button.
-2. The developer's backend calls `runCloudBatch` with `user.externalUserId`.
-3. If the returned run has `status: "payment_required"`, redirect the app user
-   to `run.checkoutUrl`.
-4. Stripe calls the Tapi webhook, Tapi credits that same `externalUserId`, and
-   the app retries the cloud batch.
-5. If credit is available, Tapi reserves the balance and starts cloud workers.
-
-```ts
-// backend route or server action
-const quote = await tapi.websiteApis.quoteCloud("schwab.place_order", {
-  inputs: [
-    { symbol: "AAPL", quantity: 1 },
-    { symbol: "MSFT", quantity: 2 },
-  ],
-  user: {
-    externalUserId: appUser.id,
-    email: appUser.email,
-  },
-  cloud: {
-    windows: true,
-    maxVms: 1,
-    chromePerVm: 10,
-    maxCostUsd: 20,
-  },
-});
-
-if (!quote.withinMaxCost) {
-  throw new Error("Cloud batch exceeds the configured cost cap");
-}
-
-const run = await tapi.websiteApis.runCloudBatch("schwab.place_order", {
-  inputs: [
-    { symbol: "AAPL", quantity: 1 },
-    { symbol: "MSFT", quantity: 2 },
-  ],
-  user: {
-    externalUserId: appUser.id,
-    email: appUser.email,
-  },
-  payment: {
-    successUrl: `https://your-app.example/cloud/success`,
-    cancelUrl: `https://your-app.example/cloud/cancel`,
-  },
-  cloud: {
-    windows: true,
-    maxVms: 1,
-    chromePerVm: 10,
-    maxCostUsd: 20,
-  },
-});
-
-if (run.status === "payment_required") {
-  return { redirectTo: run.checkoutUrl };
-}
-
-for await (const event of tapi.cloudRuns.stream(run.id)) {
-  console.log(event.status, event.traceId);
-}
-
-const results = await tapi.cloudRuns.results(run.id);
-```
-
-When `CLOUD_BILLING_ENABLED=true`, the server refuses to launch AWS workers
-unless prepaid cloud credit is available and reserved first. If balance is too
-low, `runCloudBatch` converts the server's HTTP `402` into a normal
-`CloudBatchRun` object with `status: "payment_required"`, `checkoutUrl`,
-`availableBalanceCents`, and `requiredBalanceCents`. That keeps the button
-handler simple.
-
-Credits are scoped under the Tapi API key owner, app id, and
-`user.externalUserId`. Use the same `externalUserId` for quote, balance,
-checkout, and run calls. If you omit `externalUserId` but provide `email`, Tapi
-uses the normalized email as the external user id.
-
-Applications can also create a top-up checkout explicitly:
-
-```ts
-const user = {
-  externalUserId: appUser.id,
-  email: appUser.email,
-};
-
-const balance = await tapi.cloudRuns.balance(user);
-
-if (balance.balanceCents < balance.minimumBalanceCents) {
-  const checkout = await tapi.cloudRuns.checkout({
-    amountCents: balance.minimumBalanceCents,
-    user,
-    successUrl: "https://your-app.example/cloud/success",
-    cancelUrl: "https://your-app.example/cloud/cancel",
-  });
-  console.log(checkout.checkoutUrl);
-}
-```
-
-The developer application does not need VM provisioning logic, installer
-deployment logic, worker command interpretation, browser runner internals, or
-builder logic. Those stay behind the Tapi server API.
-
-Website API requests are addressed as `<namespace>.<operation>`. The namespace
-comes from the generated website name in Studio. The operation is the name the
-developer types into the SDK name textbox at the workflow boundary.
+await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
+await tapi.runs.provideInput(run.id, "verificationCode", "123456");
+await tapi.runs.cancel(run.id);
+```
+
+## Cloud Batch Runs
+
+Cloud runs are requested from the SDK, but VM provisioning, service
+installation, worker leases, browser internals, and AWS cleanup stay on the
+Tapi server. The SDK is only the front door.
+
+Keep this code server-side. Do not put `TAPI_API_KEY` in a browser bundle and
+do not wire AWS or Stripe from the developer's app. The app sends its own user
+identity to Tapi, and Tapi handles prepaid Stripe checkout, credit accounting,
+AWS worker provisioning, and cleanup.
+
+The minimum developer flow is:
+
+1. App user clicks a button.
+2. The developer's backend calls `runCloudBatch` with `user.externalUserId`.
+3. If the returned run has `status: "payment_required"`, redirect the app user
+   to `run.checkoutUrl`.
+4. Stripe calls the Tapi webhook, Tapi credits that same `externalUserId`, and
+   the app retries the cloud batch.
+5. If credit is available, Tapi reserves the balance and starts cloud workers.
+
+```ts
+// backend route or server action
+const quote = await tapi.websiteApis.quoteCloud("schwab.place_order", {
+  inputs: [
+    { symbol: "AAPL", quantity: 1 },
+    { symbol: "MSFT", quantity: 2 },
+  ],
+  user: {
+    externalUserId: appUser.id,
+    email: appUser.email,
+  },
+  cloud: {
+    windows: true,
+    maxVms: 1,
+    chromePerVm: 10,
+    maxCostUsd: 20,
+  },
+});
+
+if (!quote.withinMaxCost) {
+  throw new Error("Cloud batch exceeds the configured cost cap");
+}
+
+const run = await tapi.websiteApis.runCloudBatch("schwab.place_order", {
+  inputs: [
+    { symbol: "AAPL", quantity: 1 },
+    { symbol: "MSFT", quantity: 2 },
+  ],
+  user: {
+    externalUserId: appUser.id,
+    email: appUser.email,
+  },
+  payment: {
+    successUrl: `https://your-app.example/cloud/success`,
+    cancelUrl: `https://your-app.example/cloud/cancel`,
+  },
+  cloud: {
+    windows: true,
+    maxVms: 1,
+    chromePerVm: 10,
+    maxCostUsd: 20,
+  },
+});
+
+if (run.status === "payment_required") {
+  return { redirectTo: run.checkoutUrl };
+}
+
+for await (const event of tapi.cloudRuns.stream(run.id)) {
+  console.log(event.status, event.traceId);
+}
+
+const results = await tapi.cloudRuns.results(run.id);
+```
+
+When `CLOUD_BILLING_ENABLED=true`, the server refuses to launch AWS workers
+unless prepaid cloud credit is available and reserved first. If balance is too
+low, `runCloudBatch` converts the server's HTTP `402` into a normal
+`CloudBatchRun` object with `status: "payment_required"`, `checkoutUrl`,
+`availableBalanceCents`, and `requiredBalanceCents`. That keeps the button
+handler simple.
+
+Credits are scoped under the Tapi API key owner, app id, and
+`user.externalUserId`. Use the same `externalUserId` for quote, balance,
+checkout, and run calls. If you omit `externalUserId` but provide `email`, Tapi
+uses the normalized email as the external user id.
+
+Applications can also create a top-up checkout explicitly:
+
+```ts
+const user = {
+  externalUserId: appUser.id,
+  email: appUser.email,
+};
+
+const balance = await tapi.cloudRuns.balance(user);
+
+if (balance.balanceCents < balance.minimumBalanceCents) {
+  const checkout = await tapi.cloudRuns.checkout({
+    amountCents: balance.minimumBalanceCents,
+    user,
+    successUrl: "https://your-app.example/cloud/success",
+    cancelUrl: "https://your-app.example/cloud/cancel",
+  });
+  console.log(checkout.checkoutUrl);
+}
+```
+
+The developer application does not need VM provisioning logic, installer
+deployment logic, worker command interpretation, browser runner internals, or
+builder logic. Those stay behind the Tapi server API.
+
+Website API requests are addressed as `<namespace>.<operation>`. The namespace
+comes from the generated website name in Studio. The operation is the name the
+developer types into the SDK name textbox at the workflow boundary.
 
 `describe()` returns the public SDK contract: input controls such as
 `textbox`, `radio`, `select`, `checkbox`, conditional requirements such as
@@ -446,6 +546,7 @@ The package includes generated TypeScript declarations. Common exported types in
 
 ```ts
 import type {
+  LateInput,
   RuntimeRequirements,
   RuntimeProfile,
   RuntimeRunOptions,