@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.1

package/README.md

@@ -16,6 +16,26 @@ npm install @kweaver-ai/kweaver-sdk
 
 Requires **Node.js >= 22**.
 
+## API reference (TypeDoc)
+
+Generate HTML from source + TSDoc, then open `docs/reference/typescript-api-html/index.html` (gitignored), or serve locally:
+
+HTML reference auto-discovers **`src/resources/*`**, **`src/api/*`**, and **`src/auth/*`** via TypeDoc's `entryPointStrategy: "expand"` (`typedoc.json`), so newly added modules appear without editing the config. The English build uses `README.md` as the cover page; the Chinese build uses `README.zh.md`. **"Defined in"** GitHub links read `gitRevision` from `TYPEDOC_GIT_REVISION` → `GITHUB_SHA` → fallback `"main"`; CI should pin links to the build SHA: `TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs`.
+
+TypeDoc does **not** ship a single-site EN/ZH toggle. Use two outputs: English UI (default) and Chinese UI strings (`docs:zh`, primarily localizes navigation chrome). API descriptions come from TSDoc and stay English unless you maintain duplicate comments elsewhere.
+
+```bash
+cd packages/typescript
+npm install
+npm run docs             # English UI → docs/reference/typescript-api-html/
+npm run docs:serve       # generate + serve http://127.0.0.1:8766
+npm run docs:zh          # Chinese UI + README.zh.md → docs/reference/typescript-api-html-zh/
+npm run docs:serve:zh    # generate + serve http://127.0.0.1:8767
+npm run docs:all         # both folders
+```
+
+> Files inside `docs/reference/**` are generated. Edit `packages/typescript/README*.md` and TSDoc comments in source instead — anything copied into `media/` is overwritten on the next build.
+
 ## Quick Start
 
 ### Authenticate

package/README.zh.md

@@ -16,6 +16,24 @@ npm install @kweaver-ai/kweaver-sdk
 
 需要 **Node.js >= 22**。
 
+## API 参考（TypeDoc）
+
+由源码与 TSDoc 生成 HTML，产物在 `docs/reference/typescript-api-html/index.html`（已 gitignore）。`typedoc.json` 用 **`entryPointStrategy: "expand"`** 自动展开 **`src/resources`**、**`src/api`**、**`src/auth`** 整目录，新增模块无需改配置。英文构建用 `README.md`，中文构建用 `README.zh.md`。**「Defined in」** 链接的 `gitRevision` 取 `TYPEDOC_GIT_REVISION` → `GITHUB_SHA` → 回退 `"main"`；CI 中固定到当前 SHA：`TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs`。
+
+TypeDoc **不会在同一个站点里提供中英文切换**。做法是生成两套目录：英文界面（默认）与中文界面（**`npm run docs:zh`**），主要翻译导航等界面文案；**API 说明仍以源码里的 TSDoc（英文）为准**。
+
+```bash
+cd packages/typescript
+npm install
+npm run docs             # 英文界面 → docs/reference/typescript-api-html/
+npm run docs:serve       # 生成并访问 http://127.0.0.1:8766
+npm run docs:zh          # 中文界面 + README.zh.md → docs/reference/typescript-api-html-zh/
+npm run docs:serve:zh    # 生成并访问 http://127.0.0.1:8767
+npm run docs:all         # 两套产物都生成
+```
+
+> `docs/reference/**` 下的所有文件均为生成产物。请编辑 `packages/typescript/README*.md` 与源码 TSDoc 注释；`media/` 下的拷贝在下次构建时会被覆盖。
+
 ## 快速上手
 
 ### 认证

