@happyvertical/smrt-commerce 0.30.0

package/dist/models/Contract.d.ts

@@ -0,0 +1,425 @@
+import { Meta, SmrtObject } from '@happyvertical/smrt-core';
+import { ContractStatus, ContractType } from '../types/index.js';
+/**
+ * Contract is the base class for all commercial agreements.
+ *
+ * Uses Single Table Inheritance (STI) to support different contract types:
+ * - Estimate: Quote/proposal for customer
+ * - Order: Customer purchase order
+ * - Lease: Rental/lease agreement
+ * - Agreement: Service/maintenance agreement
+ * - PurchaseOrder: Order to vendor/supplier
+ *
+ * @example
+ * ```typescript
+ * // Create a customer order
+ * const order = await contracts.create({
+ *   _meta_type: 'Order',
+ *   customerId: customer.id,
+ *   totalAmount: 1500.00,
+ *   status: ContractStatus.DRAFT
+ * });
+ *
+ * // Create a purchase order to vendor
+ * const po = await contracts.create({
+ *   _meta_type: 'PurchaseOrder',
+ *   vendorId: vendor.id,
+ *   totalAmount: 5000.00,
+ *   reference: 'PO-2024-001'
+ * });
+ * ```
+ */
+export declare class Contract extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global contracts
+     */
+    tenantId: string | null;
+    /**
+     * Contract type discriminator (STI)
+     */
+    contractType: ContractType;
+    /**
+     * Current status of the contract
+     */
+    status: ContractStatus;
+    /**
+     * Customer ID (for sales contracts: Estimate, Order, Agreement)
+     */
+    customerId: string;
+    /**
+     * Vendor ID (for purchase contracts: PurchaseOrder)
+     */
+    vendorId: string;
+    /**
+     * Subtotal before tax
+     */
+    subtotal: number;
+    /**
+     * Tax amount
+     */
+    taxAmount: number;
+    /**
+     * Total amount including tax
+     */
+    totalAmount: number;
+    /**
+     * Currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Date contract was issued
+     */
+    issueDate: Date;
+    /**
+     * Payment due date
+     */
+    dueDate: Date | null;
+    /**
+     * Expiry date (for estimates/quotes)
+     */
+    expiryDate: Date | null;
+    /**
+     * External reference number (PO number, quote number, etc.)
+     */
+    reference: string;
+    /**
+     * Internal notes
+     */
+    notes: string;
+    /**
+     * Terms and conditions
+     */
+    terms: string;
+    /**
+     * Sales channel that owns this contract.
+     *
+     * Plain string so consumers can model their own channels without an enum
+     * change (e.g. `dtc-web`, `wholesale-b2b`, `pos-store-1`, `marketplace-faire`).
+     * Empty string means "unattributed / legacy".
+     */
+    channelId: string;
+    /**
+     * STI discriminator field
+     */
+    static readonly _stiField = "contractType";
+    constructor(options?: any);
+    /**
+     * Check if contract is in draft state
+     */
+    isDraft(): boolean;
+    /**
+     * Check if contract is accepted
+     */
+    isAccepted(): boolean;
+    /**
+     * Check if contract is completed
+     */
+    isCompleted(): boolean;
+    /**
+     * Check if contract is expired (for estimates)
+     */
+    isExpired(): boolean;
+    /**
+     * Check if contract is overdue
+     */
+    isOverdue(): boolean;
+    /**
+     * Calculate and update totals from line items
+     */
+    recalculateTotals(): Promise<void>;
+    /**
+     * Capture the status the row was loaded with so the save-time transition
+     * guard can reject illegal status flips made via raw field assignment
+     * (mass-assignment on the generated update route, a stale caller, etc.).
+     * Only persisted rows carry a prior status.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Validate the status transition before persisting, then save. Inherited by
+     * every STI subtype (Estimate/Order/Lease/.../LicenseSale), so a forged
+     * `status` on any of them is caught here. LicenseSale layers its own
+     * rights-immutability guard on top via `super.save()`. See S5 audit #1390.
+     */
+    save(): Promise<this>;
+    /**
+     * Reject an illegal status flip done via raw assignment. No-op transitions
+     * and brand-new rows are always allowed.
+     */
+    protected assertContractStatusTransition(prior: ContractStatus | undefined): void;
+    /**
+     * Resolve the AUTHORITATIVE prior status (S5 audit #1390 round 5, codex
+     * MEDIUM#2). The WeakMap is only populated when {@link initialize} loaded the
+     * row from the DB; it is empty for an instance built via
+     * `collection.create({ id: <existing>, _skipLoad: true })` — the upsert path
+     * that lets a caller write onto an existing row without hydrating it. Trusting
+     * an empty WeakMap there would treat the write as a brand-new row and skip the
+     * transition guard entirely (a poisonable prior-state). Mirrors the
+     * authoritative-prior-load applied to Payment/PaymentIntent/Invoice/Payout.
+     *
+     * So when this instance carries an `id`, read the persisted row straight from
+     * the database and treat its `status` as the prior — a create-onto-existing is
+     * an update. Only when no row exists in the DB (truly new) do we fall back to
+     * the WeakMap (which is also empty then), i.e. `undefined` = genuinely new.
+     * The raw row's `status` column is single-word (no snake_case transform).
+     */
+    protected resolvePriorStatus(): Promise<ContractStatus | undefined>;
+}
+/**
+ * Estimate - Quote or proposal for a customer
+ */
+export declare class Estimate extends Contract {
+    contractType: ContractType;
+}
+/**
+ * Order - Customer purchase order
+ */
+export declare class Order extends Contract {
+    contractType: ContractType;
+}
+/**
+ * Lease - Rental or lease agreement
+ */
+export declare class Lease extends Contract {
+    contractType: ContractType;
+}
+/**
+ * Agreement - Service or maintenance agreement
+ */
+export declare class Agreement extends Contract {
+    contractType: ContractType;
+}
+/**
+ * PurchaseOrder - Order sent to vendor/supplier
+ */
+export declare class PurchaseOrder extends Contract {
+    contractType: ContractType;
+}
+/**
+ * WholesaleOrder - B2B order placed by a wholesale customer.
+ *
+ * Behaves like an Order but is conventionally created against a customer with
+ * `customerType: 'wholesale'`, uses NET-30/60 payment terms, and is delivered
+ * via the wholesale-portal channel rather than retail checkout.
+ */
+export declare class WholesaleOrder extends Contract {
+    contractType: ContractType;
+}
+/**
+ * ProductionOrder - instruction to commission goods from an internal or
+ * external factory.
+ *
+ * The manufacturing equivalent of a {@link PurchaseOrder} — but instead of
+ * buying finished inventory, you're paying to *make* it. A ProductionOrder
+ * consumes raw materials per a Bill of Materials (see
+ * `@happyvertical/smrt-manufacturing`) and produces finished SKU stock when
+ * posted (see `@happyvertical/smrt-inventory`).
+ *
+ * Carries two STI-meta fields that `ProductionService.consumeMaterials` /
+ * `runProduction` read from the loaded row to resolve which BOM to walk:
+ *
+ *   - `productId` — plain string ref to the upstream `Product` (or any
+ *     STI subtype, e.g. apparel `Style`). Used to look up the *active*
+ *     BOM via `BomService.findActiveForProduct` when no explicit
+ *     revision was pinned at the time the order was placed.
+ *   - `bomId` — optional pin to a specific BOM revision. When set, the
+ *     manufacturing service consumes against that exact revision even
+ *     if a newer BOM has become active in the meantime (keeps a
+ *     posted run from silently switching recipes mid-flight).
+ *
+ * Both fields are `Meta<string>` so the scanner routes them into the
+ * shared `_meta_data` JSON column on the Contract STI table instead of
+ * widening the base schema with manufacturing-specific columns.
+ */
+export declare class ProductionOrder extends Contract {
+    contractType: ContractType;
+    /**
+     * Plain string reference to the upstream product the order is asked
+     * to make. Cross-package id; never `@foreignKey()`. Required by
+     * `ProductionService.consumeMaterials` unless `bomId` is supplied.
+     */
+    productId: Meta<string>;
+    /**
+     * Optional explicit BOM revision the order locked to at posting
+     * time. When set, manufacturing uses this exact row even if the
+     * product's active BOM has since changed. When empty, falls back
+     * to the active BOM for `productId`.
+     */
+    bomId: Meta<string>;
+}
+/**
+ * Cart - transient order-in-progress for a shopper.
+ *
+ * Persisted as a Contract so it can hold the same line items, totals, and
+ * customer reference as a real Order, then convert in place (the application
+ * promotes the row from `_meta_type: Cart` to `_meta_type: Order` at checkout
+ * rather than copying data between tables).
+ *
+ * A Cart starts in {@link ContractStatus.DRAFT} via the base `Contract.status`
+ * default — the subclass doesn't need its own override. Application code
+ * is responsible for promoting the row to `ContractStatus.PENDING` /
+ * `ACCEPTED` at checkout time; the framework doesn't enforce a state
+ * machine on the cart → order transition.
+ */
+export declare class Cart extends Contract {
+    contractType: ContractType;
+}
+/**
+ * Snapshot of the rights granted by a {@link LicenseSale}. The fields are
+ * intentionally typed (not a generic JSON blob) so they survive schema
+ * migrations and downstream consumers (PDF templating, hash-registry
+ * publishers) can rely on the shape without re-parsing.
+ *
+ * Each field is opaque text — the values that make sense vary by
+ * industry. A stock-media marketplace might use:
+ *
+ * - `medium`: `web,print,social`
+ * - `distributionScope`: `worldwide` / `territorial`
+ * - `exclusivity`: `exclusive` / `non-exclusive`
+ * - `duration`: `perpetual` / `12-months` / `event-only`
+ * - `territory`: ISO-3166 list or `worldwide`
+ *
+ * Booleans (`sublicensing`, `derivatives`) are typed as such; everything
+ * else is a string so the model doesn't dictate vocabulary.
+ */
+export interface LicenseRightsSnapshot {
+    medium: string;
+    distributionScope: string;
+    exclusivity: string;
+    duration: string;
+    territory: string;
+    sublicensing: boolean;
+    derivatives: boolean;
+}
+/**
+ * LicenseSale — industry-neutral licensing primitive.
+ *
+ * Sits alongside the other Contract STI subtypes (Estimate, Order,
+ * Lease, Agreement, PurchaseOrder, WholesaleOrder, ProductionOrder,
+ * Cart) and represents a single sale of rights for a fee. A
+ * stock-media marketplace selling a one-time license, a music-
+ * licensing platform issuing a sync license, a code-asset marketplace
+ * granting a redistribution right — all use the same primitive.
+ *
+ * Immutability invariant: once a `LicenseSale` is saved with
+ * {@link ContractStatus.ACCEPTED}, its rights snapshot becomes
+ * frozen. Re-saving with mutated rights throws. The only legal
+ * transition out of ACCEPTED is `revoke()` (which moves status to
+ * CANCELLED without changing the rights). If a different snapshot
+ * is genuinely needed, the operator's contract is to issue a *new*
+ * LicenseSale row and let the old one stand as historical record.
+ *
+ * All subtype-specific fields are declared as `Meta<T>` so the
+ * scanner routes them into the shared `_meta_data` JSON column on
+ * the `contracts` STI table — no migration of the base schema needed
+ * to land this subtype.
+ */
+export declare class LicenseSale extends Contract {
+    contractType: ContractType;
+    /**
+     * Plain string reference to the upstream `Sku` (from
+     * `@happyvertical/smrt-products`) that this license was sold against.
+     * Cross-package id; never `@foreignKey()`.
+     */
+    skuId: Meta<string>;
+    /**
+     * Plain string reference to the `Payment` that satisfied the
+     * purchase. Cross-model reference matches the rest of the
+     * package's convention.
+     */
+    paymentId: Meta<string>;
+    /**
+     * The licensee's email address — the primary identity carried
+     * forward into PDF generation and any downstream hash-registry
+     * publication. Required; without it, downstream rights cannot be
+     * attributed.
+     */
+    licenseeEmail: Meta<string>;
+    /**
+     * Optional legal-entity name of the licensee for purchases that
+     * warrant it (typically high-tier B2B licenses). Empty string for
+     * individual-buyer licenses where the email *is* the legal identity.
+     */
+    licenseeLegalEntity: Meta<string>;
+    /**
+     * Optional ISO-3166 jurisdiction code of the licensee, captured for
+     * tax / disclosure / governing-law purposes. Empty when not
+     * required.
+     */
+    licenseeJurisdiction: Meta<string>;
+    /** Permitted media — `web,print,social`, `broadcast`, etc. */
+    rightsMedium: Meta<string>;
+    /** Distribution scope — `worldwide`, `territorial`, `private`, etc. */
+    rightsDistributionScope: Meta<string>;
+    /** Exclusivity — `exclusive` / `non-exclusive` / `co-exclusive`. */
+    rightsExclusivity: Meta<string>;
+    /** Duration — `perpetual` / `12-months` / `event-only`, etc. */
+    rightsDuration: Meta<string>;
+    /** Territory — ISO-3166 list, `worldwide`, region name, etc. */
+    rightsTerritory: Meta<string>;
+    /** Whether the licensee may sublicense the rights. */
+    rightsSublicensing: Meta<boolean>;
+    /** Whether the licensee may create derivative works. */
+    rightsDerivatives: Meta<boolean>;
+    /** URL of the signed PDF (typically a cloud-storage public URL). */
+    pdfUrl: Meta<string>;
+    /**
+     * SHA-256 of the signed PDF bytes (hex string, no `0x` prefix).
+     * Lets downstream consumers verify the PDF the licensee holds is
+     * the one this row was issued for, without re-fetching.
+     */
+    pdfHash: Meta<string>;
+    /**
+     * Optional reference to an on-chain hash-registry entry — set when
+     * the LicenseSale's `pdfHash` has been anchored on a public chain
+     * for tamper-evidence. Format is whatever the hash-registry
+     * service emits (e.g. `chain:tx-hash:log-index`). Empty for
+     * deployments that don't publish hashes on-chain.
+     */
+    onChainHashRegistryRef: Meta<string>;
+    constructor(options?: any);
+    /**
+     * Once `super.initialize()` has applied the framework's option-
+     * override pass, capture the rights snapshot if (and only if) the
+     * row arrived already issued. That's how the immutability guard
+     * tells "freshly drafting a license" (snapshot still mutable) apart
+     * from "loaded an already-issued row" (snapshot frozen).
+     */
+    initialize(): Promise<this>;
+    /**
+     * Return the current rights snapshot as a typed object. Read-only
+     * for callers — mutation should go through assignment to the
+     * individual `rights*` fields, gated by the issued-immutability
+     * guard.
+     */
+    getRightsSnapshot(): LicenseRightsSnapshot;
+    /**
+     * Revoke an issued license — moves status to `CANCELLED` without
+     * touching the rights snapshot (which stays frozen). Throws if
+     * called on a non-issued license; a draft license should be
+     * deleted, not revoked.
+     */
+    revoke(): void;
+    /**
+     * Save with the immutability check: if the row was loaded with
+     * `ACCEPTED` status, the rights snapshot at save time must match
+     * the snapshot at load time. Anything else means an out-of-band
+     * mutation crept in and we surface it instead of letting the row
+     * drift silently.
+     *
+     * Newly-drafted licenses (where the row was constructed without
+     * `ACCEPTED` status) capture their snapshot at the moment the
+     * caller transitions to `ACCEPTED` and saves — `validateImmutable`
+     * picks that up post-save on the next call.
+     */
+    save(): Promise<this>;
+    /**
+     * Compare the current rights against the captured snapshot
+     * (populated either at load time by `initialize` or at first
+     * issuance by `save`). Throws on mismatch.
+     */
+    private validateImmutable;
+    private serializeRightsSnapshot;
+}
+export default Contract;
+//# sourceMappingURL=Contract.d.ts.map

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

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

