@tallyui/pos 3.5.3 → 3.7.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, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
+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';
 export { getProductStock, withStockOverlay } from '@tallyui/core';
 export { countFresh, readFresh, watchFresh } from '@tallyui/core/rxdb';
 import * as rxdb from 'rxdb';
@@ -534,6 +534,28 @@ declare function useParkedSales(drafts: RxCollection | undefined): {
     discard: (id: string) => Promise<void>;
 };
 
+/** WCPOS receipt data schema version these blocks follow (wiki: fiscal groundwork, receipt identity and QR §2). */
+declare const RECEIPT_SCHEMA_VERSION = "1.4.0";
+/** 1.4 `software`: which software produced the receipt. */
+interface ReceiptSoftware {
+    name: string;
+    plugin_version: string;
+    app_version: string;
+    app_build: string;
+    platform: string;
+}
+/** 1.4 `register`: `{ id: '', name: '' }` when there is none. */
+interface ReceiptRegister {
+    id: string;
+    name: string;
+}
+/** 1.4 `fiscal` identity fields a till can know. Sale time, zone and counter come with the per-register sale counter (#475). */
+interface ReceiptFiscal {
+    document_type: 'sale' | 'refund' | 'void' | 'cancellation' | 'closure' | 'x_report';
+    is_reprint: boolean;
+    reprint_count: number;
+    qr_payload: string;
+}
 interface ReceiptLineItem {
     name: string;
     sku: string;
@@ -549,6 +571,10 @@ interface ReceiptLineItem {
     }[];
 }
 interface ReceiptData {
+    schemaVersion: string;
+    software: ReceiptSoftware;
+    register: ReceiptRegister;
+    fiscal: ReceiptFiscal;
     header: {
         storeName: string;
         storeAddress?: string;
@@ -602,6 +628,9 @@ interface ReceiptConfig {
     storeAddress?: string;
     cashier?: string;
     register?: string;
+    registerName?: string;
+    software?: Partial<ReceiptSoftware>;
+    fiscal?: Partial<ReceiptFiscal>;
     taxLabels?: Record<number, string>;
 }
 
@@ -882,27 +911,10 @@ declare class PosOrderOpenClosedError extends Error {
     constructor(databaseName: string);
 }
 /**
- * Adds `pos_orders` to `db` and resolves once no order of an older version is left to migrate. The one
- * sanctioned way to open it (ADR-032 amendment 2). On DM4 it rejects after the migration has
- * stopped and closes the collection, so the app can surface the error and open again; it never
- * deletes an order.
- *
- * RxDB 17.5.0 trusts the status its last migration stored: a leftover `ERROR` rejects
- * `migratePromise` at once while the migration keeps running (a close then interrupts it), and a
- * `DONE` left before a rollback resolves it before the older version's new orders have moved. So the
- * collection is added without `autoMigrate` and the migration is started and awaited directly: RxDB
- * 17.5's `startMigration()` ignores a leftover status (only `migratePromise()` trusts a leftover
- * `DONE`), which lets a rolled-back or interrupted run migrate again and recovers its orders. The
- * status is reset first so its record describes the new run, and a failed run's checkpoint is
- * removed (RxDB bug 1); never an order or its storage.
- *
- * A close waits for the open, up to `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`, and cancels a running
- * migration (RxDB 17.5). Called once the database's close has begun, when the close cancels its
- * migration, or when the close stops waiting, it rejects with `PosOrderOpenClosedError`
- * (`code: 'POS_ORDER_OPEN_CLOSED'`) before any further write: reopen and call it again. Any other
- * rejection (DM4, a storage error) is a real failure.
- *
- * `closeWaitMs` is for tests only; the first open on a database sets it for that database's close.
+ * Adds `pos_orders` to `db` and resolves once no order of an older version is left to migrate.
+ * On DM4 it rejects after the migration has stopped and closes the collection. It rejects with
+ * `PosOrderOpenClosedError` when the database is closing. `closeWaitMs` is for tests only.
+ * See `openMigratedCollection` for the migration and close mechanism.
  */
 declare function addPosOrderCollection(db: RxDatabase, closeWaitMs?: number): Promise<RxCollection<PosOrder>>;
 
@@ -921,6 +933,7 @@ declare function getDeviceId(storage: {
  * session closed (`lateSessionId`) or with local warnings (whatever the sync status), or pending with a `commandId` in
  * `stuckCommandIds` (the outbox's `OutboxState.stuck`: the store keeps failing it), newest first.
  * A warning code this till version doesn't know is not shown here (`knownWarnings`). Never changes `orders`.
+ * `register_session_unknown` is not shown, because the store counts the order once its session arrives (ADR-078).
  */
 declare function needsAttention(orders: PosOrder[], options?: {
     stuckCommandIds?: readonly string[];
@@ -1042,7 +1055,7 @@ declare const denominations: Record<string, number[]>;
 /**
  * The register's local collections (ADR-032): sessions, cash movements and closures. Port
  * provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`, where they are at versions 1, 0
- * and 1; each starts at version 0 here.
+ * and 1; sessions are at version 1 here (ADR-078), movements and closures at version 0.
  *
  * All three are local only, like `pos_orders`: the app creates them and never replicates them
  * (a replicated collection must never take local writes, #53). WCPOS's outbox fields
@@ -1061,7 +1074,10 @@ interface RegisterSession {
     register_id: string;
     /** The app's neutral store key (see `bindRegister`). */
     store_key?: string | null;
-    status: 'open' | 'counting' | 'closed';
+    /** Stored status is an open string so a later local state costs no migration (ADR-078 decision 9); the union names today's states. */
+    status: 'open' | 'counting' | 'closed' | 'conflict' | 'superseded';
+    /** The store session this local id was resumed as (ADR-078 decision 2), never the session that superseded it; null until a resume. */
+    server_session_id?: string | null;
     /** The store's day the session opened, `yyyy-MM-dd`. */
     business_day?: string;
     opened_at_gmt: string;
@@ -1132,16 +1148,31 @@ interface Closure {
 }
 declare const registerSessionSchema: RxJsonSchema<RegisterSession>;
 /**
- * Create `register_sessions` with this: the register document (`register-document.ts`) is a
- * local document on this collection, since a Tally database has no database-level ones.
+ * @deprecated Use `addRegisterSessionCollection` to open register_sessions.
+ * Kept so old callers compile but fail at start instead of migrating on RxDB's own path.
  */
-declare function registerSessionCollection(): {
-    readonly schema: RxJsonSchema<RegisterSession>;
-    readonly localDocuments: true;
-};
+declare function registerSessionCollection(): never;
 declare const cashMovementSchema: RxJsonSchema<CashMovement>;
 declare const closureSchema: RxJsonSchema<Closure>;
 
+/** `addRegisterSessionCollection`'s logger: attach a sink to see dropped status writes during close. */
+declare const registerSessionsLogger: Logger;
+/** How long a close waits for the open; see `openMigratedCollection` for the cancellation mechanism. */
+declare const REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS = 10000;
+/** The database is closing; no session is lost. Reopen the database and call the opener again. */
+declare class RegisterSessionOpenClosedError extends Error {
+    readonly databaseName: string;
+    readonly code = "REGISTER_SESSION_OPEN_CLOSED";
+    constructor(databaseName: string);
+}
+/**
+ * Adds `register_sessions` and resolves once no older session is left to migrate; the register
+ * document, a local document, is kept. On DM4 it rejects after migration stops and closes the collection.
+ * A closing database rejects with `RegisterSessionOpenClosedError`; `closeWaitMs` is for tests only.
+ * See `openMigratedCollection` for the migration and close mechanism.
+ */
+declare function addRegisterSessionCollection(db: RxDatabase, closeWaitMs?: number): Promise<RxCollection<RegisterSession>>;
+
 type RegisterHost = RxLocalDocumentMutation<any>;
 type RegisterCounters = {
     last_closure_number: number;
@@ -1225,6 +1256,11 @@ declare class RegisterSessionRequiredError extends Error {
 declare class RegisterSessionClosedError extends Error {
     constructor();
 }
+/** A stored session status outside the known set (written by a later build); its message can be shown to a cashier as it is. */
+declare class RegisterNeedsUpgradeError extends Error {
+    readonly code = "REGISTER_NEEDS_UPGRADE";
+    constructor();
+}
 /** ADR-068 6a: movement amounts must be safe integers, positive for paid_in/paid_out and zero for no_sale. */
 declare class RegisterMovementAmountError extends Error {
     constructor(type: 'paid_in' | 'paid_out' | 'no_sale', amountMinor: number);
@@ -1245,6 +1281,8 @@ declare class RegisterMovementStrandedError extends Error {
         session_id: string;
     });
 }
+/** Whether this build knows the stored session status. */
+declare function isKnownSessionStatus(status: string): boolean;
 declare const openSessionSelector: {
     readonly status: "open";
 };
@@ -1806,6 +1844,7 @@ type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & {
 };
 declare function sessionOpenCommand(s: RegisterSession): BuiltCommand;
 declare function sessionTransitionCommand(s: RegisterSession & {
+    status: RegisterSessionTransitionPayload['status'];
     status_at: string;
 }): BuiltCommand;
 declare function movementCommand(m: CashMovement): BuiltCommand;
@@ -1840,7 +1879,7 @@ declare class RegisterApprovalRequiredError extends Error {
     constructor();
 }
 interface UseRegisterSessionOptions {
-    /** `register_sessions`, created with `registerSessionCollection()`; `null` while it opens. */
+    /** `register_sessions`, created with `addRegisterSessionCollection`; `null` while it opens. */
     sessions: RegisterSessionCollection | null;
     /** `cash_movements`; `null` while it opens. */
     movements: CashMovementCollection | null;
@@ -1881,6 +1920,8 @@ interface UseRegisterSessionOptions {
 }
 declare function useRegisterSession(options: UseRegisterSessionOptions): {
     session: RegisterSession | null;
+    /** Any unknown session status in the current snapshot means the register needs upgrade. */
+    needsUpgrade: boolean;
     movements: CashMovement[];
     expected: Record<string, number>;
     salesCount: number;
@@ -1909,6 +1950,7 @@ declare function useRegisterSession(options: UseRegisterSessionOptions): {
          * Refuses with `RegisterSessionAlreadyOpenError` while the register has a live session or
          * another open is running (in any hook instance), and with `RegisterCloseIncompleteError`
          * while an earlier close hasn't finished: a new session would lock the till behind it.
+         * An unknown stored status refuses with `RegisterNeedsUpgradeError`.
          */
         openSession: (input: {
             expectedFloatMinor: number | null;
@@ -2496,4 +2538,43 @@ declare function planLegs(plan: TenderPlan, rowsSinceFrom: {
     };
 };
 
-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, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, 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 TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, 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, 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, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };
+/**
+ * One record per voided tender leg: its v2 ledger row plus the provenance a v2 `void`
+ * fiscal record carries (TallyUI#479). Write-once: insert only, never update or delete;
+ * a replay of a known `paymentId` is a no-op for the caller to handle.
+ * Local only, never replicated. No device-side number or checksum:
+ * v2 numbers records on the server.
+ */
+
+interface TenderVoid {
+    /** The voided leg's client-minted id (the `clientPaymentId` order.create would send). Primary key, write-once. */
+    paymentId: string;
+    /** The sale's id (`PosOrder.saleId`). */
+    saleId: string;
+    type: 'void';
+    method: PaymentMethodKind;
+    amountMinor: number;
+    /** Cash only: what the customer handed over. */
+    tenderedMinor?: number;
+    /** An external terminal's reference. */
+    reference?: string;
+    /** ISO 4217 code. */
+    currency: string;
+    /** `removed`: the cashier removed this one leg. `cancelled`: the cashier backed out of tendering. */
+    reason: 'removed' | 'cancelled';
+    /** Device clock at the void, ISO 8601. */
+    deviceTime: string;
+    /** The device's IANA time zone. */
+    deviceTz: string;
+    /** The bound register's id, `''` when no register is bound. */
+    registerId: string;
+    sessionId?: string;
+    /** The cashier, as the backend's user id string. */
+    cashierRef: string;
+}
+declare const tenderVoidSchema: RxJsonSchema<TenderVoid>;
+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, RegisterSessionOpenClosedError, RegisterSessionRequiredError, type RegisterStore, 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, activePlan, addEntryToCart, addPosOrderCollection, addRegisterSessionCollection, 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$, 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 };