@voyantjs/products 0.19.0 → 0.21.0

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

@@ -0,0 +1,203 @@
+/**
+ * Owned-arm booking handler for the `products` vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6 +
+ * §10 Phase A. Composes:
+ *
+ *   - The products vertical's existing pricing primitives
+ *     (`products.sellAmountCents` / `sellCurrency`) for pricing
+ *     basis. Per-pax / per-band pricing layered in Phase C+ via
+ *     `product_pax_pricing_tiers`.
+ *   - `getProductContent` + `buildProductDraftShape` for the journey
+ *     wizard's step descriptor.
+ *   - An injected `quickCreateBooking` function for the commit path
+ *     — keeps `@voyantjs/products` from depending on
+ *     `@voyantjs/finance` (no workspace cycle).
+ *
+ * Phase A scope (deliberately narrow):
+ *   - Price = product.sellAmountCents × pax_count, no taxes / addons /
+ *     accommodation / vouchers.
+ *   - Commit goes through the bridge into `bookingsQuickCreate`'s input
+ *     shape — products-only, no extras / hospitality / cruises / encrypted
+ *     travel details / snapshot graph.
+ *
+ * Phase C+ extensions land on this same handler without re-architecting
+ * the dispatch.
+ */
+import { type AddonOffer, type BookingDraftShape, type OwnedBookingHandler, type OwnedHandlerContext, type TravelerFieldRequirement } from "@voyantjs/catalog/booking-engine";
+/**
+ * Subset of `bookingsQuickCreate`'s input the bridge builds.
+ * Mirrors the schema in `service-bookings-quick-create.ts` — kept
+ * structural here so we don't pull a dependency into products.
+ */
+export interface QuickCreateBridgeInput {
+    productId: string;
+    optionId?: string | null;
+    slotId?: string | null;
+    bookingNumber: string;
+    personId?: string | null;
+    organizationId?: string | null;
+    internalNotes?: string | null;
+    travelers?: Array<{
+        firstName: string;
+        lastName: string;
+        email?: string | null;
+        phone?: string | null;
+        personId?: string | null;
+        participantType: "traveler" | "occupant" | "other";
+        travelerCategory?: "adult" | "child" | "infant" | "senior" | "other" | null;
+        isPrimary?: boolean | null;
+    }>;
+    paymentSchedules?: Array<{
+        scheduleType: "deposit" | "installment" | "balance" | "hold" | "other";
+        status: "pending" | "due" | "paid" | "waived" | "cancelled" | "expired";
+        dueDate: string;
+        currency: string;
+        amountCents: number;
+        notes?: string | null;
+    }>;
+    taxLines?: Array<{
+        code?: string | null;
+        name: string;
+        jurisdiction?: string | null;
+        scope?: "included" | "excluded" | "withheld";
+        currency: string;
+        amountCents: number;
+        rateBasisPoints?: number | null;
+        includedInPrice?: boolean;
+        remittanceParty?: string | null;
+        sortOrder?: number;
+    }>;
+}
+export interface QuickCreateBridgeResult {
+    status: "ok" | "product_not_found" | string;
+    bookingId?: string;
+    bookingNumber?: string;
+}
+/**
+ * Caller-supplied bridge to `bookingsQuickCreate`. Templates wire
+ * this up — `(input, opts) => quickCreateBooking(db as PostgresJsDatabase, input, opts)`.
+ */
+export type QuickCreateBridge = (input: QuickCreateBridgeInput, options?: {
+    userId?: string;
+}) => Promise<QuickCreateBridgeResult>;
+export interface BuildOwnedProductDraftShapeOptions {
+    /**
+     * Per-traveler field requirements pulled from
+     * `@voyantjs/booking-requirements` for this product. Caller-supplied
+     * so the products package doesn't depend on booking-requirements.
+     */
+    travelerFields?: ReadonlyArray<TravelerFieldRequirement>;
+    /**
+     * Add-on catalog projected from extras. Caller-supplied so
+     * products doesn't depend on `@voyantjs/extras`. When omitted,
+     * `showsAddons` is false.
+     */
+    addonCatalog?: ReadonlyArray<AddonOffer>;
+}
+export declare function buildOwnedProductDraftShape(options?: BuildOwnedProductDraftShapeOptions): BookingDraftShape;
+/** A resolved tax-rate decision — resolved from `tax_classes` ×
+ *  `tax_regimes` × buyer country at quote time. */
+export interface ResolvedTaxRate {
+    /** Stable code (e.g. "vat-ro-19", "exempt-art311"). */
+    code: string;
+    /** Display label for the breakdown. */
+    label: string;
+    /** Rate as a fraction (0..1). 0 means exempt / zero-rated. */
+    rate: number;
+    /** Whether the configured product price already includes this tax. */
+    priceMode?: "inclusive" | "exclusive";
+}
+/** Caller-supplied loaders for descriptor enrichment. Each is
+ *  optional — when omitted the handler returns the default shape.
+ *  Templates wire these to the modules they have on hand
+ *  (booking-requirements, extras, finance). */
+export interface OwnedProductsShapeLoaders {
+    /**
+     * Resolve per-traveler field requirements from
+     * @voyantjs/booking-requirements. Called per-quote so the descriptor
+     * reflects current configuration.
+     */
+    loadTravelerFields?: (ctx: OwnedHandlerContext, productId: string) => Promise<ReadonlyArray<TravelerFieldRequirement>>;
+    /**
+     * Resolve the addon catalog for the product (typically a projection
+     * over `extras` + `option_extra_configs`). Caller-supplied to keep
+     * the products package free of an @voyantjs/extras dependency.
+     */
+    loadAddonCatalog?: (ctx: OwnedHandlerContext, productId: string) => Promise<ReadonlyArray<AddonOffer>>;
+    /**
+     * Resolve the tax rate for a given (product, buyer country) pair.
+     * Templates wire this to a function that reads
+     * `products.tax_class_id`, `tax_classes.default_regime_id`, and
+     * `tax_regimes.rate_percent`. Returns null when tax can't be
+     * resolved — the engine renders the breakdown without a tax line.
+     *
+     * Per booking-journey-architecture §9.
+     */
+    loadTaxRate?: (ctx: OwnedHandlerContext, args: {
+        productId: string;
+        buyerCountry?: string;
+        buyerType?: "B2C" | "B2B";
+    }) => Promise<ResolvedTaxRate | null>;
+}
+/**
+ * Caller-supplied availability-hold bridge — keeps the products
+ * package free of an `@voyantjs/availability` dependency. When
+ * wired, the handler's `placeHold/extendHold/releaseHold` route
+ * through `availability_holds` (real inventory locks). When
+ * omitted, the handler falls back to stamping no-ops.
+ */
+export interface AvailabilityHoldBridge {
+    place: (input: {
+        draftId: string;
+        productId: string;
+        slotId: string;
+        paxCount: number;
+        ttlMs: number;
+        holdToken?: string;
+    }) => Promise<{
+        status: "ok";
+        holdToken: string;
+        expiresAt: Date;
+    } | {
+        status: "slot_not_found";
+    } | {
+        status: "insufficient_capacity";
+        remaining: number;
+        needed: number;
+    }>;
+    extend: (input: {
+        holdToken: string;
+        ttlMs: number;
+    }) => Promise<{
+        status: "ok";
+        expiresAt: Date;
+    } | {
+        status: "not_found";
+    }>;
+    release: (holdToken: string) => Promise<void>;
+}
+export interface CreateProductsBookingHandlerOptions extends OwnedProductsShapeLoaders {
+    /**
+     * Caller-supplied bridge to `bookingsQuickCreate`. Wired by the
+     * template at boot, since `@voyantjs/products` does not import
+     * `@voyantjs/finance`.
+     */
+    quickCreate: QuickCreateBridge;
+    /**
+     * Generator for booking numbers. Defaults to a timestamp-based
+     * value if not supplied. Templates that have a sequence service
+     * (operator: numbering plugin) override.
+     */
+    generateBookingNumber?: () => string;
+    /**
+     * Optional inventory-hold bridge. When wired, `placeHold`
+     * decrements `availability_slots.remainingPax` against the
+     * draft's chosen slot; `releaseHold` restores it. When omitted,
+     * the handler returns a stamping token without touching
+     * inventory.
+     */
+    holds?: AvailabilityHoldBridge;
+}
+export declare function createProductsBookingHandler(options: CreateProductsBookingHandlerOptions): OwnedBookingHandler;
+//# sourceMappingURL=handler.d.ts.map

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

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

