@taleseal/sdk

Client SDK for taleseal. Build the tale of an agent run locally — beats, decisions, widgets, metrics — then publish it as a single POST at the end. No server state until you publish. 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 { openTale } from "@taleseal/sdk";

const draft = openTale({
  agent: "revenue-watch",
  title: "Weekly revenue check",
  trigger: { source: "cron", event: "monday 09:00" },
  // 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
});

draft
  .beat({ title: "Pulled the numbers", prose: "Fetched last week's figures from Stripe." })
  .widget({ kind: "stat_tiles", tiles: [{ label: "MRR", value: "£12.4k", delta: "+3.1%", tone: "good" }] })
  .decision({ title: "Skip the churn deep-dive", state: "set_aside", why: "Churn flat week on week." })
  .evidence({ kind: "command", command: "revenue report --week", output: "MRR £12.4k (+3.1%)", exitCode: 0 })
  .provenance({ tool: "revenue-watch", extent: "fully_ai", attestation: { by: "goran" } })
  .metrics({ durationMs: 4200, model: "claude-fable-5" })
  .outcome("MRR up 3.1% week on week; nothing needs a human.", { status: "succeeded", destination: "#revenue" });

const { url } = await draft.publish();

An outcome is required (format v2) — build() and publish() throw without one, and status may honestly be "partial" or "failed". draft.build() returns the validated tale without publishing (handy in tests), and emitWidgetTool(draft) wraps widget emission as a framework-agnostic tool for the AI SDK, Mastra and similar. The schema itself lives in @taleseal/core.

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.