@voyant-travel/catalog 0.117.2

package/dist/booking-engine/quote-enricher.test.js

@@ -0,0 +1,138 @@
+/**
+ * Focused tests for the `contentEnricher` hook on `quoteEntity`. The
+ * full quote path needs a real DB — these tests stub the drizzle
+ * insert chain just enough to verify the hook's call contract:
+ *   - Called with the right input when wired and live-resolve succeeds.
+ *   - Result attached to the quote response as `shape`.
+ *   - Errors swallowed + reported via `onEnricherError` instead of
+ *     failing the quote.
+ *   - Skipped when the entity is not available (failed live-resolve).
+ */
+import { describe, expect, it, vi } from "vitest";
+import { DEFAULT_PAX_BANDS, defaultBookingFields, defaultDraftShapeFlags, defaultTravelerFields, } from "./draft-shape.js";
+import { quoteEntity } from "./quote.js";
+import { createSourceAdapterRegistry } from "./registry.js";
+function makeStubDb() {
+    // Mirrors enough of the drizzle chain for `.insert(...).values(...).returning()`.
+    return {
+        insert() {
+            return {
+                values(_v) {
+                    return {
+                        async returning() {
+                            return [{ id: "cquo_x" }];
+                        },
+                    };
+                },
+            };
+        },
+    };
+}
+function makeAdapter(liveResolve) {
+    return {
+        kind: "stub",
+        capabilities: {
+            verticals: ["products"],
+            supportsLiveResolution: true,
+            supportsDriftDetection: false,
+            supportsBookingForwarding: false,
+            postBookOperations: [],
+        },
+        connect: async () => undefined,
+        pause: async () => undefined,
+        disconnect: async () => undefined,
+        getState: async () => "active",
+        discover: async () => ({ projections: [], next_cursor: undefined }),
+        liveResolve,
+    };
+}
+const baseRequest = {
+    entityModule: "products",
+    entityId: "prod_abc",
+    sourceKind: "stub",
+    scope: { locale: "en-GB", audience: "customer", market: "GB", currency: "GBP" },
+    adapterContext: { connection_id: "conn_1" },
+};
+const okLiveResolve = async (_ctx, _req) => ({
+    values: { prod_abc: { priceCents: 10000, currency: "GBP" } },
+});
+const failLiveResolve = async (_ctx, _req) => ({
+    values: {},
+    failed: { prod_abc: "not_found" },
+});
+const sampleShape = {
+    ...defaultDraftShapeFlags(),
+    paxBands: DEFAULT_PAX_BANDS,
+    paxBandsAllowedTotal: { min: 1, max: 8 },
+    travelerFields: defaultTravelerFields(),
+    bookingFields: defaultBookingFields(),
+    paymentIntents: ["hold", "card"],
+};
+describe("quoteEntity — contentEnricher hook", () => {
+    it("attaches the enricher's BookingDraftShape to the quote result", async () => {
+        const enricher = vi.fn(async () => sampleShape);
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(okLiveResolve));
+        const result = await quoteEntity(makeStubDb(), { registry, contentEnricher: enricher }, baseRequest);
+        expect(result.available).toBe(true);
+        expect(result.shape).toEqual(sampleShape);
+        expect(enricher).toHaveBeenCalledTimes(1);
+    });
+    it("threads entity identity + scope into the enricher input", async () => {
+        let captured = null;
+        const enricher = async (input) => {
+            captured = input;
+            return sampleShape;
+        };
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(okLiveResolve));
+        await quoteEntity(makeStubDb(), { registry, contentEnricher: enricher }, baseRequest);
+        expect(captured).not.toBeNull();
+        expect(captured.entityModule).toBe("products");
+        expect(captured.entityId).toBe("prod_abc");
+        expect(captured.sourceKind).toBe("stub");
+        expect(captured.scope.locale).toBe("en-GB");
+        expect(captured.scope.market).toBe("GB");
+        expect(captured.scope.currency).toBe("GBP");
+    });
+    it("omits shape when no enricher is wired (today's default)", async () => {
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(okLiveResolve));
+        const result = await quoteEntity(makeStubDb(), { registry }, baseRequest);
+        expect(result.shape).toBeUndefined();
+    });
+    it("skips the enricher when live-resolve fails (entity not available)", async () => {
+        const enricher = vi.fn(async () => sampleShape);
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(failLiveResolve));
+        const result = await quoteEntity(makeStubDb(), { registry, contentEnricher: enricher }, baseRequest);
+        expect(result.available).toBe(false);
+        expect(result.shape).toBeUndefined();
+        expect(enricher).not.toHaveBeenCalled();
+    });
+    it("swallows enricher errors and reports via onEnricherError — quote still succeeds", async () => {
+        const enricher = async () => {
+            throw new Error("content-service unreachable");
+        };
+        const errors = [];
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(okLiveResolve));
+        const result = await quoteEntity(makeStubDb(), { registry, contentEnricher: enricher, onEnricherError: (e) => errors.push(e) }, baseRequest);
+        // Quote succeeded — the enricher error didn't block.
+        expect(result.available).toBe(true);
+        expect(result.shape).toBeUndefined();
+        // Diagnostic surfaced.
+        expect(errors).toHaveLength(1);
+        expect(errors[0]?.entityModule).toBe("products");
+        expect(errors[0]?.entityId).toBe("prod_abc");
+        expect(errors[0]?.reason).toContain("content-service unreachable");
+    });
+    it("returns shape: undefined when the enricher returns null (entity has no content)", async () => {
+        const enricher = async () => null;
+        const registry = createSourceAdapterRegistry();
+        registry.register(makeAdapter(okLiveResolve));
+        const result = await quoteEntity(makeStubDb(), { registry, contentEnricher: enricher }, baseRequest);
+        expect(result.available).toBe(true);
+        expect(result.shape).toBeUndefined();
+    });
+});