package/dist/api/agent-observability.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Single source of truth for `/api/agent-observability/v1/traces/_search` —
+ * the OpenSearch-style endpoint that backs both `kweaver agent trace` and
+ * `kweaver trace diagnose`.
+ *
+ * Owns: endpoint URL, auth/headers (via `./headers.ts`), the two-hop strategy
+ * (conversation_id → traceIds → spans), and HTTP error handling.
+ *
+ * Does NOT own normalization: callers receive raw OpenSearch `_source` objects
+ * and shape them as needed (TraceSpan for UI rendering, RawSpan for diagnose
+ * rules). This keeps the wire contract in one place while letting each consumer
+ * pick its own minimal field set.
+ */
+export declare const TRACE_SEARCH_PATH = "/api/agent-observability/v1/traces/_search";
+export declare class TraceFetchError extends Error {
+    readonly status?: number | undefined;
+    readonly url?: string | undefined;
+    constructor(message: string, status?: number | undefined, url?: string | undefined);
+}
+export interface FetchRawSpansByConversationOpts {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain: string;
+    conversationId: string;
+    /** Cap on `terms` aggregation bucket count. Default 100. */
+    maxTraceIds?: number;
+    /** Cap on spans returned by the second query. Default 2000. */
+    maxSpans?: number;
+}
+export interface FetchRawSpansByConversationResult {
+    /** Distinct traceIds observed for this conversation, in agg-bucket order. */
+    traceIds: string[];
+    /** Raw `_source` objects, unmodified. Callers do their own normalization. */
+    rawSources: Array<Record<string, unknown>>;
+    /** True if the agg saw `sum_other_doc_count > 0` (more traceIds than maxTraceIds). */
+    truncated: boolean;
+}
+export declare function postTraceSearch(baseUrl: string, accessToken: string, businessDomain: string, body: unknown): Promise<Record<string, unknown>>;
+/**
+ * Two-hop fetch of all `_source` documents belonging to a conversation.
+ *
+ * Hop 1: aggregate `traceId.keyword` for spans tagged with
+ *        `attributes.gen_ai.conversation.id.keyword == conversationId`.
+ * Hop 2: fetch every span whose `traceId.keyword` is in the agg buckets.
+ *
+ * Fixture-compat fast path: when the first response carries no `aggregations`
+ * but does carry `hits.hits`, that is taken as a flat spans payload and hop 2
+ * is skipped. Existing e2e fixtures (single OpenSearch payload per file) thus
+ * remain usable with a single mock-fetch response.
+ */
+export declare function fetchRawSpansByConversation(opts: FetchRawSpansByConversationOpts): Promise<FetchRawSpansByConversationResult>;

package/dist/api/agent-observability.js

