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

package/lib/types/store/EmailApi.d.ts

@@ -0,0 +1,185 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { EmailRouteData } from "@vertesia/common";
+/**
+ * Request payload for sending an email via the agent.
+ * Resend configuration is fetched from project settings.
+ * From address is constructed as: {project_namespace}+{agent_name}@{email_domain}
+ */
+export interface SendEmailRequest {
+    /** Email address to send to */
+    to_email: string;
+    /** Email subject */
+    subject: string;
+    /** Email body in markdown format */
+    body: string;
+    /** Agent/interaction endpoint name (used in from address) */
+    agent_name: string;
+    /** Display name for the sender (overrides project default) */
+    from_name?: string;
+    /** Workflow run ID for routing replies */
+    run_id: string;
+    /** Existing route key (for subsequent emails in same conversation) */
+    route_key?: string;
+    /** Message ID for In-Reply-To header (email threading) */
+    in_reply_to?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+}
+/**
+ * Response from sending an email.
+ */
+export interface SendEmailResponse {
+    success: boolean;
+    /** Resend email ID */
+    email_id?: string;
+    /** Message-ID header for threading */
+    message_id?: string;
+    /** Short route key for reply routing */
+    route_key?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Response from creating an email route.
+ */
+export interface CreateRouteResponse {
+    /** The generated route key (8-char alphanumeric) */
+    route_key: string;
+    /** Full reply-to address: r+{route_key}@{email_domain} */
+    reply_to: string;
+    /** The email domain for sending and receiving */
+    email_domain: string;
+}
+/**
+ * Request to forward an email to a workflow.
+ * Used by external services that handle email reception themselves.
+ */
+export interface ForwardEmailRequest {
+    /** Email content received by the external service */
+    email: {
+        /** Sender email address */
+        from: string;
+        /** Email subject */
+        subject?: string;
+        /** Plain text body */
+        text: string;
+        /** HTML body (optional) */
+        html?: string;
+        /** Message-ID header for threading */
+        message_id?: string;
+    };
+    /** Custom context data from the external service (e.g., auth tokens, user IDs) */
+    context?: Record<string, unknown>;
+    /** Attachments with download URLs */
+    attachments?: Array<{
+        filename: string;
+        content_type: string;
+        size: number;
+        download_url: string;
+    }>;
+}
+/**
+ * Response from forwarding an email.
+ */
+export interface ForwardEmailResponse {
+    success: boolean;
+    run_id: string;
+    workflow_id: string;
+    route_key: string;
+}
+/**
+ * Request to create an email route.
+ */
+export interface CreateRouteRequest {
+    /** Workflow run ID for routing replies */
+    run_id: string;
+    /** Email address of the user (for context) */
+    user_email: string;
+    /** Subject of the email thread (optional) */
+    thread_subject?: string;
+}
+/**
+ * Email API for sending emails from workflows.
+ */
+export declare class EmailApi extends ApiTopic {
+    constructor(parent: ClientBase);
+    /**
+     * Send an email from an agent/workflow.
+     * Creates a route key if not provided, sends via Resend, and returns routing info.
+     */
+    send(request: SendEmailRequest): Promise<SendEmailResponse>;
+    /**
+     * Resolve a route key to get email context.
+     * Used by webhook handler to look up workflow info from reply email.
+     * @deprecated Use getRoute() instead
+     */
+    resolveRoute(routeKey: string): Promise<EmailRouteData>;
+    /**
+     * Create a new email route without sending an email.
+     * Useful for external services that want to handle email sending themselves
+     * but need reply routing back to Vertesia workflows.
+     *
+     * @example
+     * ```ts
+     * const { route_key, reply_to } = await client.store.email.createRoute({
+     *     run_id: workflowRunId,
+     *     user_email: "user@example.com",
+     *     thread_subject: "Contract Review"
+     * });
+     * // Use reply_to as the Reply-To header when sending your own email
+     * // Replies will be routed back to the workflow
+     * ```
+     */
+    createRoute(request: CreateRouteRequest): Promise<CreateRouteResponse>;
+    /**
+     * Get an email route by key.
+     */
+    getRoute(routeKey: string): Promise<EmailRouteData & {
+        route_key: string;
+    }>;
+    /**
+     * Update an email route (e.g., to update threading info).
+     */
+    updateRoute(routeKey: string, updates: Partial<EmailRouteData>): Promise<{
+        success: boolean;
+        route_key: string;
+    }>;
+    /**
+     * Forward an email to a workflow via route key.
+     *
+     * Use this when your service receives an email reply and needs to forward
+     * it to the Vertesia workflow. You can add custom context data (like auth
+     * tokens or user IDs) that will be merged into `payload.vars.data`.
+     *
+     * **Important**: Use camelCase keys in context to match the agent start
+     * pattern. This ensures tools work identically whether the agent was
+     * started directly or received an email reply.
+     *
+     * @example
+     * ```ts
+     * // In your email webhook handler:
+     * const result = await client.store.email.forwardEmail(routeKey, {
+     *     email: {
+     *         from: inboundEmail.from,
+     *         subject: inboundEmail.subject,
+     *         text: inboundEmail.text,
+     *         message_id: inboundEmail.messageId,
+     *     },
+     *     context: {
+     *         // Use camelCase - merged into payload.vars.data
+     *         apiKey: generateServiceToken(),
+     *         tenantId: resolvedUser.tenantId,
+     *         userId: resolvedUser.id,
+     *         userEmail: resolvedUser.email,
+     *     },
+     *     attachments: inboundEmail.attachments?.map(att => ({
+     *         filename: att.filename,
+     *         content_type: att.contentType,
+     *         size: att.size,
+     *         download_url: att.url,
+     *     })),
+     * });
+     * ```
+     */
+    forwardEmail(routeKey: string, request: ForwardEmailRequest): Promise<ForwardEmailResponse>;
+}

package/lib/types/store/EmailApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailApi.d.ts","sourceRoot":"","sources":["../../../src/store/EmailApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,qDAAqD;IACrD,KAAK,EAAE;QACH,2BAA2B;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,oBAAoB;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sBAAsB;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,2BAA2B;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,sCAAsC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,WAAW,CAAC,EAAE,KAAK,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;CACN;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;gBACtB,MAAM,EAAE,UAAU;IAI9B;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI3D;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAQvD;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAItE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3E;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAIjH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAG9F"}

package/lib/types/store/EmbeddingsApi.d.ts

@@ -0,0 +1,12 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { EmbeddingsStatusResponse, GenericCommandResponse, ProjectConfigurationEmbeddings, SupportedEmbeddingTypes } from "@vertesia/common";
+/**
+ * @since 0.52.0
+ */
+export declare class EmbeddingsApi extends ApiTopic {
+    constructor(parent: ClientBase, basePath?: string);
+    status(type: SupportedEmbeddingTypes): Promise<EmbeddingsStatusResponse>;
+    activate(type: SupportedEmbeddingTypes, config: Partial<ProjectConfigurationEmbeddings>): Promise<GenericCommandResponse>;
+    disable(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse>;
+    recalculate(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse>;
+}

package/lib/types/store/EmbeddingsApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingsApi.d.ts","sourceRoot":"","sources":["../../../src/store/EmbeddingsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACH,wBAAwB,EACxB,sBAAsB,EACtB,8BAA8B,EAC9B,uBAAuB,EAC1B,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAE3B,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA6B;IAIjE,MAAM,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAIxE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,EAAE,MAAM,EAAE,OAAO,CAAC,8BAA8B,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC;IASzH,OAAO,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAIvE,WAAW,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAIpF"}

package/lib/types/store/FilesApi.d.ts

@@ -0,0 +1,110 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { GetFileUrlPayload, GetFileUrlResponse, GetUploadUrlPayload } from "@vertesia/common";
+import { StreamSource } from "../StreamSource.js";
+export declare const MEMORIES_PREFIX = "memories";
+export declare const ARTIFACTS_PREFIX = "agents";
+export declare function getMemoryFilePath(name: string): string;
+/**
+ * Build the storage path for an agent artifact
+ * @param runId - The workflow run ID
+ * @param name - The artifact filename
+ */
+export declare function getAgentArtifactPath(runId: string, name: string): string;
+export declare class FilesApi extends ApiTopic {
+    constructor(parent: ClientBase);
+    deleteFile(path: string, prefix?: boolean): Promise<void | number>;
+    /**
+     * get the metadata of a blob given its URI. Supported URI are:
+     * starting with s3:// and gs://.
+     * For s3 blobs use #region to specify the region. Ex: s3://bucket/key#us-west-2
+     * @param uri
+     * @returns
+     */
+    getMetadata(uri: string): Promise<{
+        name: string;
+        size: number;
+        contentType: string;
+        contentDisposition?: string;
+        etag?: string;
+        customMetadata?: Record<string, string>;
+    }>;
+    /**
+     * Set custom metadata on a file
+     * @param file - The file path or URI
+     * @param metadata - Custom metadata key-value pairs
+     * @returns Success status
+     */
+    setFileMetadata(file: string, metadata: Record<string, string>): Promise<{
+        success: boolean;
+        file: string;
+    }>;
+    /**
+     * Get or create a bucket for the project. If the bucket already exists, it does nothing.
+     * The bucket URI is returned.
+     * @returns
+     */
+    getOrCreateBucket(): Promise<{
+        bucket: string;
+    }>;
+    getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse>;
+    getDownloadUrl(file: string, name?: string, disposition?: "inline" | "attachment"): Promise<GetFileUrlResponse>;
+    getDownloadUrlWithOptions(payload: GetFileUrlPayload): Promise<GetFileUrlResponse>;
+    /**
+     * Upload content to a file and return the full path (including bucket name) of the uploaded file
+     * @param source
+     * @returns
+     */
+    uploadFile(source: StreamSource | File): Promise<string>;
+    /**
+     *
+     * @param location can be a relative path in the project, a reference to a cloud storage, or a accessible HTTPS URL (typically signed URL)
+     * @returns ReadableStream
+     */
+    downloadFile(location: string): Promise<ReadableStream<Uint8Array<ArrayBuffer>>>;
+    /**
+     * Copy a file to a new destination within the same bucket.
+     * @param source - Source file path (relative to project bucket)
+     * @param dest - Destination file path (relative to project bucket)
+     * @returns The destination file URI
+     */
+    copyFile(source: string, dest: string): Promise<string>;
+    uploadMemoryPack(source: StreamSource | File): Promise<string>;
+    downloadMemoryPack(name: string, gunzip?: boolean): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * List files by prefix
+     * @param prefix - Path prefix to filter files
+     * @returns Array of file paths matching the prefix
+     */
+    listByPrefix(prefix: string): Promise<{
+        files: string[];
+    }>;
+    /**
+     * Upload an artifact for an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name (e.g., "output.json")
+     * @param source - File content source
+     * @returns The full path of the uploaded artifact
+     */
+    uploadArtifact(runId: string, name: string, source: StreamSource | File): Promise<string>;
+    /**
+     * Download an artifact from an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @returns ReadableStream of the artifact content
+     */
+    downloadArtifact(runId: string, name: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Get download URL for an artifact
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @param disposition - Content disposition (inline or attachment)
+     * @returns Signed URL response
+     */
+    getArtifactDownloadUrl(runId: string, name: string, disposition?: "inline" | "attachment"): Promise<GetFileUrlResponse>;
+    /**
+     * List artifacts for an agent run
+     * @param runId - The workflow run ID
+     * @returns Array of artifact file paths
+     */
+    listArtifacts(runId: string): Promise<string[]>;
+}

package/lib/types/store/FilesApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilesApi.d.ts","sourceRoot":"","sources":["../../../src/store/FilesApi.ts"],"names":[],"mappings":"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"}

package/lib/types/store/HiveMemoryApi.d.ts

@@ -0,0 +1,160 @@
+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 declare class HiveMemoryApi extends ApiTopic {
+    constructor(parent: ClientBase);
+    /**
+     * List memories in the project.
+     *
+     * @param options - Optional filters and pagination
+     */
+    list(options?: {
+        category?: string;
+        scope?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<HiveMemory[]>;
+    /**
+     * Retrieve a memory by ID.
+     */
+    retrieve(id: string): Promise<HiveMemory>;
+    /**
+     * Create a new hive memory.
+     *
+     * @param payload - Memory content including category, summary, and learnings
+     */
+    create(payload: CreateHiveMemoryPayload): Promise<HiveMemory>;
+    /**
+     * 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>;
+    /**
+     * Delete a memory.
+     *
+     * @param id - Memory ID
+     */
+    delete(id: string): Promise<{
+        id: string;
+        deleted: boolean;
+    }>;
+    /**
+     * Search memories using semantic and keyword search.
+     *
+     * @param params - Search parameters including query, filters, and pagination
+     */
+    search(params: HiveMemorySearchParams): Promise<HiveMemorySearchResult>;
+    /**
+     * 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>;
+    /**
+     * Get a memory formatted for agent consumption.
+     *
+     * @param id - Memory ID
+     */
+    getFormatted(id: string): Promise<FormattedMemoryForAgent>;
+    /**
+     * 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;
+    }>;
+    /**
+     * 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[]>;
+    /**
+     * Get memory statistics for the project.
+     */
+    getStats(): Promise<HiveMemoryStats>;
+    /**
+     * 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;
+    }>;
+    /**
+     * 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;
+    }>;
+}

package/lib/types/store/HiveMemoryApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HiveMemoryApi.d.ts","sourceRoot":"","sources":["../../../src/store/HiveMemoryApi.ts"],"names":[],"mappings":"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"}

package/lib/types/store/IndexingApi.d.ts

@@ -0,0 +1,140 @@
+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 declare class IndexingApi extends ApiTopic {
+    constructor(parent: ClientBase, basePath?: string);
+    /**
+     * Get Elasticsearch status for the current project
+     */
+    status(): Promise<IndexingStatusResponse>;
+    /**
+     * Trigger a full reindex of all documents
+     * @param recreateIndex If true, drops and recreates the index before reindexing
+     */
+    reindex(recreateIndex?: boolean): Promise<GenericCommandResponse>;
+    /**
+     * Enable indexing for this project
+     */
+    enableIndexing(): Promise<GenericCommandResponse>;
+    /**
+     * Disable indexing for this project
+     */
+    disableIndexing(): Promise<GenericCommandResponse>;
+    /**
+     * Enable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    enableQueries(): Promise<GenericCommandResponse>;
+    /**
+     * Disable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    disableQueries(): Promise<GenericCommandResponse>;
+    /**
+     * Index a single document to Elasticsearch
+     */
+    index(objectId: string, document: ElasticsearchDocumentData): Promise<{
+        status: string;
+        objectId: string;
+    }>;
+    /**
+     * Delete a document from Elasticsearch
+     */
+    delete(objectId: string): Promise<{
+        status: string;
+        objectId: string;
+    }>;
+    /**
+     * 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>;
+    /**
+     * Ensure Elasticsearch index exists for the project
+     *
+     * @param recreate If true, drops and recreates the index
+     */
+    ensureIndex(recreate?: boolean): Promise<EnsureIndexResult>;
+    /**
+     * Create a new versioned index for reindexing (without alias)
+     * The alias will be swapped after reindexing completes via swapAlias
+     */
+    createReindexTarget(): Promise<CreateReindexTargetResult>;
+    /**
+     * 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>;
+    /**
+     * Get Elasticsearch index statistics for the project
+     */
+    getStats(): Promise<ElasticsearchIndexStats>;
+    /**
+     * Get the _id range for reindexing (first, last, count)
+     * Used by workflow to set up cursor-based pagination
+     */
+    getReindexRange(): Promise<ReindexRangeResult>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Bulk delete documents from Elasticsearch
+     *
+     * @param objectIds Array of object IDs to delete
+     */
+    bulkDelete(objectIds: string[]): Promise<BulkDeleteResult>;
+    /**
+     * 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>;
+}

package/lib/types/store/IndexingApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexingApi.d.ts","sourceRoot":"","sources":["../../../src/store/IndexingApi.ts"],"names":[],"mappings":"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"}