@gitterm/sdk 0.0.1

package/README.md

@@ -0,0 +1,102 @@
+# @gitterm/sdk
+
+TypeScript SDK for the [GitTerm](https://gitterm.dev) API. Used by the `gitterm` CLI,
+the OpenCode plugin, and any integration that needs to manage GitTerm workspaces with
+a user API token.
+
+## Install
+
+```sh
+bun add @gitterm/sdk
+# or
+npm install @gitterm/sdk
+```
+
+## 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
+
+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.
+
+```ts
+const client = createGittermClient();
+const status = await client.auth.status();
+```
+
+### API
+
+```ts
+client.auth.status();                 // -> { userId, email, name, plan, authMethod }
+client.workspaces.list(options?);     // -> { workspaces, pagination }
+client.workspaces.get(workspaceId);
+client.workspaces.pause(workspaceId);
+client.workspaces.restart(workspaceId);
+client.workspaces.terminate(workspaceId);
+client.workspaces.create(input);      // needs agentTypeId + cloudProviderId, see catalog
+client.catalog.agentTypes();
+client.catalog.cloudProviders();
+```
+
+### Errors
+
+Every method throws `GittermError` with a stable `code`:
+
+```ts
+import { GittermError } from "@gitterm/sdk";
+
+try {
+  await client.workspaces.get(id);
+} catch (error) {
+  if (error instanceof GittermError && error.code === "NOT_LOGGED_IN") {
+    // "Not logged in. Run: gitterm login"
+  }
+}
+```
+
+Codes: `NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`,
+`SERVER_ERROR`, `NETWORK`.
+
+### Obtaining a token programmatically
+
+The device-code flow used by `gitterm login` is exposed for integrations:
+
+```ts
+import { loginWithDeviceCode, saveConfig, DEFAULT_GITTERM_SERVER_URL } from "@gitterm/sdk";
+
+const { token } = await loginWithDeviceCode(DEFAULT_GITTERM_SERVER_URL, {
+  onCode: ({ verificationUri, userCode }) => {
+    console.log(`Visit ${verificationUri} and enter ${userCode}`);
+  },
+});
+
+await saveConfig({
+  serverUrl: DEFAULT_GITTERM_SERVER_URL,
+  token,
+  createdAt: Date.now(),
+});
+```
+
+Device-code logins produce the same revocable `gt_...` API token as the dashboard;
+they appear in **Settings → Account → API tokens** and can be revoked there.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 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 }>;

package/dist/index.js

