twelveai 0.3.0 → 0.4.0

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import {
+  TwelveAI
+} from "./chunk-6RZKLIGP.js";
+
+// src/cli.ts
+import { readFileSync } from "fs";
+var HELP = `twelveai <command> [args]
+
+Conversation
+  chat "<message>" [--customer <id>] [--sandbox] [--reasoning off|auto|always]
+  classify "<message>" [--reasoning off|auto|always]
+
+Manage (everything the console does)
+  agents    list | create --file <agent.json> | enable <intent> | disable <intent> | delete <intent>
+  tools     list | create --file <tool.json> | bind <name> --file <binding.json> | test <name>
+  plugins   list | install <id> | uninstall <id>
+  customers list | set <externalId> [--tier <tier>] [--name <name>] [--email <email>]
+  settings  get | set --file <settings.json>
+  billing   (show balance) | topup <amountNgn>
+  usage     (summary) | requests [--limit <n>] | request <id>
+  manifest  (the per-agent tool-call contract)
+
+Auth: set TWELVE_API_KEY (and optionally TWELVE_BASE_URL).`;
+function flag(args, name) {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : void 0;
+}
+var has = (args, name) => args.includes(`--${name}`);
+var positional = (args) => args.filter((a, i) => !a.startsWith("--") && !(i > 0 && args[i - 1].startsWith("--")));
+async function runCli(argv, deps) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    deps.log(HELP);
+    return 0;
+  }
+  const apiKey = deps.env.TWELVE_API_KEY;
+  if (!apiKey) {
+    deps.error("Set TWELVE_API_KEY to use the CLI (find yours in the console under Settings).");
+    return 1;
+  }
+  const twelve = deps.client ?? new TwelveAI({ apiKey, baseUrl: deps.env.TWELVE_BASE_URL });
+  const m = twelve.manage;
+  const json = (v) => deps.log(JSON.stringify(v, null, 2));
+  const loadJson = (label) => {
+    const file = flag(rest, "file");
+    if (!file) {
+      deps.error(`--file <${label}.json> is required.`);
+      return null;
+    }
+    try {
+      return JSON.parse(deps.readFile(file));
+    } catch (e) {
+      deps.error(`Could not read ${file}: ${e.message}`);
+      return null;
+    }
+  };
+  const done = (r) => r.ok ? 0 : 1;
+  const pos = positional(rest);
+  const sub = pos[0];
+  switch (cmd) {
+    case "chat": {
+      if (!sub) return deps.error('Usage: twelveai chat "<message>"'), 1;
+      const r = await twelve.chat({
+        message: sub,
+        customerId: flag(rest, "customer"),
+        sandbox: has(rest, "sandbox") || void 0,
+        reasoning: flag(rest, "reasoning")
+      });
+      json(r);
+      return done(r);
+    }
+    case "classify": {
+      if (!sub) return deps.error('Usage: twelveai classify "<message>"'), 1;
+      const r = await twelve.classify({ message: sub, reasoning: flag(rest, "reasoning") });
+      json(r);
+      return done(r);
+    }
+    case "agents": {
+      if (sub === "list" || !sub) return json(await m.agents.list()), 0;
+      if (sub === "create") {
+        const b = loadJson("agent");
+        if (!b) return 1;
+        const r = await m.agents.create(b);
+        json(r);
+        return done(r);
+      }
+      if (sub === "enable" && pos[1]) {
+        const r = await m.agents.enable(pos[1]);
+        json(r);
+        return done(r);
+      }
+      if (sub === "disable" && pos[1]) {
+        const r = await m.agents.disable(pos[1]);
+        json(r);
+        return done(r);
+      }
+      if (sub === "delete" && pos[1]) {
+        const r = await m.agents.delete(pos[1]);
+        json(r);
+        return done(r);
+      }
+      deps.error("Usage: twelveai agents list | create --file a.json | enable <intent> | disable <intent> | delete <intent>");
+      return 1;
+    }
+    case "tools": {
+      if (sub === "list" || !sub) return json(await m.tools.list()), 0;
+      if (sub === "create") {
+        const b = loadJson("tool");
+        if (!b) return 1;
+        const r = await m.tools.create(b);
+        json(r);
+        return done(r);
+      }
+      if (sub === "bind" && pos[1]) {
+        const b = loadJson("binding");
+        if (!b) return 1;
+        const r = await m.tools.bind(pos[1], b);
+        json(r);
+        return done(r);
+      }
+      if (sub === "test" && pos[1]) {
+        const r = await m.tools.test(pos[1]);
+        json(r);
+        return done(r);
+      }
+      deps.error("Usage: twelveai tools list | create --file t.json | bind <name> --file b.json | test <name>");
+      return 1;
+    }
+    case "plugins": {
+      if (sub === "list" || !sub) return json(await m.plugins.list()), 0;
+      if (sub === "install" && pos[1]) {
+        const r = await m.plugins.install(pos[1]);
+        json(r);
+        return done(r);
+      }
+      if (sub === "uninstall" && pos[1]) {
+        const r = await m.plugins.uninstall(pos[1]);
+        json(r);
+        return done(r);
+      }
+      deps.error("Usage: twelveai plugins list | install <id> | uninstall <id>");
+      return 1;
+    }
+    case "customers": {
+      if (sub === "list" || !sub) return json(await m.customers.list({ limit: Number(flag(rest, "limit")) || 100 })), 0;
+      if (sub === "set" && pos[1]) {
+        const r = await m.customers.upsert({ externalId: pos[1], tier: flag(rest, "tier"), name: flag(rest, "name"), email: flag(rest, "email") });
+        json(r);
+        return done(r);
+      }
+      deps.error("Usage: twelveai customers list | set <externalId> --tier <tier>");
+      return 1;
+    }
+    case "settings": {
+      if (sub === "get" || !sub) return json(await m.settings.get()), 0;
+      if (sub === "set") {
+        const b = loadJson("settings");
+        if (!b) return 1;
+        const r = await m.settings.update(b);
+        json(r);
+        return done(r);
+      }
+      deps.error("Usage: twelveai settings get | set --file settings.json");
+      return 1;
+    }
+    case "billing":
+      return json(await m.billing.get()), 0;
+    case "topup": {
+      const amount = Number(sub);
+      if (!amount || amount < 5e3) return deps.error("Usage: twelveai topup <amountNgn>  (minimum 5000)"), 1;
+      const r = await m.billing.topup(amount, flag(rest, "email"));
+      json(r);
+      return done(r);
+    }
+    case "usage":
+      return json(await m.usage.summary()), 0;
+    case "requests":
+      return json(await m.usage.events(Number(flag(rest, "limit")) || 20)), 0;
+    case "request": {
+      if (!sub) return deps.error("Usage: twelveai request <id>"), 1;
+      return json(await m.usage.event(sub)), 0;
+    }
+    case "manifest":
+      return json(await m.manifest()), 0;
+    default:
+      deps.error(`Unknown command "${cmd}".
+
+${HELP}`);
+      return 1;
+  }
+}
+var isMain = process.argv[1]?.endsWith("cli.js") || process.argv[1]?.endsWith("twelveai");
+if (isMain) {
+  runCli(process.argv.slice(2), {
+    env: process.env,
+    log: (s) => console.log(s),
+    error: (s) => console.error(s),
+    readFile: (p) => readFileSync(p, "utf8")
+  }).then((code) => process.exit(code));
+}
+export {
+  runCli
+};

