@telemai/sdk 0.3.1 → 0.3.3

package/README.md

@@ -167,6 +167,13 @@ const page = await telem.fetch("https://example.com/article", {
 const { status, content } = page.results[0]
 ```
 
+`providers` pins the fetch providers, in order; `tier` picks the fetch tier; and
+`noCache: true` reads the page live instead of from the shared cache. If you leave
+one out, the client uses its environment variable: `TELEM_FETCH_PROVIDERS` (comma
+separated), `TELEM_FETCH_TIER` (lowercased) or `TELEM_FETCH_NO_CACHE` (`1` turns it
+on). The client reads them when you create it. An option you pass wins, so
+`noCache: false` turns off `TELEM_FETCH_NO_CACHE=1` for that call.
+
 A URL that failed still returns a result. Check `result.status` and `result.error`.
 Do not expect a shorter list. The options are on the
 [fetch parameters](https://docs.telem.ai/resources/fetch-parameters/) page.

package/dist/index.cjs

@@ -60,7 +60,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.3.1";
+var VERSION = "0.3.3";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -158,6 +158,14 @@ function resolveConfig(options) {
       autoRouting: opts.autoRouting ?? (trimBlank(env.TELEM_AUTO_ROUTING ?? "") || void 0),
       maxRoutingProviders: opts.maxRoutingProviders ?? intEnv(env.TELEM_MAX_ROUTING_PROVIDERS),
       topic: opts.topic ?? (trimBlank(env.TELEM_TOPIC ?? "") || void 0)
+    },
+    // Fetch defaults: env var only, parsed as the shared option table parses it (CSV,
+    // a trimmed name, a "1"-only flag); the tier is lowercased, as the agent plugins
+    // send it. No constructor option, and no config file, as above.
+    fetchDefaults: {
+      providers: csvEnv(env.TELEM_FETCH_PROVIDERS),
+      tier: trimBlank(env.TELEM_FETCH_TIER ?? "").toLowerCase() || void 0,
+      noCache: env.TELEM_FETCH_NO_CACHE === "1" || void 0
     }
   };
 }
@@ -492,7 +500,7 @@ function wireMetadata(options, kind) {
 }
 
 // src/methods/fetch.ts
-function fetchBody(url, options) {
+function fetchBody(url, options, defaults) {
   const urls = stringList(
     typeof url === "string" ? [url] : url,
     "fetch() requires at least one URL",
@@ -500,11 +508,16 @@ function fetchBody(url, options) {
   );
   const { metadata, sessionId } = wireMetadata(options, "fetch");
   const body = { urls, metadata };
+  const providers2 = options.providers ?? defaults.providers;
+  const tier = options.tier ?? defaults.tier;
+  const noCache = options.noCache ?? defaults.noCache;
   const block = {};
-  if (options.providers !== void 0) block.providers = options.providers;
+  if (providers2 !== void 0) block.providers = providers2;
   if (options.inlineContent !== void 0) block.inline_content = options.inlineContent;
   if (options.inlineMaxChars !== void 0) block.inline_max_chars = options.inlineMaxChars;
   if (options.contentFormat !== void 0) block.content_format = options.contentFormat;
+  if (tier !== void 0) block.tier = tier;
+  if (noCache !== void 0) block.no_cache = noCache;
   if (Object.keys(block).length) body.options = block;
   if (sessionId !== void 0) body.session_id = sessionId;
   return body;
@@ -545,12 +558,17 @@ function buildFetchResponse(interaction) {
   };
 }
 async function fetchUrls(config, url, options) {
-  const body = fetchBody(url, options);
+  const body = fetchBody(url, options, config.fetchDefaults);
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
+function providersRefusal(include, includeFromCall, excludeFromCall) {
+  const where = (half, env, fromCall) => fromCall ? `the ${half} search() option` : `the client's ${half} or ${env}`;
+  const names = include.join(", ");
+  return `providersExclude removes every provider in providersInclude (${names}), so no provider is left and no search was sent. Remove ${names} from providersInclude (set by ${where("providersInclude", "TELEM_PROVIDERS_INCLUDE", includeFromCall)}) or from providersExclude (set by ${where("providersExclude", "TELEM_PROVIDERS_EXCLUDE", excludeFromCall)}).`;
+}
 function searchBlock(defaults, options) {
   const fromCallTier = options.tier !== void 0;
   const fromCallFields = options.fields !== void 0;
@@ -564,7 +582,13 @@ function searchBlock(defaults, options) {
   let exclude = options.providersExclude ?? defaults.providersExclude;
   if (include !== void 0 && exclude !== void 0) {
     const excluded = new Set(exclude);
-    include = include.filter((name) => !excluded.has(name));
+    const kept = include.filter((name) => !excluded.has(name));
+    if (include.length && !kept.length) {
+      throw invalidRequest(
+        providersRefusal(include, options.providersInclude !== void 0, options.providersExclude !== void 0)
+      );
+    }
+    include = kept;
     exclude = void 0;
   }
   const includeFullContent = options.includeFullContent ?? defaults.includeFullContent;
@@ -588,6 +612,7 @@ function searchBlock(defaults, options) {
   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);
+  if (options.includeDomains !== void 0) block.include_domains = options.includeDomains;
   return block;
 }
 function isoDate(value) {
@@ -720,8 +745,14 @@ function createMonitors(config) {
   };
   return {
     /** Create a monitor. Telem runs `query` on the schedule. */
-    async create(query, options) {
-      const body = { query, options: { frequency: options.frequency } };
+    async create(query, options = {}) {
+      const monitorOptions = {};
+      if (options.frequency !== void 0) monitorOptions.frequency = options.frequency;
+      if (options.includeDomains !== void 0) {
+        monitorOptions.include_domains = options.includeDomains;
+      }
+      if (options.search !== void 0) monitorOptions.search = searchBlock({}, options.search);
+      const body = { query, options: monitorOptions };
       if (options.metadata !== void 0) body.metadata = options.metadata;
       if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       if (options.ttl !== void 0) body.ttl = options.ttl;
@@ -747,7 +778,7 @@ function createMonitors(config) {
       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. */
+    /** Get the results that are new since the last poll. */
     async poll(monitorId, options = {}) {
       const body = {};
       if (options.session !== void 0) body.session_id = options.session;
@@ -791,7 +822,8 @@ async function providers(config) {
     method: entry.method ?? null,
     url: entry.url ?? null,
     normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
+    tiers: asArray(entry.tiers),
+    autoRouted: entry.auto_routed ?? null
   }));
 }
 

package/dist/index.d.cts

@@ -72,6 +72,9 @@ type SearchOptions = {
      *  includes that whole day. A `Date` is an exact instant; pass a "YYYY-MM-DD"
      *  string to include the whole day. */
     publishedBefore?: string | Date;
+    /** Only results from these domains: at most 20 hostnames such as `"linkedin.com"`.
+     *  A subdomain such as `"uk.linkedin.com"` matches its domain. Per-call only. */
+    includeDomains?: string[];
     /** 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) —
@@ -93,10 +96,17 @@ type SearchOptions = {
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
 type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
+    /** Fetch provider chain, in order. Defaults to `TELEM_FETCH_PROVIDERS`. */
     providers?: string[];
     inlineContent?: boolean;
     inlineMaxChars?: number;
     contentFormat?: string;
+    /** Fetch tier: `minimalist`, `default`, `extended` or `max`. Sent as given; the
+     *  server rejects an unknown one. Defaults to `TELEM_FETCH_TIER`, lowercased. */
+    tier?: string;
+    /** `true` reads every page live and skips the shared fetch cache. Defaults to
+     *  `TELEM_FETCH_NO_CACHE` (on with exactly `"1"`); `false` overrides it. */
+    noCache?: boolean;
     session?: string;
     /** Abort this call: the request stops, no retry follows, and the call rejects
      *  with the signal's reason. Merged with the per-attempt timeout. */
@@ -197,6 +207,8 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
+    /** Whether auto-routing can pick it for a ranked topic; `null` from a router that does not say. */
+    autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
 type SessionSummary = {
@@ -222,10 +234,18 @@ type SessionsResource = {
     list(): Promise<SessionSummary[]>;
     results(sessionId: string): Promise<SessionResults>;
 };
+/** The search options a monitor can run on its schedule (`MonitorCreateOptions.search`). */
+type MonitorSearchOptions = Pick<SearchOptions, "tier" | "numResults">;
 /** Options for `monitors.create`. */
 type MonitorCreateOptions = {
-    /** `"1h"`, `"6h"`, `"1d"` or `"7d"`. */
-    frequency: string;
+    /** `"1h"`, `"6h"`, `"12h"`, `"1d"` or `"7d"`. If you leave it out, the monitor runs once a day. */
+    frequency?: string;
+    /** Also run a web search for the query on the schedule, with these options. `{}`
+     *  uses the defaults. Client search defaults do not apply. */
+    search?: MonitorSearchOptions;
+    /** Only results from these sites and their subdomains, such as `["sec.gov"]`,
+     *  from every source of the monitor. */
+    includeDomains?: string[];
     /** Request metadata (query lineage keys), sent as given. */
     metadata?: Json;
     /** An `https` URL that receives the new results. */
@@ -270,7 +290,7 @@ type Monitor = {
 };
 /** The `telem.monitors` namespace. */
 type MonitorsResource = {
-    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    create(query: string, options?: MonitorCreateOptions): Promise<Monitor>;
     list(options?: {
         limit?: number;
         signal?: AbortSignal;

package/dist/index.d.ts

@@ -72,6 +72,9 @@ type SearchOptions = {
      *  includes that whole day. A `Date` is an exact instant; pass a "YYYY-MM-DD"
      *  string to include the whole day. */
     publishedBefore?: string | Date;
+    /** Only results from these domains: at most 20 hostnames such as `"linkedin.com"`.
+     *  A subdomain such as `"uk.linkedin.com"` matches its domain. Per-call only. */
+    includeDomains?: string[];
     /** 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) —
@@ -93,10 +96,17 @@ type SearchOptions = {
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
 type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
+    /** Fetch provider chain, in order. Defaults to `TELEM_FETCH_PROVIDERS`. */
     providers?: string[];
     inlineContent?: boolean;
     inlineMaxChars?: number;
     contentFormat?: string;
+    /** Fetch tier: `minimalist`, `default`, `extended` or `max`. Sent as given; the
+     *  server rejects an unknown one. Defaults to `TELEM_FETCH_TIER`, lowercased. */
+    tier?: string;
+    /** `true` reads every page live and skips the shared fetch cache. Defaults to
+     *  `TELEM_FETCH_NO_CACHE` (on with exactly `"1"`); `false` overrides it. */
+    noCache?: boolean;
     session?: string;
     /** Abort this call: the request stops, no retry follows, and the call rejects
      *  with the signal's reason. Merged with the per-attempt timeout. */
@@ -197,6 +207,8 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
+    /** Whether auto-routing can pick it for a ranked topic; `null` from a router that does not say. */
+    autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
 type SessionSummary = {
@@ -222,10 +234,18 @@ type SessionsResource = {
     list(): Promise<SessionSummary[]>;
     results(sessionId: string): Promise<SessionResults>;
 };
+/** The search options a monitor can run on its schedule (`MonitorCreateOptions.search`). */
+type MonitorSearchOptions = Pick<SearchOptions, "tier" | "numResults">;
 /** Options for `monitors.create`. */
 type MonitorCreateOptions = {
-    /** `"1h"`, `"6h"`, `"1d"` or `"7d"`. */
-    frequency: string;
+    /** `"1h"`, `"6h"`, `"12h"`, `"1d"` or `"7d"`. If you leave it out, the monitor runs once a day. */
+    frequency?: string;
+    /** Also run a web search for the query on the schedule, with these options. `{}`
+     *  uses the defaults. Client search defaults do not apply. */
+    search?: MonitorSearchOptions;
+    /** Only results from these sites and their subdomains, such as `["sec.gov"]`,
+     *  from every source of the monitor. */
+    includeDomains?: string[];
     /** Request metadata (query lineage keys), sent as given. */
     metadata?: Json;
     /** An `https` URL that receives the new results. */
@@ -270,7 +290,7 @@ type Monitor = {
 };
 /** The `telem.monitors` namespace. */
 type MonitorsResource = {
-    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    create(query: string, options?: MonitorCreateOptions): Promise<Monitor>;
     list(options?: {
         limit?: number;
         signal?: AbortSignal;

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-DKTEG7EY.js";
 
 // src/version.ts
-var VERSION = "0.3.1";
+var VERSION = "0.3.3";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -120,12 +120,20 @@ function resolveConfig(options) {
       autoRouting: opts.autoRouting ?? (trimBlank(env.TELEM_AUTO_ROUTING ?? "") || void 0),
       maxRoutingProviders: opts.maxRoutingProviders ?? intEnv(env.TELEM_MAX_ROUTING_PROVIDERS),
       topic: opts.topic ?? (trimBlank(env.TELEM_TOPIC ?? "") || void 0)
+    },
+    // Fetch defaults: env var only, parsed as the shared option table parses it (CSV,
+    // a trimmed name, a "1"-only flag); the tier is lowercased, as the agent plugins
+    // send it. No constructor option, and no config file, as above.
+    fetchDefaults: {
+      providers: csvEnv(env.TELEM_FETCH_PROVIDERS),
+      tier: trimBlank(env.TELEM_FETCH_TIER ?? "").toLowerCase() || void 0,
+      noCache: env.TELEM_FETCH_NO_CACHE === "1" || void 0
     }
   };
 }
 
 // src/methods/fetch.ts
-function fetchBody(url, options) {
+function fetchBody(url, options, defaults) {
   const urls = stringList(
     typeof url === "string" ? [url] : url,
     "fetch() requires at least one URL",
@@ -133,11 +141,16 @@ function fetchBody(url, options) {
   );
   const { metadata, sessionId } = wireMetadata(options, "fetch");
   const body = { urls, metadata };
+  const providers2 = options.providers ?? defaults.providers;
+  const tier = options.tier ?? defaults.tier;
+  const noCache = options.noCache ?? defaults.noCache;
   const block = {};
-  if (options.providers !== void 0) block.providers = options.providers;
+  if (providers2 !== void 0) block.providers = providers2;
   if (options.inlineContent !== void 0) block.inline_content = options.inlineContent;
   if (options.inlineMaxChars !== void 0) block.inline_max_chars = options.inlineMaxChars;
   if (options.contentFormat !== void 0) block.content_format = options.contentFormat;
+  if (tier !== void 0) block.tier = tier;
+  if (noCache !== void 0) block.no_cache = noCache;
   if (Object.keys(block).length) body.options = block;
   if (sessionId !== void 0) body.session_id = sessionId;
   return body;
@@ -178,12 +191,17 @@ function buildFetchResponse(interaction) {
   };
 }
 async function fetchUrls(config, url, options) {
-  const body = fetchBody(url, options);
+  const body = fetchBody(url, options, config.fetchDefaults);
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
+function providersRefusal(include, includeFromCall, excludeFromCall) {
+  const where = (half, env, fromCall) => fromCall ? `the ${half} search() option` : `the client's ${half} or ${env}`;
+  const names = include.join(", ");
+  return `providersExclude removes every provider in providersInclude (${names}), so no provider is left and no search was sent. Remove ${names} from providersInclude (set by ${where("providersInclude", "TELEM_PROVIDERS_INCLUDE", includeFromCall)}) or from providersExclude (set by ${where("providersExclude", "TELEM_PROVIDERS_EXCLUDE", excludeFromCall)}).`;
+}
 function searchBlock(defaults, options) {
   const fromCallTier = options.tier !== void 0;
   const fromCallFields = options.fields !== void 0;
@@ -197,7 +215,13 @@ function searchBlock(defaults, options) {
   let exclude = options.providersExclude ?? defaults.providersExclude;
   if (include !== void 0 && exclude !== void 0) {
     const excluded = new Set(exclude);
-    include = include.filter((name) => !excluded.has(name));
+    const kept = include.filter((name) => !excluded.has(name));
+    if (include.length && !kept.length) {
+      throw invalidRequest(
+        providersRefusal(include, options.providersInclude !== void 0, options.providersExclude !== void 0)
+      );
+    }
+    include = kept;
     exclude = void 0;
   }
   const includeFullContent = options.includeFullContent ?? defaults.includeFullContent;
@@ -221,6 +245,7 @@ function searchBlock(defaults, options) {
   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);
+  if (options.includeDomains !== void 0) block.include_domains = options.includeDomains;
   return block;
 }
 function isoDate(value) {
@@ -353,8 +378,14 @@ function createMonitors(config) {
   };
   return {
     /** Create a monitor. Telem runs `query` on the schedule. */
-    async create(query, options) {
-      const body = { query, options: { frequency: options.frequency } };
+    async create(query, options = {}) {
+      const monitorOptions = {};
+      if (options.frequency !== void 0) monitorOptions.frequency = options.frequency;
+      if (options.includeDomains !== void 0) {
+        monitorOptions.include_domains = options.includeDomains;
+      }
+      if (options.search !== void 0) monitorOptions.search = searchBlock({}, options.search);
+      const body = { query, options: monitorOptions };
       if (options.metadata !== void 0) body.metadata = options.metadata;
       if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       if (options.ttl !== void 0) body.ttl = options.ttl;
@@ -380,7 +411,7 @@ function createMonitors(config) {
       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. */
+    /** Get the results that are new since the last poll. */
     async poll(monitorId, options = {}) {
       const body = {};
       if (options.session !== void 0) body.session_id = options.session;
@@ -424,7 +455,8 @@ async function providers(config) {
     method: entry.method ?? null,
     url: entry.url ?? null,
     normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
+    tiers: asArray(entry.tiers),
+    autoRouted: entry.auto_routed ?? null
   }));
 }
 

package/package.json

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