@telemai/sdk 0.2.4 → 0.2.6

package/README.md

@@ -198,6 +198,24 @@ console.log(summary.query, summary.goal, summary.context)
 `results` returns the query, the goal and the context of the session, plus the
 results of each search step.
 
+## Monitors
+
+A monitor runs a query on a schedule. Poll it to get the results that are new since
+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 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.
+
 ## Vercel AI SDK
 
 If your agent runs on the Vercel AI SDK, `@telemai/sdk/vercel` gives it

package/dist/{chunk-RYY4S5LP.js → chunk-DKTEG7EY.js}

@@ -107,7 +107,7 @@ function retryDelay(retryAfter, attempt) {
   }
   return backoff(attempt);
 }
-async function request(config, method, path, body, abort) {
+async function request(config, method, path, body, abort, retry = "all") {
   const url = `${config.baseUrl}/${path.replace(/^\/+/, "")}`;
   const headers = { "User-Agent": config.userAgent };
   if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
@@ -172,14 +172,15 @@ async function request(config, method, path, body, abort) {
         if (signal?.aborted) {
           throw new TimeoutError(`request to ${url} timed out after ${config.timeoutMs}ms`, cause);
         }
-        if (attempt >= config.maxRetries) throw connectionError(url, cause);
+        if (retry === "rate_limit" || attempt >= config.maxRetries) throw connectionError(url, cause);
         await pause(backoff(attempt));
         continue;
       } finally {
         signal?.removeEventListener("abort", onAbort2);
       }
       if (received.status >= 200 && received.status < 300) return received.body;
-      if (isRetryable(received.status) && attempt < config.maxRetries) {
+      const retryable = retry === "rate_limit" ? received.status === 429 : isRetryable(received.status);
+      if (retryable && attempt < config.maxRetries) {
         await pause(retryDelay(received.retryAfter, attempt));
         continue;
       }

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.4";
+var VERSION = "0.2.6";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -250,7 +251,7 @@ function retryDelay(retryAfter, attempt) {
   }
   return backoff(attempt);
 }
-async function request(config, method, path, body, abort) {
+async function request(config, method, path, body, abort, retry = "all") {
   const url = `${config.baseUrl}/${path.replace(/^\/+/, "")}`;
   const headers = { "User-Agent": config.userAgent };
   if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
@@ -315,14 +316,15 @@ async function request(config, method, path, body, abort) {
         if (signal?.aborted) {
           throw new TimeoutError(`request to ${url} timed out after ${config.timeoutMs}ms`, cause);
         }
-        if (attempt >= config.maxRetries) throw connectionError(url, cause);
+        if (retry === "rate_limit" || attempt >= config.maxRetries) throw connectionError(url, cause);
         await pause(backoff(attempt));
         continue;
       } finally {
         signal?.removeEventListener("abort", onAbort2);
       }
       if (received.status >= 200 && received.status < 300) return received.body;
-      if (isRetryable(received.status) && attempt < config.maxRetries) {
+      const retryable = retry === "rate_limit" ? received.status === 429 : isRetryable(received.status);
+      if (retryable && attempt < config.maxRetries) {
         await pause(retryDelay(received.retryAfter, attempt));
         continue;
       }
@@ -547,21 +549,6 @@ async function fetchUrls(config, url, options) {
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
-// src/methods/providers.ts
-async function providers(config) {
-  const body = await request(config, "GET", "/v1/preprocessors");
-  return asArray(asObject(body).preprocessors).filter(isObject).map((entry) => ({
-    name: entry.name ?? "",
-    type: entry.type ?? "",
-    activeByDefault: entry.active_by_default ?? false,
-    description: entry.description ?? null,
-    method: entry.method ?? null,
-    url: entry.url ?? null,
-    normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
-  }));
-}
-
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
 function searchBlock(defaults, options) {
@@ -709,6 +696,110 @@ async function search(config, query, options) {
   return buildSearchResponse(data);
 }
 
+// src/methods/monitors.ts
+function monitorFrom(body) {
+  const data = asObject(body);
+  return {
+    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 ?? "") })),
+    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
+  };
+}
+function createMonitors(config) {
+  const path = (monitorId, suffix = "") => {
+    if (!monitorId || /^\.+$/.test(monitorId)) throw invalidRequest("a monitor id is required");
+    return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
+  };
+  return {
+    /** Create a monitor. Each provider 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;
+      }
+      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);
+    },
+    /** List your monitors, newest first (server default 50, maximum 200). */
+    async list(options = {}) {
+      const query = options.limit === void 0 ? "" : `?limit=${options.limit}`;
+      const body = await request(config, "GET", `/v1/monitors${query}`, void 0, options.signal);
+      return asArray(asObject(body).monitors).map(monitorFrom);
+    },
+    /** Get one monitor. */
+    async get(monitorId, options = {}) {
+      return monitorFrom(await request(config, "GET", path(monitorId), void 0, options.signal));
+    },
+    /** Pause, resume or change a monitor. Only the fields given are sent. */
+    async update(monitorId, options) {
+      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));
+    },
+    /** Get the results that are new since the last poll, one entry per provider. */
+    async poll(monitorId, options = {}) {
+      const body = {};
+      if (options.session !== void 0) body.session_id = options.session;
+      if (options.metadata !== void 0) body.metadata = options.metadata;
+      const route = path(monitorId, "/poll");
+      const data = await request(config, "POST", route, body, options.signal, "rate_limit");
+      return buildSearchResponse(data);
+    },
+    /** Delete a monitor. A repeat deletes what a failed delete left. */
+    async delete(monitorId, options = {}) {
+      await request(config, "DELETE", path(monitorId), void 0, options.signal);
+    }
+  };
+}
+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) {
+  const body = await request(config, "GET", "/v1/preprocessors");
+  return asArray(asObject(body).preprocessors).filter(isObject).map((entry) => ({
+    name: entry.name ?? "",
+    type: entry.type ?? "",
+    activeByDefault: entry.active_by_default ?? false,
+    description: entry.description ?? null,
+    method: entry.method ?? null,
+    url: entry.url ?? null,
+    normalized: entry.normalized ?? false,
+    tiers: asArray(entry.tiers)
+  }));
+}
+
 // src/methods/sessions.ts
 function sessionsFrom(body) {
   return asArray(asObject(body).sessions).filter(isObject).map((entry) => ({
@@ -774,6 +865,8 @@ var Telem = class {
   maxRetries;
   /** The session read surface: `list` and `results(id)`. */
   sessions;
+  /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+  monitors;
   #config;
   /**
    * @param options - An API key string, or an options object. Anything left unset
@@ -788,6 +881,7 @@ var Telem = class {
     this.timeoutMs = config.timeoutMs;
     this.maxRetries = config.maxRetries;
     this.sessions = createSessions(config);
+    this.monitors = createMonitors(config);
   }
   /**
    * Run a web search.
@@ -834,6 +928,7 @@ var index_default = Telem;
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 });

package/dist/index.d.cts

@@ -222,6 +222,75 @@ type SessionsResource = {
     list(): Promise<SessionSummary[]>;
     results(sessionId: string): Promise<SessionResults>;
 };
+/** 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 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`. */
+type MonitorPollOptions = {
+    /** Record this poll in another session (default: the monitor's own). */
+    session?: string;
+    /** Request metadata (query lineage keys), sent as given. */
+    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. */
+type Monitor = {
+    id: string;
+    query: string;
+    frequency: string;
+    providers: MonitorProvider[];
+    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. */
+type MonitorsResource = {
+    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    list(options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Monitor[]>;
+    get(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Monitor>;
+    update(monitorId: string, options: MonitorUpdateOptions): Promise<Monitor>;
+    poll(monitorId: string, options?: MonitorPollOptions): Promise<SearchResponse>;
+    delete(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+};
 
 /**
  * The CLOSED set of codes the client itself assigns, for failures that never
@@ -261,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>;
@@ -358,6 +433,8 @@ declare class Telem {
     readonly maxRetries: number;
     /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
+    /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+    readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
      *   resolves from `TELEM_*` env vars, then `~/.telem/credentials.json` (credentials
@@ -389,4 +466,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, 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

@@ -222,6 +222,75 @@ type SessionsResource = {
     list(): Promise<SessionSummary[]>;
     results(sessionId: string): Promise<SessionResults>;
 };
+/** 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 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`. */
+type MonitorPollOptions = {
+    /** Record this poll in another session (default: the monitor's own). */
+    session?: string;
+    /** Request metadata (query lineage keys), sent as given. */
+    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. */
+type Monitor = {
+    id: string;
+    query: string;
+    frequency: string;
+    providers: MonitorProvider[];
+    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. */
+type MonitorsResource = {
+    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    list(options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Monitor[]>;
+    get(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Monitor>;
+    update(monitorId: string, options: MonitorUpdateOptions): Promise<Monitor>;
+    poll(monitorId: string, options?: MonitorPollOptions): Promise<SearchResponse>;
+    delete(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+};
 
 /**
  * The CLOSED set of codes the client itself assigns, for failures that never
@@ -261,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>;
@@ -358,6 +433,8 @@ declare class Telem {
     readonly maxRetries: number;
     /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
+    /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+    readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
      *   resolves from `TELEM_*` env vars, then `~/.telem/credentials.json` (credentials
@@ -389,4 +466,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, 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

@@ -19,10 +19,10 @@ import {
   windowAnchor,
   wireMetadata,
   withTrajectory
-} from "./chunk-RYY4S5LP.js";
+} from "./chunk-DKTEG7EY.js";
 
 // src/version.ts
-var VERSION = "0.2.4";
+var VERSION = "0.2.6";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -182,21 +182,6 @@ async function fetchUrls(config, url, options) {
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
-// src/methods/providers.ts
-async function providers(config) {
-  const body = await request(config, "GET", "/v1/preprocessors");
-  return asArray(asObject(body).preprocessors).filter(isObject).map((entry) => ({
-    name: entry.name ?? "",
-    type: entry.type ?? "",
-    activeByDefault: entry.active_by_default ?? false,
-    description: entry.description ?? null,
-    method: entry.method ?? null,
-    url: entry.url ?? null,
-    normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
-  }));
-}
-
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
 function searchBlock(defaults, options) {
@@ -344,6 +329,110 @@ async function search(config, query, options) {
   return buildSearchResponse(data);
 }
 
+// src/methods/monitors.ts
+function monitorFrom(body) {
+  const data = asObject(body);
+  return {
+    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 ?? "") })),
+    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
+  };
+}
+function createMonitors(config) {
+  const path = (monitorId, suffix = "") => {
+    if (!monitorId || /^\.+$/.test(monitorId)) throw invalidRequest("a monitor id is required");
+    return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
+  };
+  return {
+    /** Create a monitor. Each provider 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;
+      }
+      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);
+    },
+    /** List your monitors, newest first (server default 50, maximum 200). */
+    async list(options = {}) {
+      const query = options.limit === void 0 ? "" : `?limit=${options.limit}`;
+      const body = await request(config, "GET", `/v1/monitors${query}`, void 0, options.signal);
+      return asArray(asObject(body).monitors).map(monitorFrom);
+    },
+    /** Get one monitor. */
+    async get(monitorId, options = {}) {
+      return monitorFrom(await request(config, "GET", path(monitorId), void 0, options.signal));
+    },
+    /** Pause, resume or change a monitor. Only the fields given are sent. */
+    async update(monitorId, options) {
+      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));
+    },
+    /** Get the results that are new since the last poll, one entry per provider. */
+    async poll(monitorId, options = {}) {
+      const body = {};
+      if (options.session !== void 0) body.session_id = options.session;
+      if (options.metadata !== void 0) body.metadata = options.metadata;
+      const route = path(monitorId, "/poll");
+      const data = await request(config, "POST", route, body, options.signal, "rate_limit");
+      return buildSearchResponse(data);
+    },
+    /** Delete a monitor. A repeat deletes what a failed delete left. */
+    async delete(monitorId, options = {}) {
+      await request(config, "DELETE", path(monitorId), void 0, options.signal);
+    }
+  };
+}
+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) {
+  const body = await request(config, "GET", "/v1/preprocessors");
+  return asArray(asObject(body).preprocessors).filter(isObject).map((entry) => ({
+    name: entry.name ?? "",
+    type: entry.type ?? "",
+    activeByDefault: entry.active_by_default ?? false,
+    description: entry.description ?? null,
+    method: entry.method ?? null,
+    url: entry.url ?? null,
+    normalized: entry.normalized ?? false,
+    tiers: asArray(entry.tiers)
+  }));
+}
+
 // src/methods/sessions.ts
 function sessionsFrom(body) {
   return asArray(asObject(body).sessions).filter(isObject).map((entry) => ({
@@ -409,6 +498,8 @@ var Telem = class {
   maxRetries;
   /** The session read surface: `list` and `results(id)`. */
   sessions;
+  /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+  monitors;
   #config;
   /**
    * @param options - An API key string, or an options object. Anything left unset
@@ -423,6 +514,7 @@ var Telem = class {
     this.timeoutMs = config.timeoutMs;
     this.maxRetries = config.maxRetries;
     this.sessions = createSessions(config);
+    this.monitors = createMonitors(config);
   }
   /**
    * Run a web search.
@@ -469,6 +561,7 @@ export {
   sessionKey,
   snapshotNodeKey,
   toolMarker,
+  verifyWebhook,
   windowAnchor,
   withTrajectory
 };

package/dist/vercel/index.js

@@ -9,7 +9,7 @@ import {
   toolMarker,
   windowAnchor,
   withTrajectory
-} from "../chunk-RYY4S5LP.js";
+} from "../chunk-DKTEG7EY.js";
 
 // src/vercel/index.ts
 import { jsonSchema } from "ai";

package/package.json

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