package/dist/booking-engine/quote.d.ts

@@ -0,0 +1,163 @@
+/**
+ * `quoteEntity` — the first step in the booking engine lifecycle.
+ *
+ * Asks the registered adapter "is this row still bookable, and at what
+ * price right now?", persists the answer in `catalog_quotes` with an
+ * expiry, and returns a stable `quoteId` the subsequent `bookEntity`
+ * call can validate against.
+ *
+ * Quotes are short-lived (default TTL: 10 minutes) and not de-duped.
+ * Re-quoting the same row produces a new quote row so the audit trail
+ * shows every quote attempt.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { SourceAdapterContext } from "../adapter/contract.js";
+import type { PricingBasis } from "../snapshot/schema.js";
+import type { BookingDraftShape } from "./draft-shape.js";
+import type { OwnedBookingHandlerRegistry } from "./owned-handler.js";
+import type { PromotionEvaluationInput, PromotionEvaluationOutput } from "./promotions-contract.js";
+import type { SourceAdapterRegistry } from "./registry.js";
+/** Default time-to-live for a quote. */
+export declare const DEFAULT_QUOTE_TTL_MS: number;
+export interface QuoteScope {
+    locale: string;
+    audience: string;
+    market: string;
+    currency?: string;
+}
+export interface QuoteEntityRequest {
+    /** The catalog row to quote. */
+    entityModule: string;
+    entityId: string;
+    /** Source pointer, read from the row's provenance. */
+    sourceKind: string;
+    sourceProvider?: string;
+    sourceConnectionId?: string;
+    sourceRef?: string;
+    /** Variant scope for the quote. */
+    scope: QuoteScope;
+    /** Vertical-specific parameters echoed to the adapter (date range, pax, etc.). */
+    parameters?: Record<string, unknown>;
+    /** Override the TTL (rare — defaults to `DEFAULT_QUOTE_TTL_MS`). */
+    ttlMs?: number;
+    /** Adapter context (connection_id, credentials, correlation_id). */
+    adapterContext: SourceAdapterContext;
+}
+export interface QuoteEntityResult {
+    quoteId: string;
+    quotedAt: Date;
+    expiresAt: Date;
+    available: boolean;
+    invalidReason?: string;
+    pricing?: PricingBasis;
+    upstreamPayload?: Record<string, unknown>;
+    /**
+     * The journey wizard descriptor — populated when
+     * `deps.contentEnricher` is wired and the entity is sourced. Tells
+     * the wizard which steps + sub-steps to render. Per
+     * `docs/architecture/booking-journey-architecture.md` §3, this is
+     * returned alongside the quote so the journey can render the
+     * correct shape without a follow-up call.
+     *
+     * Undefined when no enricher is wired (today's behavior — the
+     * journey hardcodes a minimal shape until templates wire content).
+     */
+    shape?: BookingDraftShape;
+}
+/**
+ * Input the content enricher receives — quote + scope + parameters.
+ * The enricher reads cached content for the entity and projects a
+ * `BookingDraftShape` that drives the wizard. Verticals compose their
+ * `build*DraftShape` builders into one enricher routed by
+ * `entity_module`.
+ */
+export interface QuoteContentEnrichmentInput {
+    db: AnyDrizzleDb;
+    entityModule: string;
+    entityId: string;
+    sourceKind: string;
+    sourceConnectionId?: string;
+    sourceRef?: string;
+    scope: QuoteScope;
+    parameters?: Record<string, unknown>;
+    adapterContext: SourceAdapterContext;
+}
+/**
+ * Hook called by `quoteEntity` after the live-resolve step succeeds.
+ * Receives entity identity + scope; returns a `BookingDraftShape` (or
+ * null when content is unavailable / the entity is owned and the
+ * enricher chooses not to surface a shape).
+ *
+ * Templates compose this from per-vertical content services, e.g.:
+ *
+ *   const enricher: QuoteContentEnricher = async (input) => {
+ *     const content = await readContentByModule(input)
+ *     return content ? buildDraftShape(input.entityModule, content, input.scope) : null
+ *   }
+ */
+export type QuoteContentEnricher = (input: QuoteContentEnrichmentInput) => Promise<BookingDraftShape | null>;
+export interface QuoteEntityDeps {
+    registry: SourceAdapterRegistry;
+    /**
+     * Owned-arm dispatch — when set and the request's source kind is
+     * `"owned"`, the engine routes to a handler keyed by
+     * `entityModule` instead of the SourceAdapterRegistry. Per
+     * booking-journey-architecture §6.
+     *
+     * Templates that ship owned products MUST wire this; templates
+     * that only proxy sourced rows can leave it undefined and the
+     * engine falls through to the legacy adapter path.
+     */
+    ownedHandlers?: OwnedBookingHandlerRegistry;
+    /**
+     * Optional content-aware enricher. When wired, called after the
+     * adapter's `liveResolve` step succeeds; the returned
+     * `BookingDraftShape` is attached to the quote result so the
+     * journey wizard can render the correct shape without a follow-up
+     * call.
+     *
+     * When not wired (today's default), the quote response omits
+     * `shape` and the journey falls back to its hardcoded minimal
+     * descriptor.
+     *
+     * Errors from the enricher are caught and logged via
+     * `onEnricherError` (defaults to silent) — they MUST NOT fail the
+     * quote because the wizard can render the minimal shape on its
+     * own.
+     */
+    contentEnricher?: QuoteContentEnricher;
+    /** Optional sink for enricher errors. */
+    onEnricherError?: (event: {
+        entityModule: string;
+        entityId: string;
+        reason: string;
+    }) => void;
+    /**
+     * Optional promotion-evaluator hook. When wired, called after the
+     * adapter's `liveResolve` succeeds (only for `entity_module ==
+     * "products"` in v1). Discounts apply to `pricing.base_amount`
+     * pre-tax; the operator starter's `applyOperatorTaxToQuoteResult`
+     * step downstream recomputes taxes against the new base.
+     *
+     * When the customer-supplied code fails validation, the engine
+     * surfaces the result as a `code_*` `invalidReason` on the quote
+     * (`code_not_found`, `code_expired`, `code_not_yet_valid`,
+     * `code_not_applicable`). Auto offers do NOT apply when a bad code
+     * is supplied — the quote is short-circuited to unavailable so the
+     * customer gets clear feedback.
+     *
+     * Per `docs/architecture/promotions-architecture.md` §3.6 + §7.1.
+     */
+    evaluatePromotions?: (input: PromotionEvaluationInput) => Promise<PromotionEvaluationOutput>;
+}
+/**
+ * Quote the row. Calls `adapter.liveResolve` (sourced) or interprets
+ * `available = true` from a stub (owned, when no adapter is registered
+ * for the `"owned"` kind in this MVP cut).
+ *
+ * Throws `NoAdapterRegisteredError` if the registry has no entry for
+ * `sourceKind`. Persists the quote either way — a `failed` lookup is
+ * still recorded so subsequent diagnostics can see the attempt.
+ */
+export declare function quoteEntity(db: AnyDrizzleDb, deps: QuoteEntityDeps, request: QuoteEntityRequest): Promise<QuoteEntityResult>;
+//# sourceMappingURL=quote.d.ts.map

