@prisma/compute-sdk 0.1.0

package/README.md

@@ -0,0 +1,638 @@
+# @prisma/compute-sdk
+
+TypeScript SDK for deploying and managing applications on [Prisma Compute](https://www.prisma.io/blog/prisma-compute).
+
+## Installation
+
+```bash
+npm install @prisma/compute-sdk @prisma/management-api-sdk
+```
+
+`@prisma/management-api-sdk` is a peer dependency that provides the authenticated API client.
+
+## Prerequisites
+
+You need an authenticated `ManagementApiClient` from `@prisma/management-api-sdk`. There are two ways to create one:
+
+### Using a service token
+
+```ts
+import { createManagementApiClient } from "@prisma/management-api-sdk";
+
+const apiClient = createManagementApiClient({
+  token: process.env.PRISMA_API_TOKEN,
+});
+```
+
+### Using OAuth
+
+```ts
+import { createManagementApiSdk } from "@prisma/management-api-sdk";
+
+const sdk = createManagementApiSdk({
+  clientId: "your-client-id",
+  redirectUri: "http://localhost:3000/callback",
+  tokenStorage: yourTokenStorageImpl, // implements TokenStorage interface
+});
+
+// sdk.client is a ManagementApiClient with automatic token refresh
+const apiClient = sdk.client;
+```
+
+See the [`@prisma/management-api-sdk` documentation](https://www.npmjs.com/package/@prisma/management-api-sdk) for full details on authentication setup.
+
+## Quick start
+
+```ts
+import { ComputeClient, PreBuilt, Ok } from "@prisma/compute-sdk";
+import { createManagementApiClient } from "@prisma/management-api-sdk";
+
+const apiClient = createManagementApiClient({
+  token: process.env.PRISMA_API_TOKEN,
+});
+
+const compute = new ComputeClient(apiClient);
+
+// Deploy a pre-built application
+const result = await compute.deploy({
+  strategy: new PreBuilt({
+    appPath: "./dist",
+    entrypoint: "index.js",
+  }),
+  projectId: "your-project-id",
+  serviceName: "my-app",
+  region: "us-east-1",
+});
+
+if (result.isOk()) {
+  console.log(`Deployed to ${result.value.deploymentUrl}`);
+} else {
+  console.error(`Deploy failed: ${result.error.message}`);
+}
+```
+
+## API reference
+
+### `ComputeClient`
+
+The main entry point for all operations. Created from a `ManagementApiClient`:
+
+```ts
+import { ComputeClient } from "@prisma/compute-sdk";
+
+const compute = new ComputeClient(apiClient);
+```
+
+All methods return `Promise<Result<T, ComputeError>>` — a discriminated union that is either `Ok` with a value or `Err` with a typed error. See [Error handling](#error-handling) for details.
+
+---
+
+#### `deploy(options): Promise<Result<DeployResult, ComputeError>>`
+
+Builds, uploads, and deploys an application version.
+
+```ts
+const result = await compute.deploy({
+  // Required: how to produce the deployable artifact
+  strategy: new PreBuilt({ appPath: "./dist", entrypoint: "index.js" }),
+
+  // Target (provide serviceId OR projectId + serviceName + region)
+  projectId: "proj_abc",
+  serviceName: "my-app",
+  region: "us-east-1",
+  // OR:
+  serviceId: "svc_xyz",
+
+  // Optional
+  envVars: { DATABASE_URL: "postgresql://..." },
+  portMapping: { http: 3000 },
+  timeoutSeconds: 120,       // max time to wait for "running" status
+  pollIntervalMs: 1000,      // how often to check status
+  signal: abortController.signal,
+  progress: { /* DeployProgress callbacks */ },
+  interaction: { /* DeployInteraction callbacks */ },
+});
+
+if (result.isOk()) {
+  const { deploymentUrl, versionId, serviceId, resolvedConfig } = result.value;
+}
+```
+
+**Returns** `DeployResult`:
+
+| Field            | Type             | Description                              |
+| ---------------- | ---------------- | ---------------------------------------- |
+| `projectId`      | `string`         | Project ID                               |
+| `serviceId`      | `string`         | Service ID                               |
+| `serviceName`    | `string`         | Service display name                     |
+| `region`         | `string`         | Region identifier                        |
+| `versionId`      | `string`         | Created version ID                       |
+| `deploymentUrl`  | `string`         | Live URL of the deployment               |
+| `resolvedConfig` | `ResolvedConfig` | Final resolved configuration             |
+
+---
+
+#### `updateEnv(options): Promise<Result<UpdateEnvResult, ComputeError>>`
+
+Creates a new version with updated environment variables and/or port mapping, reusing the code from the most recent deployment.
+
+```ts
+const result = await compute.updateEnv({
+  serviceId: "svc_xyz",
+  envVars: { DATABASE_URL: "postgresql://new-url..." },
+  portMapping: { http: 8080 },
+});
+```
+
+The service must have at least one existing version. If not, this returns a `NoExistingVersionError`.
+
+---
+
+#### `destroyVersion(options): Promise<Result<DestroyVersionResult, ComputeError>>`
+
+Stops (if running) and deletes a single version.
+
+```ts
+const result = await compute.destroyVersion({
+  versionId: "ver_abc",
+  // OR provide serviceId + interaction.selectVersion for interactive selection
+});
+```
+
+**Returns** `DestroyVersionResult`:
+
+| Field            | Type      | Description                              |
+| ---------------- | --------- | ---------------------------------------- |
+| `versionId`      | `string`  | The destroyed version ID                 |
+| `previousStatus` | `string`  | Status before destruction                |
+| `stopped`        | `boolean` | Whether a stop was required              |
+| `deleted`        | `boolean` | Whether deletion succeeded               |
+
+---
+
+#### `destroyService(options): Promise<Result<DestroyServiceResult, ComputeError>>`
+
+Stops all running versions, deletes all versions, and optionally deletes the service itself.
+
+```ts
+const result = await compute.destroyService({
+  serviceId: "svc_xyz",
+  keepService: false, // set to true to keep the service record
+});
+```
+
+If some versions fail to stop or delete, returns a `DestroyAggregateError` with details on which succeeded and which failed.
+
+---
+
+#### `listProjects(options?): Promise<Result<ProjectInfo[], ComputeError>>`
+
+```ts
+const result = await compute.listProjects();
+if (result.isOk()) {
+  for (const project of result.value) {
+    console.log(`${project.name} (${project.id})`);
+  }
+}
+```
+
+---
+
+#### `listServices(options): Promise<Result<ServiceInfo[], ComputeError>>`
+
+```ts
+const result = await compute.listServices({ projectId: "proj_abc" });
+```
+
+---
+
+#### `createService(options): Promise<Result<ServiceInfo, ComputeError>>`
+
+```ts
+const result = await compute.createService({
+  projectId: "proj_abc",
+  serviceName: "my-new-service",
+  region: "eu-west-3",
+});
+```
+
+---
+
+#### `showService(options): Promise<Result<ServiceDetail, ComputeError>>`
+
+```ts
+const result = await compute.showService({ serviceId: "svc_xyz" });
+if (result.isOk()) {
+  console.log(`Latest version: ${result.value.latestVersionId}`);
+}
+```
+
+---
+
+#### `deleteService(options): Promise<Result<void, ComputeError>>`
+
+Deletes a service record. The service should have no versions (use `destroyService` to clean up versions first).
+
+```ts
+await compute.deleteService({ serviceId: "svc_xyz" });
+```
+
+---
+
+#### `listVersions(options): Promise<Result<VersionInfo[], ComputeError>>`
+
+```ts
+const result = await compute.listVersions({ serviceId: "svc_xyz" });
+```
+
+---
+
+#### `showVersion(options): Promise<Result<VersionDetail, ComputeError>>`
+
+```ts
+const result = await compute.showVersion({ versionId: "ver_abc" });
+if (result.isOk()) {
+  console.log(`Status: ${result.value.status}`);
+  console.log(`URL: https://${result.value.previewDomain}`);
+}
+```
+
+---
+
+#### `startVersion(options): Promise<Result<void, ComputeError>>`
+
+```ts
+await compute.startVersion({ versionId: "ver_abc" });
+```
+
+---
+
+#### `stopVersion(options): Promise<Result<void, ComputeError>>`
+
+```ts
+await compute.stopVersion({ versionId: "ver_abc" });
+```
+
+---
+
+#### `deleteVersion(options): Promise<Result<void, ComputeError>>`
+
+```ts
+await compute.deleteVersion({ versionId: "ver_abc" });
+```
+
+## Build strategies
+
+A build strategy produces a deployable artifact (a directory with an entrypoint file). The SDK ships with two built-in strategies:
+
+### `PreBuilt`
+
+Use when your application is already built (e.g., output of `tsc`, `esbuild`, or any other bundler):
+
+```ts
+import { PreBuilt } from "@prisma/compute-sdk";
+
+const strategy = new PreBuilt({
+  appPath: "./dist",        // absolute or relative path to the build output
+  entrypoint: "index.js",   // relative to appPath
+});
+```
+
+`PreBuilt` validates that the entrypoint exists and is a relative path that doesn't escape the application directory. It performs no copying or transformation.
+
+### `BunBuild`
+
+Use when you want the SDK to bundle your application using [Bun](https://bun.sh):
+
+```ts
+import { BunBuild } from "@prisma/compute-sdk";
+
+const strategy = new BunBuild({
+  appPath: "./my-app",          // path to your application source
+  entrypoint: "src/index.ts",   // optional: resolved from package.json "main" if omitted
+});
+```
+
+`BunBuild` runs `bun build` with `--target bun --sourcemap=external`, manages a temporary output directory, and cleans it up after the archive is created. Requires Bun to be installed on the machine.
+
+### Custom strategies
+
+Implement the `BuildStrategy` interface to use any build tool:
+
+```ts
+import type { BuildStrategy, BuildArtifact } from "@prisma/compute-sdk";
+
+class MyCustomBuild implements BuildStrategy {
+  async execute(): Promise<BuildArtifact> {
+    // Run your build process...
+    return {
+      directory: "/path/to/output",   // absolute path to the built files
+      entrypoint: "index.js",         // relative to directory, posix separators
+      cleanup: async () => {          // optional: called after archiving
+        // clean up temp files
+      },
+    };
+  }
+}
+```
+
+## Error handling
+
+All `ComputeClient` methods return `Result<T, E>` from the [`better-result`](https://www.npmjs.com/package/better-result) library instead of throwing exceptions. This gives you exhaustive, type-safe error handling.
+
+### Checking results
+
+```ts
+const result = await compute.deploy({ /* ... */ });
+
+// Pattern 1: isOk / isErr
+if (result.isOk()) {
+  console.log(result.value.deploymentUrl);
+} else {
+  console.error(result.error.message);
+}
+
+// Pattern 2: match
+result.match({
+  Ok: (value) => console.log(value.deploymentUrl),
+  Err: (error) => console.error(error.message),
+});
+```
+
+### Error types
+
+Every error extends `TaggedError` and has a `_tag` discriminant for pattern matching:
+
+| Error class              | `_tag`                    | Description                                                   |
+| ------------------------ | ------------------------- | ------------------------------------------------------------- |
+| `AuthenticationError`    | `"AuthenticationError"`   | API returned HTTP 401                                         |
+| `ApiError`               | `"ApiError"`              | API returned a non-401 error                                  |
+| `MissingArgumentError`   | `"MissingArgumentError"`  | A required argument was not provided                          |
+| `BuildError`             | `"BuildError"`            | Build strategy failed                                         |
+| `ArtifactError`          | `"ArtifactError"`         | Archive creation or upload failed                             |
+| `TimeoutError`           | `"TimeoutError"`          | Version didn't reach target status in time                    |
+| `VersionFailedError`     | `"VersionFailedError"`    | Version transitioned to `"failed"` status                     |
+| `NoExistingVersionError` | `"NoExistingVersionError"`| `updateEnv` called on a service with no prior deployments     |
+| `CancelledError`         | `"CancelledError"`        | Operation cancelled via `AbortSignal`                         |
+| `DestroyAggregateError`  | `"DestroyAggregateError"` | Some versions failed during `destroyService`                  |
+
+### Matching specific errors
+
+```ts
+import { matchError, ApiError, AuthenticationError } from "@prisma/compute-sdk";
+
+const result = await compute.deploy({ /* ... */ });
+
+if (result.isErr()) {
+  matchError(result.error, {
+    AuthenticationError: (e) => {
+      console.error("Not authenticated. Check your token.");
+    },
+    ApiError: (e) => {
+      console.error(`API error (${e.statusCode}): ${e.message}`);
+      if (e.hint) console.error(`Hint: ${e.hint}`);
+    },
+    BuildError: (e) => {
+      console.error(`Build failed: ${e.message}`);
+    },
+    TimeoutError: (e) => {
+      console.error(`Timed out after ${Math.round(e.elapsedMs / 1000)}s`);
+    },
+    _: (e) => {
+      console.error(`Unexpected error: ${e.message}`);
+    },
+  });
+}
+```
+
+### Error type unions
+
+The SDK exports narrowed error unions for each operation:
+
+- **`DeployError`** — errors from `deploy()`: `AuthenticationError | ApiError | MissingArgumentError | BuildError | ArtifactError | TimeoutError | VersionFailedError | CancelledError`
+- **`UpdateEnvError`** — errors from `updateEnv()`: `AuthenticationError | ApiError | MissingArgumentError | NoExistingVersionError | TimeoutError | VersionFailedError | CancelledError`
+- **`DestroyError`** — errors from `destroyVersion()` / `destroyService()`: `AuthenticationError | ApiError | MissingArgumentError | CancelledError | DestroyAggregateError`
+- **`ComputeError`** — union of all error types
+
+## Progress and interaction callbacks
+
+Long-running operations accept `progress` and `interaction` callbacks for UI integration.
+
+### Deploy progress
+
+```ts
+await compute.deploy({
+  strategy,
+  projectId: "proj_abc",
+  serviceName: "my-app",
+  region: "us-east-1",
+  progress: {
+    onBuildStart() {
+      console.log("Building...");
+    },
+    onBuildComplete(artifact) {
+      console.log(`Built to ${artifact.directory}`);
+    },
+    onArchiveCreating() {
+      console.log("Creating archive...");
+    },
+    onArchiveReady(sizeBytes) {
+      console.log(`Archive: ${(sizeBytes / 1024).toFixed(1)} KB`);
+    },
+    onVersionCreated(versionId) {
+      console.log(`Version: ${versionId}`);
+    },
+    onUploadStart() {
+      console.log("Uploading...");
+    },
+    onUploadComplete() {
+      console.log("Upload complete.");
+    },
+    onStartRequested() {
+      console.log("Starting...");
+    },
+    onStatusChange(status) {
+      console.log(`Status: ${status}`);
+    },
+    onRunning(deploymentUrl) {
+      console.log(`Live at ${deploymentUrl}`);
+    },
+  },
+});
+```
+
+### Deploy interaction
+
+When `projectId`, `serviceId`, or `region` are not provided, the SDK calls interaction callbacks to let the consumer resolve them (e.g., by prompting the user):
+
+```ts
+await compute.deploy({
+  strategy,
+  interaction: {
+    async selectProject(projects) {
+      // projects: ProjectInfo[] — return the chosen project ID
+      return projects[0].id;
+    },
+    async selectService(services) {
+      // services: ServiceInfo[] — return a service ID, or null to create a new one
+      return null;
+    },
+    async provideServiceName() {
+      // return a name for the new service
+      return "my-new-service";
+    },
+    async selectRegion(regions) {
+      // regions: RegionInfo[] — return the chosen region ID
+      return "us-east-1";
+    },
+  },
+});
+```
+
+### Destroy progress
+
+```ts
+await compute.destroyService({
+  serviceId: "svc_xyz",
+  progress: {
+    onStoppingVersions(versionIds) { /* ... */ },
+    onVersionStopped(versionId) { /* ... */ },
+    onAllVersionsStopped() { /* ... */ },
+    onDeletingVersions(versionIds) { /* ... */ },
+    onVersionDeleted(versionId) { /* ... */ },
+    onAllVersionsDeleted() { /* ... */ },
+    onServiceDeleted(serviceId) { /* ... */ },
+  },
+});
+```
+
+## Cancellation
+
+All operations support cancellation via the standard `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+// Cancel after 30 seconds
+setTimeout(() => controller.abort(), 30_000);
+
+const result = await compute.deploy({
+  strategy,
+  serviceId: "svc_xyz",
+  signal: controller.signal,
+});
+
+if (result.isErr() && result.error._tag === "CancelledError") {
+  console.log("Deployment was cancelled.");
+}
+```
+
+## Domain types
+
+```ts
+import type {
+  ProjectInfo,       // { id, name, defaultRegion? }
+  ServiceInfo,       // { id, name, region, projectId, createdAt? }
+  ServiceDetail,     // ServiceInfo & { latestVersionId? }
+  VersionInfo,       // { id, status, createdAt, previewDomain? }
+  VersionDetail,     // VersionInfo & { envVars? }
+  RegionInfo,        // { id, displayName }
+  ResolvedConfig,    // { projectId, serviceId, serviceName, region, portMapping? }
+  PortMapping,       // { http?: number | null }
+} from "@prisma/compute-sdk";
+```
+
+### Available regions
+
+```ts
+import { REGIONS, KNOWN_REGION_IDS } from "@prisma/compute-sdk";
+
+// KNOWN_REGION_IDS: readonly ["us-east-1", "us-west-1", "eu-west-3", "eu-central-1", "ap-northeast-1", "ap-southeast-1"]
+// REGIONS: RegionInfo[] — same IDs with displayName
+```
+
+## Full example
+
+```ts
+import { ComputeClient, PreBuilt, matchError } from "@prisma/compute-sdk";
+import { createManagementApiClient } from "@prisma/management-api-sdk";
+
+async function main() {
+  const apiClient = createManagementApiClient({
+    token: process.env.PRISMA_API_TOKEN!,
+  });
+
+  const compute = new ComputeClient(apiClient);
+
+  // Deploy
+  const deployResult = await compute.deploy({
+    strategy: new PreBuilt({
+      appPath: "./dist",
+      entrypoint: "server.js",
+    }),
+    projectId: process.env.PROJECT_ID!,
+    serviceName: "my-api",
+    region: "us-east-1",
+    envVars: {
+      DATABASE_URL: process.env.DATABASE_URL!,
+      NODE_ENV: "production",
+    },
+    portMapping: { http: 3000 },
+    progress: {
+      onBuildStart: () => console.log("Preparing artifact..."),
+      onUploadStart: () => console.log("Uploading..."),
+      onStartRequested: () => console.log("Starting..."),
+      onStatusChange: (s) => console.log(`  Status: ${s}`),
+      onRunning: (url) => console.log(`Deployed: ${url}`),
+    },
+  });
+
+  if (deployResult.isErr()) {
+    matchError(deployResult.error, {
+      AuthenticationError: () => {
+        console.error("Invalid token. Set PRISMA_API_TOKEN.");
+        process.exit(1);
+      },
+      BuildError: (e) => {
+        console.error(`Build failed: ${e.message}`);
+        process.exit(1);
+      },
+      TimeoutError: (e) => {
+        console.error(`Deploy timed out (${Math.round(e.elapsedMs / 1000)}s).`);
+        console.error(`Version ${e.versionId} may still be starting.`);
+        process.exit(1);
+      },
+      _: (e) => {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+      },
+    });
+    return;
+  }
+
+  const { serviceId, versionId, deploymentUrl } = deployResult.value;
+  console.log(`\nService: ${serviceId}`);
+  console.log(`Version: ${versionId}`);
+  console.log(`URL:     ${deploymentUrl}`);
+
+  // List versions
+  const versionsResult = await compute.listVersions({ serviceId });
+  if (versionsResult.isOk()) {
+    console.log(`\nVersions (${versionsResult.value.length}):`);
+    for (const v of versionsResult.value) {
+      console.log(`  ${v.id} — ${v.status} (${v.createdAt})`);
+    }
+  }
+}
+
+main();
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- `@prisma/management-api-sdk` >= 1.20.1
+
+## License
+
+Apache-2.0