Error Handling & Types

Handling `APIError`

Every non-2xx response from the control plane throws an APIError. status is the HTTP status, message is the server’s error field (or the status text when there is none), and data is the parsed response body. What each status means is listed in Error Codes.

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

const client = new QumoClient({
  baseUrl: "https://api.qumo-deploy.com",
  token: process.env.QUMO_TOKEN,
});

try {
  await client.projects.list({ organization_id: "your-organization-id" });
} catch (err: unknown) {
  if (err instanceof APIError) {
    console.error(`HTTP Status: ${err.status}`);
    console.error(`Server Message: ${err.message}`);
    console.error(`Error Payload:`, err.data);

    if (err.status === 401) {
      console.error("Authentication failed: check the Bearer token (QUMO_TOKEN).");
    }
  } else {
    throw err;
  }
}

IAM Role Identifiers

Role ids appear in Session.role, OrganizationMembership.role_id, Invitation.role_id and IAM bindings. Compare them against IAM_ROLE_IDS (or the IAMRoleID type) rather than strings like "admin":

import { IAM_ROLE_IDS, type IAMRoleID } from "@qumo-deploy/sdk";

// Built-in IAM roles:
// - "roles/platform.admin"
// - "roles/project.viewer"
// - "roles/project.editor"
// - "roles/project.admin"
// - "roles/organization.admin"

const organizationAdmin: IAMRoleID = "roles/organization.admin";

function isOrganizationAdmin(roleId: string): boolean {
  return roleId === organizationAdmin;
}

console.log(IAM_ROLE_IDS.includes("roles/project.viewer")); // true

Exported Type Interfaces

The SDK exports types for the control plane’s entities, among them:

Type	Description
`User`	Authenticated user profile (`id`, `email`, `name`, `github_login`).
`Session`	A console session: the user, the active organization (`org_id`, `org_name`) and its IAM `role`.
`OrganizationMembership`	An organization the caller belongs to (`organization_id`, `organization_name`, `role_id`).
`Organization`	Organization entity (`id`, `name`, `slug`, `billing_email`).
`Project`	Project unit (`id`, `name`, `slug`, `organization_id`, `environment`).
`SigningKey`	A registered Ed25519 signing key your app signs relay credentials with (`kid`, `name`, `prefix`, `state`).
`Identity`	Machine identity (`id`, `name`, `project_id`).
`IdentityToken`	A newly created identity token; `value` is shown once.
`AuditEntry`	One audit log entry (`actor_type`, `action`, `resource`, `created_at`).