@telemai/sdk 0.2.5 → 0.3.0

package/README.md

@@ -204,17 +204,14 @@ A monitor runs a query on a schedule. Poll it to get the results that are new si
 your last poll. `poll` returns a `SearchResponse`:
 
 ```ts
-const monitor = await telem.monitors.create("Nvidia files a new 8-K with the SEC", {
-  providers: ["exa", "parallel"],
-  frequency: "1h",
-})
+const monitor = await telem.monitors.create("Nvidia files a new 8-K with the SEC", { frequency: "1h" })
 const response = await telem.monitors.poll(monitor.id)
 await telem.monitors.update(monitor.id, { status: "paused" })
 await telem.monitors.delete(monitor.id)
 ```
 
 `telem.monitors` also has `get` and `list`. See [Monitors](https://docs.telem.ai/resources/monitors/)
-for the fields, the costs and the errors.
+for the fields and the errors.
 
 ## Vercel AI SDK
 

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.3.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -702,10 +703,12 @@ function monitorFrom(body) {
     id: String(data.id ?? ""),
     query: data.query ?? "",
     frequency: data.frequency ?? "",
-    providers: asArray(data.providers).filter(isObject).map((p) => ({ name: String(p.name ?? ""), status: String(p.status ?? "") })),
+    status: String(data.status ?? ""),
     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
   };
 }
@@ -715,16 +718,11 @@ function createMonitors(config) {
     return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
   };
   return {
-    /** Create a monitor. Each provider runs `query` on the schedule. */
+    /** Create a monitor. Telem runs `query` on the schedule. */
     async create(query, options) {
-      const body = {
-        query,
-        options: { providers: { include: options.providers }, frequency: options.frequency }
-      };
-      if (options.providerOverrides !== void 0) {
-        body.options.provider_overrides = options.providerOverrides;
-      }
+      const body = { query, options: { frequency: options.frequency } };
       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);
     },
@@ -743,7 +741,7 @@ function createMonitors(config) {
       const body = {};
       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 +760,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 +921,7 @@ var index_default = Telem;
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 });

package/dist/index.d.cts

@@ -224,23 +224,21 @@ type SessionsResource = {
 };
 /** Options for `monitors.create`. */
 type MonitorCreateOptions = {
-    /** One or more provider names, for example `["exa", "parallel"]`. */
-    providers: string[];
     /** `"1h"`, `"6h"`, `"1d"` or `"7d"`. */
     frequency: string;
-    /** Per-provider create fields, keyed by provider name. */
-    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`. */
@@ -251,21 +249,19 @@ type MonitorPollOptions = {
     metadata?: Json;
     signal?: AbortSignal;
 };
-/** One provider of a monitor. `status` is `active`, `paused` (you paused it) or
- *  `idle` (paused because nobody polled; the next poll resumes it). */
-type MonitorProvider = {
-    name: string;
-    status: string;
-};
-/** A monitor: a query that providers run on a schedule. */
+/** A monitor: a query that Telem runs on a schedule. */
 type Monitor = {
     id: string;
     query: string;
     frequency: string;
-    providers: MonitorProvider[];
+    /** `active` or `paused` (you paused it). */
+    status: string;
     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 +319,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 +455,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 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

@@ -224,23 +224,21 @@ type SessionsResource = {
 };
 /** Options for `monitors.create`. */
 type MonitorCreateOptions = {
-    /** One or more provider names, for example `["exa", "parallel"]`. */
-    providers: string[];
     /** `"1h"`, `"6h"`, `"1d"` or `"7d"`. */
     frequency: string;
-    /** Per-provider create fields, keyed by provider name. */
-    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`. */
@@ -251,21 +249,19 @@ type MonitorPollOptions = {
     metadata?: Json;
     signal?: AbortSignal;
 };
-/** One provider of a monitor. `status` is `active`, `paused` (you paused it) or
- *  `idle` (paused because nobody polled; the next poll resumes it). */
-type MonitorProvider = {
-    name: string;
-    status: string;
-};
-/** A monitor: a query that providers run on a schedule. */
+/** A monitor: a query that Telem runs on a schedule. */
 type Monitor = {
     id: string;
     query: string;
     frequency: string;
-    providers: MonitorProvider[];
+    /** `active` or `paused` (you paused it). */
+    status: string;
     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 +319,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 +455,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 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.3.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -336,10 +336,12 @@ function monitorFrom(body) {
     id: String(data.id ?? ""),
     query: data.query ?? "",
     frequency: data.frequency ?? "",
-    providers: asArray(data.providers).filter(isObject).map((p) => ({ name: String(p.name ?? ""), status: String(p.status ?? "") })),
+    status: String(data.status ?? ""),
     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
   };
 }
@@ -349,16 +351,11 @@ function createMonitors(config) {
     return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
   };
   return {
-    /** Create a monitor. Each provider runs `query` on the schedule. */
+    /** Create a monitor. Telem runs `query` on the schedule. */
     async create(query, options) {
-      const body = {
-        query,
-        options: { providers: { include: options.providers }, frequency: options.frequency }
-      };
-      if (options.providerOverrides !== void 0) {
-        body.options.provider_overrides = options.providerOverrides;
-      }
+      const body = { query, options: { frequency: options.frequency } };
       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);
     },
@@ -377,7 +374,7 @@ function createMonitors(config) {
       const body = {};
       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 +393,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 +554,7 @@ export {
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 };

package/package.json

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