@volter/twin-algolia 0.1.0

package/src/index.ts

@@ -0,0 +1,103 @@
+// @volter/twin-algolia — the Algolia (algolia.com) hosted-search API twin, built on the shared
+// @volter/world-core kernel. Single-plane REST transport: every route lives under
+// `/1/indexes/{indexName}/...` (index list/delete/clear, record CRUD, REAL search — tokenize +
+// Damerau-Levenshtein typo tolerance + a faithful-subset ranking + REAL filter/facetFilters
+// evaluation + exact facet-count aggregation + customRanking tie-breaks + basic bidirectional
+// synonym expansion, settings get/set). Host-TOLERANT (not host-SPLIT, unlike pinecone): every
+// real Algolia host shape ({appId}.algolia.net / {appId}-dsn.algolia.net /
+// {appId}-N.algolianet.com) routes to the SAME single plane, since Algolia's REST paths already
+// carry the index name — no host-based dispatch is needed (see algolia-twin.ts's header). State
+// lives entirely in the kernel action log (no side-store). API-first vendor: no mirror, no UI
+// capabilities (ui-scope.json).
+//
+// THE SEARCH ENGINE (README ## Coverage has the full reasoning): this twin's search is a
+// faithful, deterministic SUBSET of the documented tie-break criteria, not a lesser stub;
+// widening it is `algolia.search.ranking_criteria_coverage` (todo). Writes apply synchronously
+// to one kernel root. Tokenization is deterministic ASCII/Unicode word-splitting today, with
+// stemming/plurals/CJK segmentation filed as `algolia.search.language_processing`. (Conformance/capability tooling lives in
+// @volter/world-tooling, a dev dependency — NOT shipped.)
+export {
+  handleAlgoliaTwinRequest,
+  routeAlgoliaSurface,
+  mintHost,
+  recoverAppIdFromHost,
+  algoliaTwinSnapshot,
+  ALGOLIA_RESOURCE_TYPES,
+} from './algolia-twin.ts';
+export type {
+  AlgoliaRequest,
+  AlgoliaResponse,
+  AlgoliaSurface,
+  AlgoliaResourceType,
+  AlgoliaTwinSnapshot,
+} from './algolia-twin.ts';
+export { createAlgoliaTwinFetch, createAlgoliaTwinServer, type AlgoliaTwinFetchOptions } from './algolia-server.ts';
+export {
+  mapIndex,
+  mapRecord,
+  pullAlgoliaIndexes,
+  pullAlgoliaRecords,
+  syncAlgoliaFromReal,
+} from './algolia-connector.ts';
+export type { AlgoliaLikeClient, AlgoliaRealIndex, AlgoliaRealRecord, AlgoliaBudgetedOptions } from './algolia-connector.ts';
+// The client-side rate budget — the fail-closed backstop every live Algolia call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is Algolia's
+// DECLARATION (window/ceiling/per-method weights) plus `guardAlgoliaClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `AlgoliaBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export {
+  ALGOLIA_BUDGETED_METHODS,
+  ALGOLIA_BUDGET_CEILING,
+  ALGOLIA_BUDGET_MAX_RETRY_AFTER_S,
+  ALGOLIA_BUDGET_WINDOW_MS,
+  ALGOLIA_CALL_WEIGHTS,
+  ALGOLIA_RATE_BUDGET,
+  AlgoliaBudget,
+  AlgoliaBudgetError,
+  algoliaBudgetPath,
+  algoliaCallWeight,
+  algoliaClientBudget,
+  guardAlgoliaClient,
+} from './algolia-budget.ts';
+export type { AlgoliaBudgetErrorKind, AlgoliaBudgetOptions, AlgoliaBudgetReservation, AlgoliaBudgetSnapshot } from './algolia-budget.ts';
+export { matchesAlgoliaFilters, matchesFacetFilters, computeFacetCounts } from './algolia-filter.ts';
+export type { FacetFilters, FacetFilterClause } from './algolia-filter.ts';
+export { tokenize, damerauLevenshtein, rankRecords, buildSynonymGroups } from './algolia-search.ts';
+export type { SearchRecord, RankedHit, CustomRankingRule } from './algolia-search.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/world-core';
+import { ALGOLIA_RATE_BUDGET as RATE_BUDGET } from './algolia-budget.ts';
+export const pack: TwinPack = {
+  vendor: 'algolia',
+  // The SAME object algolia-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-algolia',
+  resources: ['index', 'record', 'synonym', 'settings'],
+  specSource: 'algolia-conformance.ts (endpoint/resource inventory grounded LIVE against the installed algoliasearch SDK, driven end-to-end with a throwaway local server before this handler was written — see spec-sources.json)',
+  description: 'Algolia hosted-search twin — index list/delete/clear, record CRUD (add/replace/partial/delete/batch), REAL tokenize+typo+ranking search engine with REAL filter/facetFilters/facet-count evaluation, customRanking, basic synonym expansion, settings get/set, host-tolerant router. Kernel-backed. No mirror (API-first vendor).',
+  // Adoption, all in the pack's one home (descriptor-first back-migration, adding-a-twin.md §3, 2026-08-31; the bare
+  // `algolia` stem and the `algoliasearch` SDK name moved off the central maps unchanged). Stems:
+  // the bare ALGOLIA_* shape and the ALGOLIA_WRITE_* write-key half real apps split out.
+  adoption: {
+    // Algolia's own Python client - same distribution name as the npm one, different registry.
+    pypi: ['algoliasearch'],
+    sdks: ['algoliasearch'], envStems: ['ALGOLIA', 'ALGOLIAWRITE'],
+  },
+  // No `browserRouting`: unlike every other pack (which has ONE fixed absolute API host to strip
+  // for the zero-edit dev proxy — even supabase's per-PROJECT data API omits it in favor of its
+  // static management-API host), Algolia has NO fixed host at all — every real host is
+  // `{appId}.algolia.net`-shaped, with the caller's OWN appId baked directly into the domain. A
+  // literal `{appId}` placeholder is not a stripeable absolute host, so `browserRouting` is
+  // correctly omitted here rather than populated with a non-matching placeholder.
+  // INTERCEPTION RULING — hostsNone, the pack's own home for it: per-app-ID host scheme
+  // ({appId}.algolia.net / {appId}-dsn.algolia.net / {appId}-N.algolianet.com, see the pack
+  // README §Host tolerance) — no fixed host list to match; the host-tolerant twin is wired by
+  // explicit client host config.
+  hostsNone:
+    "per-app-ID host scheme ({appId}.algolia.net / {appId}-dsn.algolia.net / {appId}-N.algolianet.com, see the pack README §Host tolerance) — no fixed host list to match; the host-tolerant twin is wired by explicit client host config",
+};