@voyant-travel/catalog 0.117.2

package/dist/indexer/typesense-search-query.d.ts

@@ -0,0 +1,31 @@
+import type { FieldPolicyRegistry } from "../contract.js";
+import type { IndexerSlice, SearchRequest } from "./contract.js";
+export interface TypesenseSearchQuery {
+    q: string;
+    query_by: string;
+    filter_by?: string;
+    facet_by?: string;
+    sort_by?: string;
+    per_page?: number;
+    page?: number;
+    vector_query?: string;
+    prefix?: boolean;
+    exclude_fields?: string;
+    drop_tokens_threshold?: number;
+}
+/**
+ * Translates the catalog plane's `SearchRequest` into a Typesense query.
+ * Converts the filter expression tree, the audience-scoped query, and the
+ * pagination shape.
+ */
+export declare function buildSearchQuery(request: SearchRequest, registry: FieldPolicyRegistry, slice?: IndexerSlice): TypesenseSearchQuery;
+/**
+ * Returns the policy-owned default text fields for Typesense keyword search.
+ * Hosted Typesense-compatible proxies can use this as their server-side
+ * fallback when callers omit `query_by`, avoiding client-side schema scraping.
+ */
+export declare function buildDefaultTypesenseSearchFields(registry: FieldPolicyRegistry, slice?: IndexerSlice): string[];
+export declare function buildDefaultTypesenseQueryBy(registry: FieldPolicyRegistry, slice?: IndexerSlice): string;
+export declare function typesenseTypeForField(name: string, isList: boolean): "string" | "string[]" | "int32" | "int64" | "float" | "bool" | "object" | "float[]";
+export declare function isTypesenseSortableStringField(field: string): boolean;
+//# sourceMappingURL=typesense-search-query.d.ts.map

package/dist/indexer/typesense-search-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense-search-query.d.ts","sourceRoot":"","sources":["../../src/indexer/typesense-search-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAgB,aAAa,EAAoB,MAAM,eAAe,CAAA;AAEhG,MAAM,WAAW,oBAAoB;IACnC,CAAC,EAAE,MAAM,CAAA;IACT,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,CAAC,EAAE,YAAY,GACnB,oBAAoB,CAsDtB;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,CAAC,EAAE,YAAY,GACnB,MAAM,EAAE,CAIV;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,CAAC,EAAE,YAAY,GACnB,MAAM,CAGR;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,GACd,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAWrF;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/indexer/typesense-search-query.js