package/dist/models/ContractLineItem.d.ts

@@ -0,0 +1,92 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * ContractLineItem represents a single line item on a contract.
+ *
+ * Line items contain the details of what is being sold/purchased,
+ * including quantity, pricing, and optional subscription details.
+ *
+ * @example
+ * ```typescript
+ * const lineItem = await lineItems.create({
+ *   contractId: order.id,
+ *   description: 'Widget Pro',
+ *   quantity: 10,
+ *   unitPrice: 49.99,
+ *   taxRate: 0.08
+ * });
+ * ```
+ */
+export declare class ContractLineItem extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global line items
+     */
+    tenantId: string | null;
+    /**
+     * Parent contract
+     */
+    contractId: string;
+    /**
+     * Item description
+     */
+    description: string;
+    /**
+     * Quantity ordered
+     */
+    quantity: number;
+    /**
+     * Unit price before discount
+     */
+    unitPrice: number;
+    /**
+     * Discount amount (flat, not percentage)
+     */
+    discount: number;
+    /**
+     * Tax rate as decimal (e.g., 0.08 for 8%)
+     */
+    taxRate: number;
+    /**
+     * Calculated line amount (qty * price - discount + tax)
+     */
+    amount: number;
+    /**
+     * Optional product reference (cross-package, plain string)
+     */
+    productId: string;
+    /**
+     * SKU or item code
+     */
+    sku: string;
+    /**
+     * Start date (for lease/subscription items)
+     */
+    startDate: Date | null;
+    /**
+     * End date (for lease/subscription items)
+     */
+    endDate: Date | null;
+    /**
+     * Billing period (for subscriptions: 'monthly', 'yearly', etc.)
+     */
+    billingPeriod: string;
+    /**
+     * Sort order within the contract
+     */
+    sortOrder: number;
+    constructor(options?: any);
+    /**
+     * Calculate the line amount
+     */
+    calculateAmount(): number;
+    /**
+     * Check if this is a subscription/recurring item
+     */
+    isRecurring(): boolean;
+    /**
+     * Check if subscription is active
+     */
+    isSubscriptionActive(): boolean;
+}
+export default ContractLineItem;
+//# sourceMappingURL=ContractLineItem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ContractLineItem.d.ts","sourceRoot":"","sources":["../../src/models/ContractLineItem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAOa,gBAAiB,SAAQ,UAAU;IAC9C;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAO;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAO;IAExB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAO;IAEvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAO;IAEtB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAO;IAErB;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAM;IAEjB;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;OAEG;IACH,OAAO,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE5B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAK;gBAEV,OAAO,GAAE,GAAQ;IAoB7B;;OAEG;IACH,eAAe,IAAI,MAAM;IAMzB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,oBAAoB,IAAI,OAAO;CAUhC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/models/Customer.d.ts

