@channlize/core 0.5.0 → 0.6.0

package/dist/index.js

@@ -31,6 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AGENT_DELIVERY_MODES: () => AGENT_DELIVERY_MODES,
+  AGENT_EXPORT_FORMATS: () => AGENT_EXPORT_FORMATS,
+  AGENT_EXPORT_KINDS: () => AGENT_EXPORT_KINDS,
+  AGENT_EXPORT_SYNC_MAX_ROWS: () => AGENT_EXPORT_SYNC_MAX_ROWS,
   AGENT_MESSAGE_TYPES: () => AGENT_MESSAGE_TYPES,
   AGENT_POLICY_CODES: () => AGENT_POLICY_CODES,
   AGENT_STATUSES: () => AGENT_STATUSES,
@@ -40,6 +43,7 @@ __export(index_exports, {
   AgentTaskError: () => AgentTaskError,
   AgentThreadPausedError: () => AgentThreadPausedError,
   AuthenticationError: () => AuthenticationError,
+  COST_GROUPINGS: () => COST_GROUPINGS,
   ChannlizeClient: () => ChannlizeClient,
   ChannlizeError: () => ChannlizeError,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
@@ -71,9 +75,11 @@ __export(index_exports, {
   parseAgentWebhook: () => parseAgentWebhook,
   parseAgentWebhookEvent: () => parseAgentWebhookEvent,
   parseApiError: () => parseApiError,
+  parseTelemetryWebhook: () => parseTelemetryWebhook,
   readChannlizeEnv: () => readChannlizeEnv,
   retryAfter: () => retryAfter,
-  verifyAgentWebhook: () => verifyAgentWebhook
+  verifyAgentWebhook: () => verifyAgentWebhook,
+  verifyTelemetryWebhook: () => verifyTelemetryWebhook
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -260,6 +266,21 @@ function retryAfter(error, now = Date.now()) {
 
 // src/http.ts
 async function requestJson(http, endpoint, options = {}) {
+  return send(
+    http,
+    endpoint,
+    options,
+    async (res) => await res.json()
+  );
+}
+async function requestText(http, endpoint, options = {}) {
+  return send(http, endpoint, options, async (res) => ({
+    body: await res.text(),
+    status: res.status,
+    headers: res.headers
+  }));
+}
+async function send(http, endpoint, options, read) {
   const url = `${http.baseUrl}${endpoint}`;
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), http.timeout);
@@ -284,8 +305,7 @@ async function requestJson(http, endpoint, options = {}) {
     if (!response.ok) {
       await handleErrorResponse(response);
     }
-    const data = await response.json();
-    return data;
+    return await read(response);
   } catch (error) {
     clearTimeout(timeoutId);
     if (error instanceof ChannlizeError) {
@@ -927,6 +947,270 @@ function isTaskHandoffMessage(message) {
   );
 }
 
+// src/agents-observability.ts
+var enc2 = encodeURIComponent;
+function day(v) {
+  return v instanceof Date ? v.toISOString().slice(0, 10) : v;
+}
+function iso2(v) {
+  return v instanceof Date ? v.toISOString() : v;
+}
+function list(v) {
+  return Array.isArray(v) ? v.join(",") : v;
+}
+function need2(value, what, field) {
+  if (typeof value !== "string" || !value) {
+    throw new ValidationError(`${what} is required`, field);
+  }
+}
+function exportFilterFields(f = {}) {
+  return {
+    from: iso2(f.from),
+    to: iso2(f.to),
+    agent_id: f.agentId,
+    channel_id: f.channelId,
+    thread_id: f.threadId,
+    type: f.type,
+    status: list(f.status),
+    action: f.action,
+    actor_type: f.actorType,
+    actor_id: f.actorId,
+    target_type: f.targetType,
+    target_id: f.targetId
+  };
+}
+function defined(o) {
+  return Object.fromEntries(
+    Object.entries(o).filter(([, v]) => v !== void 0)
+  );
+}
+function filenameOf(disposition) {
+  const m = disposition ? /filename="?([^";]+)"?/i.exec(disposition) : null;
+  return m ? m[1] : null;
+}
+async function* paginate(page, max) {
+  const limit = max ?? Infinity;
+  if (limit <= 0) return;
+  let cursor;
+  let seen = 0;
+  for (; ; ) {
+    const r = await page(cursor);
+    for (const item of r.items) {
+      yield item;
+      if (++seen >= limit) return;
+    }
+    if (!r.nextCursor || r.nextCursor === cursor) return;
+    cursor = r.nextCursor;
+  }
+}
+function createAgentsObservability(request, requestText2) {
+  const safely = (fn) => {
+    try {
+      return fn();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  };
+  const rangeQuery = (f = {}) => ({
+    from: day(f.from),
+    to: day(f.to),
+    channel_id: f.channelId,
+    agent_id: f.agentId
+  });
+  function edge(source, target, options = {}) {
+    return safely(async () => {
+      need2(source, "The source node id", "source");
+      need2(target, "The target node id", "target");
+      const r = await request("GET", "/v1/agents/insights/graph/edge", {
+        query: {
+          source,
+          target,
+          from: day(options.from),
+          to: day(options.to),
+          channel_id: options.channelId,
+          cursor: options.cursor,
+          limit: options.limit
+        }
+      });
+      return {
+        range: r.range,
+        source: r.source,
+        target: r.target,
+        threads: r.threads ?? [],
+        nextCursor: r.next_cursor ?? null
+      };
+    });
+  }
+  function search(options) {
+    return safely(async () => {
+      if (!options || typeof options.q !== "string" || options.q.trim().length < 2) {
+        throw new ValidationError("search needs q, at least 2 characters", "q");
+      }
+      const r = await request("GET", "/v1/agents/search", {
+        query: {
+          q: options.q,
+          agent_id: options.agentId,
+          channel_id: options.channelId,
+          type: options.type,
+          include: list(options.include),
+          from: iso2(options.from),
+          to: iso2(options.to),
+          cursor: options.cursor,
+          limit: options.limit
+        }
+      });
+      return {
+        results: r.results ?? [],
+        nextCursor: r.next_cursor ?? null,
+        window: r.window
+      };
+    });
+  }
+  return {
+    insights: {
+      graph(filters = {}) {
+        return request("GET", "/v1/agents/insights/graph", {
+          query: {
+            ...rangeQuery(filters),
+            team_id: filters.teamId,
+            limit: filters.limit,
+            edge_limit: filters.edgeLimit
+          }
+        });
+      },
+      edge,
+      edgeAll(source, target, options = {}) {
+        const { max, ...rest } = options;
+        return paginate(async (cursor) => {
+          const page = await edge(source, target, { ...rest, cursor });
+          return { items: page.threads, nextCursor: page.nextCursor };
+        }, max);
+      },
+      cost(options = {}) {
+        return request("GET", "/v1/agents/insights/cost", {
+          query: {
+            ...rangeQuery(options),
+            group_by: options.groupBy,
+            team_id: options.teamId,
+            limit: options.limit
+          }
+        });
+      },
+      metrics(filters = {}) {
+        return request("GET", "/v1/agents/insights/metrics", {
+          query: rangeQuery(filters)
+        });
+      }
+    },
+    search,
+    searchAll(options) {
+      const { max, ...rest } = options ?? {};
+      return paginate(async (cursor) => {
+        const page = await search({ ...rest, cursor });
+        return { items: page.results, nextCursor: page.nextCursor };
+      }, max);
+    },
+    exports: {
+      download(kind, format = "csv", filters = {}) {
+        return safely(async () => {
+          need2(kind, "The export kind", "kind");
+          const res = await requestText2("/v1/agents/export", {
+            query: { kind, format, ...exportFilterFields(filters) }
+          });
+          return {
+            body: res.body,
+            rows: Number(res.headers.get("x-export-rows") ?? 0) || 0,
+            truncated: res.headers.get("x-export-truncated") === "true",
+            contentType: res.headers.get("content-type") ?? "",
+            filename: filenameOf(res.headers.get("content-disposition"))
+          };
+        });
+      },
+      start(input) {
+        return safely(async () => {
+          need2(input?.kind, "The export kind", "kind");
+          const r = await request("POST", "/v1/agents/export", {
+            body: {
+              kind: input.kind,
+              format: input.format,
+              filters: defined(exportFilterFields(input.filters))
+            }
+          });
+          return { exportId: r.export_id, status: r.status, export: r.export };
+        });
+      },
+      get(exportId) {
+        return safely(async () => {
+          need2(exportId, "The export id", "exportId");
+          const r = await request(
+            "GET",
+            `/v1/agents/export/${enc2(exportId)}`
+          );
+          return r.export;
+        });
+      },
+      async list(options = {}) {
+        const r = await request(
+          "GET",
+          "/v1/agents/export",
+          { query: { limit: options.limit } }
+        );
+        return r.exports ?? [];
+      }
+    },
+    telemetry: {
+      async getOtel() {
+        return (await request("GET", "/v1/agents/telemetry/otel")).otel;
+      },
+      async setOtel(input) {
+        const r = await request(
+          "PUT",
+          "/v1/agents/telemetry/otel",
+          {
+            body: {
+              enabled: input?.enabled,
+              endpoint_url: input?.endpointUrl,
+              headers: input?.headers
+            }
+          }
+        );
+        return r.otel;
+      },
+      testOtel() {
+        return request(
+          "POST",
+          "/v1/agents/telemetry/otel/test"
+        );
+      },
+      async getWebhook() {
+        return (await request(
+          "GET",
+          "/v1/agents/telemetry/webhook"
+        )).webhook;
+      },
+      setWebhook(input) {
+        return request(
+          "PUT",
+          "/v1/agents/telemetry/webhook",
+          {
+            body: {
+              enabled: input?.enabled,
+              url: input?.url,
+              rotate_secret: input?.rotateSecret
+            }
+          }
+        );
+      },
+      testWebhook() {
+        return request(
+          "POST",
+          "/v1/agents/telemetry/webhook/test"
+        );
+      }
+    }
+  };
+}
+
 // src/agents.ts
 function resolve(config) {
   const env = readChannlizeEnv();
@@ -953,7 +1237,7 @@ function resolve(config) {
     timeout: config.timeout ?? DEFAULT_TIMEOUT
   };
 }
-var enc2 = encodeURIComponent;
+var enc3 = encodeURIComponent;
 function isFatal(error) {
   return error instanceof ChannlizeError && [400, 401, 403, 404].includes(error.statusCode ?? 0);
 }
@@ -986,6 +1270,17 @@ function createAgentsClient(config = {}) {
     });
     return res;
   };
+  const fetchText = (path, options = {}) => {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(options.query ?? {})) {
+      if (v !== void 0 && v !== "") params.set(k, String(v));
+    }
+    const qs = params.toString();
+    return requestText(cfg, `${path}${qs ? `?${qs}` : ""}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${cfg.apiKey}` }
+    });
+  };
   function agentFor(agentId, what) {
     const id = agentId ?? cfg.agentId;
     if (!id) {
@@ -998,7 +1293,7 @@ function createAgentsClient(config = {}) {
   }
   async function inbox(agentId, options = {}) {
     const id = agentFor(agentId, "inbox");
-    const r = await request("GET", `/v1/agents/${enc2(id)}/inbox`, {
+    const r = await request("GET", `/v1/agents/${enc3(id)}/inbox`, {
       query: { cursor: options.cursor, limit: options.limit }
     });
     return {
@@ -1018,7 +1313,7 @@ function createAgentsClient(config = {}) {
         "ids"
       );
     }
-    return request("POST", `/v1/agents/${enc2(id)}/inbox/ack`, {
+    return request("POST", `/v1/agents/${enc3(id)}/inbox/ack`, {
       body
     });
   }
@@ -1073,6 +1368,7 @@ function createAgentsClient(config = {}) {
   });
   return {
     ...createAgentsGovernance(request, cfg.agentId),
+    ...createAgentsObservability(request, fetchText),
     agentId: cfg.agentId,
     send(input) {
       if (!input || typeof input.channel !== "string" || !input.channel) {
@@ -1106,7 +1402,7 @@ function createAgentsClient(config = {}) {
       return r.agents ?? [];
     },
     get(agentId) {
-      return request("GET", `/v1/agents/${enc2(agentId)}`);
+      return request("GET", `/v1/agents/${enc3(agentId)}`);
     },
     channels: {
       async list(options = {}) {
@@ -1118,20 +1414,20 @@ function createAgentsClient(config = {}) {
         return r.channels ?? [];
       },
       get(channelId, options) {
-        return request("GET", `/v1/agents/channels/${enc2(channelId)}`, {
+        return request("GET", `/v1/agents/channels/${enc3(channelId)}`, {
           query: channelRead(options)
         });
       },
       async members(channelId, options) {
         const r = await request(
           "GET",
-          `/v1/agents/channels/${enc2(channelId)}/members`,
+          `/v1/agents/channels/${enc3(channelId)}/members`,
           { query: channelRead(options) }
         );
         return r.members ?? [];
       },
       async messages(channelId, options = {}) {
-        const r = await request("GET", `/v1/agents/channels/${enc2(channelId)}/messages`, {
+        const r = await request("GET", `/v1/agents/channels/${enc3(channelId)}/messages`, {
           query: {
             ...channelRead(options),
             cursor: options.cursor,
@@ -1167,7 +1463,7 @@ async function getSubtle() {
   } catch {
   }
   throw new ChannlizeError(
-    "verifyAgentWebhook needs the Web Crypto API (globalThis.crypto.subtle, or node:crypto webcrypto on Node.js 18)"
+    "Webhook signature checks need the Web Crypto API (globalThis.crypto.subtle, or node:crypto webcrypto on Node.js 18)"
   );
 }
 function hexToBytes(hex) {
@@ -1189,6 +1485,9 @@ function toBytes(body) {
 async function verifyAgentWebhook(rawBody, signatureHeader, secret) {
   if (!secret)
     throw new ValidationError("The agent secret is required", "secret");
+  return verifyHmacSha256(rawBody, signatureHeader, secret);
+}
+async function verifyHmacSha256(rawBody, signatureHeader, secret) {
   const header = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
   const m = /^sha256=([0-9a-f]+)$/i.exec(header?.trim() ?? "");
   const expected = m ? hexToBytes(m[1]) : null;
@@ -1221,6 +1520,26 @@ async function parseAgentWebhookEvent(rawBody, signatureHeader, secret) {
   const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
   return JSON.parse(text);
 }
+async function verifyTelemetryWebhook(rawBody, signatureHeader, secret) {
+  if (!secret) {
+    throw new ValidationError(
+      "The telemetry webhook secret is required",
+      "secret"
+    );
+  }
+  return verifyHmacSha256(rawBody, signatureHeader, secret);
+}
+async function parseTelemetryWebhook(rawBody, signatureHeader, secret) {
+  if (!await verifyTelemetryWebhook(rawBody, signatureHeader, secret)) {
+    throw new ChannlizeError(
+      "Invalid telemetry webhook signature",
+      401,
+      "INVALID_SIGNATURE"
+    );
+  }
+  const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+  return JSON.parse(text);
+}
 
 // src/client.ts
 var ChannlizeClient = class {
@@ -1414,9 +1733,9 @@ var ChannlizeClient = class {
    * plan's limit for the billing period) resolves with `success: false`
    * and `dropped` instead of throwing, with one console warning per client.
    */
-  async nonFatalTracking(send) {
+  async nonFatalTracking(send2) {
     try {
-      return await send();
+      return await send2();
     } catch (error) {
       if (!(error instanceof RateLimitError)) throw error;
       const dropped = error.code === "PLAN_LIMIT_REACHED" ? "plan_limit" : "rate_limit";
@@ -1498,9 +1817,29 @@ var AGENT_TASK_STATUSES = [
   "canceled",
   "rejected"
 ];
+
+// src/agents-observability-types.ts
+var COST_GROUPINGS = [
+  "agent",
+  "channel",
+  "team",
+  "task",
+  "day"
+];
+var AGENT_EXPORT_KINDS = [
+  "messages",
+  "tasks",
+  "questions",
+  "audit"
+];
+var AGENT_EXPORT_FORMATS = ["csv", "json"];
+var AGENT_EXPORT_SYNC_MAX_ROWS = 1e4;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_DELIVERY_MODES,
+  AGENT_EXPORT_FORMATS,
+  AGENT_EXPORT_KINDS,
+  AGENT_EXPORT_SYNC_MAX_ROWS,
   AGENT_MESSAGE_TYPES,
   AGENT_POLICY_CODES,
   AGENT_STATUSES,
@@ -1510,6 +1849,7 @@ var AGENT_TASK_STATUSES = [
   AgentTaskError,
   AgentThreadPausedError,
   AuthenticationError,
+  COST_GROUPINGS,
   ChannlizeClient,
   ChannlizeError,
   DEFAULT_BASE_URL,
@@ -1540,8 +1880,10 @@ var AGENT_TASK_STATUSES = [
   parseAgentWebhook,
   parseAgentWebhookEvent,
   parseApiError,
+  parseTelemetryWebhook,
   readChannlizeEnv,
   retryAfter,
-  verifyAgentWebhook
+  verifyAgentWebhook,
+  verifyTelemetryWebhook
 });
 //# sourceMappingURL=index.js.map