@niadra/sdk 0.1.0 → 0.7.0

package/dist/vapi.js

@@ -0,0 +1,656 @@
+// src/tools.ts
+var TOOL_NAMES = {
+  search: "search_customer_history",
+  timeline: "get_customer_timeline",
+  open: "open_history_item"
+};
+var AGENT_MEMORY_TOOL_NAMES = {
+  search: "search_agent_memory",
+  remember: "remember"
+};
+var TOOL_DEFINITIONS = [
+  {
+    "type": "function",
+    "function": {
+      "name": "search_customer_history",
+      "description": "Search everything that already happened with this customer: past conversations, promises, agent actions, orders and invoices. Use it when the customer refers to something earlier or asks whether a problem happened before. Do not call it when the answer is already in the context block, including its 'Do hist\xF3rico' line, which already counts recurrences. Returns short items with date, channel and outcome, plus a recurrence count. Open one with open_history_item.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "What to look for, in the customer's words."
+          },
+          "filters": {
+            "type": "object",
+            "properties": {
+              "since": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "until": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "when": {
+                "type": "string",
+                "description": "The period in the customer's own words, as they said it: 'last week', 'semana passada', 'en marzo'."
+              },
+              "channels": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "categories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "item_kinds": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "episode",
+                    "fact",
+                    "open_item",
+                    "action",
+                    "object",
+                    "trait"
+                  ]
+                }
+              },
+              "outcome": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "max_tokens": {
+            "type": "integer",
+            "minimum": 50,
+            "maximum": 4e3
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "get_customer_timeline",
+      "description": "List this customer's conversations and agent actions in order, newest first, one line each. Use it to leaf through the history when you do not know what to search for. Pass next_cursor to continue. Prefer search_customer_history for a specific question.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+          },
+          "filters": {
+            "type": "object",
+            "properties": {
+              "since": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "until": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "when": {
+                "type": "string",
+                "description": "The period in the customer's own words, as they said it: 'last week', 'semana passada', 'en marzo'."
+              },
+              "channels": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "categories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "item_kinds": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "episode",
+                    "fact",
+                    "open_item",
+                    "action",
+                    "object",
+                    "trait"
+                  ]
+                }
+              },
+              "outcome": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "open_history_item",
+      "description": "Open one conversation or business object returned by search_customer_history or get_customer_timeline: what was asked, what was promised and by whom, the outcome and what memory came from it. Use it only after a search or timeline pointed to the item.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The item id, e.g. `episode:...`."
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+];
+var AGENT_MEMORY_TOOL_DEFINITIONS = [
+  {
+    "type": "function",
+    "function": {
+      "name": "search_agent_memory",
+      "description": "Search your own working notes: procedures, how the company's tools and processes behave, and known pitfalls. Use it before a task or a tool call you are unsure how to do. It holds nothing about customers; for the customer's history use search_customer_history.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "What you need to know how to do."
+          },
+          "tags": {
+            "type": "array",
+            "maxItems": 8,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"
+            },
+            "description": "Object types, operations or systems, e.g. `invoice`, `credit`, `erp`."
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "remember",
+      "description": "Save a working note for yourself and future runs: a procedure that worked, how a tool or process behaves, or a pitfall to avoid. Never write anything about a customer here: no names, phones, e-mails, documents, ids or words from the conversation. A note with personal data is refused. Write it so it helps with any customer.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "enum": [
+              "procedure",
+              "tool_note",
+              "process_note",
+              "pitfall"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 120
+          },
+          "body": {
+            "type": "string",
+            "maxLength": 2e3
+          },
+          "tags": {
+            "type": "array",
+            "maxItems": 8,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"
+            },
+            "description": "Object types, operations or systems, e.g. `invoice`, `credit`, `erp`."
+          }
+        },
+        "required": [
+          "kind",
+          "title",
+          "body"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+];
+
+// src/context.ts
+function emptyResult(error) {
+  return { text: "", suffix: "", variables: {}, pack: null, source: "none", response: null, error, constraints: null, state: null, coordination: null };
+}
+
+// src/integrations/shared.ts
+var ATTESTED = { A: "V2", B: "V1", C: "V1" };
+function attestationProof(attestation) {
+  if (!attestation) return null;
+  const value = attestation.trim().toUpperCase();
+  if (value.includes("FAILED") || value.startsWith("NO-")) return null;
+  const letter = value.length === 1 ? value : /PASSED-([ABC])$/.exec(value)?.[1];
+  const level = letter ? ATTESTED[letter] : void 0;
+  return level ? { method: "network_attestation", level } : null;
+}
+function isConversation(session) {
+  return "customer" in session && typeof session.customer === "function";
+}
+function phoneHandle(value) {
+  const raw = value?.trim().replace(/^tel:/i, "").replace(/[\s().-]/g, "");
+  if (!raw) return null;
+  const e164 = raw.startsWith("+") ? raw : `+${raw}`;
+  return /^\+[1-9]\d{6,14}$/.test(e164) ? { type: "phone_e164", value: e164 } : null;
+}
+function errorName(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+var Bridge = class {
+  constructor(session, proof, memory = false) {
+    this.session = session;
+    this.proof = proof;
+    this.memory = memory;
+  }
+  session;
+  proof;
+  memory;
+  proving = null;
+  /** `begin()` started the first read of a call: the first `context()` waits for it with `ready()`. */
+  begun = false;
+  opened = false;
+  /**
+   * The context and, when enabled, the agent's notes, read side by side within the same budget.
+   * Never rejects.
+   */
+  async read(options = {}) {
+    const memoryParams = this.memory === false ? null : this.memory === true ? {} : withoutWrite(this.memory);
+    const [context, memory] = await Promise.all([
+      this.context(options),
+      memoryParams ? this.agentMemory(memoryParams, options) : Promise.resolve("")
+    ]);
+    return { context, memory, prefix: [memory, context.text].filter(Boolean).join("\n\n"), suffix: context.suffix };
+  }
+  get logger() {
+    return this.session.logger;
+  }
+  /**
+   * Starts the first read of a call now, in the background, after the proof when one was given (the
+   * pack depends on the level it proves): at call start, so the read runs while the call is set up.
+   * The first `context()` then waits for it within `timeouts.contextVoiceStart`. Never throws.
+   */
+  begin() {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    const start = () => {
+      this.safe("start the first read", () => {
+        this.begun = session.begin();
+      });
+    };
+    if (this.proof === void 0 || this.proof === null) start();
+    else void this.verifyOnce().then(start);
+  }
+  /** Verifies once (when a proof was given), then reads the context. Never rejects. */
+  async context(options = {}) {
+    await this.verifyOnce();
+    try {
+      const session = this.session;
+      if (this.begun && !this.opened && isConversation(session)) {
+        this.opened = true;
+        await session.ready(options.timeout === void 0 ? {} : { timeout: options.timeout });
+      }
+      return await this.session.context(options);
+    } catch (error) {
+      this.logger.warn(`could not read context (${errorName(error)})`);
+      return emptyResult(null);
+    }
+  }
+  /** Records that `context` went into the prompt, unless it was empty for a reason other than the holdout. */
+  injected(context) {
+    if (!context.text && !context.suffix && context.response?.path !== "holdout") return;
+    this.safe("mark the injection", () => {
+      this.session.markInjected(context);
+    });
+  }
+  customer(text, options = {}) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("record the customer's turn", () => session.customer(text, options));
+  }
+  /** Sends the customer's turn so far, while they speak. In the background; never throws. */
+  prefetch(text) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("prefetch the turn", () => session.prefetch(text));
+  }
+  agent(text, options = {}) {
+    if (!text.trim()) return;
+    this.safe("record the agent's turn", () => this.session.agent(text, options));
+  }
+  /** Records a transfer. Tasks have no transfer; the call is ignored for them. */
+  async handoff(target, reason) {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    try {
+      await session.handoff(reason ? { target, reason } : { target });
+    } catch (error) {
+      this.logger.warn(`could not record the handoff (${errorName(error)})`);
+    }
+  }
+  async end() {
+    try {
+      await this.session.end();
+    } catch (error) {
+      this.logger.warn(`could not end the session (${errorName(error)})`);
+    }
+  }
+  /** The navigation kit as plain specs (with the agent's memory tools when enabled), or none for a task about an object only. */
+  tools() {
+    let bound;
+    try {
+      const memory = this.memory;
+      bound = this.session.tools(memory === false ? {} : { agentMemory: true, writeAgentMemory: memory !== true && memory.write === true });
+    } catch (error) {
+      this.logger.warn(`could not build the tools (${errorName(error)})`);
+      return [];
+    }
+    return bound ? toolSpecs(bound) : [];
+  }
+  async agentMemory(params, options) {
+    try {
+      const result = await this.session.agentMemory(params, options.timeout === void 0 ? {} : { timeout: options.timeout });
+      return result.text;
+    } catch (error) {
+      this.logger.warn(`could not read the agent's memory (${errorName(error)})`);
+      return "";
+    }
+  }
+  async verifyOnce() {
+    if (this.proof === void 0 || this.proof === null) return;
+    this.proving ??= this.runVerify();
+    await this.proving;
+  }
+  async runVerify() {
+    try {
+      const source = this.proof;
+      const proof = typeof source === "function" ? await source() : source;
+      if (!proof) return;
+      await this.session.verify(proof);
+    } catch (error) {
+      this.logger.warn(`could not record the verification (${errorName(error)})`);
+    }
+  }
+  safe(what, run) {
+    try {
+      run();
+    } catch (error) {
+      this.logger.warn(`could not ${what} (${errorName(error)})`);
+    }
+  }
+};
+function withoutWrite(option) {
+  const { write: _, ...params } = option;
+  return params;
+}
+function toolSpecs(bound) {
+  return bound.definitions.map(({ function: definition }) => ({
+    name: definition.name,
+    description: definition.description,
+    parameters: definition.parameters,
+    execute: (args) => bound.call(definition.name, args)
+  }));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/integrations/webhook.ts
+function memoryCallStore(max = 1e4) {
+  const calls = /* @__PURE__ */ new Map();
+  return {
+    get: (id) => calls.get(id),
+    set: (id, record) => {
+      calls.delete(id);
+      calls.set(id, record);
+      if (calls.size > max) {
+        const oldest = calls.keys().next().value;
+        if (oldest !== void 0) calls.delete(oldest);
+      }
+    }
+  };
+}
+function header(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== wanted) continue;
+    return Array.isArray(value) ? value[0] : value;
+  }
+  return void 0;
+}
+var encoder = new TextEncoder();
+function safeEqual(a, b) {
+  const left = encoder.encode(a);
+  const right = encoder.encode(b);
+  if (left.length !== right.length) return false;
+  let diff = 0;
+  for (let i = 0; i < left.length; i++) diff |= (left[i] ?? 0) ^ (right[i] ?? 0);
+  return diff === 0;
+}
+
+// src/integrations/vapi.ts
+var OURS = /* @__PURE__ */ new Set([...Object.values(TOOL_NAMES), ...Object.values(AGENT_MEMORY_TOOL_NAMES)]);
+var AGENT_ROLES = /* @__PURE__ */ new Set(["bot", "assistant"]);
+function vapiTools(server, options = {}) {
+  const memory = options.agentMemory;
+  const definitions = [
+    ...TOOL_DEFINITIONS,
+    ...memory ? AGENT_MEMORY_TOOL_DEFINITIONS.slice(0, memory !== true && memory.write ? 2 : 1) : []
+  ];
+  return definitions.map(({ function: definition }) => ({
+    type: "function",
+    function: { name: definition.name, description: definition.description, parameters: definition.parameters },
+    server: server.secret ? { url: server.url, secret: server.secret } : { url: server.url }
+  }));
+}
+function vapi(options) {
+  const store = options.store ?? memoryCallStore();
+  const logger = options.niadra.logger;
+  const transferred = /* @__PURE__ */ new Set();
+  const authorized = (headers) => {
+    if (!options.secret) return false;
+    const given = header(headers, "x-vapi-secret") ?? header(headers, "authorization")?.replace(/^Bearer\s+/i, "");
+    return given !== void 0 && safeEqual(given, options.secret);
+  };
+  const subjectOf = (call) => {
+    try {
+      return (options.subject ? options.subject(call) : phoneHandle(call.customerNumber)) ?? null;
+    } catch {
+      return null;
+    }
+  };
+  const recall = async (call) => {
+    try {
+      const stored = await store.get(call.id);
+      if (stored) return stored;
+    } catch (error) {
+      logger.warn(`could not read the call store (${errorName(error)})`);
+    }
+    const subject = subjectOf(call);
+    return subject ? { subject, verification: "V0" } : null;
+  };
+  const open = (call, record) => options.niadra.conversation({ subject: record.subject, channel: "voice", conversation_id: call.id, verification: record.verification });
+  async function assistantRequest(call) {
+    const context = { context: "", agentMemory: "", turn: "" };
+    const subject = subjectOf(call);
+    if (subject) {
+      const conversation = options.niadra.conversation({ subject, channel: "voice", conversation_id: call.id });
+      const bridge = new Bridge(conversation, options.verify ? () => options.verify?.(call) : void 0, options.agentMemory);
+      bridge.begin();
+      const read = await bridge.read(options.contextTimeout ? { timeout: options.contextTimeout } : {});
+      bridge.injected(read.context);
+      context.context = read.context.text;
+      context.agentMemory = read.memory;
+      context.turn = read.suffix;
+      try {
+        await store.set(call.id, { subject, verification: conversation.verification, stamp: conversation.contextStamp });
+      } catch (error) {
+        logger.warn(`could not write the call store (${errorName(error)})`);
+      }
+    }
+    let chosen;
+    try {
+      chosen = typeof options.assistant === "function" ? await options.assistant(call, context) : options.assistant;
+    } catch (error) {
+      logger.warn(`could not build the assistant (${errorName(error)})`);
+      return { status: 200, body: { error: "The assistant is not available right now." } };
+    }
+    return { status: 200, body: assistantResponse(chosen, context, Boolean(options.agentMemory)) };
+  }
+  async function toolCalls(call) {
+    const list = Array.isArray(call.message.toolCallList) ? call.message.toolCallList : [];
+    const record = await recall(call);
+    const specs = record ? new Bridge(open(call, record), void 0, options.agentMemory).tools() : [];
+    const results = [];
+    for (const item of list) {
+      if (!isRecord(item) || !isRecord(item.function)) continue;
+      const id = typeof item.id === "string" ? item.id : "";
+      const name = typeof item.function.name === "string" ? item.function.name : "";
+      const args = item.function.arguments;
+      let result;
+      if (OURS.has(name)) {
+        const spec = specs.find((candidate) => candidate.name === name);
+        result = spec ? await spec.execute(args ?? {}) : JSON.stringify({ error: "unavailable", detail: "customer history is unavailable right now" });
+      } else if (options.otherTool) {
+        try {
+          result = await options.otherTool(name, args, call);
+        } catch (error) {
+          logger.warn(`a tool outside Niadra failed (${errorName(error)})`);
+          results.push({ name, toolCallId: id, error: "tool failed" });
+          continue;
+        }
+      } else {
+        results.push({ name, toolCallId: id, error: `unknown tool: ${name}` });
+        continue;
+      }
+      results.push({ name, toolCallId: id, result });
+    }
+    return { status: 200, body: { results } };
+  }
+  async function transfer(call, answer) {
+    if (!transferred.has(call.id)) {
+      transferred.add(call.id);
+      if (transferred.size > 1e4) transferred.clear();
+      const record = await recall(call);
+      if (record) await new Bridge(open(call, record)).handoff("human", "transfer");
+    }
+    if (!answer) return { status: 200, body: {} };
+    try {
+      return { status: 200, body: options.transfer ? await options.transfer(call) : {} };
+    } catch (error) {
+      logger.warn(`could not choose the transfer destination (${errorName(error)})`);
+      return { status: 200, body: { error: "The transfer is not available right now." } };
+    }
+  }
+  async function endOfCall(call) {
+    const record = await recall(call);
+    if (!record) return { status: 200, body: { recorded: 0 } };
+    const bridge = new Bridge(open(call, record));
+    const artifact = isRecord(call.message.artifact) ? call.message.artifact : {};
+    const messages = Array.isArray(artifact.messages) ? artifact.messages : [];
+    let recorded = 0;
+    for (const [index, message] of messages.entries()) {
+      if (!isRecord(message) || typeof message.message !== "string" || !message.message.trim()) continue;
+      const role = typeof message.role === "string" ? message.role : "";
+      const at = typeof message.time === "number" ? new Date(message.time) : void 0;
+      const base = { idempotency_key: `vapi:${call.id}:${index}`, ...at ? { occurred_at: at } : {} };
+      if (role === "user") {
+        bridge.customer(message.message, base);
+        recorded++;
+      } else if (AGENT_ROLES.has(role)) {
+        bridge.agent(message.message, record.stamp ? { ...base, context_stamp: record.stamp } : base);
+        recorded++;
+      }
+    }
+    await bridge.end();
+    await options.niadra.flush();
+    return { status: 200, body: { recorded } };
+  }
+  return async (body, headers) => {
+    if (!authorized(headers)) return { status: 401, body: { error: "unauthorized" } };
+    const call = callOf(body);
+    if (!call) return { status: 400, body: { error: "invalid_body" } };
+    switch (call.message.type) {
+      case "assistant-request":
+        return assistantRequest(call);
+      case "tool-calls":
+        return toolCalls(call);
+      case "transfer-destination-request":
+        return transfer(call, true);
+      case "transfer-update":
+        return transfer(call, false);
+      case "end-of-call-report":
+        return endOfCall(call);
+      default:
+        return { status: 200, body: {} };
+    }
+  };
+}
+function callOf(body) {
+  const message = isRecord(body) && isRecord(body.message) ? body.message : null;
+  if (!message || typeof message.type !== "string") return null;
+  const call = isRecord(message.call) ? message.call : {};
+  const id = typeof call.id === "string" ? call.id : void 0;
+  if (!id) return null;
+  const customer = isRecord(call.customer) ? call.customer : isRecord(message.customer) ? message.customer : {};
+  return { id, customerNumber: typeof customer.number === "string" ? customer.number : void 0, message };
+}
+function assistantResponse(chosen, context, memory) {
+  const variableValues = { niadra_context: context.context, niadra_turn: context.turn };
+  if (memory) variableValues.niadra_agent_memory = context.agentMemory;
+  if (typeof chosen === "string") return { assistantId: chosen, assistantOverrides: { variableValues } };
+  if (!chosen) return { assistantOverrides: { variableValues } };
+  if (!("model" in chosen) && ("assistantId" in chosen || "squadId" in chosen || "assistant" in chosen)) {
+    const overrides = isRecord(chosen.assistantOverrides) ? chosen.assistantOverrides : {};
+    const values = isRecord(overrides.variableValues) ? overrides.variableValues : {};
+    return { ...chosen, assistantOverrides: { ...overrides, variableValues: { ...values, ...variableValues } } };
+  }
+  const model = isRecord(chosen.model) ? chosen.model : null;
+  const messages = model && Array.isArray(model.messages) ? [...model.messages] : [];
+  const prefix = [context.agentMemory, context.context].filter(Boolean).join("\n\n");
+  if (model && prefix) {
+    let position = 0;
+    while (position < messages.length && isRecord(messages[position]) && messages[position].role === "system") position++;
+    messages.splice(position, 0, { role: "system", content: prefix });
+  }
+  const assistant = model ? { ...chosen, model: { ...model, messages } } : chosen;
+  return { assistant, assistantOverrides: { variableValues } };
+}
+
+export { attestationProof, memoryCallStore, vapi, vapiTools };
+//# sourceMappingURL=vapi.js.map
+//# sourceMappingURL=vapi.js.map