@volter/twin-algolia

Legacy connector helpers: this package still has callable helpers using the retired v1 syncPull API. Those paths require migration before use on the current kernel; older helper descriptions below do not establish current compatibility. Check the generated index for protocol standing and use the shared model for current state semantics.

Local Algolia twin for the hosted-search surface: index list/delete/clear, record CRUD (add-auto-objectID/add-replace/get/partial-update/delete/batch), a REAL search engine — tokenize + Damerau-Levenshtein typo tolerance (<=2) + REAL filters/facetFilters evaluation + exact facet-count aggregation + a faithful-subset ranking tie-break chain + customRanking — settings get/set, basic bidirectional synonym expansion, and a host-tolerant router — built on the shared @volter/world-core kernel. API-first vendor (no product UI to mirror — the real surface agents integrate with is the REST API / algoliasearch SDK, not the Algolia dashboard).

bun packages/twin/algolia/src/cli.ts

Coverage

This is a v1 slice of the Algolia API, not the full surface. Modeled done: index list/delete/clear, record add-auto-objectID/add-replace/get/partial-update/delete/batch (heterogeneous actions in one call — addObject/updateObject/partialUpdateObject/ partialUpdateObjectNoCreate/deleteObject, grounded LIVE against the real SDK), and search with all the real teeth: typo tolerance (a crafted record set where a 1-typo query matches ONLY the near-typo record), a numeric filters string that EXCLUDES the textually-stronger match (changing hits[0]), facetFilters (incl. an OR-array), EXACT facet-value counts, attributesToRetrieve projection, real pagination (page/hitsPerPage/nbPages), customRanking (flips the order of two text-tied records), settings get/set (a genuine partial merge — setting A doesn't erase a previously-set B), a data-coupling proof that configuring searchableAttributes changes the hit set, and basic bidirectional synonym expansion (a query matches ONLY via a configured synonym group, paired with a control index that has the identical data but no synonym — proving neither an empty-return nor a return-all implementation can fake it). Every one of these is hand-computed-expected-value tested, including the ranking-order assertions, in algolia-capabilities.ts and algolia-twin.test.ts.

Left as todo (honest gaps, not yet modeled): geo search, Query Rules, optional-words / remove-words-if-no-results progressive relaxation, per-word-length graduated typo tuning (uniform <=2 today), distinct dedup, highlighting/snippeting, exposed ranking info, disjunctive facet counting, one-way/placeholder/alt-correction synonyms, the dedicated synonym search endpoint, delete-by-query, multi-object get, index replicas, facet-value search, index copy/move, real async task polling (taskID is a deterministic 0 stub today), full browse (v1 has no /browse endpoint at all — list via search with an empty query instead), multi-index queries, API-key management (incl. HMAC-signed secured keys), query suggestions, personalization, A/B testing, Insights/analytics events, dictionary management, connector push + synonym pull, fixture seeding, parenthesized filters precedence, _tags/tag: shorthand, geo filters, and independently-confirmed exact error-message text (see ## A note on error-message grounding below).

Planned (todo):

1. algolia.search.ranking_criteria_coverage — the remaining documented tie-break criteria and their weighting (geo, filters-as-criterion) on top of the typo/attribute/proximity/exact/custom chain this twin already computes.
2. algolia.search.language_processing — stemming, plural-folding, CJK/Thai segmentation and language-aware normalization; tokenization is deterministic ASCII/Unicode word-boundary splitting + Damerau-Levenshtein typo matching today.

Writes apply synchronously to one kernel root and the twin is host-tolerant (it accepts every real host shape and routes by path) rather than physically split across a DSN.

See src/algolia-capabilities.ts for the full manifest (the real vendor surface is the denominator — coverage is honest and partial until the twin reaches it).

A note on the search engine's honesty

Like this repo's pinecone twin (and unlike the generative twins), Algolia's core operation — matching + ranking text records against a query — is genuinely computable offline: given the stored records, tokenize + Damerau-Levenshtein typo matching + the documented tie-break criteria is deterministic, correct compute, not a placeholder. src/algolia-search.ts (tokenize/typo/rank) and src/algolia-filter.ts (filters string grammar + facetFilters + facet-count aggregation) are net-new modules — see their file headers for the exact modeled semantics, including every honest simplification (strict AND-across-query-words matching within one attribute; no parenthesized filters precedence; a uniform <=2-typo cap instead of per-word-length graduated tuning).

A note on error-message grounding

This pack's {message,status} error envelope SHAPE and the auth headers (x-algolia-application-id/x-algolia-api-key) were confirmed round-tripping correctly through the REAL algoliasearch SDK's own error type in a live pass (a throwaway local server, driven by the actually-installed 4.27.0 package) BEFORE this pack was written — see algolia-sdk.integration.test.ts's header. The exact MESSAGE TEXT for an unknown objectID/index (e.g. "ObjectID does not exist") is modeled on the well-known, widely-published Algolia convention rather than independently re-confirmed against a live account during this build (the rendered API-reference pages are a JS-rendered SPA that did not yield the literal string via a read-only fetch) — filed honestly as algolia.errors.wire_shape_confirmed (todo), not silently claimed as verified.

No webhooks, no signed requests

Algolia's core Search REST surface has no webhook/signed-request surface for this v1 slice (unlike Replicate/fal/Clerk), so this pack has no webhook module and no pure-crypto mutation-test allow entries. Secured (HMAC-signed) API keys are a real Algolia feature but are modeled todo (algolia.auth.secured_api_keys_generate), not done.

Host tolerance, not a host split

Unlike pinecone (a genuine control/data host SPLIT — different planes, different envelopes), Algolia's REST paths already carry the index name (/1/indexes/{indexName}/...), so there is nothing for a host to disambiguate. This twin instead demonstrates host tolerance: every real host shape ({appId}.algolia.net, {appId}-dsn.algolia.net, {appId}-N.algolianet.com) is accepted, and routing is 100% path-driven — an S-sizing simplification, not a physical DSN split.