twelveai 0.3.0 → 0.4.0

package/dist/cli.cjs

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+"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/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_fs = require("fs");
+
+// src/manage.ts
+function buildManage(request) {
+  return {
+    agents: {
+      list: () => request("GET", "/v1/agents"),
+      create: (input) => request("POST", "/v1/agents", { ...input }),
+      update: (intent, patch) => request("PUT", "/v1/agents", { intent, ...patch }),
+      enable: (intent) => request("PUT", "/v1/agents", { intent, enabled: true }),
+      disable: (intent) => request("PUT", "/v1/agents", { intent, enabled: false }),
+      delete: (intent) => request("DELETE", `/v1/agents/${encodeURIComponent(intent)}`)
+    },
+    tools: {
+      list: () => request("GET", "/v1/tools"),
+      create: (input) => request("POST", "/v1/tools", { ...input }),
+      bind: (name, binding) => request("PUT", `/v1/tools/${encodeURIComponent(name)}`, { ...binding }),
+      test: (name) => request("POST", `/v1/tools/${encodeURIComponent(name)}/test`),
+      importOpenApi: (input) => request("POST", "/v1/tools/import", { ...input })
+    },
+    plugins: {
+      list: () => request("GET", "/v1/plugins"),
+      install: (id) => request("POST", `/v1/plugins/${encodeURIComponent(id)}/install`),
+      uninstall: (id) => request("POST", `/v1/plugins/${encodeURIComponent(id)}/uninstall`)
+    },
+    customers: {
+      list: (opts = {}) => request("GET", `/v1/customers?limit=${opts.limit ?? 100}${opts.range ? `&range=${opts.range}` : ""}`),
+      upsert: (input) => request("POST", "/v1/customers", { ...input }),
+      get: (externalId) => request("GET", `/v1/customers/${encodeURIComponent(externalId)}`)
+    },
+    settings: {
+      get: () => request("GET", "/v1/settings"),
+      update: (patch) => request("PUT", "/v1/settings", patch)
+    },
+    billing: {
+      get: () => request("GET", "/v1/billing"),
+      topup: (amountNgn, email) => request("POST", "/v1/billing/topup", { amount: amountNgn, ...email ? { email } : {} })
+    },
+    usage: {
+      summary: () => request("GET", "/v1/usage"),
+      events: (limit = 20) => request("GET", `/v1/usage/events?limit=${limit}`),
+      event: (id) => request("GET", `/v1/usage/events/${id}`),
+      analytics: (days = 30) => request("GET", `/v1/usage/analytics?days=${days}`)
+    },
+    manifest: () => request("GET", "/v1/manifest")
+  };
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://ai.twelveai.app";
+var TwelveAI = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  clientAuth;
+  maxHandoffRounds;
+  /**
+   * Everything the console can do, from code: agents, tools, plugins,
+   * customers, settings, billing, usage. `twelve.manage.plugins.install('bills')`.
+   */
+  manage;
+  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).");
+    }
+    this.manage = buildManage((method, path, body) => this.api(method, path, body));
+  }
+  /**
+   * Low-level authenticated call to any engine endpoint. Returns
+   * `{ ok, status, ...payload }`; never throws on HTTP errors.
+   */
+  async api(method, path, body) {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        ...data,
+        ok: res.ok && data.ok !== false,
+        status: res.status,
+        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
+      };
+    } catch (error) {
+      return { ok: false, status: 0, error: error?.message || "Could not reach the engine." };
+    }
+  }
+  /**
+   * 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, ...input.reasoning ? { reasoning: input.reasoning } : {} })
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        intent: null,
+        label: null,
+        confidence: 0,
+        alternatives: [],
+        entities: {},
+        ...data,
+        // pass every field through (matchedKeywords, score, margin, classifyOnly, ...)
+        ok: res.ok && data.ok !== false,
+        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.reasoning) body.reasoning = input.reasoning;
+    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/cli.ts
+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) => (0, import_node_fs.readFileSync)(p, "utf8")
+  }).then((code) => process.exit(code));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});

package/dist/cli.d.cts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { T as TwelveAI } from './client-C5vzks2N.cjs';
+
+interface CliDeps {
+    env: Record<string, string | undefined>;
+    log: (s: string) => void;
+    error: (s: string) => void;
+    readFile: (path: string) => string;
+    client?: TwelveAI;
+}
+declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
+
+export { runCli };

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { T as TwelveAI } from './client-C5vzks2N.js';
+
+interface CliDeps {
+    env: Record<string, string | undefined>;
+    log: (s: string) => void;
+    error: (s: string) => void;
+    readFile: (path: string) => string;
+    client?: TwelveAI;
+}
+declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
+
+export { runCli };