@@ -0,0 +1,108 @@
+/**
+ * Single source of truth for `/api/agent-observability/v1/traces/_search` —
+ * the OpenSearch-style endpoint that backs both `kweaver agent trace` and
+ * `kweaver trace diagnose`.
+ *
+ * Owns: endpoint URL, auth/headers (via `./headers.ts`), the two-hop strategy
+ * (conversation_id → traceIds → spans), and HTTP error handling.
+ *
+ * Does NOT own normalization: callers receive raw OpenSearch `_source` objects
+ * and shape them as needed (TraceSpan for UI rendering, RawSpan for diagnose
+ * rules). This keeps the wire contract in one place while letting each consumer
+ * pick its own minimal field set.
+ */
+import { buildHeaders } from "./headers.js";
+export const TRACE_SEARCH_PATH = "/api/agent-observability/v1/traces/_search";
+export class TraceFetchError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = "TraceFetchError";
+    }
+}
+export async function postTraceSearch(baseUrl, accessToken, businessDomain, body) {
+    const url = `${baseUrl.replace(/\/+$/, "")}${TRACE_SEARCH_PATH}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...buildHeaders(accessToken, businessDomain),
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new TraceFetchError(`trace search failed: HTTP ${res.status} ${res.statusText} — ${text.slice(0, 200)}`, res.status, url);
+    }
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new TraceFetchError(`trace search: invalid JSON response — ${err.message}`);
+    }
+}
+/**
+ * Two-hop fetch of all `_source` documents belonging to a conversation.
+ *
+ * Hop 1: aggregate `traceId.keyword` for spans tagged with
+ *        `attributes.gen_ai.conversation.id.keyword == conversationId`.
+ * Hop 2: fetch every span whose `traceId.keyword` is in the agg buckets.
+ *
+ * Fixture-compat fast path: when the first response carries no `aggregations`
+ * but does carry `hits.hits`, that is taken as a flat spans payload and hop 2
+ * is skipped. Existing e2e fixtures (single OpenSearch payload per file) thus
+ * remain usable with a single mock-fetch response.
+ */
+export async function fetchRawSpansByConversation(opts) {
+    const { baseUrl, accessToken, businessDomain, conversationId } = opts;
+    const maxTraceIds = opts.maxTraceIds ?? 100;
+    const maxSpans = opts.maxSpans ?? 2000;
+    const aggResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: 0,
+        query: { term: { "attributes.gen_ai.conversation.id.keyword": conversationId } },
+        aggs: { tids: { terms: { field: "traceId.keyword", size: maxTraceIds } } },
+    });
+    const aggregations = aggResult.aggregations;
+    if (!aggregations) {
+        const directHits = aggResult.hits?.hits;
+        if (Array.isArray(directHits)) {
+            const rawSources = [];
+            const traceIds = new Set();
+            for (const h of directHits) {
+                if (!h._source)
+                    continue;
+                rawSources.push(h._source);
+                const tid = h._source.traceId ?? h._source.trace_id;
+                if (typeof tid === "string" && tid.length > 0)
+                    traceIds.add(tid);
+            }
+            return { traceIds: [...traceIds], rawSources, truncated: false };
+        }
+    }
+    const tids = aggregations?.tids;
+    const buckets = tids?.buckets ?? [];
+    const truncated = (tids?.sum_other_doc_count ?? 0) > 0;
+    const traceIds = buckets
+        .map((b) => b.key)
+        .filter((k) => typeof k === "string" && k.length > 0);
+    if (traceIds.length === 0) {
+        return { traceIds: [], rawSources: [], truncated: false };
+    }
+    const spansResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: maxSpans,
+        query: { terms: { "traceId.keyword": traceIds } },
+        sort: [{ startTime: "asc" }],
+    });
+    const hits = spansResult.hits?.hits ?? [];
+    const rawSources = [];
+    for (const h of hits) {
+        if (h._source)
+            rawSources.push(h._source);
+    }
+    return { traceIds, rawSources, truncated };
+}

package/dist/api/conversations.d.ts

@@ -61,14 +61,10 @@ export interface TracesByConversationResult {
  */
 export declare function listConversations(opts: ListConversationsOptions): Promise<string>;
 /**
- * Fetch all spans belonging to a conversation via trace-ai's OpenSearch-style _search.
- *
- * Two-hop strategy (see kweaver-sdk#115):
- *   1. Aggregate traceIds for spans tagged with gen_ai.conversation.id == conversationId.
- *   2. Fetch every span sharing those traceIds — this recovers pipeline spans
- *      (HTTP entry, internal RPCs, prompt-build) that are not tagged with conversation_id.
- *
- * Returns a structured result; callers can format as tree/perf/evidence views or stringify.
+ * Fetch all spans belonging to a conversation, shaped as `TraceSpan[]` for UI
+ * rendering (tree/perf/evidence/reasoning views). The wire-level two-hop and
+ * auth/header concerns live in `./agent-observability`; this function only
+ * normalizes the raw `_source` documents.
  */
 export declare function getTracesByConversation(opts: GetTracesOptions): Promise<TracesByConversationResult>;
 /**

package/dist/api/conversations.js

@@ -1,4 +1,5 @@
 import { buildHeaders } from "./headers.js";
+import { fetchRawSpansByConversation } from "./agent-observability.js";
 function buildConversationsUrl(baseUrl, agentKey) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}/api/agent-factory/v1/app/${agentKey}/conversation`;
@@ -29,32 +30,6 @@ export async function listConversations(opts) {
     }
     return body || "[]";
 }
