@telemai/sdk 0.2.5 → 0.2.6

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   sessionKey: () => sessionKey,
   snapshotNodeKey: () => snapshotNodeKey,
   toolMarker: () => toolMarker,
+  verifyWebhook: () => verifyWebhook,
   windowAnchor: () => windowAnchor,
   withTrajectory: () => withTrajectory
 });
@@ -59,7 +60,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.2.5";
+var VERSION = "0.2.6";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -706,6 +707,8 @@ function monitorFrom(body) {
     sessionId: String(data.session_id ?? ""),
     createdAt: data.created_at ?? "",
     lastPolledAt: data.last_polled_at ?? null,
+    webhookUrl: data.webhook_url ?? null,
+    webhookSecret: data.webhook_secret ?? null,
     raw: data
   };
 }
@@ -725,6 +728,7 @@ function createMonitors(config) {
         body.options.provider_overrides = options.providerOverrides;
       }
       if (options.metadata !== void 0) body.metadata = options.metadata;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit");
       return monitorFrom(data);
     },
@@ -744,6 +748,7 @@ function createMonitors(config) {
       if (options.status !== void 0) body.status = options.status;
       if (options.frequency !== void 0) body.frequency = options.frequency;
       if (options.providerOverrides !== void 0) body.provider_overrides = options.providerOverrides;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       const route = path(monitorId);
       return monitorFrom(await request(config, "PATCH", route, body, options.signal));
     },
@@ -762,6 +767,23 @@ function createMonitors(config) {
     }
   };
 }
+async function verifyWebhook(body, header, secret, toleranceSeconds = 300) {
+  const parts = Object.fromEntries(
+    header.split(",").map((item) => [item.slice(0, item.indexOf("=")), item.slice(item.indexOf("=") + 1)])
+  );
+  const t = parts.t ?? "";
+  const v1 = parts.v1 ?? "";
+  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1e3 - Number(t)) > toleranceSeconds) return false;
+  if (!/^([0-9a-f]{2})+$/.test(v1)) return false;
+  const encoder = new TextEncoder();
+  const raw = typeof body === "string" ? encoder.encode(body) : body;
+  const signed = new Uint8Array([...encoder.encode(`${t}.`), ...raw]);
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "verify"
+  ]);
+  const signature = new Uint8Array(v1.match(/../g).map((byte) => parseInt(byte, 16)));
+  return crypto.subtle.verify("HMAC", key, signature, signed);
+}
 
 // src/methods/providers.ts
 async function providers(config) {
@@ -906,6 +928,7 @@ var index_default = Telem;
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 });

package/dist/index.d.cts

@@ -232,15 +232,19 @@ type MonitorCreateOptions = {
     providerOverrides?: Record<string, Json>;
     /** Request metadata (query lineage keys), sent as given. */
     metadata?: Json;
+    /** An `https` URL that receives the new results. */
+    webhookUrl?: string;
     signal?: AbortSignal;
 };
-/** Options for `monitors.update`. Send at least one of the three fields. */
+/** Options for `monitors.update`. Send at least one field. */
 type MonitorUpdateOptions = {
     /** `"paused"` or `"active"`. */
     status?: string;
     frequency?: string;
     /** New overrides for the providers named. They replace the ones sent before. */
     providerOverrides?: Record<string, Json>;
+    /** A new webhook URL, with a new `webhookSecret` in the response. `null` removes it. */
+    webhookUrl?: string | null;
     signal?: AbortSignal;
 };
 /** Options for `monitors.poll`. */
@@ -266,6 +270,9 @@ type Monitor = {
     sessionId: string;
     createdAt: string;
     lastPolledAt: string | null;
+    webhookUrl: string | null;
+    /** Signs the webhook deliveries. Only in the response that set `webhookUrl`. */
+    webhookSecret: string | null;
     raw: Json;
 };
 /** The `telem.monitors` namespace. */
@@ -323,6 +330,12 @@ declare class TimeoutError extends TelemError {
     constructor(message: string, cause?: unknown);
 }
 
+/**
+ * Check a monitor webhook: the `Telem-Signature` header against the raw body.
+ * True when the signature is correct and not older than `toleranceSeconds`.
+ */
+declare function verifyWebhook(body: string | Uint8Array, header: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
+
 /** Metadata keys the trajectory payload owns. A caller-supplied value for any of
  *  these is dropped rather than allowed to forge identity. */
 declare const RESERVED_METADATA: ReadonlySet<string>;
@@ -453,4 +466,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorProvider, type MonitorUpdateOptions, type MonitorsResource, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, toolMarker, windowAnchor, withTrajectory };
+export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorProvider, type MonitorUpdateOptions, type MonitorsResource, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, toolMarker, verifyWebhook, windowAnchor, withTrajectory };

