@venizia/ignis 0.0.10-4 → 0.1.0

package/dist/connectors/typesense/{driver.js → connector.js}

@@ -1,71 +1,141 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypesenseDriver = exports.BaseSearchDriver = void 0;
+exports.TypesenseConnector = void 0;
+const common_1 = require("../../common");
+const search_1 = require("../../connectors/search");
+const internal_1 = require("../../connectors/search/internal");
 const ignis_helpers_1 = require("@venizia/ignis-helpers");
 const typesense_1 = require("typesense");
-const driver_internal_1 = require("./internal/driver-internal");
-const search_driver_internal_1 = require("./internal/search-driver-internal");
+const connector_internal_1 = require("./internal/connector-internal");
 const types_1 = require("./types");
-/** Shared base every concrete search driver (e.g. TypesenseDriver) extends. */
-class BaseSearchDriver extends ignis_helpers_1.BaseHelper {
-    constructor(opts) {
-        super(opts);
-    }
-    async ping() {
-        const health = await this.getHealth();
-        return health.ok;
-    }
-    assertNonEmpty(opts) {
-        const { value, name, method } = opts;
-        if (!value || value.trim().length === 0) {
-            throw (0, ignis_helpers_1.getError)({ message: `[${method}] Missing or empty value | name: ${name}` });
-        }
-    }
-    // Runs the engine verb; routes tolerated errors (benign 404/409) to the caller-provided branch,
-    // wraps everything else as a sanitized 503. `tolerate.handle` may return a fallback or throw.
-    async runEngineCall(opts) {
-        const { method, run, tolerate } = opts;
-        try {
-            const rs = await run();
-            return rs;
-        }
-        catch (error) {
-            if (tolerate?.when(error)) {
-                const rs = await tolerate.handle(error);
-                return rs;
-            }
-            search_driver_internal_1.SearchDriverInternal.wrapDependencyError({ method, error, logger: this.logger });
-        }
-    }
-}
-exports.BaseSearchDriver = BaseSearchDriver;
 // Narrow runtime readers for the `unknown` payloads ITypesenseClientLike hands back - each is the
 // single narrowest cast for its field, isolated here instead of repeated ad hoc at every call site.
