TypeScript SDK Quickstart

The official @qumo-deploy/sdk package provides complete, strongly-typed programmatic control over the Qumo Deploy control plane.

Installation

Install the package using your favorite package manager:

npm install @qumo-deploy/sdk

pnpm add @qumo-deploy/sdk

yarn add @qumo-deploy/sdk

bun add @qumo-deploy/sdk

{
  "imports": {
    "@qumo-deploy/sdk": "npm:@qumo-deploy/sdk@^0.2.0"
  }
}

Client Initialization

Construct an instance of QumoClient by supplying your base URL and credentials:

import { QumoClient } from "@qumo-deploy/sdk";

// Initialize with an API key
const client = new QumoClient({
  baseUrl: process.env.QUMO_BASE_URL || "https://api.qumo.dev",
  apiKey: process.env.QUMO_API_KEY, // e.g. "ak_live_..."
});

Authentication Modes

The client supports three distinct authentication contexts:

API Key (apiKey): Best for server-to-server microservices and background daemons. Sends the X-API-Key header.
Bearer Token (token): Best for CI/CD runners, personal access tokens (PAT), or headless service tokens. Sends Authorization: Bearer <token>.
Session Cookie + CSRF (csrfToken): Best for web console applications running in browsers where session cookies (qumo_session) are present. Pass a callback function returning the CSRF token:

const browserClient = new QumoClient({
  baseUrl: "https://api.qumo.dev",
  csrfToken: () => getCookie("qumo_csrf"),
});

First API Call: Fetching Identity & Projects

import { QumoClient } from "@qumo-deploy/sdk";

async function main() {
  const client = new QumoClient({
    baseUrl: "https://api.qumo.dev",
    token: process.env.QUMO_TOKEN,
  });

  // Verify authentication identity
  const session = await client.auth.getSession();
  console.log(`Authenticated as: ${session.user.email} (${session.org_name})`);

  // List all projects in the tenant
  const projects = await client.projects.list();
  console.log(`Found ${projects.length} projects:`);
  for (const p of projects) {
    console.log(` - ${p.name} [${p.environment}] (ID: ${p.id})`);
  }
}

main().catch(console.error);