@vertesia/client 0.81.1 → 1.0.0-dev.20260203.130115Z

package/src/store/IndexingAdminApi.ts

@@ -0,0 +1,336 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+
+/**
+ * Document data structure for Elasticsearch indexing
+ */
+export interface ElasticsearchDocumentData {
+    name?: string;
+    text?: string;
+    properties?: Record<string, unknown>;
+    status?: string;
+    type?: {
+        id?: string;
+        name?: string;
+    };
+    security?: {
+        'content:read'?: string[];
+        'content:write'?: string[];
+        'content:delete'?: string[];
+    };
+    revision?: {
+        head?: boolean;
+        root?: string;
+    };
+    embeddings_text?: number[];
+    embeddings_image?: number[];
+    embeddings_properties?: number[];
+    created_at?: Date | string;
+    updated_at?: Date | string;
+}
+
+/**
+ * Result from bulk indexing
+ */
+export interface BulkIndexResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Result from creating a reindex target
+ */
+export interface CreateReindexTargetResult {
+    created: boolean;
+    indexName: string;
+    aliasName: string;
+    version: number;
+}
+
+/**
+ * Result from getting reindex range
+ */
+export interface ReindexRangeResult {
+    first: string | null;
+    last: string | null;
+    count: number;
+}
+
+/**
+ * Result from fetching a batch
+ */
+export interface FetchBatchResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from indexing a batch
+ */
+export interface IndexBatchResult {
+    successful: number;
+    failed: number;
+    processed: number;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from triggering a reindex
+ */
+export interface TriggerReindexResult {
+    status: string;
+    workflow?: string;
+    workflowId?: string;
+    runId?: string;
+    objectCount?: number;
+    reason?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Elasticsearch index statistics
+ */
+export interface ElasticsearchIndexStats {
+    enabled: boolean;
+    exists?: boolean;
+    documentCount?: number;
+    sizeInBytes?: number;
+    indexName?: string;
+    aliasName?: string;
+}
+
+/**
+ * Embedding configuration for a single type
+ */
+export interface EmbeddingTypeConfig {
+    environment?: string;
+    dimensions?: number;
+    model?: string;
+    provider?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Detailed index configuration
+ */
+export interface IndexConfiguration {
+    enabled: boolean;
+    exists?: boolean;
+    indexName?: string;
+    aliasName?: string;
+    version?: number;
+    documentCount?: number;
+    sizeInBytes?: number;
+    embeddingDimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    fieldMappings?: Record<string, unknown>;
+    projectEmbeddingsConfig?: {
+        text?: EmbeddingTypeConfig;
+        image?: EmbeddingTypeConfig;
+        properties?: EmbeddingTypeConfig;
+    };
+    createdAt?: Date | null;
+}
+
+/**
+ * Result from fetching documents by IDs
+ */
+export interface FetchDocumentsByIdsResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    notFound: string[];
+}
+
+/**
+ * Result from bulk delete
+ */
+export interface BulkDeleteResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Admin API for Elasticsearch operations
+ *
+ * These methods are called by Temporal workflow activities to perform
+ * Elasticsearch operations. They require content admin permissions.
+ */
+export class IndexingAdminApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/admin/elasticsearch") {
+        super(parent, basePath);
+    }
+
+    /**
+     * Index a single document to Elasticsearch
+     */
+    index(objectId: string, document: ElasticsearchDocumentData): Promise<{ status: string; objectId: string }> {
+        return this.post("/index", {
+            payload: { objectId, document },
+        });
+    }
+
+    /**
+     * Delete a document from Elasticsearch
+     */
+    delete(objectId: string): Promise<{ status: string; objectId: string }> {
+        return this.post("/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("/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<{ created: boolean; recreated?: boolean; existed?: boolean }> {
+        return this.post("/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("/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<{ swapped: boolean; aliasName?: string; newIndexName?: string }> {
+        return this.post("/swap-alias", {
+            payload: { newIndexName, deleteOld },
+        });
+    }
+
+    /**
+     * Get Elasticsearch index statistics for the project
+     */
+    getStats(): Promise<ElasticsearchIndexStats> {
+        return this.post("/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("/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("/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
+     */
+    indexBatch(cursor?: string | null, limit?: number, targetIndex?: string): Promise<IndexBatchResult> {
+        return this.post("/index-batch", {
+            payload: { cursor, limit, targetIndex },
+        });
+    }
+
+    /**
+     * Trigger a reindex operation via Temporal workflow
+     *
+     * @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("/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("/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("/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("/configuration", {
+            payload: {},
+        });
+    }
+}

package/src/store/IndexingApi.ts

@@ -0,0 +1,62 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    IndexingStatusResponse,
+    GenericCommandResponse,
+} from "@vertesia/common";
+
+/**
+ * API for indexing operations on content objects.
+ * Provides status, reindex, and configuration management.
+ */
+export class IndexingApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/indexing") {
+        super(parent, basePath);
+    }
+
+    /**
+     * 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
+     * (routes searches to index instead of Atlas Search)
+     */
+    async enableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/enable-queries");
+    }
+
+    /**
+     * Disable index-based queries for this project
+     * (routes searches back to Atlas Search)
+     */
+    async disableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/disable-queries");
+    }
+
+}

package/src/store/ObjectsApi.ts

@@ -1,5 +1,6 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
 import {
+    canGenerateRendition,
     ContentObjectApiHeaders,
     ComplexSearchPayload,
     ComputeObjectFacetPayload,
@@ -16,13 +17,18 @@ import {
     GetFileUrlResponse,
     GetRenditionParams,
     GetRenditionResponse,
+    getSupportedRenditionFormats,
     GetUploadUrlPayload,
     ListWorkflowRunsResponse,
     ObjectSearchPayload,
     ObjectSearchQuery,
     SupportedEmbeddingTypes,
+    supportsVisualRendition,
 } from "@vertesia/common";
 
+// Re-export rendition utilities for consumers
+export { canGenerateRendition, getSupportedRenditionFormats, supportsVisualRendition };
+
 import { StreamSource } from "../StreamSource.js";
 import { AnalyzeDocApi } from "./AnalyzeDocApi.js";
 import { ZenoClient } from "./client.js";
@@ -284,6 +290,7 @@ export class ObjectsApi extends ApiTopic {
      * @param options Additional options
      * @param options.createRevision Whether to create a new revision instead of updating in place
      * @param options.revisionLabel Optional label for the revision (e.g., "v1.2")
+     * @param options.suppressWorkflows When true, prevents this update from triggering workflow rules
      * @returns The updated object or newly created revision
      */
     async update(
@@ -293,6 +300,7 @@ export class ObjectsApi extends ApiTopic {
             createRevision?: boolean;
             revisionLabel?: string;
             processing_priority?: ContentObjectProcessingPriority;
+            suppressWorkflows?: boolean;
         },
     ): Promise<ContentObject> {
         const updatePayload: Partial<CreateContentObjectPayload> = {
@@ -317,6 +325,9 @@ export class ObjectsApi extends ApiTopic {
                 headers[ContentObjectApiHeaders.REVISION_LABEL] = options.revisionLabel;
             }
         }
+        if (options?.suppressWorkflows) {
+            headers[ContentObjectApiHeaders.SUPPRESS_WORKFLOWS] = "true";
+        }
 
         return this.put(`/${id}`, {
             payload: updatePayload,
@@ -372,6 +383,35 @@ export class ObjectsApi extends ApiTopic {
         });
     }
 
+    /**
+     * Get rendition with pre-validation of content type compatibility.
+     * Returns null instead of throwing if the format is not supported for the content type.
+     *
+     * @param documentId - The document ID
+     * @param contentType - The content type of the document (e.g., 'image/png', 'text/markdown')
+     * @param options - Rendition options including format
+     * @returns The rendition response, or null if format is not supported for the content type
+     *
+     * @example
+     * const rendition = await client.objects.getRenditionSafe(docId, doc.content?.type, {
+     *     format: ImageRenditionFormat.jpeg,
+     *     generate_if_missing: true
+     * });
+     * if (!rendition) {
+     *     console.log('Document does not support JPEG renditions');
+     * }
+     */
+    getRenditionSafe(
+        documentId: string,
+        contentType: string | undefined,
+        options: GetRenditionParams,
+    ): Promise<GetRenditionResponse | null> {
+        if (!canGenerateRendition(contentType, options.format)) {
+            return Promise.resolve(null);
+        }
+        return this.getRendition(documentId, options);
+    }
+
     exportProperties(
         payload: ExportPropertiesPayload,
     ): Promise<ExportPropertiesResponse> {

package/src/store/PendingAsksApi.ts

@@ -0,0 +1,98 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { ListPendingAsksResponse, PendingAskData, UserChannel } from "@vertesia/common";
+
+/**
+ * Request to register a pending ask.
+ */
+export interface RegisterPendingAskRequest {
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Name of the agent/interaction */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Timeout in hours (default 48) */
+    timeoutHours?: number;
+    /** User communication channels */
+    userChannels: UserChannel[];
+}
+
+/**
+ * Response from registering a pending ask.
+ */
+export interface RegisterPendingAskResponse {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** Generated ask ID */
+    askId?: string;
+    /** Whether webhook was sent */
+    webhookSent?: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Request to resolve a pending ask.
+ */
+export interface ResolvePendingAskRequest {
+    /** User's response */
+    response: string;
+}
+
+/**
+ * Response from resolving a pending ask.
+ */
+export interface ResolvePendingAskResponse {
+    /** Whether resolution succeeded */
+    success: boolean;
+    /** Whether webhook was sent */
+    webhookSent?: boolean;
+    /** How long the user took to respond (ms) */
+    waitDurationMs?: number;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Pending Asks API for tracking ask_user requests.
+ * Handles registration, resolution, and listing of pending asks.
+ */
+export class PendingAsksApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/pending-asks");
+    }
+
+    /**
+     * Register a new pending ask.
+     * Called when an agent calls ask_user.
+     * Stores in Redis and sends webhook if configured.
+     */
+    register(request: RegisterPendingAskRequest): Promise<RegisterPendingAskResponse> {
+        return this.post("/", { payload: request });
+    }
+
+    /**
+     * Resolve a pending ask with the user's response.
+     * Called when a user responds to an ask.
+     * Updates Redis and sends webhook if configured.
+     */
+    resolve(askId: string, request: ResolvePendingAskRequest): Promise<ResolvePendingAskResponse> {
+        return this.post(`/${askId}/resolve`, { payload: request });
+    }
+
+    /**
+     * List all pending asks for the current project.
+     */
+    list(): Promise<ListPendingAsksResponse> {
+        return this.get("/");
+    }
+
+    /**
+     * Get a specific pending ask by ID.
+     */
+    retrieve(askId: string): Promise<PendingAskData> {
+        return this.get(`/${askId}`);
+    }
+}

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 });
+    }
+}