@happyvertical/smrt-commerce 0.30.0

package/dist/models/Fulfillment.d.ts

@@ -0,0 +1,99 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { Address, FulfillmentStatus, FulfillmentType } from '../types/index.js';
+/**
+ * Fulfillment tracks the delivery or completion of contract items.
+ *
+ * A contract can have multiple fulfillments (e.g., partial shipments).
+ * Each fulfillment tracks what was delivered and when.
+ *
+ * @example
+ * ```typescript
+ * const fulfillment = await fulfillments.create({
+ *   contractId: order.id,
+ *   fulfillmentType: FulfillmentType.SHIPMENT,
+ *   trackingNumber: 'UPS-123456789',
+ *   carrier: 'UPS',
+ *   shippingAddress: {
+ *     street1: '123 Main St',
+ *     city: 'Anytown',
+ *     state: 'CA',
+ *     postalCode: '90210',
+ *     country: 'US'
+ *   }
+ * });
+ * ```
+ */
+export declare class Fulfillment extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global fulfillments
+     */
+    tenantId: string | null;
+    /**
+     * Parent contract being fulfilled
+     */
+    contractId: string;
+    /**
+     * Type of fulfillment
+     */
+    fulfillmentType: FulfillmentType;
+    /**
+     * Current fulfillment status
+     */
+    status: FulfillmentStatus;
+    /**
+     * Tracking number from carrier
+     */
+    trackingNumber: string;
+    /**
+     * Shipping carrier name
+     */
+    carrier: string;
+    /**
+     * Shipping destination address
+     */
+    shippingAddress: Address;
+    /**
+     * When the shipment was sent
+     */
+    shippedAt: Date | null;
+    /**
+     * When the shipment was delivered
+     */
+    deliveredAt: Date | null;
+    /**
+     * Estimated delivery date
+     */
+    estimatedDelivery: Date | null;
+    /**
+     * Notes about this fulfillment
+     */
+    notes: string;
+    constructor(options?: any);
+    /**
+     * Check if fulfillment is complete
+     */
+    isDelivered(): boolean;
+    /**
+     * Check if fulfillment is in transit
+     */
+    isInTransit(): boolean;
+    /**
+     * Check if fulfillment is pending
+     */
+    isPending(): boolean;
+    /**
+     * Mark as shipped
+     */
+    markShipped(trackingNumber?: string, carrier?: string): void;
+    /**
+     * Mark as delivered
+     */
+    markDelivered(): void;
+    /**
+     * Cancel fulfillment
+     */
+    cancel(): void;
+}
+export default Fulfillment;
+//# sourceMappingURL=Fulfillment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Fulfillment.d.ts","sourceRoot":"","sources":["../../src/models/Fulfillment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,EACL,KAAK,OAAO,EACZ,iBAAiB,EACjB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAMa,WAAY,SAAQ,UAAU;IACzC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,eAAe,EAAE,eAAe,CAA4B;IAE5D;;OAEG;IACH,MAAM,EAAE,iBAAiB,CAA6B;IAEtD;;OAEG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,eAAe,EAAE,OAAO,CAAM;IAE9B;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;OAEG;IACH,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEtC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAoB7B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAO5D;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,MAAM,IAAI,IAAI;CAGf;AAED,eAAe,WAAW,CAAC"}

package/dist/models/FulfillmentLineItem.d.ts

@@ -0,0 +1,42 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * FulfillmentLineItem tracks which contract line items are included
+ * in a specific fulfillment and how much was fulfilled.
+ *
+ * This allows partial fulfillment - e.g., shipping 5 of 10 items ordered.
+ *
+ * @example
+ * ```typescript
+ * const fulfillmentItem = await fulfillmentItems.create({
+ *   fulfillmentId: fulfillment.id,
+ *   contractLineItemId: lineItem.id,
+ *   quantityFulfilled: 5  // of 10 ordered
+ * });
+ * ```
+ */
+export declare class FulfillmentLineItem extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global fulfillment line items
+     */
+    tenantId: string | null;
+    /**
+     * Parent fulfillment
+     */
+    fulfillmentId: string;
+    /**
+     * Contract line item being fulfilled
+     */
+    contractLineItemId: string;
+    /**
+     * Quantity fulfilled in this fulfillment
+     */
+    quantityFulfilled: number;
+    /**
+     * Notes about this line item
+     */
+    notes: string;
+    constructor(options?: any);
+}
+export default FulfillmentLineItem;
+//# sourceMappingURL=FulfillmentLineItem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FulfillmentLineItem.d.ts","sourceRoot":"","sources":["../../src/models/FulfillmentLineItem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAGxE;;;;;;;;;;;;;;GAcG;AACH,qBAMa,mBAAoB,SAAQ,UAAU;IACjD;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IAEH,kBAAkB,EAAE,MAAM,CAAM;IAEhC;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAO;IAEhC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;CAW9B;AAED,eAAe,mBAAmB,CAAC"}

package/dist/models/Invoice.d.ts

