twelveai 0.3.1 → 0.4.0

package/README.md

@@ -91,6 +91,43 @@ if (res.pendingConfirmation) {
 }
 ```
 
+## Manage your workspace from code or the terminal
+
+Everything the console does is also available programmatically (same API key):
+
+```ts
+await twelve.manage.plugins.install('bills')
+await twelve.manage.agents.create({
+  intent: 'loan_request',
+  keywords: ['loan', 'borrow'],
+  systemPrompt: 'You help customers with loan questions. Call list_loans and answer only from what it returns.',
+  tools: ['list_loans'],
+})
+await twelve.manage.tools.create({
+  name: 'list_loans',
+  description: "List this customer's active loans.",
+  sideEffect: 'read',
+  method: 'GET',
+  url: 'https://api.yourbank.com/v1/customers/{customer_id}/loans',
+  sampleResponse: { status: 'success', data: { loans: [] } },
+})
+await twelve.manage.settings.update({ webhookUrl: 'https://api.yourapp.com/hooks' })
+```
+
+Namespaces: `agents`, `tools`, `plugins`, `customers`, `settings`, `billing`, `usage`, plus `twelve.api(method, path, body?)` for anything else.
+
+Or use the CLI (ships with this package):
+
+```bash
+export TWELVE_API_KEY=sk-...
+npx -p twelveai twelveai plugins install bills
+npx -p twelveai twelveai agents list
+npx -p twelveai twelveai chat "what's my balance?" --customer cus_123 --sandbox
+npx -p twelveai twelveai usage
+```
+
+Run `twelveai help` for the full command list.
+
 ## Sandbox
 
 Add `sandbox: true` and every tool returns realistic sample data - nothing real is called or moved. Perfect for CI and demos.

package/dist/chunk-6RZKLIGP.js

@@ -0,0 +1,248 @@
+// 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." };
+    }
+  }
+};
+
+export {
+  buildManage,
+  TwelveAI
+};