Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,314 @@
import { describe, expect, it, vi } from "vitest";
import { createSearchClient, type MeiliFactory } from "./client.js";
import { createInMemoryMeili } from "./testing.js";
describe("createSearchClient — guards", () => {
it("rejects an empty index name", () => {
const { factory } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
expect(() => client.index("")).toThrow(/non-empty string/);
});
it("constructs against the real Meilisearch SDK when no factory is injected", () => {
// Exercises the default require()-based factory. Construction is offline
// (no network request is made until a method is actually called).
const client = createSearchClient({ url: "http://127.0.0.1:7700" });
expect(typeof client.index).toBe("function");
expect(typeof client.health).toBe("function");
});
it("reports unavailable when health returns a malformed payload", async () => {
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments() {},
};
},
async health() {
return null as unknown as { status: string };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(client.health()).resolves.toEqual({ status: "unavailable" });
});
});
describe("IndexHandle.ensure — createIndex error handling", () => {
it("rethrows a non 'already exists' error from createIndex", async () => {
const { factory } = createInMemoryMeili({ throwOnIndex: true });
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(
client.index("x").ensure({ primaryKey: "id", settings: {} })
).rejects.toThrow(/meili offline/);
});
it("swallows an HTTP 409 conflict and still applies settings", async () => {
const updateSettings = vi.fn(async () => {});
const factory: MeiliFactory = () => ({
async createIndex() {
throw Object.assign(new Error("conflict"), { httpStatus: 409 });
},
index() {
return {
updateSettings,
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments() {},
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(
client.index("x").ensure({ primaryKey: "id", settings: { searchableAttributes: ["t"] } })
).resolves.toBeUndefined();
expect(updateSettings).toHaveBeenCalledOnce();
});
});
describe("IndexHandle.ensure — settings mapping", () => {
it("maps every settings field including synonyms onto the Meilisearch input", async () => {
let received: Record<string, unknown> | undefined;
// No createIndex member → exercises the branch where ensure skips
// index creation entirely.
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings(input: Record<string, unknown>) {
received = input;
},
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments() {},
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await client.index("x").ensure({
primaryKey: "id",
settings: {
searchableAttributes: ["title"],
filterableAttributes: ["tenantId"],
sortableAttributes: ["createdAt"],
rankingRules: ["words"],
stopWords: ["the"],
synonyms: { car: ["auto", "vehicle"] },
},
});
expect(received).toEqual({
searchableAttributes: ["title"],
filterableAttributes: ["tenantId"],
sortableAttributes: ["createdAt"],
rankingRules: ["words"],
stopWords: ["the"],
synonyms: { car: ["auto", "vehicle"] },
});
});
});
describe("IndexHandle.search — result normalisation & option mapping", () => {
it("fills missing totals, omits absent limit/offset, and forwards every option", async () => {
let receivedOptions: Record<string, unknown> | undefined;
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search(_query: string, options: Record<string, unknown>) {
receivedOptions = options;
// Intentionally omit estimatedTotalHits / processingTimeMs /
// limit / offset to drive the default-and-omit branches.
return { hits: [{ id: "1", tenantId: "t1" }] };
},
async addDocuments() {},
async deleteDocuments() {},
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const result = await client.index("x").search("hello", {
filter: ['tenantId = "t1"', "isPublished = true"],
sort: ["createdAt:desc"],
limit: 5,
offset: 2,
attributesToHighlight: ["title"],
attributesToRetrieve: ["id", "title"],
});
expect(result.estimatedTotalHits).toBe(1); // estimatedTotalHits ?? hits.length
expect(result.processingTimeMs).toBe(0); // processingTimeMs ?? 0
expect(result.limit).toBeUndefined();
expect(result.offset).toBeUndefined();
expect(result.hits).toEqual([{ document: { id: "1", tenantId: "t1" } }]);
expect(receivedOptions).toEqual({
filter: ['tenantId = "t1"', "isPublished = true"],
sort: ["createdAt:desc"],
limit: 5,
offset: 2,
attributesToHighlight: ["title"],
attributesToRetrieve: ["id", "title"],
});
});
});
describe("IndexHandle — empty batches are no-ops", () => {
it("does not touch the backend on an empty upsert or delete", async () => {
const addDocuments = vi.fn(async () => {});
const deleteDocuments = vi.fn(async () => {});
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search() {
return { hits: [] };
},
addDocuments,
deleteDocuments,
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const handle = client.index("x");
await handle.upsert([]);
await handle.delete([]);
expect(addDocuments).not.toHaveBeenCalled();
expect(deleteDocuments).not.toHaveBeenCalled();
});
});
describe("IndexHandle.deleteByFilter", () => {
it("deletes documents matching a filter via deleteDocuments({ filter })", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const handle = client.index<{ id: string; tenantId: string }>("kb");
await handle.ensure({ primaryKey: "id", settings: { filterableAttributes: ["tenantId"] } });
await handle.upsert([
{ id: "a", tenantId: "t1" },
{ id: "b", tenantId: "t2" },
]);
await handle.deleteByFilter('tenantId = "t1"');
const docs = state.indexes.get("kb")?.documents;
expect(docs?.has("a")).toBe(false);
expect(docs?.has("b")).toBe(true);
});
it("falls back to deleteDocumentsFilter when filtered deleteDocuments is unsupported", async () => {
const deleteDocumentsFilter = vi.fn(async () => {});
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments(input: readonly (string | number)[] | { filter: string }) {
if (!Array.isArray(input)) {
throw new Error("filter delete is unsupported on this build");
}
},
deleteDocumentsFilter,
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await client.index("kb").deleteByFilter('tenantId = "t1"');
expect(deleteDocumentsFilter).toHaveBeenCalledWith({ filter: 'tenantId = "t1"' });
});
it("throws when no filter-delete capability exists at all", async () => {
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments(input: readonly (string | number)[] | { filter: string }) {
if (!Array.isArray(input)) {
throw new Error("filter delete is unknown on this build");
}
},
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(client.index("kb").deleteByFilter('tenantId = "t1"')).rejects.toThrow(
/does not support deleteByFilter/
);
});
it("rethrows an error from deleteDocuments that is not a 'filter unsupported' signal", async () => {
const factory: MeiliFactory = () => ({
index() {
return {
async updateSettings() {},
async search() {
return { hits: [] };
},
async addDocuments() {},
async deleteDocuments() {
throw new Error("backend exploded");
},
};
},
async health() {
return { status: "available" };
},
});
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(client.index("kb").deleteByFilter('tenantId = "t1"')).rejects.toThrow(
/backend exploded/
);
});
});
describe("in-memory fixture behaviour relied on by worker integration tests", () => {
it("auto-creates a missing index on first search", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const res = await client.index("lazy").search("", { limit: 10 });
expect(res.hits).toEqual([]);
expect(state.indexes.has("lazy")).toBe(true);
});
it("matches documents by terms inside array-valued fields", async () => {
const { factory } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const handle = client.index<{ id: string; tenantId: string; tags: string[] }>("kb");
await handle.ensure({ primaryKey: "id", settings: { filterableAttributes: ["tenantId"] } });
await handle.upsert([{ id: "1", tenantId: "t1", tags: ["Onboarding", "Setup"] }]);
const res = await handle.search("setup", { filter: 'tenantId = "t1"', limit: 10 });
expect(res.hits.map((hit) => hit.document.id)).toEqual(["1"]);
});
});
@@ -0,0 +1,65 @@
import { describe, expect, it } from "vitest";
import { createSearchClient } from "./client.js";
import { createSearchIndex } from "./index-helper.js";
import type { SearchIndexSchema } from "./schemas/index.js";
import { createInMemoryMeili } from "./testing.js";
/**
* A schema that carries stopWords + synonyms but deliberately omits
* rankingRules — exercises both the truthy (stopWords/synonyms) and the
* falsy (rankingRules) merge branches plus the synonyms copy helper.
*/
const schemaWithSynonyms: SearchIndexSchema = {
name: "syn-index",
primaryKey: "id",
searchableAttributes: ["title"],
filterableAttributes: ["tenantId"],
sortableAttributes: ["createdAt"],
stopWords: ["the", "a"],
synonyms: { car: ["auto", "vehicle"], laptop: ["notebook"] },
allowedDocumentFields: ["id", "tenantId", "title", "createdAt"],
};
describe("createSearchIndex — schema settings merge", () => {
it("forwards schema-level stopWords and synonyms, omitting absent rankingRules", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await createSearchIndex({ client, schema: schemaWithSynonyms });
const settings = state.indexes.get("syn-index")?.settings;
expect(settings).toMatchObject({
searchableAttributes: ["title"],
stopWords: ["the", "a"],
synonyms: { car: ["auto", "vehicle"], laptop: ["notebook"] },
});
expect(settings).not.toHaveProperty("rankingRules");
});
it("lets each overridable field win over the schema value", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await createSearchIndex({
client,
schema: schemaWithSynonyms,
settingsOverride: {
searchableAttributes: ["body"],
filterableAttributes: ["tenantId", "status"],
sortableAttributes: ["updatedAt"],
rankingRules: ["words", "sort"],
stopWords: ["und"],
synonyms: { x: ["y"] },
},
});
expect(state.indexes.get("syn-index")?.settings).toMatchObject({
searchableAttributes: ["body"],
filterableAttributes: ["tenantId", "status"],
sortableAttributes: ["updatedAt"],
rankingRules: ["words", "sort"],
stopWords: ["und"],
synonyms: { x: ["y"] },
});
});
});
@@ -0,0 +1,63 @@
import { describe, expect, it } from "vitest";
import * as search from "./index.js";
/**
* The barrel is the package's public contract: every name listed in the
* code-review checklist must stay re-exported, and the raw Meilisearch SDK
* must never leak through it. These tests pin both invariants so an
* accidental re-export removal (or a stray `MeiliSearch` export) fails CI.
*/
describe("@hivegrid/search public barrel", () => {
it("re-exports the documented runtime API", () => {
const expected = [
"createSearchClient",
"createSearchIndex",
"IndexSchemaValidationError",
"validateIndexSchema",
"bulkIndex",
"deleteFromIndex",
"health",
"searchInIndex",
"searchWithFallback",
"TenantScopeError",
"ALL_SEARCH_INDEXES",
"BULK_REINDEX_SUPPORTED_INDEXES",
"BULK_REINDEX_SUPPORTED_INDEX_NAMES",
"crmContactsIndex",
"getSearchIndexSchema",
"kbArticlesIndex",
"usersIndex",
"getIndexedEntitiesForPermissions",
"getIndexedEntity",
"indexedEntities",
"listIndexedEntities",
"validateIndexedEntities",
"sanitizeDocument",
"publishSearchBulkReindexEvent",
"publishSearchDeleteEvent",
"publishSearchUpsertEvent",
"searchEventType",
] as const;
for (const name of expected) {
expect(search, `missing export: ${name}`).toHaveProperty(name);
expect(search[name as keyof typeof search]).toBeDefined();
}
});
it("does not leak the raw Meilisearch SDK constructor", () => {
expect(search).not.toHaveProperty("MeiliSearch");
expect(search).not.toHaveProperty("Meilisearch");
});
it("wires the error classes as constructable Error subclasses", () => {
expect(new search.TenantScopeError("nope")).toBeInstanceOf(Error);
expect(new search.IndexSchemaValidationError("nope", "EMPTY_NAME")).toBeInstanceOf(Error);
});
it("keeps the index registry consistent between the barrel and schemas", () => {
expect(search.ALL_SEARCH_INDEXES).toContain(search.kbArticlesIndex);
expect(search.getSearchIndexSchema(search.kbArticlesIndex.name)).toBe(search.kbArticlesIndex);
expect(search.getSearchIndexSchema("does-not-exist")).toBeUndefined();
});
});
@@ -1,5 +1,5 @@
/**
* Public entry point for `@toolctrl/search`.
* Public entry point for `@hivegrid/search`.
*
* The package exposes a typed wrapper around Meilisearch with two
* non-negotiable invariants:
@@ -37,10 +37,11 @@ export {
BULK_REINDEX_SUPPORTED_INDEXES,
BULK_REINDEX_SUPPORTED_INDEX_NAMES,
crmContactsIndex,
entitiesIndex,
filesIndex,
getSearchIndexSchema,
kbArticlesIndex,
rowsIndex,
projectsIndex,
tasksIndex,
usersIndex,
} from "./schemas/index.js";
export type { SearchIndexSchema } from "./schemas/index.js";
@@ -20,6 +20,14 @@ describe("indexedEntities registry", () => {
const keys = listIndexedEntities().map((entity) => entity.key);
expect(keys).toContain("file");
expect(getIndexedEntity("file")).toMatchObject({ key: "file", table: "File", index: "files", permission: "files.read_all" });
// CRM contacts (R-P6): one entry covers both private persons and organisations.
expect(keys).toContain("contact");
expect(getIndexedEntity("contact")).toMatchObject({
key: "contact",
table: "Kontakt",
index: "crm-contacts",
permission: "crm.read_all",
});
});
it("lists registered entities together with their key", () => {
@@ -59,6 +59,50 @@ export const indexedEntities = {
searchable: ["title", "description"],
permission: "tasks.read_all",
},
// CRM contacts (R-P6). Tenant-scoped; only contacts the user may read_all
// surface in global search (the owner/zustaendiger read_own visibility is
// enforced at the route layer, not here — mirroring file/task). One entry is
// sufficient: a Kontakt is the Oberbegriff for BOTH private persons
// (kontaktTyp = privatperson → vorname/nachname) and organisations
// (kontaktTyp = organisation → orgName), so there is no separate Firma/Company
// model or index — companies search through this same `contact` entry.
//
// `searchable` lists the `crm-contacts` Meilisearch *document* fields (English,
// = crmContactsIndex.searchableAttributes), NOT the German Kontakt columns:
// the typed Kontakt fields are projected onto these document keys when indexed
// (vorname → firstName, nachname → lastName, orgName → company, primaerEmail →
// email), exactly like the existing entity-builder contact feeder
// (apps/web/.../rowSearchOutbox.server.ts → rowToContactDocument).
contact: {
table: "Kontakt",
index: "crm-contacts",
searchable: ["firstName", "lastName", "email", "company", "jobTitle", "tags"],
permission: "crm.read_all",
},
company: {
table: "Kontakt",
index: "crm-contacts",
searchable: ["company", "email", "tags"],
permission: "crm.read_all",
},
lead: {
table: "InboxLead",
index: "crm-contacts",
searchable: ["firstName", "lastName", "email", "company", "tags"],
permission: "leads.read_all",
},
project: {
table: "Projekt",
index: "projects",
searchable: ["projectNumber", "name", "description", "type", "source"],
permission: "projects.read_all",
},
user: {
table: "TenantUser",
index: "users",
searchable: ["firstName", "lastName", "email"],
permission: "app.settings.members.view",
},
} satisfies Record<string, IndexedEntityConfig>;
export type IndexedEntityKey = keyof typeof indexedEntities;
@@ -13,9 +13,9 @@ import type { SearchIndexSchema } from "./schemas/index.js";
import { sanitizeDocument } from "./sanitize.js";
/**
* Loose alias matching the @toolctrl/db OutboxPublisherTransaction shape.
* Loose alias matching the @hivegrid/db OutboxPublisherTransaction shape.
* We avoid the direct import to keep packages/search free of a Prisma /
* @toolctrl/db dependency — the helper here is a thin wrapper around the
* @hivegrid/db dependency — the helper here is a thin wrapper around the
* caller-supplied publish function.
*/
export interface SearchOutboxPublisher {
@@ -0,0 +1,288 @@
import { describe, expect, it, vi } from "vitest";
import type {
IndexHandle,
IndexSearchOptions,
SearchClient,
SearchDocument,
SearchHits,
} from "./client.js";
import { bulkIndex, searchInIndex, searchWithFallback } from "./query.js";
import { kbArticlesIndex } from "./schemas/index.js";
const ORIGINAL_PRIMARY_KEY_FIELD = "__hivegridOriginalPrimaryKey";
/**
* Minimal SearchClient fake that records the (query, options) handed to
* the underlying index handle and returns a caller-supplied result. Lets
* the tests assert the exact filter / attribute strings query.ts builds
* without depending on the in-memory fake's filter interpretation.
*/
function capturingClient(result?: SearchHits): {
client: SearchClient;
calls: Array<{ query: string; options: IndexSearchOptions }>;
} {
const calls: Array<{ query: string; options: IndexSearchOptions }> = [];
const searchResult: SearchHits = result ?? { hits: [], estimatedTotalHits: 0, processingTimeMs: 0 };
const client = {
index<TDocument extends SearchDocument = SearchDocument>(): IndexHandle<TDocument> {
return {
async ensure() {},
async search(query: string, options: IndexSearchOptions) {
calls.push({ query, options });
return searchResult as SearchHits<TDocument>;
},
async upsert() {},
async delete() {},
async deleteByFilter() {},
};
},
async health() {
return { status: "available" as const };
},
} satisfies SearchClient;
return { client, calls };
}
function throwingClient(error: unknown): SearchClient {
return {
index<TDocument extends SearchDocument = SearchDocument>(): IndexHandle<TDocument> {
return {
async ensure() {},
async search(): Promise<SearchHits<TDocument>> {
throw error;
},
async upsert() {},
async delete() {},
async deleteByFilter() {},
};
},
async health() {
return { status: "available" as const };
},
};
}
describe("searchInIndex — filter construction", () => {
it("escapes quotes and backslashes in the tenantId so the filter cannot be broken out of", async () => {
const { client, calls } = capturingClient();
await searchInIndex({ client, schema: kbArticlesIndex, tenantId: 'a"b\\c', query: "x" });
// Backslash -> \\ then quote -> \" → the value stays inside one quoted token.
expect(calls[0]?.options.filter).toBe('tenantId = "a\\"b\\\\c"');
});
it("AND-merges an array of extra filters and drops blank entries", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
options: { extraFilters: ["isPublished = true", " ", 'language = "de"'] },
});
expect(calls[0]?.options.filter).toBe(
'tenantId = "t1" AND (isPublished = true) AND (language = "de")'
);
});
it("falls back to the bare tenant filter when every array entry is blank", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
options: { extraFilters: [" ", ""] },
});
expect(calls[0]?.options.filter).toBe('tenantId = "t1"');
});
it("falls back to the bare tenant filter for a blank single extra filter", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
options: { extraFilters: " " },
});
expect(calls[0]?.options.filter).toBe('tenantId = "t1"');
});
it("defaults a missing query to an empty string", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: undefined as unknown as string,
});
expect(calls[0]?.query).toBe("");
});
});
describe("searchInIndex — attributesToRetrieve handling", () => {
it("augments attributesToRetrieve with the primary key and internal field, deduped", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
// "id" duplicates the primaryKey to exercise the de-dup path.
options: { attributesToRetrieve: ["title", "id"] },
});
expect(calls[0]?.options.attributesToRetrieve).toEqual([
"title",
"id",
ORIGINAL_PRIMARY_KEY_FIELD,
]);
});
it("leaves attributesToRetrieve untouched when the wildcard is requested", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
options: { attributesToRetrieve: ["*"] },
});
expect(calls[0]?.options.attributesToRetrieve).toEqual(["*"]);
});
it("strips the internal extraFilters key before handing options to the client", async () => {
const { client, calls } = capturingClient();
await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
options: { extraFilters: "isPublished = true", limit: 3 },
});
expect(calls[0]?.options).not.toHaveProperty("extraFilters");
expect(calls[0]?.options.limit).toBe(3);
});
});
describe("searchInIndex — primary-key restoration", () => {
it("returns the document unchanged when it carries no internal primary-key field", async () => {
const { client } = capturingClient({
hits: [{ document: { id: "raw-id", tenantId: "t1", title: "X" } }],
estimatedTotalHits: 1,
processingTimeMs: 0,
});
const res = await searchInIndex({ client, schema: kbArticlesIndex, tenantId: "t1", query: "x" });
expect(res.hits[0]?.document).toEqual({ id: "raw-id", tenantId: "t1", title: "X" });
});
it("restores the original domain id from the internal field", async () => {
const { client } = capturingClient({
hits: [{ document: { id: "t1:raw", tenantId: "t1", [ORIGINAL_PRIMARY_KEY_FIELD]: "raw" } }],
estimatedTotalHits: 1,
processingTimeMs: 0,
});
const res = await searchInIndex({ client, schema: kbArticlesIndex, tenantId: "t1", query: "x" });
expect(res.hits[0]?.document).toEqual({ id: "raw", tenantId: "t1" });
expect(ORIGINAL_PRIMARY_KEY_FIELD in (res.hits[0]?.document ?? {})).toBe(false);
});
it("drops the internal field but keeps the scoped id when the original is not a primitive", async () => {
const { client } = capturingClient({
hits: [
{
document: {
id: "t1:raw",
tenantId: "t1",
title: "X",
[ORIGINAL_PRIMARY_KEY_FIELD]: { nested: true },
},
},
],
estimatedTotalHits: 1,
processingTimeMs: 0,
});
const res = await searchInIndex({ client, schema: kbArticlesIndex, tenantId: "t1", query: "x" });
expect(res.hits[0]?.document).toEqual({ id: "t1:raw", tenantId: "t1", title: "X" });
expect(ORIGINAL_PRIMARY_KEY_FIELD in (res.hits[0]?.document ?? {})).toBe(false);
});
});
describe("bulkIndex — input validation", () => {
it("surfaces a clear error when a document is missing its primary key", async () => {
const { client } = capturingClient();
await expect(
bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "t1",
documents: [
{ tenantId: "t1", title: "no id" } as unknown as SearchDocument,
],
})
).rejects.toThrow(/missing primary key/);
});
});
describe("searchWithFallback — connectivity detection", () => {
const fallbackResult: SearchHits = {
hits: [{ document: { id: "fb", tenantId: "t1" } }],
estimatedTotalHits: 1,
processingTimeMs: 0,
};
const fallback = () => Promise.resolve(fallbackResult);
it("falls back when the error matches only by its name", async () => {
const error = Object.assign(new Error("boom"), { name: "MeiliSearchCommunicationError" });
const res = await searchWithFallback({
client: throwingClient(error),
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
fallback,
});
expect(res.hits[0]?.document.id).toBe("fb");
});
it("falls back when the error matches only by its message", async () => {
const error = { message: "fetch failed" };
const res = await searchWithFallback({
client: throwingClient(error),
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
fallback,
});
expect(res.hits[0]?.document.id).toBe("fb");
});
it("rethrows a non-connectivity error and never invokes the fallback", async () => {
const onFallback = vi.fn();
const spied = vi.fn(fallback);
await expect(
searchWithFallback({
client: throwingClient(new Error("validation failed: bad filter syntax")),
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
fallback: spied,
onFallback,
})
).rejects.toThrow(/validation failed/);
expect(spied).not.toHaveBeenCalled();
expect(onFallback).not.toHaveBeenCalled();
});
it("rethrows when the thrown value is not an object", async () => {
const spied = vi.fn(fallback);
await expect(
searchWithFallback({
client: throwingClient("string error"),
schema: kbArticlesIndex,
tenantId: "t1",
query: "x",
fallback: spied,
})
).rejects.toBe("string error");
expect(spied).not.toHaveBeenCalled();
});
});
@@ -2,7 +2,7 @@
* Tenant-scoped search query helpers.
*
* These functions are the only sanctioned read/write surface — domain
* code that imports `@toolctrl/search` reaches Meilisearch through them
* code that imports `@hivegrid/search` reaches Meilisearch through them
* and nothing else. Every call requires an explicit tenantId; the
* wrapper translates that into the Meilisearch filter expression
* `tenantId = "<id>"` and AND-merges it with any caller-supplied
@@ -14,7 +14,7 @@ import type { IndexSearchOptions, SearchClient, SearchDocument, SearchHits } fro
import { sanitizeDocument } from "./sanitize.js";
import type { SearchIndexSchema } from "./schemas/index.js";
const ORIGINAL_PRIMARY_KEY_FIELD = "__toolctrlOriginalPrimaryKey";
const ORIGINAL_PRIMARY_KEY_FIELD = "__hivegridOriginalPrimaryKey";
export class TenantScopeError extends Error {
override readonly name = "TenantScopeError";
@@ -9,12 +9,13 @@ export const crmContactsIndex: SearchIndexSchema = {
name: "crm-contacts",
primaryKey: "id",
searchableAttributes: ["firstName", "lastName", "email", "company", "jobTitle", "tags"],
filterableAttributes: ["tenantId", "status", "ownerId", "tags"],
filterableAttributes: ["tenantId", "entityType", "status", "ownerId", "tags"],
sortableAttributes: ["createdAt", "updatedAt", "lastInteractionAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"entityType",
"firstName",
"lastName",
"email",
@@ -1,16 +0,0 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Entity (table-definition) search. Powers the entity picker in row
* editors. The schema is small because entity definitions are low
* cardinality and rarely change.
*/
export const entitiesIndex: SearchIndexSchema = {
name: "entities",
primaryKey: "id",
searchableAttributes: ["name", "title", "titlePlural"],
filterableAttributes: ["tenantId", "type"],
sortableAttributes: ["name", "createdAt", "updatedAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: ["id", "tenantId", "name", "title", "titlePlural", "type", "createdAt", "updatedAt"],
};
@@ -0,0 +1,18 @@
import type { SearchIndexSchema } from "./types.js";
/**
* HR employee directory (AK-P17a). Only non-sensitive display fields are indexed
* so people can find a colleague by name/position/team. Emergency contacts,
* personnel documents and ALL password-safe data are NEVER indexed. The
* estate-wide `hivegrid-` Meili prefix (infra STANDARDS §4) is applied at the
* runtime adapter layer, so the schema name here stays unprefixed.
*/
export const hrDirectoryIndex: SearchIndexSchema = {
name: "hr-directory",
primaryKey: "id",
searchableAttributes: ["name", "position", "team", "email"],
filterableAttributes: ["tenantId", "team", "locationId"],
sortableAttributes: ["name", "team"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: ["id", "tenantId", "userId", "name", "email", "position", "team", "locationId"],
};
@@ -0,0 +1,16 @@
import type { SearchIndexSchema } from "./types.js";
/**
* HR locations (AK-P17a). Searchable by name/city/address so admins can find a
* site quickly. The estate-wide `hivegrid-` Meili prefix (infra STANDARDS §4) is
* applied at the runtime adapter layer, so the schema name here stays unprefixed.
*/
export const hrLocationsIndex: SearchIndexSchema = {
name: "hr-locations",
primaryKey: "id",
searchableAttributes: ["name", "city", "addressLine1", "postalCode"],
filterableAttributes: ["tenantId", "isDefault", "archived"],
sortableAttributes: ["name"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: ["id", "tenantId", "name", "addressLine1", "postalCode", "city", "country", "isDefault", "archived"],
};
@@ -1,17 +1,19 @@
import { crmContactsIndex } from "./crm-contacts.js";
import { entitiesIndex } from "./entities.js";
import { filesIndex } from "./files.js";
import { hrDirectoryIndex } from "./hr-directory.js";
import { hrLocationsIndex } from "./hr-locations.js";
import { kbArticlesIndex } from "./kb-articles.js";
import { rowsIndex } from "./rows.js";
import { projectsIndex } from "./projects.js";
import { tasksIndex } from "./tasks.js";
import type { SearchIndexSchema } from "./types.js";
import { usersIndex } from "./users.js";
export { crmContactsIndex } from "./crm-contacts.js";
export { entitiesIndex } from "./entities.js";
export { filesIndex } from "./files.js";
export { hrDirectoryIndex } from "./hr-directory.js";
export { hrLocationsIndex } from "./hr-locations.js";
export { kbArticlesIndex } from "./kb-articles.js";
export { rowsIndex } from "./rows.js";
export { projectsIndex } from "./projects.js";
export { tasksIndex } from "./tasks.js";
export { usersIndex } from "./users.js";
export type { SearchIndexSchema } from "./types.js";
@@ -25,11 +27,12 @@ export type { SearchIndexSchema } from "./types.js";
export const ALL_SEARCH_INDEXES: readonly SearchIndexSchema[] = [
kbArticlesIndex,
crmContactsIndex,
rowsIndex,
entitiesIndex,
usersIndex,
projectsIndex,
filesIndex,
tasksIndex,
hrDirectoryIndex,
hrLocationsIndex,
];
/**
@@ -37,7 +40,7 @@ export const ALL_SEARCH_INDEXES: readonly SearchIndexSchema[] = [
* pager. Keep this list in sync with apps/worker/src/jobs/search-indexer-
* bulk-pagers.ts so the CLI cannot enqueue jobs the worker cannot run.
*/
export const BULK_REINDEX_SUPPORTED_INDEX_NAMES = [kbArticlesIndex.name, crmContactsIndex.name, rowsIndex.name, usersIndex.name] as const;
export const BULK_REINDEX_SUPPORTED_INDEX_NAMES = [kbArticlesIndex.name, crmContactsIndex.name, usersIndex.name, projectsIndex.name] as const;
export const BULK_REINDEX_SUPPORTED_INDEXES: readonly SearchIndexSchema[] = ALL_SEARCH_INDEXES.filter((schema) =>
(BULK_REINDEX_SUPPORTED_INDEX_NAMES as readonly string[]).includes(schema.name)
@@ -0,0 +1,29 @@
import type { SearchIndexSchema } from "./types.js";
export const projectsIndex: SearchIndexSchema = {
name: "projects",
primaryKey: "id",
searchableAttributes: ["projectNumber", "name", "description", "type", "source"],
filterableAttributes: ["tenantId", "pipelineId", "stageId", "ownerId", "projectLeadId", "archived"],
sortableAttributes: ["createdAt", "updatedAt", "deadline", "potentialValue", "orderVolume"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"projectNumber",
"name",
"description",
"type",
"source",
"pipelineId",
"stageId",
"ownerId",
"projectLeadId",
"archived",
"createdAt",
"updatedAt",
"deadline",
"potentialValue",
"orderVolume",
],
};
@@ -1,27 +0,0 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Generic row search inside the rows-engine. Used by the table-search
* widget; the indexer flattens the row payload into a `searchable` text
* blob (caller responsibility) and a normalized `properties` JSON for
* facets.
*/
export const rowsIndex: SearchIndexSchema = {
name: "rows",
primaryKey: "id",
searchableAttributes: ["searchable", "folio", "entityName"],
filterableAttributes: ["tenantId", "entityId", "entityName", "createdById"],
sortableAttributes: ["createdAt", "updatedAt", "folio"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"entityId",
"entityName",
"folio",
"searchable",
"createdById",
"createdAt",
"updatedAt",
],
};
@@ -7,9 +7,9 @@ import {
BULK_REINDEX_SUPPORTED_INDEX_NAMES,
crmContactsIndex,
usersIndex,
projectsIndex,
getSearchIndexSchema,
kbArticlesIndex,
rowsIndex,
} from "./index.js";
describe("search index catalog", () => {
@@ -40,8 +40,8 @@ describe("search index catalog", () => {
expect([...BULK_REINDEX_SUPPORTED_INDEX_NAMES]).toEqual([
kbArticlesIndex.name,
crmContactsIndex.name,
rowsIndex.name,
usersIndex.name,
projectsIndex.name,
]);
expect(BULK_REINDEX_SUPPORTED_INDEXES.map((schema) => schema.name)).toEqual([
...BULK_REINDEX_SUPPORTED_INDEX_NAMES,
@@ -56,7 +56,7 @@ describe("search index catalog", () => {
it("keeps operator docs explicit about the current bulk-reindex scope", () => {
const featureDocs = readRepoFile("docs/features/search.md");
expect(featureDocs).toContain("`kb-articles`, `crm-contacts`, `rows`, and `users`");
expect(featureDocs).toContain("`kb-articles`, `crm-contacts`, `users`, and `projects`");
expect(featureDocs).toMatch(/Entities still require\s+a dedicated bulk pager/);
});
});