@vertesia/client 1.0.0-dev.20260128.144200 → 1.0.0-dev.20260225.024852Z

package/src/client.ts

@@ -3,6 +3,7 @@ import { AuthTokenPayload, AuthTokenResponse } from "@vertesia/common";
 import AccountApi from "./AccountApi.js";
 import AccountsApi from "./AccountsApi.js";
 import AnalyticsApi from "./AnalyticsApi.js";
+import AuditTrailApi from "./AuditTrailApi.js";
 import { ApiKeysApi } from "./ApiKeysApi.js";
 import AppsApi from "./AppsApi.js";
 import CommandsApi from "./CommandsApi.js";
@@ -333,6 +334,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     accounts = new AccountsApi(this);
     apikeys = new ApiKeysApi(this);
     analytics = new AnalyticsApi(this);
+    auditTrail = new AuditTrailApi(this);
     training = new TrainingApi(this);
     users = new UsersApi(this);
     iam = new IamApi(this);

package/src/store/HiveMemoryApi.ts

@@ -0,0 +1,231 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    CreateHiveMemoryPayload,
+    FormattedMemoryForAgent,
+    HiveMemory,
+    HiveMemorySearchParams,
+    HiveMemorySearchResult,
+    UpdateHiveMemoryPayload,
+} from "@vertesia/common";
+
+/**
+ * Statistics about hive memories in the project
+ */
+export interface HiveMemoryStats {
+    total_memories: number;
+    by_category: Array<{
+        category: string;
+        count: number;
+        avg_confidence: number;
+        total_usage: number;
+    }>;
+    overall: {
+        avgConfidence: number;
+        avgUsage: number;
+        totalContributions: number;
+    };
+}
+
+/**
+ * Result from recall endpoint
+ */
+export interface RecallResult {
+    memories: FormattedMemoryForAgent[];
+    count: number;
+}
+
+/**
+ * Client API for managing hive memories.
+ *
+ * Hive memory is a system for storing and retrieving agent learnings,
+ * enabling agents to learn from past runs and share knowledge.
+ */
+export class HiveMemoryApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/hive-memory");
+    }
+
+    /**
+     * List memories in the project.
+     *
+     * @param options - Optional filters and pagination
+     */
+    list(options?: {
+        category?: string;
+        scope?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<HiveMemory[]> {
+        const params = new URLSearchParams();
+        if (options?.category) params.set('category', options.category);
+        if (options?.scope) params.set('scope', options.scope);
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const queryString = params.toString();
+        return this.get(queryString ? `/?${queryString}` : '/');
+    }
+
+    /**
+     * Retrieve a memory by ID.
+     */
+    retrieve(id: string): Promise<HiveMemory> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Create a new hive memory.
+     *
+     * @param payload - Memory content including category, summary, and learnings
+     */
+    create(payload: CreateHiveMemoryPayload): Promise<HiveMemory> {
+        return this.post("/", { payload });
+    }
+
+    /**
+     * Update an existing memory with new learnings.
+     *
+     * This merges new learnings with existing ones rather than replacing them.
+     *
+     * @param id - Memory ID
+     * @param payload - Fields to update/merge
+     */
+    update(id: string, payload: UpdateHiveMemoryPayload): Promise<HiveMemory> {
+        return this.put(`/${id}`, { payload });
+    }
+
+    /**
+     * Delete a memory.
+     *
+     * @param id - Memory ID
+     */
+    delete(id: string): Promise<{ id: string; deleted: boolean }> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Search memories using semantic and keyword search.
+     *
+     * @param params - Search parameters including query, filters, and pagination
+     */
+    search(params: HiveMemorySearchParams): Promise<HiveMemorySearchResult> {
+        return this.post("/search", { payload: params });
+    }
+
+    /**
+     * Recall memories for an agent.
+     *
+     * This is the primary method for agents to retrieve relevant learnings.
+     * It searches for memories matching the task description and returns
+     * them formatted for agent consumption.
+     *
+     * @param taskDescription - Description of the current task
+     * @param options - Optional filters
+     *
+     * @example
+     * ```typescript
+     * const result = await client.hiveMemory.recall(
+     *   "Extract financial data from PDF documents",
+     *   {
+     *     tools: ["extract_text", "analyze_document"],
+     *     maxResults: 5
+     *   }
+     * );
+     * ```
+     */
+    recall(
+        taskDescription: string,
+        options?: {
+            tools?: string[];
+            category?: string;
+            maxResults?: number;
+        }
+    ): Promise<RecallResult> {
+        return this.post("/recall", {
+            payload: {
+                task_description: taskDescription,
+                tools: options?.tools,
+                category: options?.category,
+                max_results: options?.maxResults,
+            }
+        });
+    }
+
+    /**
+     * Get a memory formatted for agent consumption.
+     *
+     * @param id - Memory ID
+     */
+    getFormatted(id: string): Promise<FormattedMemoryForAgent> {
+        return this.get(`/${id}/formatted`);
+    }
+
+    /**
+     * Record that a memory was used.
+     *
+     * This increments the usage count and helps track memory effectiveness.
+     *
+     * @param id - Memory ID
+     */
+    recordUsage(id: string): Promise<{ success: boolean }> {
+        return this.post(`/${id}/usage`, {});
+    }
+
+    /**
+     * Get memories by category.
+     *
+     * @param category - Task category (e.g., "document-analysis", "data-extraction")
+     * @param options - Pagination options
+     */
+    getByCategory(
+        category: string,
+        options?: { limit?: number; offset?: number }
+    ): Promise<HiveMemory[]> {
+        const params = new URLSearchParams();
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const queryString = params.toString();
+        return this.get(`/category/${category}${queryString ? `?${queryString}` : ''}`);
+    }
+
+    /**
+     * Get memory statistics for the project.
+     */
+    getStats(): Promise<HiveMemoryStats> {
+        return this.get("/stats");
+    }
+
+    /**
+     * Apply confidence decay to unused memories.
+     *
+     * Admin operation that reduces confidence scores for memories
+     * that haven't been used recently.
+     *
+     * @param options - Decay parameters
+     */
+    applyDecay(options?: {
+        daysThreshold?: number;
+        decayRate?: number;
+    }): Promise<{ modified_count: number }> {
+        return this.post("/admin/decay", {
+            payload: {
+                days_threshold: options?.daysThreshold,
+                decay_rate: options?.decayRate,
+            }
+        });
+    }
+
+    /**
+     * Archive memories with low confidence scores.
+     *
+     * Admin operation that removes memories below a confidence threshold.
+     *
+     * @param threshold - Confidence threshold (0-1), default 0.2
+     */
+    archiveLowConfidence(threshold?: number): Promise<{ archived_count: number }> {
+        return this.post("/admin/archive", {
+            payload: { threshold }
+        });
+    }
+}

package/src/store/IndexingApi.ts

@@ -0,0 +1,250 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    IndexingStatusResponse,
+    GenericCommandResponse,
+    ElasticsearchDocumentData,
+    BulkIndexResult,
+    CreateReindexTargetResult,
+    ReindexRangeResult,
+    FetchBatchResult,
+    IndexBatchResult,
+    TriggerReindexResult,
+    ElasticsearchIndexStats,
+    IndexConfiguration,
+    FetchDocumentsByIdsResult,
+    BulkDeleteResult,
+    EnsureIndexResult,
+    SwapAliasResult,
+} from "@vertesia/common";
+
+/**
+ * API for indexing operations on content objects.
+ * Provides status, reindex, and configuration management.
+ *
+ * Internal endpoints (prefixed with /internal/) are used by Temporal workflow activities
+ * and require content_admin permission.
+ */
+export class IndexingApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/indexing") {
+        super(parent, basePath);
+    }
+
+    // ========================================================================
+    // User-facing endpoints
+    // ========================================================================
+
+    /**
+     * Get Elasticsearch status for the current project
+     */
+    async status(): Promise<IndexingStatusResponse> {
+        return this.get("/status");
+    }
+
+    /**
+     * Trigger a full reindex of all documents
+     * @param recreateIndex If true, drops and recreates the index before reindexing
+     */
+    async reindex(recreateIndex?: boolean): Promise<GenericCommandResponse> {
+        return this.post("/reindex", { payload: { recreateIndex } });
+    }
+
+    /**
+     * Enable indexing for this project
+     */
+    async enableIndexing(): Promise<GenericCommandResponse> {
+        return this.post("/enable-indexing");
+    }
+
+    /**
+     * Disable indexing for this project
+     */
+    async disableIndexing(): Promise<GenericCommandResponse> {
+        return this.post("/disable-indexing");
+    }
+
+    /**
+     * Enable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    async enableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/enable-queries");
+    }
+
+    /**
+     * Disable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    async disableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/disable-queries");
+    }
+
+    // ========================================================================
+    // Internal endpoints - called by Temporal workflow activities
+    // ========================================================================
+
+    /**
+     * Index a single document to Elasticsearch
+     */
+    index(objectId: string, document: ElasticsearchDocumentData): Promise<{ status: string; objectId: string }> {
+        return this.post("/internal/index", {
+            payload: { objectId, document },
+        });
+    }
+
+    /**
+     * Delete a document from Elasticsearch
+     */
+    delete(objectId: string): Promise<{ status: string; objectId: string }> {
+        return this.post("/internal/delete", {
+            payload: { objectId },
+        });
+    }
+
+    /**
+     * Bulk index multiple documents to Elasticsearch
+     *
+     * @param documents Array of documents to index
+     * @param targetIndex Optional explicit index name for zero-downtime reindexing
+     */
+    bulkIndex(
+        documents: Array<{ id: string; document: ElasticsearchDocumentData }>,
+        targetIndex?: string
+    ): Promise<BulkIndexResult> {
+        return this.post("/internal/bulk-index", {
+            payload: { documents, targetIndex },
+        });
+    }
+
+    /**
+     * Ensure Elasticsearch index exists for the project
+     *
+     * @param recreate If true, drops and recreates the index
+     */
+    ensureIndex(recreate?: boolean): Promise<EnsureIndexResult> {
+        return this.post("/internal/ensure-index", {
+            payload: { recreate },
+        });
+    }
+
+    /**
+     * Create a new versioned index for reindexing (without alias)
+     * The alias will be swapped after reindexing completes via swapAlias
+     */
+    createReindexTarget(): Promise<CreateReindexTargetResult> {
+        return this.post("/internal/create-reindex-target", {
+            payload: {},
+        });
+    }
+
+    /**
+     * Atomically swap the alias from old index to new index
+     *
+     * @param newIndexName The new index to point the alias to
+     * @param deleteOld If true, deletes the old index after swapping
+     */
+    swapAlias(newIndexName: string, deleteOld?: boolean): Promise<SwapAliasResult> {
+        return this.post("/internal/swap-alias", {
+            payload: { newIndexName, deleteOld },
+        });
+    }
+
+    /**
+     * Get Elasticsearch index statistics for the project
+     */
+    getStats(): Promise<ElasticsearchIndexStats> {
+        return this.post("/internal/stats", {
+            payload: {},
+        });
+    }
+
+    /**
+     * Get the _id range for reindexing (first, last, count)
+     * Used by workflow to set up cursor-based pagination
+     */
+    getReindexRange(): Promise<ReindexRangeResult> {
+        return this.post("/internal/reindex-range", {
+            payload: {},
+        });
+    }
+
+    /**
+     * Fetch a batch of documents from MongoDB (without indexing)
+     * Used by pipeline approach: fetch next batch while indexing current
+     *
+     * @param cursor Cursor from previous batch (null for first batch)
+     * @param limit Maximum documents to fetch (default: 500)
+     */
+    fetchBatch(cursor?: string | null, limit?: number): Promise<FetchBatchResult> {
+        return this.post("/internal/fetch-batch", {
+            payload: { cursor, limit },
+        });
+    }
+
+    /**
+     * Fetch and index a batch of documents (server-side)
+     * Uses cursor-based pagination for reliability
+     *
+     * @param cursor Cursor from previous batch (null for first batch)
+     * @param limit Maximum documents to process (default: 500)
+     * @param targetIndex Optional explicit index name for zero-downtime reindexing
+     * @param since Only index docs with updated_at >= this ISO timestamp (for catch-up after reindex)
+     */
+    indexBatch(cursor?: string | null, limit?: number, targetIndex?: string, since?: string): Promise<IndexBatchResult> {
+        return this.post("/internal/index-batch", {
+            payload: { cursor, limit, targetIndex, since },
+        });
+    }
+
+    /**
+     * Trigger a reindex operation via Temporal workflow (internal version with more options)
+     *
+     * @param fullReindex If true, reindexes all documents in the project
+     * @param objectIds Specific object IDs to reindex (if not fullReindex)
+     * @param recreateIndex If true, recreates the index before reindexing
+     */
+    triggerReindex(options?: {
+        fullReindex?: boolean;
+        objectIds?: string[];
+        recreateIndex?: boolean;
+    }): Promise<TriggerReindexResult> {
+        return this.post("/internal/trigger-reindex", {
+            payload: options ?? {},
+        });
+    }
+
+    /**
+     * Fetch documents by their IDs from MongoDB (for retry workflow)
+     * Returns documents ready for bulk indexing
+     *
+     * @param objectIds Array of object IDs to fetch
+     */
+    fetchDocumentsByIds(objectIds: string[]): Promise<FetchDocumentsByIdsResult> {
+        return this.post("/internal/fetch-by-ids", {
+            payload: { objectIds },
+        });
+    }
+
+    /**
+     * Bulk delete documents from Elasticsearch
+     *
+     * @param objectIds Array of object IDs to delete
+     */
+    bulkDelete(objectIds: string[]): Promise<BulkDeleteResult> {
+        return this.post("/internal/bulk-delete", {
+            payload: { objectIds },
+        });
+    }
+
+    /**
+     * Get detailed index configuration for the project
+     *
+     * Returns comprehensive information about the Elasticsearch index including
+     * status, embedding dimensions, field mappings, and project configuration.
+     */
+    getConfiguration(): Promise<IndexConfiguration> {
+        return this.post("/internal/configuration", {
+            payload: {},
+        });
+    }
+}

