@voyant-travel/distribution 0.109.8

package/dist/interface.js

@@ -0,0 +1,286 @@
+import { and, eq, ne } from "drizzle-orm";
+import { externalRefs } from "./external-refs/schema.js";
+import { channelReconciliationItems, channels, channelWebhookEvents } from "./schema.js";
+import { suppliers } from "./suppliers/schema.js";
+export function counterpartyRoleToEntityType(role) {
+    return role;
+}
+export function counterpartyEntityTypeToRole(entityType) {
+    if (entityType === "supplier" || entityType === "channel") {
+        return entityType;
+    }
+    return null;
+}
+export async function resolveCounterparty(db, input) {
+    const externalRef = input.externalRef
+        ? await findExternalRef(db, {
+            ...input.externalRef,
+            entityType: input.role ? counterpartyRoleToEntityType(input.role) : undefined,
+            entityId: input.id,
+        })
+        : null;
+    const role = input.role ?? (externalRef ? counterpartyEntityTypeToRole(externalRef.entityType) : null);
+    if (!role) {
+        return input.id
+            ? { status: "ambiguous", reason: "role_required_for_id_lookup" }
+            : { status: "not_found", reason: "external_ref_not_found" };
+    }
+    const id = input.id ?? externalRef?.entityId;
+    if (!id) {
+        return { status: "not_found", reason: "external_ref_not_found" };
+    }
+    const counterparty = await getCounterpartyByRole(db, role, id, externalRef);
+    if (!counterparty) {
+        return externalRef
+            ? { status: "not_found", reason: "counterparty_not_found" }
+            : {
+                status: "not_found",
+                reason: input.externalRef ? "external_ref_not_found" : "counterparty_not_found",
+            };
+    }
+    return { status: "resolved", counterparty };
+}
+export async function linkExternalReference(db, input) {
+    const resolved = await resolveCounterparty(db, input.counterparty);
+    if (resolved.status !== "resolved") {
+        return resolved;
+    }
+    const entityType = resolved.counterparty.entityType;
+    const namespace = input.namespace ?? "default";
+    if (input.isPrimary) {
+        await clearPrimaryExternalRefs(db, {
+            entityType,
+            entityId: resolved.counterparty.id,
+            sourceSystem: input.sourceSystem,
+        });
+    }
+    const existing = await findExternalRef(db, {
+        entityType,
+        entityId: resolved.counterparty.id,
+        sourceSystem: input.sourceSystem,
+        objectType: input.objectType,
+        namespace,
+        externalId: input.externalId,
+    });
+    if (existing) {
+        const [externalRef] = await db
+            .update(externalRefs)
+            .set({
+            externalParentId: input.externalParentId,
+            isPrimary: input.isPrimary,
+            status: input.status,
+            lastSyncedAt: toDate(input.lastSyncedAt),
+            metadata: input.metadata,
+            updatedAt: new Date(),
+        })
+            .where(eq(externalRefs.id, existing.id))
+            .returning();
+        return {
+            status: "linked",
+            counterparty: resolved.counterparty,
+            externalRef: externalRef ?? existing,
+            created: false,
+        };
+    }
+    const [externalRef] = await db
+        .insert(externalRefs)
+        .values({
+        entityType,
+        entityId: resolved.counterparty.id,
+        sourceSystem: input.sourceSystem,
+        objectType: input.objectType,
+        namespace,
+        externalId: input.externalId,
+        externalParentId: input.externalParentId ?? null,
+        isPrimary: input.isPrimary ?? false,
+        status: input.status ?? "active",
+        lastSyncedAt: toDate(input.lastSyncedAt),
+        metadata: input.metadata,
+    })
+        .returning();
+    if (!externalRef) {
+        throw new Error("Failed to link external reference");
+    }
+    return {
+        status: "linked",
+        counterparty: resolved.counterparty,
+        externalRef,
+        created: true,
+    };
+}
+export async function routeCounterpartyEvent(db, input) {
+    const resolved = await resolveCounterparty(db, input.counterparty);
+    if (resolved.status !== "resolved") {
+        return resolved;
+    }
+    if (resolved.counterparty.role === "supplier") {
+        return {
+            status: "routed",
+            counterparty: resolved.counterparty,
+            destination: "supplier_adapter",
+            event: null,
+        };
+    }
+    const [event] = await db
+        .insert(channelWebhookEvents)
+        .values({
+        channelId: resolved.counterparty.id,
+        eventType: input.eventType,
+        externalEventId: input.externalEventId ?? null,
+        payload: input.payload ?? {},
+        receivedAt: toDate(input.receivedAt) ?? new Date(),
+        status: input.status ?? "pending",
+    })
+        .returning();
+    if (!event) {
+        throw new Error("Failed to route channel event");
+    }
+    return {
+        status: "routed",
+        counterparty: resolved.counterparty,
+        destination: "channel_webhook_events",
+        event,
+    };
+}
+export async function reconcileCounterpartyActivity(db, input) {
+    const expected = input.counterparty ? await resolveCounterparty(db, input.counterparty) : null;
+    if (expected && expected.status !== "resolved") {
+        return expected;
+    }
+    const externalRef = await findExternalRef(db, input.externalRef);
+    if (!externalRef) {
+        if (!expected || !input.createExternalReference) {
+            return {
+                status: "unmatched",
+                reason: expected ? "external_ref_not_found" : "counterparty_required_to_create_link",
+            };
+        }
+        const linked = await linkExternalReference(db, {
+            counterparty: {
+                role: expected.counterparty.role,
+                id: expected.counterparty.id,
+            },
+            ...input.externalRef,
+            metadata: input.metadata,
+            lastSyncedAt: new Date(),
+        });
+        if (linked.status !== "linked") {
+            return linked;
+        }
+        return {
+            status: "linked",
+            counterparty: linked.counterparty,
+            externalRef: linked.externalRef,
+            reconciliationItem: await maybeCreateChannelReconciliationItem(db, linked.counterparty, input.channelReconciliation),
+        };
+    }
+    const actualRole = counterpartyEntityTypeToRole(externalRef.entityType);
+    if (!actualRole) {
+        return { status: "unsupported", entityType: externalRef.entityType };
+    }
+    const actual = await getCounterpartyByRole(db, actualRole, externalRef.entityId, externalRef);
+    if (!actual) {
+        return { status: "not_found", reason: "counterparty_not_found" };
+    }
+    if (expected &&
+        (expected.counterparty.role !== actual.role || expected.counterparty.id !== actual.id)) {
+        return {
+            status: "conflict",
+            expected: expected.counterparty,
+            actual,
+            externalRef,
+        };
+    }
+    return {
+        status: "matched",
+        counterparty: actual,
+        externalRef,
+        reconciliationItem: await maybeCreateChannelReconciliationItem(db, actual, input.channelReconciliation),
+    };
+}
+async function getCounterpartyByRole(db, role, id, externalRef) {
+    if (role === "supplier") {
+        const [record] = await db.select().from(suppliers).where(eq(suppliers.id, id)).limit(1);
+        return record
+            ? {
+                role,
+                entityType: "supplier",
+                id: record.id,
+                record,
+                externalRef,
+            }
+            : null;
+    }
+    const [record] = await db.select().from(channels).where(eq(channels.id, id)).limit(1);
+    return record
+        ? {
+            role,
+            entityType: "channel",
+            id: record.id,
+            record,
+            externalRef,
+        }
+        : null;
+}
+async function findExternalRef(db, input) {
+    const conditions = [
+        eq(externalRefs.sourceSystem, input.sourceSystem),
+        eq(externalRefs.objectType, input.objectType),
+        eq(externalRefs.namespace, input.namespace ?? "default"),
+        eq(externalRefs.externalId, input.externalId),
+    ];
+    if (input.entityType) {
+        conditions.push(eq(externalRefs.entityType, input.entityType));
+    }
+    if (input.entityId) {
+        conditions.push(eq(externalRefs.entityId, input.entityId));
+    }
+    const [row] = await db
+        .select()
+        .from(externalRefs)
+        .where(and(...conditions))
+        .limit(1);
+    return row ?? null;
+}
+async function clearPrimaryExternalRefs(db, input) {
+    const conditions = [
+        eq(externalRefs.entityType, input.entityType),
+        eq(externalRefs.entityId, input.entityId),
+        eq(externalRefs.sourceSystem, input.sourceSystem),
+    ];
+    if (input.exceptId) {
+        conditions.push(ne(externalRefs.id, input.exceptId));
+    }
+    await db
+        .update(externalRefs)
+        .set({ isPrimary: false, updatedAt: new Date() })
+        .where(and(...conditions));
+}
+async function maybeCreateChannelReconciliationItem(db, counterparty, input) {
+    if (!input || counterparty.role !== "channel") {
+        return null;
+    }
+    const [item] = await db
+        .insert(channelReconciliationItems)
+        .values({
+        reconciliationRunId: input.reconciliationRunId,
+        bookingLinkId: input.bookingLinkId ?? null,
+        bookingId: input.bookingId ?? null,
+        externalBookingId: input.externalBookingId ?? null,
+        issueType: input.issueType ?? "other",
+        severity: input.severity ?? "warning",
+        resolutionStatus: input.resolutionStatus ?? "open",
+        notes: input.notes ?? null,
+    })
+        .returning();
+    return item ?? null;
+}
+function toDate(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return value instanceof Date ? value : new Date(value);
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Per-channel rate limiting (token bucket on Postgres).
+ *
+ * `acquireToken` is the canonical channel-push wrapper around the
+ * generic `infra.rate_limit_buckets` primitive. Each call:
+ *
+ *   1. Atomically refills the bucket based on `(now - last_refill_at) *
+ *      refill_rate`, capped at capacity.
+ *   2. Checks the priority gate: tokens_available >= gate * capacity
+ *      AND tokens_available >= 1.
+ *   3. On success, decrements by 1 and returns `{ acquired: true }`.
+ *   4. On denial, returns `{ acquired: false, retryAfterMs }` computed
+ *      from how long until enough tokens refill to clear the gate.
+ *
+ * Whole thing is one round-trip (an UPSERT with conditional UPDATE).
+ *
+ * Per docs/architecture/channel-push-architecture.md §14.2 and §14.3.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+export type ChannelPushPriority = "booking" | "availability" | "content";
+export interface RateLimitConfig {
+    /** Sustained refill rate (tokens per second). */
+    rps: number;
+    /** Burst capacity (max tokens in the bucket). */
+    burst: number;
+    /**
+     * Per-priority reserve thresholds. Defaults to:
+     *   { booking: 0, availability: 0.3, content: 0.7 }
+     * Read as: bookings dispatch with any tokens; availability when
+     * bucket ≥ 30% full; content when ≥ 70% full.
+     */
+    priorityGates?: Partial<Record<ChannelPushPriority, number>>;
+}
+export declare const DEFAULT_PRIORITY_GATES: Record<ChannelPushPriority, number>;
+export interface AcquireTokenAcquired {
+    acquired: true;
+    /** Tokens left in the bucket after this call. */
+    tokensRemaining: number;
+}
+export interface AcquireTokenDenied {
+    acquired: false;
+    /** Suggested wait time in milliseconds before retrying. */
+    retryAfterMs: number;
+    /** Tokens currently in the bucket (post-refill). */
+    tokensAvailable: number;
+}
+export type AcquireTokenResult = AcquireTokenAcquired | AcquireTokenDenied;
+/**
+ * Build the channel-push scope key from a (channel, connection) pair.
+ * Same shape used by the workflow + reconciler so all paths address the
+ * same bucket.
+ */
+export declare function channelScopeKey(channelId: string, connectionId: string): string;
+/**
+ * Acquire one token from the bucket at `scope`, applying the priority
+ * gate for `priority`. Creates the bucket on first call (UPSERT with
+ * full capacity).
+ */
+export declare function acquireToken(db: AnyDrizzleDb, scope: string, config: RateLimitConfig, priority: ChannelPushPriority): Promise<AcquireTokenResult>;
+/**
+ * Drain the bucket to zero and freeze it for `cooldownMs`.
+ *
+ * Called when an upstream returns 429 with a `Retry-After` hint —
+ * prevents subsequent dispatchers from immediately retrying through
+ * the same bucket and lets our outbound estimate converge with the
+ * channel's authoritative state. Per §14.4.
+ */
+export declare function drainBucket(db: AnyDrizzleDb, scope: string, cooldownMs: number): Promise<void>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAA;AAExE,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAA;CAC7D;AAED,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAItE,CAAA;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,IAAI,CAAA;IACd,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAA;IACf,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,kBAAkB,CAAA;AAE1E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAkF7B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/rate-limit.js

@@ -0,0 +1,135 @@
+/**
+ * Per-channel rate limiting (token bucket on Postgres).
+ *
+ * `acquireToken` is the canonical channel-push wrapper around the
+ * generic `infra.rate_limit_buckets` primitive. Each call:
+ *
+ *   1. Atomically refills the bucket based on `(now - last_refill_at) *
+ *      refill_rate`, capped at capacity.
+ *   2. Checks the priority gate: tokens_available >= gate * capacity
+ *      AND tokens_available >= 1.
+ *   3. On success, decrements by 1 and returns `{ acquired: true }`.
+ *   4. On denial, returns `{ acquired: false, retryAfterMs }` computed
+ *      from how long until enough tokens refill to clear the gate.
+ *
+ * Whole thing is one round-trip (an UPSERT with conditional UPDATE).
+ *
+ * Per docs/architecture/channel-push-architecture.md §14.2 and §14.3.
+ */
+import { infraRateLimitBucketsTable } from "@voyant-travel/db/schema/infra";
+import { eq } from "drizzle-orm";
+export const DEFAULT_PRIORITY_GATES = {
+    booking: 0,
+    availability: 0.3,
+    content: 0.7,
+};
+/**
+ * Build the channel-push scope key from a (channel, connection) pair.
+ * Same shape used by the workflow + reconciler so all paths address the
+ * same bucket.
+ */
+export function channelScopeKey(channelId, connectionId) {
+    return `channel:${channelId}:${connectionId}`;
+}
+/**
+ * Acquire one token from the bucket at `scope`, applying the priority
+ * gate for `priority`. Creates the bucket on first call (UPSERT with
+ * full capacity).
+ */
+export async function acquireToken(db, scope, config, priority) {
+    const gate = config.priorityGates?.[priority] ?? DEFAULT_PRIORITY_GATES[priority];
+    const gateThreshold = Math.max(0, gate) * config.burst;
+    const now = new Date();
+    // Read or create the bucket. We use an UPSERT to keep the operation
+    // single-call.
+    const existing = await db
+        .select()
+        .from(infraRateLimitBucketsTable)
+        .where(eq(infraRateLimitBucketsTable.scope, scope))
+        .limit(1);
+    let bucket = existing[0];
+    if (!bucket) {
+        const created = await db
+            .insert(infraRateLimitBucketsTable)
+            .values({
+            scope,
+            tokensAvailable: String(config.burst),
+            capacity: String(config.burst),
+            refillRatePerSec: String(config.rps),
+            lastRefillAt: now,
+        })
+            .onConflictDoNothing()
+            .returning();
+        if (created[0]) {
+            bucket = created[0];
+        }
+        else {
+            // Lost the race — re-read.
+            const reread = await db
+                .select()
+                .from(infraRateLimitBucketsTable)
+                .where(eq(infraRateLimitBucketsTable.scope, scope))
+                .limit(1);
+            bucket = reread[0];
+        }
+        if (!bucket) {
+            throw new Error(`acquireToken: failed to create bucket for scope "${scope}"`);
+        }
+    }
+    // Refill based on elapsed time, then check the gate.
+    const tokensBefore = Number.parseFloat(bucket.tokensAvailable);
+    const capacity = Number.parseFloat(bucket.capacity);
+    const refillRate = Number.parseFloat(bucket.refillRatePerSec);
+    const elapsedMs = now.getTime() - new Date(bucket.lastRefillAt).getTime();
+    const refilled = Math.min(capacity, tokensBefore + (elapsedMs / 1000) * refillRate);
+    if (refilled < 1 || refilled < gateThreshold) {
+        // Not enough tokens. Compute the wait until we cross the higher of
+        // (1, gateThreshold).
+        const target = Math.max(1, gateThreshold);
+        const deficit = target - refilled;
+        const retryAfterMs = refillRate > 0 ? Math.ceil((deficit / refillRate) * 1000) : 60_000;
+        // Persist the refill so concurrent acquirers see the same baseline.
+        await db
+            .update(infraRateLimitBucketsTable)
+            .set({
+            tokensAvailable: String(refilled),
+            lastRefillAt: now,
+            updatedAt: now,
+        })
+            .where(eq(infraRateLimitBucketsTable.scope, scope));
+        return {
+            acquired: false,
+            retryAfterMs: Math.max(retryAfterMs, 0),
+            tokensAvailable: refilled,
+        };
+    }
+    const after = refilled - 1;
+    await db
+        .update(infraRateLimitBucketsTable)
+        .set({
+        tokensAvailable: String(after),
+        lastRefillAt: now,
+        updatedAt: now,
+    })
+        .where(eq(infraRateLimitBucketsTable.scope, scope));
+    return { acquired: true, tokensRemaining: after };
+}
+/**
+ * Drain the bucket to zero and freeze it for `cooldownMs`.
+ *
+ * Called when an upstream returns 429 with a `Retry-After` hint —
+ * prevents subsequent dispatchers from immediately retrying through
+ * the same bucket and lets our outbound estimate converge with the
+ * channel's authoritative state. Per §14.4.
+ */
+export async function drainBucket(db, scope, cooldownMs) {
+    const lastRefillAt = new Date(Date.now() + cooldownMs);
+    await db
+        .update(infraRateLimitBucketsTable)
+        .set({
+        tokensAvailable: "0",
+        lastRefillAt,
+        updatedAt: new Date(),
+    })
+        .where(eq(infraRateLimitBucketsTable.scope, scope));
+}