@roamhq/sdk

Official TypeScript SDK for the Roam API.

npm install @roamhq/sdk

Requires Node.js 18+ (the client uses the built-in fetch). If you compile from TypeScript source you need TypeScript 5.7+. The package has no runtime dependencies.

import { RoamClient } from "@roamhq/sdk";

const client = new RoamClient({ token: process.env.ROAM_TOKEN! });

await client.chat.post({
  groupId: "88bebce7-6cbb-4666-96f9-5c02d73e6661",
  text: "Build completed successfully!",
});

Full usage — pagination, retries, error handling, version pinning — is in the SDK guide. The API reference documents every endpoint.

Verifying webhooks

import { verifyWebhook } from "@roamhq/sdk/webhooks";

// req.body must be the RAW bytes — express.raw({ type: "application/json" })
const event = verifyWebhook(req.body.toString("utf8"), req.headers, process.env.ROAM_WEBHOOK_SECRET!);

Throws on any failure; treat a throw as a 401. Pass the signing secret exactly as Roam issued it, whsec_ prefix included.

This is the one part of the SDK that is hand-written rather than generated. See webhooks/verify.ts for why.

This repository is mostly generated

Everything under src/ is generated from the Roam OpenAPI specification by Fern. Do not edit src/ by hand — the next regeneration will overwrite it.

A change to the spec opens or updates a single long-lived pull request here titled "Regenerate SDK from OpenAPI spec". A human reviews the diff, picks the semantic-version bump, and merges.

Everything outside src/ is hand-maintained and protected by .fernignore:

| Path | What it is | | --- | --- | | package.json, tsconfig*.json | Package manifest and build. Fern's local-file-system output is source files only, so this repo owns all of it. | | webhooks/ | Hand-written signature verification, shipped as @roamhq/sdk/webhooks. Outside src/ on purpose — a regeneration cannot delete it. | | tests/ | Hand-written contract tests. See tests/README.md. | | .github/ | CI and publishing. | | README.md, LICENSE | This file, and the license. |

If you find a wrong type or a missing field, it is almost always a bug in the OpenAPI spec rather than in hand-written code — fixing it there fixes the docs site and every SDK at once. Report it via Roam Support or [email protected].

Building

npm ci
npm run build      # dual ESM + CJS into dist/
npm test           # contract tests
npm run typecheck  # src/ and tests/, no emit

The package ships both ESM and CommonJS. dist/cjs/package.json carries a { "type": "commonjs" } marker because the root manifest declares "type": "module"; without it Node would read the CommonJS build as ESM and require("@roamhq/sdk") would fail.

Releasing

RELEASING.md has the full procedure — the one-time npm trusted-publisher setup, the per-release steps, and troubleshooting.

Briefly: bump version in package.json, merge, then push a matching vX.Y.Z tag. publish.yml publishes to npm with provenance via OIDC. No token is stored anywhere.

License

MIT — see LICENSE.