twelveai 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,203 +1,4 @@
-/** 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>;
-interface ClassifyResponse {
-    ok: boolean;
-    /** The winning agent intent, or null when nothing matched. */
-    intent: string | null;
-    label: string | null;
-    /** Deterministic confidence in [0, 0.95]; 0 = no match. */
-    confidence: number;
-    alternatives: Array<{
-        intent: string;
-        label: string;
-    }>;
-    /** Cheap extracted entities: amount, account_number, phone (when present). */
-    entities: Record<string, unknown>;
-    status: number;
-    error?: string;
-}
-
-/**
- * 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>;
-    /**
-     * Level-0 integration: classify a message WITHOUT running the conversation.
-     * Returns the intent, a deterministic confidence score, and cheap extracted
-     * entities (amount / account number / phone) - you keep your existing flows
-     * and make the call yourself. Free: no tools run, nothing is stored.
-     */
-    classify(input: {
-        message: string;
-    }): Promise<ClassifyResponse>;
-    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;
-}
+export { A as Attachment, B as BindToolInput, C as ChatInput, a as ChatResponse, b as ClassifyResponse, c as CreateAgentInput, d as CreateToolInput, H as HandoffExecutor, e as HandoffRequest, M as Manage, f as ManageResult, P as PendingToolCall, g as ToolCall, h as ToolResult, T as TwelveAI, i as TwelveAIOptions, j as buildManage } from './client-C5vzks2N.js';
 
 /** 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;
@@ -252,4 +53,4 @@ declare function createJwksVerifier(options?: JwksVerifierOptions): (input: JwtR
     claims?: Record<string, unknown>;
 }>;
 
-export { type Attachment, type ChatInput, type ChatResponse, type ClassifyResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };
+export { type JwksVerifierOptions, type JwtRequestInput, type SignedRequestInput, createJwksVerifier, verifySignedRequest, verifyWebhook };

package/dist/index.js

@@ -1,169 +1,7 @@
-// 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 });
-  }
-  /**
-   * Level-0 integration: classify a message WITHOUT running the conversation.
-   * Returns the intent, a deterministic confidence score, and cheap extracted
-   * entities (amount / account number / phone) - you keep your existing flows
-   * and make the call yourself. Free: no tools run, nothing is stored.
-   */
-  async classify(input) {
-    try {
-      const res = await this.fetchImpl(`${this.baseUrl}/v1/classify`, {
-        method: "POST",
-        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
-        body: JSON.stringify({ message: input.message })
-      });
-      const data = await res.json().catch(() => ({}));
-      return {
-        ok: res.ok && data.ok !== false,
-        intent: data.intent ?? null,
-        label: data.label ?? null,
-        confidence: data.confidence ?? 0,
-        alternatives: data.alternatives ?? [],
-        entities: data.entities ?? {},
-        status: res.status,
-        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
-      };
-    } catch (error) {
-      return { ok: false, intent: null, label: null, confidence: 0, alternatives: [], entities: {}, status: 0, error: error?.message || "Could not reach the engine." };
-    }
-  }
-  /* ------------------------------ 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." };
-    }
-  }
-};
+import {
+  TwelveAI,
+  buildManage
+} from "./chunk-6RZKLIGP.js";
 
 // src/verify.ts
 import { createHash, createHmac, createPublicKey, createVerify, timingSafeEqual } from "crypto";
@@ -238,6 +76,7 @@ function header(headers, name) {
 }
 export {
   TwelveAI,
+  buildManage,
   createJwksVerifier,
   verifySignedRequest,
   verifyWebhook

package/dist/mcp.d.cts

@@ -5,7 +5,7 @@
  * tool-call contract, classify messages, and test chats in the sandbox while it
  * writes your integration.
  *
- *   npx twelveai-mcp            # stdio transport
+ *   npx -y -p twelveai twelveai-mcp     # stdio transport
  *
  * Config (env):
  *   TWELVE_API_KEY   your workspace key - required for manifest/classify/chat

package/dist/mcp.d.ts

@@ -5,7 +5,7 @@
  * tool-call contract, classify messages, and test chats in the sandbox while it
  * writes your integration.
  *
- *   npx twelveai-mcp            # stdio transport
+ *   npx -y -p twelveai twelveai-mcp     # stdio transport
  *
  * Config (env):
  *   TWELVE_API_KEY   your workspace key - required for manifest/classify/chat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twelveai",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -38,7 +38,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/mcp.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/mcp.ts src/cli.ts --format esm,cjs --dts --clean",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
@@ -56,6 +56,7 @@
     "access": "public"
   },
   "bin": {
-    "twelveai-mcp": "./dist/mcp.js"
+    "twelveai-mcp": "./dist/mcp.js",
+    "twelveai": "./dist/cli.js"
   }
 }