@taleseal/sdk

Client SDK for taleseal. Compose a tale — a page of typed blocks (words, tables, charts, diagrams, code, images) — validate it locally with the exact schema the API runs, then draft, edit and publish it at a stable link the reader needs no account to open. Sealing Claude Code or Codex sessions instead? You want the taleseal CLI — no integration needed.

Install

bun add @taleseal/sdk   # or: npm install @taleseal/sdk

Usage

import { applyTaleOps, composeTale, draftTale, getTaleOutline, publishTale } from "@taleseal/sdk";

// Compose locally — the same zod schema the API runs, so what validates here publishes there.
const tale = composeTale({
  title: "Weekly revenue check",
  standfirst: "MRR up 3.1% week on week; nothing needs a human.",
  sender: { name: "revenue-watch", org: "Acme" },
  blocks: [
    { kind: "lead", text: "MRR is up 3.1% week on week." },
    { kind: "stat_tiles", tiles: [{ label: "MRR", value: "£12.4k", delta: "+3.1%", tone: "good" }] },
    { kind: "prose", markdown: "Churn is flat, so the deep-dive is parked until it moves." },
    { kind: "evidence", items: [{ kind: "web", name: "Stripe revenue report", url: "https://dashboard.stripe.com" }] },
  ],
});

// Create it as a DRAFT at its final URL — the page carries a DRAFT banner until publish.
// apiKey defaults to TALESEAL_API_KEY, then the key `npx taleseal login` stores;
// baseUrl to TALESEAL_URL, then the stored config, then https://taleseal.com.
const { id, url } = await draftTale(tale);

// Edit the draft block by block, atomically, under optimistic concurrency.
const { draftSeq } = await getTaleOutline(id);
await applyTaleOps(id, { baseRevision: draftSeq, ops: [/* … */] });

// A human reviews at `url`, then the same link serves the published revision.
await publishTale(id);

The full surface: draftTale / publishTale / reviseTale / retractTale run the lifecycle, getTale / getTaleOutline / getTaleBlocks read a draft, applyTaleOps edits it id-addressed and atomically (a stale base is a conflict outcome, never a throw), uploadImage mints the reference an image block carries, and composeTale validates without touching the network. The schema itself lives in @taleseal/core.

Publishing without an account

// No credential at all. The page is LIVE the moment the POST lands — no draft step,
// immutable — and hard-deleted after 24 hours unless a human opens the once-shown
// claimUrl and keeps it. Claiming is free and transfers the page to their account.
const anon = await draftTale(tale, { anonymous: true });
console.log(anon.url, anon.claimUrl, anon.claimExpiresAt);

While unclaimed the page renders with no branding, an "Unverified" sender and outbound links as plain text. Anonymity is an explicit opt-in: a missing key still throws, it never silently falls back — and nothing else has an anonymous form (an anonymous tale cannot be revised, retracted or edited, and cannot carry images).

Authentication

Credentials resolve in the same order on every taleseal surface: the explicit option, then the environment (TALESEAL_API_KEY / TALESEAL_URL), then the config file npx taleseal login writes ($XDG_CONFIG_HOME/taleseal/config.json, falling back to ~/.config, mode 0600). On a development machine, one npx taleseal login — browser approval, signing up on the way if needed — is all the setup the SDK needs. On CI, mint a key in the dashboard and set TALESEAL_API_KEY. For the one-shot no-account case, draftTale(tale, { anonymous: true }) needs no credential at all (see above).