twelveai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TwelveAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# twelveai
+
+Official Node.js SDK for [TwelveAI](https://twelveai.app) - AI infrastructure for conversational banking.
+
+Your customers chat in plain language; TwelveAI routes intent, calls your typed tools, grounds every answer in real data (never an invented figure), and gates money moves behind confirmation. This SDK runs the whole protocol in **one call**.
+
+- **Zero runtime dependencies** - Node 18+, ESM and CommonJS, full TypeScript types.
+- **One-call conversations** - continuations, tool hand-offs, and resume handled for you.
+- **Zero-credential integration** - with client-fetch tools, TwelveAI never holds a key to your API; the SDK completes handed-off requests with *your* auth, on *your* server.
+- **Money is never auto-executed** - transfers pause for your PIN/OTP flow, always.
+- **Request verification included** - prove a webhook or tool call really came from TwelveAI (HMAC or public-key JWKS).
+
+```bash
+npm install twelveai
+```
+
+## Quickstart
+
+```ts
+import { TwelveAI } from 'twelveai'
+
+const twelve = new TwelveAI({
+  apiKey: process.env.TWELVE_API_KEY!, // from https://console.twelveai.app
+  // Only needed when your tools use "My app calls it" (client-fetch): these are
+  // the headers YOUR server uses to call YOUR OWN API. TwelveAI never sees them.
+  clientAuth: { authorization: `Bearer ${process.env.MY_INTERNAL_TOKEN}` },
+})
+
+const res = await twelve.chat({
+  message: "what's my balance?",
+  customerId: 'cus_123', // your id for this end user
+})
+
+console.log(res.message) // "Your current balance is NGN 307.05."
+```
+
+Behind that one call the SDK also completed any **client-fetch hand-offs**: when a tool is configured as *"my app calls it"*, the engine returns the resolved request (method, URL, body - no credentials attached) instead of calling your API. The SDK performs it with your `clientAuth`, resumes the turn, and hands you the final grounded answer. Inspect what ran via `res.executedHandoffs`.
+
+## Multi-turn conversations
+
+Pass the previous turn's `continuation` to keep context:
+
+```ts
+let res = await twelve.chat({ message: "what's my balance?", customerId: 'cus_123' })
+
+res = await twelve.chat({
+  message: 'and my last 3 transactions?',
+  customerId: 'cus_123',
+  continuation: res.continuation!,
+})
+```
+
+## Money moves (confirmation + PIN)
+
+Money is **never** auto-executed. A transfer pauses and comes back to you:
+
+```ts
+const res = await twelve.chat({
+  message: 'send 5,000 to 0123456789 GTBank',
+  customerId: 'cus_123',
+})
+
+// res.message -> "You're about to send NGN 5,000 to JOHN DOE. Confirm?"
+const pending = res.pendingToolCalls?.[0]
+if (pending) {
+  // 1. Show res.message and collect your PIN/OTP from the user.
+  // 2. Execute the transfer on YOUR rails (KYC, limits, PIN all enforced by you).
+  const receipt = await runTransferOnMyRails(pending.arguments)
+  // 3. Resume the conversation with the result - the reply is a grounded receipt.
+  const done = await twelve.resume(res.continuation!, [
+    { id: pending.id, result: { ok: true, data: receipt } },
+  ])
+  console.log(done.message)
+}
+
+// Hosted writes pause with pendingConfirmation instead - approve with one call:
+if (res.pendingConfirmation) {
+  const done = await twelve.confirm(res.continuation!, { customerId: 'cus_123' })
+}
+```
+
+## Sandbox
+
+Add `sandbox: true` and every tool returns realistic sample data - nothing real is called or moved. Perfect for CI and demos.
+
+```ts
+await twelve.chat({ message: 'balance?', customerId: 'test-1', sandbox: true })
+```
+
+## Verifying requests FROM TwelveAI
+
+When TwelveAI calls your endpoints (hosted tools) or delivers webhooks, verify the origin. With JWKS, **no shared secret exists at all**.
+
+```ts
+import { verifySignedRequest, createJwksVerifier, verifyWebhook } from 'twelveai'
+
+// Tool auth "signed" (HMAC with your signing secret from Settings -> Request signing):
+app.post('/ai/*', (req, res, next) => {
+  const ok = verifySignedRequest(process.env.TWELVE_SIGNING_SECRET!, {
+    method: req.method,
+    path: req.originalUrl,   // path + query
+    rawBody: req.rawBody,    // capture the raw body bytes in your body parser
+    headers: req.headers,
+  })
+  if (!ok) return res.status(401).end()
+  next()
+})
+
+// Tool auth "jwks" (public key, verified against the platform's published keys;
+// each token is bound to that one request - method, URL, body hash):
+const verify = createJwksVerifier() // defaults to https://ai.twelveai.app/.well-known/jwks.json
+const v = await verify({
+  authorization: req.get('authorization')!,
+  method: req.method,
+  rawBody: req.rawBody,
+})
+if (!v.ok) return res.status(401).end()
+
+// Webhook deliveries:
+if (!verifyWebhook(process.env.TWELVE_WEBHOOK_SECRET!, req.headers)) {
+  return res.status(401).end()
+}
+```
+
+Your security team can also allowlist TwelveAI's static egress IPs: `https://ai.twelveai.app/.well-known/egress-ips`.
+
+## API reference
+
+### `new TwelveAI(options)`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` | **Required.** Your workspace API key (`sk_live_...` / `sk_test_...`). |
+| `baseUrl` | `string` | Engine URL. Default `https://ai.twelveai.app`. |
+| `clientAuth` | `object \| () => object` | Headers your server adds when executing client-fetch hand-offs against your own API. |
+| `maxHandoffRounds` | `number` | Max auto-resume rounds per `chat()`. Default `3`. |
+| `fetch` | `typeof fetch` | Custom fetch (tests, polyfills). |
+
+### `twelve.chat(input, opts?)`
+
+Sends one turn and returns the completed `ChatResponse`.
+
+Input fields: `message`, `customerId`, `continuation`, `confirmed`, `sandbox`, `channel`, `intent`, `tier`, `customerToken` (per-turn end-user token for `customer_token` tool auth), `attachments` (images / voice notes as `{ url | data, mediaType }`), `metadata`.
+
+Options: `autoExecute: false` returns the raw paused response without executing hand-offs; `onHandoff: async (call) => result` replaces the default executor.
+
+### `twelve.resume(continuation, toolResults, input?)`
+
+Resume a paused turn with results your system produced: `toolResults: [{ id, result }]`.
+
+### `twelve.confirm(continuation, input?)`
+
+Approve a `pendingConfirmation` (resends the turn with `confirmed: true`).
+
+### `ChatResponse` (the important fields)
+
+| Field | Meaning |
+| --- | --- |
+| `message` | The assistant's reply to show your user. |
+| `continuation` | Pass back next turn to keep context. |
+| `pendingConfirmation` | A hosted write awaiting approval - call `confirm()`. |
+| `pendingToolCalls` | Calls YOUR system must run (money moves). Each may carry `request` (a resolved HTTP request) for client-fetch tools. |
+| `toolCalls` | Tools already executed this turn, with their grounded results. |
+| `executedHandoffs` | Hand-offs the SDK auto-completed (observability). |
+| `escalated` / `policy` | The turn was routed for human review, and by which rule. |
+| `usage` / `billing` | Token usage and billing for the turn. |
+
+## Docs
+
+Full platform documentation - agents, policies, customer tiers, WhatsApp channel, endpoint auth options, streaming: **https://console.twelveai.app/docs**
+
+AI coding agents: a machine-readable integration guide lives at **https://console.twelveai.app/llms.txt**.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,246 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TwelveAI: () => TwelveAI,
+  createJwksVerifier: () => createJwksVerifier,
+  verifySignedRequest: () => verifySignedRequest,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://ai.twelveai.app";
+var TwelveAI = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  clientAuth;
+  maxHandoffRounds;
+  constructor(options) {
+    if (!options?.apiKey) throw new Error("TwelveAI: apiKey is required.");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.clientAuth = options.clientAuth;
+    this.maxHandoffRounds = options.maxHandoffRounds ?? 3;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("TwelveAI: global fetch is unavailable - pass options.fetch (Node 18+ has fetch built in).");
+    }
+  }
+  /**
+   * Send one chat turn and return the completed result. Read hand-offs are
+   * auto-executed (see class docs); pass `autoExecute: false` to get the raw
+   * paused response instead, or `onHandoff` to execute them yourself.
+   */
+  async chat(input, opts = {}) {
+    let res = await this.post("/v1/chat", this.chatBody(input));
+    if (opts.autoExecute === false) return res;
+    return this.completeHandoffs(res, input, opts.onHandoff);
+  }
+  /** Resume a paused turn with tool results your system produced. */
+  async resume(continuation, toolResults, input = {}) {
+    return this.post("/v1/chat", { ...this.chatBody(input), continuation, toolResults });
+  }
+  /**
+   * Approve a pending action (after your PIN/OTP step) - resends the turn with
+   * `confirmed: true` so the engine proceeds.
+   */
+  async confirm(continuation, input = {}) {
+    return this.chat({ message: "yes", ...input, continuation, confirmed: true });
+  }
+  /* ------------------------------ internals ------------------------------ */
+  chatBody(input) {
+    const body = {};
+    if (input.message !== void 0) body.message = input.message;
+    if (input.customerId !== void 0) body.customerId = input.customerId;
+    if (input.continuation) body.continuation = input.continuation;
+    if (input.confirmed !== void 0) body.confirmed = input.confirmed;
+    if (input.sandbox !== void 0) body.sandbox = input.sandbox;
+    if (input.channel) body.channel = input.channel;
+    if (input.intent) body.intent = input.intent;
+    if (input.tier) body.tier = input.tier;
+    if (input.customerToken) body.customerToken = input.customerToken;
+    if (input.attachments?.length) body.attachments = input.attachments;
+    if (input.metadata) body.metadata = input.metadata;
+    return body;
+  }
+  async post(path, body) {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+        body: JSON.stringify(body)
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        ok: res.ok && data.ok !== false,
+        message: data.message ?? null,
+        intent: data.intent ?? null,
+        toolCalls: data.toolCalls ?? [],
+        pendingConfirmation: data.pendingConfirmation ?? null,
+        pendingToolCalls: data.pendingToolCalls ?? null,
+        continuation: data.continuation ?? null,
+        ...data,
+        status: res.status,
+        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: 0,
+        message: null,
+        intent: null,
+        toolCalls: [],
+        pendingConfirmation: null,
+        pendingToolCalls: null,
+        continuation: null,
+        error: error?.message || "Could not reach the engine."
+      };
+    }
+  }
+  /**
+   * Execute client-fetch hand-offs and resume until the turn completes. Only
+   * calls that carry a resolved `request` are auto-executed - a hand-off
+   * without one (e.g. a money move awaiting your PIN flow) stops the loop and
+   * is returned to you untouched.
+   */
+  async completeHandoffs(res, input, onHandoff) {
+    const executed = [];
+    for (let round = 0; round < this.maxHandoffRounds; round++) {
+      const calls = res.pendingToolCalls ?? [];
+      if (!calls.length || !res.continuation) break;
+      if (!calls.every((c) => c.request?.url)) break;
+      const results = [];
+      for (const call of calls) {
+        const result = onHandoff ? await onHandoff(call) : await this.performHandoff(call);
+        executed.push({
+          name: call.name,
+          method: call.request.method,
+          url: call.request.url,
+          ok: result?.ok !== false
+        });
+        results.push({ id: call.id, result });
+      }
+      const next = await this.resume(res.continuation, results, input);
+      if (next.error) break;
+      res = next;
+    }
+    if (executed.length) res.executedHandoffs = executed;
+    return res;
+  }
+  /** Default hand-off executor: perform the request with your clientAuth headers. */
+  async performHandoff(call) {
+    const req = call.request;
+    try {
+      const extra = typeof this.clientAuth === "function" ? await this.clientAuth() : this.clientAuth ?? {};
+      const res = await this.fetchImpl(req.url, {
+        method: req.method,
+        headers: { "content-type": "application/json", ...req.headers ?? {}, ...extra },
+        ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {}
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) return { ok: false, error: `Endpoint returned ${res.status}` };
+      return { ok: true, data: body.data ?? body };
+    } catch (error) {
+      return { ok: false, error: error?.message || "Request failed." };
+    }
+  }
+};
+
+// src/verify.ts
+var import_node_crypto = require("crypto");
+function safeEqual(a, b) {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && (0, import_node_crypto.timingSafeEqual)(ba, bb);
+}
+function verifyWebhook(secret, headers) {
+  const got = headers["x-webhook-secret"];
+  return typeof got === "string" && !!secret && safeEqual(got, secret);
+}
+function verifySignedRequest(secret, input) {
+  const ts = header(input.headers, "x-engine-timestamp");
+  const sig = header(input.headers, "x-engine-signature");
+  if (!secret || !ts || !sig) return false;
+  const tolerance = input.toleranceSeconds ?? 300;
+  const age = Math.abs(Date.now() / 1e3 - Number(ts));
+  if (!Number.isFinite(age) || age > tolerance) return false;
+  const payload = `${ts}.${input.method.toUpperCase()}.${input.path}.${input.rawBody ?? ""}`;
+  const expected = "sha256=" + (0, import_node_crypto.createHmac)("sha256", secret).update(payload, "utf8").digest("hex");
+  return safeEqual(expected, sig);
+}
+function createJwksVerifier(options = {}) {
+  const jwksUrl = options.jwksUrl ?? "https://ai.twelveai.app/.well-known/jwks.json";
+  const cacheMs = (options.cacheSeconds ?? 300) * 1e3;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  let cache = null;
+  async function keys() {
+    if (cache && Date.now() - cache.fetchedAt < cacheMs) return cache.keys;
+    const res = await fetchImpl(jwksUrl);
+    if (!res.ok) throw new Error(`JWKS fetch failed (${res.status})`);
+    const doc = await res.json();
+    cache = { keys: doc.keys ?? [], fetchedAt: Date.now() };
+    return cache.keys;
+  }
+  return async function verify(input) {
+    try {
+      const jwt = (input.authorization ?? "").replace(/^Bearer\s+/i, "").trim();
+      const parts = jwt.split(".");
+      if (parts.length !== 3) return { ok: false, reason: "malformed token" };
+      const [h, p, s] = parts;
+      const head = JSON.parse(Buffer.from(h, "base64url").toString());
+      if (head.alg !== "ES256") return { ok: false, reason: `unsupported alg ${head.alg}` };
+      const jwk = (await keys()).find((k) => k.kid === head.kid);
+      if (!jwk) return { ok: false, reason: "unknown key id" };
+      const pub = (0, import_node_crypto.createPublicKey)({ key: jwk, format: "jwk" });
+      const v = (0, import_node_crypto.createVerify)("SHA256");
+      v.update(`${h}.${p}`);
+      if (!v.verify({ key: pub, dsaEncoding: "ieee-p1363" }, Buffer.from(s, "base64url"))) {
+        return { ok: false, reason: "bad signature" };
+      }
+      const claims = JSON.parse(Buffer.from(p, "base64url").toString());
+      const now = Math.floor(Date.now() / 1e3);
+      if (typeof claims.exp !== "number" || claims.exp < now) return { ok: false, reason: "expired" };
+      if (typeof claims.htm === "string" && claims.htm !== input.method.toUpperCase()) return { ok: false, reason: "method mismatch" };
+      if (input.url && typeof claims.htu === "string" && claims.htu !== input.url) return { ok: false, reason: "url mismatch" };
+      if (input.rawBody !== void 0 && typeof claims.bh === "string") {
+        const bh = (0, import_node_crypto.createHash)("sha256").update(input.rawBody ?? "", "utf8").digest("hex");
+        if (bh !== claims.bh) return { ok: false, reason: "body hash mismatch" };
+      }
+      return { ok: true, claims };
+    } catch (error) {
+      return { ok: false, reason: error?.message || "verification failed" };
+    }
+  };
+}
+function header(headers, name) {
+  const v = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0] ?? null;
+  return typeof v === "string" ? v : null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TwelveAI,
+  createJwksVerifier,
+  verifySignedRequest,
+  verifyWebhook
+});

