@gitterm/sdk 0.4.0 → 0.6.1

package/README.md

@@ -23,12 +23,12 @@ Create a workspace, run a prompt, and get the final result:
 import { createGittermClient } from "@gitterm/sdk";
 
 const client = createGittermClient({ token: process.env.GITTERM_API_TOKEN });
-const [github] = await client.integrations.github.list();
+const [github] = await client.integrations.connections.list({ integration: "github" });
 if (!github) throw new Error("Connect GitHub in the Gitterm dashboard first");
 
 const { workspace } = await client.workspaces.create({
   repo: "https://github.com/acme/product",
-  gitIntegrationId: github.id,
+  connections: [github.id],
   autoTerminateAfterMs: 2 * 60 * 60 * 1000,
 });
 
@@ -45,16 +45,17 @@ try {
 }
 ```
 
-Connected cloud identities are discoverable without returning credentials:
+Every integration you can attach, personal or admin-provided, is a **connection** with one shape.
+Attach any number by id (at most one per integration):
 
 ```ts
-const [github] = await client.integrations.github.list();
-const [googleCloud] = await client.integrations.googleCloud.list();
+const connections = await client.integrations.connections.list();
+const github = connections.find((c) => c.integration === "github");
+const google = connections.find((c) => c.integration === "google");
 
 await client.workspaces.create({
   repo: "https://github.com/acme/product",
-  gitIntegrationId: github.id,
-  googleCloudIntegrationId: googleCloud.id,
+  connections: [github!.id, google!.id],
 });
 ```
 
@@ -117,12 +118,14 @@ without a GitTerm server, is described at the [end](#direct-provider-mode).
 `createGittermClient()` resolves its server and token in this order: constructor options →
 `GITTERM_SERVER_URL` / `GITTERM_API_TOKEN` → the CLI config at `~/.config/gitterm/cli.json`
 written by `gitterm login`. The default server is the hosted API at `https://api.gitterm.dev`;
-self-hosted instances use the same SDK with their own `serverUrl`:
+self-hosted instances use the same SDK with their own `serverUrl`. Behind the bundled
+path-routing proxy, point it at the `/api` path (for example
+`GITTERM_SERVER_URL=https://<host>/api`); a server reached directly uses its origin:
 
 ```ts
 const hosted = createGittermClient({ token: process.env.GITTERM_API_TOKEN });
 const selfHosted = createGittermClient({
-  serverUrl: "https://gitterm.example.com", // or http://localhost:3000
+  serverUrl: "https://gitterm.example.com/api", // or http://localhost:3000
   token: process.env.GITTERM_API_TOKEN,
 });
 const fromCli = createGittermClient(); // env vars, then the CLI's saved login
@@ -160,8 +163,16 @@ client.catalog.cloudProviders();
 client.catalog.workspaceOptions();
 client.credentials.list();             // dashboard credential metadata, never secrets
 client.credentials.listProviders();
-client.models.list({ provider: "openai" }); // discover provider/model IDs
-client.workspaces.models(workspace);  // resolved sources + known models; no secrets or runtime wake-up
+client.integrations.catalog();         // integrations the admin enabled: key, category, personal/shared
+client.integrations.connections.list(filter?); // what you can attach; personal + shared, one shape
+client.integrations.connections.get(id);
+client.integrations.connections.create(input); // integrations:write; may return a browser step
+client.integrations.connections.remove(id);
+client.integrations.connections.waitFor({ integration, since }); // after a `pending` create
+client.integrations.github.repositories(connectionId);
+client.integrations.github.branches(connectionId, owner, repo);
+client.integrations.google.setup();    // issuer + attribute mapping to configure Google
+client.workspaces.models(workspace);  // resolved credential sources; no secrets or runtime wake-up
 ```
 
 Every poll-based wait (`ensureRunning`, `waitForSetup`, and `runs.create` with `waitForSetup`)
@@ -175,19 +186,77 @@ finishes tearing down resources after the call returns.
 
 ## Workspaces
 
