@telemai/sdk 0.2.4 → 0.2.5

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

@@ -59,7 +59,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.2.4";
+var VERSION = "0.2.5";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -250,7 +250,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 +315,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 +548,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 +695,89 @@ 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,
+    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;
+      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;
+      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);
+    }
+  };
+}
+
+// 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 +843,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 +859,7 @@ var Telem = class {
     this.timeoutMs = config.timeoutMs;
     this.maxRetries = config.maxRetries;
     this.sessions = createSessions(config);
+    this.monitors = createMonitors(config);
   }
   /**
    * Run a web search.

package/dist/index.d.cts

@@ -222,6 +222,68 @@ 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;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.update`. Send at least one of the three fields. */
+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>;
+    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;
+    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
@@ -358,6 +420,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 +453,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, windowAnchor, withTrajectory };

package/dist/index.d.ts

@@ -222,6 +222,68 @@ 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;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.update`. Send at least one of the three fields. */
+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>;
+    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;
+    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
@@ -358,6 +420,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 +453,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, 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.5";
 
 // 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,89 @@ 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,
+    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;
+      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;
+      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);
+    }
+  };
+}
+
+// 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 +477,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 +493,7 @@ var Telem = class {
     this.timeoutMs = config.timeoutMs;
     this.maxRetries = config.maxRetries;
     this.sessions = createSessions(config);
+    this.monitors = createMonitors(config);
   }
   /**
    * Run a web search.

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.5",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",