@tapi-dev/sdk 0.1.7 → 0.1.9

package/README.md

@@ -10,164 +10,108 @@ 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.
 
-## Install Tapi Studio
-
-Tapi Studio is the desktop app used to author and test local Tapi integrations. Install the SDK first, then use the bundled CLI:
-
-```bash
-npm install @tapi-dev/sdk
-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 install flow talks to the Tapi API host first:
-
-```text
-POST /api/sdk/v1/studio/install-token
-GET  /api/sdk/v1/studio/releases/<channel>
-```
-
-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.
-
-Useful commands:
-
-```bash
-npx tapi studio install --channel pilot
-npx tapi studio install --channel pilot --download-only
-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
-```
-
-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_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_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:
+## Developer Flow
 
-```env
-STUDIO_INSTALL_TOKEN_SECRET=replace-me
-S3_BUCKET=your-private-release-bucket
-AWS_REGION=us-east-1
+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
 ```
 
-If the Studio installer objects remain publicly downloadable, users can bypass
-the approval gate by skipping the CLI entirely.
+`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.
+
+Useful commands:
 
-Tapi Studio desktop releases are currently published for Windows x64.
+```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
+```
 
-Cloud Windows workers use a separate protected service runtime manifest:
+Local authoring files live in the app repo:
 
 ```text
-GET /api/sdk/v1/service/releases/<channel>
+.tapi/project.json
+.tapi/sitemaps/<site>.json
+.tapi/apis/<site>/<api>.json
+.tapi/generated/catalog.json
+src/tapi.generated.ts
 ```
 
-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
-
-Create one TAPI client in your app's server-side code:
-
-```ts
-import { TapiClient } from "@tapi-dev/sdk";
-
-export const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  appId: process.env.TAPI_APP_ID,
-});
-```
-
-Then call a TAPI website API:
-
-```ts
-const run = await tapi.websiteApis.run("brokerage.submitTrade", {
-  inputs: {
-    symbol: "AAPL",
-    quantity: 1,
-    side: "buy",
-  },
-});
-
-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.
+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
+```
+
+## 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!,
+});
+```
+
+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);
+```
+
+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.
 
 ## Runtime Profiles and Proxies
 
@@ -238,15 +182,17 @@ const tapi = new TapiClient({
 });
 ```
 
-## Configuration
-
-```env
-TAPI_BASE_URL=https://your-tapi-api-host
-TAPI_API_KEY=tapi_your_api_key
-TAPI_APP_ID=your-app-id
-```
-
-`appId` is optional. If provided, the SDK sends it as the `X-Tapi-App` header.
+## 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
 
@@ -262,12 +208,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!,
-  appId: process.env.TAPI_APP_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.
 

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type TapiWorkspace } from "./workspace.js";
 export type StudioChannel = "pilot" | "stable" | "nightly";
 export interface StudioReleaseManifest {
     product?: string;
@@ -15,6 +16,7 @@ export interface StudioReleaseManifest {
     commitShort?: string;
     ref?: string;
     installerKind?: string;
+    serverExecutable?: string;
     bundledService?: {
         product?: string;
         version?: string;
@@ -26,6 +28,26 @@ export interface StudioReleaseManifest {
         };
     };
 }
+export interface ServiceReleaseManifest {
+    product?: string;
+    version: string;
+    channel: string;
+    platform: string;
+    artifactName: string;
+    url: string;
+    sha256: string;
+    sizeBytes?: number;
+    serviceHostExecutable?: string;
+    workerExecutable?: string;
+    installer?: string;
+    uninstaller?: string;
+    builtAt?: string;
+    commit?: string;
+    commitShort?: string;
+    ref?: string;
+    mobileChrome?: Record<string, unknown>;
+    contents?: string[];
+}
 interface StudioCliOptions {
     channel: StudioChannel;
     apiBaseUrl: string;
@@ -36,10 +58,16 @@ interface StudioCliOptions {
     silent: boolean;
     exePath?: string;
     installToken?: string;
+    workspace?: TapiWorkspace;
+    workspaceRoot?: string;
+    projectId?: string;
+    projectSlug?: string;
+    workspaceMode: boolean;
 }
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
 export declare function getDefaultStudioCacheDir(): string;
+export declare function getDefaultServiceCacheDir(): string;
 export declare class CliWideEvent {
     private readonly filePath;
     private readonly startedAt;
@@ -55,5 +83,6 @@ export declare function createCliWideEvent(eventName: string, initialFields?: Re
 export declare function getCliWideEventRoot(): string;
 export declare function getStudioExecutableCandidates(): string[];
 export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
+export declare function validateServiceReleaseManifest(input: unknown): ServiceReleaseManifest;
 export declare function compareVersions(left: string, right: string): number;
 export {};