package/dist/client-C5vzks2N.d.cts

@@ -0,0 +1,325 @@
+/** 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;
+    /** Routing reasoning: 'off' | 'auto' (default) | 'always'. */
+    reasoning?: 'off' | 'auto' | 'always';
+    /**
+     * 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;
+        confidence?: number;
+        matchedKeywords?: string[];
+    }>;
+    /** The exact keywords that selected the winning intent (explainability). */
+    matchedKeywords?: string[];
+    /** Raw keyword-hit count for the winner, and its lead over the runner-up. */
+    score?: number;
+    margin?: number;
+    /** True when the winning intent is classifier-only (your systems handle it). */
+    classifyOnly?: boolean;
+    /** Extracted entities: amount, account_number, phone, bank {name, code}, currency. */
+    entities: Record<string, unknown>;
+    status: number;
+    error?: string;
+}
+
+/**
+ * Management API - everything the console can do, callable from code. Thin,
+ * typed-enough wrappers over the engine's management endpoints, all
+ * authenticated with the same x-api-key as chat. Every method resolves to
+ * `{ ok, status, ...payload }` and never throws on HTTP errors.
+ */
+interface ManageResult {
+    ok: boolean;
+    status: number;
+    error?: string;
+    [key: string]: unknown;
+}
+interface CreateAgentInput {
+    intent: string;
+    label?: string;
+    keywords: string[];
+    /** With instructions (and optionally tools) this creates a FULL chat agent; without, a classifier-only intent. */
+    systemPrompt?: string;
+    tools?: string[];
+    requiresCustomer?: boolean;
+}
+interface CreateToolInput {
+    name: string;
+    description: string;
+    sideEffect: 'read' | 'write';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** {placeholders} become the tool's arguments; {customer_id} is filled per turn. */
+    url: string;
+    execution?: 'hosted' | 'client';
+    /** A real example response - drives result parsing and the sandbox. */
+    sampleResponse?: unknown;
+}
+interface BindToolInput {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    resultPath?: string | null;
+    sampleResponse?: unknown;
+    execution?: 'hosted' | 'client';
+    auth?: Record<string, unknown>;
+}
+type Request = (method: string, path: string, body?: Record<string, unknown>) => Promise<ManageResult>;
+/** Build the management namespaces over one authenticated request function. */
+declare function buildManage(request: Request): {
+    agents: {
+        list: () => Promise<ManageResult>;
+        create: (input: CreateAgentInput) => Promise<ManageResult>;
+        update: (intent: string, patch: Record<string, unknown>) => Promise<ManageResult>;
+        enable: (intent: string) => Promise<ManageResult>;
+        disable: (intent: string) => Promise<ManageResult>;
+        delete: (intent: string) => Promise<ManageResult>;
+    };
+    tools: {
+        list: () => Promise<ManageResult>;
+        create: (input: CreateToolInput) => Promise<ManageResult>;
+        bind: (name: string, binding: BindToolInput) => Promise<ManageResult>;
+        test: (name: string) => Promise<ManageResult>;
+        importOpenApi: (input: {
+            url?: string;
+            spec?: unknown;
+            execution?: "hosted" | "client";
+            dryRun?: boolean;
+            auth?: Record<string, unknown>;
+        }) => Promise<ManageResult>;
+    };
+    plugins: {
+        list: () => Promise<ManageResult>;
+        install: (id: string) => Promise<ManageResult>;
+        uninstall: (id: string) => Promise<ManageResult>;
+    };
+    customers: {
+        list: (opts?: {
+            limit?: number;
+            range?: string;
+        }) => Promise<ManageResult>;
+        upsert: (input: {
+            externalId: string;
+            tier?: string | null;
+            name?: string;
+            email?: string;
+            status?: string;
+        }) => Promise<ManageResult>;
+        get: (externalId: string) => Promise<ManageResult>;
+    };
+    settings: {
+        get: () => Promise<ManageResult>;
+        update: (patch: Record<string, unknown>) => Promise<ManageResult>;
+    };
+    billing: {
+        get: () => Promise<ManageResult>;
+        topup: (amountNgn: number, email?: string) => Promise<ManageResult>;
+    };
+    usage: {
+        summary: () => Promise<ManageResult>;
+        events: (limit?: number) => Promise<ManageResult>;
+        event: (id: number | string) => Promise<ManageResult>;
+        analytics: (days?: number) => Promise<ManageResult>;
+    };
+    manifest: () => Promise<ManageResult>;
+};
+type Manage = ReturnType<typeof buildManage>;
+
+/**
+ * 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;
+    /**
+     * Everything the console can do, from code: agents, tools, plugins,
+     * customers, settings, billing, usage. `twelve.manage.plugins.install('bills')`.
+     */
+    readonly manage: Manage;
+    constructor(options: TwelveAIOptions);
+    /**
+     * Low-level authenticated call to any engine endpoint. Returns
+     * `{ ok, status, ...payload }`; never throws on HTTP errors.
+     */
+    api(method: string, path: string, body?: Record<string, unknown>): Promise<ManageResult>;
+    /**
+     * 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;
+        reasoning?: 'off' | 'auto' | 'always';
+    }): 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 { type Attachment as A, type BindToolInput as B, type ChatInput as C, type HandoffExecutor as H, type Manage as M, type PendingToolCall as P, TwelveAI as T, type ChatResponse as a, type ClassifyResponse as b, type CreateAgentInput as c, type CreateToolInput as d, type HandoffRequest as e, type ManageResult as f, type ToolCall as g, type ToolResult as h, type TwelveAIOptions as i, buildManage as j };