@gitterm/sdk 0.0.1 → 0.0.4

package/README.md

@@ -12,33 +12,93 @@ bun add @gitterm/sdk
 npm install @gitterm/sdk
 ```
 
+## Switching servers (hosted vs self-hosted)
+
+The default API is the hosted service at `https://api.gitterm.dev`. Self-hosted
+instances use the same SDK — pass your instance’s base URL as `serverUrl`.
+
+| Deployment  | Example `serverUrl`           |
+| ----------- | ----------------------------- |
+| Hosted      | `https://api.gitterm.dev`     |
+| Self-hosted | `https://gitterm.example.com` |
+| Local dev   | `http://localhost:3000`       |
+
+### Explicit client (recommended for apps)
+
+```ts
+import { createGittermClient } from "@gitterm/sdk";
+
+// Hosted
+const hosted = createGittermClient({
+  serverUrl: "https://api.gitterm.dev",
+  token: process.env.GITTERM_API_TOKEN,
+});
+
+// Self-hosted / local
+const selfHosted = createGittermClient({
+  serverUrl: "https://gitterm.example.com", // or http://localhost:3000
+  token: process.env.GITTERM_API_TOKEN,
+});
+```
+
+### Environment variables
+
+```bash
+export GITTERM_SERVER_URL=https://gitterm.example.com
+export GITTERM_API_TOKEN=gt_...
+```
+
+```ts
+// Picks up GITTERM_SERVER_URL + GITTERM_API_TOKEN
+const client = createGittermClient();
+```
+
+### CLI saved login
+
+If you omit both options, the SDK also reads `~/.config/gitterm/cli.json` written by
+`gitterm login` / `gitterm login --server <url>`.
+
+**Resolution order:** constructor options → `GITTERM_SERVER_URL` / `GITTERM_API_TOKEN` → CLI config file.
+
+Create tokens in the dashboard under **Settings → Account → API tokens**, or via
+`gitterm login` (device-code flow). Tokens are the same `gt_...` shape on hosted and
+self-hosted.
+
 ## Usage
 
 ### With an explicit API token
 
-Create a token in the GitTerm dashboard under **Settings → Account → API tokens**
-(revocable, optional expiry), or obtain one via `gitterm login`.
-
 ```ts
 import { createGittermClient } from "@gitterm/sdk";
 
 const client = createGittermClient({
-  serverUrl: "https://api.gitterm.dev",
   token: process.env.GITTERM_API_TOKEN,
 });
 
 const { workspaces } = await client.workspaces.list();
 ```
 
-### With the CLI's saved login
+The SDK deliberately exposes two clients. `createGittermClient()` uses a user API token and
+can manage the user's workspaces. `createGittermWorkspaceClient()` uses the scoped identity
+injected into a GitTerm workspace and can inspect only that workspace and its ports:
+
+```ts
+import { createGittermWorkspaceClient } from "@gitterm/sdk";
+
+const workspace = createGittermWorkspaceClient();
+const self = await workspace.self.get();
+const preview = await workspace.ports.open(3000, { name: "app" });
+```
+
+The workspace client never reads the CLI's saved account login and has no create, list,
+pause, restart, or terminate operations.
 
-If you omit `serverUrl`/`token`, the SDK reads the config written by `gitterm login`
-(`~/.config/gitterm/cli.json`), falling back to the `GITTERM_SERVER_URL` and
-`GITTERM_API_TOKEN` environment variables.
+### With the CLI's saved login
 
 ```ts
 const client = createGittermClient();
 const status = await client.auth.status();
+// status + client.serverUrl show which account and server you hit
 ```
 
 ### API
@@ -47,14 +107,106 @@ const status = await client.auth.status();
 client.auth.status();                 // -> { userId, email, name, plan, authMethod }
 client.workspaces.list(options?);     // -> { workspaces, pagination }
 client.workspaces.get(workspaceId);
+client.workspaces.getRuntimeAccess(workspaceId); // read-only; never resumes compute
+client.workspaces.ensureRunning(workspaceId, options?);
 client.workspaces.pause(workspaceId);
 client.workspaces.restart(workspaceId);
 client.workspaces.terminate(workspaceId);
-client.workspaces.create(input);      // needs agentTypeId + cloudProviderId, see catalog
+client.workspaces.create({
+  repo: "https://github.com/acme/product",
+});
 client.catalog.agentTypes();
 client.catalog.cloudProviders();
