TypeScript SDK

@heela/sdk is a thin, zero-dependency TypeScript client for the Hee control plane. Works in Node.js 18+, Deno, Bun, and Cloudflare Workers.

Install

npm install @heela/sdk
# or
yarn add @heela/sdk
# or
bun add @heela/sdk

Configure

import { HeeClient } from "@heela/sdk";

const hee = new HeeClient({
  token: process.env.HEE_API_TOKEN!,
  // optional:
  // baseUrl: "https://api.hee.la",  // default
  // timeoutMs: 5000,                 // default
});

Register a domain

const domain = await hee.domains.register({
  hostname: "docs.customer.com",
  metadata: {
    workspaceId: "ws_abc123",
    theme: "dark",
  },
});

console.log(domain);
// {
//   hostname: "docs.customer.com",
//   projectSlug: "acme-saas",
//   verified: false,
//   verifiedAt: null,
//   createdAt: "2026-04-20T21:47:38.000Z",
//   metadata: { workspaceId: "ws_abc123", theme: "dark" }
// }

Registering the same hostname twice is idempotent — the second call returns the existing record. If you pass new metadata, it’s merged in.

List domains

const domains = await hee.domains.list();
// Returns all domains owned by this token's project.

Remove a domain

await hee.domains.remove("docs.customer.com");
// Soft delete. Cert retained for 24h in case of re-add.

Error handling

All errors are instances of HeeError:

import { HeeError } from "@heela/sdk";

try {
  await hee.domains.register({ hostname: "docs.customer.com" });
} catch (err) {
  if (err instanceof HeeError) {
    if (err.status === 409) {
      // hostname is claimed by another project
    } else if (err.status === 402) {
      // project is over its plan limit
    } else {
      // network / server issue
    }
  }
}

Status	Meaning
200	Success
204	Success (no body, e.g. DELETE)
400	Invalid hostname format
401	Invalid or revoked token
402	Over plan limit
403	Token not authorized for this project
404	Hostname not found (on remove)
409	Hostname claimed by another project
5xx	Control plane outage — retry with backoff

Timeouts & retries

The SDK does not retry automatically — that’s your caller’s responsibility. Recommended pattern:

async function registerWithRetry(input: { hostname: string }) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await hee.domains.register(input);
    } catch (err) {
      if (err instanceof HeeError && err.status < 500) throw err; // don't retry 4xx
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
    }
  }
  throw new Error("Hee registration failed after 3 attempts");
}

Custom fetch / testing

Pass your own fetch implementation for testing or non-standard runtimes:

import { HeeClient } from "@heela/sdk";

const hee = new HeeClient({
  token: "hee_test_...",
  fetch: customFetch, // e.g. undici, node-fetch, mocked fetch
});

Source

github.com/shekhardtu/heela/tree/main/packages/sdk