@happyvertical/smrt-commerce 0.30.0

package/dist/models/PaymentIntent.d.ts

@@ -0,0 +1,341 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { PaymentIntentStatus, PaymentOption } from '../types/index.js';
+export declare class PaymentIntent extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation. Nullable so the same model
+     * can serve both per-tenant SaaS deployments and single-tenant /
+     * global setups.
+     */
+    tenantId: string | null;
+    /**
+     * Plain string reference to the upstream `Sku` (from
+     * `@happyvertical/smrt-products`) being purchased. Cross-package
+     * reference — plain string, not `@foreignKey()`, to avoid the
+     * circular dependency the framework warns against.
+     *
+     * Required for the marketplace flow; other consumers can leave it
+     * empty if they don't model a catalog.
+     */
+    skuId: string;
+    /**
+     * Caller-supplied scope for the idempotency-key natural key. The
+     * marketplace sets this to a `Sku` id, but the field is intentionally
+     * abstract so other consumers (subscription tiers, donation tiers,
+     * tipping flows) can scope idempotency by whatever granularity makes
+     * sense.
+     *
+     * Empty string is permitted but disables the natural-key dedup —
+     * every retry then creates a fresh row.
+     */
+    offeringRef: string;
+    /**
+     * The buyer's email address. The licensee on any downstream
+     * `LicenseSale` (or similar rights-issuance row) is identified by
+     * this email — high-tier purchases also create a `Customer` record
+     * and set {@link customerId}, but most purchases get away with email
+     * alone.
+     */
+    licenseeEmail: string;
+    /**
+     * Optional link to a `Customer` row for purchases that warrant a
+     * full customer record (high-tier licensing, recurring buyers,
+     * etc.). Cross-model reference is kept as a plain string to match
+     * the rest of the package's cross-package convention.
+     */
+    customerId: string;
+    /**
+     * The payment rails the buyer can choose between to satisfy this
+     * intent. Stored as a JSON column. See {@link PaymentOption} for
+     * the per-option shape. Empty array means the intent is invalid /
+     * mis-built; callers should reject save in that case.
+     */
+    paymentOptions: PaymentOption[];
+    /**
+     * USD price locked at quote time. Stored at decimal precision.
+     * Independent of any specific option's native-currency amount;
+     * `usdPriceLocked` is the canonical "what this costs in USD"
+     * number used downstream for reporting, tax, and drift accounting.
+     */
+    usdPriceLocked: number;
+    /**
+     * Length of the price-lock window in milliseconds. Defaults to 15
+     * minutes; consumers can override per-intent. Stored so a later
+     * audit can see the original window even after {@link priceLockExpiresAt}
+     * has passed.
+     */
+    priceLockWindowMs: number;
+    /**
+     * Wall-clock time at which the price lock expires. Set by the
+     * constructor (or by `expire()` if you want to short-circuit a
+     * specific intent). Once `Date.now()` passes this value and the
+     * status is still `AWAITING_PAYMENT`, callers should treat the
+     * intent as expired and refuse to record a payment against it.
+     */
+    priceLockExpiresAt: Date | null;
+    /**
+     * Current status — see {@link PaymentIntentStatus} for the state
+     * machine. Mutate via the dedicated `markPaid` / `markIssued` /
+     * `expire` / `cancel` / `retire` helpers rather than assigning
+     * directly, so the helpers' invariant checks run.
+     */
+    status: PaymentIntentStatus;
+    /**
+     * Caller-supplied idempotency key. Combined with `tenantId`,
+     * `offeringRef`, and `licenseeEmail`, this forms the natural key
+     * registered in `conflictColumns` — a retried `create` with the
+     * same tuple upserts the existing row instead of creating a
+     * duplicate.
+     *
+     * Empty string disables natural-key dedup (every retry creates a
+     * fresh row).
+     */
+    idempotencyKey: string;
+    /**
+     * `backendId` of the option that satisfied the intent. Set by
+     * {@link markPaid}; remains empty for non-paid intents. Used by
+     * {@link isOptionRetired} to flag inbound funds on the other
+     * options as "needs refund".
+     */
+    paidOptionBackendId: string;
+    /**
+     * Plain string reference to the `Payment` row that satisfied the
+     * intent. Cross-model reference matches the rest of the
+     * package's convention.
+     */
+    paymentId: string;
+    /**
+     * When the intent transitioned to `PAID`.
+     */
+    paidAt: Date | null;
+    /**
+     * When the intent transitioned to `ISSUED`.
+     */
+    issuedAt: Date | null;
+    /**
+     * When the intent transitioned to `EXPIRED`.
+     */
+    expiredAt: Date | null;
+    /**
+     * When the intent transitioned to `CANCELLED`.
+     */
+    cancelledAt: Date | null;
+    /**
+     * When the intent transitioned to `RETIRED`.
+     */
+    retiredAt: Date | null;
+    /**
+     * Optional human-readable notes (e.g., support tickets, refund
+     * memos, cancellation reasons). Append-only by convention.
+     */
+    notes: string;
+    constructor(options?: any);
+    /**
+     * Re-normalize `paymentOptions` after the framework's
+     * `initializePropertiesFromOptions` pass has overwritten the
+     * constructor-set values with the raw cloned input, and stamp a
+     * default `priceLockExpiresAt` so newly-created intents have a
+     * concrete expiry without callers needing to compute it.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Save-time state-machine guard (S5 audit #1390 round 2).
+     *
+     * `status`, `paymentId`, and `paidOptionBackendId` are all mass-assignable on
+     * the generated update route, and the sync `markPaid` helper trusts its
+     * arguments. Two distinct attacks follow:
+     *
+     *  1. **Forge a PAID intent** — set `status: 'paid'` (or call bare `markPaid`)
+     *     against a bogus / pending / non-matching Payment. This falsifies
+     *     downstream "this was paid for" rights issuance.
+     *  2. **Repoint an already-PAID intent** — leave `status: 'paid'` but swap
+     *     `paymentId` / `paidOptionBackendId` to a bogus Payment after the fact.
+     *     Round 1 only verified the *transition into* PAID, so an already-PAID
+     *     row could be silently repointed with no re-verify. Likewise an intent
+     *     forced straight to `ISSUED` (the terminal happy-path that gates rights
+     *     issuance) was never required to have been backed by a real Payment.
+     *
+     * This guard therefore:
+     *  - validates the status transition is legal (no `awaiting_payment → issued`
+     *    skips, no reviving terminal states);
+     *  - re-verifies the backing Payment on **every** save where the persisted
+     *    status is PAID or ISSUED — not just the transition edge — so a repoint
+     *    of the paid backing fields is caught.
+     *
+     * Re-verifying an unchanged PAID/ISSUED row is cheap (one Payment load) and
+     * closes the repoint hole; freezing the backing fields would instead block
+     * legitimate corrections, so we re-verify.
+     */
+    save(): Promise<this>;
+    /**
+     * Load the authoritative persisted row for this intent (S5 audit #1390 round
+     * 4). Returns `undefined` when the intent has no `id` or no row exists yet
+     * (truly new). Reading the DB directly — rather than trusting the
+     * {@link loadedIntentStatus} WeakMap, which is only populated when
+     * {@link initialize} hydrated the row — defeats the poisonable-prior-state
+     * vector where `create({ id: <existing>, _skipLoad: true })` produces an
+     * un-hydrated instance whose WeakMap entry is missing. A create-onto-existing
+     * is thus correctly treated as an update.
+     */
+    private loadPersistedRow;
+    /**
+     * Reject any change to the settled backing fields of an already-PAID/ISSUED
+     * intent (codex HIGH#2). `paymentOptions` is compared structurally because
+     * the winning option's `nativeAmount` is exactly what the reconciliation in
+     * {@link assertBackedByCompletedPayment} binds against — letting it drift
+     * would let a repointed `paymentId` match a doctored option.
+     */
+    private assertBackingFieldsUnchanged;
+    /**
+     * Reject an illegal status flip done via raw field assignment. Compares the
+     * about-to-be-written status against the status the row was loaded with.
+     * No-op re-saves (status unchanged) and brand-new rows are allowed (the
+     * backing-Payment verification still runs separately for PAID/ISSUED).
+     */
+    private assertStatusTransition;
+    /**
+     * Verify the intent's `paidOptionBackendId` / `paymentId` reference a real,
+     * COMPLETED, amount-matching Payment. Throws otherwise. Shared by
+     * {@link verifyAndMarkPaid} (pre-transition) and the save-time guard
+     * (catch-all for raw mass-assignment).
+     */
+    private assertBackedByCompletedPayment;
+    /**
+     * Reconcile a COMPLETED Payment against the winning {@link PaymentOption}
+     * (S5 audit #1390). Beyond the amount check, the Payment must have arrived on
+     * the SAME rail and currency the option quoted — otherwise an unrelated
+     * completed payment that merely shares a numeric amount (e.g. a USD 199
+     * payment) could satisfy a different option (e.g. a `base-usdc` 199 option),
+     * marking the intent paid on the wrong rail with no matching funds. Compares
+     * the Payment's `backendId` (rail) and native currency (falling back to its
+     * settlement currency) against the option's `backendId` / `currency`, then
+     * the native amount.
+     *
+     * Shared by {@link verifyAndMarkPaid} (pre-transition) and
+     * {@link assertBackedByCompletedPayment} (save-time catch-all) so both gates
+     * enforce the identical invariant.
+     */
+    private reconcilePaymentWithOption;
+    isAwaitingPayment(): boolean;
+    isPaid(): boolean;
+    isIssued(): boolean;
+    isCancelled(): boolean;
+    isRetired(): boolean;
+    /**
+     * Terminal-state predicate: any status other than `AWAITING_PAYMENT`
+     * is terminal (the intent will not accept further state changes
+     * except the explicit `markIssued` after `PAID`).
+     */
+    isTerminal(): boolean;
+    /**
+     * `Date.now()`-based predicate: has the price lock window passed?
+     * Independent of `status` so callers can detect a stale-but-not-
+     * yet-marked-EXPIRED intent (and call `expire()` to advance it).
+     */
+    isExpired(): boolean;
+    /**
+     * Transition the intent to `PAID`, naming which option satisfied it
+     * and which `Payment` row carries the funds. Implicitly retires the
+     * other options — callers can check {@link isOptionRetired} to flag
+     * later inbound funds for refund.
+     *
+     * Throws when called on a non-`AWAITING_PAYMENT` intent so a stale
+     * caller can't accidentally overwrite a winning option with a
+     * losing one.
+     */
+    markPaid(args: {
+        backendId: string;
+        paymentId: string;
+    }): void;
+    /**
+     * Verify-then-transition variant of {@link markPaid} (S5 audit #1390).
+     *
+     * `markPaid` trusts the caller-supplied `paymentId` / `backendId` without
+     * checking the referenced `Payment` actually exists, is `COMPLETED`, or
+     * carries the amount the winning option quoted. That lets a caller mark an
+     * intent PAID against a non-existent or still-pending payment. This method
+     * loads the `Payment` row and enforces:
+     *
+     *  - the Payment exists,
+     *  - it is `COMPLETED` (not pending / failed / cancelled / refunded),
+     *  - it arrived on the same rail (`backendId`) and currency the option
+     *    quoted (so an unrelated completed payment that merely shares a numeric
+     *    amount can't satisfy a different option),
+     *  - and its amount reconciles with the winning option's `nativeAmount`
+     *    (within sub-cent tolerance), falling back to the option vs. the
+     *    Payment's settlement `amount` when no native rail is recorded.
+     *
+     * Only after those pass does it delegate to the sync `markPaid` for the
+     * status-machine invariants.
+     *
+     * @param args.backendId  backendId of the option that was satisfied
+     * @param args.paymentId  id of the Payment row carrying the funds (required)
+     */
+    verifyAndMarkPaid(args: {
+        backendId: string;
+        paymentId: string;
+    }): Promise<void>;
+    /**
+     * Transition a `PAID` intent to `ISSUED` once the downstream rights
+     * / contract / fulfillment have been created. Idempotent — calling
+     * twice is a no-op so callers don't have to guard against retries.
+     */
+    markIssued(): void;
+    /**
+     * Move an `AWAITING_PAYMENT` intent to `EXPIRED`. Safe to call on
+     * an already-expired intent (no-op). Throws on terminal non-
+     * expired states so a confused caller can't undo a paid / issued
+     * intent.
+     */
+    expire(): void;
+    /**
+     * Cancel an open intent. Only valid from `AWAITING_PAYMENT` —
+     * a paid / issued intent is no longer the buyer's to cancel; that
+     * path is a refund, modelled separately on `Payment`.
+     */
+    cancel(reason?: string): void;
+    /**
+     * Mark a paid intent as retired — used when a previously-recorded
+     * payment was reversed (chargeback, refund) and the intent should
+     * not be considered "satisfied" anymore. Distinct from `cancel()`
+     * which only applies to never-paid intents.
+     */
+    retire(reason?: string): void;
+    /**
+     * Return the option whose `backendId` matches, or `undefined` if
+     * no such option is on this intent. Useful for routing inbound
+     * payments to the right option's `nativeAmount` / `payTo` for
+     * verification.
+     */
+    getOption(backendId: string): PaymentOption | undefined;
+    /**
+     * `true` once the intent is paid and the given option was NOT the
+     * winning one. Consumers use this to flag inbound funds to retired
+     * options for refund. Returns `false` for the winning option, for
+     * unpaid intents, and for an unknown `backendId`.
+     */
+    isOptionRetired(backendId: string): boolean;
+    /**
+     * The options that were NOT selected at payment time. Returns an
+     * empty array for unpaid intents so callers can iterate without
+     * special-casing.
+     */
+    getRetiredOptions(): PaymentOption[];
+    /**
+     * Defensive coercion for `paymentOptions` input. Accepts either an
+     * already-parsed array or a JSON string (e.g. from a row whose
+     * column was hand-edited or migrated from a different schema).
+     * Drops entries that don't carry the required `backendId` /
+     * `currency` / `payTo` / `nativeAmount` quartet so downstream
+     * routing code can rely on the invariant.
+     */
+    private static normalizePaymentOptions;
+    /**
+     * Coerce a Date-ish input (Date / number / ISO string / null /
+     * undefined) into a `Date | null`. The framework hands us strings
+     * when hydrating from SQLite, numbers when round-tripping through
+     * JSON, and Date instances from the application.
+     */
+    private static coerceDate;
+}
+export default PaymentIntent;
+//# sourceMappingURL=PaymentIntent.d.ts.map