@@ -0,0 +1,339 @@
+// src/client.ts
+import { createTRPCClient, httpBatchLink, TRPCClientError } from "@trpc/client";
+
+// src/config.ts
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_GITTERM_SERVER_URL = "https://api.gitterm.dev";
+function getConfigPath(configPath) {
+  return configPath ?? join(homedir(), ".config", "gitterm", "cli.json");
+}
+async function ensureConfigDir(path) {
+  await mkdir(dirname(path), { recursive: true });
+}
+function parseConfig(text) {
+  const parsed = JSON.parse(text);
+  if (!parsed.token || !parsed.serverUrl)
+    return null;
+  return {
+    serverUrl: parsed.serverUrl,
+    token: parsed.token,
+    createdAt: parsed.createdAt ?? Date.now()
+  };
+}
+async function loadConfig(configPath) {
+  try {
+    const text = await readFile(getConfigPath(configPath), "utf-8");
+    return parseConfig(text);
+  } catch {
+    return null;
+  }
+}
+function loadConfigSync(configPath) {
+  try {
+    const text = readFileSync(getConfigPath(configPath), "utf-8");
+    return parseConfig(text);
+  } catch {
+    return null;
+  }
+}
+async function saveConfig(config, configPath) {
+  const path = getConfigPath(configPath);
+  await ensureConfigDir(path);
+  await writeFile(path, JSON.stringify(config, null, 2), "utf-8");
+}
+async function deleteConfig(configPath) {
+  try {
+    await unlink(getConfigPath(configPath));
+  } catch {}
+}
+
+// src/errors.ts
+class GittermError extends Error {
+  code;
+  cause;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "GittermError";
+    this.code = code;
+    this.cause = options.cause;
+  }
+}
+
+// src/client.ts
+function envValue(name) {
+  const value = typeof process !== "undefined" ? process.env[name] : undefined;
+  return value && value.trim() ? value : undefined;
+}
+function resolveCredentials(options) {
+  const config = !options.serverUrl || !options.token ? loadConfigSync(options.configPath) : null;
+  const serverUrl = options.serverUrl ?? envValue("GITTERM_SERVER_URL") ?? config?.serverUrl;
+  const token = options.token ?? envValue("GITTERM_API_TOKEN") ?? config?.token;
+  if (!serverUrl || !token) {
+    throw new GittermError("NOT_LOGGED_IN", "Not logged in. Run: gitterm login");
+  }
+  return { serverUrl, token };
+}
+function toTrpcUrl(serverUrl) {
+  return new URL("/trpc", serverUrl).toString();
+}
+function toIso(value) {
+  if (!value)
+    return null;
+  return value instanceof Date ? value.toISOString() : value;
+}
+function normalizeBaseCommit(value) {
+  if (value == null)
+    return null;
+  const trimmed = value.trim();
+  if (!trimmed)
+    return null;
+  return /^[0-9a-f]{40}([0-9a-f]{24})?$/i.test(trimmed) ? trimmed.toLowerCase() : trimmed;
+}
+function normalizeWorkspace(workspace) {
+  if (!workspace)
+    return null;
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    status: workspace.status,
+    repositoryUrl: workspace.repositoryUrl,
+    repositoryBranch: workspace.repositoryBranch,
+    baseCommit: normalizeBaseCommit(workspace.baseCommit ?? workspace.repositoryBaseCommit ?? null),
+    checkoutRef: workspace.checkoutRef ?? workspace.repositoryCheckoutRef ?? null,
+    domain: workspace.domain,
+    subdomain: workspace.subdomain,
+    persistent: workspace.persistent,
+    hostingType: workspace.hostingType,
+    serverOnly: workspace.serverOnly,
+    workspaceProfile: workspace.workspaceProfile,
+    cloudProviderId: workspace.cloudProviderId,
+    agentType: workspace.image?.agentType ? {
+      id: workspace.image.agentType.id,
+      name: workspace.image.agentType.name,
+      description: workspace.image.agentType.description
+    } : null,
+    image: workspace.image ? {
+      id: workspace.image.id,
+      name: workspace.image.name,
+      imageId: workspace.image.imageId
+    } : null,
+    startedAt: toIso(workspace.startedAt),
+    stoppedAt: toIso(workspace.stoppedAt),
+    terminatedAt: toIso(workspace.terminatedAt),
+    lastActiveAt: toIso(workspace.lastActiveAt),
+    updatedAt: toIso(workspace.updatedAt)
+  };
+}
+function normalizeRuntime(runtime) {
+  return {
+    workspaceId: runtime.workspaceId,
+    status: runtime.status,
+    url: runtime.url,
+    headers: runtime.headers,
+    password: runtime.password,
+    directory: runtime.directory,
+    repo: runtime.repo,
+    branch: runtime.branch,
+    baseCommit: normalizeBaseCommit(runtime.baseCommit),
+    checkoutRef: runtime.checkoutRef,
+    persistent: runtime.persistent,
+    recoverable: runtime.recoverable,
+    providerKey: runtime.providerKey
+  };
+}
+function mapTrpcCode(code) {
+  switch (code) {
+    case "UNAUTHORIZED":
+      return "UNAUTHORIZED";
+    case "NOT_FOUND":
+      return "NOT_FOUND";
+    case "FORBIDDEN":
+      return "FORBIDDEN";
+    case "BAD_REQUEST":
+      return "BAD_REQUEST";
+    default:
+      return "SERVER_ERROR";
+  }
+}
+async function runWithServer(serverUrl, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof GittermError)
+      throw error;
+    if (error instanceof TRPCClientError) {
+      const trpcCode = error.data?.code;
+      if (!error.data) {
+        throw new GittermError("NETWORK", `Could not reach the GitTerm server at ${serverUrl}`, {
+          cause: error
+        });
+      }
+      const code = mapTrpcCode(trpcCode);
+      throw new GittermError(code, code === "UNAUTHORIZED" ? "Not logged in or token expired. Run: gitterm login" : error.message, { cause: error });
+    }
+    throw new GittermError("NETWORK", error instanceof Error ? error.message : "Network request failed", { cause: error });
+  }
+}
+function createGittermClient(options = {}) {
+  const credentials = resolveCredentials(options);
+  const trpc = createTRPCClient({
+    links: [
+      httpBatchLink({
+        url: toTrpcUrl(credentials.serverUrl),
+        fetch: options.fetch,
+        headers: () => ({ authorization: `Bearer ${credentials.token}` })
+      })
+    ]
+  });
+  const run = (operation) => runWithServer(credentials.serverUrl, operation);
+  const createWorkspace = (input) => run(async () => {
+    const result = await trpc.workspace.createWorkspace.mutate(input);
+    const workspace = normalizeWorkspace(result.workspace);
+    if (!workspace)
+      throw new GittermError("SERVER_ERROR", "Workspace creation failed");
+    const runtime = result.runtime ? normalizeRuntime(result.runtime) : {
+      workspaceId: workspace.id,
+      status: workspace.status,
+      url: null,
+      directory: "/workspace",
+      repo: workspace.repositoryUrl,
+      branch: workspace.repositoryBranch,
+      baseCommit: workspace.baseCommit,
+      checkoutRef: workspace.checkoutRef,
+      persistent: workspace.persistent,
+      recoverable: workspace.status !== "terminated",
+      providerKey: null
+    };
+    return { workspace, runtime };
+  });
+  return {
+    serverUrl: credentials.serverUrl,
+    auth: {
+      status: () => run(async () => {
+        const me = await trpc.agent.me.query();
+        return {
+          loggedIn: true,
+          userId: me.userId,
+          email: me.email,
+          name: me.name,
+          plan: me.plan ?? "free",
+          authMethod: me.authMethod
+        };
+      })
+    },
+    workspaces: {
+      list: (input) => run(async () => {
+        const result = await trpc.workspace.listWorkspaces.query(input);
+        return {
+          workspaces: result.workspaces.map((workspace) => normalizeWorkspace(workspace)),
+          pagination: result.pagination
+        };
+      }),
+      get: (workspaceId) => run(async () => {
+        const result = await trpc.workspace.getWorkspace.query({ workspaceId });
+        const workspace = normalizeWorkspace(result.workspace);
+        if (!workspace)
+          throw new GittermError("NOT_FOUND", "Workspace not found");
+        return workspace;
+      }),
+      getRuntimeAccess: (workspaceId) => run(async () => {
+        const result = await trpc.workspace.getRuntimeAccess.query({ workspaceId });
+        return normalizeRuntime(result);
+      }),
+      ensureRunning: (workspaceId, options2) => run(async () => {
+        const result = await trpc.workspace.ensureRunning.mutate({
+          workspaceId,
+          timeoutMs: options2?.timeoutMs,
+          pollIntervalMs: options2?.pollIntervalMs
+        });
+        const workspace = normalizeWorkspace(result.workspace);
+        if (!workspace)
+          throw new GittermError("SERVER_ERROR", "ensureRunning failed");
+        return {
+          workspace,
+          runtime: normalizeRuntime(result.runtime)
+        };
+      }),
+      pause: (workspaceId) => run(async () => {
+        const result = await trpc.workspace.pauseWorkspace.mutate({ workspaceId });
+        return { durationMinutes: result.durationMinutes };
+      }),
+      restart: (workspaceId) => run(async () => {
+        const result = await trpc.workspace.restartWorkspace.mutate({ workspaceId });
+        return { status: result.status };
+      }),
+      terminate: (workspaceId) => run(async () => {
+        const result = await trpc.workspace.deleteWorkspace.mutate({ workspaceId });
+        return {
+          workspace: normalizeWorkspace(result.workspace),
+          cleanupInBackground: result.cleanupInBackground
+        };
+      }),
+      create: createWorkspace,
+      createSandbox: createWorkspace
+    },
+    catalog: {
+      agentTypes: (input) => run(async () => {
+        const result = await trpc.workspace.listAgentTypes.query(input);
+        return result.agentTypes;
+      }),
+      cloudProviders: (input) => run(async () => {
+        const result = await trpc.workspace.listCloudProviders.query(input);
+        return result.cloudProviders;
+      })
+    }
+  };
+}
+// src/device-login.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function loginWithDeviceCode(serverUrl, options = {}) {
+  const fetchImpl = options.fetch ?? fetch;
+  const codeRes = await fetchImpl(new URL("/api/device/code", serverUrl), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ clientName: options.clientName ?? "gitterm" })
+  });
+  if (!codeRes.ok)
+    throw new Error(`Failed to start device login: ${codeRes.status}`);
+  const codeJson = await codeRes.json();
+  await options.onCode?.({
+    userCode: codeJson.userCode,
+    verificationUri: codeJson.verificationUri,
+    intervalSeconds: codeJson.intervalSeconds,
+    expiresInSeconds: codeJson.expiresInSeconds
+  });
+  const deadline = Date.now() + codeJson.expiresInSeconds * 1000;
+  while (Date.now() < deadline) {
+    const tokenRes = await fetchImpl(new URL("/api/device/token", serverUrl), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceCode: codeJson.deviceCode })
+    });
+    if (tokenRes.ok) {
+      const tokenJson = await tokenRes.json();
+      return { token: tokenJson.accessToken };
+    }
+    if (tokenRes.status !== 428) {
+      const errText = await tokenRes.text().catch(() => "");
+      throw new Error(`Login failed: ${tokenRes.status} ${errText}`);
+    }
+    await sleep(Math.max(1, codeJson.intervalSeconds) * 1000);
+  }
+  throw new Error("Device code expired; try again.");
+}
+export {
+  saveConfig,
+  loginWithDeviceCode,
+  loadConfigSync,
+  loadConfig,
+  getConfigPath,
+  deleteConfig,
+  createGittermClient,
+  GittermError,
+  DEFAULT_GITTERM_SERVER_URL
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gitterm/sdk",
+  "version": "0.0.1",
+  "files": [
+    "dist",
+    "src/index.d.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @trpc/client && cp src/index.d.ts dist/index.d.ts",
+    "prepublishOnly": "bun run check-types && bun run build",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@trpc/client": "^11.8.1"
+  },
+  "devDependencies": {
+    "@gitterm/api": "workspace:*",
+    "@gitterm/config": "workspace:*",
+    "@trpc/server": "catalog:",
+    "@types/bun": "^1.2.6",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 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 }>;