@niadra/sdk 0.1.0 → 0.1.1

package/dist/index.js

@@ -358,6 +358,15 @@ function checkCloses(closes) {
   const byObject = Boolean(closes.object && closes.operation);
   if (byId === byObject) fail("closes takes either item_id, or object and operation");
 }
+function checkUsage(usage) {
+  if (!/^[a-z0-9][a-z0-9_.-]{0,63}$/.test(usage.provider)) fail("usage.provider must be lowercase, like `openai`");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:/@-]{0,127}$/.test(usage.model)) fail("usage.model is not a model name");
+  const counts = [usage.prompt_tokens, usage.cached_tokens ?? 0, usage.cache_write_tokens ?? 0];
+  if (!counts.every((n) => Number.isInteger(n) && n >= 0)) fail("usage counts are whole numbers from 0");
+  if ((usage.cached_tokens ?? 0) + (usage.cache_write_tokens ?? 0) > usage.prompt_tokens) {
+    fail("cached and written tokens are part of prompt_tokens");
+  }
+}
 function checkContent(content) {
   if (!content) return;
   if ((content.text?.length ?? 0) > MAX_EVENT_TEXT) fail(`content.text is longer than ${MAX_EVENT_TEXT}`);
@@ -388,6 +397,10 @@ function buildEvent(input) {
     if ((input.action.result?.length ?? 0) > 2e3) fail("action.result is longer than 2000");
     checkCloses(input.action.closes);
   }
+  if (input.usage) {
+    if (kind !== "message" || speaker.role !== "ai_agent") fail("`usage` is only valid on a message of the `ai_agent`");
+    checkUsage(input.usage);
+  }
   const event = {
     type: "event",
     kind,
@@ -403,6 +416,7 @@ function buildEvent(input) {
   if (input.canonical_type) event.canonical_type = input.canonical_type;
   if (input.fields) event.fields = input.fields;
   if (input.action) event.action = input.action;
+  if (input.usage) event.usage = input.usage;
   copyOptional(event, input);
   assertSerializable(event);
   return event;
@@ -577,6 +591,76 @@ function withDeltas(result, response, deltas) {
   return { ...result, response: merged, suffix: renderSuffix(merged) };
 }
 
+// src/usage.ts
+var PROVIDER = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+var MODEL = /^[A-Za-z0-9][A-Za-z0-9_.:/@-]{0,127}$/;
+function get(value, name) {
+  return (typeof value === "object" || typeof value === "function") && value !== null ? value[name] : void 0;
+}
+function count(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function tokenCounts(usage) {
+  const read = count(get(usage, "cache_read_input_tokens")) ?? 0;
+  const written = count(get(usage, "cache_creation_input_tokens")) ?? 0;
+  let prompt = count(get(usage, "prompt_tokens"));
+  let cached;
+  if (prompt !== null) {
+    const reported = count(get(get(usage, "prompt_tokens_details"), "cached_tokens"));
+    cached = reported !== null && reported > 0 ? reported : read;
+  } else {
+    const inputs = count(get(usage, "input_tokens"));
+    if (inputs === null) return null;
+    const details = get(usage, "input_tokens_details");
+    if (details !== void 0 && details !== null) {
+      prompt = inputs;
+      cached = count(get(details, "cached_tokens")) ?? 0;
+    } else {
+      prompt = inputs + read + written;
+      cached = read;
+    }
+  }
+  return { prompt_tokens: Math.max(prompt, cached + written), cached_tokens: cached, cache_write_tokens: written };
+}
+function providerOf(model, usage) {
+  const slash = model.indexOf("/");
+  if (slash > 0) return model.slice(0, slash).trim().toLowerCase();
+  const name = model.trim().toLowerCase();
+  if (name.startsWith("claude") || `.${name}`.includes(".anthropic.")) return "anthropic";
+  if (name.startsWith("gemini")) return "google";
+  if (get(usage, "prompt_tokens") === void 0 && get(usage, "cache_read_input_tokens") !== void 0) {
+    return "anthropic";
+  }
+  return "openai";
+}
+function modelUsage(response, options = {}) {
+  try {
+    let usage = get(response, "usage");
+    if (usage === void 0 || usage === null || typeof usage !== "object") usage = response;
+    const counts = tokenCounts(usage);
+    const name = options.model ?? get(response, "model");
+    if (!counts || typeof name !== "string" || !MODEL.test(name)) return null;
+    const provider = (options.provider ?? providerOf(name, usage)).toLowerCase();
+    if (!PROVIDER.test(provider)) return null;
+    return { provider, model: name, ...counts };
+  } catch {
+    return null;
+  }
+}
+function asModelUsage(value) {
+  if (value === void 0 || value === null) return null;
+  if (isModelUsage(value)) return value;
+  return modelUsage(value);
+}
+function isModelUsage(value) {
+  const provider = get(value, "provider");
+  const model = get(value, "model");
+  const prompt = count(get(value, "prompt_tokens"));
+  const cached = get(value, "cached_tokens") === void 0 ? 0 : count(get(value, "cached_tokens"));
+  const written = get(value, "cache_write_tokens") === void 0 ? 0 : count(get(value, "cache_write_tokens"));
+  return typeof provider === "string" && PROVIDER.test(provider) && typeof model === "string" && MODEL.test(model) && prompt !== null && cached !== null && written !== null && cached + written <= prompt;
+}
+
 // src/conversation.ts
 var Conversation = class {
   constructor(client, params, hooks) {
@@ -736,6 +820,8 @@ var Conversation = class {
     if (options.visibility) event.visibility = options.visibility;
     if (options.voice) event.voice = options.voice;
     if (options.context_stamp) event.context_stamp = options.context_stamp;
+    const usage = role === "ai_agent" ? asModelUsage(options.usage) : null;
+    if (usage) event.usage = usage;
     return this.client.track(event);
   }
 };
@@ -879,6 +965,7 @@ var DEFAULT_CACHE = {
 var DEFAULT_QUEUE = {
   flushAt: 15,
   flushIntervalMs: 1e3,
+  turnFlushIntervalMs: 200,
   maxBatchSize: 100,
   maxQueueSize: 1e4,
   maxAttempts: 3,
@@ -902,6 +989,7 @@ var EventQueue = class {
   now;
   items = [];
   timer = null;
+  timerDueAt = Number.POSITIVE_INFINITY;
   tail = Promise.resolve();
   closed = false;
   droppedSinceWarning = 0;
@@ -926,7 +1014,8 @@ var EventQueue = class {
     if (this.items.length >= this.options.flushAt) {
       this.flushInBackground();
     } else {
-      this.schedule();
+      const { flushIntervalMs, turnFlushIntervalMs } = this.options;
+      this.schedule(isTurn(item) ? Math.min(turnFlushIntervalMs, flushIntervalMs) : flushIntervalMs);
     }
     return true;
   }
@@ -1016,20 +1105,29 @@ var EventQueue = class {
     this.sentInWindow = 0;
     return item;
   }
-  schedule() {
-    if (this.timer !== null) return;
+  /** Sends what is waiting in `delayMs`, unless a send is already due sooner. */
+  schedule(delayMs) {
+    const dueAt = this.now() + delayMs;
+    if (this.timer !== null && this.timerDueAt <= dueAt) return;
+    this.cancelTimer();
+    this.timerDueAt = dueAt;
     this.timer = setTimeout(() => {
       this.timer = null;
+      this.timerDueAt = Number.POSITIVE_INFINITY;
       this.flushInBackground();
-    }, this.options.flushIntervalMs);
+    }, delayMs);
     unref(this.timer);
   }
   cancelTimer() {
     if (this.timer === null) return;
     clearTimeout(this.timer);
     this.timer = null;
+    this.timerDueAt = Number.POSITIVE_INFINITY;
   }
 };
+function isTurn(item) {
+  return item.type === "event" && item.kind === "message" && Boolean(item.conversation_id);
+}
 function unref(timer) {
   if (typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function") {
     timer.unref();
@@ -1106,6 +1204,8 @@ var Task = class {
     if (options.idempotency_key) event.idempotency_key = options.idempotency_key;
     if (options.occurred_at) event.occurred_at = options.occurred_at;
     if (options.visibility) event.visibility = options.visibility;
+    const usage = asModelUsage(options.usage);
+    if (usage) event.usage = usage;
     return this.track(event);
   }
   /**
@@ -1177,7 +1277,7 @@ var TOOL_NAMES = {
   timeline: "get_customer_timeline",
   open: "open_history_item"
 };
-var ITEM_KINDS = ["episode", "fact", "open_item", "action", "system_event", "object", "trait"];
+var ITEM_KINDS = ["episode", "fact", "open_item", "action", "object", "trait"];
 var period = {
   since: { type: "string", format: "date-time", description: "Only items at or after this ISO 8601 time." },
   until: { type: "string", format: "date-time", description: "Only items before this ISO 8601 time." },
@@ -1197,7 +1297,7 @@ var TOOL_DEFINITIONS = [
     type: "function",
     function: {
       name: TOOL_NAMES.search,
-      description: "Search this customer's past conversations, actions and system events by meaning and keywords. Use it when the customer refers to something that happened before and the details are not in the customer context you already have. Do not use it for facts already listed there. The result also says how often the same kind of issue came back. To read one result in full, call open_history_item.",
+      description: "Search this customer's past conversations, actions and business objects by meaning and keywords. Use it when the customer refers to something that happened before and the details are not in the customer context you already have. Do not use it for facts already listed there. The result also says how often the same kind of issue came back. To read one result in full, call open_history_item.",
       parameters: {
         type: "object",
         properties: {
@@ -1215,7 +1315,7 @@ var TOOL_DEFINITIONS = [
     type: "function",
     function: {
       name: TOOL_NAMES.timeline,
-      description: "List this customer's history in chronological order, one line per item. Use it when you need the sequence of events, for example what happened since a given date. Prefer search_customer_history when you are looking for something specific.",
+      description: "List this customer's history, newest first, one line per item. Use it when you need the sequence of events, for example what happened since a given date. Prefer search_customer_history when you are looking for something specific.",
       parameters: {
         type: "object",
         properties: {
@@ -1309,7 +1409,7 @@ function bindTools(subject, binding, navigator, strict) {
       case TOOL_NAMES.open: {
         const id = str(args, "id");
         if (!id) throw new NiadraValidationError("open_history_item needs an id");
-        return navigator.open(id, binding, voice);
+        return navigator.open(id, subject, binding, voice);
       }
       default:
         throw new NiadraValidationError(`unknown tool: ${name}`);
@@ -1348,7 +1448,7 @@ function cloneDefinition(definition) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 
 // src/transport.ts
 var RETRYABLE_WRITE_STATUS = /* @__PURE__ */ new Set([408, 421, 429, 500, 502, 503, 504]);
@@ -1401,13 +1501,17 @@ var Transport = class {
     );
   }
   async retrying(timeoutMs, policy, signal, attempt) {
-    for (let count = 1; ; count++) {
-      const deadline = new Deadline(timeoutMs, signal);
+    const end = policy.totalMs === void 0 ? Number.POSITIVE_INFINITY : Date.now() + policy.totalMs;
+    for (let count2 = 1; ; count2++) {
+      const left = end - Date.now();
+      if (left <= 0) throw new NiadraTimeoutError(policy.totalMs ?? timeoutMs);
+      const deadline = new Deadline(Math.min(timeoutMs, left), signal);
       try {
         return await attempt(deadline);
       } catch (error) {
-        if (count >= policy.maxAttempts || !isTransient(error)) throw error;
-        const delay = retryDelay(error, count, policy.baseDelayMs, policy.maxDelayMs);
+        if (count2 >= policy.maxAttempts || !isTransient(error)) throw error;
+        const delay = retryDelay(error, count2, policy.baseDelayMs, policy.maxDelayMs);
+        if (Date.now() + delay >= end) throw error;
         await sleep(delay, signal);
       } finally {
         deadline.clear();
@@ -1558,9 +1662,13 @@ function sleep(ms, signal) {
 
 // src/client.ts
 function readEnv(name) {
-  const env = globalThis.process?.env;
-  const value = env?.[name];
-  return value === "" ? void 0 : value;
+  try {
+    const env = globalThis.process?.env;
+    const value = env?.[name];
+    return value === "" ? void 0 : value;
+  } catch {
+    return void 0;
+  }
 }
 function describe(error) {
   if (error instanceof NiadraAPIError) {
@@ -1700,7 +1808,7 @@ var Niadra = class {
       return this.readSpec("POST", "/v1/history/search", params, this.timeouts.navigation, options);
     });
   }
-  /** The customer's history in chronological order, one line per item, paginated by cursor. */
+  /** The customer's history, newest first, one line per item, paginated by cursor. */
   async timeline(params, options = {}) {
     return this.navigate(
       () => this.readSpec("POST", "/v1/history/timeline", params, this.timeouts.navigation, options)
@@ -1708,20 +1816,17 @@ var Niadra = class {
   }
   /**
    * Opens one history item from `search()` or `timeline()`: summary, request, commitments,
-   * outcome and resolution. The literal transcript excerpt only comes back to keys with an
-   * elevated scope.
+   * outcome and resolution. Sent as `POST /v1/history/open`: the conversation id and `subject` go
+   * in the body, never in a URL.
    */
   async open(id, params = {}, options = {}) {
     return this.navigate(() => {
       if (!id) throw new NiadraValidationError("open() needs an item id");
-      const path = `/v1/history/items/${encodeURIComponent(id)}`;
-      const spec = this.readSpec("GET", path, void 0, this.timeouts.navigation, options);
-      spec.query = {
-        verification: params.verification,
-        conversation_id: params.conversation_id,
-        task_id: params.task_id
-      };
-      return spec;
+      const body = { item_id: id };
+      if (params.subject) body.subject = params.subject;
+      if (params.verification) body.verification = params.verification;
+      if (params.conversation_id) body.conversation_id = params.conversation_id;
+      return this.readSpec("POST", "/v1/history/open", body, this.timeouts.navigation, options);
     });
   }
   /**
@@ -1762,11 +1867,10 @@ var Niadra = class {
     const navigator = {
       search: (params, voice) => this.search(params, this.voiceBudget(voice)),
       timeline: (params, voice) => this.timeline(params, this.voiceBudget(voice)),
-      open: (id, bound, voice) => {
-        const scope = {};
+      open: (id, customer, bound, voice) => {
+        const scope = { subject: customer };
         if (bound.verification) scope.verification = bound.verification;
         if (bound.conversation_id) scope.conversation_id = bound.conversation_id;
-        if (bound.task_id) scope.task_id = bound.task_id;
         return this.open(id, scope, this.voiceBudget(voice));
       }
     };
@@ -1829,7 +1933,7 @@ var Niadra = class {
         body: request,
         headers: { "idempotency-key": key },
         timeoutMs: this.timeouts.write,
-        retry: core.writes
+        retry: { ...core.writes, totalMs: this.timeouts.write }
       });
       const [rejected] = response.data?.errors ?? [];
       if (rejected) {
@@ -1860,7 +1964,7 @@ var Niadra = class {
         path: "/v1/media/uploads",
         body: request,
         timeoutMs: this.timeouts.write,
-        retry: core.writes,
+        retry: { ...core.writes, totalMs: this.timeouts.write },
         signal: options.signal
       });
       const media_ref = reserved.data?.media_ref;
@@ -1873,7 +1977,7 @@ var Niadra = class {
           body: bytes,
           headers: uploadHeaders(reserved.data?.upload_headers, request.content_type),
           timeoutMs: this.timeouts.upload,
-          retry: core.writes,
+          retry: { ...core.writes, totalMs: this.timeouts.upload },
           signal: options.signal
         });
       }
@@ -2060,11 +2164,20 @@ var Niadra = class {
     }
     return new Promise((resolve, reject) => {
       const key = item.idempotency_key;
-      core.queue.push(item, (error) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        this.logger.warn(`write not confirmed within ${this.timeouts.write} ms; it stays queued`);
+        settle(new NiadraTimeoutError(this.timeouts.write));
+      }, this.timeouts.write);
+      const settle = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
         if (!error) resolve({ ok: true, idempotency_key: key, error: null });
         else if (this.strict) reject(error);
         else resolve({ ok: false, idempotency_key: key, error });
-      });
+      };
+      core.queue.push(item, settle);
       core.queue.flushInBackground();
     });
   }
@@ -2251,22 +2364,22 @@ var Answer = class {
   parsed(value) {
     try {
       if (!this.stream) {
-        this.record(messageText(value));
+        this.record(messageText(value), modelUsage(value));
         return value;
       }
-      return isAsyncIterable(value) ? captureStream(value, (text) => {
-        this.record(text);
+      return isAsyncIterable(value) ? captureStream(value, (text, usage) => {
+        this.record(text, usage);
       }) : value;
     } catch (error) {
       this.session.logger.warn(`could not capture the model's answer (${errorName(error)})`);
       return value;
     }
   }
-  record(text) {
+  record(text, usage) {
     if (this.recorded || !text) return;
     this.recorded = true;
     try {
-      this.session.agent(text);
+      this.session.agent(text, usage ? { usage } : {});
     } catch (error) {
       this.session.logger.warn(`could not record the model's answer (${errorName(error)})`);
     }
@@ -2274,11 +2387,19 @@ var Answer = class {
 };
 function captureStream(stream, done) {
   const parts = [];
+  let usage = null;
+  let model;
   let finished = false;
+  const observe = (chunk) => {
+    const reported = property(chunk, "usage");
+    if (isRecord(reported)) usage = reported;
+    const name = property(chunk, "model");
+    if (typeof name === "string" && name) model = name;
+  };
   const finish = () => {
     if (finished) return;
     finished = true;
-    done(parts.join(""));
+    done(parts.join(""), usage ? modelUsage(usage, model ? { model } : {}) : null);
   };
   return new Proxy(stream, {
     get(target, prop) {
@@ -2290,7 +2411,10 @@ function captureStream(stream, done) {
               try {
                 const step = await inner.next();
                 if (step.done) finish();
-                else parts.push(deltaText(step.value));
+                else {
+                  parts.push(deltaText(step.value));
+                  observe(step.value);
+                }
                 return step;
               } catch (error) {
                 finish();
@@ -2350,6 +2474,6 @@ function errorName(error) {
   return error instanceof Error ? error.name : typeof error;
 }
 
-export { Conversation, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, TOOL_DEFINITIONS, TOOL_NAMES, Task, VERSION, baseURLFromKey, consoleLogger, handles, injectContext, parseApiKey, renderLive, renderSuffix, silentLogger, toObjectRef, uuidv7, wrap };
+export { Conversation, DEFAULT_CACHE, DEFAULT_QUEUE, DEFAULT_TIMEOUTS, MAX_BATCH_ITEMS, MAX_EVENT_TEXT, MAX_MEDIA_BYTES, Niadra, NiadraAPIError, NiadraAbortError, NiadraAuthenticationError, NiadraConfigError, NiadraConnectionError, NiadraError, NiadraPermissionError, NiadraRateLimitError, NiadraTimeoutError, NiadraValidationError, TOOL_DEFINITIONS, TOOL_NAMES, Task, VERSION, baseURLFromKey, consoleLogger, handles, injectContext, modelUsage, parseApiKey, providerOf, renderLive, renderSuffix, silentLogger, toObjectRef, tokenCounts, uuidv7, wrap };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map