@@ -0,0 +1,326 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { InvoiceStatus, RecognizeRevenueOptions } from '../types/index.js';
+/**
+ * Invoice represents a bill sent to a customer for goods or services.
+ *
+ * Invoices are distinct from Contracts - a Contract is an agreement,
+ * while an Invoice is the billing document requesting payment.
+ *
+ * Invoices integrate with:
+ * - `@happyvertical/smrt-ledgers` for revenue recognition (double-entry accounting)
+ * - `@happyvertical/accounting` SDK for syncing with external providers (QBO, Stripe)
+ *
+ * @example
+ * ```typescript
+ * // Create an invoice
+ * const invoice = await invoices.create({
+ *   customerId: customer.id,
+ *   invoiceNumber: await invoices.generateInvoiceNumber(),
+ *   issueDate: new Date(),
+ *   dueDate: addDays(new Date(), 30),
+ *   subtotal: 1000,
+ *   taxAmount: 50,
+ *   totalAmount: 1050,
+ *   currency: 'CAD'
+ * });
+ *
+ * // Recognize revenue in ledger
+ * await invoice.recognizeRevenue({
+ *   arAccountId: arAccount.id,
+ *   revenueAccountId: revenueAccount.id,
+ *   taxAccountId: taxAccount.id
+ * });
+ * ```
+ */
+export declare class Invoice extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global invoices
+     */
+    tenantId: string | null;
+    /**
+     * Customer this invoice is for
+     */
+    customerId: string;
+    /**
+     * Optional link to Contract (cross-package reference)
+     */
+    contractId: string;
+    /**
+     * Invoice number (e.g., INV-2025-0001)
+     * Generated via InvoiceCollection.generateInvoiceNumber()
+     */
+    invoiceNumber: string;
+    /**
+     * External reference (e.g., customer PO number)
+     */
+    reference: string;
+    /**
+     * Date invoice was issued
+     */
+    issueDate: Date;
+    /**
+     * Payment due date
+     */
+    dueDate: Date;
+    /**
+     * Date invoice was fully paid
+     */
+    paidDate: Date | null;
+    /**
+     * Subtotal before tax
+     */
+    subtotal: number;
+    /**
+     * Tax amount
+     */
+    taxAmount: number;
+    /**
+     * Total amount due (subtotal + tax)
+     */
+    totalAmount: number;
+    /**
+     * Amount paid (sum of PaymentAllocations)
+     */
+    amountPaid: number;
+    /**
+     * Currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Current invoice status
+     */
+    status: InvoiceStatus;
+    /**
+     * Journal ID for AR recognition (cross-package ref to smrt-ledgers)
+     */
+    arJournalId: string;
+    /**
+     * Journal ID for revenue recognition (cross-package ref to smrt-ledgers)
+     */
+    revenueJournalId: string;
+    /**
+     * External ID in accounting provider (e.g., QBO invoice ID)
+     */
+    externalId: string;
+    /**
+     * Customer's external ID in accounting provider.
+     * Used to link invoice to customer in external system.
+     */
+    customerExternalId: string;
+    /**
+     * Accounting provider name ('quickbooks' | 'stripe' | etc.)
+     */
+    externalProvider: string;
+    /**
+     * When invoice was last synced to provider
+     */
+    syncedAt: Date | null;
+    /**
+     * When invoice was sent to customer
+     */
+    sentAt: Date | null;
+    /**
+     * When customer viewed the invoice
+     */
+    viewedAt: Date | null;
+    /**
+     * Number of payment reminders sent
+     */
+    remindersSent: number;
+    /**
+     * When last reminder was sent
+     */
+    lastReminderAt: Date | null;
+    /**
+     * Internal notes (not shown to customer)
+     */
+    notes: string;
+    /**
+     * Notes shown to customer on invoice
+     */
+    customerNotes: string;
+    /**
+     * Payment terms text
+     */
+    terms: string;
+    constructor(options?: any);
+    /**
+     * Capture the persisted 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 a generated update route, a stale caller,
+     * etc.). Only rows that already exist in the database carry a "prior"
+     * status — freshly-constructed (not-yet-saved) invoices have no prior and
+     * may start in any status.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Recompute and validate financial fields before every write so forged
+     * totals, negative amounts, and illegal status flips can't be persisted via
+     * raw mass-assignment on the generated CRUD routes.
+     *
+     * Behaviour:
+     *  - **Totals are authoritative from line items.** When the invoice is
+     *    persisted and has line items, `subtotal` / `taxAmount` / `totalAmount`
+     *    are recomputed from those items, overriding whatever the caller sent.
+     *    This blocks "create real line items but claim a tiny total" forgery.
+     *  - **Without line items**, the caller-supplied totals are accepted but the
+     *    `totalAmount === subtotal + taxAmount` arithmetic invariant is enforced.
+     *  - **amountPaid is derived/validated.** When persisted, it is recomputed
+     *    from PaymentAllocations rather than trusted from the caller. It may
+     *    never exceed `totalAmount` (beyond rounding tolerance).
+     *  - **Non-negativity** is enforced on all four amounts.
+     *  - **Status transitions** are validated against the prior persisted status.
+     */
+    save(): Promise<this>;
+    /**
+     * Resolve the AUTHORITATIVE prior status (S5 audit #1390 round 4). The
+     * {@link loadedInvoiceStatus} WeakMap is only populated when {@link initialize}
+     * hydrated the row, so a `create({ id: <existing>, _skipLoad: true })` upsert
+     * yields an instance whose WeakMap entry is missing — trusting it would treat
+     * the write as a brand-new row and skip the transition guard entirely. Read
+     * the persisted row's status directly so a create-onto-existing is correctly
+     * treated as an update. `undefined` means no row exists (genuinely new).
+     */
+    private resolvePriorStatus;
+    /**
+     * Recompute subtotal/tax/total from line items (when present) and derive
+     * amountPaid from PaymentAllocations. Falls back to the arithmetic invariant
+     * when the invoice has no line items. Tolerant of smrt-ledgers being absent
+     * (the dynamic imports stay inside the package).
+     */
+    private recomputeAmountsForSave;
+    /**
+     * After amounts are recomputed and amountPaid is re-derived from allocations,
+     * assert the persisted `status` is consistent with the derived
+     * amountPaid-vs-totalAmount relationship. This blocks the raw
+     * `SENT → PAID with amountPaid=0` flip (and its inverse, claiming PARTIAL/SENT
+     * while fully allocated) that the status-transition map alone permits because
+     * SENT → PAID is a structurally legal edge.
+     *
+     * Only enforced for the payment-derived statuses (PAID / PARTIAL and the
+     * unpaid open states SENT / VIEWED). Lifecycle statuses that aren't a
+     * function of amountPaid — DRAFT, OVERDUE, CANCELLED, WRITTEN_OFF — are left
+     * to their own transition rules.
+     */
+    private assertPaymentStatusConsistent;
+    /**
+     * Enforce `totalAmount === subtotal + taxAmount` (within rounding tolerance).
+     * Used when the invoice has no line items to recompute from.
+     */
+    private assertTotalArithmetic;
+    /**
+     * Reject negative financial values and an amountPaid that exceeds the total
+     * (beyond rounding tolerance — overpayment is modelled elsewhere, not by
+     * letting amountPaid float above the invoice total).
+     */
+    private assertNonNegativeAmounts;
+    /**
+     * 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 transitions (status unchanged) and brand-new rows are always allowed.
+     */
+    private assertStatusTransition;
+    /**
+     * Check if invoice is a draft
+     */
+    isDraft(): boolean;
+    /**
+     * Check if invoice has been sent
+     */
+    isSent(): boolean;
+    /**
+     * Check if invoice is fully paid
+     */
+    isPaid(): boolean;
+    /**
+     * Check if invoice is partially paid
+     */
+    isPartial(): boolean;
+    /**
+     * Check if invoice is overdue
+     */
+    isOverdue(): boolean;
+    /**
+     * Get remaining amount due
+     */
+    getAmountDue(): number;
+    /**
+     * Mark invoice as sent
+     */
+    markSent(): void;
+    /**
+     * Record that the invoice was viewed by the customer.
+     *
+     * This method is idempotent - calling it multiple times will only
+     * record the first view time. Status only transitions to VIEWED if
+     * the current status is SENT (other statuses like PARTIAL or PAID
+     * are preserved).
+     */
+    markViewed(): void;
+    /**
+     * Update payment amount and status.
+     *
+     * Called when PaymentAllocations change. Handles both forward transitions
+     * (SENT → PARTIAL → PAID) and reversals (PAID → PARTIAL → original status).
+     *
+     * Terminal statuses (CANCELLED, WRITTEN_OFF) are not modified.
+     */
+    updatePaymentStatus(amountPaid: number): void;
+    /**
+     * Cancel the invoice
+     */
+    cancel(): void;
+    /**
+     * Write off the invoice (bad debt)
+     */
+    writeOff(): void;
+    /**
+     * Recognize revenue and create AR journal entry.
+     *
+     * Creates a balanced journal entry in smrt-ledgers:
+     * - Debit: Accounts Receivable (assets increase)
+     * - Credit: Revenue (revenue increases)
+     * - Credit: Tax Payable (liability increases, if taxAmount > 0)
+     *
+     * **Note**: This method saves the invoice after setting arJournalId.
+     *
+     * @param options - Account IDs for the journal entry
+     * @returns The created journal
+     *
+     * @example
+     * ```typescript
+     * const journal = await invoice.recognizeRevenue({
+     *   arAccountId: '1120',
+     *   revenueAccountId: '4100',
+     *   taxAccountId: '2130'
+     * });
+     * ```
+     */
+    recognizeRevenue(options: RecognizeRevenueOptions): Promise<any>;
+    /**
+     * Get the AR journal entry (if revenue was recognized)
+     */
+    getArJournal(): Promise<any | null>;
+    /**
+     * Convert to InvoiceInput for SDK accounting provider sync.
+     *
+     * Fetches line items and maps all fields to the format expected
+     * by @happyvertical/accounting providers.
+     *
+     * @returns InvoiceInput compatible with @happyvertical/accounting
+     *
+     * @example
+     * ```typescript
+     * const provider = await getAccountingProvider({ type: 'quickbooks', ... });
+     * const input = await invoice.toAccountingInput();
+     * const result = await provider.invoices.push(input);
+     * invoice.externalId = result.externalId;
+     * invoice.syncedAt = result.syncedAt;
+     * await invoice.save();
+     * ```
+     */
+    toAccountingInput(): Promise<any>;
+}
+export default Invoice;
+//# sourceMappingURL=Invoice.d.ts.map

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

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

