@telemai/sdk 0.3.2 → 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.2";
+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;
@@ -798,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

@@ -96,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. */
@@ -200,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 = {

package/dist/index.d.ts

@@ -96,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. */
@@ -200,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 = {

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-DKTEG7EY.js";
 
 // src/version.ts
-var VERSION = "0.3.2";
+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;
@@ -431,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.2",
+  "version": "0.3.3",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",