package/dist/models/PaymentIntent.d.ts.map

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

package/dist/models/Payout.d.ts

@@ -0,0 +1,200 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { PayoutStatus } from '../types/index.js';
+export declare class Payout extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation. Nullable so global / single-
+     * tenant deployments work too.
+     */
+    tenantId: string | null;
+    /**
+     * The source {@link Payment} that funded this payout. Plain string
+     * reference (FK convention: `@foreignKey('ModelName')` would be
+     * fine within the package, but `Payment` lives in this same
+     * package — staying with a string keeps the dependency graph
+     * clean and matches how `PaymentIntent` references `Payment`).
+     */
+    paymentId: string;
+    /**
+     * The destination {@link Vendor}. Foreign-key constrained because
+     * Vendor lives in this same package and a hard reference catches
+     * dangling payouts at insert time.
+     */
+    vendorId: string;
+    /**
+     * Total funds moved, in the originating payment's native currency.
+     * Stored at decimal precision (matches `Payment.amount` /
+     * `Payment.nativeAmount` convention).
+     */
+    grossAmount: number;
+    /**
+     * Operator's take from `grossAmount`. Must equal
+     * `grossAmount - supplierNet` at save time — the model enforces
+     * the invariant via `validateAmounts()`.
+     */
+    operatorFee: number;
+    /**
+     * Net funds the supplier receives. Must equal
+     * `grossAmount - operatorFee` at save time.
+     */
+    supplierNet: number;
+    /**
+     * Native currency the funds are denominated in — payout-rail-
+     * qualified, matching `Payment.nativeCurrency` and
+     * `Vendor.payoutAddresses` keys (`USDC-base`, `BTC`, `USD-stripe`,
+     * etc.).
+     */
+    currency: string;
+    /**
+     * The `PaymentBackend` adapter id used to send the payout. For a
+     * marketplace this typically matches the source `Payment.backendId`
+     * (currency-match settlement, no conversion); other consumers can
+     * use a different backend if they bridge currencies elsewhere.
+     */
+    backendId: string;
+    /**
+     * Outgoing chain transaction hash, gateway settlement id, or
+     * (for not-yet-broadcast BTC payouts) a PSBT identifier. Set when
+     * the payout transitions to `SENT`. Empty until then.
+     */
+    backendTxRef: string;
+    /**
+     * Current status — see {@link PayoutStatus} for the state machine.
+     * Mutate via `markSent` / `markConfirmed` / `markFailed` /
+     * `resetFromFailed` rather than direct assignment so the
+     * transition invariants run.
+     */
+    status: PayoutStatus;
+    /**
+     * When the payout transitioned to `SENT`.
+     */
+    sentAt: Date | null;
+    /**
+     * When the payout transitioned to `CONFIRMED`.
+     */
+    confirmedAt: Date | null;
+    /**
+     * When the payout transitioned to `FAILED`.
+     */
+    failedAt: Date | null;
+    /**
+     * Caller-supplied human-readable failure reason. Empty for non-
+     * failed payouts. Cleared by `resetFromFailed()`.
+     */
+    failureReason: string;
+    /**
+     * Append-only operator notes — chargeback memos, manual-retry
+     * justifications, etc.
+     */
+    notes: string;
+    constructor(options?: any);
+    /**
+     * Re-coerce timestamp fields after the framework reapplies raw option
+     * values during initialization.
+     */
+    initialize(): Promise<this>;
+    isPending(): boolean;
+    isSent(): boolean;
+    isConfirmed(): boolean;
+    isFailed(): boolean;
+    /**
+     * Transition `PENDING → SENT`. Requires `backendTxRef` — without a
+     * way to identify the outgoing transaction the payout cannot be
+     * tracked further. Throws on any other source status so a confused
+     * caller can't accidentally roll back a confirmed payout.
+     */
+    markSent(backendTxRef: string): void;
+    /**
+     * Transition `SENT → CONFIRMED`. Throws if called from any other
+     * status — confirmations on a pending payout would mean a chain
+     * confirmation arrived before the application even recorded the
+     * outgoing tx, which is a code bug worth surfacing rather than
+     * silently fixing.
+     */
+    markConfirmed(): void;
+    /**
+     * Move the payout to `FAILED`. Valid from `PENDING` (couldn't even
+     * broadcast) or `SENT` (broadcast but chain rejected). Confirmed
+     * payouts cannot fail — that path is a refund, modelled separately.
+     */
+    markFailed(reason: string): void;
+    /**
+     * Operator-driven reset: move a `FAILED` payout back to `PENDING`
+     * after fixing whatever broke. Clears the failure metadata and the
+     * old `backendTxRef` (the next attempt will have a new one).
+     * Distinct from `markFailed` reflexivity — the issue spec says
+     * "failed is terminal but allows manual reset via explicit method".
+     */
+    resetFromFailed(): void;
+    /**
+     * Throws if the gross/fee/net invariant doesn't hold. Tolerates a
+     * sub-cent rounding fuzz (`EPSILON = 0.01`) to match the rest of
+     * the smrt-ledgers package's tolerance.
+     */
+    validateAmounts(): void;
+    /**
+     * Save-time state-machine + settlement guard (S5 audit #1390 round 2).
+     *
+     * `status`, `backendTxRef`, and the amount triple are all mass-assignable on
+     * the generated create/update routes. The amount invariant alone (round 1)
+     * still let a caller raw-flip a persisted payout to `CONFIRMED` / `SENT`
+     * (skipping the chain steps) or remit a `grossAmount` larger than the source
+     * Payment actually brought in — money that never arrived.
+     *
+     * This guard adds:
+     *  - **Transitions on an existing row must be legal** per
+     *    {@link PAYOUT_STATUS_TRANSITIONS} (no `pending → confirmed` skip on a
+     *    raw update, no reviving a CONFIRMED payout). Brand-new rows may be
+     *    created in any status (collection/import/query fixtures), but advancing
+     *    a persisted row is constrained to the legal edges the helpers enforce.
+     *  - **SENT requires a backendTxRef** (matches `markSent`'s invariant) so a
+     *    sent payout is always traceable, regardless of how the status was set.
+     *  - **grossAmount is capped by the source Payment** when that Payment
+     *    resolves: a payout can never remit more than the funding Payment
+     *    settled. A `paymentId` that doesn't resolve (synthetic id, Payment-less
+     *    deployment) skips the cap — the source Payment is a plain-string,
+     *    cross-model reference by design and may legitimately be a manually
+     *    recorded (non-COMPLETED) row, so the cap is best-effort rather than a
+     *    hard existence requirement.
+     *
+     * The amount-invariant check (`validateAmounts`) still runs first as the
+     * arithmetic floor.
+     */
+    save(): Promise<this>;
+    /**
+     * Resolve the AUTHORITATIVE prior status from the database (S5 audit #1390
+     * round 4). The {@link loadedPayoutStatus} WeakMap is only populated when
+     * {@link initialize} hydrated the row, so a `create({ id: <existing>,
+     * _skipLoad: true })` upsert produces an instance with a missing WeakMap
+     * entry — trusting it would treat the write as a brand-new row and skip the
+     * transition + CONFIRMED-genesis guards. Reading the persisted row directly
+     * makes a create-onto-existing behave as an update. `undefined` means no row
+     * exists (genuinely new).
+     */
+    private resolvePriorStatus;
+    /**
+     * Reject an illegal status flip on an existing row. Brand-new payouts (no
+     * prior) may start in any status — collection imports and query fixtures
+     * legitimately seed SENT / CONFIRMED rows — but advancing a *persisted* row
+     * is constrained to the legal edges the helpers enforce, so a raw update
+     * can't skip `pending → confirmed` or revive a terminal CONFIRMED.
+     */
+    private assertStatusTransition;
+    /**
+     * Cap `grossAmount` by the source {@link Payment}'s settled funds. A payout
+     * that remits more than the Payment that funded it brought in is money the
+     * operator never received.
+     *
+     * HARD requirement (S5 audit #1390 round 4, codex HIGH#3): the source Payment
+     * MUST resolve. Round 3 made the cap best-effort — a `paymentId` that didn't
+     * resolve silently skipped the cap, so a caller could remit an arbitrary
+     * `grossAmount` simply by pointing at a non-existent (or empty) payment.
+     * A payout's whole purpose is to remit funds that *arrived* via a Payment;
+     * without a resolvable source there is no funded amount to cap against, so we
+     * reject rather than skip. `PayoutCollection.createFromPayment()` always wires
+     * a real `paymentId`, so this never blocks the supported creation path.
+     */
+    private assertCappedBySourcePayment;
+    private static coerceDate;
+}
+export default Payout;
+//# sourceMappingURL=Payout.d.ts.map

package/dist/models/Payout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Payout.d.ts","sourceRoot":"","sources":["../../src/models/Payout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAmCjD,qBAsBa,MAAO,SAAQ,UAAU;IACpC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,CAAM;IAEtB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAM;IAEtB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAM;IAE1B;;;;;OAKG;IACH,MAAM,EAAE,YAAY,CAAwB;IAE5C;;OAEG;IACH,MAAM,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE3B;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;OAEG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE7B;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAM;IAE3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IA2B7B;;;OAGG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAa1C,SAAS,IAAI,OAAO;IAIpB,MAAM,IAAI,OAAO;IAIjB,WAAW,IAAI,OAAO;IAItB,QAAQ,IAAI,OAAO;IAInB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAcpC;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAUrB;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAchC;;;;;;OAMG;IACH,eAAe,IAAI,IAAI;IAevB;;;;OAIG;IACH,eAAe,IAAI,IAAI;IA0BvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwCpC;;;;;;;;;OASG;YACW,kBAAkB;IAchC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;;;;;;;;;;;;OAaG;YACW,2BAA2B;IAoCzC,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,MAAM,CAAC"}