@aglyn/plugins-commerce 1.0.0-beta.278 → 1.0.0-beta.282

package/src/lib/model/commerce-pos-day-report.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @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 PosShift, type PosShiftRefund, type PosShiftReport, type PosShiftSale, type PosTenderMethod } from './commerce-pos-ops';
+/** The route, as the console and the native register call it. */
+export declare const POS_DAY_REPORT_ROUTE = "/api/commerce/pos-day-report";
+/** The longest range one report covers: a month of trading, or a long event. */
+export declare const POS_DAY_REPORT_MAX_DAYS = 31;
+/** The most sales one report reads; past it the report says it is partial. */
+export declare const POS_DAY_REPORT_SALES_CEILING = 5000;
+/** The most returns one report reads per register. */
+export declare const POS_DAY_REPORT_RETURNS_CEILING = 2000;
+/** The most shifts one report lists. */
+export declare const POS_DAY_REPORT_SHIFTS_CEILING = 500;
+/** The sales figures every total, register row and cashier row carries. */
+export interface PosDayTotals {
+    orderCount: number;
+    /** What customers paid for the goods: order totals, tax in, tips out. */
+    grossSalesCents: number;
+    discountsCents: number;
+    taxCents: number;
+    tipsCents: number;
+    refundCount: number;
+    refundsCents: number;
+    /** Gross sales less refunds. */
+    netSalesCents: number;
+    /** Sales by tender, the shift report's keys; a tender with nothing is absent. */
+    salesByTender: Partial<Record<PosTenderMethod, number>>;
+}
+/** One tender's line: what it took, what went back to it, and the difference. */
+export interface PosDayTenderRow {
+    method: PosTenderMethod;
+    label: string;
+    salesCents: number;
+    refundsCents: number;
+    netCents: number;
+}
+export interface PosDayRegisterRow extends PosDayTotals {
+    registerId: string;
+    /** The register's name, or its id when the register has since been removed. */
+    name: string;
+}
+export interface PosDayCashierRow extends PosDayTotals {
+    /** The member who rang the sales, or `''` for sales that name nobody. */
+    memberId: string;
+    name: string;
+}
+/** A shift in the range, as the shifts table lists it. */
+export interface PosDayShiftRow {
+    shiftId: string;
+    registerId: string;
+    registerName: string;
+    status: 'open' | 'closed';
+    openedAtMs: number;
+    closedAtMs: number | null;
+    openedByName: string;
+    closedByName: string | null;
+    openingFloatCents: number;
+    /** The Z report's net sales, or the X report's so far while it is open. */
+    netSalesCents: number;
+    /** The Z report's expected cash, or what the drawer should hold now while it is open. */
+    expectedCashCents: number;
+    /** What the closing cashier counted; `null` while the shift is open. */
+    countedCashCents: number | null;
+    /** counted − expected: positive is over, negative is short; `null` while open. */
+    varianceCents: number | null;
+}
+/** The cash drawers, summed over every register. */
+export interface PosDayCash {
+    /** The floats of the shifts that opened in the range. */
+    openingFloatCents: number;
+    /** Cash taken by sales in the range (change handed back is not counted), plus cash tips. */
+    cashSalesCents: number;
+    /** Returns paid out of a drawer in the range. */
+    cashRefundsCents: number;
+    paidInCents: number;
+    paidOutCents: number;
+    dropsCents: number;
+    closedShiftCount: number;
+    openShiftCount: number;
+    /** What the closed shifts' drawers should have held when they were counted. */
+    expectedCashCents: number;
+    /** What was counted in them. */
+    countedCashCents: number;
+    /** counted − expected over the closed shifts: positive is over, negative is short. */
+    varianceCents: number;
+    /** What the drawers still open should hold right now; not counted yet. */
+    openExpectedCashCents: number;
+}
+/** `GET /api/commerce/pos-day-report`'s answer. Every amount is integer minor units. */
+export interface PosDayReport {
+    hostId: string;
+    /** The site's name, as the printed report heads it. */
+    storeName: string;
+    /** The store's currency, lower case ISO 4217 (`usd`). */
+    currency: string;
+    /** The zone the days are counted in (the site's, else the workspace's, else UTC). */
+    timeZone: string;
+    /** The first day, `YYYY-MM-DD`, inclusive. */
+    from: string;
+    /** The last day, `YYYY-MM-DD`, inclusive. */
+    to: string;
+    /** The instant the first day starts in `timeZone`. */
+    startMs: number;
+    /** The instant after the last day ends in `timeZone` (exclusive). */
+    endMs: number;
+    days: number;
+    generatedAtMs: number;
+    totals: PosDayTotals;
+    byTender: PosDayTenderRow[];
+    byRegister: PosDayRegisterRow[];
+    byCashier: PosDayCashierRow[];
+    shifts: PosDayShiftRow[];
+    cash: PosDayCash;
+    /** More sales, returns or shifts were in the range than one report reads. */
+    truncated?: boolean;
+}
+export type PosDayRange = {
+    ok: true;
+    from: string;
+    to: string;
+    startMs: number;
+    endMs: number;
+    days: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The days a report covers, as instants in the store's zone. No `from` is
+ * today there; no `to` is the same day as `from`. Midnight is found on the
+ * zone's own calendar, so a day a clock change falls in is 23 or 25 hours.
+ */
+export declare function posDayReportRange(input: {
+    from?: unknown;
+    to?: unknown;
+    nowMs: number;
+    timeZone: string;
+}): PosDayRange;
+/** A register sale as the day report reads it. */
+export interface PosDaySale extends PosShiftSale {
+    registerId?: string;
+    cashierId?: string;
+    shiftId?: string;
+}
+/** A register return as the day report reads it: its register and who rang it. */
+export interface PosDayReturn extends PosShiftRefund {
+    registerId: string;
+    cashierId?: string;
+}
+/** A shift in the range, with the X report of an open one already read. */
+export type PosDayShift = Pick<PosShift, 'registerId' | 'status' | 'openedAtMs' | 'openedBy' | 'openedByName' | 'openingFloatCents' | 'cashEvents' | 'closedAtMs' | 'closedBy' | 'closedByName' | 'countedCashCents' | 'expectedCashCents' | 'varianceCents' | 'netSalesCents' | 'report'> & {
+    id: string;
+    liveReport?: PosShiftReport;
+};
+export interface PosDayReportInput {
+    hostId: string;
+    storeName: string;
+    currency: string;
+    timeZone: string;
+    range: Extract<PosDayRange, {
+        ok: true;
+    }>;
+    generatedAtMs: number;
+    sales: readonly PosDaySale[];
+    returns: readonly PosDayReturn[];
+    shifts: readonly PosDayShift[];
+    /** Register id → name. */
+    registerNames: Readonly<Record<string, string>>;
+    /** Member id → display name. */
+    memberNames: Readonly<Record<string, string>>;
+    truncated?: boolean;
+}
+/** The day report from what the route read. */
+export declare function computePosDayReport(input: PosDayReportInput): PosDayReport;
+/** Whether the range had nothing to report: no sale, no return, no shift. */
+export declare function posDayReportIsEmpty(report: PosDayReport): boolean;
+/** Minor units as a spreadsheet number in the store's currency: `12.34`, `1200` for yen. */
+export declare function posDayAmount(cents: number | null | undefined, currency: string): string;
+/** The range as a reader says it: `2026-10-24` or `2026-10-24 to 2026-10-26`. */
+export declare function posDayRangeLabel(report: Pick<PosDayReport, 'from' | 'to'>): string;
+/**
+ * The report as one spreadsheet: a heading block, the sales by register and
+ * cashier under the total, the tenders, the shifts and the drawer — each a
+ * block of its own with its own header row, amounts in the store's currency.
+ */
+export declare function posDayReportCsv(report: PosDayReport): string;
+/** The report's rows as the screen, the browser print and an 80 mm printer all read them. */
+export declare function posDayReportSections(report: PosDayReport, money: (cents: number) => string): Array<{
+    section: string;
+    rows: Array<{
+        label: string;
+        value: string;
+        strong?: boolean;
+    }>;
+}>;