@tapi-dev/sdk 0.1.4 → 0.1.6

package/README.md

@@ -20,36 +20,46 @@ npx tapi studio install --channel pilot
 npx tapi studio open
 ```
 
+`studio install` opens a browser sign-in before any Studio EXE download. The
+CLI exchanges the browser credential for Firebase auth, requests a short-lived
+Studio install token from the Tapi API, then fetches a protected manifest and
+installer download URL. If the signed-in user is not yet approved, the server
+submits an approval request and sends the existing email approval links to the
+admin. After approval, rerun the same command.
+
 You can also run the CLI directly from npm without adding the package first:
 
 ```bash
 npx @tapi-dev/sdk studio install --channel pilot
 ```
 
-The CLI reads the release manifest from:
+The install flow talks to the Tapi API host first:
 
 ```text
-https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+POST /api/sdk/v1/studio/install-token
+GET  /api/sdk/v1/studio/releases/<channel>
 ```
 
-It downloads the Windows installer, verifies the manifest SHA256, caches the installer locally, and runs it. The installer cache defaults to:
+It then downloads the Windows installer, verifies the manifest SHA256, caches
+the installer locally, and runs it. The installer cache defaults to:
 
 ```text
-%LOCALAPPDATA%\Tapi\Studio\downloads
-```
-
-Tapi Studio includes the matching Tapi Service build. When the installer runs,
-it installs or replaces the local `tapi-service` Windows service with the
-version declared in the Studio manifest. Developers do not pick a service
-version separately; updating Studio updates the service version used by that
-project and by apps generated from that project.
+%LOCALAPPDATA%\Tapi\Studio\downloads
+```
+
+Tapi Studio includes the matching Tapi Service build. When the installer runs,
+it installs or replaces the local `tapi-service` Windows service with the
+version declared in the Studio manifest. Developers do not pick a service
+version separately; updating Studio updates the service version used by that
+project and by apps generated from that project.
 
 Useful commands:
 
 ```bash
 npx tapi studio install --channel pilot
 npx tapi studio install --channel pilot --download-only
-npx tapi studio install --manifest https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+npx tapi studio install --api-base-url https://api.example.com
+npx tapi studio install --install-token tsi_your_preissued_token
 npx tapi studio open
 npx tapi studio doctor
 ```
@@ -57,13 +67,42 @@ npx tapi studio doctor
 Environment overrides:
 
 ```env
+TAPI_BASE_URL=https://your-tapi-api-host
+TAPI_STUDIO_API_BASE_URL=https://your-tapi-api-host
 TAPI_STUDIO_CHANNEL=pilot
 TAPI_STUDIO_MANIFEST_URL=https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
-TAPI_DOWNLOADS_BASE_URL=https://d4xaf52nfwiok.cloudfront.net
+TAPI_STUDIO_INSTALL_TOKEN=tsi_your_preissued_token
+TAPI_STUDIO_AUTH_HTML_URL=https://rsarlong-1f92fd.gitlab.io/auth.html
+TAPI_FIREBASE_API_KEY=AIzaSyCDZR8lWyVQcWYfFdNZa4vuL4IWEC0h6gE
 TAPI_STUDIO_EXE=C:\Users\you\AppData\Local\Tapi Studio\Tapi Studio.exe
 ```
 
-Tapi Studio desktop releases are currently published for Windows x64.
+`TAPI_STUDIO_MANIFEST_URL` remains useful for `studio doctor`. Direct manifest
+overrides are not used by the protected installer path.
+
+Server-side protected install delivery also requires:
+
+```env
+STUDIO_INSTALL_TOKEN_SECRET=replace-me
+S3_BUCKET=your-private-release-bucket
+AWS_REGION=us-east-1
+```
+
+If the Studio installer objects remain publicly downloadable, users can bypass
+the approval gate by skipping the CLI entirely.
+
+Tapi Studio desktop releases are currently published for Windows x64.
+
+Cloud Windows workers use a separate protected service runtime manifest:
+
+```text
+GET /api/sdk/v1/service/releases/<channel>
+```
+
+The request must include either `Authorization: Bearer
+$CLOUD_WORKER_BOOTSTRAP_SECRET` or `X-Tapi-Worker-Bootstrap-Secret`. The server
+reads `service/channels/<channel>/latest.json` from the private S3 bucket and
+returns a short-lived signed download URL for the Tapi Service zip.
 
 ## Quick Start
 