package/src/store/ObjectsApi.ts

@@ -1,10 +1,10 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
 import {
     canGenerateRendition,
-    ContentObjectApiHeaders,
     ComplexSearchPayload,
     ComputeObjectFacetPayload,
     ContentObject,
+    ContentObjectApiHeaders,
     ContentObjectItem,
     ContentObjectProcessingPriority,
     ContentSource,
@@ -23,7 +23,7 @@ import {
     ObjectSearchPayload,
     ObjectSearchQuery,
     SupportedEmbeddingTypes,
-    supportsVisualRendition,
+    supportsVisualRendition
 } from "@vertesia/common";
 
 // Re-export rendition utilities for consumers
@@ -151,6 +151,7 @@ export class ObjectsApi extends ApiTopic {
             name: source.name,
             mime_type: source.type,
         });
+        const sourceMimeType = source.type || mime_type;
 
         // upload the file content to the signed URL
         /*const res = await this.fetch(url, {
@@ -175,9 +176,7 @@ export class ObjectsApi extends ApiTopic {
             body: isStream ? source.stream : source,
             //@ts-ignore: duplex is not in the types. See https://github.com/node-fetch/node-fetch/issues/1769
             duplex: isStream ? "half" : undefined,
-            headers: {
-                "Content-Type": mime_type || "application/octet-stream",
-            },
+            headers: sourceMimeType ? { "Content-Type": sourceMimeType } : undefined,
         })
             .then((res: Response) => {
                 if (res.ok) {
@@ -201,7 +200,7 @@ export class ObjectsApi extends ApiTopic {
         return {
             source: id,
             name: source.name,
-            type: mime_type,
+            type: sourceMimeType,
             etag,
         };
     }
@@ -226,7 +225,7 @@ export class ObjectsApi extends ApiTopic {
         const headers: Record<string, string> = {};
         if (options?.processing_priority) {
             headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
-        } 
+        }
         if (options?.collection_id) {
             headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
         }
@@ -270,7 +269,7 @@ export class ObjectsApi extends ApiTopic {
         const headers: Record<string, string> = {};
         if (options?.processing_priority) {
             headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
-        } 
+        }
         if (options?.collection_id) {
             headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
         }
@@ -301,6 +300,8 @@ export class ObjectsApi extends ApiTopic {
             revisionLabel?: string;
             processing_priority?: ContentObjectProcessingPriority;
             suppressWorkflows?: boolean;
+            /** If provided, the server will reject the update with 412 if the document's content etag no longer matches. */
+            ifMatch?: string;
         },
     ): Promise<ContentObject> {
         const updatePayload: Partial<CreateContentObjectPayload> = {
@@ -316,6 +317,9 @@ export class ObjectsApi extends ApiTopic {
         }
 
         const headers: Record<string, string> = {};
+        if (options?.ifMatch) {
+            headers['if-match'] = options.ifMatch;
+        }
         if (options?.processing_priority) {
             headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
         }

package/src/store/QueryApi.ts

@@ -0,0 +1,110 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+
+/**
+ * Query payload for agent data access
+ */
+export interface QueryPayload {
+    /** SQL query (uses ES SQL API) */
+    sql?: string;
+    /** ES|QL query (Elastic's piped query language) */
+    esql?: string;
+    /** Raw DSL query for full control */
+    dsl?: {
+        query?: Record<string, unknown>;
+        aggs?: Record<string, unknown>;
+        size?: number;
+        from?: number;
+        sort?: Array<Record<string, unknown>>;
+    };
+    /** Output format */
+    format?: 'json' | 'csv' | 'table';
+}
+
+/**
+ * Query result
+ */
+export interface QueryResult {
+    /** Result type */
+    type: 'sql' | 'esql' | 'dsl';
+    /** Column definitions */
+    columns?: Array<{ name: string; type: string }>;
+    /** Rows for SQL/ES|QL */
+    rows?: unknown[][];
+    /** Hits for DSL */
+    hits?: Array<{ id: string; score: number; source: unknown }>;
+    /** Total count */
+    total?: number;
+    /** Aggregations for DSL */
+    aggregations?: Record<string, unknown>;
+    /** Cursor for pagination (SQL) */
+    cursor?: string;
+    /** Query execution time in ms */
+    took?: number;
+}
+
+/**
+ * API for querying documents using SQL, ES|QL, or raw Elasticsearch DSL.
+ * All queries are automatically filtered based on the authenticated user's permissions.
+ */
+export class QueryApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/query") {
+        super(parent, basePath);
+    }
+
+    /**
+     * Execute a query against the project's document index
+     *
+     * @param payload - Query payload with sql, esql, or dsl
+     * @returns Query result with columns/rows or hits/aggregations
+     *
+     * @example SQL query
+     * ```typescript
+     * const result = await client.query.execute({
+     *   sql: "SELECT name, status FROM content WHERE status = 'published' LIMIT 10"
+     * });
+     * ```
+     *
+     * @example ES|QL query
+     * ```typescript
+     * const result = await client.query.execute({
+     *   esql: "FROM content | WHERE status == 'published' | STATS count = COUNT(*) BY type.name"
+     * });
+     * ```
+     *
+     * @example DSL query with aggregations
+     * ```typescript
+     * const result = await client.query.execute({
+     *   dsl: {
+     *     query: { match: { text: "machine learning" } },
+     *     aggs: { by_type: { terms: { field: "type.name" } } },
+     *     size: 10
+     *   }
+     * });
+     * ```
+     */
+    async execute(payload: QueryPayload): Promise<QueryResult> {
+        return this.post("/", { payload });
+    }
+
+    /**
+     * Execute a SQL query
+     */
+    async sql(query: string): Promise<QueryResult> {
+        return this.execute({ sql: query });
+    }
+
+    /**
+     * Execute an ES|QL query
+     */
+    async esql(query: string): Promise<QueryResult> {
+        return this.execute({ esql: query });
+    }
+
+    /**
+     * Execute a DSL query
+     */
+    async dsl(query: QueryPayload['dsl']): Promise<QueryResult> {
+        return this.execute({ dsl: query });
+    }
+}