-function buildTraceSearchUrl(baseUrl) {
-    const base = baseUrl.replace(/\/+$/, "");
-    return `${base}/api/agent-observability/v1/traces/_search`;
-}
-async function postTraceSearch(baseUrl, accessToken, businessDomain, body) {
-    const response = await fetch(buildTraceSearchUrl(baseUrl), {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            ...buildHeaders(accessToken, businessDomain),
-        },
-        body: JSON.stringify(body),
-    });
-    const text = await response.text();
-    if (!response.ok) {
-        throw new Error(`getTracesByConversation failed: HTTP ${response.status} ${response.statusText} — ${text.slice(0, 200)}`);
-    }
-    if (!text)
-        return {};
-    try {
-        return JSON.parse(text);
-    }
-    catch (err) {
-        throw new Error(`getTracesByConversation: invalid JSON response — ${err.message}`);
-    }
-}
 function computeDurationNanos(source) {
     if (typeof source.durationInNanos === "number")
         return source.durationInNanos;
@@ -113,45 +88,28 @@ function normalizeSpan(source) {
     };
 }
 /**
- * Fetch all spans belonging to a conversation via trace-ai's OpenSearch-style _search.
- *
- * Two-hop strategy (see kweaver-sdk#115):
- *   1. Aggregate traceIds for spans tagged with gen_ai.conversation.id == conversationId.
- *   2. Fetch every span sharing those traceIds — this recovers pipeline spans
- *      (HTTP entry, internal RPCs, prompt-build) that are not tagged with conversation_id.
- *
- * Returns a structured result; callers can format as tree/perf/evidence views or stringify.
+ * Fetch all spans belonging to a conversation, shaped as `TraceSpan[]` for UI
+ * rendering (tree/perf/evidence/reasoning views). The wire-level two-hop and
+ * auth/header concerns live in `./agent-observability`; this function only
+ * normalizes the raw `_source` documents.
  */
 export async function getTracesByConversation(opts) {
-    const { baseUrl, accessToken, conversationId, businessDomain = "bd_public", maxTraceIds = 100, maxSpans = 2000, } = opts;
-    const aggResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
-        size: 0,
-        query: { term: { "attributes.gen_ai.conversation.id.keyword": conversationId } },
-        aggs: { tids: { terms: { field: "traceId.keyword", size: maxTraceIds } } },
-    });
-    const aggregations = aggResult.aggregations;
-    const tids = aggregations?.tids;
-    const buckets = tids?.buckets ?? [];
-    const truncated = (tids?.sum_other_doc_count ?? 0) > 0;
-    const traceIds = buckets.map((b) => b.key).filter((k) => typeof k === "string" && k.length > 0);
-    if (traceIds.length === 0) {
-        return { conversationId, traceIds: [], spans: [], truncated: false };
-    }
-    const spansResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
-        size: maxSpans,
-        query: { terms: { "traceId.keyword": traceIds } },
-        sort: [{ startTime: "asc" }],
+    const { baseUrl, accessToken, conversationId, businessDomain = "bd_public", maxTraceIds, maxSpans, } = opts;
+    const fetched = await fetchRawSpansByConversation({
+        baseUrl,
+        accessToken,
+        businessDomain,
+        conversationId,
+        maxTraceIds,
+        maxSpans,
     });
-    const hits = spansResult.hits?.hits ?? [];
     const spans = [];
-    for (const hit of hits) {
-        if (!hit._source)
-            continue;
-        const span = normalizeSpan(hit._source);
+    for (const src of fetched.rawSources) {
+        const span = normalizeSpan(src);
         if (span)
             spans.push(span);
     }
-    return { conversationId, traceIds, spans, truncated };
+    return { conversationId, traceIds: fetched.traceIds, spans, truncated: fetched.truncated };
 }
 /**
  * List messages for a conversation.

package/dist/api/datasources.d.ts

@@ -58,23 +58,5 @@ export interface ListTablesOptions {
     businessDomain?: string;
 }
 export declare function listTables(options: ListTablesOptions): Promise<string>;
-export interface ListTablesWithColumnsOptions extends ListTablesOptions {
-    autoScan?: boolean;
-}
-/** List tables with column details. Optionally triggers metadata scan if no tables found. */
-export declare function listTablesWithColumns(options: ListTablesWithColumnsOptions): Promise<string>;
-export interface ScanMetadataOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    dsType?: string;
-    businessDomain?: string;
-}
-export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;
-export interface ScanDatasourceMetadataOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function scanDatasourceMetadata(options: ScanDatasourceMetadataOptions): Promise<string>;
+export { listTablesWithColumns, scanMetadata, scanDatasourceMetadata, } from "./vega.js";
+export type { ListTablesWithColumnsOptions, ScanMetadataOptions, ScanDatasourceMetadataOptions, } from "./vega.js";