@@ -94,8 +133,111 @@ const completedRun = await tapi.runs.wait(run.id);
 console.log(completedRun.status, completedRun.result);
 ```
 
+Generated website APIs are created in Tapi Studio by setting workflow bounds,
+choosing the SDK operation name, selecting inputs/outputs, and publishing the
+operation. Studio owns the private workflow bindings. The SDK sees the public
+shape as:
+
+```text
+<autogenerated website namespace>.<developer operation name>
+```
+
+For example, if Studio shows `SDK name: schwab.[ place_order ]`, call:
+
+```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,
+  },
+});
+```
+
+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" \
+  --app "$TAPI_APP_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
+
+Browser identity is selected with a runner-local `profileRef`, not by passing
+Chrome folder paths through the cloud API.
+
+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:
+
+```ts
+const perm = await tapi.runtime.permProfiles.create({
+  displayName: "Mom Walmart",
+  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 },
+});
+```
+
+Use `TempProfile` for throwaway work. Temp profiles can be cloned from a
+template profile and assigned different proxies:
+
+```ts
+const temp = await tapi.runtime.tempProfiles.provisionMany({
+  count: 3,
+  displayNamePrefix: "checkout",
+  proxies: [
+    "http://user1:pass1@proxy-a.example:8080",
+    "http://user2:pass2@proxy-b.example:8080",
+    "http://user3:pass3@proxy-c.example:8080",
+  ],
+  destroyOnRelease: true,
+});
+
+await Promise.all(
+  temp.profiles.map((profile) =>
+    tapi.websiteApis.run("walmart.lookupItem", {
+      inputs: { sku: "123" },
+      runtime: {
+        profileRef: profile.profileRef,
+        destroyOnRelease: profile.destroyOnRelease,
+      },
+    }),
+  ),
+);
+```
+
+`runtime.profileRef` is the only value sent to the TAPI cloud run API. 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,
+the runner creates runtime clones so Chrome does not open the same
+`--user-data-dir` twice. You can also create a clone explicitly with
+`tapi.runtime.profiles.clone({ profileRef, site })`, but most apps should pass
+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,
+});
+```
+
 ## Configuration
 
 ```env
@@ -135,20 +277,146 @@ Application code should import this shared client instead of constructing a new
 await tapi.catalog.get();
 await tapi.runners.list();
 await tapi.runtime.requirements();
+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");
 
 const run = await tapi.websiteApis.run("apiName.requestKey", {
   inputs: { example: true },
+  runtime: { profileRef: "perm_default" },
   priority: 5,
   runnerId: "runner-id",
   idempotencyKey: "request-123",
 });
 
 await tapi.runs.get(run.id);
-await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
-await tapi.runs.cancel(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.
 
-Website API requests are addressed as `<apiName>.<requestKey>`.
+`describe()` returns the public SDK contract: input controls such as
+`textbox`, `radio`, `select`, `checkbox`, conditional requirements such as
+`requiredWhen`, and the output schema. It does not expose workflow ids, state
+ids, action ids, selectors, runner ids, or other Studio internals.
 
 ## Errors
 
@@ -174,9 +442,12 @@ The package includes generated TypeScript declarations. Common exported types in
 ```ts
 import type {
   RuntimeRequirements,
+  RuntimeProfile,
+  RuntimeRunOptions,
   SdkCatalog,
   TapiRun,
   TapiRunner,
+  WebsiteApiOperation,
   WebsiteApiRunRequest,
 } from "@tapi-dev/sdk";
 ```

package/dist/cli.d.ts

@@ -24,11 +24,14 @@ export interface StudioReleaseManifest {
 }
 interface StudioCliOptions {
     channel: StudioChannel;
+    apiBaseUrl: string;
     manifestUrl: string;
+    manifestUrlOverride?: string;
     cacheDir: string;
     downloadOnly: boolean;
     silent: boolean;
     exePath?: string;
+    installToken?: string;
 }
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;