-### Managed private repositories
+### Integrations and connections
 
-For renewable, short-lived repository authentication, connect the GitHub App in the GitTerm
-dashboard and copy its **SDK integration ID** from the Integrations page:
+`client.integrations` works the same way for every provider. `catalog()` tells you which
+integrations the admin has enabled and whether each allows **personal** connections (you create
+them, e.g. by installing the GitHub App) and/or a **shared** one (the admin provides it for the
+whole deployment). `connections.list()` returns everything you can attach right now:
 
 ```ts
-const { workspace, runtime } = await client.workspaces.create({
-  repo: "https://github.com/acme/private-repo",
-  branch: "main",
-  gitIntegrationId: "your-dashboard-integration-id",
+for (const c of await client.integrations.connections.list()) {
+  console.log(c.id, c.integration, c.kind, c.name, c.status);
+}
+// 8c1f…        github  personal  acme-bot (GitHub App)   connected
+// github:shared github  shared    acme-ci (shared PAT)    connected
+// 3f7d…        google  personal  Production              connected
+```
+
+Personal connection ids are stable row ids. Shared connection ids are well-known:
+`<integration>:shared`. Pass any mix to `workspaces.create({ connections: [...] })`; the server
+rejects more than one connection per integration. Credentials are issued inside the workspace and
+are never returned to the SDK caller.
+
+#### Creating connections from the SDK
+
+Creating a connection requires an API token with the `integrations:write` scope. Some providers
+complete immediately; others need a browser step and return `pending`:
+
+```ts
+// Google Cloud: completes immediately, then tell the user what to run in gcloud.
+const setup = await client.integrations.google.setup(); // issuer to configure on the provider
+const created = await client.integrations.connections.create({
+  integration: "google",
+  name: "Production",
+  projectId: "my-project",
+  workloadIdentityProvider:
+    "projects/123456789/locations/global/workloadIdentityPools/gitterm/providers/gitterm",
+  serviceAccountEmail: "agent@my-project.iam.gserviceaccount.com",
 });
+if (created.status === "connected") {
+  for (const step of created.nextSteps) console.log(step.label, "\n", step.command);
+}
+
+// GitHub App: the user installs the App in a browser, then we wait for the connection.
+const started = new Date();
+const pending = await client.integrations.connections.create({ integration: "github" });
+if (pending.status === "pending") {
+  console.log("Open", pending.authorizeUrl);
+  const github = await client.integrations.connections.waitFor({
+    integration: "github",
+    since: started,
+  });
+  console.log("Connected as", github.name);
+}
 ```
 
+`connections.remove(id)` disconnects a personal connection (for GitHub it asks GitHub to uninstall
+the App; the removal completes when GitHub confirms). Shared connections are managed by the admin.
+
+#### GitHub
+
+A GitHub App connection can browse what it has access to:
+
+```ts
+const repos = await client.integrations.github.repositories(github.id);
+const branches = await client.integrations.github.branches(github.id, "acme", "product");
+```
+
+The admin picks one repository mode for the deployment: either users install a GitHub App
+(personal connections) or the admin provides a shared PAT (`github:shared`). The shared PAT
+authenticates as the admin-chosen GitHub account, so its permissions apply to every workspace that
+attaches it. Neither mode requires GitHub login.
+
 Managed workspaces can also use dashboard-managed model subscriptions while accepting an
 application-owned GitHub PAT inline:
 