package/dist/api/datasources.js

@@ -130,126 +130,10 @@ export async function listTables(options) {
     }
     return body;
 }
-/** List tables with column details. Optionally triggers metadata scan if no tables found. */
-export async function listTablesWithColumns(options) {
-    const { id, autoScan = true, ...rest } = options;
-    let body = await listTables({ ...rest, id });
-    const parsed = JSON.parse(body);
-    let items = Array.isArray(parsed) ? parsed : (parsed.entries ?? parsed.data ?? []);
-    if (items.length === 0 && autoScan) {
-        await scanMetadata({
-            baseUrl: rest.baseUrl,
-            accessToken: rest.accessToken,
-            id,
-            businessDomain: rest.businessDomain,
-        });
-        body = await listTables({ ...rest, id });
-        const parsed2 = JSON.parse(body);
-        items = Array.isArray(parsed2) ? parsed2 : (parsed2.entries ?? parsed2.data ?? []);
-    }
-    const base = rest.baseUrl.replace(/\/+$/, "");
-    const tables = [];
-    for (const t of items) {
-        const tableId = String(t.id ?? "");
-        const tableName = String(t.name ?? "");
-        let columnsRaw = (t.columns ?? t.fields ?? []);
-        if (columnsRaw.length === 0 && tableId) {
-            const tableUrl = `${base}/api/data-connection/v1/metadata/table/${encodeURIComponent(tableId)}?limit=-1`;
-            const colResponse = await fetch(tableUrl, {
-                method: "GET",
-                headers: buildHeaders(rest.accessToken, rest.businessDomain ?? "bd_public"),
-            });
-            const colData = (await colResponse.json());
-            columnsRaw = Array.isArray(colData) ? colData : (colData.entries ?? colData.data ?? []);
-        }
-        const tablePkArray = extractPrimaryKeys(t);
-        const columns = columnsRaw.map((c) => {
-            const name = String(c.name ?? c.field_name ?? "");
-            const flagged = isColumnPrimaryKey(c) || tablePkArray.includes(name);
-            return {
-                name,
-                type: String(c.type ?? c.field_type ?? "varchar"),
-                comment: typeof c.comment === "string" ? c.comment : undefined,
-                ...(flagged ? { isPrimaryKey: true } : {}),
-            };
-        });
-        // Reconcile: if backend gave per-column flags but no table-level array,
-        // synthesize one so downstream callers have a single PK source of truth.
-        const synthesizedPks = tablePkArray.length > 0
-            ? tablePkArray
-            : columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
-        tables.push({
-            name: tableName,
-            columns,
-            ...(synthesizedPks.length > 0 ? { primaryKeys: synthesizedPks } : {}),
-        });
-    }
-    return JSON.stringify(tables);
-}
-// Two PK metadata shapes are recognized — both confirmed conventions:
-//   - per-column `is_primary_key: true` (data-connection metadata standard)
-//   - per-column `column_key === "PRI"` (MySQL INFORMATION_SCHEMA pass-through)
-//   - table-level `primary_keys: string[]` (composite-PK carrier)
-// Other plausible spellings (camelCase, singular keys, SQLite `pk` integer) are
-// intentionally NOT recognized here — adding them speculatively risks false
-// matches and creates code paths the test suite can't pin down. Extend only when
-// a real backend response demonstrates the need.
-function isColumnPrimaryKey(col) {
-    if (col.is_primary_key === true)
-        return true;
-    if (typeof col.column_key === "string" && col.column_key.toUpperCase() === "PRI")
-        return true;
-    return false;
-}
-function extractPrimaryKeys(table) {
-    const arr = table.primary_keys;
-    if (Array.isArray(arr)) {
-        return arr.filter((x) => typeof x === "string");
-    }
-    return [];
-}
-export async function scanMetadata(options) {
-    const { baseUrl, accessToken, id, dsType = "mysql", businessDomain = "bd_public", } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const scanUrl = `${base}/api/data-connection/v1/metadata/scan`;
-    const statusUrl = (taskId) => `${base}/api/data-connection/v1/metadata/scan/${taskId}`;
-    const scanBody = JSON.stringify({
-        scan_name: `sdk_scan_${id.slice(0, 8)}`,
-        type: 0,
-        ds_info: { ds_id: id, ds_type: dsType },
-        use_default_template: true,
-        use_multi_threads: true,
-        status: "open",
-    });
-    const scanResponse = await fetch(scanUrl, {
-        method: "POST",
-        headers: {
-            ...buildHeaders(accessToken, businessDomain),
-            "content-type": "application/json",
-        },
-        body: scanBody,
-    });
-    const scanResult = await scanResponse.json();
-    const taskId = scanResult.id ?? "";
-    for (let i = 0; i < 30; i += 1) {
-        const delay = Math.min(2000 * Math.pow(1.5, i), 15000);
-        await new Promise((r) => setTimeout(r, delay));
-        const statusResponse = await fetch(statusUrl(taskId), {
-            method: "GET",
-            headers: buildHeaders(accessToken, businessDomain),
-        });
-        const statusData = (await statusResponse.json());
-        if (statusData.status === "success" || statusData.status === "fail") {
-            break;
-        }
-    }
-    return taskId;
-}
-// Looks up a datasource's type then triggers a metadata scan, so callers
-// don't have to repeat the GET-then-scan dance whenever a flow needs the
-// platform catalog refreshed (after import-csv, before discovering tables).
-export async function scanDatasourceMetadata(options) {
-    const dsBody = await getDatasource(options);
-    const dsType = JSON.parse(dsBody).type ?? "mysql";
-    return scanMetadata({ ...options, dsType });
-}
+// ── Vega catalog re-exports (backward compatibility) ─────────────────────────
+//
+// listTablesWithColumns, scanMetadata, and scanDatasourceMetadata now live in
+// vega.ts (they talk exclusively to vega-backend, not data-connection).
+// Re-exported here so existing callers don't break — new code should import
+// from "../api/vega.js" directly.
+export { listTablesWithColumns, scanMetadata, scanDatasourceMetadata, } from "./vega.js";

