@tapi-dev/sdk 0.1.34 → 0.1.36

package/README.md

@@ -55,57 +55,86 @@ 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
+tapi studio
+tapi service install --channel pilot
+tapi service status
+tapi services describe schwab.place_order
+tapi tapp create brokerage
+tapi queue create "John"
+tapi tapp queue add brokerage queue_abc123
+tapi runner setup --runner-id john-laptop --project brokerage
+tapi runner slot set john-laptop 1 queue_abc123 --project brokerage
+tapi tapp service add brokerage schwab.place_order --service-map sm_123 --entry place_order
+tapi triggers sync
+tapi sessions
+```
+
+Local project identity lives in the app repo:
+
+```text
+.tapi/project.json
+.tapi/services/catalog.json
 ```
 
-Local project identity lives in the app repo:
+ServiceMaps and service-run contracts are saved in the bound Tapi server
+project. Runtime SDK calls read the service catalog from that project.
 
-```text
-.tapi/project.json
-.tapi/generated/catalog.json
-src/tapi.generated.ts
+```bash
+TAPI_API_KEY=tapi_project_key tapi tapp create brokerage --name "Brokerage"
+TAPI_API_KEY=tapi_project_key tapi tapp service add brokerage schwab.place_order \
+  --service-map sm_123 \
+  --entry place_order
 ```
 
-Sitemaps and API contracts are saved in the bound Tapi server project. Run
-`tapi publish` to mark ready server-side requests as published and activate 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
-```
+Create a queue, attach it to the Tapp, and point one or more runner slots at
+that queue:
+
+```bash
+tapi queue create "John" --project brokerage
+tapi tapp queue add brokerage queue_abc123
+
+tapi runner slot set john-laptop 1 queue_abc123 \
+  --project brokerage
+```
+
+For users setting up a local runner, `tapi runner setup` opens a localhost setup
+page that can create or accept a queue id, attach that queue to the Tapp, and
+assign one or more slots on the runner:
+
+```bash
+TAPI_API_KEY=tapi_project_key tapi runner setup \
+  --runner-id john-laptop \
+  --project brokerage
+```
 
 ## 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`.
+Create one TAPI client in server-side app code. Use a developer API key, the
+Tapp id that owns the service call, and optionally 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!,
-});
-```
+export const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  tappId: process.env.TAPI_TAPP_ID!,
+  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,
-});
+const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  tappId: process.env.TAPI_TAPP_ID!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+  dev: false,
+});
 ```
 
 During development, set `dev: true`. If a website reaches an unknown state,