-function isRecord(value) {
+const isRecord = (value) => {
     return typeof value === 'object' && value !== null;
-}
-function readBooleanFlag(opts) {
+};
+const readBooleanFlag = (opts) => {
     const { value, key } = opts;
     return isRecord(value) ? Boolean(value[key]) : false;
-}
-function readNumberField(opts) {
+};
+const readNumberField = (opts) => {
     const { value, key } = opts;
     if (!isRecord(value) || typeof value[key] !== 'number') {
         return 0;
     }
     return value[key];
-}
-// eslint-disable-next-line @typescript-eslint/naming-convention
-function isAliasResponse(value) {
-    return (isRecord(value) && typeof value.name === 'string' && typeof value.collection_name === 'string');
-}
-/** Typesense engine driver - built/injected by TypesenseDataSource, which exposes the raw client via getClient(). */
-class TypesenseDriver extends BaseSearchDriver {
+};
+const readStringField = (opts) => {
+    const { value, key } = opts;
+    if (!isRecord(value) || typeof value[key] !== 'string') {
+        return undefined;
+    }
+    return value[key];
+};
+/** Maps a raw Typesense search hit (snake_case `text_match`) onto the camelCase `ISearchResult` hit shape; read via bracket string access so no snake_case identifier is declared here. */
+const mapSearchHit = (hit) => {
+    if (!isRecord(hit)) {
+        return { document: {} };
+    }
+    const mapped = {
+        document: hit['document'],
+    };
+    if (hit['highlight'] !== undefined) {
+        mapped.highlight = hit['highlight'];
+    }
+    if (Array.isArray(hit['highlights'])) {
+        mapped.highlights = hit['highlights'];
+    }
+    if (typeof hit['text_match'] === 'number') {
+        mapped.score = hit['text_match'];
+    }
+    return mapped;
+};
+/** Maps a raw Typesense search response onto the camelCase `ISearchResult` - snake_case wire fields
+ * (`out_of`/`search_time_ms`/`facet_counts`/`grouped_hits`) are read only via bracket string access,
+ * never as identifiers. Absent fields are omitted rather than mapped as `undefined`. */
+const mapSearchResult = (raw) => {
+    if (!isRecord(raw)) {
+        return { found: 0, isFoundExact: true };
+    }
+    // Typesense's `found` is an exhaustive count, so it is never an estimate.
+    const result = {
+        found: readNumberField({ value: raw, key: 'found' }),
+        isFoundExact: true,
+    };
+    if (typeof raw['out_of'] === 'number') {
+        result.outOf = raw['out_of'];
+    }
+    if (typeof raw['search_time_ms'] === 'number') {
+        result.searchTimeMs = raw['search_time_ms'];
+    }
+    if (Array.isArray(raw['facet_counts'])) {
+        result.facetCounts = raw['facet_counts'];
+    }
+    if (Array.isArray(raw['grouped_hits'])) {
+        result.groupedHits = raw['grouped_hits'];
+    }
+    if (Array.isArray(raw['hits'])) {
+        result.hits = raw['hits'].map(hit => mapSearchHit(hit));
+    }
+    return result;
+};
+/** Empty TSearchResponse shape returned when search() tolerates a missing collection; built via bracket assignment so no snake_case identifier is declared here. */
+const buildEmptySearchResponse = () => {
+    const response = { found: 0, page: 1, hits: [] };
+    response['out_of'] = 0;
+    response['search_time_ms'] = 0;
+    response['request_params'] = {};
+    return response;
+};
+// Typesense's wire shape for a synonym set; `root` is only present for one-way synonyms.
+const isSynonymResponse = (value) => {
+    return isRecord(value) && typeof value.id === 'string' && Array.isArray(value.synonyms);
+};
+const toSynonym = (value) => {
+    const { id, synonyms, root } = value;
+    // Multi-way sets come back with root: "" - treat empty/absent alike so only one-way keeps a root.
+    return root ? { id, synonyms, root } : { id, synonyms };
+};
+/** Typesense engine connector - built/injected by TypesenseDataSource, which exposes the raw client via getClient(). */
+class TypesenseConnector extends search_1.BaseSearchConnector {
     constructor(opts) {
         super({
-            scope: opts.scope ?? TypesenseDriver.name,
+            scope: opts.scope ?? TypesenseConnector.name,
             identifier: opts.identifier ?? opts.name,
         });
+        this.collection = {
+            create: opts => this.createCollection(opts),
+            ensure: opts => this.ensureCollection(opts),
+            get: opts => this.getCollection(opts),
+            list: () => this.listCollections(),
+            exists: opts => this.collectionExists(opts),
+            patchSchema: opts => this.patchCollectionSchema(opts),
+            delete: opts => this.deleteCollection(opts),
+        };
+        this.alias = {
+            upsert: opts => this.upsertAlias(opts),
+            get: opts => this.getAlias(opts),
+        };
+        this.synonymSet = {
+            upsert: opts => this.upsertSynonymSet(opts),
+            get: opts => this.getSynonymSet(opts),
+            list: () => this.listSynonymSets(),
+            delete: opts => this.deleteSynonymSet(opts),
+            link: opts => this.linkSynonymSets(opts),
+        };
+        this.document = {
+            create: (opts) => this.createDocument(opts),
+            get: (opts) => this.getDocument(opts),
+            count: opts => this.countDocuments(opts),
+            upsert: (opts) => this.upsertDocument(opts),
+            update: (opts) => this.updateDocument(opts),
+            delete: opts => this.deleteDocument(opts),
+            import: (opts) => this.importDocuments(opts),
+            updateBy: (opts) => this.updateByFilter(opts),
+            deleteBy: opts => this.deleteByFilter(opts),
+            deleteAll: opts => this.deleteAllDocuments(opts),
+            export: opts => this.exportDocuments(opts),
+        };
         try {
             this.client =
                 opts.client ??
@@ -81,17 +151,17 @@ class TypesenseDriver extends BaseSearchDriver {
         catch (error) {
             this.logger
                 .for('constructor')
-                .error('Failed to initialize Typesense client | error: %j', search_driver_internal_1.SearchDriverInternal.describeError({ error }));
+                .error('Failed to initialize Typesense client | error: %s', internal_1.SearchConnectorInternal.describeError({ error }));
             opts.onError?.({ name: opts.name, error });
             throw error;
         }
     }
-    // -------------------------------------------------------------------------------------------
-    // Lifecycle
-    // -------------------------------------------------------------------------------------------
     getClient() {
         return this.client;
     }
+    isNotFoundError(opts) {
+        return connector_internal_1.TypesenseInternal.isNotFoundError(opts);
+    }
     async getHealth() {
         try {
             const health = await this.client.health.retrieve();
@@ -100,26 +170,22 @@ class TypesenseDriver extends BaseSearchDriver {
         catch (error) {
             this.logger
                 .for(this.getHealth.name)
-                .warn('Health probe failed | error: %j', search_driver_internal_1.SearchDriverInternal.describeError({ error }));
+                .warn('Health probe failed | error: %s', internal_1.SearchConnectorInternal.describeError({ error }));
             return { ok: false };
         }
     }
-    // -------------------------------------------------------------------------------------------
-    // Collections
-    // -------------------------------------------------------------------------------------------
     async createCollection(opts) {
         const { schema } = opts;
         const logger = this.logger.for(this.createCollection.name);
         const rs = await this.runEngineCall({
             method: this.createCollection.name,
             run: async () => {
-                // ITypesenseCollectionsApi.create() is `unknown` by contract (see interface above); the engine echoes back the created schema.
                 const created = (await this.client.collections().create(schema));
                 logger.info('Created collection | name: %s', schema.name);
                 return created;
             },
             tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isAlreadyExistsError({ error }),
+                when: error => connector_internal_1.TypesenseInternal.isAlreadyExistsError({ error }),
                 handle: () => {
                     logger.info('Collection already exists, skipping | name: %s', schema.name);
                 },
@@ -135,7 +201,7 @@ class TypesenseDriver extends BaseSearchDriver {
         }
         // The create response IS the collection schema. Reading it back immediately instead is a
         // read-after-write race on multi-node clusters (follower may 404 before the raft log catches
-        // up) - found live on a real 3-node cluster. Only the tolerated already-exists path re-reads.
+        // up). Only the tolerated already-exists path re-reads.
         const created = await this.createCollection({ schema });
         if (created) {
             return created;
@@ -145,24 +211,16 @@ class TypesenseDriver extends BaseSearchDriver {
     async getCollection(opts) {
         const { name } = opts;
         this.assertNonEmpty({ value: name, name: 'collection', method: this.getCollection.name });
-        const logger = this.logger.for(this.getCollection.name);
         const rs = await this.runEngineCall({
             method: this.getCollection.name,
             run: async () => {
-                // Client-facade retrieve() is `unknown` by contract; engine guarantees a collection schema shape.
                 const collection = (await this.client.collections(name).retrieve());
                 return collection;
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Collection not found | name: %s', name);
-                    search_driver_internal_1.SearchDriverInternal.throwNotFoundError({
-                        method: this.getCollection.name,
-                        subject: `Collection '${name}'`,
-                    });
-                },
-            },
+            tolerate: this.notFoundTolerance({
+                method: this.getCollection.name,
+                subject: `Collection '${name}'`,
+            }),
         });
         return rs;
     }
@@ -170,7 +228,6 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.listCollections.name,
             run: async () => {
-                // Client-facade retrieve() is `unknown` by contract; engine guarantees an array of collection schemas.
                 const collections = (await this.client.collections().retrieve());
                 return collections;
             },
@@ -189,7 +246,7 @@ class TypesenseDriver extends BaseSearchDriver {
         catch (error) {
             this.logger
                 .for(this.collectionExists.name)
-                .warn('Existence check failed, treating as absent | name: %s | error: %j', name, search_driver_internal_1.SearchDriverInternal.describeError({ error }));
+                .warn('Existence check failed, treating as absent | name: %s | error: %s', name, internal_1.SearchConnectorInternal.describeError({ error }));
             return false;
         }
     }
@@ -207,16 +264,10 @@ class TypesenseDriver extends BaseSearchDriver {
                 await this.client.collections(name).update({ fields });
                 logger.info('Patched schema | name: %s | fields: %d', name, fields.length);
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Collection not found | name: %s', name);
-                    search_driver_internal_1.SearchDriverInternal.throwNotFoundError({
-                        method: this.patchCollectionSchema.name,
-                        subject: `Collection '${name}'`,
-                    });
-                },
-            },
+            tolerate: this.notFoundTolerance({
+                method: this.patchCollectionSchema.name,
+                subject: `Collection '${name}'`,
+            }),
         });
     }
     async deleteCollection(opts) {
@@ -230,19 +281,15 @@ class TypesenseDriver extends BaseSearchDriver {
                 logger.info('Deleted collection | name: %s', name);
                 return true;
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Collection not found, treating as already deleted | name: %s', name);
-                    return false;
-                },
-            },
+            tolerate: this.notFoundFallback({
+                method: this.deleteCollection.name,
+                message: 'Collection not found, treating as already deleted | name: %s',
+                args: [name],
+                fallback: false,
+            }),
         });
         return rs;
     }
-    // -------------------------------------------------------------------------------------------
-    // Aliases (primitives only)
-    // -------------------------------------------------------------------------------------------
     async upsertAlias(opts) {
         const { name, collection } = opts;
         this.assertNonEmpty({ value: name, name: 'alias', method: this.upsertAlias.name });
@@ -251,8 +298,9 @@ class TypesenseDriver extends BaseSearchDriver {
         await this.runEngineCall({
             method: this.upsertAlias.name,
             run: async () => {
-                // eslint-disable-next-line @typescript-eslint/naming-convention
-                await this.client.aliases().upsert(name, { collection_name: collection });
+                const mapping = {};
+                mapping['collection_name'] = collection;
+                await this.client.aliases().upsert(name, mapping);
                 logger.info('Upserted alias | %s -> %s', name, collection);
             },
         });
@@ -260,32 +308,121 @@ class TypesenseDriver extends BaseSearchDriver {
     async getAlias(opts) {
         const { name } = opts;
         this.assertNonEmpty({ value: name, name: 'alias', method: this.getAlias.name });
-        const logger = this.logger.for(this.getAlias.name);
         const rs = await this.runEngineCall({
             method: this.getAlias.name,
             run: async () => {
                 const alias = await this.client.aliases(name).retrieve();
-                if (!isAliasResponse(alias)) {
-                    search_driver_internal_1.SearchDriverInternal.throwNotFoundError({
+                const aliasName = readStringField({ value: alias, key: 'name' });
+                const collectionName = readStringField({ value: alias, key: 'collection_name' });
+                if (aliasName === undefined || collectionName === undefined) {
+                    internal_1.SearchConnectorInternal.throwNotFoundError({
                         method: this.getAlias.name,
                         subject: `Alias '${name}'`,
                     });
                 }
-                return { name: alias.name, collection: alias.collection_name };
+                return { name: aliasName, collection: collectionName };
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Alias not found | name: %s', name);
-                    return null;
-                },
+            tolerate: this.notFoundFallback({
+                method: this.getAlias.name,
+                message: 'Alias not found | name: %s',
+                args: [name],
+                fallback: null,
+            }),
+        });
+        return rs;
+    }
+    async upsertSynonymSet(opts) {
+        const { name, items } = opts;
+        this.assertNonEmpty({
+            value: name,
+            name: 'synonym set name',
+            method: this.upsertSynonymSet.name,
+        });
+        const logger = this.logger.for(this.upsertSynonymSet.name);
+        await this.runEngineCall({
+            method: this.upsertSynonymSet.name,
+            run: async () => {
+                const payload = items.map(item => item.root
+                    ? { id: item.id, synonyms: item.synonyms, root: item.root }
+                    : { id: item.id, synonyms: item.synonyms });
+                await this.client.synonymSets(name).upsert({ items: payload });
+                logger.info('Upserted synonym set | name: %s | items: %s', name, items.length);
+            },
+        });
+    }
+    async getSynonymSet(opts) {
+        const { name } = opts;
+        this.assertNonEmpty({ value: name, name: 'synonym set name', method: this.getSynonymSet.name });
+        const rs = await this.runEngineCall({
+            method: this.getSynonymSet.name,
+            run: async () => {
+                const result = await this.client.synonymSets(name).retrieve();
+                const items = isRecord(result) && Array.isArray(result.items) ? result.items : [];
+                return items.filter(isSynonymResponse).map(toSynonym);
             },
+            tolerate: this.notFoundFallback({
+                method: this.getSynonymSet.name,
+                message: 'Synonym set not found | name: %s',
+                args: [name],
+                fallback: null,
+            }),
         });
         return rs;
     }
-    // -------------------------------------------------------------------------------------------
-    // Documents
-    // -------------------------------------------------------------------------------------------
+    async listSynonymSets() {
+        const rs = await this.runEngineCall({
+            method: this.listSynonymSets.name,
+            run: async () => {
+                const result = await this.client.synonymSets().retrieve();
+                const sets = Array.isArray(result) ? result : [];
+                return sets
+                    .filter(isRecord)
+                    .map(set => set.name)
+                    .filter((setName) => typeof setName === 'string');
+            },
+        });
+        return rs;
+    }
+    async deleteSynonymSet(opts) {
+        const { name } = opts;
+        this.assertNonEmpty({
+            value: name,
+            name: 'synonym set name',
+            method: this.deleteSynonymSet.name,
+        });
+        const logger = this.logger.for(this.deleteSynonymSet.name);
+        const rs = await this.runEngineCall({
+            method: this.deleteSynonymSet.name,
+            run: async () => {
+                await this.client.synonymSets(name).delete();
+                logger.info('Deleted synonym set | name: %s', name);
+                return true;
+            },
+            tolerate: this.notFoundFallback({
+                method: this.deleteSynonymSet.name,
+                message: 'Synonym set not found, treating as already deleted | name: %s',
+                args: [name],
+                fallback: false,
+            }),
+        });
+        return rs;
+    }
+    async linkSynonymSets(opts) {
+        const { collection, synonymSets } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.linkSynonymSets.name,
+        });
+        const logger = this.logger.for(this.linkSynonymSets.name);
+        await this.runEngineCall({
+            method: this.linkSynonymSets.name,
+            run: async () => {
+                await this.client.collections(collection).update({ ['synonym_sets']: synonymSets });
+                logger.info('Linked synonym set(s) | collection: %s | sets: %j', collection, synonymSets);
+            },
+        });
+    }
     async createDocument(opts) {
         const { collection, document } = opts;
         this.assertNonEmpty({
@@ -293,16 +430,28 @@ class TypesenseDriver extends BaseSearchDriver {
             name: 'collection',
             method: this.createDocument.name,
         });
+        const id = document['id'];
         const rs = await this.runEngineCall({
             method: this.createDocument.name,
             run: async () => {
-                // Facade create() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
                 const created = (await this.client
                     .collections(collection)
                     .documents()
                     .create(document));
                 return created;
             },
+            // Typesense rejects a duplicate id with 409; surface the neutral already_exists conflict
+            // instead of the generic sanitized 503 - same contract Meilisearch's createDocument throws.
+            tolerate: {
+                when: error => connector_internal_1.TypesenseInternal.isAlreadyExistsError({ error }),
+                handle: () => {
+                    throw (0, ignis_helpers_1.getError)({
+                        statusCode: ignis_helpers_1.HTTP.ResultCodes.RS_4.Conflict,
+                        messageCode: common_1.SearchErrorCodes.ALREADY_EXISTS,
+                        message: `[${this.createDocument.name}] Document '${String(id)}' already exists in collection '${collection}'.`,
+                    });
+                },
+            },
         });
         return rs;
     }
@@ -310,27 +459,35 @@ class TypesenseDriver extends BaseSearchDriver {
         const { collection, id } = opts;
         this.assertNonEmpty({ value: collection, name: 'collection', method: this.getDocument.name });
         this.assertNonEmpty({ value: id, name: 'document id', method: this.getDocument.name });
-        const logger = this.logger.for(this.getDocument.name);
         const rs = await this.runEngineCall({
             method: this.getDocument.name,
             run: async () => {
-                // Facade retrieve() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
                 const document = (await this.client.collections(collection).documents(id).retrieve());
                 return document;
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Document not found | collection: %s | id: %s', collection, id);
-                    search_driver_internal_1.SearchDriverInternal.throwNotFoundError({
-                        method: this.getDocument.name,
-                        subject: `Document '${id}' in collection '${collection}'`,
-                    });
-                },
-            },
+            tolerate: this.notFoundTolerance({
+                method: this.getDocument.name,
+                subject: `Document '${id}' in collection '${collection}'`,
+            }),
         });
         return rs;
     }
+    /** Typesense's `found` is exhaustive, so a `per_page: 0` search is already an exact count - no separate endpoint needed. */
+    async countDocuments(opts) {
+        const { collection, filterBy } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.countDocuments.name,
+        });
+        const params = { q: '*' };
+        params['per_page'] = 0;
+        if (filterBy) {
+            params['filter_by'] = filterBy;
+        }
+        const result = await this.search({ collection, params });
+        return result.found;
+    }
     async upsertDocument(opts) {
         const { collection, document } = opts;
         this.assertNonEmpty({
@@ -341,7 +498,6 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.upsertDocument.name,
             run: async () => {
-                // Facade upsert() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
                 const upserted = (await this.client
                     .collections(collection)
                     .documents()
@@ -359,27 +515,19 @@ class TypesenseDriver extends BaseSearchDriver {
             method: this.updateDocument.name,
         });
         this.assertNonEmpty({ value: id, name: 'document id', method: this.updateDocument.name });
-        const logger = this.logger.for(this.updateDocument.name);
         const rs = await this.runEngineCall({
             method: this.updateDocument.name,
             run: async () => {
-                // Facade update() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
                 const updated = (await this.client
                     .collections(collection)
                     .documents(id)
                     .update(document));
                 return updated;
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Document not found | collection: %s | id: %s', collection, id);
-                    search_driver_internal_1.SearchDriverInternal.throwNotFoundError({
-                        method: this.updateDocument.name,
-                        subject: `Document '${id}' in collection '${collection}'`,
-                    });
-                },
-            },
+            tolerate: this.notFoundTolerance({
+                method: this.updateDocument.name,
+                subject: `Document '${id}' in collection '${collection}'`,
+            }),
         });
         return rs;
     }
@@ -391,20 +539,18 @@ class TypesenseDriver extends BaseSearchDriver {
             method: this.deleteDocument.name,
         });
         this.assertNonEmpty({ value: id, name: 'document id', method: this.deleteDocument.name });
-        const logger = this.logger.for(this.deleteDocument.name);
         const rs = await this.runEngineCall({
             method: this.deleteDocument.name,
             run: async () => {
                 await this.client.collections(collection).documents(id).delete();
                 return true;
             },
-            tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
-                handle: () => {
-                    logger.debug('Document not found, returning false | collection: %s | id: %s', collection, id);
-                    return false;
-                },
-            },
+            tolerate: this.notFoundFallback({
+                method: this.deleteDocument.name,
+                message: 'Document not found, returning false | collection: %s | id: %s',
+                args: [collection, id],
+                fallback: false,
+            }),
         });
         return rs;
     }
@@ -435,12 +581,11 @@ class TypesenseDriver extends BaseSearchDriver {
         try {
             for (let start = 0; start < documents.length; start += batchSize) {
                 const batch = documents.slice(start, start + batchSize);
-                // typesense defaults to throwOnFail:true (throws on any failed row); opt out so import() returns per-row responses to aggregate below.
+                // opt out of typesense's default throwOnFail:true so import() returns per-row responses to aggregate below.
                 const importParams = { action, throwOnFail: false };
                 if (dirtyValues) {
-                    importParams.dirty_values = dirtyValues;
+                    importParams['dirty_values'] = dirtyValues;
                 }
-                // Facade import() is `unknown` by contract; engine guarantees one ImportResponse row per submitted document.
                 const batchResult = (await this.client
                     .collections(collection)
                     .documents()
@@ -457,8 +602,13 @@ class TypesenseDriver extends BaseSearchDriver {
             }
         }
         catch (error) {
+            // A framework ApplicationError (already sanitized, carrying its own statusCode/messageCode) must
+            // surface as-is; only raw engine failures get wrapped as a 503. Mirrors runEngineCall's guard.
+            if ((0, ignis_helpers_1.isApplicationError)(error)) {
+                throw error;
+            }
             // Batches before the failure are already persisted server-side; attach partial progress so callers can decide to resume or retry.
-            search_driver_internal_1.SearchDriverInternal.wrapDependencyError({
+            internal_1.SearchConnectorInternal.wrapDependencyError({
                 method: this.importDocuments.name,
                 error,
                 logger: this.logger,
@@ -471,7 +621,7 @@ class TypesenseDriver extends BaseSearchDriver {
             });
         }
         logger.info('Imported documents | collection: %s | ok: %d | fail: %d', collection, successCount, failCount);
-        return { successCount, failCount, responses };
+        return { count: { success: successCount, fail: failCount }, responses };
     }
     async updateByFilter(opts) {
         const { collection, document, filterBy } = opts;
@@ -484,11 +634,12 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.updateByFilter.name,
             run: async () => {
+                const updateOptions = {};
+                updateOptions['filter_by'] = filterBy;
                 const result = await this.client
                     .collections(collection)
                     .documents()
-                    // eslint-disable-next-line @typescript-eslint/naming-convention
-                    .update(document, { filter_by: filterBy });
+                    .update(document, updateOptions);
                 return { updatedCount: readNumberField({ value: result, key: 'num_updated' }) };
             },
         });
@@ -505,14 +656,13 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.deleteByFilter.name,
             run: async () => {
-                /* eslint-disable @typescript-eslint/naming-convention */
-                const deleteParams = { filter_by: filterBy };
-                /* eslint-enable @typescript-eslint/naming-convention */
+                const deleteParams = {};
+                deleteParams['filter_by'] = filterBy;
                 if (batchSize && batchSize > 0) {
-                    deleteParams.batch_size = batchSize;
+                    deleteParams['batch_size'] = batchSize;
                 }
                 if (ignoreNotFound !== undefined) {
-                    deleteParams.ignore_not_found = ignoreNotFound;
+                    deleteParams['ignore_not_found'] = ignoreNotFound;
                 }
                 const result = await this.client.collections(collection).documents().delete(deleteParams);
                 return readNumberField({ value: result, key: 'num_deleted' });
@@ -552,15 +702,13 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.exportDocuments.name,
             run: async () => {
-                // eslint-disable-next-line @typescript-eslint/naming-convention
                 const exportParams = {};
                 if (filterBy) {
-                    exportParams.filter_by = filterBy;
+                    exportParams['filter_by'] = filterBy;
                 }
                 if (includeFields && includeFields.length > 0) {
-                    exportParams.include_fields = includeFields.join(',');
+                    exportParams['include_fields'] = includeFields.join(',');
                 }
-                // Facade export() is `unknown` by contract; engine guarantees a JSONL string when no readable-stream option is passed.
                 const exported = (await this.client
                     .collections(collection)
                     .documents()
@@ -570,9 +718,6 @@ class TypesenseDriver extends BaseSearchDriver {
         });
         return rs;
     }
-    // -------------------------------------------------------------------------------------------
-    // Search (raw passthrough)
-    // -------------------------------------------------------------------------------------------
     async search(opts) {
         const { collection, params, options } = opts;
         this.assertNonEmpty({ value: collection, name: 'collection', method: this.search.name });
@@ -580,7 +725,6 @@ class TypesenseDriver extends BaseSearchDriver {
         const rs = await this.runEngineCall({
             method: this.search.name,
             run: async () => {
-                // Facade search() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
                 const result = (await this.client
                     .collections(collection)
                     .documents()
@@ -588,37 +732,27 @@ class TypesenseDriver extends BaseSearchDriver {
                 return result;
             },
             tolerate: {
-                when: error => driver_internal_1.TypesenseInternal.isNotFoundError({ error }),
+                when: error => connector_internal_1.TypesenseInternal.isNotFoundError({ error }),
                 handle: () => {
                     logger.warn('Search on missing collection, returning empty | name: %s', collection);
                     // Missing collection -> empty result (not a 500); shape fully so consumers don't see undefined fields.
-                    /* eslint-disable @typescript-eslint/naming-convention */
-                    return {
-                        found: 0,
-                        out_of: 0,
-                        page: 1,
-                        search_time_ms: 0,
-                        request_params: {},
-                        hits: [],
-                    };
-                    /* eslint-enable @typescript-eslint/naming-convention */
+                    return buildEmptySearchResponse();
                 },
             },
         });
-        return rs;
+        return mapSearchResult(rs);
     }
     async multiSearch(opts) {
-        const { searches, commonParams, options } = opts;
+        const { searches, union: isUnion, commonParams, options } = opts;
         const rs = await this.runEngineCall({
             method: this.multiSearch.name,
             run: async () => {
-                const result = await this.client.multiSearch.perform({ searches }, commonParams ?? {}, options);
-                // Facade perform() is `unknown` by contract; caller-supplied T can't be runtime-validated generically.
+                const result = await this.client.multiSearch.perform(isUnion ? { union: true, searches } : { searches }, commonParams ?? {}, options);
                 return result;
             },
         });
         return rs;
     }
 }
-exports.TypesenseDriver = TypesenseDriver;
-//# sourceMappingURL=driver.js.map
+exports.TypesenseConnector = TypesenseConnector;
+//# sourceMappingURL=connector.js.map