+client.catalog.workspaceOptions();
+```
+
+The server defaults the agent to `opencode`, selects the user's preferred provider,
+uses that provider's default machine profile, and applies the provider's persistence policy.
+Override only the placement decisions your integration cares about:
+
+```ts
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  agent: "opencode",
+  setupCommands: ["npm install", "npm run generate"],
+  opencode: {
+    skills: [
+      {
+        name: "release-demo",
+        content: `---
+name: release-demo
+description: Record and publish a product release demo.
+---
+
+Follow the repository's release-demo workflow.`,
+      },
+    ],
+    plugins: ["@acme/opencode-browser@1.2.3"],
+  },
+  provider: {
+    type: "exedev",
+    machine: { type: "profile", key: "content-rendering" },
+  },
+});
+```
+
+Setup commands run in order from the checked-out repository after the agent server is
+ready. They do not delay workspace creation or stop the agent if they fail. Provider and
+agent defaults configured by an administrator run first. Use
+`client.workspaces.setupStatus(workspaceId)` or `waitForSetup(workspaceId)` to inspect them.
+GitTerm persists the reported state and bounded log; a recovery copy also lives in the
+repository's git-excluded `.gitterm/setup/` directory.
+
+`provider` is a discriminated union, so TypeScript only offers `region` for providers
+where GitTerm supports caller-selected placement. Machine keys are configured by admins
+and returned by `client.catalog.workspaceOptions()`; raw CPU, memory, credentials, and
+provider account configuration are never supplied by SDK callers.
+
+This makes release automation a normal workspace task: create an OpenCode workspace,
+run UI review or browser capture tools in the sandbox, upload the resulting media, update
+the changelog in the checked-out repository, then terminate the workspace. Use an
+`idempotencyKey` based on the release SHA when the workflow may be retried.
+
+### Agent runs
+
+Runs use durable GitTerm IDs backed by the workspace's native OpenCode session. Reusing an
+idempotency key with the same input returns the original run, and terminal results remain
+available after the workspace is paused. Completion means the native session became idle;
+it does not claim that a pull request, upload, or other product outcome succeeded.
+
+```ts
+const { workspace } = await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  setupCommands: ["npm install", "npm run db:seed"],
+});
+
+const run = await client.runs.create({
+  workspaceId: workspace.id,
+  idempotencyKey: "onboarding-v2",
+  waitForSetup: true,
+  prompt: "Record the new onboarding flow and open a pull request adding it to the changelog.",
+});
+
+const completed = await client.runs.wait(workspace.id, run.id);
+const messages = await client.runs.messages(workspace.id, run.id);
 ```
 
+Runs are isolated by default and can execute in parallel. To preserve conversational context,
+continue a terminal run; continued runs sharing context must remain sequential:
+
+```ts
+const next = await client.runs.create({
+  workspaceId: workspace.id,
+  idempotencyKey: "onboarding-tests-v1",
+  prompt: "Now add tests for that change.",
+  context: { type: "continue", runId: completed.id },
+});
+```
+
+Use `client.runs.cancel(workspaceId, runId)` to abort the current run. GitTerm keeps the
+underlying OpenCode session private. For native session control, use
+`workspaces.getRuntimeAccess()` and connect with the official OpenCode SDK.
+
 ### Errors
 
 Every method throws `GittermError` with a stable `code`:
@@ -71,24 +223,35 @@ try {
 }
 ```
 
-Codes: `NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`,
-`SERVER_ERROR`, `NETWORK`.
+Workspace lifecycle failures are also exposed as `WorkspaceLifecycleError`, with stable
+`WORKSPACE_TERMINATED`, `WORKSPACE_NON_RECOVERABLE`, `WORKSPACE_START_TIMEOUT`, and
+`WORKSPACE_RESTART_FAILED` codes. General codes are
+`NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`, `CONFLICT`,
+`SERVER_ERROR`, and `NETWORK`.
+
+The package ships self-contained declarations from `dist`; TypeScript consumers do not
+need GitTerm's API package or tRPC server types.
 
 ### Obtaining a token programmatically
 