package/dist/api/trace.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `RawSpan`-flavored view of conversation trace data, for diagnose rule
+ * predicates. The HTTP / two-hop / auth concerns live in `./agent-observability`;
+ * this module only normalizes the raw `_source` documents into the minimal
+ * span shape rules read.
+ */
+export { TraceFetchError } from "./agent-observability.js";
+export interface GetSpansByConversationIdOpts {
+    baseUrl: string;
+    token: string;
+    businessDomain: string;
+    conversationId: string;
+    /** Cap on `terms` aggregation bucket count. Default 100. */
+    maxTraceIds?: number;
+    /** Cap on spans returned by the second query. Default 2000. */
+    maxSpans?: number;
+}
+export interface RawSpan {
+    spanId: string;
+    parentSpanId: string | null;
+    name?: string;
+    startTimeUnixNano?: string;
+    endTimeUnixNano?: string;
+    status?: {
+        code?: string;
+    };
+    attributes?: Record<string, unknown>;
+    /** OTel traceId for the trace this span belongs to (when known). */
+    traceId?: string;
+}
+export interface GetSpansByConversationIdResult {
+    /** Distinct traceIds observed for this conversation. */
+    traceIds: string[];
+    /** All spans across all observed traceIds, mapped to `RawSpan` shape. */
+    spans: RawSpan[];
+    /** True if the agg saw `sum_other_doc_count > 0` (more traceIds than maxTraceIds). */
+    truncated: boolean;
+}
+/**
+ * ISO timestamp → nanos-since-epoch string. Preserves up to 9 fractional digits.
+ * Falls back to ms precision when the input lacks a fractional component.
+ */
+export declare function isoToNanos(iso: string | undefined): string | undefined;
+export declare function getSpansByConversationId(opts: GetSpansByConversationIdOpts): Promise<GetSpansByConversationIdResult>;

