heyarchie

The official TypeScript client for Archie Connect. Connect Claude, Cursor, your code, or your Slack to a senior accountant.

The Python SDK + CLI ships under the same name — pip install heyarchie. Same brand, one client shape across both ecosystems.

Install

npm install heyarchie
# or
pnpm add heyarchie
# or
bun add heyarchie

Requires Node 20+, or any modern runtime with a global fetch (browsers, Deno, Cloudflare Workers, edge functions).

Quickstart

import { Archie } from "heyarchie";

const archie = new Archie({ apiKey: "sk_..." });
// Or set ARCHIE_API_KEY in the environment and pass nothing.

// Registry-driven invocation — always reflects the live catalogue.
const reply = await archie.skills.invoke("ask_archie", {
  query: "What does ASC 710-10-25-2 require for vacation accrual?",
});
console.log(reply.output);

API surface

archie.skills

Registry-driven. Every skill the workspace exposes is reachable here.

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

const reply = await archie.skills.invoke("compare_standards", {
  document_id: "doc_...",
  standards: ["AASB16", "FRS102"],
});

archie.messages

Convenience alias for the most-used skill, ask_archie.

const reply = await archie.messages.create({
  query: "Walk me through ASC 842 lease modifications.",
});
console.log(reply.output.answer);
for (const cite of reply.output.citations ?? []) {
  console.log(cite.standard, cite.section);
}

Errors

The client raises typed exceptions per the canonical error envelope.

import { ArchieRateLimitError, ArchieError } from "heyarchie";

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

The client automatically retries 429 once when Retry-After ≤ 60 seconds.

Configuration

new Archie({
  apiKey: "sk_...",                      // or ARCHIE_API_KEY
  baseURL: "https://api.heyarchie.ai",   // override for alpha / dev
  apiVersion: "2026-04-24",              // pin the API revision
  timeoutMs: 60_000,                     // per-request
  fetch: customFetch,                    // for tests, edge runtimes
});

Idempotency

Pass idempotencyKey on any invoke call. Replays inside 24 hours return the original response.

await archie.skills.invoke(
  "create_journal_entry",
  { /* ... */ },
  { idempotencyKey: "uniq-2026-04-25-q1-bas-001" },
);

Edge runtimes

Cloudflare Workers, Vercel Edge, Deno Deploy: works out of the box. The SDK relies only on fetch, URL, AbortController, and setTimeout — all standard runtime globals.

Talk to a human

[email protected]. We read it.