@endora-commerce/mod-search 0.100.0

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+CAA+C,EAAE,MAAM,iDAAiD,CAAC;AAElH,eAAO,MAAM,UAAU,4DAEtB,CAAC;AAEF,OAAO,EACL,+CAA+C,GAChD,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260501T123145SearchPhraseRecordsInit } from './20260501T123145_search_phrase_records_init.js';
+export const migrations = [
+    Migration20260501T123145SearchPhraseRecordsInit,
+];
+export { Migration20260501T123145SearchPhraseRecordsInit, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+CAA+C,EAAE,MAAM,iDAAiD,CAAC;AAElH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,+CAA+C;CAChD,CAAC;AAEF,OAAO,EACL,+CAA+C,GAChD,CAAC"}

package/docs/search.md

@@ -0,0 +1,284 @@
+---
+title: search
+description: Meilisearch indexer + query bridge
+---
+
+# `search`
+
+Meilisearch-backed catalog search. Owns the indexer that mirrors Catalog
+events into per-Sales-Channel indexes, the typed query bridge, the
+typeahead-popup feed, the analytics ingest for committed search phrases,
+and the LLM-augmented-search opt-in.
+
+The module composition root subscribes to Catalog events
+(`product.created.v1`, `product.updated.v1`, `product.archived.v1`,
+`attribute.updated.v1`) and to Settings events
+(`settings.value_changed`) without imports into either module's
+internals.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/search/suggest?q=…&limit=N` | storefront (no auth) | Typeahead popup feed; returns up to `limit` `ProductSummary` rows ordered by Meilisearch relevance |
+| `POST /api/v1/search/record` | storefront (no auth) | Fire-and-forget analytics ingest; persists one verbatim row in `search_phrase_records` per committed search |
+| `POST /api/v1/admin/search/llm/toggle` | admin (`search:write`) | Cross-setting-validating wrapper around `search.llm.enabled`; refuses to enable when any embedder.* field is empty for any targeted channel |
+
+The full search results page reuses `GET /api/v1/catalog/products?q=…` —
+catalog owns that contract, and the storefront `/search` route just
+re-exports `CatalogPage`. There is no parallel results-page contract.
+
+## Settings
+
+Six knobs live under the `search` group, registered by
+`packages/modules/search/src/manifest.ts`:
+
+| Code | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `search.popup.suggestion_count` | `number` | `8` | How many products the storefront popup shows; `0` suppresses the popup but committed search still navigates |
+| `search.popup.minimum_query_length` | `number` | `3` | Minimum characters before the storefront fires a suggest request and before the recorder persists a row |
+| `search.llm.enabled` | `boolean` | `false` | Enables Meilisearch's hybrid lexical + semantic search on this channel |
+| `search.llm.embedder_url` | `string` | `""` | OpenAI-compatible embedder endpoint URL (used by Meilisearch) |
+| `search.llm.embedder_api_key` | `string` | `""` | Embedder API key (admin UI masks the input) |
+| `search.llm.embedder_model` | `string` | `""` | Embedder model identifier (e.g. `text-embedding-3-small`) |
+
+All six are sales-channel-scoped via the existing Settings model. The
+storefront popup reads its count + threshold per request via the
+universal getter (`SettingsService.get`); on any read error (cache
+miss, `SettingNotRegistered`) the suggest service falls back to the
+manifest defaults so a Settings hiccup never 500s the popup.
+
+## LLM-augmented search
+
+Toggling `search.llm.enabled` on for a channel attaches a Meilisearch
+embedder to that channel's index. We register the embedder under the
+well-known name `default` with `source: 'openAi'`; the `url` parameter
+makes it work against any OpenAI-compatible endpoint (OpenAI itself,
+Azure OpenAI, Ollama's OpenAI shim, …).
+
+The toggle wrapper (`POST /api/v1/admin/search/llm/toggle`) refuses to
+flip `enabled=true` for any channel whose three embedder.* fields
+aren't all populated. The error envelope's `details[]` lists
+every missing `(channelCode, settingCode)` pair so the admin UI can
+highlight the gaps.
+
+The reactor (in `SearchEventSubscriber`) is belt-and-braces: a power
+user PUTting `search.llm.enabled=true` directly through the generic
+Settings admin route (bypassing the wrapper) does **not** poison
+Meilisearch — the reactor warn-logs and leaves the index alone if the
+embedder.* triplet is incomplete.
+
+Disabling never refuses; the reactor calls `index.resetEmbedders()` so
+the channel falls back to plain lexical ranking.
+
+Meilisearch v1.11 gates `embedders` behind the `vectorStore`
+experimental feature; v1.13+ treats embedders as stable. Both are
+supported transparently — the admin endpoint does not gate on the
+Meilisearch version.
+
+## Analytics ingest
+
+Every committed storefront search lands one row in
+`search_phrase_records` for the future Analytics module to aggregate:
+
+| Column | Notes |
+| --- | --- |
+| `phrase` | Verbatim — no typo correction or LLM expansion |
+| `phrase_normalized` | `lower(trim(phrase))`, maintained at insert time; supports case-insensitive aggregation without rewriting the verbatim phrase |
+| `sales_channel_id` | FK → `sales_channels.id` (`ON DELETE RESTRICT` — dropping a channel must surface as a deliberate decision rather than silently delete history) |
+| `result_count` | Number of products the search returned; `0` for dead-end phrases |
+| `recorded_at` | `timestamptz default now()` |
+
+Indexes:
+
+- `idx_search_phrase_records_aggr` on `(sales_channel_id, phrase_normalized, recorded_at desc)` — supports the analytics-module's "phrases by channel and frequency over a window" query.
+- `idx_search_phrase_records_recent` on `(recorded_at desc)` — for ops dashboards.
+
+The recorder is fire-and-forget (`SearchPhraseRecorder.record(...)`):
+it returns once the row has been queued, not once persisted, and
+swallows every exception via warn-log. The route hands off the
+promise without awaiting (`void recorder.record(...)`) and returns
+`202 { ok: true }` immediately. The storefront response is therefore
+never delayed or failed by analytics persistence.
+
+Below-threshold phrases (shorter than the channel's
+`minimum_query_length`) are silently no-op'd server-side as a
+belt-and-braces against a UI bug flooding the table with stub
+phrases.
+
+## Indexer + event subscriber
+
+`SearchIndexer` writes one document per product into a per-channel
+index named `products_<channel_code>`. Document shape carries the
+catalog product surface (id, sku, name, description, type, status,
+slug, primaryAssetUrl, categoryIds, categorySlugs, attributes,
+searchableOptions, createdAt, updatedAt). The indexer also drives
+Meilisearch's `searchableAttributes` + `filterableAttributes` from the
+live `product_attributes.is_searchable` + `is_filterable` flags, and
+its `sortableAttributes` from `SORTABLE_ATTRIBUTES` (see *Sorting*).
+
+**A document carries no price.** It used to carry one, copied from the
+legacy `attributes.defaultPrice` catalogue attribute — not any price
+list's figure — and read by nothing on the query path, which resolves
+the viewer's price from `price_lists` at hydrate time so the index
+cannot decide what a buyer pays. A per-buyer price cannot be indexed
+in any case: one index per sales channel and one document per product
+means pricing the document would multiply the corpus by the customer
+base. The legacy attribute is still indexed under
+`attributes.defaultPrice`, where its name says what it is.
+
+### Sorting
+
+Meilisearch refuses a sort on any field outside the index's
+`sortableAttributes`, so the fields the query path may sort on are
+declared once, in `SORTABLE_ATTRIBUTES` (`search-indexer.ts`):
+`createdAt` and `name`. That constant is both what the indexer applies
+to every channel index and the alphabet `buildSort` may emit — its
+return type is built from it, so a sort naming a field the indexer
+never declared does not compile.
+
+The listing contract's four sorts map as follows:
+
+| `?sort=` | Meilisearch |
+| --- | --- |
+| `relevance` (or absent) | none — the engine's ranking rules |
+| `-createdAt` | `createdAt:desc` |
+| `name` | `name:asc` |
+| `-name` | `name:desc` |
+
+The indexed `name` is resolved in the channel's own default language,
+which is the language the listing renders, so the order a buyer sees
+is the order they were sorted by.
+
+**Upgrading an index built before the sort settings were applied** needs a reindex: the
+settings were never applied (`sortableAttributes` was `[]` on every
+index, and every sorted listing was silently answered by the Postgres
+fallback), and `createdAt` was never written into a document. A full
+reindex applies both. That happens automatically on the next periodic
+sweep in the worker role (`search.reindex_interval_minutes`, default
+10); a deployment that runs no sweep needs the operator step — the
+admin **Reindex products** action or `pnpm --filter backend run
+search:reindex`. An `attribute.updated.v1` refresh reapplies the
+settings but writes no documents, so it restores `name` sorting and
+not `-createdAt`.
+
+### `searchableOptions` — option-list search
+
+For attributes flagged `isSearchable` AND with a select-style
+`valueType` (`select`, `enum`, `multiselect`), the indexer resolves
+the per-locale option label and includes it in the document's
+`searchableOptions: string[]` field. Meilisearch settings include
+`searchableOptions` in `searchableAttributes` so a customer searching
+for the rendered text they see (e.g. "Czerwony") hits products whose
+raw value is the option key (e.g. "red"). Toggling `isSearchable` off
+removes the option labels from `searchableOptions` on the next refresh
+within the existing event-driven cadence.
+
+`SearchEventSubscriber` keeps the indexes in sync:
+
+| Event | Handler |
+| --- | --- |
+| `product.created.v1` | `indexer.upsertProduct(productId)` |
+| `product.updated.v1` | `indexer.upsertProduct(productId)` |
+| `product.archived.v1` | `indexer.deleteProduct(productId)` |
+| `attribute.updated.v1` | `indexer.refreshAttributeSettings()` |
+| `settings.value_changed` (when `settingCode === 'search.llm.enabled'`) | `indexer.attachEmbedderForChannel` / `detachEmbedderForChannel` |
+
+All handlers swallow their own errors — a transient Meilisearch
+outage does not break the catalog write path. The reserved fallback
+in the read path (`catalog/routes.public.ts`) keeps storefront search
+functional with a stale index until the next offline `search:reindex`.
+
+### When the index does not answer
+
+The fallback stays a fallback — a public catalogue must not 503
+because search is unhappy — but it distinguishes two facts that used
+to be fused into one:
+
+- **unreachable** — the engine is down, unroutable or timing out.
+  Transient. `catalog` logs it per request and re-runs the listing
+  through Postgres; nothing else is expected of anybody.
+- **refused** — the engine answered, in milliseconds, that it will not
+  run *this* query: `invalid_search_sort`, `index_not_found`, a
+  rejected API key. Deterministic, will not pass on its own, and a
+  defect in how this module configured the index. The reason string
+  the caller logs names Meilisearch's own error code, and `search`
+  reports it itself at `error` level — once per code, because an index
+  setting is a deployment fact and a public listing would otherwise
+  report it on every request.
+
+That distinction is the whole reason the defect could survive on five
+live indexes: every sorted listing was falling back to Postgres, and
+the only trace of it was a line reading `meilisearch unavailable`
+about an engine that was up and healthy.
+
+## Storefront integration
+
+The page header (`storefront/components/Header.tsx`) renders a
+`<form action="/search" method="GET">` with a progressively-enhanced
+`<SearchAutocomplete>` client component inside it:
+
+- 200 ms debounce; AbortController cancels stale fetches.
+- Below the channel's `minimum_query_length`, no request fires.
+- Keyboard model: ArrowUp/Down to move selection, Enter to navigate
+  to the selected suggestion, Escape to close, click outside to
+  dismiss.
+- 503 from `/search/suggest` surfaces a "search temporarily
+  unavailable" item in the popup without breaking the static form.
+- With JS disabled, the form posts `?q=…` to `/search` natively
+  (no JS required for crawlability).
+
+The `/search` page (`storefront/app/(catalog)/search/page.tsx`)
+re-exports `CatalogPage` — the listing, filters, sort, pagination,
+and empty state are identical to `/catalog`. The only search-specific
+behaviour is the analytics fire-and-forget: when `?q=` is present,
+the page awaits `listProducts` (so `resultCount` is meaningful), then
+`void recordPhrase(...)` BEFORE delegating to `CatalogPage`.
+
+## Reindex CLI
+
+`search reindex` walks every Sales Channel and pushes its public
+product surface into Meilisearch. Idempotent — safe to run after a
+fresh `endora demo seed` or whenever the index drifts from Postgres.
+
+It is a command this module declares in its `manifest.ts` and the host
+runs, so it reindexes through the one `SearchIndexer` the composition
+holds rather than building a second one:
+
+```bash
+pnpm --filter backend run search:reindex
+# or, addressing the host binary directly:
+pnpm --filter backend exec tsx src/cli.ts search reindex
+```
+
+The body is `packages/modules/search/src/backend/cli/reindex.ts`.
+
+## Testing
+
+- `backend/test/contract/search/public-suggest.contract.test.ts` (7 cases) — happy path, limit override, threshold, oversize, missing q, limit OOB.
+- `backend/test/contract/search/public-record.contract.test.ts` (7 cases) — happy path, default `result_count`, channel pinning, empty/oversize/negative validation, below-threshold no-op.
+- `backend/test/contract/search/admin-llm-toggle.contract.test.ts` (5 cases) — incomplete-config refusal (every embedder.* permutation), full-config success, disable always succeeds, unauthenticated → 401.
+- `backend/test/integration/search/manifest-reconcile.test.ts` (2 cases) — group + 6 settings seeded with correct defaults; idempotent re-apply.
+- `backend/test/integration/search/embedder-reactor.test.ts` (3 cases) — attach on enable=true, detach on flip-back-to-false, no event-fire when wrapper refuses the toggle.
+- `backend/test/integration/search/event-subscriber.test.ts` (existing) — catalog-event-driven indexing.
+- `backend/test/integration/search/catalog-via-meilisearch.test.ts` (existing) — env-flag-dispatched read path.
+- `backend/test/integration/search/sort-order.test.ts` (6 cases) — each of the four sorts served by Meilisearch (`x-search-backend` is the load-bearing assertion: Postgres answers all four, so the order alone cannot tell a served page from a fallback), the declared `sortableAttributes`, and the absence of the indexed `price`.
+- `backend/test/unit/search/search-sort-attributes.test.ts` (4 cases) — `buildSort` emits only fields `SORTABLE_ATTRIBUTES` declares.
+- `backend/test/unit/search/search-degrade-observability.test.ts` (3 cases) — a refused query names the engine's error code and is reported once; an unreachable one is not reported twice.
+
+The last two need no services; the rest run against real Postgres +
+real Meilisearch.
+
+## Extension points
+
+- **Custom rankers** — Meilisearch supports custom ranking rules per
+  index; the indexer can push the rule set when the admin UI grows a
+  per-channel weighting affordance.
+- **Embedder-source enum** — `search.llm.embedder_source` with values
+  `openAi | huggingFace | rest | userProvided` would let a single
+  channel pick a non-OpenAI-compatible provider without renaming the
+  three credential settings.
+- **Reserved fallback** — already implemented: when Meilisearch is
+  unavailable, the catalog read path degrades to Postgres ILIKE
+  search via `catalog-query.service.ts` so the storefront is never
+  fully broken.

package/i18n/en.json

@@ -0,0 +1,10 @@
+{
+  "errors.QUERY_TOO_SHORT": "Query Too Short.",
+  "errors.QUERY_TOO_LONG": "Query Too Long.",
+  "errors.LIMIT_OUT_OF_RANGE": "Limit Out Of Range.",
+  "errors.SEARCH_BACKEND_UNAVAILABLE": "Search Backend Unavailable.",
+  "errors.PHRASE_REQUIRED": "Phrase Required.",
+  "errors.PHRASE_TOO_LONG": "Phrase Too Long.",
+  "errors.RESULT_COUNT_INVALID": "Result Count Invalid.",
+  "errors.LLM_CONFIG_INCOMPLETE": "LLM search configuration is incomplete."
+}

package/i18n/pl.json

@@ -0,0 +1,10 @@
+{
+  "errors.QUERY_TOO_SHORT": "Błąd: query too short.",
+  "errors.QUERY_TOO_LONG": "Błąd: query too long.",
+  "errors.LIMIT_OUT_OF_RANGE": "Błąd: limit out of range.",
+  "errors.SEARCH_BACKEND_UNAVAILABLE": "Błąd: search backend unavailable.",
+  "errors.PHRASE_REQUIRED": "Błąd: phrase required.",
+  "errors.PHRASE_TOO_LONG": "Błąd: phrase too long.",
+  "errors.RESULT_COUNT_INVALID": "Błąd: result count invalid.",
+  "errors.LLM_CONFIG_INCOMPLETE": "Konfiguracja wyszukiwania LLM jest niekompletna."
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@endora-commerce/mod-search",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Per-channel Meilisearch indexes, suggest popup, and optional LLM-augmented search.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "search"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/search"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "meilisearch": "^0",
+    "zod": "^4",
+    "@endora-commerce/platform": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "fastify": "^5.12.5",
+    "meilisearch": "^0.57.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}