package/dist/index.d.ts

@@ -232,15 +232,19 @@ type MonitorCreateOptions = {
     providerOverrides?: Record<string, Json>;
     /** Request metadata (query lineage keys), sent as given. */
     metadata?: Json;
+    /** An `https` URL that receives the new results. */
+    webhookUrl?: string;
     signal?: AbortSignal;
 };
-/** Options for `monitors.update`. Send at least one of the three fields. */
+/** Options for `monitors.update`. Send at least one field. */
 type MonitorUpdateOptions = {
     /** `"paused"` or `"active"`. */
     status?: string;
     frequency?: string;
     /** New overrides for the providers named. They replace the ones sent before. */
     providerOverrides?: Record<string, Json>;
+    /** A new webhook URL, with a new `webhookSecret` in the response. `null` removes it. */
+    webhookUrl?: string | null;
     signal?: AbortSignal;
 };
 /** Options for `monitors.poll`. */
@@ -266,6 +270,9 @@ type Monitor = {
     sessionId: string;
     createdAt: string;
     lastPolledAt: string | null;
+    webhookUrl: string | null;
+    /** Signs the webhook deliveries. Only in the response that set `webhookUrl`. */
+    webhookSecret: string | null;
     raw: Json;
 };
 /** The `telem.monitors` namespace. */
@@ -323,6 +330,12 @@ declare class TimeoutError extends TelemError {
     constructor(message: string, cause?: unknown);
 }
 
+/**
+ * Check a monitor webhook: the `Telem-Signature` header against the raw body.
+ * True when the signature is correct and not older than `toleranceSeconds`.
+ */
+declare function verifyWebhook(body: string | Uint8Array, header: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
+
 /** Metadata keys the trajectory payload owns. A caller-supplied value for any of
  *  these is dropped rather than allowed to forge identity. */
 declare const RESERVED_METADATA: ReadonlySet<string>;
@@ -453,4 +466,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorProvider, type MonitorUpdateOptions, type MonitorsResource, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, toolMarker, windowAnchor, withTrajectory };
+export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorProvider, type MonitorUpdateOptions, type MonitorsResource, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, toolMarker, verifyWebhook, windowAnchor, withTrajectory };

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-DKTEG7EY.js";
 
 // src/version.ts
-var VERSION = "0.2.5";
+var VERSION = "0.2.6";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -340,6 +340,8 @@ function monitorFrom(body) {
     sessionId: String(data.session_id ?? ""),
     createdAt: data.created_at ?? "",
     lastPolledAt: data.last_polled_at ?? null,
+    webhookUrl: data.webhook_url ?? null,
+    webhookSecret: data.webhook_secret ?? null,
     raw: data
   };
 }
@@ -359,6 +361,7 @@ function createMonitors(config) {
         body.options.provider_overrides = options.providerOverrides;
       }
       if (options.metadata !== void 0) body.metadata = options.metadata;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit");
       return monitorFrom(data);
     },
@@ -378,6 +381,7 @@ function createMonitors(config) {
       if (options.status !== void 0) body.status = options.status;
       if (options.frequency !== void 0) body.frequency = options.frequency;
       if (options.providerOverrides !== void 0) body.provider_overrides = options.providerOverrides;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       const route = path(monitorId);
       return monitorFrom(await request(config, "PATCH", route, body, options.signal));
     },
@@ -396,6 +400,23 @@ function createMonitors(config) {
     }
   };
 }
+async function verifyWebhook(body, header, secret, toleranceSeconds = 300) {
+  const parts = Object.fromEntries(
+    header.split(",").map((item) => [item.slice(0, item.indexOf("=")), item.slice(item.indexOf("=") + 1)])
+  );
+  const t = parts.t ?? "";
+  const v1 = parts.v1 ?? "";
+  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1e3 - Number(t)) > toleranceSeconds) return false;
+  if (!/^([0-9a-f]{2})+$/.test(v1)) return false;
+  const encoder = new TextEncoder();
+  const raw = typeof body === "string" ? encoder.encode(body) : body;
+  const signed = new Uint8Array([...encoder.encode(`${t}.`), ...raw]);
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "verify"
+  ]);
+  const signature = new Uint8Array(v1.match(/../g).map((byte) => parseInt(byte, 16)));
+  return crypto.subtle.verify("HMAC", key, signature, signed);
+}
 
 // src/methods/providers.ts
 async function providers(config) {
@@ -540,6 +561,7 @@ export {
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemai/sdk",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",