TypeScript SDK

The official TypeScript client, heyarchie. Typed, zero runtime dependencies, built on the platform fetch — Node 20+, browsers, Deno, Cloudflare Workers. The per-skill surface is generated from the canonical skill registry, so it tracks the live catalogue.

Status: in the repo, not on npm

Honest version: heyarchie 2.1.0 lives at apps/sdk-typescript/ in the archie-platform-v2 repo and has not been published to npm. When it goes public it ships as heyarchie on npm — the same name as the Python SDK. Until then, design partners install it from a repo checkout — everything below works today against that build.

Install (from the repo)

Build the package once from a checkout, then install the built directory into your project by path:

git clone https://github.com/heyarchie-ai/archie-platform-v2.git
cd archie-platform-v2/apps/sdk-typescript
npm install && npm run build

# then, from your own project:
npm install /path/to/archie-platform-v2/apps/sdk-typescript

Node 20 or newer (the client uses the global fetch). The import name is heyarchie:

import { Archie } from "heyarchie";

Constructor

Pass apiKey, or set ARCHIE_API_KEY in the environment (Node) and pass nothing. The constructor throws if neither is present. Tokens start with sk_.

import { Archie } from "heyarchie";

const archie = new Archie({
  apiKey: "sk_...",                    // or set ARCHIE_API_KEY and omit
  baseURL: "https://api.dev.arch.ie",  // note the capital URL
});

Watch the capitalisation: the key is baseURL — capital URL. Unknown config keys are currently silently ignored, so a typo like baseUrl doesn't error; the client quietly falls back to the production default https://api.heyarchie.ai. If your dev requests are mysteriously hitting production, check this first.

Typed skill methods

Every public skill is a typed method under archie.skills.generated — 65 of them, one per skill, camelCase of the slug (topic_list → topicList). They're generated from the same registry that drives the skill catalogue, and each one delegates to skills.invoke(), so the wire format is unchanged. Input interfaces (e.g. TopicCreateInput) live alongside the methods in src/resources/_generated_skills.ts.

// One typed method per skill — camelCase of the slug
const topics = await archie.skills.generated.topicList({ limit: 5 });

await archie.skills.generated.topicCreate({
  name: "FY26 audit — Acme",
  type: "client",
});

const advice = await archie.skills.generated.adviseTax({
  topic: "CGT discount on an active asset",
  jurisdiction: "AU",
});

Every method resolves to the same envelope as invoke():

interface InvokeResult<T = Record<string, unknown>> {
  readonly skill: string;
  readonly output: T;          // the skill's typed output
  readonly correlation_id: string;
}

A second argument takes per-call options — today that's idempotencyKey (replays inside 24h return the original response).

Generic invoke and the catalogue

Also available: the slug-addressed path, for when the skill name is data rather than code. skills.list() returns the live catalogue; skills.invoke() calls any skill by slug.

const catalog = await archie.skills.list();
for (const s of catalog.skills) {
  console.log(s.slug, "—", s.description);
}

const reply = await archie.skills.invoke("ask_archie", {
  query: "Under ASC 606, when is revenue recognised?",
});
console.log(reply.output);

Errors

Non-2xx responses raise typed subclasses of ArchieError, decoded from the canonical error envelope. Each carries status, requestId, and a detail object (type, code, message). 429s are retried once automatically when the response carries Retry-After.

import {
  ArchieAuthError,         // 401, invalid or revoked key
  ArchiePermissionError,   // 403, key lacks permission
  ArchieNotFoundError,     // 404
  ArchieIdempotencyError,  // 409, idempotency conflict
  ArchieRateLimitError,    // 429, check detail.retry_after_seconds
  ArchieAPIError,          // 5xx
  ArchieError,             // base class
} from "heyarchie";

try {
  await archie.skills.invoke("ask_archie", { query: "..." });
} catch (err) {
  if (err instanceof ArchieRateLimitError) {
    const wait = err.detail.retry_after_seconds ?? 60;
    // back off
  } else if (err instanceof ArchieError) {
    console.error(err.detail.code, err.detail.message, err.requestId);
  } else {
    throw err;
  }
}

Beyond skills

The client mirrors the rest of the Connect surface as resources on the same instance:

• archie.conversations: multi-turn chat
• archie.messages: convenience alias for ask_archie
• archie.workstreams: cycles, tasks, and signals
• archie.runs / archie.triggers / archie.grants: run inspection, trigger management, observer grants
• archie.sse: server-sent event streams for workstream cycles
• archie.transport: the low-level HTTP layer, if you need a raw request

Reference

Full type signatures are checked into apps/sdk-typescript in the public repo. The REST reference lists every endpoint the SDK calls under the hood, and the Python SDK is the same surface from Python.