package/dist/models/InvoiceLineItem.d.ts

@@ -0,0 +1,120 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * InvoiceLineItem represents a single line item on an invoice.
+ *
+ * Line items contain details of what is being billed, including
+ * quantity, pricing, and optional source tracking (e.g., from ad campaigns).
+ *
+ * @example
+ * ```typescript
+ * const lineItem = await lineItems.create({
+ *   invoiceId: invoice.id,
+ *   description: 'Display Advertising - Summer Campaign',
+ *   quantity: 50000,  // impressions
+ *   unitPrice: 0.01,  // per impression
+ *   taxRate: 0.05,
+ *   sourceType: 'campaign',
+ *   sourceId: 'campaign-uuid',
+ *   periodStart: new Date('2025-06-01'),
+ *   periodEnd: new Date('2025-06-30')
+ * });
+ * ```
+ */
+export declare class InvoiceLineItem extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global invoice line items
+     */
+    tenantId: string | null;
+    /**
+     * Parent invoice
+     */
+    invoiceId: string;
+    /**
+     * Item description
+     */
+    description: string;
+    /**
+     * SKU or item code
+     */
+    sku: string;
+    /**
+     * Quantity (e.g., impressions, hours, units)
+     */
+    quantity: number;
+    /**
+     * Unit price before discount
+     */
+    unitPrice: number;
+    /**
+     * Discount amount (flat, not percentage)
+     */
+    discount: number;
+    /**
+     * Tax rate as decimal (e.g., 0.05 for 5%)
+     */
+    taxRate: number;
+    /**
+     * Calculated line amount
+     */
+    amount: number;
+    /**
+     * Type of source ('campaign' | 'contract' | 'manual' | etc.)
+     */
+    sourceType: string;
+    /**
+     * ID of the source (e.g., campaign ID, contract ID)
+     */
+    sourceId: string;
+    /**
+     * Service period start (for time-based billing)
+     */
+    periodStart: Date | null;
+    /**
+     * Service period end (for time-based billing)
+     */
+    periodEnd: Date | null;
+    /**
+     * Revenue account ID (cross-package ref to smrt-ledgers)
+     * Used for revenue recognition to specific accounts
+     */
+    revenueAccountId: string;
+    /**
+     * Sort order within the invoice
+     */
+    sortOrder: number;
+    constructor(options?: any);
+    /**
+     * Calculate the line amount.
+     *
+     * Formula: (quantity * unitPrice - discount) * (1 + taxRate)
+     *
+     * Tax is calculated on the discounted subtotal. This follows the common
+     * "discount before tax" approach used in most North American jurisdictions.
+     * For jurisdictions requiring different tax calculation methods, override
+     * this method or calculate amounts externally.
+     */
+    calculateAmount(): number;
+    /**
+     * Get subtotal (before tax)
+     */
+    getSubtotal(): number;
+    /**
+     * Get tax amount
+     */
+    getTaxAmount(): number;
+    /**
+     * Check if line item has source tracking
+     */
+    hasSource(): boolean;
+    /**
+     * Check if line item has a service period
+     */
+    hasPeriod(): boolean;
+    /**
+     * Convert to line item format for SDK accounting provider
+     */
+    toAccountingLineItem(): any;
+}
+export default InvoiceLineItem;
+//# sourceMappingURL=InvoiceLineItem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InvoiceLineItem.d.ts","sourceRoot":"","sources":["../../src/models/InvoiceLineItem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAMa,eAAgB,SAAQ,UAAU;IAC7C;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAM;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAK;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAK;IAEtB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAK;IAErB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAK;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;IAMnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAM;IAEtB;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAM9B;;;OAGG;IAEH,gBAAgB,EAAE,MAAM,CAAM;IAE9B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAK;gBAEV,OAAO,GAAE,GAAQ;IAsB7B;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAMzB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,oBAAoB,IAAI,GAAG;CAa5B;AAED,eAAe,eAAe,CAAC"}