wauldo 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -833,4 +833,112 @@ declare class AgentsClient {
     streamTask(taskId: string): AsyncGenerator<StateTransition>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };
+/**
+ * History API client — Wauldo Funnel #1 audit log.
+ *
+ * Read-only access to a tenant's task history (every completed task is
+ * persisted to a tenant-scoped DynamoDB audit log on the server side,
+ * exposed via /v1/history). Mirrors {@link MemoryClient} shape so a
+ * caller already familiar with the Memory API has zero ramp-up.
+ *
+ * Three formats:
+ *
+ * - {@link HistoryClient.list} — paginated JSON, suitable for dashboards.
+ * - {@link HistoryClient.export} with `format="csv"` — single CSV blob
+ *   (compliance evidence, header + footer metadata).
+ * - {@link HistoryClient.export} with `format="jsonl"` — newline-
+ *   delimited JSON for log pipelines.
+ *
+ * Right To Be Forgotten (GDPR Art. 17) is supported via
+ * {@link HistoryClient.deleteTask}, which removes every audit row for a
+ * specific task id within the caller's tenant.
+ *
+ * @example
+ * ```ts
+ * import { HistoryClient } from "wauldo/history";
+ * const hist = new HistoryClient({
+ *   baseUrl: "https://api.wauldo.com",
+ *   apiKey: "tig_live_...",
+ *   tenant: "my-org",
+ * });
+ * const page = await hist.list({ verdict: "CONFLICT", limit: 20 });
+ * for (const item of page.items) console.log(item.task_id, item.verdict);
+ * const blob = await hist.export({ format: "csv" });
+ * await hist.deleteTask("a69b8612-0c47-43f3-93f2-c00c8a4ac1f8");
+ * ```
+ */
+interface HistoryClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    tenant?: string;
+    timeoutMs?: number;
+}
+interface TaskHistoryEntry {
+    task_id: string;
+    tenant_id: string;
+    agent_id?: string | null;
+    verdict: string;
+    support_score: number;
+    halluc_rate: number;
+    latency_ms: number;
+    cost_micro_usd: number;
+    claims_count: number;
+    model?: string | null;
+    created_at: number;
+}
+interface HistoryListResponse {
+    items: TaskHistoryEntry[];
+    next_cursor: string | null;
+    /**
+     * `false` when the server hasn't wired its DynamoDB store (self-host
+     * without IAM perm). UI should show "audit log not enabled" rather
+     * than "no events yet" in that case.
+     */
+    enabled: boolean;
+}
+interface ListOptions {
+    verdict?: string;
+    agentId?: string;
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
+}
+interface ExportOptions extends Omit<ListOptions, "limit" | "cursor"> {
+    format: "csv" | "jsonl" | "json";
+}
+declare class HistoryClient {
+    private readonly config;
+    constructor(config: HistoryClientConfig);
+    private headers;
+    private buildQs;
+    private fetchRaw;
+    /**
+     * GET /v1/history — paginated audit log page. Pass `cursor` from a
+     * previous response's `next_cursor` to paginate. Filters compose
+     * with AND.
+     */
+    list(opts?: ListOptions): Promise<HistoryListResponse>;
+    /**
+     * Async generator over all pages within a window, yielding each page
+     * as the server returns it. Stops when `next_cursor` is null.
+     */
+    iterPages(opts?: ListOptions): AsyncIterableIterator<HistoryListResponse>;
+    /**
+     * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+     * the body as a string (`format=csv|jsonl`) or a parsed object
+     * (`format=json`). Server auto-paginates up to 10000 rows; the body
+     * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+     * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+     * a non-2xx response throws.
+     */
+    export(opts: ExportOptions): Promise<string | HistoryListResponse>;
+    /**
+     * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+     * audit row for `taskId` within the caller's tenant. Idempotent.
+     * Returns the number of rows deleted.
+     */
+    deleteTask(taskId: string): Promise<number>;
+}
+
+export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };

package/dist/index.d.ts

@@ -833,4 +833,112 @@ declare class AgentsClient {
     streamTask(taskId: string): AsyncGenerator<StateTransition>;
 }
 