package/dist/index.d.cts

@@ -0,0 +1,230 @@
+/** Shared request/response types for the TwelveAI chat API. */
+interface TwelveAIOptions {
+    /** Your workspace API key (sk_live_... / sk_test_...). */
+    apiKey: string;
+    /** Engine base URL. Defaults to the hosted platform. */
+    baseUrl?: string;
+    /**
+     * Auth your server adds when the SDK performs client-fetch hand-offs against
+     * YOUR OWN API (the engine hands the resolved request back without any
+     * credentials). Static headers, or a function returning them per request.
+     */
+    clientAuth?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Custom fetch implementation (tests, polyfills). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Max auto-resume rounds for client-fetch hand-offs per chat() call. Default 3. */
+    maxHandoffRounds?: number;
+}
+interface Attachment {
+    /** Public URL, or a data: URL. */
+    url?: string;
+    /** Base64 content (alternative to url). */
+    data?: string;
+    mediaType?: string;
+    /** A WhatsApp media id, if the engine should fetch it via your connected WhatsApp. */
+    whatsappMediaId?: string;
+}
+interface ChatInput {
+    /** The end user's message. Optional when resuming or sending only attachments. */
+    message?: string;
+    /** Your id for this end user (alias: userId). Required for customer-scoped agents. */
+    customerId?: string;
+    /** Continue an existing conversation with the token from the previous turn. */
+    continuation?: string;
+    /** The user approved a pending action (PIN/OTP collected on your side). */
+    confirmed?: boolean;
+    /** Sandbox: tools return sample data; nothing real is called or moved. */
+    sandbox?: boolean;
+    channel?: string;
+    /** Force a specific agent instead of routing. */
+    intent?: string;
+    /** Customer tier to sync for this turn's caps. */
+    tier?: string;
+    /**
+     * Short-lived end-user session token, forwarded verbatim on tool bindings
+     * with auth type 'customer_token'. Never stored by the engine.
+     */
+    customerToken?: string;
+    /** Images / voice notes attached to this turn. */
+    attachments?: Attachment[];
+    metadata?: Record<string, unknown>;
+}
+interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+    result: unknown;
+}
+interface HandoffRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Record<string, unknown>;
+}
+interface PendingToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Client-fetch hand-off: the resolved request your server should perform. */
+    request?: HandoffRequest;
+}
+interface ToolResult {
+    id: string;
+    result: unknown;
+}
+interface ChatResponse {
+    ok: boolean;
+    sandbox?: boolean;
+    /** The assistant's reply to show the user. */
+    message: string | null;
+    intent: string | null;
+    toolCalls: ToolCall[];
+    /** A write awaiting the user's confirmation (resend with confirmed: true). */
+    pendingConfirmation: {
+        tool: string;
+        arguments: Record<string, unknown>;
+    } | null;
+    /**
+     * Client-executed tool calls YOUR system must run. With auto-execution on
+     * (the default), read hand-offs are already completed by the SDK; anything
+     * left here is yours to handle (typically a money move awaiting PIN).
+     */
+    pendingToolCalls: PendingToolCall[] | null;
+    /** Pass this back on the next turn to continue the conversation. */
+    continuation: string | null;
+    escalated?: boolean;
+    policy?: string | null;
+    autonomy?: string | null;
+    fee?: {
+        feeNgn: number;
+        amountNgn: number;
+        totalNgn: number;
+    } | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    billing?: Record<string, unknown>;
+    latencyMs?: number;
+    metadata?: Record<string, unknown>;
+    error?: string;
+    /** HTTP status of the underlying call. */
+    status: number;
+    /** Hand-offs the SDK auto-executed to complete this turn (for observability). */
+    executedHandoffs?: Array<{
+        name: string;
+        method: string;
+        url: string;
+        ok: boolean;
+    }>;
+}
+/**
+ * Executor for one client-fetch hand-off. Return the tool result the engine
+ * resumes with. The default executor performs `call.request` with your
+ * `clientAuth` headers and returns `{ ok, data }`.
+ */
+type HandoffExecutor = (call: PendingToolCall) => Promise<unknown>;
+
+/**
+ * The TwelveAI client. One call does the whole conversation protocol:
+ *
+ *   const twelve = new TwelveAI({ apiKey: process.env.TWELVE_API_KEY! })
+ *   const res = await twelve.chat({ message: "what's my balance?", customerId: 'cus_123' })
+ *   console.log(res.message)
+ *
+ * Client-fetch hand-offs (tools configured as "my app calls it") are executed
+ * automatically against your own API - the engine never holds your credentials;
+ * you supply them once via `clientAuth` and the SDK completes the loop. Money
+ * moves are never auto-executed: they surface in `pendingToolCalls` /
+ * `pendingConfirmation` for your PIN flow, then you call `confirm()` or
+ * `resume()`.
+ */
+declare class TwelveAI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly clientAuth;
+    private readonly maxHandoffRounds;
+    constructor(options: TwelveAIOptions);
+    /**
+     * Send one chat turn and return the completed result. Read hand-offs are
+     * auto-executed (see class docs); pass `autoExecute: false` to get the raw
+     * paused response instead, or `onHandoff` to execute them yourself.
+     */
+    chat(input: ChatInput, opts?: {
+        autoExecute?: boolean;
+        onHandoff?: HandoffExecutor;
+    }): Promise<ChatResponse>;
+    /** Resume a paused turn with tool results your system produced. */
+    resume(continuation: string, toolResults: ToolResult[], input?: Pick<ChatInput, 'customerId' | 'channel' | 'sandbox' | 'customerToken'>): Promise<ChatResponse>;
+    /**
+     * Approve a pending action (after your PIN/OTP step) - resends the turn with
+     * `confirmed: true` so the engine proceeds.
+     */
+    confirm(continuation: string, input?: Omit<ChatInput, 'continuation' | 'confirmed'>): Promise<ChatResponse>;
+    private chatBody;
+    private post;
+    /**
+     * Execute client-fetch hand-offs and resume until the turn completes. Only
+     * calls that carry a resolved `request` are auto-executed - a hand-off
+     * without one (e.g. a money move awaiting your PIN flow) stops the loop and
+     * is returned to you untouched.
+     */
+    private completeHandoffs;
+    /** Default hand-off executor: perform the request with your clientAuth headers. */
+    private performHandoff;
+}
+
+/** Verify a TwelveAI webhook delivery: the x-webhook-secret header must match your secret. */
+declare function verifyWebhook(secret: string, headers: Record<string, string | string[] | undefined>): boolean;
+interface SignedRequestInput {
+    /** HTTP method of the incoming request. */
+    method: string;
+    /** Path + query as received, e.g. '/ai/balance?x=1' (Express: req.originalUrl). */
+    path: string;
+    /** The RAW request body string ('' for none). Must be the exact bytes received. */
+    rawBody: string;
+    /** Incoming headers (x-engine-timestamp / x-engine-signature). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Allowed clock skew in seconds. Default 300. */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify an HMAC-signed tool call (auth type 'signed'): recomputes
+ * HMAC-SHA256(secret, `${ts}.${METHOD}.${path}.${rawBody}`) and compares it to
+ * the X-Engine-Signature header inside the timestamp tolerance window.
+ */
+declare function verifySignedRequest(secret: string, input: SignedRequestInput): boolean;
+interface JwksVerifierOptions {
+    /** JWKS document URL. Defaults to the hosted platform's. */
+    jwksUrl?: string;
+    /** How long to cache the JWKS, in seconds. Default 300. */
+    cacheSeconds?: number;
+    fetch?: typeof globalThis.fetch;
+}
+interface JwtRequestInput {
+    /** The Authorization header value ('Bearer <jwt>') or the raw JWT. */
+    authorization: string;
+    /** HTTP method of the incoming request (checked against the htm claim). */
+    method: string;
+    /** Full URL as the engine called it (checked against the htu claim). Optional. */
+    url?: string;
+    /** The RAW request body ('' for none) - checked against the bh (body hash) claim. */
+    rawBody?: string;
+}
+/**
+ * Build a verifier for JWKS-signed tool calls (auth type 'jwks'). Fetches and
+ * caches the platform's public keys; each call verifies the ES256 signature,
+ * the expiry, and that the token is bound to THIS request (method, URL, body
+ * hash) - so a captured token cannot be replayed against another request.
+ *
+ *   const verify = createJwksVerifier()
+ *   const v = await verify({ authorization: req.get('authorization'), method: req.method, rawBody })
+ *   if (!v.ok) return res.status(401).end()
+ */
+declare function createJwksVerifier(options?: JwksVerifierOptions): (input: JwtRequestInput) => Promise<{
+    ok: boolean;
+    reason?: string;
+    claims?: Record<string, unknown>;
+}>;
+
+export { type Attachment, type ChatInput, type ChatResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+/** Shared request/response types for the TwelveAI chat API. */
+interface TwelveAIOptions {
+    /** Your workspace API key (sk_live_... / sk_test_...). */
+    apiKey: string;
+    /** Engine base URL. Defaults to the hosted platform. */
+    baseUrl?: string;
+    /**
+     * Auth your server adds when the SDK performs client-fetch hand-offs against
+     * YOUR OWN API (the engine hands the resolved request back without any
+     * credentials). Static headers, or a function returning them per request.
+     */
+    clientAuth?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Custom fetch implementation (tests, polyfills). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Max auto-resume rounds for client-fetch hand-offs per chat() call. Default 3. */
+    maxHandoffRounds?: number;
+}
+interface Attachment {
+    /** Public URL, or a data: URL. */
+    url?: string;
+    /** Base64 content (alternative to url). */
+    data?: string;
+    mediaType?: string;
+    /** A WhatsApp media id, if the engine should fetch it via your connected WhatsApp. */
+    whatsappMediaId?: string;
+}
+interface ChatInput {
+    /** The end user's message. Optional when resuming or sending only attachments. */
+    message?: string;
+    /** Your id for this end user (alias: userId). Required for customer-scoped agents. */
+    customerId?: string;
+    /** Continue an existing conversation with the token from the previous turn. */
+    continuation?: string;
+    /** The user approved a pending action (PIN/OTP collected on your side). */
+    confirmed?: boolean;
+    /** Sandbox: tools return sample data; nothing real is called or moved. */
+    sandbox?: boolean;
+    channel?: string;
+    /** Force a specific agent instead of routing. */
+    intent?: string;
+    /** Customer tier to sync for this turn's caps. */
+    tier?: string;
+    /**
+     * Short-lived end-user session token, forwarded verbatim on tool bindings
+     * with auth type 'customer_token'. Never stored by the engine.
+     */
+    customerToken?: string;
+    /** Images / voice notes attached to this turn. */
+    attachments?: Attachment[];
+    metadata?: Record<string, unknown>;
+}
+interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+    result: unknown;
+}
+interface HandoffRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Record<string, unknown>;
+}
+interface PendingToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Client-fetch hand-off: the resolved request your server should perform. */
+    request?: HandoffRequest;
+}
+interface ToolResult {
+    id: string;
+    result: unknown;
+}
+interface ChatResponse {
+    ok: boolean;
+    sandbox?: boolean;
+    /** The assistant's reply to show the user. */
+    message: string | null;
+    intent: string | null;
+    toolCalls: ToolCall[];
+    /** A write awaiting the user's confirmation (resend with confirmed: true). */
+    pendingConfirmation: {
+        tool: string;
+        arguments: Record<string, unknown>;
+    } | null;
+    /**
+     * Client-executed tool calls YOUR system must run. With auto-execution on
+     * (the default), read hand-offs are already completed by the SDK; anything
+     * left here is yours to handle (typically a money move awaiting PIN).
+     */
+    pendingToolCalls: PendingToolCall[] | null;
+    /** Pass this back on the next turn to continue the conversation. */
+    continuation: string | null;
+    escalated?: boolean;
+    policy?: string | null;
+    autonomy?: string | null;
+    fee?: {
+        feeNgn: number;
+        amountNgn: number;
+        totalNgn: number;
+    } | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    billing?: Record<string, unknown>;
+    latencyMs?: number;
+    metadata?: Record<string, unknown>;
+    error?: string;
+    /** HTTP status of the underlying call. */
+    status: number;
+    /** Hand-offs the SDK auto-executed to complete this turn (for observability). */
+    executedHandoffs?: Array<{
+        name: string;
+        method: string;
+        url: string;
+        ok: boolean;
+    }>;
+}
+/**
+ * Executor for one client-fetch hand-off. Return the tool result the engine
+ * resumes with. The default executor performs `call.request` with your
+ * `clientAuth` headers and returns `{ ok, data }`.
+ */
+type HandoffExecutor = (call: PendingToolCall) => Promise<unknown>;
+
+/**
+ * The TwelveAI client. One call does the whole conversation protocol:
+ *
+ *   const twelve = new TwelveAI({ apiKey: process.env.TWELVE_API_KEY! })
+ *   const res = await twelve.chat({ message: "what's my balance?", customerId: 'cus_123' })
+ *   console.log(res.message)
+ *
+ * Client-fetch hand-offs (tools configured as "my app calls it") are executed
+ * automatically against your own API - the engine never holds your credentials;
+ * you supply them once via `clientAuth` and the SDK completes the loop. Money
+ * moves are never auto-executed: they surface in `pendingToolCalls` /
+ * `pendingConfirmation` for your PIN flow, then you call `confirm()` or
+ * `resume()`.
+ */
+declare class TwelveAI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly clientAuth;
+    private readonly maxHandoffRounds;
+    constructor(options: TwelveAIOptions);
+    /**
+     * Send one chat turn and return the completed result. Read hand-offs are
+     * auto-executed (see class docs); pass `autoExecute: false` to get the raw
+     * paused response instead, or `onHandoff` to execute them yourself.
+     */
+    chat(input: ChatInput, opts?: {
+        autoExecute?: boolean;
+        onHandoff?: HandoffExecutor;
+    }): Promise<ChatResponse>;
+    /** Resume a paused turn with tool results your system produced. */
+    resume(continuation: string, toolResults: ToolResult[], input?: Pick<ChatInput, 'customerId' | 'channel' | 'sandbox' | 'customerToken'>): Promise<ChatResponse>;
+    /**
+     * Approve a pending action (after your PIN/OTP step) - resends the turn with
+     * `confirmed: true` so the engine proceeds.
+     */
+    confirm(continuation: string, input?: Omit<ChatInput, 'continuation' | 'confirmed'>): Promise<ChatResponse>;
+    private chatBody;
+    private post;
+    /**
+     * Execute client-fetch hand-offs and resume until the turn completes. Only
+     * calls that carry a resolved `request` are auto-executed - a hand-off
+     * without one (e.g. a money move awaiting your PIN flow) stops the loop and
+     * is returned to you untouched.
+     */
+    private completeHandoffs;
+    /** Default hand-off executor: perform the request with your clientAuth headers. */
+    private performHandoff;
+}
+
+/** Verify a TwelveAI webhook delivery: the x-webhook-secret header must match your secret. */
+declare function verifyWebhook(secret: string, headers: Record<string, string | string[] | undefined>): boolean;
+interface SignedRequestInput {
+    /** HTTP method of the incoming request. */
+    method: string;
+    /** Path + query as received, e.g. '/ai/balance?x=1' (Express: req.originalUrl). */
+    path: string;
+    /** The RAW request body string ('' for none). Must be the exact bytes received. */
+    rawBody: string;
+    /** Incoming headers (x-engine-timestamp / x-engine-signature). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Allowed clock skew in seconds. Default 300. */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify an HMAC-signed tool call (auth type 'signed'): recomputes
+ * HMAC-SHA256(secret, `${ts}.${METHOD}.${path}.${rawBody}`) and compares it to
+ * the X-Engine-Signature header inside the timestamp tolerance window.
+ */
+declare function verifySignedRequest(secret: string, input: SignedRequestInput): boolean;
+interface JwksVerifierOptions {
+    /** JWKS document URL. Defaults to the hosted platform's. */
+    jwksUrl?: string;
+    /** How long to cache the JWKS, in seconds. Default 300. */
+    cacheSeconds?: number;
+    fetch?: typeof globalThis.fetch;
+}
+interface JwtRequestInput {
+    /** The Authorization header value ('Bearer <jwt>') or the raw JWT. */
+    authorization: string;
+    /** HTTP method of the incoming request (checked against the htm claim). */
+    method: string;
+    /** Full URL as the engine called it (checked against the htu claim). Optional. */
+    url?: string;
+    /** The RAW request body ('' for none) - checked against the bh (body hash) claim. */
+    rawBody?: string;
+}
+/**
+ * Build a verifier for JWKS-signed tool calls (auth type 'jwks'). Fetches and
+ * caches the platform's public keys; each call verifies the ES256 signature,
+ * the expiry, and that the token is bound to THIS request (method, URL, body
+ * hash) - so a captured token cannot be replayed against another request.
+ *
+ *   const verify = createJwksVerifier()
+ *   const v = await verify({ authorization: req.get('authorization'), method: req.method, rawBody })
+ *   if (!v.ok) return res.status(401).end()
+ */
+declare function createJwksVerifier(options?: JwksVerifierOptions): (input: JwtRequestInput) => Promise<{
+    ok: boolean;
+    reason?: string;
+    claims?: Record<string, unknown>;
+}>;
+
+export { type Attachment, type ChatInput, type ChatResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };

package/dist/index.js

@@ -0,0 +1,216 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://ai.twelveai.app";
+var TwelveAI = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  clientAuth;
+  maxHandoffRounds;
+  constructor(options) {
+    if (!options?.apiKey) throw new Error("TwelveAI: apiKey is required.");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.clientAuth = options.clientAuth;
+    this.maxHandoffRounds = options.maxHandoffRounds ?? 3;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("TwelveAI: global fetch is unavailable - pass options.fetch (Node 18+ has fetch built in).");
+    }
+  }
+  /**
+   * Send one chat turn and return the completed result. Read hand-offs are
+   * auto-executed (see class docs); pass `autoExecute: false` to get the raw
+   * paused response instead, or `onHandoff` to execute them yourself.
+   */
+  async chat(input, opts = {}) {
+    let res = await this.post("/v1/chat", this.chatBody(input));
+    if (opts.autoExecute === false) return res;
+    return this.completeHandoffs(res, input, opts.onHandoff);
+  }
+  /** Resume a paused turn with tool results your system produced. */
+  async resume(continuation, toolResults, input = {}) {
+    return this.post("/v1/chat", { ...this.chatBody(input), continuation, toolResults });
+  }
+  /**
+   * Approve a pending action (after your PIN/OTP step) - resends the turn with
+   * `confirmed: true` so the engine proceeds.
+   */
+  async confirm(continuation, input = {}) {
+    return this.chat({ message: "yes", ...input, continuation, confirmed: true });
+  }
+  /* ------------------------------ internals ------------------------------ */
+  chatBody(input) {
+    const body = {};
+    if (input.message !== void 0) body.message = input.message;
+    if (input.customerId !== void 0) body.customerId = input.customerId;
+    if (input.continuation) body.continuation = input.continuation;
+    if (input.confirmed !== void 0) body.confirmed = input.confirmed;
+    if (input.sandbox !== void 0) body.sandbox = input.sandbox;
+    if (input.channel) body.channel = input.channel;
+    if (input.intent) body.intent = input.intent;
+    if (input.tier) body.tier = input.tier;
+    if (input.customerToken) body.customerToken = input.customerToken;
+    if (input.attachments?.length) body.attachments = input.attachments;
+    if (input.metadata) body.metadata = input.metadata;
+    return body;
+  }
+  async post(path, body) {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+        body: JSON.stringify(body)
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        ok: res.ok && data.ok !== false,
+        message: data.message ?? null,
+        intent: data.intent ?? null,
+        toolCalls: data.toolCalls ?? [],
+        pendingConfirmation: data.pendingConfirmation ?? null,
+        pendingToolCalls: data.pendingToolCalls ?? null,
+        continuation: data.continuation ?? null,
+        ...data,
+        status: res.status,
+        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: 0,
+        message: null,
+        intent: null,
+        toolCalls: [],
+        pendingConfirmation: null,
+        pendingToolCalls: null,
+        continuation: null,
+        error: error?.message || "Could not reach the engine."
+      };
+    }
+  }
+  /**
+   * Execute client-fetch hand-offs and resume until the turn completes. Only
+   * calls that carry a resolved `request` are auto-executed - a hand-off
+   * without one (e.g. a money move awaiting your PIN flow) stops the loop and
+   * is returned to you untouched.
+   */
+  async completeHandoffs(res, input, onHandoff) {
+    const executed = [];
+    for (let round = 0; round < this.maxHandoffRounds; round++) {
+      const calls = res.pendingToolCalls ?? [];
+      if (!calls.length || !res.continuation) break;
+      if (!calls.every((c) => c.request?.url)) break;
+      const results = [];
+      for (const call of calls) {
+        const result = onHandoff ? await onHandoff(call) : await this.performHandoff(call);
+        executed.push({
+          name: call.name,
+          method: call.request.method,
+          url: call.request.url,
+          ok: result?.ok !== false
+        });
+        results.push({ id: call.id, result });
+      }
+      const next = await this.resume(res.continuation, results, input);
+      if (next.error) break;
+      res = next;
+    }
+    if (executed.length) res.executedHandoffs = executed;
+    return res;
+  }
+  /** Default hand-off executor: perform the request with your clientAuth headers. */
+  async performHandoff(call) {
+    const req = call.request;
+    try {
+      const extra = typeof this.clientAuth === "function" ? await this.clientAuth() : this.clientAuth ?? {};
+      const res = await this.fetchImpl(req.url, {
+        method: req.method,
+        headers: { "content-type": "application/json", ...req.headers ?? {}, ...extra },
+        ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {}
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) return { ok: false, error: `Endpoint returned ${res.status}` };
+      return { ok: true, data: body.data ?? body };
+    } catch (error) {
+      return { ok: false, error: error?.message || "Request failed." };
+    }
+  }
+};
+
+// src/verify.ts
+import { createHash, createHmac, createPublicKey, createVerify, timingSafeEqual } from "crypto";
+function safeEqual(a, b) {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+function verifyWebhook(secret, headers) {
+  const got = headers["x-webhook-secret"];
+  return typeof got === "string" && !!secret && safeEqual(got, secret);
+}
+function verifySignedRequest(secret, input) {
+  const ts = header(input.headers, "x-engine-timestamp");
+  const sig = header(input.headers, "x-engine-signature");
+  if (!secret || !ts || !sig) return false;
+  const tolerance = input.toleranceSeconds ?? 300;
+  const age = Math.abs(Date.now() / 1e3 - Number(ts));
+  if (!Number.isFinite(age) || age > tolerance) return false;
+  const payload = `${ts}.${input.method.toUpperCase()}.${input.path}.${input.rawBody ?? ""}`;
+  const expected = "sha256=" + createHmac("sha256", secret).update(payload, "utf8").digest("hex");
+  return safeEqual(expected, sig);
+}
+function createJwksVerifier(options = {}) {
+  const jwksUrl = options.jwksUrl ?? "https://ai.twelveai.app/.well-known/jwks.json";
+  const cacheMs = (options.cacheSeconds ?? 300) * 1e3;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  let cache = null;
+  async function keys() {
+    if (cache && Date.now() - cache.fetchedAt < cacheMs) return cache.keys;
+    const res = await fetchImpl(jwksUrl);
+    if (!res.ok) throw new Error(`JWKS fetch failed (${res.status})`);
+    const doc = await res.json();
+    cache = { keys: doc.keys ?? [], fetchedAt: Date.now() };
+    return cache.keys;
+  }
+  return async function verify(input) {
+    try {
+      const jwt = (input.authorization ?? "").replace(/^Bearer\s+/i, "").trim();
+      const parts = jwt.split(".");
+      if (parts.length !== 3) return { ok: false, reason: "malformed token" };
+      const [h, p, s] = parts;
+      const head = JSON.parse(Buffer.from(h, "base64url").toString());
+      if (head.alg !== "ES256") return { ok: false, reason: `unsupported alg ${head.alg}` };
+      const jwk = (await keys()).find((k) => k.kid === head.kid);
+      if (!jwk) return { ok: false, reason: "unknown key id" };
+      const pub = createPublicKey({ key: jwk, format: "jwk" });
+      const v = createVerify("SHA256");
+      v.update(`${h}.${p}`);
+      if (!v.verify({ key: pub, dsaEncoding: "ieee-p1363" }, Buffer.from(s, "base64url"))) {
+        return { ok: false, reason: "bad signature" };
+      }
+      const claims = JSON.parse(Buffer.from(p, "base64url").toString());
+      const now = Math.floor(Date.now() / 1e3);
+      if (typeof claims.exp !== "number" || claims.exp < now) return { ok: false, reason: "expired" };
+      if (typeof claims.htm === "string" && claims.htm !== input.method.toUpperCase()) return { ok: false, reason: "method mismatch" };
+      if (input.url && typeof claims.htu === "string" && claims.htu !== input.url) return { ok: false, reason: "url mismatch" };
+      if (input.rawBody !== void 0 && typeof claims.bh === "string") {
+        const bh = createHash("sha256").update(input.rawBody ?? "", "utf8").digest("hex");
+        if (bh !== claims.bh) return { ok: false, reason: "body hash mismatch" };
+      }
+      return { ok: true, claims };
+    } catch (error) {
+      return { ok: false, reason: error?.message || "verification failed" };
+    }
+  };
+}
+function header(headers, name) {
+  const v = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0] ?? null;
+  return typeof v === "string" ? v : null;
+}
+export {
+  TwelveAI,
+  createJwksVerifier,
+  verifySignedRequest,
+  verifyWebhook
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "twelveai",
+  "version": "0.1.0",
+  "description": "Official SDK for TwelveAI - AI infrastructure for conversational banking. One call runs the whole chat protocol: routing, grounded tool calls, client-fetch hand-offs, confirmations, and request verification.",
+  "license": "MIT",
+  "author": "TwelveAI",
+  "homepage": "https://github.com/Laozofficial/twelveai-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Laozofficial/twelveai-sdk.git"
+  },
+  "keywords": [
+    "twelveai",
+    "conversational-banking",
+    "fintech",
+    "ai",
+    "agent",
+    "banking",
+    "chatbot"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/Laozofficial/twelveai-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}