@telemai/sdk 0.2.2 → 0.2.4

package/README.md

@@ -42,7 +42,7 @@ See [Authentication](https://docs.telem.ai/authentication/) for the full rules.
 
 ```ts
 
-const telem = new Telem()          // environment, then ~/.telem/credentials.json
+const telem = new Telem          // environment, then ~/.telem/credentials.json
 const telem = new Telem("tlm_...") // just a key
 const telem = new Telem({
   apiKey: "tlm_...",
@@ -176,7 +176,7 @@ Do not expect a shorter list. The options are on the
 List the providers the deployment can run:
 
 ```ts
-for (const provider of await telem.providers()) {
+for (const provider of await telem.providers) {
   console.log(provider.name, provider.activeByDefault, provider.tiers)
 }
 ```
@@ -187,7 +187,7 @@ Every search belongs to a session. The response carries its id as `sessionId`. R
 your sessions back to see what an agent searched for. Both methods require an API key:
 
 ```ts
-for (const session of await telem.sessions.list()) {
+for (const session of await telem.sessions.list) {
   console.log(session.id, session.interactionCount, session.latestInteractionAt)
 }
 
@@ -210,7 +210,7 @@ import { generateText } from "ai"
 import Telem from "@telemai/sdk"
 import { createTelemVercelTools } from "@telemai/sdk/vercel"
 
-const telem = new Telem()
+const telem = new Telem
 const tools = createTelemVercelTools({ telem, harness: "my-app" })
 
 const result = await generateText({ model, tools, prompt: "Is the Nintendo Museum open over New Year?" })
@@ -222,7 +222,7 @@ then appear in the console under the tool call that started it. `ai` version 5
 or later is an optional peer dependency, used by this subpath only. The full
 guide, subagents, your own tools, and the options, is on the
 [Vercel AI SDK page](https://docs.telem.ai/integrations/vercel-ai/). The runnable example is `examples/vercel-ai-agents.mjs`
-in the SDK source, first in the [examples list](https://github.com/TelemAI/TelemSDK/tree/main/js-sdk/examples).
+in the SDK source, first in the [examples list](https://github.com/TelemAI/telem-js-sdk/tree/main/examples).
 
 ## Query lineage
 
@@ -251,8 +251,8 @@ Node SDK, where the completion id is the turn and each tool call has its own id:
 
 ```ts
 
-const telem = new Telem()
-const openai = new OpenAI()
+const telem = new Telem
+const openai = new OpenAI
 const messages = [{ role: "user" as const, content: "Is the Nintendo Museum open over New Year?" }]
 const tools = [
   {
@@ -269,7 +269,7 @@ const tools = [
   },
 ]
 
-const conversationId = crypto.randomUUID()     // once, when the conversation starts
+const conversationId = crypto.randomUUID     // once, when the conversation starts
 const windowId = await windowAnchor(messages)  // once, from the first message
 
 const completion = await openai.chat.completions.create({ model: "gpt-4o", messages, tools })

package/dist/index.cjs

@@ -59,7 +59,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.2.2";
+var VERSION = "0.2.4";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -594,13 +594,18 @@ function searchBlock(defaults, options) {
   if (options.rerank !== void 0) block.rerank = options.rerank;
   if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
   const autoRouting = options.autoRouting ?? defaults.autoRouting;
-  if (autoRouting !== void 0) block.auto_routing = autoRouting;
+  if (autoRouting !== void 0 && autoRouting.toLowerCase() !== "off") block.auto_routing = autoRouting;
   const maxRoutingProviders = options.maxRoutingProviders ?? defaults.maxRoutingProviders;
   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");
@@ -767,7 +772,7 @@ var Telem = class {
   timeoutMs;
   /** Resolved retry budget (attempts after the first). */
   maxRetries;
-  /** The session read surface: `list()` and `results(id)`. */
+  /** The session read surface: `list` and `results(id)`. */
   sessions;
   #config;
   /**

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) —
@@ -190,7 +198,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -333,7 +341,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -348,7 +356,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset

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) —
@@ -190,7 +198,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -333,7 +341,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -348,7 +356,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-RYY4S5LP.js";
 
 // src/version.ts
-var VERSION = "0.2.2";
+var VERSION = "0.2.4";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -229,13 +229,18 @@ function searchBlock(defaults, options) {
   if (options.rerank !== void 0) block.rerank = options.rerank;
   if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
   const autoRouting = options.autoRouting ?? defaults.autoRouting;
-  if (autoRouting !== void 0) block.auto_routing = autoRouting;
+  if (autoRouting !== void 0 && autoRouting.toLowerCase() !== "off") block.auto_routing = autoRouting;
   const maxRoutingProviders = options.maxRoutingProviders ?? defaults.maxRoutingProviders;
   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");
@@ -402,7 +407,7 @@ var Telem = class {
   timeoutMs;
   /** Resolved retry budget (attempts after the first). */
   maxRetries;
-  /** The session read surface: `list()` and `results(id)`. */
+  /** The session read surface: `list` and `results(id)`. */
   sessions;
   #config;
   /**

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

@@ -121,7 +121,7 @@ type TelemVercelAgentOptions = {
      *  several HTTP requests must pass a stable id (the chat id), or every request
      *  becomes its own session. */
     conversationId?: string;
-    /** The root-first chain this agent hangs under; `child()` fills it. */
+    /** The root-first chain this agent hangs under; `child` fills it. */
     ancestors?: readonly TrajectorySnapshot[];
     /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
      *  Unset reads `TELEM_INCREMENTAL` per call. */
@@ -133,7 +133,7 @@ type TelemVercelAgentOptions = {
      *  without replacing a tool. A throw or a rejection here is swallowed; it
      *  never fails the call. */
     onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
-    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+    /** Advanced: the ledgers to share. `child` passes its parent's, so a child
      *  never re-sends what the parent already proved delivered. */
     incrementalState?: IncrementalState;
 };
@@ -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

@@ -121,7 +121,7 @@ type TelemVercelAgentOptions = {
      *  several HTTP requests must pass a stable id (the chat id), or every request
      *  becomes its own session. */
     conversationId?: string;
-    /** The root-first chain this agent hangs under; `child()` fills it. */
+    /** The root-first chain this agent hangs under; `child` fills it. */
     ancestors?: readonly TrajectorySnapshot[];
     /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
      *  Unset reads `TELEM_INCREMENTAL` per call. */
@@ -133,7 +133,7 @@ type TelemVercelAgentOptions = {
      *  without replacing a tool. A throw or a rejection here is swallowed; it
      *  never fails the call. */
     onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
-    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+    /** Advanced: the ledgers to share. `child` passes its parent's, so a child
      *  never re-sends what the parent already proved delivered. */
     incrementalState?: IncrementalState;
 };
@@ -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

@@ -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.2",
+  "version": "0.2.4",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",
@@ -42,14 +42,10 @@
     "node": ">=20.16"
   },
   "scripts": {
-    "pretest": "npm run build",
-    "test": "node --test 'test/**/*.test.ts'",
-    "typecheck": "tsc --noEmit",
-    "gen-version": "node scripts/gen-version.mjs",
-    "prebuild": "node scripts/gen-version.mjs",
     "build": "tsup",
+    "typecheck": "tsc --noEmit",
     "prepack": "npm run build",
-    "smoke:vercel": "node scripts/vercel-live.mjs"
+    "test": "node scripts/smoke.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -71,5 +67,13 @@
         "./dist/vercel/index.d.ts"
       ]
     }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TelemAI/telem-js-sdk.git"
+  },
+  "homepage": "https://docs.telem.ai/sdks/javascript/",
+  "bugs": {
+    "url": "https://github.com/TelemAI/telem-js-sdk/issues"
   }
 }