-export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };
+/**
+ * History API client — Wauldo Funnel #1 audit log.
+ *
+ * Read-only access to a tenant's task history (every completed task is
+ * persisted to a tenant-scoped DynamoDB audit log on the server side,
+ * exposed via /v1/history). Mirrors {@link MemoryClient} shape so a
+ * caller already familiar with the Memory API has zero ramp-up.
+ *
+ * Three formats:
+ *
+ * - {@link HistoryClient.list} — paginated JSON, suitable for dashboards.
+ * - {@link HistoryClient.export} with `format="csv"` — single CSV blob
+ *   (compliance evidence, header + footer metadata).
+ * - {@link HistoryClient.export} with `format="jsonl"` — newline-
+ *   delimited JSON for log pipelines.
+ *
+ * Right To Be Forgotten (GDPR Art. 17) is supported via
+ * {@link HistoryClient.deleteTask}, which removes every audit row for a
+ * specific task id within the caller's tenant.
+ *
+ * @example
+ * ```ts
+ * import { HistoryClient } from "wauldo/history";
+ * const hist = new HistoryClient({
+ *   baseUrl: "https://api.wauldo.com",
+ *   apiKey: "tig_live_...",
+ *   tenant: "my-org",
+ * });
+ * const page = await hist.list({ verdict: "CONFLICT", limit: 20 });
+ * for (const item of page.items) console.log(item.task_id, item.verdict);
+ * const blob = await hist.export({ format: "csv" });
+ * await hist.deleteTask("a69b8612-0c47-43f3-93f2-c00c8a4ac1f8");
+ * ```
+ */
+interface HistoryClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    tenant?: string;
+    timeoutMs?: number;
+}
+interface TaskHistoryEntry {
+    task_id: string;
+    tenant_id: string;
+    agent_id?: string | null;
+    verdict: string;
+    support_score: number;
+    halluc_rate: number;
+    latency_ms: number;
+    cost_micro_usd: number;
+    claims_count: number;
+    model?: string | null;
+    created_at: number;
+}
+interface HistoryListResponse {
+    items: TaskHistoryEntry[];
+    next_cursor: string | null;
+    /**
+     * `false` when the server hasn't wired its DynamoDB store (self-host
+     * without IAM perm). UI should show "audit log not enabled" rather
+     * than "no events yet" in that case.
+     */
+    enabled: boolean;
+}
+interface ListOptions {
+    verdict?: string;
+    agentId?: string;
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
+}
+interface ExportOptions extends Omit<ListOptions, "limit" | "cursor"> {
+    format: "csv" | "jsonl" | "json";
+}
+declare class HistoryClient {
+    private readonly config;
+    constructor(config: HistoryClientConfig);
+    private headers;
+    private buildQs;
+    private fetchRaw;
+    /**
+     * GET /v1/history — paginated audit log page. Pass `cursor` from a
+     * previous response's `next_cursor` to paginate. Filters compose
+     * with AND.
+     */
+    list(opts?: ListOptions): Promise<HistoryListResponse>;
+    /**
+     * Async generator over all pages within a window, yielding each page
+     * as the server returns it. Stops when `next_cursor` is null.
+     */
+    iterPages(opts?: ListOptions): AsyncIterableIterator<HistoryListResponse>;
+    /**
+     * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+     * the body as a string (`format=csv|jsonl`) or a parsed object
+     * (`format=json`). Server auto-paginates up to 10000 rows; the body
+     * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+     * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+     * a non-2xx response throws.
+     */
+    export(opts: ExportOptions): Promise<string | HistoryListResponse>;
+    /**
+     * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+     * audit row for `taskId` within the caller's tenant. Idempotent.
+     * Returns the number of rows deleted.
+     */
+    deleteTask(taskId: string): Promise<number>;
+}
+
+export { type A2aResponse, AgentClient, type AgentListResponse, type AgentRunResponse, AgentsClient, type AgentsClientConfig, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type CreateAgentInput, type DeployedAgent, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, type GuardClaim, type GuardMode, type GuardResponse, HistoryClient, type HistoryClientConfig, type ExportOptions as HistoryExportOptions, type ListOptions as HistoryListOptions, type HistoryListResponse, HttpClient, type HttpClientConfig, HttpError, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, type StateTransition, type Task, type TaskClaim, type TaskHistoryEntry, type TaskStatus, type TaskVerification, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, type UpdateAgentPatch, ValidationError, type Verdict, WauldoError, chatContent, guardIsBlocked, guardIsSafe, isTerminalStatus, supportScore };

package/dist/index.js

@@ -24,6 +24,7 @@ __export(index_exports, {
   AgentsClient: () => AgentsClient,
   ConnectionError: () => ConnectionError,
   Conversation: () => Conversation,
+  HistoryClient: () => HistoryClient,
   HttpClient: () => HttpClient,
   HttpError: () => HttpError,
   MockHttpClient: () => MockHttpClient,
@@ -1518,12 +1519,122 @@ var AgentsClient = class {
     }
   }
 };