@@ -206,11 +275,10 @@ const { workspace, runtime } = await client.workspaces.create({
 });
 ```
 
-The username defaults to `x-access-token`. Inline repository credentials take precedence over
-`gitIntegrationId` and authenticate repository validation, cloning, and runtime Git operations such
-as pull and push. Without inline credentials, `gitIntegrationId` continues to use the connected
-dashboard integration. Omitting `models` likewise continues to
-use dashboard-managed model credentials.
+The username defaults to `x-access-token`. Use either a GitHub connection in `connections` or
+`repositoryCredentials`, not both. Both authenticate repository validation, cloning, and runtime
+Git operations such as pull and push. Omitting `models` continues to use dashboard-managed model
+credentials.
 
 #### GitHub CLI authentication
 
@@ -218,12 +286,15 @@ For GitHub repositories, GitTerm configures both Git and `gh` from the same work
 credentials. Agents can run commands such as `gh pr list` or `gh pr create` without
 running `gh auth login`:
 
-- `repositoryCredentials.token` takes precedence over `gitIntegrationId`. The supplied
-  token is retained in a permission-restricted file on the workspace machine and is
-  not automatically renewed. This also works with the standalone SDK's direct providers.
-- `gitIntegrationId` uses the GitHub App installation token. Git and `gh` share a
+- `repositoryCredentials.token` is retained in a permission-restricted file on the workspace
+  machine and is not automatically renewed. This also works with the standalone SDK's direct
+  providers.
+- A personal GitHub connection uses the GitHub App installation token. Git and `gh` share a
   cached token and refresh it through GitTerm before expiry. Concurrent commands share
   the refresh, and a failed refresh stops the command rather than using an expired token.
+- The shared `github:shared` connection uses the admin's deployment-wide PAT. Switching the
+  deployment's GitHub mode prevents future refreshes for existing workspaces using it; revoke
+  the PAT at GitHub to stop access in an already-running workspace.
 - Without repository credentials or an integration, GitTerm leaves CLI authentication
   to the environment or the CLI's existing configuration.
 
@@ -253,8 +324,9 @@ Updating an integration's token does not grant permissions absent from its insta
 GitTerm does not save inline PATs in its application database. Inline PATs must be delivered to the
 selected compute provider and retained on the workspace machine for runtime Git operations, so
 provider infrastructure and processes running in that workspace may be able to access them. Prefer
-`gitIntegrationId` for durable managed workspaces and use narrowly scoped, short-lived PATs when
-inline credentials are necessary.
+a GitHub connection for durable managed workspaces and use narrowly scoped, short-lived PATs when
+inline credentials are necessary. The standalone/direct SDK has no GitTerm account to look up:
+it supports `repositoryCredentials` but not `connections`.
 
 The SDK deliberately exposes two clients. `createGittermClient()` uses a user API token and
 can manage the user's workspaces. `createGittermWorkspaceClient()` uses the scoped identity
@@ -266,8 +338,14 @@ import { createGittermWorkspaceClient } from "@gitterm/sdk";
 const workspace = createGittermWorkspaceClient();
 const self = await workspace.self.get();
 const preview = await workspace.ports.open(3000, { name: "app" });
+const api = await workspace.ports.open(8080, { name: "api", visibility: "public" });
 ```
 
+Ports are `private` by default: only the workspace owner's signed-in GitTerm browser session can
+reach the URL. Make a port `public` when it needs to be reachable without a GitTerm login, for
+example an API or webhook receiver. Use `workspace.ports.setVisibility(port, visibility)` to change
+it later.
+
 The workspace client never reads the CLI's saved account login and has no create, list,
 pause, restart, or terminate operations.
 
@@ -660,20 +738,21 @@ selection fails explicitly; give them distinct dashboard labels. Discovery requi
 **Inline credentials** use `{ source: "apiKey", apiKey }` for this workspace only. A missing or
 blank key fails validation; it never falls back to a saved credential. Keys are injected into
 the sandbox, not saved in the dashboard. `credentials.listProviders()` includes each authentication
-integration's `logicalProviderKey`. `models.list({ provider: "openai" })` discovers model IDs.
-Managed OAuth credentials must be connected through the dashboard.
+integration's `logicalProviderKey`. Managed OAuth credentials must be connected through the
+dashboard.
 
-`workspaces.models(workspace)` shows which sources were configured and the matching catalog models.
+`workspaces.models(workspace)` shows which credential sources were configured.
 It reads control-plane metadata only: it does not verify a key with the model provider, discover
 custom runtime models, or resume a paused workspace. A saved credential's label/active status is
 its current dashboard metadata.
 
 Rules and errors:
 