-The device-code flow used by `gitterm login` is exposed for integrations:
+The device-code flow used by `gitterm login` is exposed for integrations. Pass the
+server URL of the instance you want to log into:
 
 ```ts
 import { loginWithDeviceCode, saveConfig, DEFAULT_GITTERM_SERVER_URL } from "@gitterm/sdk";
 
-const { token } = await loginWithDeviceCode(DEFAULT_GITTERM_SERVER_URL, {
+// Hosted: DEFAULT_GITTERM_SERVER_URL ("https://api.gitterm.dev")
+// Self-hosted: "https://gitterm.example.com" or "http://localhost:3000"
+const serverUrl = process.env.GITTERM_SERVER_URL ?? DEFAULT_GITTERM_SERVER_URL;
+
+const { token } = await loginWithDeviceCode(serverUrl, {
   onCode: ({ verificationUri, userCode }) => {
     console.log(`Visit ${verificationUri} and enter ${userCode}`);
   },
 });
 
 await saveConfig({
-  serverUrl: DEFAULT_GITTERM_SERVER_URL,
+  serverUrl,
   token,
   createdAt: Date.now(),
 });

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunMessage, AuthStatus, CloudProvider, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus } from "./types.js";
+export type GittermClientOptions = {
+    serverUrl?: string;
+    token?: string;
+    configPath?: string;
+    fetch?: typeof fetch;
+};
+export type GittermClient = {
+    serverUrl: string;
+    auth: {
+        status(): Promise<AuthStatus>;
+    };
+    workspaces: {
+        list(input?: WorkspaceListOptions): Promise<WorkspaceListResult>;
+        get(workspaceId: string): Promise<Workspace>;
+        getRuntimeAccess(workspaceId: string): Promise<WorkspaceRuntimeAccess>;
+        ensureRunning(workspaceId: string, options?: {
+            timeoutMs?: number;
+            pollIntervalMs?: number;
+        }): Promise<WorkspaceEnsureRunningResult>;
+        pause(workspaceId: string): Promise<WorkspacePauseResult>;
+        restart(workspaceId: string): Promise<WorkspaceRestartResult>;
+        terminate(workspaceId: string): Promise<WorkspaceTerminateResult>;
+        create(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
+        setupStatus(workspaceId: string): Promise<WorkspaceSetupStatus>;
+        waitForSetup(workspaceId: string, options?: {
+            timeoutMs?: number;
+            pollIntervalMs?: number;
+        }): Promise<WorkspaceSetupStatus>;
+    };
+    runs: {
+        create(input: AgentRunCreateInput): Promise<AgentRun>;
+        get(workspaceId: string, runId: string): Promise<AgentRun>;
+        messages(workspaceId: string, runId: string): Promise<AgentRunMessage[]>;
+        cancel(workspaceId: string, runId: string): Promise<{
+            cancelled: boolean;
+        }>;
+        wait(workspaceId: string, runId: string, options?: {
+            timeoutMs?: number;
+            pollIntervalMs?: number;
+        }): Promise<AgentRun>;
+    };
+    catalog: {
+        agentTypes(input?: {
+            serverOnly?: boolean;
+        }): Promise<AgentType[]>;
+        cloudProviders(input?: {
+            localOnly?: boolean;
+            cloudOnly?: boolean;
+            sandboxOnly?: boolean;
+            nonSandboxOnly?: boolean;
+        }): Promise<CloudProvider[]>;
+        workspaceOptions(): Promise<WorkspaceCatalog>;
+    };
+};
+export declare function createGittermClient(options?: GittermClientOptions): GittermClient;

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_GITTERM_SERVER_URL = "https://api.gitterm.dev";
+export type CliConfig = {
+    serverUrl: string;
+    token: string;
+    createdAt: number;
+};
+export declare function getConfigPath(configPath?: string): string;
+export declare function loadConfig(configPath?: string): Promise<CliConfig | null>;
+export declare function loadConfigSync(configPath?: string): CliConfig | null;
+export declare function saveConfig(config: CliConfig, configPath?: string): Promise<void>;
+export declare function deleteConfig(configPath?: string): Promise<void>;

package/dist/device-login.d.ts

@@ -0,0 +1,15 @@
+export type DeviceCodeInfo = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds: number;
+    expiresInSeconds: number;
+};
+export type LoginWithDeviceCodeOptions = {
+    clientName?: string;
+    fetch?: typeof fetch;
+    onCode?: (code: Omit<DeviceCodeInfo, "deviceCode">) => void | Promise<void>;
+};
+export declare function loginWithDeviceCode(serverUrl: string, options?: LoginWithDeviceCodeOptions): Promise<{
+    token: string;
+}>;

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | WorkspaceLifecycleErrorCode;
+export type WorkspaceLifecycleErrorCode = "WORKSPACE_TERMINATED" | "WORKSPACE_NON_RECOVERABLE" | "WORKSPACE_START_TIMEOUT" | "WORKSPACE_RESTART_FAILED";
+export declare class GittermError extends Error {
+    readonly code: GittermErrorCode;
+    readonly cause?: unknown;
+    constructor(code: GittermErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class WorkspaceLifecycleError extends GittermError {
+    readonly code: WorkspaceLifecycleErrorCode;
+    constructor(code: WorkspaceLifecycleErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/index.d.ts

@@ -1,213 +1,9 @@
-/**
- * Hand-maintained public type surface for @gitterm/sdk.
- *
- * External npm consumers resolve these types instead of the TypeScript
- * sources, because the sources derive types from the private @gitterm/api
- * router. Keep this file in sync with src/types.ts and src/client.ts.
- *
- * TODO: replace with generated declarations once the AppRouter types can be
- * bundled into a standalone .d.ts.
- */
-
-export const DEFAULT_GITTERM_SERVER_URL: string;
-
-export type CliConfig = {
-  serverUrl: string;
-  token: string;
-  createdAt: number;
-};
-
-export type GittermErrorCode =
-  | "NOT_LOGGED_IN"
-  | "UNAUTHORIZED"
-  | "NOT_FOUND"
-  | "FORBIDDEN"
-  | "BAD_REQUEST"
-  | "SERVER_ERROR"
-  | "NETWORK";
-
-export class GittermError extends Error {
-  readonly code: GittermErrorCode;
-  readonly cause?: unknown;
-  constructor(code: GittermErrorCode, message: string, options?: { cause?: unknown });
-}
-
-export type GittermClientOptions = {
-  serverUrl?: string;
-  token?: string;
-  configPath?: string;
-  fetch?: typeof fetch;
-};
-
-export type AuthStatus = {
-  loggedIn: true;
-  userId: string;
-  email: string;
-  name: string;
-  plan: string;
-  authMethod: "session" | "apiToken";
-};
-
-export type WorkspaceStatus = "pending" | "running" | "paused" | "terminated";
-export type WorkspaceHostingType = "cloud" | "local";
-
-export type Workspace = {
-  id: string;
-  name: string | null;
-  status: WorkspaceStatus;
-  repositoryUrl: string | null;
-  repositoryBranch: string | null;
-  baseCommit: string | null;
-  checkoutRef: string | null;
-  domain: string;
-  subdomain: string | null;
-  persistent: boolean;
-  hostingType: WorkspaceHostingType;
-  serverOnly: boolean;
-  workspaceProfile: string;
-  cloudProviderId: string;
-  agentType: { id: string; name: string; description: string | null } | null;
-  image: { id: string; name: string; imageId: string } | null;
-  startedAt: string | null;
-  stoppedAt: string | null;
-  terminatedAt: string | null;
-  lastActiveAt: string | null;
-  updatedAt: string | null;
-};
-
-export type WorkspaceRuntimeAccess = {
-  workspaceId: string;
-  status: WorkspaceStatus;
-  url: string | null;
-  headers?: Record<string, string>;
-  password?: string;
-  directory: string;
-  repo: string | null;
-  branch: string | null;
-  baseCommit: string | null;
-  checkoutRef: string | null;
-  persistent: boolean;
-  recoverable: boolean;
-  providerKey: string | null;
-};
-
-export type WorkspaceCreateResult = {
-  workspace: Workspace;
-  runtime: WorkspaceRuntimeAccess;
-};
-
-export type WorkspaceListOptions = {
-  limit?: number;
-  offset?: number;
-  status?: "all" | "active" | "terminated";
-};
-
-export type WorkspaceListResult = {
-  workspaces: Workspace[];
-  pagination: {
-    total: number;
-    limit: number;
-    offset: number;
-    hasMore: boolean;
-  };
-};
-
-export type WorkspaceCreateInput = {
-  name?: string;
-  repo?: string;
-  branch?: string;
-  baseCommit?: string;
-  checkoutRef?: string;
-  subdomain?: string;
-  agentTypeId: string;
-  cloudProviderId: string;
-  regionId?: string;
-  gitIntegrationId?: string;
-  persistent: boolean;
-  workspaceProfile?: "standard" | "ssh-enabled";
-};
-
-export type WorkspaceStopResult = { durationMinutes: number };
-export type WorkspacePauseResult = WorkspaceStopResult;
-export type WorkspaceRestartResult = { status: WorkspaceStatus };
-export type WorkspaceTerminateResult = {
-  workspace: Workspace | null;
-  cleanupInBackground: boolean;
-};
-export type WorkspaceEnsureRunningResult = {
-  workspace: Workspace;
-  runtime: WorkspaceRuntimeAccess;
-};
-
-export type AgentType = {
-  id: string;
-  name: string;
-  description: string | null;
-  serverOnly: boolean;
-  isEnabled: boolean;
-  createdAt: Date | string;
-  updatedAt: Date | string;
-};
-
-export type CloudProvider = Record<string, unknown> & {
-  id: string;
-  name: string;
-  providerKey: string;
-  regions?: Array<Record<string, unknown>>;
-};
-
-export type GittermClient = {
-  serverUrl: string;
-  auth: {
-    status(): Promise<AuthStatus>;
-  };
-  workspaces: {
-    list(input?: WorkspaceListOptions): Promise<WorkspaceListResult>;
-    get(workspaceId: string): Promise<Workspace>;
-    getRuntimeAccess(workspaceId: string): Promise<WorkspaceRuntimeAccess>;
-    ensureRunning(
-      workspaceId: string,
-      options?: { timeoutMs?: number; pollIntervalMs?: number },
-    ): Promise<WorkspaceEnsureRunningResult>;
-    pause(workspaceId: string): Promise<WorkspacePauseResult>;
-    restart(workspaceId: string): Promise<WorkspaceRestartResult>;
-    terminate(workspaceId: string): Promise<WorkspaceTerminateResult>;
-    create(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
-    createSandbox(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
-  };
-  catalog: {
-    agentTypes(input?: { serverOnly?: boolean }): Promise<AgentType[]>;
-    cloudProviders(input?: {
-      localOnly?: boolean;
-      cloudOnly?: boolean;
-      sandboxOnly?: boolean;
-      nonSandboxOnly?: boolean;
-    }): Promise<CloudProvider[]>;
-  };
-};
-
-export function createGittermClient(options?: GittermClientOptions): GittermClient;
-export function getConfigPath(configPath?: string): string;
-export function loadConfig(configPath?: string): Promise<CliConfig | null>;
-export function loadConfigSync(configPath?: string): CliConfig | null;
-export function saveConfig(config: CliConfig, configPath?: string): Promise<void>;
-export function deleteConfig(configPath?: string): Promise<void>;
-
-export type DeviceCodeInfo = {
-  deviceCode: string;
-  userCode: string;
-  verificationUri: string;
-  intervalSeconds: number;
-  expiresInSeconds: number;
-};
-
-export type LoginWithDeviceCodeOptions = {
-  clientName?: string;
-  fetch?: typeof fetch;
-  onCode?: (code: Omit<DeviceCodeInfo, "deviceCode">) => void | Promise<void>;
-};
-
-export function loginWithDeviceCode(
-  serverUrl: string,
-  options?: LoginWithDeviceCodeOptions,
-): Promise<{ token: string }>;
+export { createGittermClient, type GittermClient, type GittermClientOptions } from "./client.js";
+export { DEFAULT_GITTERM_SERVER_URL, getConfigPath, loadConfig, loadConfigSync, saveConfig, deleteConfig, } from "./config.js";
+export type { CliConfig } from "./config.js";
+export { loginWithDeviceCode } from "./device-login.js";
+export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.js";
+export { GittermError, WorkspaceLifecycleError } from "./errors.js";
+export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspaceSelf, } from "./workspace-client.js";
+export type { GittermErrorCode, WorkspaceLifecycleErrorCode } from "./errors.js";
+export type { AgentRun, AgentRunCreateInput, AgentRunMessage, AgentRunStatus, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, } from "./types.js";