@tallyui/pos 3.8.0 → 3.9.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, ProductCategory, TraitContext, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, RegisterSessionTransitionPayload, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
+import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, woocommerceCoupons, ProductCategory, TraitContext, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, OrderRefundEnvelope, OrderRefundResult, RegisterCommandType, RegisterCommandResult, RegisterSessionTransitionPayload, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
 export { getProductStock, withStockOverlay } from '@tallyui/core';
 export { countFresh, readFresh, watchFresh } from '@tallyui/core/rxdb';
 import * as rxdb from 'rxdb';
@@ -249,6 +249,11 @@ declare function createRepository<T extends {
     id: string;
 }>(collection: RxCollection<T>): Repository<T>;
 
+interface OrderCoupon {
+    code: string;
+    discountMinor: number;
+    discountTaxMinor: number;
+}
 interface Order {
     id: string;
     status: 'draft' | 'parked' | 'saved' | 'completed';
@@ -256,6 +261,8 @@ interface Order {
     fees?: FeeLine[];
     shipping?: ShippingLine[];
     discounts: AppliedDiscount[];
+    /** Present only after coupon replay; discountMinor excludes coupons, which are carried here. */
+    coupons?: OrderCoupon[];
     payments: Payment[];
     customer: CustomerSummary | null;
     note: string;
@@ -301,6 +308,11 @@ interface DisplayTotals {
         name: string;
         amountMinor: number;
     }>;
+    /** Present exactly when Order.coupons is. */
+    coupons?: Array<{
+        code: string;
+        amountMinor: number;
+    }>;
     orderDiscountMinor: number;
 }
 /** One line in the display mode (ADR-063): before any discount, with its own discounts as sub-rows. */
@@ -416,10 +428,18 @@ interface AddLineInput {
     taxClass?: string;
 }
 
+interface OrderCouponContext {
+    configs: ReadonlyMap<string, woocommerceCoupons.CouponDiscountConfig>;
+    productCategories: ReadonlyMap<number, {
+        id: number;
+    }[]>;
+    calcDiscountsSequentially: boolean;
+}
 interface OrderBuilderOptions {
     currency: string;
     taxContext: TaxContext;
     id?: string;
+    couponContext?: OrderCouponContext;
 }
 interface OrderBuilder {
     order$: Observable<Order>;
@@ -449,6 +469,8 @@ interface OrderBuilder {
     removePayment(paymentId: string): void;
     setCustomer(customer: CustomerSummary | null): void;
     setNote(note: string): void;
+    /** Replaces the coupon codes with their trimmed, lower-case, deduplicated list. */
+    setCoupons(codes: readonly string[]): void;
     clear(): void;
     getSnapshot(): Order;
 }
@@ -966,17 +988,40 @@ declare function movementFieldError(input: {
     reason: string;
 }): 'amount' | 'reason' | null;
 
+type PosRefundStatus = 'pending' | 'applied' | 'rejected' | 'unsent';
+interface PosRefund {
+    id: string;
+    commandId: string;
+    orderId: string;
+    sessionId: string;
+    registerId: string;
+    envelope: OrderRefundEnvelope;
+    status: PosRefundStatus;
+    result?: OrderRefundResult;
+    duplicate?: boolean;
+    error?: CommandError;
+    createdAt: string;
+    updatedAt: string;
+}
+type PosRefundCollection = RxCollection<PosRefund>;
+declare const posRefundSchema: RxJsonSchema<PosRefund>;
+/** Local-only, never replicated (ADR-080 amendment 1).
+ * Added with addCollections like cash_movements. */
+declare const posRefundCollection: () => {
+    schema: RxJsonSchema<PosRefund>;
+};
+
 /**
  * What the register should hold at close, per tender method: the session's cash float plus
  * captured payments and cash movements — never what the cashier counts. Port provenance
  * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
  *
- * **Refund attribution is deferred.** WCPOS's `attributeRefunds` debits a session's drawer for
- * refunds processed against its captured payments (by stamped session, then by a legacy
- * `refunded_amount` fallback). TallyUI has no refund model yet (ADR-032 amendment 1), so
- * `deriveExpected` covers only the float, the session's captured payment rows, and its
- * paid-in/paid-out cash movements under WCPOS's void rules.
+ * Refunds come from the till's applied `pos_refunds`, counted in the record's own `sessionId`
+ * (ADR-080 amendment 1), by the server's rule. WCPOS's `attributeRefunds` fallbacks (allocations,
+ * `refunded_amount`) are not ported: the store attributes each refund to a tender in `byMethod`.
  */
+
+type RefundRow = Pick<PosRefund, 'id' | 'sessionId' | 'status' | 'result'>;
 /** `session_id`, `kind`, `method_id`, `status` kept as WCPOS names them; money is TallyUI's integer-minor-units convention. */
 type LedgerRow = {
     session_id?: string | null;
@@ -997,18 +1042,19 @@ type Movement$1 = {
 /**
  * Expected totals per tender method: the counted float, plus every captured ledger row for the
  * session (grouped under `cash` for cash rows, else `method_id`), plus its non-voided
- * paid-in/paid-out movements.
+ * paid-in/paid-out movements, minus its applied refunds.
  *
  * A movement is excluded when its own `voided_by` is set, or when a `type: 'void'` row's
  * `voids` names its id; the `void` row itself carries no amount of its own.
  */
-declare function deriveExpected({ session, movements, ledgerRowsBySession, }: {
+declare function deriveExpected({ session, movements, ledgerRowsBySession, refunds, }: {
     session: {
         id: string;
         countedFloatMinor: number;
     };
     movements: readonly Movement$1[];
     ledgerRowsBySession: readonly LedgerRow[];
+    refunds?: readonly RefundRow[];
 }): Record<string, number>;
 
 /**
@@ -1130,7 +1176,7 @@ interface Closure {
     counted: TenderMap;
     variance: TenderMap;
     period_sales_total_minor: number;
-    /** Always 0 until TallyUI has a refund model (ADR-032 amendment 1). */
+    /** The session's applied refunds (ADR-080 amendment 1); 0 when the app passes none. */
     period_refunds_total_minor: number;
     perpetual_sales_total_minor: number;
     perpetual_refunds_total_minor: number;
@@ -1350,8 +1396,9 @@ declare function voidMovement(sessions: RegisterSessionCollection, movements: Ca
  * Only a closed session (`closed` with `closed_at_gmt`) has a closure, and a closed session is
  * final, so its existing closure is returned as it was frozen. Orders the server rejected still
  * count in the drawer, because the cash was taken.
+ * A refund still pending at close is not counted, and the Z lists it.
  */
-declare function writeClosure({ closures, register, storeKey, session, counted, otherTenders, movements, orders, tillExpected, labels, resolveCashierName, softwareVersion, timezone, }: {
+declare function writeClosure({ closures, register, storeKey, session, counted, otherTenders, movements, orders, refunds, tillExpected, labels, resolveCashierName, softwareVersion, timezone, }: {
     closures: ClosureCollection;
     /** The register document's host (`register_sessions`). */
     register: RegisterHost;
@@ -1363,6 +1410,8 @@ declare function writeClosure({ closures, register, storeKey, session, counted,
     movements: readonly CashMovement[];
     /** Any `pos_orders`; only those whose `sessionId` is this session's are counted. */
     orders: readonly PosOrder[];
+    /** `pos_refunds` rows; only this session's applied ones are counted (ADR-080 amendment 1). */
+    refunds?: readonly PosRefund[];
     tillExpected?: Record<string, number>;
     labels?: {
         register_name: string;
@@ -1896,6 +1945,8 @@ interface UseRegisterSessionOptions {
     sessions: RegisterSessionCollection | null;
     /** `cash_movements`; `null` while it opens. */
     movements: CashMovementCollection | null;
+    /** `pos_refunds` (`posRefundCollection()`); `null` while it opens. Leave it out when the app takes no refunds (ADR-080 amendment 1). */
+    refunds?: PosRefundCollection | null;
     /** `closures`; `null` while it opens. */
     closures: ClosureCollection | null;
     /** `register_commands`, created with `registerCommandCollection()`; `null` while it opens. */
@@ -2014,6 +2065,12 @@ declare function useRegisterSession(options: UseRegisterSessionOptions): {
     };
 };
 
+type SessionTarget = {
+    commands: RegisterCommandCollection;
+    sessions: RegisterSessionCollection;
+    sessionId: string;
+    now?: string;
+};
 /**
  * Applied opens fill a missing resume id; refused opens make open/counting sessions conflict.
  * Superseded rejections make open/counting sessions terminal; a conflict session leaves only by an applied open or abandon (ADR-078 decision 9); terminal/unknown states stay untouched.
@@ -2025,13 +2082,11 @@ declare function adoptRegisterResults({ commands, sessions, registerId }: {
     sessions: RegisterSessionCollection;
     registerId: string;
 }): Promise<void>;
-declare function takeOverSession({ commands, sessions, sessionId, now }: {
-    commands: RegisterCommandCollection;
-    sessions: RegisterSessionCollection;
-    sessionId: string;
-    now?: string;
+declare function takeOverSession({ commands, sessions, sessionId, now, registerContract }: SessionTarget & {
+    /** The store's register contract (`capabilities.register`); take over needs 2, and a missing value counts as below 2. */
+    registerContract?: number;
 }): Promise<void>;
-declare function abandonSession(input: Parameters<typeof takeOverSession>[0]): Promise<void>;
+declare function abandonSession(input: SessionTarget): Promise<void>;
 
 type CatalogueEntry<Doc> = {
     product: Doc;
@@ -2448,6 +2503,46 @@ interface UseOrderOutboxResult {
 /** Opens the order store for `storeKey`, runs its outbox and watches the recent orders (lifted from medusapos/app, ADR-052). */
 declare function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxResult;
 
+type OrderRefundOutcome = {
+    kind: 'applied';
+    refund: OrderRefundResult;
+    duplicate: boolean;
+} | {
+    kind: 'rejected';
+    error: CommandError;
+} | {
+    kind: 'unknown';
+    reason: string;
+    retryAfterMs?: number;
+} | {
+    kind: 'refused';
+    status: number;
+    reason: string;
+} | {
+    kind: 'unauthorized';
+};
+/** Online only, never queued (ADR-080). On unknown, resend the same envelope (same id).
+ * After rejected, a new attempt needs a new id. Refused and unauthorized mean the store did not take the batch. */
+declare function sendOrderRefund(transport: CommandTransport<OrderRefundEnvelope>, envelope: OrderRefundEnvelope): Promise<OrderRefundOutcome>;
+
+declare class RefundAnswerPendingError extends Error {
+    readonly record: PosRefund;
+    readonly code = "REFUND_ANSWER_PENDING";
+    constructor(record: PosRefund);
+}
+/** Online only, never queued; the record is written before the send.
+ * An applied record is final; a pending one is resent only with its own envelope
+ * (ADR-080 amendment 1). */
+declare function submitOrderRefund({ refunds, transport, envelope, now }: {
+    refunds: PosRefundCollection;
+    transport: CommandTransport<OrderRefundEnvelope>;
+    envelope: OrderRefundEnvelope;
+    now?: () => string;
+}): Promise<{
+    outcome: OrderRefundOutcome;
+    record: PosRefund;
+}>;
+
 /** The transport a payment terminal is reached over: hardware-neutral, not tied to any backend. */
 type PaymentTransport = 'bluetooth' | 'usb' | 'network' | 'tap_to_pay';
 type TenderView = 'select' | 'amount' | 'cancel';
@@ -2633,4 +2728,4 @@ declare function tenderVoidCollection(): {
     readonly schema: RxJsonSchema<TenderVoid>;
 };
 
-export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type CatalogueGridColumns, type CatalogueView, type CatalogueViewAction, type CatalogueViewState, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DEFAULT_CATALOGUE_VIEW_STATE, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OrderTransportContext, type OutboxState, PRODUCT_SORT_FIELDS, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type ProductSort, type ProductSortValue, RECEIPT_SCHEMA_VERSION, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptFiscal, type ReceiptLineItem, type ReceiptRegister, type ReceiptSoftware, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, RegisterNeedsUpgradeError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionConflictError, RegisterSessionOpenClosedError, RegisterSessionRequiredError, type RegisterStore, RegisterTakeOverError, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TenderVoid, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, abandonSession, activePlan, addEntryToCart, addPosOrderCollection, addRegisterSessionCollection, adoptRegisterResults, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, catalogueViewReducer, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, inCategory, initTenderState, initialTenderState, isKnownSessionStatus, isServerDecimal, labelKeys, listCategories, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, normalizeCatalogueViewState, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, productCategories, productSortValue, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, registerSessionsLogger, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, takeOverSession, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, tenderVoidCollection, tenderVoidSchema, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };
+export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type CatalogueGridColumns, type CatalogueView, type CatalogueViewAction, type CatalogueViewState, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DEFAULT_CATALOGUE_VIEW_STATE, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderCoupon, type OrderCouponContext, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderRefundOutcome, type OrderTaxTotals, type OrderTransportContext, type OutboxState, PRODUCT_SORT_FIELDS, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type PosRefund, type PosRefundCollection, type PosRefundStatus, type ProductSort, type ProductSortValue, RECEIPT_SCHEMA_VERSION, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptFiscal, type ReceiptLineItem, type ReceiptRegister, type ReceiptSoftware, type RecordedFigures, RefundAnswerPendingError, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, RegisterNeedsUpgradeError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionConflictError, RegisterSessionOpenClosedError, RegisterSessionRequiredError, type RegisterStore, RegisterTakeOverError, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TenderVoid, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, abandonSession, activePlan, addEntryToCart, addPosOrderCollection, addRegisterSessionCollection, adoptRegisterResults, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, catalogueViewReducer, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, inCategory, initTenderState, initialTenderState, isKnownSessionStatus, isServerDecimal, labelKeys, listCategories, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, normalizeCatalogueViewState, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, posRefundCollection, posRefundSchema, productCategories, productSortValue, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, registerSessionsLogger, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sendOrderRefund, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, submitOrderRefund, takeOverSession, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, tenderVoidCollection, tenderVoidSchema, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };