@telemai/sdk 0.2.3 → 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.3";
+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) {
@@ -599,8 +585,13 @@ function searchBlock(defaults, options) {
   if (maxRoutingProviders !== void 0) block.max_routing_providers = maxRoutingProviders;
   const topic = options.topic ?? defaults.topic;
   if (topic !== void 0) block.topic = topic;
+  if (options.publishedAfter !== void 0) block.published_after = isoDate(options.publishedAfter);
+  if (options.publishedBefore !== void 0) block.published_before = isoDate(options.publishedBefore);
   return block;
 }
+function isoDate(value) {
+  return typeof value === "string" ? value : value.toISOString();
+}
 function userInput(query) {
   if (typeof query === "string") {
     if (query === "") throw invalidRequest("search() requires a non-empty query");
@@ -704,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) => ({
@@ -769,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
@@ -783,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

@@ -64,6 +64,14 @@ type SearchOptions = {
     autoRouting?: string;
     maxRoutingProviders?: number;
     topic?: string;
+    /** Only results published on or after this date or date-time: an ISO 8601 string
+     *  (no time zone means UTC) or a `Date`. Results with no known date are kept.
+     *  Per-call only, like the two below. */
+    publishedAfter?: string | Date;
+    /** Only results published before this date or date-time. A date with no time
+     *  includes that whole day. A `Date` is an exact instant; pass a "YYYY-MM-DD"
+     *  string to include the whole day. */
+    publishedBefore?: string | Date;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -214,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
@@ -350,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
@@ -381,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

@@ -64,6 +64,14 @@ type SearchOptions = {
     autoRouting?: string;
     maxRoutingProviders?: number;
     topic?: string;
+    /** Only results published on or after this date or date-time: an ISO 8601 string
+     *  (no time zone means UTC) or a `Date`. Results with no known date are kept.
+     *  Per-call only, like the two below. */
+    publishedAfter?: string | Date;
+    /** Only results published before this date or date-time. A date with no time
+     *  includes that whole day. A `Date` is an exact instant; pass a "YYYY-MM-DD"
+     *  string to include the whole day. */
+    publishedBefore?: string | Date;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -214,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
@@ -350,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
@@ -381,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.3";
+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) {
@@ -234,8 +219,13 @@ function searchBlock(defaults, options) {
   if (maxRoutingProviders !== void 0) block.max_routing_providers = maxRoutingProviders;
   const topic = options.topic ?? defaults.topic;
   if (topic !== void 0) block.topic = topic;
+  if (options.publishedAfter !== void 0) block.published_after = isoDate(options.publishedAfter);
+  if (options.publishedBefore !== void 0) block.published_before = isoDate(options.publishedBefore);
   return block;
 }
+function isoDate(value) {
+  return typeof value === "string" ? value : value.toISOString();
+}
 function userInput(query) {
   if (typeof query === "string") {
     if (query === "") throw invalidRequest("search() requires a non-empty query");
@@ -339,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) => ({
@@ -404,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
@@ -418,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.cjs

@@ -452,7 +452,10 @@ async function turnAnchor(messages, windowId) {
   return await contentAnchor(String(messages.length), windowId, text);
 }
 function compact(response) {
-  return response.results.slice(0, RESULT_CAP).map(({ provider, title, url, summary }) => ({ provider, title, url, summary }));
+  return response.results.slice(0, RESULT_CAP).map(({ provider, title, url, summary, publishDate }) => {
+    const published = publishDate?.trim();
+    return published ? { provider, title, url, summary, published } : { provider, title, url, summary };
+  });
 }
 function page(response) {
   const first = response.results[0];
@@ -477,6 +480,14 @@ var SEARCH_SCHEMA = (0, import_ai.jsonSchema)({
     topic: {
       type: "string",
       description: "Optional. Set it only when the answer must come from one site: linkedin, reddit, or x (twitter is also accepted). Leave it unset otherwise."
+    },
+    published_after: {
+      type: "string",
+      description: "Optional. Only return results published on or after this date or date-time, in ISO 8601 (for example 2026-10-01 or 2026-10-01T09:00:00Z). A value with no time zone is read as UTC. Results with no known publication date are kept. Set it only when the task needs sources from a time period; leave it unset otherwise."
+    },
+    published_before: {
+      type: "string",
+      description: "Optional. Only return results published before this date or date-time, in ISO 8601. A value with no time zone is read as UTC, and a date with no time includes that whole day. Results with no known publication date are kept. Set it only when the task needs sources from a time period; leave it unset otherwise."
     }
   },
   required: ["query"],
@@ -567,7 +578,14 @@ function createTelemVercelAgent(options) {
     const opts = { ...searchOptions ?? {}, signal: signalFor(execution, searchOptions?.signal) };
     const { envelope, plan } = await lineage(execution, {
       name: SEARCH_TOOL,
-      input: { query, goal: opts.goal, context: opts.context, topic: opts.topic }
+      input: {
+        query,
+        goal: opts.goal,
+        context: opts.context,
+        topic: opts.topic,
+        published_after: opts.publishedAfter,
+        published_before: opts.publishedBefore
+      }
     });
     const response = await state.sendWithOmissionRetry(
       plan,
@@ -624,12 +642,18 @@ function createTelemVercelAgent(options) {
   }
   const tools = {
     telem_search: {
-      description: "Search the public web. One query per call; returns the top results with provider, title, url and summary. Use telem_fetch to read a page in full.",
+      description: "Search the public web. One query per call; returns the top results with provider, title, url, summary and, when known, publication date. Use telem_fetch to read a page in full.",
       inputSchema: SEARCH_SCHEMA,
       execute: async (input, execution) => {
         const topic = input.topic?.trim() || void 0;
+        const publishedAfter = input.published_after?.trim() || void 0;
+        const publishedBefore = input.published_before?.trim() || void 0;
         return renderSearch(
-          await search(input.query, { goal: input.goal, context: input.context, topic }, execution)
+          await search(
+            input.query,
+            { goal: input.goal, context: input.context, topic, publishedAfter, publishedBefore },
+            execution
+          )
         );
       }
     },

package/dist/vercel/index.d.cts

@@ -142,17 +142,21 @@ type TelemVercelSearchInput = {
     goal?: string;
     context?: string;
     topic?: string;
+    published_after?: string;
+    published_before?: string;
 };
 type TelemVercelFetchInput = {
     url: string;
     goal?: string;
 };
-/** The default `render.search`: the top results, compact. */
+/** The default `render.search`: the top results, compact. `published` is there only
+ *  when the result has a publication date. */
 type TelemVercelSearchOutput = Array<{
     provider: string;
     title: string;
     url: string;
     summary: string | null;
+    published?: string;
 }>;
 /** The default `render.fetch`: one page's status, error and text. */
 type TelemVercelFetchOutput = {

package/dist/vercel/index.d.ts

@@ -142,17 +142,21 @@ type TelemVercelSearchInput = {
     goal?: string;
     context?: string;
     topic?: string;
+    published_after?: string;
+    published_before?: string;
 };
 type TelemVercelFetchInput = {
     url: string;
     goal?: string;
 };
-/** The default `render.search`: the top results, compact. */
+/** The default `render.search`: the top results, compact. `published` is there only
+ *  when the result has a publication date. */
 type TelemVercelSearchOutput = Array<{
     provider: string;
     title: string;
     url: string;
     summary: string | null;
+    published?: string;
 }>;
 /** The default `render.fetch`: one page's status, error and text. */
 type TelemVercelFetchOutput = {

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";
@@ -290,7 +290,10 @@ async function turnAnchor(messages, windowId) {
   return await contentAnchor(String(messages.length), windowId, text);
 }
 function compact(response) {
-  return response.results.slice(0, RESULT_CAP).map(({ provider, title, url, summary }) => ({ provider, title, url, summary }));
+  return response.results.slice(0, RESULT_CAP).map(({ provider, title, url, summary, publishDate }) => {
+    const published = publishDate?.trim();
+    return published ? { provider, title, url, summary, published } : { provider, title, url, summary };
+  });
 }
 function page(response) {
   const first = response.results[0];
@@ -315,6 +318,14 @@ var SEARCH_SCHEMA = jsonSchema({
     topic: {
       type: "string",
       description: "Optional. Set it only when the answer must come from one site: linkedin, reddit, or x (twitter is also accepted). Leave it unset otherwise."
+    },
+    published_after: {
+      type: "string",
+      description: "Optional. Only return results published on or after this date or date-time, in ISO 8601 (for example 2026-10-01 or 2026-10-01T09:00:00Z). A value with no time zone is read as UTC. Results with no known publication date are kept. Set it only when the task needs sources from a time period; leave it unset otherwise."
+    },
+    published_before: {
+      type: "string",
+      description: "Optional. Only return results published before this date or date-time, in ISO 8601. A value with no time zone is read as UTC, and a date with no time includes that whole day. Results with no known publication date are kept. Set it only when the task needs sources from a time period; leave it unset otherwise."
     }
   },
   required: ["query"],
@@ -405,7 +416,14 @@ function createTelemVercelAgent(options) {
     const opts = { ...searchOptions ?? {}, signal: signalFor(execution, searchOptions?.signal) };
     const { envelope, plan } = await lineage(execution, {
       name: SEARCH_TOOL,
-      input: { query, goal: opts.goal, context: opts.context, topic: opts.topic }
+      input: {
+        query,
+        goal: opts.goal,
+        context: opts.context,
+        topic: opts.topic,
+        published_after: opts.publishedAfter,
+        published_before: opts.publishedBefore
+      }
     });
     const response = await state.sendWithOmissionRetry(
       plan,
@@ -462,12 +480,18 @@ function createTelemVercelAgent(options) {
   }
   const tools = {
     telem_search: {
-      description: "Search the public web. One query per call; returns the top results with provider, title, url and summary. Use telem_fetch to read a page in full.",
+      description: "Search the public web. One query per call; returns the top results with provider, title, url, summary and, when known, publication date. Use telem_fetch to read a page in full.",
       inputSchema: SEARCH_SCHEMA,
       execute: async (input, execution) => {
         const topic = input.topic?.trim() || void 0;
+        const publishedAfter = input.published_after?.trim() || void 0;
+        const publishedBefore = input.published_before?.trim() || void 0;
         return renderSearch(
-          await search(input.query, { goal: input.goal, context: input.context, topic }, execution)
+          await search(
+            input.query,
+            { goal: input.goal, context: input.context, topic, publishedAfter, publishedBefore },
+            execution
+          )
         );
       }
     },

package/package.json

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