@@ -0,0 +1,185 @@
+/**
+ * Translates the catalog plane's `SearchRequest` into a Typesense query.
+ * Converts the filter expression tree, the audience-scoped query, and the
+ * pagination shape.
+ */
+export function buildSearchQuery(request, registry, slice) {
+    const perPage = request.pagination?.limit ?? 20;
+    // Cursor doubles as the 1-indexed page number for Typesense's `page`
+    // parameter. Callers wanting a different cursor strategy (e.g. opaque
+    // cursor for streaming results) write a different adapter.
+    const page = parsePageCursor(request.pagination?.cursor) ?? 1;
+    const query = {
+        q: request.query.length > 0 ? request.query : "*",
+        query_by: buildDefaultTypesenseQueryBy(registry, slice),
+        per_page: perPage,
+        page,
+        // Strip the vector field from response payloads. At e.g. 3072-dim that's
+        // roughly 12 KB per hit of float-array noise the caller never reads.
+        exclude_fields: "text_embedding,embedding_model_id",
+    };
+    if (request.filters && request.filters.length > 0) {
+        query.filter_by = serializeFilters(request.filters);
+    }
+    if (request.facets && request.facets.length > 0) {
+        query.facet_by = request.facets.map((f) => normalizeTypesenseField(f.field)).join(",");
+    }
+    const sortBy = resolveTypesenseSortBy(request.sort, registry, slice);
+    if (sortBy) {
+        query.sort_by = sortBy;
+    }
+    // Hybrid / semantic mode: attach the vector query if an embedding was
+    // provided. The actual embedding generation for the query string lives in
+    // the search/semantic helper (Phase 2); this adapter just relays it.
+    if ((request.mode === "hybrid" || request.mode === "semantic") && request.query_embedding) {
+        // Ground the ANN search against a candidate pool larger than `per_page`
+        // so caller-side pagination has actual results to walk through. Typesense
+        // resolves `max(k, per_page)` per the docs, so we lift the floor.
+        const k = Math.max(perPage * 10, 100);
+        const vectorOpts = [`k:${k}`];
+        if (request.alpha != null)
+            vectorOpts.push(`alpha:${request.alpha}`);
+        if (request.distance_threshold != null) {
+            vectorOpts.push(`distance_threshold:${request.distance_threshold}`);
+        }
+        query.vector_query = `text_embedding:([${request.query_embedding.join(",")}], ${vectorOpts.join(", ")})`;
+    }
+    // For multi-token hybrid queries, the docs warn that the default
+    // `drop_tokens_threshold` (10) leads to redundant internal keyword
+    // re-runs. Disable token drop entirely for short catalog queries.
+    if (request.mode === "hybrid" && request.query.length > 0) {
+        query.drop_tokens_threshold = 0;
+    }
+    return query;
+}
+/**
+ * Returns the policy-owned default text fields for Typesense keyword search.
+ * Hosted Typesense-compatible proxies can use this as their server-side
+ * fallback when callers omit `query_by`, avoiding client-side schema scraping.
+ */
+export function buildDefaultTypesenseSearchFields(registry, slice) {
+    return registry.policies
+        .filter((policy) => isDefaultSearchablePolicy(policy, slice))
+        .map((policy) => normalizeTypesenseField(policy.path));
+}
+export function buildDefaultTypesenseQueryBy(registry, slice) {
+    const fields = buildDefaultTypesenseSearchFields(registry, slice);
+    return fields.length > 0 ? fields.join(",") : "title";
+}
+export function typesenseTypeForField(name, isList) {
+    if (isList)
+        return "string[]";
+    if (BOOLEAN_FIELD_NAMES.has(name) || /^(has|is)[A-Z]/.test(name))
+        return "bool";
+    if (FLOAT_FIELD_NAMES.has(name) || /(Latitude|Longitude)$/.test(name))
+        return "float";
+    if (INTEGER_FIELD_NAMES.has(name) ||
+        INTEGER_FIELD_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
+        return "int64";
+    }
+    return "string";
+}
+export function isTypesenseSortableStringField(field) {
+    return SORTABLE_STRING_FIELD_NAMES.has(field);
+}
+function resolveTypesenseSortBy(sort, registry, slice) {
+    if (!sort || sort === "relevance")
+        return undefined;
+    const fields = SORT_FIELDS[sort];
+    const field = fields.find((candidate) => isSortableField(candidate, registry, slice));
+    if (!field)
+        return undefined;
+    const direction = sort === "price-desc" || sort === "newest" ? "desc" : "asc";
+    return `${field}:${direction}`;
+}
+const SORT_FIELDS = {
+    "price-asc": ["priceFromAmountCents", "sellAmountCents"],
+    "price-desc": ["priceFromAmountCents", "sellAmountCents"],
+    "departure-asc": ["nextDepartureDate", "nextDepartureAt", "startDateEpochDays", "startDate"],
+    newest: ["publishedAt", "createdAt"],
+};
+function isSortableField(field, registry, slice) {
+    const policy = registry.resolve(field);
+    if (!policy)
+        return false;
+    if (!slice || slice.audience === "staff-admin")
+        return true;
+    return policy.visibility.includes(slice.audience);
+}
+function parsePageCursor(cursor) {
+    if (!cursor)
+        return undefined;
+    const n = Number(cursor);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+function serializeFilters(filters) {
+    return filters.map(serializeFilter).filter(Boolean).join(" && ");
+}
+function serializeFilter(filter) {
+    switch (filter.kind) {
+        case "eq":
+            return `${normalizeTypesenseField(filter.field)}:=${typeof filter.value === "string" ? `"${filter.value}"` : filter.value}`;
+        case "in":
+            return `${normalizeTypesenseField(filter.field)}:[${filter.values.map((v) => (typeof v === "string" ? `"${v}"` : v)).join(",")}]`;
+        case "range": {
+            const parts = [];
+            const field = normalizeTypesenseField(filter.field);
+            if (filter.gte != null)
+                parts.push(`${field}:>=${filter.gte}`);
+            if (filter.lte != null)
+                parts.push(`${field}:<=${filter.lte}`);
+            return parts.join(" && ");
+        }
+        case "and":
+            return filter.clauses.map(serializeFilter).join(" && ");
+        case "or":
+            return `(${filter.clauses.map(serializeFilter).join(" || ")})`;
+    }
+}
+function normalizeTypesenseField(field) {
+    return field.endsWith("[]") ? field.slice(0, -2) : field;
+}
+function isDefaultSearchablePolicy(policy, slice) {
+    if (policy.query !== "indexed-column")
+        return false;
+    if (policy.class !== "merchandisable" && policy.class !== "structural")
+        return false;
+    if (!isVisibleInSlice(policy.visibility, slice))
+        return false;
+    const field = normalizeTypesenseField(policy.path);
+    return isTextSearchableField(field) && !isNonSearchTextField(field);
+}
+function isVisibleInSlice(visibility, slice) {
+    if (!slice || slice.audience === "staff-admin")
+        return true;
+    return visibility.includes(slice.audience);
+}
+function isTextSearchableField(name) {
+    const type = typesenseTypeForField(name, false);
+    return type === "string" || type === "string[]";
+}
+function isNonSearchTextField(name) {
+    return SORTABLE_STRING_FIELD_NAMES.has(name) || NON_SEARCH_TEXT_FIELD_RE.test(name);
+}
+const BOOLEAN_FIELD_NAMES = new Set(["activated"]);
+const FLOAT_FIELD_NAMES = new Set(["latitude", "longitude"]);
+const INTEGER_FIELD_NAMES = new Set(["pax"]);
+const INTEGER_FIELD_SUFFIXES = [
+    "AmountCents",
+    "Percent",
+    "Count",
+    "Days",
+    "EpochDays",
+    "EpochMs",
+    "Minutes",
+    "Total",
+];
+const SORTABLE_STRING_FIELD_NAMES = new Set([
+    "createdAt",
+    "endDate",
+    "nextDepartureAt",
+    "nextDepartureDate",
+    "publishedAt",
+    "startDate",
+]);
+const NON_SEARCH_TEXT_FIELD_RE = /(?:^|\.)(?:.*Url|.*Uri|.*Href|.*Html|.*Markdown)$/i;

package/dist/indexer/typesense.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Native Typesense IndexerAdapter — the v1 default for catalog-plane search.
+ *
+ * Uses an injected `TypesenseClient` interface (mirroring the storage R2Bucket
+ * binding pattern) so the package doesn't take a hard dep on the Typesense
+ * HTTP SDK. Templates wire in the actual client.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.4.1 for design.
+ */
+import type { FieldPolicyRegistry } from "../contract.js";
+import type { DocumentEmitter, IndexerAdapter, IndexerSlice } from "./contract.js";
+import { type TypesenseSearchQuery } from "./typesense-search-query.js";
+export { buildDefaultTypesenseQueryBy, buildDefaultTypesenseSearchFields, buildSearchQuery, type TypesenseSearchQuery, } from "./typesense-search-query.js";
+/**
+ * Minimal interface the Typesense client must satisfy. Templates pass in
+ * the real `typesense` SDK client (or a custom HTTP wrapper) and the adapter
+ * uses only these methods.
+ */
+export interface TypesenseClient {
+    collections(name?: string): {
+        create(schema: TypesenseCollectionSchema): Promise<void>;
+        update(schema: Partial<TypesenseCollectionSchema>): Promise<void>;
+        delete(): Promise<void>;
+        retrieve(): Promise<TypesenseCollectionSchema>;
+        documents(): {
+            import(documents: unknown[], options?: {
+                action?: "upsert" | "create";
+            }): Promise<unknown>;
+            delete(query: {
+                filter_by: string;
+            }): Promise<unknown>;
+            search(query: TypesenseSearchQuery): Promise<TypesenseSearchResponse>;
+        };
+    };
+}
+export interface TypesenseFieldSchema {
+    name: string;
+    type: "string" | "string[]" | "int32" | "int64" | "float" | "bool" | "object" | "float[]";
+    facet?: boolean;
+    index?: boolean;
+    optional?: boolean;
+    sort?: boolean;
+    num_dim?: number;
+    vec_dist?: "cosine" | "ip";
+}
+export interface TypesenseCollectionSchema {
+    name: string;
+    fields: TypesenseFieldSchema[];
+    default_sorting_field?: string;
+    enable_nested_fields?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface TypesenseSearchHit {
+    document: Record<string, unknown>;
+    text_match: number;
+}
+export interface TypesenseSearchResponse {
+    hits: TypesenseSearchHit[];
+    found: number;
+    facet_counts?: Array<{
+        field_name: string;
+        counts: Array<{
+            value: string | number;
+            count: number;
+        }>;
+    }>;
+}
+export interface TypesenseIndexerOptions {
+    client: TypesenseClient;
+    /** Embedding dimension shipped by the configured EmbeddingProvider. */
+    vectorDimensions?: number | null;
+    /** Optional collection-name prefix (useful for multi-tenant single-cluster setups). */
+    collectionPrefix?: string;
+    /**
+     * Field-policy registries keyed by vertical. Seeds the per-vertical registry
+     * cache so a search-only process (the worker, which never runs
+     * `ensureCollection`) builds queries against the REAL policy — including
+     * numeric sort/filter fields. Without this, search falls back to
+     * `inferRegistryFromCollection`, which only knows string fields, so numeric
+     * sorts (e.g. `price-asc` → `priceFromAmountCents`) silently no-op.
+     */
+    registries?: ReadonlyMap<string, FieldPolicyRegistry>;
+}
+/**
+ * Returns the Typesense collection name for one variant slice. Stable across
+ * runs so existing collections survive deployments.
+ */
+export declare function collectionName(slice: IndexerSlice, prefix?: string): string;
+/**
+ * Builds a Typesense collection schema from the field-policy registry. Maps
+ * field-policy types onto Typesense field types using `query` + `class` from
+ * the policy.
+ */
+export declare function buildCollectionSchema(slice: IndexerSlice, registry: FieldPolicyRegistry, options?: {
+    vectorDimensions?: number | null;
+    collectionPrefix?: string;
+}): TypesenseCollectionSchema;
+export declare function createTypesenseIndexer(options: TypesenseIndexerOptions): IndexerAdapter;
+/**
+ * Helper for verticals that want to register a `DocumentEmitter` against
+ * this adapter. Currently a thin pass-through; reserved for future emitter
+ * registry extensions.
+ */
+export declare function attachEmitter<TSource>(emitter: DocumentEmitter<TSource>): DocumentEmitter<TSource>;
+//# sourceMappingURL=typesense.d.ts.map

package/dist/indexer/typesense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense.d.ts","sourceRoot":"","sources":["../../src/indexer/typesense.ts"],"names":[],"mappings":"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"}