package/dist/api/trace.js

@@ -0,0 +1,81 @@
+/**
+ * `RawSpan`-flavored view of conversation trace data, for diagnose rule
+ * predicates. The HTTP / two-hop / auth concerns live in `./agent-observability`;
+ * this module only normalizes the raw `_source` documents into the minimal
+ * span shape rules read.
+ */
+import { fetchRawSpansByConversation } from "./agent-observability.js";
+export { TraceFetchError } from "./agent-observability.js";
+/**
+ * ISO timestamp → nanos-since-epoch string. Preserves up to 9 fractional digits.
+ * Falls back to ms precision when the input lacks a fractional component.
+ */
+export function isoToNanos(iso) {
+    if (!iso)
+        return undefined;
+    // "YYYY-MM-DDTHH:MM:SS.fffffffffZ" or "...+08:00"
+    const m = iso.match(/^(.+?)\.(\d{1,9})(Z|[+-]\d{2}:?\d{2})$/);
+    if (!m) {
+        const ms = Date.parse(iso);
+        if (Number.isNaN(ms))
+            return undefined;
+        return (BigInt(ms) * 1000000n).toString();
+    }
+    const ms = Date.parse(m[1] + m[3]);
+    if (Number.isNaN(ms))
+        return undefined;
+    const frac = m[2].padEnd(9, "0").slice(0, 9);
+    const seconds = BigInt(Math.floor(ms / 1000));
+    return (seconds * 1000000000n + BigInt(frac)).toString();
+}
+function normalizeToRawSpan(source) {
+    const spanIdRaw = source.spanId ?? source.span_id;
+    const spanId = typeof spanIdRaw === "string" ? spanIdRaw : "";
+    if (!spanId)
+        return null;
+    const parentRaw = source.parentSpanId ?? source.parent_span_id ?? source.parentSpanID;
+    const parentSpanId = typeof parentRaw === "string" && parentRaw !== "" && parentRaw !== "0" ? parentRaw : null;
+    // Prefer pre-normalized nanos (synthetic fixtures); else derive from ISO.
+    let startTimeUnixNano;
+    let endTimeUnixNano;
+    if (typeof source.startTimeUnixNano === "string")
+        startTimeUnixNano = source.startTimeUnixNano;
+    else if (typeof source.startTime === "string")
+        startTimeUnixNano = isoToNanos(source.startTime);
+    if (typeof source.endTimeUnixNano === "string")
+        endTimeUnixNano = source.endTimeUnixNano;
+    else if (typeof source.endTime === "string")
+        endTimeUnixNano = isoToNanos(source.endTime);
+    const status = source.status;
+    const attributes = source.attributes;
+    const name = typeof source.name === "string" ? source.name : undefined;
+    const traceIdRaw = source.traceId ?? source.trace_id;
+    const traceId = typeof traceIdRaw === "string" ? traceIdRaw : undefined;
+    return {
+        spanId,
+        parentSpanId,
+        name,
+        startTimeUnixNano,
+        endTimeUnixNano,
+        status,
+        attributes,
+        traceId,
+    };
+}
+export async function getSpansByConversationId(opts) {
+    const fetched = await fetchRawSpansByConversation({
+        baseUrl: opts.baseUrl,
+        accessToken: opts.token,
+        businessDomain: opts.businessDomain,
+        conversationId: opts.conversationId,
+        maxTraceIds: opts.maxTraceIds,
+        maxSpans: opts.maxSpans,
+    });
+    const spans = [];
+    for (const src of fetched.rawSources) {
+        const span = normalizeToRawSpan(src);
+        if (span)
+            spans.push(span);
+    }
+    return { traceIds: fetched.traceIds, spans, truncated: fetched.truncated };
+}