+
+// src/history.ts
+var HistoryClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.config.apiKey) h["Authorization"] = `Bearer ${this.config.apiKey}`;
+    if (this.config.tenant) h["x-rapidapi-user"] = this.config.tenant;
+    return h;
+  }
+  buildQs(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null);
+    if (entries.length === 0) return "";
+    const usp = new URLSearchParams();
+    for (const [k, v] of entries) usp.set(k, String(v));
+    return "?" + usp.toString();
+  }
+  async fetchRaw(method, path) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 6e4);
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`HTTP ${resp.status} ${resp.statusText}: ${body.slice(0, 200)}`);
+      }
+      return resp;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * GET /v1/history — paginated audit log page. Pass `cursor` from a
+   * previous response's `next_cursor` to paginate. Filters compose
+   * with AND.
+   */
+  async list(opts = {}) {
+    const qs = this.buildQs({
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    return await resp.json();
+  }
+  /**
+   * Async generator over all pages within a window, yielding each page
+   * as the server returns it. Stops when `next_cursor` is null.
+   */
+  async *iterPages(opts = {}) {
+    let cursor = opts.cursor;
+    const pageSize = opts.limit ?? 50;
+    while (true) {
+      const next = { ...opts, limit: pageSize };
+      if (cursor !== void 0) next.cursor = cursor;
+      const page = await this.list(next);
+      yield page;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /**
+   * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+   * the body as a string (`format=csv|jsonl`) or a parsed object
+   * (`format=json`). Server auto-paginates up to 10000 rows; the body
+   * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+   * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+   * a non-2xx response throws.
+   */
+  async export(opts) {
+    if (!["csv", "jsonl", "json"].includes(opts.format)) {
+      throw new Error(`unsupported format '${opts.format}' \u2014 use csv|jsonl|json`);
+    }
+    const qs = this.buildQs({
+      format: opts.format,
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    if (opts.format === "json") {
+      return await resp.json();
+    }
+    return await resp.text();
+  }
+  /**
+   * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+   * audit row for `taskId` within the caller's tenant. Idempotent.
+   * Returns the number of rows deleted.
+   */
+  async deleteTask(taskId) {
+    if (!taskId) throw new Error("taskId required");
+    const resp = await this.fetchRaw("DELETE", `/v1/history/${encodeURIComponent(taskId)}`);
+    const body = await resp.json();
+    return Number(body?.deleted ?? 0);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentClient,
   AgentsClient,
   ConnectionError,
   Conversation,
+  HistoryClient,
   HttpClient,
   HttpError,
   MockHttpClient,

package/dist/index.mjs

@@ -1476,11 +1476,121 @@ var AgentsClient = class {
     }
   }
 };
+
+// src/history.ts
+var HistoryClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.baseUrl) throw new Error("baseUrl is required");
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.config.apiKey) h["Authorization"] = `Bearer ${this.config.apiKey}`;
+    if (this.config.tenant) h["x-rapidapi-user"] = this.config.tenant;
+    return h;
+  }
+  buildQs(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null);
+    if (entries.length === 0) return "";
+    const usp = new URLSearchParams();
+    for (const [k, v] of entries) usp.set(k, String(v));
+    return "?" + usp.toString();
+  }
+  async fetchRaw(method, path) {
+    const url = this.config.baseUrl.replace(/\/$/, "") + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 6e4);
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: this.headers(),
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`HTTP ${resp.status} ${resp.statusText}: ${body.slice(0, 200)}`);
+      }
+      return resp;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * GET /v1/history — paginated audit log page. Pass `cursor` from a
+   * previous response's `next_cursor` to paginate. Filters compose
+   * with AND.
+   */
+  async list(opts = {}) {
+    const qs = this.buildQs({
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    return await resp.json();
+  }
+  /**
+   * Async generator over all pages within a window, yielding each page
+   * as the server returns it. Stops when `next_cursor` is null.
+   */
+  async *iterPages(opts = {}) {
+    let cursor = opts.cursor;
+    const pageSize = opts.limit ?? 50;
+    while (true) {
+      const next = { ...opts, limit: pageSize };
+      if (cursor !== void 0) next.cursor = cursor;
+      const page = await this.list(next);
+      yield page;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /**
+   * GET /v1/history?format=csv|jsonl — single-blob export. Returns
+   * the body as a string (`format=csv|jsonl`) or a parsed object
+   * (`format=json`). Server auto-paginates up to 10000 rows; the body
+   * footer (CSV `# wauldo-history-export ...` line / JSONL `_export`
+   * object) signals truncation. Rate-limited per tenant to 5 / 60s —
+   * a non-2xx response throws.
+   */
+  async export(opts) {
+    if (!["csv", "jsonl", "json"].includes(opts.format)) {
+      throw new Error(`unsupported format '${opts.format}' \u2014 use csv|jsonl|json`);
+    }
+    const qs = this.buildQs({
+      format: opts.format,
+      verdict: opts.verdict,
+      agent_id: opts.agentId,
+      from: opts.fromMs,
+      to: opts.toMs
+    });
+    const resp = await this.fetchRaw("GET", `/v1/history${qs}`);
+    if (opts.format === "json") {
+      return await resp.json();
+    }
+    return await resp.text();
+  }
+  /**
+   * DELETE /v1/history/:task_id — RTBF (GDPR Art. 17). Removes every
+   * audit row for `taskId` within the caller's tenant. Idempotent.
+   * Returns the number of rows deleted.
+   */
+  async deleteTask(taskId) {
+    if (!taskId) throw new Error("taskId required");
+    const resp = await this.fetchRaw("DELETE", `/v1/history/${encodeURIComponent(taskId)}`);
+    const body = await resp.json();
+    return Number(body?.deleted ?? 0);
+  }
+};
 export {
   AgentClient,
   AgentsClient,
   ConnectionError,
   Conversation,
+  HistoryClient,
   HttpClient,
   HttpError,
   MockHttpClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wauldo",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Official TypeScript SDK for Wauldo — Verified AI answers from your documents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",