captify 0.1.18 → 1.1.0

package/dist/search/services/opensearch.service.js

@@ -0,0 +1,825 @@
+/**
+ * OpenSearch Service
+ *
+ * Client wrapper for OpenSearch operations with support for multi-index search,
+ * user-specific credential management, and automatic retry with exponential backoff.
+ */
+import https from "node:https";
+import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
+import { Client as OpenSearchClient } from "@opensearch-project/opensearch";
+import { AwsSigv4Signer } from "@opensearch-project/opensearch/aws";
+// Custom HTTPS agent with larger connection pool for bulk operations
+const httpsAgent = new https.Agent({
+    keepAlive: true,
+    maxSockets: 50, // Allow more concurrent connections
+    maxFreeSockets: 10,
+    timeout: 60000, // 60 second timeout
+});
+import { BaseAwsService } from "../../shared/services/base-aws-service";
+import { invariant } from "../../shared/utilities/invariant";
+import { ALL_SEARCH_INDICES, INDEX_DEFINITIONS, INDEX_METADATA_KEYS, INDEX_STATUS, MIGRATION_CONFIG, OPENSEARCH_DEFAULT_CONFIG, OPENSEARCH_ERROR_MESSAGES, } from "../search.constants";
+import { InvalidIndexDeletionError, toSearchError } from "../search.errors";
+/**
+ * OpenSearch service for search operations.
+ *
+ * Features:
+ * - Multi-index search support
+ * - AWS IAM authentication via SigV4
+ * - User-specific credential support for governance compliance
+ * - Basic auth for local development
+ * - Automatic retry with exponential backoff
+ * - Connection health checking
+ *
+ * @example Basic search with user credentials
+ * ```typescript
+ * const service = OpenSearchServiceSingleton.getInstance();
+ *
+ * const results = await service.search({
+ *   indices: ['captify-search-documents', 'captify-search-users'],
+ *   query: {
+ *     multi_match: {
+ *       query: 'test search',
+ *       fields: ['title', 'content', 'name']
+ *     }
+ *   },
+ *   size: 10,
+ *   userCredentials,
+ * });
+ * ```
+ */
+export class OpenSearchService extends BaseAwsService {
+    constructor(deps) {
+        var _a;
+        super({ logger: deps.logger, serviceName: "opensearch" });
+        this.userClients = new Map();
+        this.cleanupInterval = null;
+        this.config = deps.config;
+        this.client = (_a = deps.client) !== null && _a !== void 0 ? _a : this.createServiceClient(deps.config);
+        this.startCleanupInterval();
+    }
+    /**
+     * Start periodic cleanup of stale user clients
+     */
+    startCleanupInterval() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupStaleClients();
+        }, OPENSEARCH_DEFAULT_CONFIG.USER_CLIENT_CLEANUP_INTERVAL_MS);
+        // Ensure interval doesn't prevent process exit
+        this.cleanupInterval.unref();
+    }
+    /**
+     * Cleanup stale user clients (called periodically)
+     */
+    cleanupStaleClients() {
+        const now = Date.now();
+        let cleanedCount = 0;
+        for (const [key, { client, lastUsed }] of this.userClients.entries()) {
+            if (now - lastUsed >= OPENSEARCH_DEFAULT_CONFIG.USER_CLIENT_TTL_MS) {
+                client.close().catch((error) => {
+                    this.logger.debug("Failed to close stale client during cleanup", {
+                        cacheKey: key,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                this.userClients.delete(key);
+                cleanedCount++;
+            }
+        }
+        if (cleanedCount > 0) {
+            this.logger.debug("Cleaned up stale user clients", {
+                cleanedCount,
+                remainingCount: this.userClients.size,
+            });
+        }
+    }
+    /**
+     * Evict least recently used clients when cache exceeds max size
+     */
+    evictLruClients() {
+        const maxSize = OPENSEARCH_DEFAULT_CONFIG.USER_CLIENT_MAX_CACHE_SIZE;
+        if (this.userClients.size <= maxSize) {
+            return;
+        }
+        // Sort entries by lastUsed (oldest first)
+        const entries = [...this.userClients.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+        // Evict oldest entries until we're under the limit
+        const toEvict = entries.slice(0, this.userClients.size - maxSize);
+        for (const [key, { client }] of toEvict) {
+            client.close().catch((error) => {
+                this.logger.debug("Failed to close evicted client during LRU cleanup", {
+                    cacheKey: key,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            this.userClients.delete(key);
+        }
+        this.logger.debug("Evicted LRU user clients", {
+            evictedCount: toEvict.length,
+            remainingCount: this.userClients.size,
+        });
+    }
+    /**
+     * Create OpenSearch client for service account (default client)
+     * Uses AWS SigV4 signing for authentication
+     */
+    createServiceClient(config) {
+        var _a;
+        // If explicit credentials provided, use them; otherwise use default credential chain
+        const { credentials } = config;
+        const credentialProvider = credentials
+            ? () => Promise.resolve({
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                sessionToken: credentials.sessionToken,
+            })
+            : fromNodeProviderChain();
+        return new OpenSearchClient(Object.assign(Object.assign({}, AwsSigv4Signer({
+            region: config.region,
+            service: OPENSEARCH_DEFAULT_CONFIG.AWS_SERVICE_NAME,
+            getCredentials: credentialProvider,
+        })), { node: config.endpoint, requestTimeout: (_a = config.requestTimeout) !== null && _a !== void 0 ? _a : OPENSEARCH_DEFAULT_CONFIG.REQUEST_TIMEOUT_MS, compression: "gzip", maxRetries: OPENSEARCH_DEFAULT_CONFIG.MAX_RETRIES, 
+            // Use 'optimistic' to immediately retry dead nodes on next request
+            // AWS OpenSearch endpoint is a load balancer, so it's always "alive"
+            // Individual request failures shouldn't mark the entire endpoint as dead
+            resurrectStrategy: "optimistic", agent: () => httpsAgent }));
+    }
+    /**
+     * Create OpenSearch client with user credentials for governance
+     */
+    createUserClient(config, credentials) {
+        var _a;
+        return new OpenSearchClient(Object.assign(Object.assign({}, AwsSigv4Signer({
+            region: config.region,
+            service: OPENSEARCH_DEFAULT_CONFIG.AWS_SERVICE_NAME,
+            getCredentials: () => Promise.resolve({
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                sessionToken: credentials.sessionToken,
+            }),
+        })), { node: config.endpoint, requestTimeout: (_a = config.requestTimeout) !== null && _a !== void 0 ? _a : OPENSEARCH_DEFAULT_CONFIG.REQUEST_TIMEOUT_MS, compression: "gzip", maxRetries: OPENSEARCH_DEFAULT_CONFIG.MAX_RETRIES, 
+            // Use 'optimistic' to immediately retry dead nodes on next request
+            resurrectStrategy: "optimistic", agent: () => httpsAgent }));
+    }
+    /**
+     * Get OpenSearch client for operation
+     * If userCredentials are provided, returns a cached client or creates a new one
+     * Otherwise, returns the default service account client
+     */
+    getClientForOperation(userCredentials) {
+        if (!userCredentials) {
+            return this.client;
+        }
+        // Use accessKeyId as cache key (unique per user session)
+        const cacheKey = userCredentials.accessKeyId;
+        const cached = this.userClients.get(cacheKey);
+        const now = Date.now();
+        // Return cached client if still valid
+        if (cached && now - cached.lastUsed < OPENSEARCH_DEFAULT_CONFIG.USER_CLIENT_TTL_MS) {
+            cached.lastUsed = now;
+            return cached.client;
+        }
+        // Close stale client if exists
+        if (cached) {
+            cached.client.close().catch((error) => {
+                this.logger.debug("Failed to close stale cached client", {
+                    cacheKey,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            this.userClients.delete(cacheKey);
+        }
+        // Create new client with user's temporary credentials
+        const newClient = this.createUserClient(this.config, userCredentials);
+        this.userClients.set(cacheKey, { client: newClient, lastUsed: now });
+        // Evict LRU clients if cache exceeds max size
+        this.evictLruClients();
+        return newClient;
+    }
+    /**
+     * Create OpenSearch service with configuration
+     */
+    static create(config, logger) {
+        var _a, _b, _c;
+        invariant((_a = config.endpoint) === null || _a === void 0 ? void 0 : _a.trim(), OPENSEARCH_ERROR_MESSAGES.ENDPOINT_REQUIRED);
+        invariant((_b = config.region) === null || _b === void 0 ? void 0 : _b.trim(), OPENSEARCH_ERROR_MESSAGES.REGION_REQUIRED);
+        const fullConfig = {
+            endpoint: config.endpoint,
+            region: config.region,
+            credentials: config.credentials,
+            requestTimeout: (_c = config.requestTimeout) !== null && _c !== void 0 ? _c : OPENSEARCH_DEFAULT_CONFIG.REQUEST_TIMEOUT_MS,
+        };
+        return new OpenSearchService({ config: fullConfig, logger });
+    }
+    /**
+     * Load configuration from environment variables
+     */
+    static loadEnvConfig() {
+        const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+        const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+        const sessionToken = process.env.AWS_SESSION_TOKEN;
+        const credentials = accessKeyId && secretAccessKey ? { accessKeyId, secretAccessKey, sessionToken } : undefined;
+        return {
+            endpoint: process.env.OPENSEARCH_ENDPOINT,
+            region: process.env.OPENSEARCH_REGION || process.env.AWS_REGION,
+            credentials,
+        };
+    }
+    /**
+     * Execute a search query
+     */
+    async search(options) {
+        const { indices, query, _source, sort, size, from, searchAfter, highlight, aggs, collapse, minScore, userCredentials, } = options;
+        const indexString = Array.isArray(indices) ? indices.join(",") : indices;
+        const client = this.getClientForOperation(userCredentials);
+        return this.executeWithRetry(async () => {
+            try {
+                // When searchAfter is provided, use search_after pagination (faster for deep pages)
+                // Otherwise fall back to offset-based pagination with 'from'
+                const body = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ query }, (sort && { sort })), (size !== undefined && { size })), (searchAfter ? { search_after: searchAfter } : from !== undefined && { from })), (highlight && { highlight })), (_source !== undefined && { _source })), (aggs && { aggs })), (collapse && { collapse })), (minScore !== undefined && { min_score: minScore }));
+                const response = await client.search({
+                    index: indexString,
+                    body: body,
+                });
+                return response.body;
+            }
+            catch (error) {
+                this.logger.error("OpenSearch search failed", {
+                    indices: indexString,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw toSearchError(error);
+            }
+        });
+    }
+    /**
+     * Execute a multi-search query
+     */
+    async msearch(searches, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        return this.executeWithRetry(async () => {
+            try {
+                const body = searches.flatMap(({ index, body }) => [
+                    { index: Array.isArray(index) ? index.join(",") : index },
+                    body,
+                ]);
+                const response = await client.msearch({ body });
+                return response.body.responses;
+            }
+            catch (error) {
+                this.logger.error("OpenSearch msearch failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw toSearchError(error);
+            }
+        });
+    }
+    /**
+     * Check cluster health
+     */
+    async healthCheck(userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.cluster.health();
+            const body = response.body;
+            return {
+                status: body.status,
+                clusterName: body.cluster_name,
+                numberOfNodes: body.number_of_nodes,
+                activePrimaryShards: body.active_primary_shards,
+            };
+        }
+        catch (error) {
+            this.logger.error("OpenSearch health check failed", {
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            // Return generic error message to callers - detailed error is logged above
+            return {
+                status: "unavailable",
+                error: OPENSEARCH_ERROR_MESSAGES.CONNECTION_FAILED,
+            };
+        }
+    }
+    /**
+     * Check if the service is available
+     */
+    async isAvailable(userCredentials) {
+        const health = await this.healthCheck(userCredentials);
+        return health.status !== "unavailable";
+    }
+    /**
+     * Bulk index multiple documents in a single API call.
+     * Much more efficient than individual index calls for batch operations.
+     *
+     * @param indexName - The index to write to
+     * @param documents - Array of documents with id and body
+     * @param userCredentials - Optional user credentials for governance
+     * @returns Bulk operation result with success/error counts
+     */
+    async bulkIndex(indexName, documents, userCredentials) {
+        if (documents.length === 0) {
+            return { indexed: 0, errors: 0, errorIds: [] };
+        }
+        const client = this.getClientForOperation(userCredentials);
+        // Build bulk request body: alternating action and document lines
+        const body = [];
+        for (const doc of documents) {
+            body.push({ index: { _index: indexName, _id: doc.id } });
+            body.push(doc.body);
+        }
+        try {
+            const response = await client.bulk({
+                body,
+                refresh: false, // Don't refresh after each bulk - caller can refresh at end
+            });
+            const result = response.body;
+            let indexed = 0;
+            let errors = 0;
+            const errorIds = [];
+            for (const item of result.items) {
+                const indexResult = item.index;
+                if (!indexResult) {
+                    continue;
+                }
+                if (indexResult.error) {
+                    errors++;
+                    errorIds.push(indexResult._id);
+                    this.logger.warn("Bulk index item failed", {
+                        id: indexResult._id,
+                        error: indexResult.error.reason,
+                    });
+                }
+                else {
+                    indexed++;
+                }
+            }
+            this.logger.info("Bulk index completed", {
+                index: indexName,
+                total: documents.length,
+                indexed,
+                errors,
+            });
+            return { indexed, errors, errorIds };
+        }
+        catch (error) {
+            this.logger.error("Bulk index failed", {
+                index: indexName,
+                documentCount: documents.length,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get index information
+     */
+    async getIndices(pattern = OPENSEARCH_DEFAULT_CONFIG.DEFAULT_INDEX_PATTERN, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.cat.indices({
+                index: pattern,
+                format: "json",
+            });
+            return response.body.map((idx) => idx.index);
+        }
+        catch (error) {
+            this.logger.error("Failed to get indices", {
+                pattern,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get underlying client for advanced operations
+     */
+    getClient(userCredentials) {
+        return this.getClientForOperation(userCredentials);
+    }
+    /**
+     * List all indices with details
+     */
+    async listIndices(userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.cat.indices({
+                format: "json",
+            });
+            return response.body.map((idx) => ({
+                index: idx.index,
+                health: idx.health,
+                status: idx.status,
+                docsCount: idx["docs.count"] || OPENSEARCH_DEFAULT_CONFIG.DEFAULT_DOCS_COUNT,
+            }));
+        }
+        catch (error) {
+            this.logger.error("Failed to list indices", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Check if an index exists
+     * @throws SearchError if unable to check index existence (network error, auth error, etc.)
+     */
+    async indexExists(indexName, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.indices.exists({ index: indexName });
+            return response.body;
+        }
+        catch (error) {
+            this.logger.error("Failed to check index existence - throwing error, do not assume index does not exist", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Create an index with mappings and optional settings
+     */
+    async createIndex(indexName, mappings, userCredentials, settings) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            await client.indices.create({
+                index: indexName,
+                body: {
+                    mappings,
+                    settings: Object.assign({ number_of_shards: OPENSEARCH_DEFAULT_CONFIG.DEFAULT_NUMBER_OF_SHARDS, number_of_replicas: OPENSEARCH_DEFAULT_CONFIG.DEFAULT_NUMBER_OF_REPLICAS }, settings),
+                },
+            });
+            this.logger.info("Created index", { index: indexName });
+        }
+        catch (error) {
+            this.logger.error("Failed to create index", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Delete an index
+     * Only allows deletion of captify-managed search indices for safety
+     */
+    async deleteIndex(indexName, userCredentials) {
+        // Validate index name is a captify-managed index to prevent accidental deletion of other indices
+        if (!ALL_SEARCH_INDICES.includes(indexName)) {
+            throw new InvalidIndexDeletionError(indexName);
+        }
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            await client.indices.delete({ index: indexName });
+            this.logger.info("Deleted index", { index: indexName });
+        }
+        catch (error) {
+            this.logger.error("Failed to delete index", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    // ============================================================================
+    // Version and Migration Methods
+    // ============================================================================
+    /**
+     * Get index settings including custom metadata
+     */
+    async getIndexSettings(indexName, userCredentials) {
+        var _a, _b, _c;
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.indices.getSettings({ index: indexName });
+            const body = response.body;
+            return (_c = (_b = (_a = body[indexName]) === null || _a === void 0 ? void 0 : _a.settings) === null || _b === void 0 ? void 0 : _b.index) !== null && _c !== void 0 ? _c : null;
+        }
+        catch (error) {
+            // Return null if index doesn't exist
+            if ((error === null || error === void 0 ? void 0 : error.statusCode) === 404) {
+                return null;
+            }
+            this.logger.error("Failed to get index settings", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get index mappings including _meta
+     */
+    async getIndexMappings(indexName, userCredentials) {
+        var _a, _b;
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.indices.getMapping({ index: indexName });
+            const body = response.body;
+            return (_b = (_a = body[indexName]) === null || _a === void 0 ? void 0 : _a.mappings) !== null && _b !== void 0 ? _b : null;
+        }
+        catch (error) {
+            // Return null if index doesn't exist
+            if ((error === null || error === void 0 ? void 0 : error.statusCode) === 404) {
+                return null;
+            }
+            this.logger.error("Failed to get index mappings", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get the schema version of an index from its metadata
+     * Returns null if index doesn't exist or has no version (legacy index)
+     * Version is stored in mappings._meta.schema_version
+     */
+    async getIndexVersion(indexName, userCredentials) {
+        const mappings = await this.getIndexMappings(indexName, userCredentials);
+        if (!mappings) {
+            return null;
+        }
+        // Extract version from mappings._meta
+        const meta = mappings._meta;
+        const version = meta === null || meta === void 0 ? void 0 : meta[INDEX_METADATA_KEYS.SCHEMA_VERSION];
+        return typeof version === "string" ? version : null;
+    }
+    /**
+     * Create an index with mappings, settings, and version metadata
+     * Version metadata is stored in mappings._meta (OpenSearch standard for custom metadata)
+     */
+    async createIndexWithVersion(indexName, mappings, version, userCredentials, settings) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            // Store version metadata in mappings._meta (OpenSearch standard)
+            const mappingsWithMeta = Object.assign(Object.assign({}, mappings), { _meta: Object.assign(Object.assign({}, mappings._meta), { [INDEX_METADATA_KEYS.SCHEMA_VERSION]: version, [INDEX_METADATA_KEYS.CREATED_AT]: Date.now() }) });
+            await client.indices.create({
+                index: indexName,
+                body: {
+                    mappings: mappingsWithMeta,
+                    settings: Object.assign({ number_of_shards: OPENSEARCH_DEFAULT_CONFIG.DEFAULT_NUMBER_OF_SHARDS, number_of_replicas: OPENSEARCH_DEFAULT_CONFIG.DEFAULT_NUMBER_OF_REPLICAS }, settings),
+                },
+            });
+            this.logger.info("Created index with version", { index: indexName, version });
+        }
+        catch (error) {
+            this.logger.error("Failed to create index with version", {
+                index: indexName,
+                version,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Create all indices defined in INDEX_DEFINITIONS
+     * Skips indices that already exist, creates new ones with version metadata
+     */
+    async createAllIndices(userCredentials) {
+        this.logger.info("Creating all indices", { count: INDEX_DEFINITIONS.length });
+        // Create indices in parallel since they are independent
+        const results = await Promise.all(INDEX_DEFINITIONS.map(async (indexDef) => {
+            try {
+                const exists = await this.indexExists(indexDef.name, userCredentials);
+                if (exists) {
+                    return { name: indexDef.name, status: INDEX_STATUS.ALREADY_EXISTS };
+                }
+                await this.createIndexWithVersion(indexDef.name, indexDef.mappings, indexDef.version, userCredentials, indexDef.settings);
+                return {
+                    name: indexDef.name,
+                    status: INDEX_STATUS.CREATED,
+                    version: indexDef.version,
+                };
+            }
+            catch (error) {
+                this.logger.error("Failed to create index", {
+                    index: indexDef.name,
+                    error: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack : undefined,
+                });
+                return {
+                    name: indexDef.name,
+                    status: INDEX_STATUS.ERROR,
+                    error: OPENSEARCH_ERROR_MESSAGES.INDEX_CREATION_FAILED,
+                };
+            }
+        }));
+        const created = results.filter((r) => r.status === INDEX_STATUS.CREATED).length;
+        const skipped = results.filter((r) => r.status === INDEX_STATUS.ALREADY_EXISTS).length;
+        const failed = results.filter((r) => r.status === INDEX_STATUS.ERROR).length;
+        this.logger.info("Finished creating indices", { created, skipped, failed });
+        return { results };
+    }
+    /**
+     * Reindex documents from source to destination index
+     * Returns the task ID for async monitoring
+     */
+    async reindex(sourceIndex, destIndex, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.reindex({
+                wait_for_completion: false,
+                body: {
+                    source: { index: sourceIndex },
+                    dest: { index: destIndex },
+                },
+            });
+            const taskId = response.body.task;
+            this.logger.info("Started reindex operation", {
+                sourceIndex,
+                destIndex,
+                taskId,
+            });
+            return taskId;
+        }
+        catch (error) {
+            this.logger.error("Failed to start reindex", {
+                sourceIndex,
+                destIndex,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get reindex task status
+     */
+    async getTaskStatus(taskId, userCredentials) {
+        var _a, _b, _c, _d, _e, _f;
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.tasks.get({ task_id: taskId });
+            const body = response.body;
+            const status = (_a = body.task) === null || _a === void 0 ? void 0 : _a.status;
+            const processed = ((_b = status === null || status === void 0 ? void 0 : status.created) !== null && _b !== void 0 ? _b : 0) + ((_c = status === null || status === void 0 ? void 0 : status.updated) !== null && _c !== void 0 ? _c : 0) + ((_d = status === null || status === void 0 ? void 0 : status.deleted) !== null && _d !== void 0 ? _d : 0);
+            return {
+                completed: body.completed,
+                total: (_e = status === null || status === void 0 ? void 0 : status.total) !== null && _e !== void 0 ? _e : 0,
+                processed,
+                error: (_f = body.error) === null || _f === void 0 ? void 0 : _f.reason,
+            };
+        }
+        catch (error) {
+            this.logger.error("Failed to get task status", {
+                taskId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Update index aliases (for zero-downtime migration)
+     */
+    async updateAlias(aliasName, removeIndex, addIndex, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const actions = [];
+            if (removeIndex) {
+                actions.push({ remove: { index: removeIndex, alias: aliasName } });
+            }
+            actions.push({ add: { index: addIndex, alias: aliasName } });
+            await client.indices.updateAliases({
+                body: { actions },
+            });
+            this.logger.info("Updated alias", {
+                alias: aliasName,
+                removeIndex,
+                addIndex,
+            });
+        }
+        catch (error) {
+            this.logger.error("Failed to update alias", {
+                alias: aliasName,
+                removeIndex,
+                addIndex,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Get document count for an index
+     */
+    async getDocumentCount(indexName, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            const response = await client.count({ index: indexName });
+            return response.body.count;
+        }
+        catch (error) {
+            // Return 0 if index doesn't exist
+            if ((error === null || error === void 0 ? void 0 : error.statusCode) === 404) {
+                return 0;
+            }
+            this.logger.error("Failed to get document count", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Update documents matching a query using OpenSearch's update_by_query API.
+     * Useful for cascading updates to denormalized data (e.g., session titles in messages).
+     *
+     * @param indexName The index to update documents in
+     * @param query OpenSearch query DSL to match documents
+     * @param script Painless script to apply updates
+     * @param userCredentials Optional user credentials for governance compliance
+     * @returns Number of documents updated
+     * @throws SearchError if the operation fails
+     *
+     * @example
+     * ```typescript
+     * // Update sessionTitle for all messages in a session
+     * const updated = await opensearch.updateByQuery(
+     *   'captify-search-messages',
+     *   { term: { sessionId: 'session-123' } },
+     *   { source: 'ctx._source.sessionTitle = params.title', params: { title: 'New Title' } },
+     *   userCredentials
+     * );
+     * ```
+     */
+    async updateByQuery(indexName, query, script, userCredentials) {
+        const client = this.getClientForOperation(userCredentials);
+        return this.executeWithRetry(async () => {
+            var _a, _b;
+            try {
+                const response = await client.updateByQuery({
+                    index: indexName,
+                    refresh: true,
+                    body: {
+                        query,
+                        script: {
+                            source: script.source,
+                            lang: "painless",
+                            params: script.params,
+                        },
+                    },
+                });
+                const body = response.body;
+                const updated = (_a = body.updated) !== null && _a !== void 0 ? _a : 0;
+                this.logger.info("Updated documents by query", {
+                    index: indexName,
+                    updated,
+                    total: (_b = body.total) !== null && _b !== void 0 ? _b : 0,
+                });
+                return updated;
+            }
+            catch (error) {
+                this.logger.error("Failed to update documents by query", {
+                    index: indexName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw toSearchError(error);
+            }
+        });
+    }
+    /**
+     * Delete an index by name (internal use, bypasses safety check for migration temp indices)
+     */
+    async deleteIndexUnsafe(indexName, userCredentials) {
+        // Only allow deletion of captify-managed indices or temp migration indices
+        const isCaptifyIndex = ALL_SEARCH_INDICES.includes(indexName);
+        const isTempMigrationIndex = indexName.endsWith(MIGRATION_CONFIG.TEMP_INDEX_SUFFIX);
+        if (!isCaptifyIndex && !isTempMigrationIndex) {
+            throw new InvalidIndexDeletionError(indexName);
+        }
+        const client = this.getClientForOperation(userCredentials);
+        try {
+            await client.indices.delete({ index: indexName });
+            this.logger.info("Deleted index (unsafe)", { index: indexName });
+        }
+        catch (error) {
+            this.logger.error("Failed to delete index (unsafe)", {
+                index: indexName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw toSearchError(error);
+        }
+    }
+    /**
+     * Close the service and all cached user clients
+     */
+    async close() {
+        // Stop the cleanup interval
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Close all cached user clients
+        for (const { client } of this.userClients.values()) {
+            await client.close().catch((error) => {
+                this.logger.debug("Failed to close client during shutdown", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
+        this.userClients.clear();
+        // Close the service account client
+        await this.client.close();
+    }
+}
+//# sourceMappingURL=opensearch.service.js.map