package/dist/booking-engine/quote.d.ts.map

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

package/dist/booking-engine/quote.js

@@ -0,0 +1,259 @@
+/**
+ * `quoteEntity` — the first step in the booking engine lifecycle.
+ *
+ * Asks the registered adapter "is this row still bookable, and at what
+ * price right now?", persists the answer in `catalog_quotes` with an
+ * expiry, and returns a stable `quoteId` the subsequent `bookEntity`
+ * call can validate against.
+ *
+ * Quotes are short-lived (default TTL: 10 minutes) and not de-duped.
+ * Re-quoting the same row produces a new quote row so the audit trail
+ * shows every quote attempt.
+ */
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { OWNED_SOURCE_KIND } from "./owned-handler.js";
+import { catalogQuotesTable } from "./schema.js";
+/** Default time-to-live for a quote. */
+export const DEFAULT_QUOTE_TTL_MS = 10 * 60 * 1000;
+/**
+ * Quote the row. Calls `adapter.liveResolve` (sourced) or interprets
+ * `available = true` from a stub (owned, when no adapter is registered
+ * for the `"owned"` kind in this MVP cut).
+ *
+ * Throws `NoAdapterRegisteredError` if the registry has no entry for
+ * `sourceKind`. Persists the quote either way — a `failed` lookup is
+ * still recorded so subsequent diagnostics can see the attempt.
+ */
+export async function quoteEntity(db, deps, request) {
+    const ttlMs = request.ttlMs ?? DEFAULT_QUOTE_TTL_MS;
+    const quotedAt = new Date();
+    const expiresAt = new Date(quotedAt.getTime() + ttlMs);
+    // Two dispatch arms:
+    //   - Owned: handler registry keyed by entity_module. Returns a
+    //     ComputeQuoteResult directly — pricing, shape, availability.
+    //   - Sourced: SourceAdapterRegistry keyed by connection_id (with
+    //     a kind-only fallback for legacy single-connection-per-kind).
+    let available;
+    let failedReason;
+    let pricing;
+    let upstreamPayload;
+    let ownedShape;
+    if (request.sourceKind === OWNED_SOURCE_KIND && deps.ownedHandlers) {
+        const handler = deps.ownedHandlers.resolveOrThrow(request.entityModule);
+        const result = await handler.computeQuote({ db, adapterContext: request.adapterContext }, {
+            entityModule: request.entityModule,
+            entityId: request.entityId,
+            scope: request.scope,
+            parameters: request.parameters,
+            draft: request.parameters?.draft,
+        });
+        available = result.available;
+        failedReason = result.invalidReason;
+        pricing = result.pricing;
+        upstreamPayload = result.upstreamPayload;
+        ownedShape = result.shape;
+    }
+    else {
+        const adapter = request.sourceConnectionId
+            ? (deps.registry.resolveByConnection(request.sourceConnectionId) ??
+                deps.registry.resolveOrThrow(request.sourceKind))
+            : deps.registry.resolveOrThrow(request.sourceKind);
+        let liveResolve = { values: {} };
+        if (adapter.liveResolve) {
+            liveResolve = await adapter.liveResolve(request.adapterContext, {
+                ids: [request.entityId],
+                scope: {
+                    locale: request.scope.locale,
+                    audience: request.scope.audience,
+                    market: request.scope.market,
+                    currency: request.scope.currency,
+                },
+                parameters: request.parameters,
+            });
+        }
+        failedReason = liveResolve.failed?.[request.entityId];
+        const liveValues = liveResolve.values[request.entityId];
+        available = !failedReason && liveValues !== undefined;
+        pricing = available ? liveValuesToPricing(liveValues, request.scope.currency) : undefined;
+        upstreamPayload = liveValues;
+    }
+    // Promotion evaluation — runs only for the products vertical in v1
+    // (other verticals would need their own bridge to the evaluator).
+    // Discounts apply to `pricing.base_amount` pre-tax; operator starter
+    // tax recompute downstream picks up the new base.
+    let appliedOffers;
+    if (deps.evaluatePromotions && available && pricing && request.entityModule === "products") {
+        const params = request.parameters;
+        const promotionCode = readString(params?.promotionCode);
+        // Read `paxCount` first — `engineParametersFromDraft` (in this file's
+        // sibling `routes.ts`) writes the summed traveler count under that key
+        // when a draft drives the quote, and the products owned-handler reads
+        // `paxCount` too. Fall back to `pax` for callers that build parameters
+        // directly without going through the draft pipeline.
+        const pax = readNumber(params?.paxCount) ?? readNumber(params?.pax);
+        const offerEval = await deps.evaluatePromotions({
+            productId: request.entityId,
+            slice: { audience: narrowAudience(request.scope.audience), market: request.scope.market },
+            pax,
+            date: quotedAt,
+            code: promotionCode,
+            basePriceCents: Math.round(pricing.base_amount),
+            baseCurrency: pricing.currency,
+        });
+        const codeStatus = offerEval.codeStatus;
+        if (codeStatus && codeStatus.kind !== "code_valid") {
+            // Customer-supplied code failed validation. Surface as a quote-
+            // level invalidReason and short-circuit; auto offers don't apply
+            // either, so the customer gets unambiguous feedback.
+            available = false;
+            failedReason = codeStatusToReason(codeStatus);
+        }
+        else if (offerEval.applied.length > 0) {
+            // Subtract the discount from base_amount in cents. The operator
+            // template's `applyOperatorTaxToQuoteResult` step downstream
+            // sees the new base and recomputes taxes accordingly.
+            pricing.base_amount = Math.round(pricing.base_amount) - offerEval.total.discountAppliedCents;
+            pricing.appliedOffers = offerEval.applied;
+            appliedOffers = offerEval.applied;
+            // Invalidate any taxes / breakdown that the source (sourced
+            // adapter or owned handler) computed against the un-discounted
+            // base — they're stale now. Setting `taxes = 0` and clearing
+            // `breakdown` is the explicit signal the operator-side transform
+            // (`applyOperatorTaxToQuoteResult`) reads to recompute. Without
+            // this, the API serializer would echo a breakdown total that
+            // doesn't match `appliedOffers`.
+            pricing.taxes = 0;
+            pricing.breakdown = undefined;
+        }
+    }
+    const quoteId = newId("catalog_quotes");
+    const inserted = (await db
+        .insert(catalogQuotesTable)
+        .values({
+        id: quoteId,
+        entity_module: request.entityModule,
+        entity_id: request.entityId,
+        source_kind: request.sourceKind,
+        source_provider: request.sourceProvider,
+        source_connection_id: request.sourceConnectionId,
+        source_ref: request.sourceRef,
+        available,
+        invalid_reason: failedReason,
+        locale: request.scope.locale,
+        audience: request.scope.audience,
+        market: request.scope.market,
+        currency: request.scope.currency,
+        pricing_base_amount: pricing?.base_amount != null ? String(pricing.base_amount) : undefined,
+        pricing_taxes: pricing?.taxes != null ? String(pricing.taxes) : undefined,
+        pricing_fees: pricing?.fees != null ? String(pricing.fees) : undefined,
+        pricing_surcharges: pricing?.surcharges != null ? String(pricing.surcharges) : undefined,
+        pricing_currency: pricing?.currency,
+        pricing_breakdown: pricing?.breakdown,
+        pricing_applied_offers: appliedOffers,
+        upstream_payload: upstreamPayload ?? null,
+        created_at: quotedAt,
+        expires_at: expiresAt,
+    })
+        .returning());
+    if (!inserted[0])
+        throw new Error("quoteEntity: insert returned no rows");
+    // Optional content enrichment — per booking-journey-architecture
+    // §3, the quote response carries a BookingDraftShape descriptor
+    // when the engine has the content in front of it. When the hook
+    // throws, we swallow the error (the wizard's minimal-shape fallback
+    // covers it) but surface via onEnricherError for diagnostics.
+    //
+    // Owned handlers are authoritative for their own products — when
+    // they returned a shape, the enricher is not consulted.
+    let shape = ownedShape;
+    if (!shape && deps.contentEnricher && available) {
+        try {
+            const enriched = await deps.contentEnricher({
+                db,
+                entityModule: request.entityModule,
+                entityId: request.entityId,
+                sourceKind: request.sourceKind,
+                sourceConnectionId: request.sourceConnectionId,
+                sourceRef: request.sourceRef,
+                scope: request.scope,
+                parameters: request.parameters,
+                adapterContext: request.adapterContext,
+            });
+            shape = enriched ?? undefined;
+        }
+        catch (err) {
+            deps.onEnricherError?.({
+                entityModule: request.entityModule,
+                entityId: request.entityId,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        quoteId,
+        quotedAt,
+        expiresAt,
+        available,
+        invalidReason: failedReason,
+        pricing,
+        upstreamPayload,
+        shape,
+    };
+}
+/**
+ * Convert an adapter's per-entity `liveResolve` value into the catalog
+ * plane's `PricingBasis` shape. The adapter's payload is opaque, so this
+ * helper looks for the conventional fields (`priceCents`, `currency`,
+ * `taxesCents`, `feesCents`, `surchargesCents`) and falls back to a
+ * single-line "all in base_amount" basis when only a price is provided.
+ */
+function liveValuesToPricing(values, fallbackCurrency) {
+    if (!values)
+        return undefined;
+    const priceCents = readNumber(values.priceCents) ?? readNumber(values.price);
+    if (priceCents == null)
+        return undefined;
+    const currency = readString(values.currency) ?? fallbackCurrency;
+    if (!currency)
+        return undefined;
+    return {
+        base_amount: priceCents,
+        taxes: readNumber(values.taxesCents) ?? 0,
+        fees: readNumber(values.feesCents) ?? 0,
+        surcharges: readNumber(values.surchargesCents) ?? 0,
+        currency,
+    };
+}
+function readNumber(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string") {
+        const n = Number.parseFloat(v);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+function readString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+const KNOWN_AUDIENCES = new Set(["staff", "customer", "partner", "supplier"]);
+/**
+ * Narrow the QuoteScope.audience (typed `string` for legacy reasons)
+ * to the evaluator's `Visibility` enum. Unknown audiences fall back to
+ * `"customer"` — the most permissive storefront default; exotic audience
+ * tokens (e.g., `"staff-admin"`) get no special treatment beyond visibility
+ * rules the offer's scope already encodes.
+ */
+function narrowAudience(audience) {
+    if (audience === "staff-admin")
+        return "staff";
+    return KNOWN_AUDIENCES.has(audience) ? audience : "customer";
+}
+/**
+ * Map a non-valid `CodeStatus` to a quote `invalidReason` string. The
+ * `code_valid` case is filtered upstream so this only sees the failure
+ * variants.
+ */
+function codeStatusToReason(codeStatus) {
+    return codeStatus.kind;
+}

package/dist/booking-engine/registry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `SourceAdapterRegistry` — process-local map keyed by `connection_id` that
+ * the booking engine and channel-push pipeline consult when dispatching a
+ * quote / book / cancel / push call.
+ *
+ * Templates wire the registry at process start, registering one adapter
+ * instance per upstream connection. Two connections of the same kind
+ * (e.g. TUI dev + TUI prod, or two different Voyant Connect peers) get
+ * two registry entries with two distinct `connection_id`s — different
+ * credentials, different rate buckets, different `channel_id` mappings.
+ *
+ * `kind` remains a useful secondary index — "list all adapters of this
+ * kind" supports rotate-to-next-available policies and admin debug
+ * surfaces. But routing dispatches by `connection_id` because that's
+ * what the data carries (provenance.source_connection_id on sourced
+ * rows, channels.id on outbound mappings).
+ *
+ * Per channel-push-architecture §3.1 and catalog-booking-engine §4.
+ */
+import type { SourceAdapter } from "../adapter/contract.js";
+/**
+ * One registry entry. `connectionId` is the typed-id key (the row in
+ * whichever table holds the connection record — `channels` for outbound,
+ * the catalog plane's connection store for inbound). For adapters with
+ * no upstream connection record (e.g. the demo adapter at boot), pass a
+ * stable synthetic id like `"default:<kind>"`.
+ */
+export interface RegisteredAdapter {
+    connectionId: string;
+    adapter: SourceAdapter;
+}
+export interface SourceAdapterRegistry {
+    /**
+     * Register an adapter under a connection id. The connection id is the
+     * primary key — re-registering the same connection id replaces the
+     * previous adapter (used at hot-reload time). Production registrations
+     * happen once at process start, one entry per upstream connection.
+     */
+    register(connectionId: string, adapter: SourceAdapter): void;
+    /**
+     * Backward-compat overload — register an adapter without an explicit
+     * connection id. Stored under the synthetic id `"default:<kind>"`.
+     * Use this for single-deployment adapters where there's no separate
+     * connection record (e.g. demo adapters, single-tenant integrations).
+     * New code paths that route per-connection should prefer the explicit
+     * `register(connectionId, adapter)` form.
+     */
+    register(adapter: SourceAdapter): void;
+    /**
+     * Resolve by connection id. Hot path for the booking engine (sourced
+     * bookings) and the channel-push pipeline (outbound dispatches).
+     * Returns `undefined` when no adapter is registered.
+     */
+    resolveByConnection(connectionId: string): SourceAdapter | undefined;
+    /** Like `resolveByConnection` but throws `NoAdapterRegisteredError` on miss. */
+    resolveByConnectionOrThrow(connectionId: string): SourceAdapter;
+    /**
+     * Resolve by source kind. Returns the FIRST adapter registered for this
+     * kind. Useful for legacy dispatch paths that don't yet thread a
+     * connection id, and for the common single-connection-per-kind case.
+     * New code that supports multiple connections per kind should use
+     * `byKind` to pick deliberately.
+     */
+    resolveOrThrow(sourceKind: string): SourceAdapter;
+    /**
+     * Returns every adapter registered for this kind, paired with its
+     * connection id. Order is registration order. Use for "rotate to next
+     * available connection" policies and admin debug surfaces.
+     */
+    byKind(sourceKind: string): ReadonlyArray<RegisteredAdapter>;
+    /** Returns the registered connection ids. */
+    connections(): ReadonlyArray<string>;
+    /** Returns the registered source kinds. */
+    kinds(): ReadonlyArray<string>;
+    /** True iff a connection id is registered. */
+    has(connectionId: string): boolean;
+    /** True iff at least one adapter of this kind is registered. */
+    hasKind(sourceKind: string): boolean;
+}
+/**
+ * Construct a fresh registry. Templates create one at process start and
+ * pass it to the booking-engine route handlers + channel-push wiring.
+ */
+export declare function createSourceAdapterRegistry(): SourceAdapterRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/booking-engine/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/booking-engine/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAI3D;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,aAAa,CAAA;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAE5D;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAEtC;;;;OAIG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAA;IAEpE,gFAAgF;IAChF,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAAA;IAE/D;;;;;;OAMG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAA;IAEjD;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAA;IAE5D,6CAA6C;IAC7C,WAAW,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IAEpC,2CAA2C;IAC3C,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IAE9B,8CAA8C;IAC9C,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAA;IAElC,gEAAgE;IAChE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,CA6FnE"}