-- Omitting `models` uses dashboard defaults. An explicit `models` block defaults to
+- Omitting `models` ships every saved dashboard account, labelled as in the dashboard, with each
+  provider's default as the active OpenCode account. An explicit `models` block defaults to
   `inherit: "none"`; `models: {}` injects no dashboard credentials.
-- Use `inherit: "defaults"` to inherit every unlisted provider's dashboard default. Explicit
-  sources override only their own provider. Each provider map key selects exactly one source.
+- Use `inherit: "defaults"` to ship every unlisted provider's saved accounts the same way. Explicit
+  sources override only their own provider and ship exactly one account for it.
 - Unknown providers or inline keys for OAuth-only providers throw `MODEL_CREDENTIAL_INVALID`.
   A missing or ambiguous label throws `MODEL_CREDENTIAL_UNAVAILABLE`.
 - A run that requests a credential-backed `provider/model` not available in its workspace throws
@@ -683,12 +762,20 @@ Rules and errors:
 for that run. Credentials remain workspace-scoped: changing credentials for one concurrent run
 would otherwise change them for other runs on the same runtime.
 
-## OpenCode API versions
+## OpenCode runtime
+
+Every workspace runs OpenCode 2 (the `@opencode/cli` npm package) and its `/api/*` HTTP API. Runs,
+questions, permissions, and events use GitTerm's OpenCode 2 runtime adapter. Attach a local TUI with
+`OPENCODE_PASSWORD=<password> opencode --server <workspace url>`.
 
-Managed workspaces default to OpenCode V1 from `opencode-ai` and use `opencodeApi: "v1"`.
-Credentials are written to OpenCode's `auth.json` before the runtime starts. Runs, questions,
-permissions, and events use GitTerm's V1 runtime adapter. V2 remains selectable only for explicitly
-compatible images.
+OpenCode 2 keeps credentials in its SQLite store and has no headless import, so workspaces receive
+`~/.gitterm/opencode/credentials.json` and a local OpenCode plugin at
+`~/.config/opencode/plugins/gitterm-credentials.js`. The plugin imports each account through OpenCode's
+integration API on first load under its dashboard label (inline keys use `Gitterm`), so a provider can
+carry several accounts and `opencode auth switch` works inside the workspace. The dashboard default is
+the account OpenCode selects. Accounts whose label already exists on the integration are skipped, so
+restarts are idempotent. OAuth entries are stored with OpenCode's built-in method IDs and refreshed by
+OpenCode itself.
 
 ## Errors
 
@@ -814,10 +901,9 @@ Direct mode does not provide managed durable run storage or submission idempoten
 Serialized workspaces/runs contain runtime credentials: encrypt them and never send them to an
 untrusted UI. Custom providers can implement `DirectProviderAdapter`; inspect `client.provider.capabilities`.
 
-Both modes default to OpenCode **v1** and share v1/v2 run, permission, question, and SSE adapters.
-For direct v2, supply a compatible provider image/template and `opencode: { api: "v2" }` at workspace
-creation. The flag chooses the protocol; it does not install or upgrade the runtime. Direct mode
-does not accept saved/dashboard credential sources or `inherit: "defaults"`.
+Both modes run OpenCode 2 and share its run, permission, question, and SSE adapters. Provider
+images/templates must ship OpenCode 2 (`@opencode/cli`). Direct mode does not accept saved/dashboard
+credential sources or `inherit: "defaults"`.
 
 Every adapter receives the same normalized plan: repository/ref and optional Git credentials, agent files, model credentials, environment, setup commands, serve command, and port. Provider-specific configuration only describes how to allocate and expose compute.
 