@@ -113,41 +142,46 @@ 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,
-});
+const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  tappId: process.env.TAPI_TAPP_ID!,
+  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>
-```
-
-`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>
+tapi sessions --json
+tapi sessions open <session-id>
 ```
 
-```ts
-const operation = await tapi.websiteApis.describe("schwab.place_order");
+`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.
 
-const run = await tapi.websiteApis.run("schwab.place_order", {
-  inputs: {
-    symbol: "AAPL",
-    side: "buy",
+Service runs are authored visually in Tapi Studio by setting ServiceMap bounds
+and selecting inputs/outputs. The SDK sees the public service-run name:
+
+```text
+<namespace>.<operation>
+```
+
+A service run is routed through a queue. The queue id is the only routing handle:
+the Tapp must attach the queue, and one or more runner slots must be configured
+with the same queue id.
+
+```ts
+const operation = await tapi.services.describe("schwab.place_order");
+
+const run = await tapi.services.run("schwab.place_order", {
+  queueId: "queue_abc123",
+  inputs: {
+    symbol: "AAPL",
+    side: "buy",
     quantity: 10,
     orderType: "limit",
     limitPrice: 190,
@@ -160,13 +194,13 @@ console.log(completedRun.status, completedRun.result);
 
 ## Late Inputs
 
-Most API inputs are known before the run starts. Use `lateInput()` when the
+Most service 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
+state 4 runs. Declare the input up front with the service run, then resolve it
 from your own code:
 
 ```ts
@@ -179,7 +213,7 @@ const verificationCode = lateInput<string>({
   timeoutMs: 180_000,
 });
 
-const run = await tapi.websiteApis.run("walmart.login", {
+const run = await tapi.services.run("walmart.login", {
   inputs: {
     email: "buyer@example.com",
     password: process.env.WALMART_PASSWORD!,
@@ -198,7 +232,7 @@ worker, webhook, or polling loop finds the value:
 ```ts
 const verificationCode = lateInput<string>({ timeoutMs: 180_000 });
 
-const run = await tapi.websiteApis.run("walmart.login", {
+const run = await tapi.services.run("walmart.login", {
   inputs: { email: "buyer@example.com", verificationCode },
 });
 
@@ -214,19 +248,19 @@ 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.
+the website itself should stay as normal service outputs.
 
-## API-Call Triggers
+## Service Triggers
 
-Triggers are scheduled calls to published website APIs. Keep trigger definitions
-in the app repo and sync them after publishing the API catalog:
+Triggers are scheduled service runs. Keep trigger definitions in the app repo
+and sync them with the service catalog from that repo:
 
 ```ts
 // tapi.config.ts
 export default {
   triggers: {
     nightlyBalance: {
-      apiRequest: "schwab.get_balance",
+      serviceRun: "schwab.get_balance",
       schedule: { cron: "0 9 * * MON-FRI" },
       inputs: { accountId: "main" },
       runtime: { profileRef: "perm_default" },
@@ -248,7 +282,7 @@ You can also manage triggers directly:
 ```ts
 await tapi.triggers.create({
   name: "nightlyBalance",
-  apiRequest: "schwab.get_balance",
+  serviceRun: "schwab.get_balance",
   schedule: { cron: "0 9 * * MON-FRI" },
   inputs: { accountId: "main" },
   runtime: { profileRef: "perm_default" },
@@ -261,7 +295,7 @@ await tapi.triggers.disable("act_123");
 You can inspect the same input/output contract from the CLI:
 
 ```bash
-tapi apis describe schwab.place_order \
+tapi services describe schwab.place_order \
   --api-base-url "$TAPI_BASE_URL" \
   --api-key "$TAPI_API_KEY" \
   --project "$TAPI_PROJECT_ID"
@@ -273,7 +307,7 @@ own backend route, server action, or job worker when using secret API keys.
 ## Runtime Profiles and Proxies
 
 Browser identity is selected with a runner-local `profileRef`, not by passing
-Chrome folder paths through the cloud API.
+Chrome folder paths through the cloud service-run request.
 
 Use `PermProfile` for a long-lived account identity. It owns a persistent
 Chrome user-data directory and should usually use the runner's normal home IP:
@@ -284,13 +318,14 @@ const perm = await tapi.runtime.permProfiles.create({
   originPolicy: { type: "home" },
 });
 
-await tapi.runtime.permProfiles.launchSetup(perm.profile.profileRef);
-// The user logs in, adds passkeys, then closes setup Chrome.
-
-await tapi.websiteApis.run("walmart.reorder", {
-  inputs: { item: "paper towels" },
-  runtime: { profileRef: perm.profile.profileRef },
-});
+await tapi.runtime.permProfiles.launchSetup(perm.profile.profileRef);
+// The user logs in, adds passkeys, then closes setup Chrome.
+
+await tapi.services.run("walmart.reorder", {
+  queueId: "queue_abc123",
+  inputs: { item: "paper towels" },
+  runtime: { profileRef: perm.profile.profileRef },
+});
 ```
 
 Use `TempProfile` for throwaway work. Temp profiles can be cloned from a
@@ -310,8 +345,9 @@ const temp = await tapi.runtime.tempProfiles.provisionMany({
 
 await Promise.all(
   temp.profiles.map((profile) =>
-    tapi.websiteApis.run("walmart.lookupItem", {
-      inputs: { sku: "123" },
+    tapi.services.run("walmart.lookupItem", {
+      queueId: "queue_abc123",
+      inputs: { sku: "123" },
       runtime: {
         profileRef: profile.profileRef,
         destroyOnRelease: profile.destroyOnRelease,
@@ -321,7 +357,7 @@ await Promise.all(
 );
 ```
 
-`runtime.profileRef` is the only value sent to the TAPI cloud run API. Proxy
+`runtime.profileRef` is the only value sent to the TAPI cloud run request. Proxy
 URLs, proxy credentials, and Chrome profile folders stay on the local runner
 and are handled through the local control WebSocket at `ws://127.0.0.1:8765`.
 When the same `PermProfile` is used concurrently for multiple different sites,
@@ -332,24 +368,27 @@ the base `profileRef` and let the runner decide.
 If your JavaScript runtime does not provide `WebSocket`, pass one:
 
 ```ts
-const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  webSocket: MyWebSocketImplementation,
-});
-```
+const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  tappId: process.env.TAPI_TAPP_ID!,
+  webSocket: MyWebSocketImplementation,
+});
+```
 
 ## 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.
+TAPI_BASE_URL=https://your-tapi-api-host
+TAPI_API_KEY=tapi_project_key
+TAPI_TAPP_ID=brokerage
+TAPI_PROJECT_ID=brokerage
+```
+
+`tappId` is required. Service calls are made for that Tapp, and the developer
+who owns the Tapp pays for the service delivery. `projectId` is optional when
+the API key is already project-scoped. If provided, the SDK sends it as the
+`X-Tapi-Project` header and the server rejects mismatches.
 
 ## Common Project Setup
 
@@ -365,11 +404,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!,
+  tappId: process.env.TAPI_TAPP_ID!,
+  projectId: process.env.TAPI_PROJECT_ID!,
+});
 ```
 
 Application code should import this shared client instead of constructing a new client in every file.
@@ -384,15 +424,15 @@ await tapi.runtime.profiles.list();
 await tapi.runtime.profiles.clone({ profileRef: "perm_default", site: "walmart" });
 await tapi.runtime.permProfiles.create({ displayName: "Default", originPolicy: { type: "home" } });
 await tapi.runtime.tempProfiles.provisionMany({ proxies: ["http://user:pass@host:8080"] });
-await tapi.websiteApis.describe("schwab.place_order");
+await tapi.services.describe("schwab.place_order");
 
-const run = await tapi.websiteApis.run("apiName.requestKey", {
-  inputs: { example: true },
-  runtime: { profileRef: "perm_default" },
-  priority: 5,
-  runnerId: "runner-id",
-  idempotencyKey: "request-123",
-});
+const run = await tapi.services.run("serviceName.serviceKey", {
+  queueId: "queue_abc123",
+  inputs: { example: true },
+  runtime: { profileRef: "perm_default" },
+  priority: 5,
+  idempotencyKey: "request-123",
+});
 
 await tapi.runs.get(run.id);
 await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
@@ -423,7 +463,7 @@ The minimum developer flow is:
 
 ```ts
 // backend route or server action
-const quote = await tapi.websiteApis.quoteCloud("schwab.place_order", {
+const quote = await tapi.services.quoteCloud("schwab.place_order", {
   inputs: [
     { symbol: "AAPL", quantity: 1 },
     { symbol: "MSFT", quantity: 2 },
@@ -444,7 +484,7 @@ if (!quote.withinMaxCost) {
   throw new Error("Cloud batch exceeds the configured cost cap");
 }
 
-const run = await tapi.websiteApis.runCloudBatch("schwab.place_order", {
+const run = await tapi.services.runCloudBatch("schwab.place_order", {
   inputs: [
     { symbol: "AAPL", quantity: 1 },
     { symbol: "MSFT", quantity: 2 },
@@ -483,10 +523,10 @@ low, `runCloudBatch` converts the server's HTTP `402` into a normal
 `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.
+Credits are scoped under the Tapi API key owner, Tapp 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:
 
@@ -513,9 +553,9 @@ 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.
+Service runs are addressed as `<serviceName>.<serviceKey>`. The service name
+comes from the ServiceMap name in Studio. The service key is the name the
+developer types into the SDK name textbox at the service boundary.
 
 `describe()` returns the public SDK contract: input controls such as
 `textbox`, `radio`, `select`, `checkbox`, conditional requirements such as
@@ -550,10 +590,10 @@ import type {
   RuntimeProfile,
   RuntimeRunOptions,
   SdkCatalog,
+  ServiceOperation,
+  ServiceRunRequest,
   TapiRun,
   TapiRunner,
-  WebsiteApiOperation,
-  WebsiteApiRunRequest,
 } from "@tapi-dev/sdk";
 ```
 

package/dist/catalog.js

@@ -1,9 +1,10 @@
+import { normalizeSdkCatalog } from "./service-contract.js";
 export class CatalogResource {
     http;
     constructor(http) {
         this.http = http;
     }
-    get() {
-        return this.http.get("/api/sdk/v1/catalog");
+    async get() {
+        return normalizeSdkCatalog(await this.http.get("/api/sdk/v1/catalog"));
     }
 }

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import type { TapiDevSession } from "./types.js";
 import { type TapiWorkspace } from "./workspace.js";
+export declare const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 120000;
 export type StudioChannel = "pilot" | "stable" | "nightly";
 export interface StudioReleaseManifest {
     product?: string;
@@ -68,6 +69,32 @@ export interface StudioCliOptions {
     workspaceMode: boolean;
     launchUrlQuery?: string;
 }
+export interface RunnerSetupCliOptions {
+    apiBaseUrl: string;
+    apiKey: string;
+    projectId: string;
+    runnerId: string;
+    port: number;
+    openBrowser: boolean;
+}
+export interface RunnerSetupAction {
+    queueId?: string;
+    displayName?: string;
+    maxSlots?: number;
+    slotStart?: number;
+    slotCount?: number;
+}
+export interface RunnerSetupActionResult {
+    queueId: string;
+    queue: Record<string, unknown>;
+    attachment: Record<string, unknown>;
+    slots: Record<string, unknown>[];
+}
+export interface RunnerSetupServerHandle {
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+}
 export interface ServiceStatus {
     installed: boolean;
     name?: string;
@@ -80,6 +107,9 @@ type StudioPortAvailable = (port: number) => Promise<boolean>;
 type StudioPortReaper = (preferred: number, count: number) => Promise<number>;
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
+export declare function parseRunnerSetupOptions(args: string[]): RunnerSetupCliOptions;
+export declare function startRunnerSetupServer(options: RunnerSetupCliOptions, fetchImpl?: FetchLike): Promise<RunnerSetupServerHandle>;
+export declare function executeRunnerSetupAction(options: RunnerSetupCliOptions, action: RunnerSetupAction, fetchImpl?: FetchLike): Promise<RunnerSetupActionResult>;
 export declare function trySelectDevSessionInOpenStudio(session: TapiDevSession, options: StudioCliOptions, fetchImpl?: FetchLike): Promise<{
     selected: boolean;
     baseUrl?: string;