/** * Tenant-scoped search query helpers. * * These functions are the only sanctioned read/write surface — domain * code that imports `@toolctrl/search` reaches Meilisearch through them * and nothing else. Every call requires an explicit tenantId; the * wrapper translates that into the Meilisearch filter expression * `tenantId = ""` and AND-merges it with any caller-supplied * filters. Special characters in the tenantId are escaped to prevent * filter injection. */ import type { IndexSearchOptions, SearchClient, SearchDocument, SearchHits } from "./client.js"; import { sanitizeDocument } from "./sanitize.js"; import type { SearchIndexSchema } from "./schemas/index.js"; const ORIGINAL_PRIMARY_KEY_FIELD = "__toolctrlOriginalPrimaryKey"; export class TenantScopeError extends Error { override readonly name = "TenantScopeError"; readonly code: "MISSING_TENANT" | "INVALID_TENANT"; constructor(message: string, code: TenantScopeError["code"] = "MISSING_TENANT") { super(message); this.code = code; } } export interface SearchInIndexInput { readonly client: SearchClient; readonly schema: SearchIndexSchema; readonly tenantId: string; readonly query: string; readonly options?: Omit & { extraFilters?: string | readonly string[] }; } export async function searchInIndex( input: SearchInIndexInput ): Promise> { assertTenantId(input.tenantId); const handle = input.client.index(input.schema.name); const filter = buildFilter(input.tenantId, input.options?.extraFilters); const attributesToRetrieve = input.options?.attributesToRetrieve; const opts: IndexSearchOptions = { ...(input.options ?? {}), filter, ...(attributesToRetrieve && !attributesToRetrieve.includes("*") ? { attributesToRetrieve: unique([...attributesToRetrieve, input.schema.primaryKey, ORIGINAL_PRIMARY_KEY_FIELD]) } : {}), }; // strip our internal extraFilters key (it isn't part of IndexSearchOptions on the client) delete (opts as { extraFilters?: unknown }).extraFilters; const result = await handle.search(input.query ?? "", opts); return { ...result, hits: result.hits.map((hit) => ({ ...hit, document: restoreDocumentPrimaryKey(input.schema, hit.document), })), }; } export interface BulkIndexInput { readonly client: SearchClient; readonly schema: SearchIndexSchema; readonly tenantId: string; readonly documents: readonly TDocument[]; } export async function bulkIndex( input: BulkIndexInput ): Promise { assertTenantId(input.tenantId); if (input.documents.length === 0) return; const sanitized = input.documents.map((doc) => { if ("tenantId" in doc && doc.tenantId !== input.tenantId) { throw new TenantScopeError( `bulkIndex received a document whose tenantId differs from the call-site tenantId.`, "INVALID_TENANT" ); } const projected = sanitizeDocument(input.schema, { ...doc, tenantId: input.tenantId }); if (projected.tenantId !== input.tenantId) { throw new TenantScopeError( `bulkIndex received a document whose tenantId differs from the call-site tenantId.`, "INVALID_TENANT" ); } return scopeDocumentPrimaryKey(input.schema, input.tenantId, projected); }); const handle = input.client.index(input.schema.name); await handle.upsert(sanitized as readonly TDocument[]); } export interface DeleteFromIndexInput { readonly client: SearchClient; readonly schema: SearchIndexSchema; readonly tenantId: string; readonly documentIds: readonly (string | number)[]; } export async function deleteFromIndex(input: DeleteFromIndexInput): Promise { assertTenantId(input.tenantId); if (input.documentIds.length === 0) return; const handle = input.client.index(input.schema.name); await handle.delete(input.documentIds.map((documentId) => buildScopedPrimaryKey(input.tenantId, documentId))); } export interface SearchFallback { (input: { query: string; tenantId: string }): Promise>; } export interface SearchWithFallbackInput extends SearchInIndexInput { readonly fallback: SearchFallback; /** Optional hook fired when the fallback path engages — useful for * Sentry tagging or Prometheus counters. */ readonly onFallback?: (info: { reason: "search-error"; error: unknown }) => void; } export async function searchWithFallback( input: SearchWithFallbackInput ): Promise> { try { return await searchInIndex(input); } catch (error) { if (error instanceof TenantScopeError) throw error; if (!isMeiliConnectivityError(error)) throw error; input.onFallback?.({ reason: "search-error", error }); return input.fallback({ query: input.query, tenantId: input.tenantId }); } } export async function health(client: SearchClient): Promise<{ status: "available" | "unavailable" }> { try { return await client.health(); } catch { return { status: "unavailable" }; } } /** * Escape characters that have special meaning inside a Meilisearch * filter expression. The wrapper always quotes the value, so we just * need to neutralise quotes and backslashes — the rest is plain text. */ function escapeFilterValue(value: string): string { return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"'); } function buildFilter(tenantId: string, extra: string | readonly string[] | undefined): string { const base = `tenantId = "${escapeFilterValue(tenantId)}"`; if (!extra) return base; if (Array.isArray(extra)) { const trimmed = extra.map((f) => f.trim()).filter((f) => f.length > 0); if (trimmed.length === 0) return base; return `${base} AND ${trimmed.map((f) => `(${f})`).join(" AND ")}`; } const single = (extra as string).trim(); return single.length === 0 ? base : `${base} AND (${single})`; } function scopeDocumentPrimaryKey( schema: SearchIndexSchema, tenantId: string, document: TDocument ): TDocument { const primaryKey = document[schema.primaryKey]; if (typeof primaryKey !== "string" && typeof primaryKey !== "number") { throw new Error(`Document primary key "${schema.primaryKey}" must be string or number.`); } return { ...document, [schema.primaryKey]: buildScopedPrimaryKey(tenantId, primaryKey), [ORIGINAL_PRIMARY_KEY_FIELD]: primaryKey, } as TDocument; } function restoreDocumentPrimaryKey( schema: SearchIndexSchema, document: TDocument ): TDocument { if (!(ORIGINAL_PRIMARY_KEY_FIELD in document)) { return document; } const { [ORIGINAL_PRIMARY_KEY_FIELD]: originalPrimaryKey, ...rest } = document; if (typeof originalPrimaryKey !== "string" && typeof originalPrimaryKey !== "number") { return rest as TDocument; } return { ...rest, [schema.primaryKey]: originalPrimaryKey, } as TDocument; } function buildScopedPrimaryKey(tenantId: string, documentId: string | number): string { return `${encodeURIComponent(tenantId)}:${encodeURIComponent(String(documentId))}`; } function unique(values: readonly T[]): T[] { return Array.from(new Set(values)); } function assertTenantId(tenantId: unknown): asserts tenantId is string { if (typeof tenantId !== "string" || tenantId.length === 0) { throw new TenantScopeError("Search calls require a non-empty tenantId.", "MISSING_TENANT"); } } function isMeiliConnectivityError(error: unknown): boolean { if (!error || typeof error !== "object") return false; const candidate = error as { code?: string; name?: string; message?: string }; if (typeof candidate.code === "string" && /ECONN|ETIMEDOUT|ENOTFOUND|FETCH/iu.test(candidate.code)) return true; if (typeof candidate.name === "string" && /FetchError|MeiliSearchCommunicationError|MeiliSearchTimeOutError|AbortError/iu.test(candidate.name)) return true; if (typeof candidate.message === "string" && /fetch failed|network|unavailable|connect|timeout/iu.test(candidate.message)) return true; return false; }