@@ -860,9 +946,9 @@ await direct.workspaces.create({
 
 ### Provider authentication
 
-Direct **v2** workspaces can start OpenCode provider authentication without shell access. This
-connection-management API is v2-only; v1 supports inline API keys/OAuth bundles at creation and
-`auth.setCredential()`. Discover a headless/device-code method for remote authentication:
+Direct workspaces can start OpenCode provider authentication without shell access. Inline API
+keys/OAuth bundles are still accepted at creation. Discover a headless/device-code method for remote
+authentication:
 
 ```ts
 const openai = await direct.auth.get(workspace, "openai");
@@ -909,14 +995,11 @@ const workspace = await direct.workspaces.create({
   },
 });
 
-// v1 credentials can also be added or rotated on an existing runtime.
-// On v2, setCredential supports API keys; use connectOAuth for OAuth rotation.
+// API keys can also be added or rotated on an existing runtime; use connectOAuth for OAuth rotation.
 await direct.auth.setCredential(workspace, {
-  source: "oauth",
+  source: "apiKey",
   providerName: "openai",
-  refreshToken: credential.refreshToken,
-  accessToken: credential.accessToken,
-  expiresAt: credential.expiresAt,
+  apiKey: credential.apiKey,
 });
 ```
 

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, GitHubIntegration, GoogleCloudIntegration } from "./types.js";
-import type { AgentRunEvent, AgentRunResult, RunResultOptions, ModelInfo, WorkspaceModelAccess } from "./types.js";
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, Integration, IntegrationKey, Connection, ConnectionKind, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup } from "./types.js";
+import type { AgentRunEvent, AgentRunResult, RunResultOptions, WorkspaceModelAccess } from "./types.js";
 export type GittermClientOptions = {
     serverUrl?: string;
     token?: string;
@@ -22,7 +22,7 @@ export type GittermClient = {
         terminate(workspace: WorkspaceRef): Promise<WorkspaceTerminateResult>;
         create(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
         setupStatus(workspace: WorkspaceRef): Promise<WorkspaceSetupStatus>;
-        /** Credential-source metadata and known models; never wakes the runtime. */
+        /** Credential-source metadata; never wakes the runtime. */
         models(workspace: WorkspaceRef): Promise<WorkspaceModelAccess>;
         waitForSetup(workspace: WorkspaceRef, options?: WaitOptions): Promise<WorkspaceSetupStatus>;
     };
@@ -70,17 +70,39 @@ export type GittermClient = {
         listProviders(): Promise<ModelProviderInfo[]>;
     };
     integrations: {
+        /** Integrations the admin has enabled for this deployment. */
+        catalog(): Promise<Integration[]>;
+        connections: {
+            /** Personal and shared connections you can attach to a workspace. */
+            list(filter?: {
+                integration?: IntegrationKey;
+                kind?: ConnectionKind;
+            }): Promise<Connection[]>;
+            get(id: string): Promise<Connection>;
+            /** Requires the `integrations:write` scope. */
+            create(input: CreateConnectionInput): Promise<CreateConnectionResult>;
+            /** Removes a personal connection. Shared connections are managed by the admin. */
+            remove(id: string): Promise<void>;
+            /**
+             * Poll until a connection for `integration` connected after `since` appears; use after a
+             * `pending` create result once the browser step is done.
+             */
+            waitFor(options: {
+                integration: IntegrationKey;
+                since?: Date | string;
+                timeoutMs?: number;
+                intervalMs?: number;
+            }): Promise<Connection>;
+        };
         github: {
-            list(): Promise<GitHubIntegration[]>;
+            /** Repositories reachable through a GitHub App connection. */
+            repositories(connectionId: string): Promise<GitHubRepository[]>;
+            branches(connectionId: string, owner: string, repo: string): Promise<GitHubBranch[]>;
         };
-        googleCloud: {
-            list(): Promise<GoogleCloudIntegration[]>;
+        google: {
+            /** Issuer and attribute mapping to configure the Google provider before connecting. */
+            setup(): Promise<GoogleSetup>;
         };
     };
-    models: {
-        list(options?: {
-            provider?: string;
-        }): Promise<ModelInfo[]>;
-    };
 };
 export declare function createGittermClient(options?: GittermClientOptions): GittermClient;