@aglyn/plugins-commerce 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/model/commerce-pos-ops.d.ts

@@ -0,0 +1,437 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PrintReport } from './commerce-printers';
+/** How one payment toward a sale was taken, in the register's tender words. */
+export type PosTenderMethod = 'cash' | 'card_present' | 'card_keyed' | 'card_link' | 'gift_card' | 'folio';
+export declare const POS_TENDER_METHODS: readonly PosTenderMethod[];
+/** What each tender is called on a report, a receipt and a refund. */
+export declare const POS_TENDER_LABELS: Readonly<Record<PosTenderMethod, string>>;
+/** The tenders whose money moved through Stripe and goes back through it. */
+export declare const POS_STRIPE_TENDERS: ReadonlySet<PosTenderMethod>;
+/**
+ * One settled payment toward a sale, as the shift report and a register
+ * return read it.
+ */
+export interface PosOrderTender {
+    /** The payment's id on the order, or `legacy` for an order before the tender ledger. */
+    id: string;
+    method: PosTenderMethod;
+    /** Cents put toward the sale; never the tip, never the change. */
+    amountCents: number;
+    tipCents: number;
+    paymentIntentId?: string;
+    giftCardId?: string;
+    reservationId?: string;
+    cardBrand?: string;
+    last4?: string;
+    cashTenderedCents?: number;
+    changeCents?: number;
+}
+/** The order fields the tender reader looks at. */
+export interface PosTenderSource {
+    payments?: unknown;
+    channel?: string;
+    status?: string;
+    totals?: {
+        totalCents?: number;
+        tipCents?: number;
+    } | null;
+    amountCents?: number;
+    reservationId?: string;
+    checkoutSessionId?: string;
+    paymentIntentId?: string;
+}
+/**
+ * THE ONE PLACE THE TENDER LEDGER IS READ (AGL-3609).
+ *
+ * A register sale may carry `payments[]` — one entry per tender, the ledger
+ * the split-tender register writes (AGL-3607) — and only the payments that
+ * SUCCEEDED count: a declined card or a voided gift card took nothing. An
+ * order written before that ledger is one payment, inferred the way the
+ * ledger's own reader infers it: a folio when it names a reservation, a card
+ * link when Stripe saw it (or it came through the storefront), cash otherwise.
+ *
+ * The ledger's own reader (`orderPayments`) does both; this narrows it to the
+ * settled payments and the fields a report or a refund reads.
+ */
+export declare function posOrderTenders(order: PosTenderSource | null | undefined): PosOrderTender[];
+/** A tender as one line of a receipt: `Card •• 4242`. */
+export declare function posTenderLabel(tender: Pick<PosOrderTender, 'method' | 'cardBrand' | 'last4'>): string;
+/**
+ * Cash that moved through the drawer without a sale: money put in, money
+ * paid out for a reason (a delivery, petty cash), a drop to the safe, and
+ * a register return paid out in cash.
+ */
+export type PosCashEventType = 'paid_in' | 'paid_out' | 'drop' | 'refund';
+export declare const POS_CASH_EVENT_LABELS: Readonly<Record<PosCashEventType, string>>;
+export interface PosCashEvent {
+    /** The register's attempt id, so a retried tap records one event. */
+    id: string;
+    type: PosCashEventType;
+    amountCents: number;
+    reason: string;
+    /** The member who moved the cash. */
+    by: string;
+    atMs: number;
+    /** The order a `refund` paid out against. */
+    orderId?: string;
+}
+/** Sales, refunds and cash movements over one shift. */
+export interface PosShiftReport {
+    orderCount: number;
+    /** What customers paid for the goods: order totals, tax in, tips out. */
+    grossSalesCents: number;
+    discountsCents: number;
+    taxCents: number;
+    tipsCents: number;
+    salesByTender: Partial<Record<PosTenderMethod, number>>;
+    refundCount: number;
+    refundsCents: number;
+    refundsByTender: Partial<Record<PosTenderMethod, number>>;
+    /** Gross sales less refunds. */
+    netSalesCents: number;
+    openingFloatCents: number;
+    cashSalesCents: number;
+    paidInCents: number;
+    paidOutCents: number;
+    dropsCents: number;
+    cashRefundsCents: number;
+    /** float + cash sales + paid in − paid out − drops − cash refunds. */
+    expectedCashCents: number;
+    /** More sales were stamped with the shift than the report could read. */
+    truncated?: boolean;
+}
+/** `hosts/{hostId}/registers/{registerId}/shifts/{shiftId}`. */
+export interface PosShift {
+    hostId: string;
+    registerId: string;
+    status: 'open' | 'closed';
+    openedBy: string;
+    /** The member's name when the shift opened, for the history and the export. */
+    openedByName?: string;
+    openedAtMs: number;
+    openingFloatCents: number;
+    cashEvents: PosCashEvent[];
+    closedBy?: string;
+    closedByName?: string;
+    closedAtMs?: number;
+    /** What the closing cashier counted in the drawer. */
+    countedCashCents?: number;
+    expectedCashCents?: number;
+    /** counted − expected: positive is over, negative is short. */
+    varianceCents?: number;
+    closingNote?: string;
+    /** The Z report, frozen when the shift closed. */
+    report?: PosShiftReport;
+}
+/** The cash-event sums one formula reads. */
+export declare function posCashEventTotals(events: readonly PosCashEvent[] | null | undefined): {
+    paidInCents: number;
+    paidOutCents: number;
+    dropsCents: number;
+    cashRefundsCents: number;
+};
+/**
+ * THE DRAWER'S EXPECTED CASH: what should be in it when it is counted.
+ *
+ *   opening float + cash sales + paid in − paid out − safe drops − cash refunds
+ *
+ * Cash SALES are the cash tender's `amountCents`, which is what the sale took
+ * and never what the customer handed over: the change went straight back out
+ * of the same drawer. A tip left in cash is in the drawer too, so it counts.
+ */
+export declare function posExpectedCashCents(input: {
+    openingFloatCents: number;
+    cashSalesCents: number;
+    paidInCents: number;
+    paidOutCents: number;
+    dropsCents: number;
+    cashRefundsCents: number;
+}): number;
+/** A sale as the shift report reads it. */
+export interface PosShiftSale extends PosTenderSource {
+    totals?: {
+        totalCents?: number;
+        discountCents?: number;
+        taxCents?: number;
+        tipCents?: number;
+    } | null;
+}
+/** A register return as the shift report reads it. */
+export interface PosShiftRefund {
+    refundedCents: number;
+    tenders: Array<{
+        method: PosTenderMethod;
+        amountCents: number;
+    }>;
+}
+/**
+ * The X report (mid-shift) and the Z report (at close) are this one function
+ * over the sales stamped with the shift, the returns rung at the register
+ * during it and the shift's own cash events. A pending sale took no money and
+ * a cancelled one gave it back, so neither counts; a sale refunded LATER
+ * still counts as a sale, and its refund is counted where it was paid out.
+ */
+export declare function computePosShiftReport(input: {
+    shift: Pick<PosShift, 'openingFloatCents' | 'cashEvents'>;
+    sales: readonly PosShiftSale[];
+    refunds: readonly PosShiftRefund[];
+    truncated?: boolean;
+}): PosShiftReport;
+/** counted − expected; positive is over, negative is short. */
+export declare function posCashVarianceCents(countedCashCents: number, expectedCashCents: number): number;
+/** `$12.34`, `-$0.50` — the register's money format, store currency USD. */
+export declare function posMoney(cents: number): string;
+/** The shift history as a spreadsheet: one row per shift, money in dollars. */
+export declare function posShiftsCsv(shifts: ReadonlyArray<PosShift & {
+    id: string;
+    registerName?: string;
+}>, memberName?: (uid: string) => string): string;
+/** One line picked for return: its index on the order and how many units. */
+export interface PosReturnPick {
+    index: number;
+    quantity: number;
+}
+/** The order fields a return reads. */
+export interface PosReturnSource extends PosTenderSource {
+    lineItems?: Array<{
+        unitAmountCents?: number;
+        quantity?: number;
+        name?: string;
+    }> | null;
+    totals?: {
+        totalCents?: number;
+        discountCents?: number;
+        taxCents?: number;
+        shippingCents?: number;
+        tipCents?: number;
+    } | null;
+    refundedCents?: number;
+    refundedLineItemIds?: number[];
+    /** Units of each line already returned at a register, by line index. */
+    returnedQuantities?: Record<string, number>;
+    /** Cents already refunded to each payment by a register return. */
+    posPaymentRefunds?: Record<string, number>;
+}
+/**
+ * What each line is worth back, whole: its price less its share of the
+ * order's discount, plus its share of the order's tax — the same
+ * apportionment `orderLineRefundCents` uses for the discount, extended to the
+ * tax a register sale charged on top. Shipping and tips are not a line's.
+ */
+export declare function posReturnLineValues(order: PosReturnSource): number[];
+/** Units of each line already returned, a line refunded whole counting as all of it. */
+export declare function posReturnedQuantities(order: PosReturnSource): number[];
+export type PosReturnPlan = {
+    ok: true;
+    refundCents: number;
+    /** Cents per picked line, in the order picked. */
+    lineCents: number[];
+    /** The order's per-line returned quantities after this return. */
+    returnedQuantities: Record<string, number>;
+    /** Lines this return finishes, for `refundedLineItemIds`. */
+    completedLines: number[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What a return of these picks refunds, to the cent.
+ *
+ * Each line's value is split across its units CUMULATIVELY: returning `k` of
+ * `n` units already returned `r` refunds `round(V·(r+k)/n) − round(V·r/n)`,
+ * so returning a line one unit at a time refunds exactly what returning it
+ * whole would have, and the rounding never strands or invents a cent. The
+ * sum is capped at what is left to refund on the order — a refund given
+ * from the order dialog already took its share.
+ *
+ * `heldElsewhere` is, per line, the units an online return (the returns
+ * flow) already holds or took back. They cap what the register may take, but
+ * they are not written into `returnedQuantities`, which counts only what the
+ * register itself took.
+ */
+export declare function planPosReturn(order: PosReturnSource, picks: readonly PosReturnPick[], heldElsewhere?: readonly number[]): PosReturnPlan;
+/** One slice of a refund, sent back to one of the sale's payments. */
+export interface PosRefundAllocation {
+    paymentId: string;
+    method: PosTenderMethod;
+    amountCents: number;
+}
+/**
+ * What each payment can still take back: what it put toward the sale, less
+ * what register returns already sent to it. A refund given from the order
+ * dialog refunds through Stripe without naming a payment, so whatever it
+ * took that no payment accounts for comes off the Stripe payments first.
+ */
+export declare function posRefundableByTender(order: PosReturnSource): Array<PosOrderTender & {
+    refundableCents: number;
+}>;
+export type PosRefundSplit = {
+    ok: true;
+    allocations: PosRefundAllocation[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Sends `amountCents` back to the sale's own payments.
+ *
+ * With no `requested` split, each payment takes what it can in
+ * {@link REFUND_ORDER}. With one, every slice must name a payment of this
+ * sale and fit what that payment can still take, and the slices must add up
+ * to the refund exactly — a refund is never sent to a tender the sale was
+ * not paid with.
+ */
+export declare function splitPosRefund(order: PosReturnSource, amountCents: number, requested?: ReadonlyArray<{
+    paymentId: string;
+    amountCents: number;
+}> | null): PosRefundSplit;
+/** `hosts/{hostId}/registers/{registerId}/returns/{returnId}`. */
+export interface PosRegisterReturn {
+    hostId: string;
+    registerId: string;
+    orderId: string;
+    orderNumber?: number;
+    /** The shift the drawer was in when the return was rung, if one was open. */
+    shiftId?: string;
+    lines: Array<{
+        index: number;
+        quantity: number;
+        name: string;
+        refundCents: number;
+    }>;
+    refundedCents: number;
+    tenders: Array<PosRefundAllocation & {
+        status: 'refunded' | 'failed';
+        refundId?: string;
+        error?: string;
+    }>;
+    restocked: boolean;
+    locationId?: string;
+    /** The member at the register (by PIN or by sign-in). */
+    cashierId: string;
+    /** The manager whose PIN allowed a refund above the cashier's limit. */
+    approvedBy?: string;
+    reason?: string;
+    status: 'refunded' | 'partial';
+    atMs: number;
+}
+/** How long a cashier PIN switch lasts before the register asks again. */
+export declare const POS_CASHIER_ASSERTION_TTL_MS: number;
+/** A manager's approval is for the one refund in front of them. */
+export declare const POS_MANAGER_ASSERTION_TTL_MS: number;
+/** Wrong PINs in a row before the member is locked out. */
+export declare const POS_PIN_MAX_ATTEMPTS = 5;
+/** How long a lockout lasts. */
+export declare const POS_PIN_LOCKOUT_MS: number;
+/**
+ * Why a PIN cannot be used, or `null` when it can: 4 to 6 digits, and not
+ * one a stranger tries first — every digit the same, or a straight run.
+ */
+export declare function posPinProblem(pin: unknown): string | null;
+export interface PosReceiptLine {
+    name: string;
+    variantLabel?: string;
+    quantity: number;
+    unitAmountCents: number;
+    lineCents: number;
+}
+export interface PosReceipt {
+    storeName: string;
+    logoUrl?: string;
+    addressLines: string[];
+    orderNumber: string;
+    /** The digits the barcode encodes and the register's return lookup reads. */
+    barcodeValue: string;
+    dateLabel: string;
+    cashierName?: string;
+    registerName?: string;
+    customerName?: string;
+    lines: PosReceiptLine[];
+    subtotalCents: number;
+    discountCents: number;
+    taxCents: number;
+    totalCents: number;
+    tipCents: number;
+    tenders: Array<{
+        label: string;
+        amountCents: number;
+    }>;
+    changeCents: number;
+    refundedCents: number;
+    footer?: string;
+    returnPolicy?: string;
+    /** A gift receipt: the items and nothing about what they cost. */
+    gift: boolean;
+}
+/** The order fields a receipt prints. */
+export interface PosReceiptOrder extends PosReturnSource {
+    number?: number;
+    createdAtMs?: number;
+    customerName?: string | null;
+    lineItems?: Array<{
+        name?: string;
+        variantLabel?: string;
+        unitAmountCents?: number;
+        quantity?: number;
+    }> | null;
+}
+/**
+ * The receipt for one sale, from the order alone plus what the store prints
+ * on every receipt. The sale's lines, totals, tenders and change are the
+ * receipt model's (`receiptDataFromOrder`, the one the cloud printers print
+ * from), so a browser print and a cloud print never disagree; this adds the
+ * logo, the address, the return policy and the gift receipt. A gift receipt
+ * keeps the lines and the barcode — the recipient's way to return — and
+ * drops every price, total and tender.
+ */
+export declare function buildPosReceipt(input: {
+    orderId: string;
+    order: PosReceiptOrder;
+    store: {
+        name: string;
+        logoUrl?: string;
+        address?: string;
+        footer?: string;
+        returnPolicy?: string;
+    };
+    cashierName?: string;
+    registerName?: string;
+    gift?: boolean;
+    /** How the date prints; the register's own locale by default. */
+    formatDate?: (ms: number) => string;
+}): PosReceipt;
+/** One titled block of an X or Z report: what the screen, the browser print and a cloud printer all show. */
+export interface PosShiftReportSection {
+    section: string;
+    rows: Array<{
+        label: string;
+        value: string;
+        strong?: boolean;
+    }>;
+}
+/** The rows of an X or Z report, in the order a manager reads them. */
+export declare function posShiftReportRows(report: PosShiftReport, shift?: Pick<PosShift, 'countedCashCents' | 'varianceCents'>): PosShiftReportSection[];
+/** A shift's X or Z report as the receipt printer prints it. */
+export declare function posShiftPrintReport(input: {
+    title: 'X REPORT' | 'Z REPORT';
+    storeName: string;
+    registerName?: string;
+    report: PosShiftReport;
+    shift?: Pick<PosShift, 'countedCashCents' | 'varianceCents'>;
+    subtitle?: string;
+}): PrintReport;