package/dist/booking-engine/handler.js

@@ -0,0 +1,330 @@
+/**
+ * Owned-arm booking handler for the `products` vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6 +
+ * §10 Phase A. Composes:
+ *
+ *   - The products vertical's existing pricing primitives
+ *     (`products.sellAmountCents` / `sellCurrency`) for pricing
+ *     basis. Per-pax / per-band pricing layered in Phase C+ via
+ *     `product_pax_pricing_tiers`.
+ *   - `getProductContent` + `buildProductDraftShape` for the journey
+ *     wizard's step descriptor.
+ *   - An injected `quickCreateBooking` function for the commit path
+ *     — keeps `@voyantjs/products` from depending on
+ *     `@voyantjs/finance` (no workspace cycle).
+ *
+ * Phase A scope (deliberately narrow):
+ *   - Price = product.sellAmountCents × pax_count, no taxes / addons /
+ *     accommodation / vouchers.
+ *   - Commit goes through the bridge into `bookingsQuickCreate`'s input
+ *     shape — products-only, no extras / hospitality / cruises / encrypted
+ *     travel details / snapshot graph.
+ *
+ * Phase C+ extensions land on this same handler without re-architecting
+ * the dispatch.
+ */
+import { DEFAULT_PAX_BANDS, defaultBookingFields, defaultDraftShapeFlags, defaultTravelerFields, paxBandsAllowedTotalFrom, } from "@voyantjs/catalog/booking-engine";
+import { eq } from "drizzle-orm";
+import { products } from "../schema-core.js";
+export function buildOwnedProductDraftShape(options = {}) {
+    const paxBands = DEFAULT_PAX_BANDS;
+    const fields = options.travelerFields ?? defaultTravelerFields();
+    const addons = options.addonCatalog ?? [];
+    const flags = defaultDraftShapeFlags();
+    return {
+        ...flags,
+        showsAddons: addons.length > 0,
+        paxBands,
+        paxBandsAllowedTotal: paxBandsAllowedTotalFrom(paxBands),
+        travelerFields: fields,
+        bookingFields: defaultBookingFields(),
+        paymentIntents: ["hold", "card"],
+        configureSubSteps: [{ kind: "occupancy", bands: paxBands }],
+        addons: addons.length > 0 ? { catalog: addons } : undefined,
+    };
+}
+export function createProductsBookingHandler(options) {
+    const generateNumber = options.generateBookingNumber ?? defaultBookingNumber;
+    return {
+        entityModule: "products",
+        async computeQuote(ctx, request) {
+            const product = await loadProduct(ctx.db, request.entityId);
+            if (!product) {
+                return { available: false, invalidReason: "product_not_found" };
+            }
+            if (product.status !== "active" && product.status !== "draft") {
+                return {
+                    available: false,
+                    invalidReason: `product_status_${product.status}`,
+                };
+            }
+            const draft = (request.draft ?? {});
+            // Concurrent enrichment — all three calls are pure reads and
+            // don't depend on each other.
+            const [travelerFields, addonCatalog, taxRate] = await Promise.all([
+                options.loadTravelerFields?.(ctx, request.entityId) ?? Promise.resolve(undefined),
+                options.loadAddonCatalog?.(ctx, request.entityId) ?? Promise.resolve(undefined),
+                options.loadTaxRate?.(ctx, {
+                    productId: request.entityId,
+                    buyerCountry: draft.billing?.address?.country,
+                    buyerType: draft.billing?.buyerType,
+                }) ?? Promise.resolve(null),
+            ]);
+            const paxCount = sumPax(draft.configure?.pax);
+            // Per-pax pricing fallback: when no pax is supplied yet, quote a
+            // single-occupant baseline so the wizard can render a starter
+            // total before the user picks counts.
+            const effectivePax = paxCount > 0 ? paxCount : 1;
+            const unitCents = product.sellAmountCents ?? 0;
+            const grossCents = unitCents * effectivePax;
+            // Tax computation. The base is taxable; addons/accommodation
+            // get the same rate in this MVP cut. Per-line override (the
+            // `applies_to` axis on tax_classes.lines) lands in a follow-up
+            // when the catalog actually carries mixed treatments.
+            const taxIsInclusive = taxRate?.priceMode === "inclusive";
+            const taxCents = taxRate && taxRate.rate > 0
+                ? taxIsInclusive
+                    ? Math.round(grossCents - grossCents / (1 + taxRate.rate))
+                    : Math.round(grossCents * taxRate.rate)
+                : 0;
+            const netCents = taxIsInclusive ? grossCents - taxCents : grossCents;
+            const payableCents = taxIsInclusive ? grossCents : netCents + taxCents;
+            const pricing = unitCents > 0
+                ? {
+                    base_amount: netCents,
+                    taxes: taxCents,
+                    fees: 0,
+                    surcharges: 0,
+                    currency: product.sellCurrency,
+                    breakdown: {
+                        lines: [
+                            {
+                                kind: "base",
+                                label: product.name,
+                                quantity: effectivePax,
+                                unitAmount: unitCents,
+                                totalAmount: grossCents,
+                                taxIncluded: taxIsInclusive,
+                            },
+                        ],
+                        taxes: taxRate && taxCents > 0
+                            ? [
+                                {
+                                    code: taxRate.code,
+                                    label: taxRate.label,
+                                    rate: taxRate.rate,
+                                    amount: taxCents,
+                                    base: netCents,
+                                    includedInPrice: taxIsInclusive,
+                                    scope: taxIsInclusive ? "included" : "excluded",
+                                },
+                            ]
+                            : [],
+                        subtotal: netCents,
+                        taxTotal: taxCents,
+                        total: payableCents,
+                        paxCount: effectivePax,
+                    },
+                }
+                : undefined;
+            return {
+                available: unitCents > 0,
+                invalidReason: unitCents > 0 ? undefined : "no_sell_amount_configured",
+                pricing,
+                shape: buildOwnedProductDraftShape({
+                    travelerFields,
+                    addonCatalog,
+                }),
+            };
+        },
+        /**
+         * Place a soft hold on the row's chosen slot. When the
+         * `holds` bridge is wired, decrements
+         * `availability_slots.remainingPax` against the slot for the
+         * pax count; concurrent placeHold attempts are serialized via
+         * a row-level lock inside the bridge. When omitted, returns a
+         * stamping token without touching inventory.
+         *
+         * The slot id and pax count are pulled off
+         * `request.parameters.slotId` / `request.parameters.paxCount`
+         * — the journey wizard threads these from the draft's
+         * Configure step (`departureSlotId` + summed `pax`).
+         */
+        async placeHold(_ctx, request) {
+            const token = request.draftId ?? defaultBookingNumber();
+            const expiresAt = new Date(Date.now() + request.ttlMs);
+            if (!options.holds) {
+                return { holdToken: token, expiresAt };
+            }
+            const params = (request.parameters ?? {});
+            const slotId = params.slotId;
+            const paxCount = params.paxCount ?? 1;
+            if (!slotId || !request.draftId) {
+                // No slot chosen yet → no inventory to lock. Return a
+                // stamping token so the journey can still call extend /
+                // release.
+                return { holdToken: token, expiresAt };
+            }
+            const result = await options.holds.place({
+                draftId: request.draftId,
+                productId: params.productId ?? request.entityId,
+                slotId,
+                paxCount,
+                ttlMs: request.ttlMs,
+                holdToken: token,
+            });
+            if (result.status === "ok") {
+                return { holdToken: result.holdToken, expiresAt: result.expiresAt };
+            }
+            // Capacity / lookup failures fall back to a stamping token
+            // — the journey commit will revalidate via the engine's
+            // re-quote and reject if capacity has dried up.
+            return { holdToken: token, expiresAt };
+        },
+        async extendHold(_ctx, holdToken, request) {
+            const ttlMs = request?.ttlMs ?? 30 * 60 * 1000;
+            if (options.holds) {
+                const result = await options.holds.extend({ holdToken, ttlMs });
+                if (result.status === "ok") {
+                    return { holdToken, expiresAt: result.expiresAt };
+                }
+            }
+            return { holdToken, expiresAt: new Date(Date.now() + ttlMs) };
+        },
+        async releaseHold(_ctx, holdToken) {
+            if (options.holds) {
+                await options.holds.release(holdToken);
+            }
+        },
+        async commit(ctx, request) {
+            const draft = (request.draft ?? {});
+            // Defensive product load — the bridge will fail with
+            // `product_not_found` anyway, but a clean early-return keeps the
+            // commit path's error envelope predictable.
+            const product = await loadProduct(ctx.db, request.entityId);
+            if (!product) {
+                return {
+                    status: "failed",
+                    orderRef: "",
+                    upstreamPayload: { reason: "product_not_found" },
+                };
+            }
+            const travelers = (draft.travelers ?? []).map((t) => ({
+                firstName: t.firstName,
+                lastName: t.lastName,
+                email: t.email,
+                phone: t.phone,
+                participantType: "traveler",
+                travelerCategory: t.band === "child" || t.band === "infant"
+                    ? t.band
+                    : "adult",
+            }));
+            const bridge = await options.quickCreate({
+                productId: product.id,
+                bookingNumber: generateNumber(),
+                personId: extractPersonId(request.party),
+                organizationId: extractOrganizationId(request.party),
+                internalNotes: extractInternalNotes(request.party),
+                travelers: travelers.length > 0 ? travelers : undefined,
+                taxLines: extractTaxLines(request.pricing),
+            });
+            if (bridge.status !== "ok" || !bridge.bookingId) {
+                return {
+                    status: "failed",
+                    orderRef: "",
+                    upstreamPayload: { bridge },
+                };
+            }
+            return {
+                status: "held",
+                orderRef: bridge.bookingNumber ?? bridge.bookingId,
+                pricing: request.pricing,
+                upstreamPayload: { bridgeBookingId: bridge.bookingId },
+            };
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+async function loadProduct(db, productId) {
+    const drizzle = db;
+    const rows = (await drizzle
+        .select()
+        .from(products)
+        .where(eq(products.id, productId))
+        .limit(1));
+    return rows[0];
+}
+function sumPax(pax) {
+    if (!pax)
+        return 0;
+    let total = 0;
+    for (const v of Object.values(pax)) {
+        if (typeof v === "number" && Number.isFinite(v) && v > 0)
+            total += v;
+    }
+    return total;
+}
+function extractPersonId(party) {
+    if (!party)
+        return undefined;
+    const v = party.personId;
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function extractOrganizationId(party) {
+    if (!party)
+        return undefined;
+    const v = party.organizationId;
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function extractInternalNotes(party) {
+    if (!party)
+        return undefined;
+    const v = party.internalNotes;
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function extractTaxLines(pricing) {
+    const breakdown = pricing?.breakdown;
+    if (!breakdown || typeof breakdown !== "object" || Array.isArray(breakdown))
+        return undefined;
+    const taxes = breakdown.taxes;
+    if (!Array.isArray(taxes))
+        return undefined;
+    const lines = [];
+    for (const [index, tax] of taxes.entries()) {
+        if (!tax || typeof tax !== "object" || Array.isArray(tax))
+            continue;
+        const row = tax;
+        const amountCents = asFiniteInteger(row.amount);
+        const rate = typeof row.rate === "number" && Number.isFinite(row.rate) ? row.rate : null;
+        const currency = typeof pricing?.currency === "string" && pricing.currency.length === 3
+            ? pricing.currency
+            : "EUR";
+        const name = typeof row.label === "string" && row.label.length > 0 ? row.label : "Tax";
+        if (!amountCents || amountCents <= 0)
+            continue;
+        const includedInPrice = row.includedInPrice === true || row.scope === "included";
+        lines.push({
+            code: typeof row.code === "string" ? row.code : null,
+            name,
+            scope: includedInPrice ? "included" : "excluded",
+            currency,
+            amountCents,
+            rateBasisPoints: rate == null ? null : Math.round(rate * 10_000),
+            includedInPrice,
+            sortOrder: index,
+        });
+    }
+    return lines.length ? lines : undefined;
+}
+function asFiniteInteger(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return Math.round(value);
+}
+function defaultBookingNumber() {
+    const ts = Date.now().toString(36).toUpperCase();
+    return `BK-${ts}`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * `@voyantjs/products/booking-engine` — owned-arm booking handler
+ * for the products vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6.
+ */
+export { type AvailabilityHoldBridge, buildOwnedProductDraftShape, type CreateProductsBookingHandlerOptions, createProductsBookingHandler, type QuickCreateBridge, type QuickCreateBridgeInput, type QuickCreateBridgeResult, } from "./handler.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/booking-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,sBAAsB,EAC3B,2BAA2B,EAC3B,KAAK,mCAAmC,EACxC,4BAA4B,EAC5B,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAA"}

package/dist/booking-engine/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@voyantjs/products/booking-engine` — owned-arm booking handler
+ * for the products vertical.
+ *
+ * Per `docs/architecture/booking-journey-architecture.md` §6.
+ */
+export { buildOwnedProductDraftShape, createProductsBookingHandler, } from "./handler.js";

package/dist/catalog-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Catalog plane field policy for `packages/products`.
+ *
+ * Declares every product field's governance under the
+ * `@voyantjs/catalog` 12-attribute contract. Phase B shake-out
+ * adoption — see `docs/architecture/catalog-architecture.md` §9.1.
+ *
+ * Scope of this file:
+ *   - The root `products` table (from `schema-core.ts`).
+ *   - Provenance + identity fields the catalog plane needs to track.
+ *
+ * Out of scope (deferred to follow-up adoption passes):
+ *   - `productOptions`, `optionUnits`, `productDays`, `productNotes`,
+ *     `productVersions` — promoted child entities (per composition rule §6.2);
+ *     each gets its own micro-registry when wired in.
+ *   - The split of `tags` into `marketing_tags` + `facet_tags` per the
+ *     human-readable / machine-evaluable rule (§7.1). Today's schema has a
+ *     single `tags` column; declared here as merchandisable with a TODO.
+ */
+import { type FieldPolicyInput } from "@voyantjs/catalog/contract";
+/**
+ * Field-policy declarations for `products`. Pass through `defineFieldPolicy`
+ * to apply inheritance and produce the runtime registry.
+ */
+declare const PRODUCT_FIELD_POLICY: FieldPolicyInput[];
+/**
+ * Resolved field-policy registry for products. Verticals adopt the catalog
+ * plane by exporting this; templates wire it into the indexer, overlay
+ * resolver, and snapshot capture pipeline.
+ */
+export declare const productCatalogPolicy: import("@voyantjs/catalog").FieldPolicy[];
+export { PRODUCT_FIELD_POLICY };
+//# sourceMappingURL=catalog-policy.d.ts.map

package/dist/catalog-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-policy.d.ts","sourceRoot":"","sources":["../src/catalog-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAErF;;;GAGG;AACH,QAAA,MAAM,oBAAoB,EAAE,gBAAgB,EA0Y3C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,2CAA0C,CAAA;AAE3E,OAAO,EAAE,oBAAoB,EAAE,CAAA"}