@gitterm/sdk 0.4.0 → 0.6.1

package/dist/direct/types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRun, AgentRunMessage, OpencodeApi, RunWaitOptions } from "../types.js";
+import type { AgentRun, AgentRunMessage, RunWaitOptions } from "../types.js";
 export type DirectWorkspaceLifecycle = "ephemeral" | "persistent";
 export type DirectWorkspaceStatus = "pending" | "running" | "paused" | "failed" | "terminated" | "unknown";
 export type DirectProviderCapabilities = {
@@ -11,12 +11,16 @@ export type DirectProviderCapabilities = {
 };
 export type DirectApiModelCredential = {
     providerName: string;
+    /** Account label shown in OpenCode. Defaults to "Gitterm". */
+    label?: string;
     source: "apiKey";
     apiKey: string;
     metadata?: Record<string, string>;
 };
 export type DirectOAuthModelCredential = {
     providerName: string;
+    /** Account label shown in OpenCode. Defaults to "Gitterm". */
+    label?: string;
     source: "oauth";
     refreshToken: string;
     /** May be omitted when OpenCode should refresh immediately. */
@@ -147,8 +151,6 @@ export type DirectWorkspaceCreateInput = {
     /** Trusted integration context appended to the generated global AGENTS.md. */
     additionalAgentInstructions?: string;
     opencode?: {
-        /** Defaults to v1. v2 requires a compatible provider image/template. */
-        api?: OpencodeApi;
         config?: Record<string, unknown>;
         plugins?: string[];
         skills?: Array<{
@@ -170,7 +172,6 @@ export type DirectWorkspace = {
     status: DirectWorkspaceStatus;
     lifecycle: DirectWorkspaceLifecycle;
     runtime: DirectWorkspaceRuntime;
-    opencodeApi: OpencodeApi;
     setup: "not_requested" | "before_agent_complete" | "after_agent";
     createdAt: string;
 };

package/dist/index.d.ts

@@ -4,6 +4,6 @@ export type { CliConfig } from "./config.js";
 export { loginWithDeviceCode } from "./device-login.js";
 export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.js";
 export { AgentRunError, GittermError, WorkspaceLifecycleError } from "./errors.js";
-export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspaceSelf, } from "./workspace-client.js";
+export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspacePortVisibility, type WorkspaceSelf, } from "./workspace-client.js";
 export type { CredentialErrorCode, GittermErrorCode, WorkspaceLifecycleErrorCode, } from "./errors.js";
-export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, OpencodeApi, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, GitHubIntegration, GoogleCloudIntegration, } from "./types.js";
+export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, Integration, IntegrationKey, IntegrationCategory, Connection, ConnectionKind, ConnectionStatus, ConnectionDetails, GitHubConnectionDetails, GoogleConnectionDetails, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup, } from "./types.js";

package/dist/index.js

@@ -112,6 +112,23 @@ function normalizeServerUrl(value) {
   url.search = "";
   return url.toString().replace(/\/$/, "");
 }
+function withPath(serverUrl, pathname) {
+  const url = new URL(serverUrl);
+  url.pathname = pathname;
+  return url.toString();
+}
+function basePath(serverUrl) {
+  return new URL(serverUrl).pathname.replace(/\/+$/, "");
+}
+function trpcEndpoint(serverUrl) {
+  const base = basePath(serverUrl);
+  return withPath(serverUrl, base.endsWith("/trpc") ? base : `${base}/trpc`);
+}
+function apiEndpoint(serverUrl, route) {
+  const base = basePath(serverUrl);
+  const apiBase = base.endsWith("/api") ? base : `${base}/api`;
+  return withPath(serverUrl, `${apiBase}/${route.replace(/^\/+/, "")}`);
+}
 function createNoRedirectFetch(fetchImpl = fetch) {
   return async (input, init) => {
     const response = await fetchImpl(input, { ...init, redirect: "manual" });
@@ -270,6 +287,9 @@ function runHelpers(operations) {
 }
 
 // src/client.ts
+function toConnection(connection) {
+  return { ...connection, connectedAt: toIso(connection.connectedAt) };
+}
 function envValue(name) {
   const value = typeof process !== "undefined" ? process.env[name] : undefined;
   return value && value.trim() ? value : undefined;
@@ -283,9 +303,6 @@ function resolveCredentials(options) {
   }
   return { serverUrl: normalizeServerUrl(serverUrl), token };
 }
-function toTrpcUrl(serverUrl) {
-  return new URL("/trpc", serverUrl).toString();
-}
 function toIso(value) {
   if (!value)
     return null;
@@ -351,7 +368,6 @@ function normalizeWorkspace(workspace) {
       imageId: workspace.image.imageId
     } : null,
     metadata: workspace.metadata ?? {},
-    opencodeApi: workspace.opencodeApi ?? "v1",
     autoTerminateAt: toIso(workspace.autoTerminateAt),
     customImage: workspace.customImage ?? null,
     startedAt: toIso(workspace.startedAt),
@@ -490,14 +506,14 @@ function createGittermClient(options = {}) {
       splitLink({
         condition: (operation) => operation.type === "subscription",
         true: httpSubscriptionLink({
-          url: toTrpcUrl(credentials.serverUrl),
+          url: trpcEndpoint(credentials.serverUrl),
           EventSource,
           eventSourceOptions: {
             fetch: (url, init) => fetchImpl(url, { ...init, headers: { ...init.headers, authorization } })
           }
         }),
         false: httpBatchLink({
-          url: toTrpcUrl(credentials.serverUrl),
+          url: trpcEndpoint(credentials.serverUrl),
           fetch: fetchImpl,
           headers: () => ({ authorization })
         })
@@ -534,7 +550,7 @@ function createGittermClient(options = {}) {
     const timeoutMs = waitOptions?.timeoutMs ?? 10 * 60000;
     const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
     const signal = waitOptions?.signal;
-    const deadline2 = Date.now() + timeoutMs;
+    const deadline = Date.now() + timeoutMs;
     while (true) {
       throwIfAborted(signal, "waiting for workspace setup");
       const result = await trpc.workspace.getSetupStatus.query({ workspaceId }, { signal });
@@ -545,7 +561,7 @@ function createGittermClient(options = {}) {
         throw new GittermError("BAD_REQUEST", `Workspace setup failed${result.exitCode === null ? "" : ` with exit code ${result.exitCode}`}${log ? `
 ${log}` : ""}`);
       }
-      if (Date.now() >= deadline2) {
+      if (Date.now() >= deadline) {
         const log = result.log?.trim();
         throw new GittermError("TIMEOUT", `Timed out waiting for workspace ${workspaceId} setup (last status: ${result.status})${log ? `
 ${log}` : ""}`);
@@ -674,44 +690,43 @@ ${log}` : ""}`);
       }),
       workspaceOptions: () => run(async () => trpc.workspace.getWorkspaceCatalog.query())
     },
-    models: {
-      list: (listOptions) => run(async () => {
-        const result = await trpc.modelCredentials.listModels.query();
-        return result.models.map((model) => ({
-          id: model.modelId,
-          name: model.displayName,
-          provider: model.modelId.slice(0, model.modelId.indexOf("/")),
-          isFree: model.isFree,
-          isRecommended: model.isRecommended
-        })).filter((model) => !listOptions?.provider || model.provider === listOptions.provider);
-      })
-    },
     integrations: {
-      github: {
-        list: () => run(async () => {
-          const result = await trpc.workspace.listUserInstallations.query();
-          return result.installations.map(({ git_integration, github_app_installation }) => ({
-            id: git_integration.id,
-            accountLogin: git_integration.providerAccountLogin,
-            accountType: github_app_installation.accountType,
-            repositorySelection: github_app_installation.repositorySelection,
-            suspended: github_app_installation.suspended,
-            connectedAt: toIso(git_integration.connectedAt)
-          }));
+      catalog: () => run(async () => trpc.integrations.catalog.query()),
+      connections: {
+        list: (filter) => run(async () => {
+          const result = await trpc.integrations.connections.list.query(filter);
+          return result.map(toConnection);
+        }),
+        get: (id) => run(async () => toConnection(await trpc.integrations.connections.get.query({ id }))),
+        create: (input) => run(async () => {
+          const result = await trpc.integrations.connections.create.mutate(input);
+          return result.status === "connected" ? { ...result, connection: toConnection(result.connection) } : result;
+        }),
+        remove: (id) => run(async () => {
+          await trpc.integrations.connections.remove.mutate({ id });
+        }),
+        waitFor: ({ integration, since, timeoutMs = 5 * 60000, intervalMs = 3000 }) => run(async () => {
+          const sinceMs = since ? new Date(since).getTime() : 0;
+          const deadline = Date.now() + timeoutMs;
+          while (Date.now() < deadline) {
+            const result = await trpc.integrations.connections.list.query({
+              integration,
+              kind: "personal"
+            });
+            const match = result.map(toConnection).filter((c) => c.status === "connected" && new Date(c.connectedAt).getTime() >= sinceMs).sort((a, b) => b.connectedAt.localeCompare(a.connectedAt))[0];
+            if (match)
+              return match;
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+          }
+          throw new Error(`Timed out waiting for a ${integration} connection`);
         })
       },
-      googleCloud: {
-        list: () => run(async () => {
-          const result = await trpc.googleCloud.list.query();
-          return result.map((integration) => ({
-            id: integration.id,
-            name: integration.name,
-            projectId: integration.projectId,
-            workloadIdentityProvider: integration.workloadIdentityProvider,
-            serviceAccountEmail: integration.serviceAccountEmail,
-            connectedAt: toIso(integration.connectedAt)
-          }));
-        })
+      github: {
+        repositories: (connectionId) => run(async () => trpc.integrations.github.repositories.query({ connectionId })),
+        branches: (connectionId, owner, repo) => run(async () => trpc.integrations.github.branches.query({ connectionId, owner, repo }))
+      },
+      google: {
+        setup: () => run(async () => trpc.integrations.google.setup.query())
       }
     },
     credentials: {
@@ -746,7 +761,7 @@ function sleep2(ms) {
 async function loginWithDeviceCode(serverUrl, options = {}) {
   const normalizedServerUrl = normalizeServerUrl(serverUrl);
   const fetchImpl = createNoRedirectFetch(options.fetch);
-  const codeRes = await fetchImpl(new URL("/api/device/code", normalizedServerUrl), {
+  const codeRes = await fetchImpl(apiEndpoint(normalizedServerUrl, "device/code"), {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ clientName: options.clientName ?? "gitterm" })
@@ -760,9 +775,9 @@ async function loginWithDeviceCode(serverUrl, options = {}) {
     intervalSeconds: codeJson.intervalSeconds,
     expiresInSeconds: codeJson.expiresInSeconds
   });
-  const deadline2 = Date.now() + codeJson.expiresInSeconds * 1000;
-  while (Date.now() < deadline2) {
-    const tokenRes = await fetchImpl(new URL("/api/device/token", normalizedServerUrl), {
+  const deadline = Date.now() + codeJson.expiresInSeconds * 1000;
+  while (Date.now() < deadline) {
+    const tokenRes = await fetchImpl(apiEndpoint(normalizedServerUrl, "device/token"), {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ deviceCode: codeJson.deviceCode })
@@ -801,10 +816,6 @@ function errorCode(code) {
     return code;
   return "SERVER_ERROR";
 }
-function toWorkspaceTrpcUrl(serverUrl) {
-  const url = new URL(serverUrl);
-  return url.pathname.endsWith("/trpc") ? serverUrl : new URL("/trpc", url).toString();
-}
 function createGittermWorkspaceClient(options = {}) {
   const detected = options.serverUrl && options.token && options.workspaceId ? null : getWorkspaceEnvironment();
   const rawServerUrl = options.serverUrl ?? detected?.serverUrl;
@@ -817,7 +828,7 @@ function createGittermWorkspaceClient(options = {}) {
   const trpc = createTRPCClient2({
     links: [
       httpBatchLink2({
-        url: toWorkspaceTrpcUrl(serverUrl),
+        url: trpcEndpoint(serverUrl),
         fetch: createNoRedirectFetch(options.fetch),
         headers: () => ({ authorization: `Bearer ${token}` })
       })
@@ -840,6 +851,7 @@ function createGittermWorkspaceClient(options = {}) {
     ports: {
       list: () => run(() => trpc.workspaceOps.listPorts.query()),
       open: (port, input) => run(() => trpc.workspaceOps.openPort.mutate({ port, ...input })),
+      setVisibility: (port, visibility) => run(() => trpc.workspaceOps.setPortVisibility.mutate({ port, visibility })),
       close: (port) => run(() => trpc.workspaceOps.closePort.mutate({ port }))
     }
   };

package/dist/transport.d.ts

@@ -1,2 +1,9 @@
 export declare function normalizeServerUrl(value: string): string;
+/**
+ * Resolve the tRPC endpoint relative to the server URL's path, so a base like
+ * `https://host/api` (path-routing proxy) maps to `https://host/api/trpc`.
+ */
+export declare function trpcEndpoint(serverUrl: string): string;
+/** Resolve a server `/api/*` route, adding `/api` only when the base doesn't already end in it. */
+export declare function apiEndpoint(serverUrl: string, route: string): string;
 export declare function createNoRedirectFetch(fetchImpl?: typeof fetch): typeof fetch;

package/dist/types.d.ts

@@ -42,8 +42,6 @@ export type Workspace = {
     } | null;
     /** Caller-owned tags supplied at create time. */
     metadata: Record<string, string>;
-    /** OpenCode HTTP API generation the workspace's agent server speaks. */
-    opencodeApi: OpencodeApi;
     /** When set, the workspace is terminated at this time regardless of activity. */
     autoTerminateAt: string | null;
     /** The caller-supplied image or E2B template this workspace runs, if any. */
@@ -63,8 +61,6 @@ export type RunRef = {
     workspaceId: string;
     id: string;
 };
-/** `v1` = OpenCode 1.x (`/event`, `/session/*`) and the default; `v2` = OpenCode 2 (`/api/*`). */
-export type OpencodeApi = "v1" | "v2";
 export type WaitOptions = {
     timeoutMs?: number;
     pollIntervalMs?: number;
@@ -223,16 +219,17 @@ export type WorkspaceCreateInput = {
     agent?: AgentKey;
     /** Provider intent. Defaults to the user's or deployment's preferred provider. */
     provider?: WorkspaceProviderSelection;
-    /** Inline Git credentials for repository validation, cloning, and runtime pull/push. */
-    /** Runtime Git/gh authentication. Takes precedence over gitIntegrationId; not auto-renewed. */
+    /** Inline Git/gh credentials for validation, cloning, and runtime operations. Not auto-renewed. */
     repositoryCredentials?: {
         username?: string;
         token: string;
     };
-    /** Dashboard GitHub App integration; runtime Git/gh credentials are renewed automatically. */
-    gitIntegrationId?: string;
-    /** Google Workload Identity Federation integration; injects keyless ADC/gcloud auth. */
-    googleCloudIntegrationId?: string;
+    /**
+     * Connection ids to attach, from `client.integrations.connections.list()`. At most one per
+     * integration. A GitHub connection renews Git/gh credentials automatically; a Google connection
+     * injects keyless ADC/gcloud auth. Cannot be combined with `repositoryCredentials` for GitHub.
+     */
+    connections?: string[];
     /** Defaults from the selected provider. */
     persistent?: boolean;
     workspaceProfile?: "standard" | "ssh-enabled";
@@ -271,28 +268,100 @@ export type WorkspaceCreateInput = {
          * webfetch: "allow" } } disables tool approval prompts in headless runs.
          */
         config?: Record<string, unknown>;
-        /**
-         * OpenCode API generation served by the image. Defaults to `v1`. Use `v2`
-         * only with an explicitly compatible image.
-         */
-        api?: OpencodeApi;
     };
 };
-export type GitHubIntegration = {
-    id: string;
+export type IntegrationKey = "github" | "google" | "gitlab" | "bitbucket" | "executor" | "mcp";
+export type IntegrationCategory = "git" | "cloud" | "mcp";
+/** An integration the admin has enabled for this deployment. */
+export type Integration = {
+    key: IntegrationKey;
+    name: string;
+    category: IntegrationCategory;
+    /** Users may create their own connections (e.g. install the GitHub App). */
+    allowPersonal: boolean;
+    /** The admin provides a deployment-wide connection with id `<key>:shared`. */
+    allowShared: boolean;
+};
+export type ConnectionKind = "personal" | "shared";
+export type ConnectionStatus = "connected" | "suspended";
+export type GitHubConnectionDetails = {
+    integration: "github";
+    mode: "app" | "pat";
     accountLogin: string;
-    accountType: string;
-    repositorySelection: string;
-    suspended: boolean;
-    connectedAt: string;
+    accountType?: string;
+    repositorySelection?: "all" | "selected";
+    installationId?: string;
+    patSuffix?: string;
 };
-export type GoogleCloudIntegration = {
+export type GoogleConnectionDetails = {
+    integration: "google";
+    projectId: string;
+    serviceAccountEmail: string;
+    workloadIdentityProvider: string;
+    setup: {
+        issuer: string;
+        audience: string;
+        principalSet: string;
+        attributeMapping: Record<string, string>;
+    };
+};
+export type ConnectionDetails = GitHubConnectionDetails | GoogleConnectionDetails;
+/**
+ * Something you can attach to a workspace via `connections: [id]`. Personal connections are
+ * owned by you; shared ones are provided by the admin and have stable ids like `github:shared`.
+ */
+export type Connection = {
     id: string;
+    integration: IntegrationKey;
+    kind: ConnectionKind;
+    name: string;
+    status: ConnectionStatus;
+    connectedAt: string;
+    details: ConnectionDetails;
+};
+export type CreateConnectionInput = {
+    integration: "google";
     name: string;
     projectId: string;
+    /** projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider> */
     workloadIdentityProvider: string;
     serviceAccountEmail: string;
-    connectedAt: string;
+} | {
+    integration: "github";
+};
+export type CreateConnectionResult = {
+    status: "connected";
+    connection: Connection;
+    /** Commands you still need to run outside GitTerm, e.g. the Google IAM binding. */
+    nextSteps: Array<{
+        label: string;
+        command: string;
+    }>;
+} | {
+    /** Finish in a browser at `authorizeUrl`, then `connections.waitFor()` the new connection. */
+    status: "pending";
+    integration: IntegrationKey;
+    authorizeUrl: string;
+};
+export type GitHubRepository = {
+    id: number;
+    name: string;
+    fullName: string;
+    owner: string;
+    private: boolean;
+    defaultBranch: string;
+    htmlUrl: string;
+    pushedAt: string | null;
+};
+export type GitHubBranch = {
+    name: string;
+    protected: boolean;
+};
+export type GoogleSetup = {
+    available: boolean;
+    /** OIDC issuer to configure on the Google workload identity provider. */
+    issuer: string | null;
+    attributeMapping: Record<string, string>;
 };
 export type WorkspaceRestartResult = {
     status: WorkspaceStatus;
@@ -547,14 +616,6 @@ export type ModelProviderInfo = {
     authType: string;
     isRecommended: boolean;
 };
-export type ModelInfo = {
-    /** Full provider/model identifier accepted by runs.create(). */
-    id: string;
-    name: string;
-    provider: string;
-    isFree: boolean;
-    isRecommended: boolean;
-};
 /** Control-plane configuration, not a live authentication check. */
 export type WorkspaceModelAccess = {
     providers: Array<{
@@ -563,8 +624,6 @@ export type WorkspaceModelAccess = {
         label: string | null;
         active: boolean;
     }>;
-    /** Known catalog models whose provider is configured, plus free models. */
-    models: ModelInfo[];
 };
 /** Explicit credential intent. Saved sources use dashboard labels, never credential IDs. */
 export type ModelCredentialSource = {
@@ -595,6 +654,8 @@ export type ModelCredential = {
     /** Select with models.providers[logicalProviderKey] = { source: "saved", label }. */
     label: string;
     keyHash: string;
+    /** Last four characters of the API key; null for OAuth credentials. */
+    keySuffix: string | null;
     isActive: boolean;
     isDefault: boolean;
     lastUsedAt: string | null;

package/dist/workspace-client.d.ts

@@ -15,9 +15,15 @@ export type WorkspaceSelf = {
     url: string | null;
     ports: WorkspacePort[];
 };
+/**
+ * `private`: only the workspace owner's signed-in GitTerm browser session can reach the URL.
+ * `public`: anyone with the URL can reach it, so it works for APIs and webhooks.
+ */
+export type WorkspacePortVisibility = "private" | "public";
 export type WorkspacePort = {
     port: number;
     name: string | null;
+    visibility: WorkspacePortVisibility;
     url: string | null;
 };
 export type WorkspaceClientOptions = Partial<WorkspaceEnvironment> & {
@@ -31,9 +37,12 @@ export type GittermWorkspaceClient = {
     };
     ports: {
         list(): Promise<WorkspacePort[]>;
+        /** Ports open as `private` unless `visibility` is set; reopening keeps the current visibility. */
         open(port: number, options?: {
             name?: string;
+            visibility?: WorkspacePortVisibility;
         }): Promise<WorkspacePort>;
+        setVisibility(port: number, visibility: WorkspacePortVisibility): Promise<WorkspacePort>;
         close(port: number): Promise<{
             port: number;
             closed: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "files": [
     "dist"
   ],