@telemai/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,369 @@
+type Json = Record<string, unknown>;
+/** What one event node needs to identify itself, before derivation. Every id here
+ *  is an OPAQUE host string; the UUIDs that reach the wire are derived from them by
+ *  `buildMetadata`, never forwarded. */
+type TrajectoryArgs = {
+    harness: string;
+    conversationId: string;
+    windowId: string;
+    messageId: string;
+    toolCallId: string;
+    /** The flattened conversation history, in the backend's `{role, content}` shape. */
+    history: readonly Record<string, string>[];
+    /** The root-first ancestor chain; its LAST entry is the direct parent. */
+    ancestors: readonly Json[];
+};
+/** A derived, wire-ready trajectory envelope: the output of `buildMetadata`, and the
+ *  only thing `withTrajectory` should be handed. Its keys are the reserved lineage
+ *  keys the freeform `metadata` bag may not carry, so they are snake_case — they land
+ *  on the wire `metadata` verbatim, with the node's `kind` stamped by the call that
+ *  sends it. Build it with `buildMetadata`; do not hand-assemble one, or the derived
+ *  ids will not join the backend's rows. */
+type TrajectoryEnvelope = {
+    message_history: readonly Record<string, string>[];
+    session_key: string;
+    fingerprint: string;
+    node_key: string;
+    parent_node_key: string | null;
+    ancestors: readonly Json[];
+};
+/** What freezes one agent at a delegation boundary, before derivation. */
+type SnapshotArgs = {
+    harness: string;
+    conversationId: string;
+    windowId: string;
+    /** The model turn that delegated; subagents started in one turn share the node. */
+    messageId: string;
+    /** The agent's conversation so far, frozen at the boundary. */
+    context: readonly Record<string, string>[];
+    /** The agent's own root-first ancestor chain. */
+    ancestors: readonly Json[];
+    /** ISO timestamp; defaults to now. */
+    spawnedAt?: string;
+};
+/** One entry of a child's `ancestors`: the output of `buildSnapshot`. */
+type TrajectorySnapshot = {
+    session_key: string;
+    fingerprint: string;
+    node_key: string;
+    parent_node_key: string | null;
+    context: readonly Record<string, string>[];
+    spawned_at: string;
+};
+/** Search options. `undefined` is unset (client default, then server default);
+ *  `[]`/`{}`/`false` are explicit values sent to the server as-is. */
+type SearchOptions = {
+    tier?: string;
+    fields?: string[];
+    providersInclude?: string[];
+    providersExclude?: string[];
+    providerOverrides?: Record<string, Json>;
+    numResults?: number;
+    includeRaw?: boolean;
+    includeFullContent?: boolean;
+    /** 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) —
+     *  otherwise they are recorded only. Per-call intent, like `includeRaw`; the
+     *  server default is off, and rerank is metered. */
+    rerank?: boolean;
+    goal?: string;
+    context?: string;
+    session?: string;
+    /** Freeform metadata for the wire. Reserved trajectory-lineage keys
+     *  (`RESERVED_METADATA`) are STRIPPED from here — lineage may only be attached
+     *  through `withTrajectory`, fed by `buildMetadata`, never smuggled in as data. */
+    metadata?: Json;
+};
+/** The subset of search options that may also be set as a client default.
+ *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
+type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent">;
+type FetchOptions = {
+    providers?: string[];
+    inlineContent?: boolean;
+    inlineMaxChars?: number;
+    contentFormat?: string;
+    session?: string;
+    metadata?: Json;
+};
+type TelemOptions = SearchDefaults & {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injectable transport — embedded runtimes, edge workers, and tests. */
+    fetch?: typeof globalThis.fetch;
+    userAgent?: string;
+    /** Retry backoff seam. Defaults to a real timer; tests pass a recorder. */
+    sleep?: (ms: number) => Promise<void>;
+};
+type SearchResult = {
+    url: string;
+    title: string;
+    summary: string | null;
+    excerpt: string[] | null;
+    fullContent: Json | null;
+    publishDate: string | null;
+    rank: number | null;
+    thumbnail: string | null;
+    favicon: string | null;
+    source: Json | null;
+    enrichments: Json | null;
+    fetchMeta: Json | null;
+    provider: string;
+    raw: Json;
+};
+type ProviderRun = {
+    provider: string;
+    status: string;
+    results: SearchResult[];
+    error: Json | null;
+    latencyMs: number | null;
+    preprocessorRunId: string | null;
+    tier: string | null;
+    fields: string[];
+    query: string;
+    batchIndex: number;
+    answer: string | null;
+    entities: Json | unknown[] | null;
+    related: Json | null;
+    verticals: Json | null;
+    usage: Json | unknown[] | null;
+    warnings: Json[];
+    raw: Json | null;
+};
+type SearchResponse = {
+    /** Flattened across providers: provider run order, then envelope row order. */
+    results: SearchResult[];
+    /** Per-provider breakdown, preserving partial failures. */
+    byProvider: ProviderRun[];
+    sessionId: string;
+    interactionId: string;
+    status: string;
+    normalizedSchemaVersion: number | null;
+    raw: Json;
+};
+type FetchResult = {
+    url: string;
+    canonicalUrl: string | null;
+    title: string;
+    status: string;
+    content: string | null;
+    contentTruncated: boolean | null;
+    contentFormat: string | null;
+    contentSha256: string | null;
+    contentType: string | null;
+    contentRef: Json | null;
+    provider: string;
+    httpStatus: number | null;
+    fetchedAt: string | null;
+    latencyMs: number | null;
+    providerMetadata: Json | null;
+    error: Json | null;
+    batchIndex: number;
+    raw: Json;
+};
+type FetchResponse = {
+    /** One result per requested URL, in request (batchIndex) order. */
+    results: FetchResult[];
+    sessionId: string;
+    interactionId: string;
+    status: string;
+    raw: Json;
+};
+type ProviderInfo = {
+    name: string;
+    type: string;
+    activeByDefault: boolean;
+    description: string | null;
+    method: string | null;
+    url: string | null;
+    normalized: boolean;
+    tiers: string[];
+};
+/** One session as `sessions.list()` reports it. */
+type SessionSummary = {
+    id: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    interactionCount: number;
+    latestInteractionAt: string | null;
+    raw: Json;
+};
+/** Aggregated websearch preprocessor results for a session. `query`, `goal` and
+ *  `context` are always strings — a server that said nothing sends `""`, never null. */
+type SessionResults = {
+    sessionId: string;
+    query: string;
+    goal: string;
+    context: string;
+    previousPreprocessorResults: Json[];
+    raw: Json;
+};
+/** The `telem.sessions` namespace. */
+type SessionsResource = {
+    list(): Promise<SessionSummary[]>;
+    results(sessionId: string): Promise<SessionResults>;
+};
+
+/**
+ * The CLOSED set of codes the client itself assigns, for failures that never
+ * reached the server or that the server's own envelope does not describe. Any
+ * other value came off the wire (the `/v1/fetch` envelope's `error.code`) and is
+ * passed through untouched.
+ *
+ * Branch on these, never on message text — messages are not a contract.
+ */
+type TelemClientErrorCode = 
+/** The arguments were rejected before any request was made. */
+"invalid_request"
+/** A 2xx search response did not echo `normalized_schema_version >= 2`. */
+ | "unsupported_server_version"
+/** The request never produced a response (DNS, refused, reset, TLS). */
+ | "connection_error"
+/** The request was still outstanding when the timeout fired. */
+ | "timeout";
+type TelemErrorOptions = {
+    /** HTTP status that produced this error; absent for transport failures. */
+    status?: number;
+    /** A `TelemClientErrorCode`, or the stable code the server's envelope carried.
+     *  Absent when a non-2xx response named no code of its own. */
+    code?: TelemClientErrorCode | (string & {});
+    /** Parsed response body (or raw text when it would not parse). */
+    details?: unknown;
+    cause?: unknown;
+};
+declare class TelemError extends Error {
+    status?: number;
+    code?: TelemClientErrorCode | (string & {});
+    details?: unknown;
+    constructor(message: string, options?: TelemErrorOptions);
+}
+/** The request never produced a response in time. Always `code: "timeout"`. */
+declare class TimeoutError extends TelemError {
+    constructor(message: string, cause?: unknown);
+}
+
+/** Metadata keys the trajectory payload owns. A caller-supplied value for any of
+ *  these is dropped rather than allowed to forge identity. */
+declare const RESERVED_METADATA: ReadonlySet<string>;
+/** Stable, non-reversible conversation identity. */
+declare function fingerprint(harness: string, conversationId: string): Promise<string>;
+/** Deterministic identity of one context-window generation. */
+declare function sessionKey(harness: string, conversationId: string, windowId: string): Promise<string>;
+/** Replay-stable event node key for one model tool call. */
+declare function eventNodeKey(harness: string, session: string, messageId: string, toolCallId: string): Promise<string>;
+/** Identity of an agent snapshot at a delegation boundary. */
+declare function snapshotNodeKey(harness: string, conversationId: string, messageId: string): Promise<string>;
+/** Stable anchor id for content a host did not assign an id to.
+ *  Length-prefixed like every other key component, so concatenation stays injective. */
+declare function contentAnchor(...parts: string[]): Promise<string>;
+/**
+ * Identify this context-window generation by its first message.
+ *
+ * Messages carry no ids of their own, so the anchor is a content hash. When a
+ * caller trims or summarizes the front of the history — the equivalent of a
+ * compaction — the anchor moves and a new generation begins.
+ *
+ * @returns The anchor, or `NONE` when there are no messages at all.
+ */
+declare function windowAnchor(messages: readonly Json[]): Promise<string>;
+/**
+ * Assemble the trajectory-v5 metadata block for one event node.
+ *
+ * Built from the ALLOWLIST (`RESERVED_METADATA`) and nothing else — never by
+ * merging caller data — so nothing smuggled in through a host envelope can ride
+ * out to the wire. `parent_node_key` is the DIRECT parent's snapshot key, which is
+ * the last entry of the root-first chain, or `null` when there is no parent.
+ */
+declare function buildMetadata(args: TrajectoryArgs): Promise<TrajectoryEnvelope>;
+/**
+ * Freeze one agent at a delegation boundary into the entry its subagents carry in
+ * `ancestors`.
+ *
+ * Keyed on the delegating turn, so subagents started in one turn share one parent
+ * node. `context` is the agent's conversation at that moment; the caller copies it
+ * if the live history keeps growing.
+ */
+declare function buildSnapshot(args: SnapshotArgs): Promise<TrajectorySnapshot>;
+/** The seam key. A SYMBOL, so an envelope can never arrive from parsed JSON, never
+ *  survives a `structuredClone` of caller options, and never appears on the published
+ *  option surface or in the `.d.ts` — the ONLY way to attach lineage is
+ *  `withTrajectory`, which is why lineage cannot be forged through freeform metadata.
+ *  A REGISTERED symbol, so the ESM and CJS builds of this package share one key: an
+ *  envelope attached by one copy is read by the other. Not re-exported from the
+ *  package root; the seam is the function, not the key. */
+declare const TRAJECTORY: unique symbol;
+/** Search / fetch options carrying a pre-built trajectory envelope. Package-internal. */
+type TrajectorySearchOptions = SearchOptions & {
+    [TRAJECTORY]?: TrajectoryEnvelope;
+};
+type TrajectoryFetchOptions = FetchOptions & {
+    [TRAJECTORY]?: TrajectoryEnvelope;
+};
+/**
+ * Attach a derived lineage envelope to one call's options — the public seam an
+ * example or adapter uses to thread trajectory identity onto a search or a fetch.
+ *
+ * The envelope must come from {@link buildMetadata}: it lands on the wire `metadata`
+ * whole, so it is the allowlist — not this function — that keeps caller data out of
+ * it, and a `session_key` in it makes the call's own `session` id drop out. One
+ * envelope serves both calls; the sending call stamps the node's kind.
+ */
+declare function withTrajectory(options: SearchOptions, envelope: TrajectoryEnvelope): TrajectorySearchOptions;
+declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvelope): TrajectoryFetchOptions;
+
+/**
+ * The Telem client.
+ *
+ * @example
+ * ```ts
+ * 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" })
+ * ```
+ */
+declare class Telem {
+    #private;
+    /** Resolved API key, or `undefined` for an anonymous client. */
+    readonly apiKey?: string;
+    /** Resolved base URL, trailing slash stripped. */
+    readonly baseUrl: string;
+    /** Resolved per-request timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /** Resolved retry budget (attempts after the first). */
+    readonly maxRetries: number;
+    /** The session read surface: `list()` and `results(id)`. */
+    readonly sessions: SessionsResource;
+    /**
+     * @param options - An API key string, or an options object. Anything left unset
+     *   resolves from `TELEM_*` env vars, then `~/.telem/credentials.json` (credentials
+     *   only, read lazily), then the defaults.
+     */
+    constructor(options?: string | TelemOptions);
+    /**
+     * Run a web search.
+     *
+     * @param query - One query, or an array of queries batched into one interaction.
+     * @param options - Per-call options; each overrides the matching client default.
+     *   `null` and `undefined` both mean none.
+     * @returns The flattened results plus the per-provider breakdown.
+     */
+    search(query: string | string[], options?: SearchOptions | null): Promise<SearchResponse>;
+    /**
+     * Fetch the readable content of one or more URLs.
+     *
+     * @param url - One URL, or an array of URLs fetched in one request.
+     * @param options - Per-call fetch options. `null` and `undefined` both mean none.
+     * @returns One result per requested URL, in request order.
+     */
+    fetch(url: string | string[], options?: FetchOptions | null): Promise<FetchResponse>;
+    /**
+     * List the search providers this deployment can run.
+     *
+     * @returns One entry per configured provider, in the server's own order.
+     */
+    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, windowAnchor, withTrajectory };