@@ -0,0 +1,98 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { Address, CustomerStatus, CustomerType } from '../types/index.js';
+/**
+ * Customer represents the customer role for a Profile.
+ *
+ * One Profile can have multiple Customer records (e.g., different business contexts).
+ * Customer stores customer-specific data like credit limits and payment terms.
+ *
+ * @example
+ * ```typescript
+ * const customer = await customers.create({
+ *   profileId: 'profile-uuid',
+ *   creditLimit: 10000,
+ *   paymentTerms: 'Net 30'
+ * });
+ * ```
+ */
+export declare class Customer extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global customers
+     */
+    tenantId: string | null;
+    /**
+     * Reference to smrt-profiles Profile
+     * Plain string for cross-package reference
+     */
+    profileId: string;
+    /**
+     * Maximum credit extended to this customer
+     */
+    creditLimit: number;
+    /**
+     * Payment terms (e.g., "Net 30", "Due on receipt", "2/10 Net 30")
+     */
+    paymentTerms: string;
+    /**
+     * Whether customer is exempt from tax
+     */
+    taxExempt: boolean;
+    /**
+     * Tax identification number
+     *
+     * Sensitive (#1540): PII excluded from generated API/MCP responses and
+     * rejected as a `where` filter key.
+     */
+    taxId: string;
+    /**
+     * Default shipping address
+     */
+    defaultShippingAddress: Address;
+    /**
+     * Default billing address
+     */
+    defaultBillingAddress: Address;
+    /**
+     * Customer status
+     */
+    status: CustomerStatus;
+    /**
+     * Customer classification — DTC, wholesale, or retail.
+     *
+     * Drives channel access (wholesale portal vs. storefront vs. POS), default
+     * price tier, and credit terms. Defaults to DTC for backwards compatibility.
+     */
+    customerType: CustomerType;
+    /**
+     * Internal notes about this customer
+     */
+    notes: string;
+    constructor(options?: any);
+    /**
+     * Convenience predicate: is this a wholesale customer?
+     */
+    isWholesale(): boolean;
+    /**
+     * Check if customer is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if customer has available credit
+     */
+    hasAvailableCredit(amount: number): boolean;
+    /**
+     * Get the profile ID for external lookup.
+     *
+     * To get the actual Profile object, use the ProfileCollection from smrt-profiles:
+     * ```typescript
+     * const profiles = await ProfileCollection.create(options);
+     * const profile = await profiles.get({ id: customer.profileId });
+     * ```
+     *
+     * @returns The profile ID or empty string if not set
+     */
+    getProfileId(): string;
+}
+export default Customer;
+//# sourceMappingURL=Customer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Customer.d.ts","sourceRoot":"","sources":["../../src/models/Customer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,KAAK,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,qBAMa,QAAS,SAAQ,UAAU;IACtC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;OAGG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;OAEG;IACH,YAAY,EAAE,MAAM,CAAM;IAE1B;;OAEG;IACH,SAAS,EAAE,OAAO,CAAS;IAE3B;;;;;OAKG;IAEH,KAAK,EAAE,MAAM,CAAM;IAEnB;;OAEG;IACH,sBAAsB,EAAE,OAAO,CAAM;IAErC;;OAEG;IACH,qBAAqB,EAAE,OAAO,CAAM;IAEpC;;OAEG;IACH,MAAM,EAAE,cAAc,CAAyB;IAE/C;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAoB;IAE9C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IA4B7B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK3C;;;;;;;;;;OAUG;IACH,YAAY,IAAI,MAAM;CAGvB;AAED,eAAe,QAAQ,CAAC"}