@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/pos/reports.d.ts

@@ -0,0 +1,360 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * The back office's POS reports (engine sprint 28): every figure computed by the engine from the
+ * drawers' records, never summed by the caller. One read, `posReport(input)`, whose sections are
+ * fields; each method here selects ONE section (plus the report's header), so a page reads only
+ * what it shows.
+ *
+ * - Days are BUSINESS days: the label each drawer was stamped with when it opened, in its
+ *   location's zone (a bar's 01:30 sale is the day before's). `fromDay`/`toDay` are inclusive
+ *   `YYYY-MM-DD`, both today in the store's zone when omitted, at most 31 days apart.
+ * - Every day reconciles to its Z reports: `net = inZ + notInZ + unexplained + live −
+ *   refundsAfterClose` (`PosReportZCheck`). A card refund made after its sale's drawer closed is
+ *   in no Z: it counts on the day it was made. Open drawers are in, live (`openDrawerCount`).
+ * - A sale is credited to the cashier who completed it; who rang each line is not recorded.
+ * - Money is integer minor units of the drawer currency (the store's default); a sale in another
+ *   currency is in no figure (`otherCurrencySaleCount`). Exchange credit and returns without a
+ *   receipt are memos, never money.
+ *
+ * Needs `UpdateSettings` or `ManagePosDevices`; a location-restricted caller names one of its
+ * locations (`LOCATION_NOT_ALLOWED`). Refused `POS_LIST_RANGE_INVALID` (`extensions.reason`),
+ * `POS_REGISTER_NOT_FOUND`, `POS_REPORT_TIMED_OUT` (narrow the days or pick a location). Each
+ * method is its own document: an engine before 28 refuses it at validation, nothing else.
+ */
+export interface PosReportInput {
+    fromDay?: string;
+    toDay?: string;
+    /** One stock location; every location of the store when omitted. */
+    stockLocationId?: string;
+    /** One register (standing at `stockLocationId` when both are given). */
+    registerId?: string;
+}
+/** What every section answers beside it: the window and the drawers it covers. */
+export interface PosReportHeader {
+    fromDay: string;
+    toDay: string;
+    currencyCode: string;
+    stockLocationId: string | null;
+    registerId: string | null;
+    generatedAt: string;
+    drawerCount: number;
+    /** Drawers still open: their figures can still change. */
+    openDrawerCount: number;
+    /** Completed sales in another currency than the drawer's: in no figure. */
+    otherCurrencySaleCount: number;
+}
+export interface PosReportFigures {
+    saleCount: number;
+    itemCount: number;
+    salesTotal: number;
+    cash: number;
+    card: number;
+    other: number;
+    cashRefunds: number;
+    cardRefunds: number;
+    otherRefunds: number;
+    /** Card and other refunds made after their sale's drawer had closed (in no Z). */
+    refundsAfterClose: number;
+    net: number;
+    /** Signed; never part of `net`. */
+    cashRounding: number;
+    /** Not money: never in a tender or in `net`. */
+    exchangeCredit: number;
+    /** Returns without a receipt, both payouts; their cash is also in `cashRefunds`. */
+    noReceiptReturns: number;
+    /** Of which gift cards sold: a memo already inside cash, card and other; never taken off net. */
+    giftCardsSold: number;
+    giftCardsSoldCount: number;
+    /** Store credit issued on returns instead of a refund: a memo, in no refund and not in net. */
+    storeCreditIssued: number;
+    storeCreditIssuedCount: number;
+}
+export interface PosReportZCheck {
+    inZ: number;
+    notInZ: number;
+    live: number;
+    refundsAfterClose: number;
+    /** 0 unless a closed drawer's cash changed. */
+    unexplained: number;
+    recomputedZCount: number;
+}
+export interface PosReportDay {
+    businessDay: string;
+    drawerCount: number;
+    openDrawerCount: number;
+    uncountedDrawerCount: number;
+    figures: PosReportFigures;
+    zCheck: PosReportZCheck;
+    /** With one location: `open`, `closed` or `reopened` (more may come); null otherwise. */
+    storeDayStatus: string | null;
+    storeDayMismatch: boolean;
+}
+export interface PosReportReconciliation {
+    salesTotal: number;
+    paymentsBySale: number;
+    uncompletedCartPayments: number;
+    cashElsewhere: number;
+}
+export interface PosReportSummary extends PosReportHeader {
+    totals: PosReportFigures;
+    totalsCheck: PosReportZCheck;
+    days: PosReportDay[];
+    reconciliation: PosReportReconciliation;
+}
+export interface PosReportTenderRow {
+    /** `cash`, `card` or `other`. */
+    kind: string;
+    method: string;
+    methodName: string;
+    /** The store's stored-value method: part of other. */
+    storedValue: boolean;
+    paymentCount: number;
+    payments: number;
+    refunds: number;
+    refundsAfterClose: number;
+    net: number;
+}
+export interface PosReportDrawer {
+    openingFloats: number;
+    cashSales: number;
+    cashRefunds: number;
+    cashRounding: number;
+    paidIn: number;
+    paidOut: number;
+    safeDrops: number;
+    floatAdjustments: number;
+    noSaleCount: number;
+    expectedCash: number;
+    countedDrawerCount: number;
+    countedCash: number;
+    variance: number;
+    uncountedDrawerCount: number;
+    pendingApprovalCount: number;
+}
+export interface PosReportTenders extends PosReportHeader {
+    tenders: {
+        rows: PosReportTenderRow[];
+        drawer: PosReportDrawer;
+    };
+}
+export interface PosReportRegister {
+    registerId: string;
+    registerName: string | null;
+    drawerCount: number;
+    openDrawerCount: number;
+    uncountedDrawerCount: number;
+    figures: PosReportFigures;
+    variance: number;
+}
+export interface PosReportLocation {
+    stockLocationId: string | null;
+    name: string | null;
+    figures: PosReportFigures;
+    variance: number;
+    registers: PosReportRegister[];
+}
+export interface PosReportLocations extends PosReportHeader {
+    locations: PosReportLocation[];
+}
+export interface PosReportHour {
+    /** 0-23 in each drawer's own time zone. */
+    hour: number;
+    saleCount: number;
+    itemCount: number;
+    salesTotal: number;
+}
+export interface PosReportHours extends PosReportHeader {
+    hours: PosReportHour[];
+}
+export interface PosReportCashier extends PosReportCashierActivity {
+    staffId: string | null;
+    name: string | null;
+    /** A connected system's own reference for the person, as it gave it. */
+    externalRef: string | null;
+    saleCount: number;
+    itemCount: number;
+    salesTotal: number;
+    cashRefundCount: number;
+    cashRefunds: number;
+}
+export interface PosReportCashiers extends PosReportHeader {
+    cashiers: {
+        rows: PosReportCashier[];
+        refundsNotAttributed: number;
+    };
+}
+export interface PosReportCashierActivity {
+    /** Returns, voids and exchanges processed (returns without a receipt included). */
+    returnCount: number;
+    returnGross: number;
+    /** Returns approved as the manager. */
+    returnApprovalCount: number;
+    /** Till discounts the store's discount log names this staff member for. */
+    tillDiscountCount: number;
+    tillDiscountGross: number;
+}
+/** How a product page is sorted, each descending. */
+export type PosReportProductSort = 'NET_GROSS' | 'QUANTITY' | 'RETURNED';
+export interface PosReportProductOptions extends ListOptions {
+    sort?: PosReportProductSort;
+}
+export interface PosReportProduct {
+    productVariantId: string;
+    productId: string | null;
+    /** "Custom items" for the custom item carrier. */
+    name: string;
+    sku: string | null;
+    customItems: boolean;
+    soldQuantity: number;
+    returnedQuantity: number;
+    netQuantity: number;
+    listGross: number;
+    /** Promotions, coupons and till discounts on the sold lines. */
+    discounts: number;
+    salesGross: number;
+    returnedGross: number;
+    netGross: number;
+    netOfTax: number;
+    tax: number;
+}
+export interface PosReportProductTotals {
+    soldQuantity: number;
+    returnedQuantity: number;
+    listGross: number;
+    discounts: number;
+    salesGross: number;
+    returnedGross: number;
+    netGross: number;
+    netOfTax: number;
+    tax: number;
+}
+/** A page of product rows, with the report's header and the totals over every row. */
+export interface PosReportProductsPage extends Page<PosReportProduct> {
+    report: PosReportHeader;
+    totals: PosReportProductTotals;
+}
+export interface PosReportTaxRow {
+    description: string;
+    taxRate: number;
+    pricesIncludeTax: boolean | null;
+    salesGross: number;
+    salesNet: number;
+    salesTax: number;
+    returnsGross: number;
+    returnsNet: number;
+    returnsTax: number;
+    /** Money-only refunds, apportioned over the refunded sale's rates. */
+    apportionedRefundsGross: number;
+    apportionedRefundsNet: number;
+    apportionedRefundsTax: number;
+    netGross: number;
+    netNet: number;
+    /** The tax to file: Σ per receipt. */
+    netTax: number;
+    taxOnTotal: number | null;
+    rounding: number | null;
+}
+export interface PosReportTax extends PosReportHeader {
+    tax: {
+        rows: PosReportTaxRow[];
+        days: Array<{
+            businessDay: string;
+            rows: PosReportTaxRow[];
+        }>;
+        lineAllocationRounding: number;
+    };
+}
+export interface PosReportReturns extends PosReportHeader {
+    returns: {
+        /** False: the store keeps no returns record (only returns without a receipt count). */
+        available: boolean;
+        /** `return`, `void`, `exchange`, `back_office`, `no_receipt`; more may come. */
+        kinds: Array<{
+            kind: string;
+            returnCount: number;
+            gross: number;
+        }>;
+        reasons: Array<{
+            reasonCode: string;
+            lineCount: number;
+            quantity: number;
+            gross: number;
+        }>;
+        restockedQuantity: number;
+        writtenOffQuantity: number;
+        gross: number;
+        awaitingSettlementCount: number;
+        awaitingSettlementGross: number;
+        noReceiptCount: number;
+        noReceiptGross: number;
+        noReceiptCashGross: number;
+        noReceiptStoreCreditGross: number;
+    };
+}
+export interface PosReportDiscounts extends PosReportHeader {
+    discounts: {
+        tillGross: number;
+        tillNet: number;
+        tillSaleCount: number;
+        /** False: the store keeps no discount log. */
+        reasonsAvailable: boolean;
+        reasons: Array<{
+            reasonCode: string | null;
+            reasonName: string | null;
+            count: number;
+            gross: number;
+            net: number;
+        }>;
+        /** Till discounts no log row names. */
+        notLoggedGross: number;
+        promotions: Array<{
+            description: string;
+            lineCount: number;
+            gross: number;
+            net: number;
+        }>;
+        promotionsGross: number;
+    };
+}
+export interface PosReportsModule {
+    /** By business day, reconciled to the Zs, with the range's totals and reconciliation. */
+    summary(input?: PosReportInput, options?: Call): Promise<PosReportSummary>;
+    /** By tender (each payment method), and the drawers' cash. */
+    tenders(input?: PosReportInput, options?: Call): Promise<PosReportTenders>;
+    /** By location, each register under it. */
+    locations(input?: PosReportInput, options?: Call): Promise<PosReportLocations>;
+    /** 24 rows, each drawer's sales in its own zone's hour. */
+    hours(input?: PosReportInput, options?: Call): Promise<PosReportHours>;
+    /** By the cashier who completed each sale. */
+    cashiers(input?: PosReportInput, options?: Call): Promise<PosReportCashiers>;
+    /**
+     * By product and variant, returns netted, a page at a time (`limit` 1-200, 50 by default;
+     * `after` an offset cursor), with the totals over every row. `POS_REPORT_TOO_LARGE` above
+     * 250,000 sold lines: choose fewer days or one location.
+     */
+    products(input?: PosReportInput, options?: PosReportProductOptions): Promise<PosReportProductsPage>;
+    /** By tax rate, per business day and for the window (`POS_REPORT_TOO_LARGE` as products). */
+    tax(input?: PosReportInput, options?: Call): Promise<PosReportTax>;
+    /** Returns and voids, returns without a receipt. */
+    returns(input?: PosReportInput, options?: Call): Promise<PosReportReturns>;
+    /** Till discounts by reason, promotions by description (`POS_REPORT_TOO_LARGE` as products). */
+    discounts(input?: PosReportInput, options?: Call): Promise<PosReportDiscounts>;
+}
+export declare const POS_REPORT_FIGURES_FIELDS = "saleCount itemCount salesTotal cash card other cashRefunds cardRefunds otherRefunds refundsAfterClose net cashRounding exchangeCredit noReceiptReturns giftCardsSold giftCardsSoldCount storeCreditIssued storeCreditIssuedCount";
+export declare const POS_REPORT_SUMMARY_QUERY: string;
+export declare const POS_REPORT_TENDERS_QUERY: string;
+export declare const POS_REPORT_LOCATIONS_QUERY: string;
+export declare const POS_REPORT_HOURS_QUERY: string;
+export declare const POS_REPORT_CASHIERS_QUERY: string;
+export declare const POS_REPORT_PRODUCTS_QUERY = "query PosReportProducts($input: PosReportInput, $products: PosReportProductsInput) { posReport(input: $input) { fromDay toDay currencyCode stockLocationId registerId generatedAt drawerCount openDrawerCount otherCurrencySaleCount products(input: $products) { items { productVariantId productId name sku customItems netQuantity soldQuantity returnedQuantity listGross discounts salesGross returnedGross netGross netOfTax tax } totalItems totals { soldQuantity returnedQuantity listGross discounts salesGross returnedGross netGross netOfTax tax } } } }";
+export declare const POS_REPORT_TAX_QUERY: string;
+export declare const POS_REPORT_RETURNS_QUERY: string;
+export declare const POS_REPORT_DISCOUNTS_QUERY: string;
+/** A product page: at most this many rows. */
+export declare const POS_REPORT_PRODUCTS_MAX_PAGE = 200;
+/** ... and this many when `limit` is omitted. */
+export declare const POS_REPORT_PRODUCTS_DEFAULT_PAGE = 50;
+/** `{ input }` when there is one, else nothing: the engine's defaults apply to an absent input. */
+export declare function reportVariables(input: PosReportInput | undefined): Record<string, unknown>;
+export declare function createPosReportsModule(transport: Transport): PosReportsModule;

package/dist/pos/reports.js

@@ -0,0 +1,62 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+const HEADER = 'fromDay toDay currencyCode stockLocationId registerId generatedAt drawerCount openDrawerCount otherCurrencySaleCount';
+export const POS_REPORT_FIGURES_FIELDS = 'saleCount itemCount salesTotal cash card other cashRefunds cardRefunds otherRefunds refundsAfterClose net cashRounding exchangeCredit noReceiptReturns giftCardsSold giftCardsSoldCount storeCreditIssued storeCreditIssuedCount';
+const ZCHECK = 'inZ notInZ live refundsAfterClose unexplained recomputedZCount';
+function reportQuery(name, section) {
+    return `query ${name}($input: PosReportInput) { posReport(input: $input) { ${HEADER} ${section} } }`;
+}
+export const POS_REPORT_SUMMARY_QUERY = reportQuery('PosReportSummary', `totals { ${POS_REPORT_FIGURES_FIELDS} } totalsCheck { ${ZCHECK} } days { businessDay drawerCount openDrawerCount uncountedDrawerCount figures { ${POS_REPORT_FIGURES_FIELDS} } zCheck { ${ZCHECK} } storeDayStatus storeDayMismatch } reconciliation { salesTotal paymentsBySale uncompletedCartPayments cashElsewhere }`);
+export const POS_REPORT_TENDERS_QUERY = reportQuery('PosReportTenders', 'tenders { rows { kind method methodName storedValue paymentCount payments refunds refundsAfterClose net } drawer { openingFloats cashSales cashRefunds cashRounding paidIn paidOut safeDrops floatAdjustments noSaleCount expectedCash countedDrawerCount countedCash variance uncountedDrawerCount pendingApprovalCount } }');
+export const POS_REPORT_LOCATIONS_QUERY = reportQuery('PosReportLocations', `locations { stockLocationId name figures { ${POS_REPORT_FIGURES_FIELDS} } variance registers { registerId registerName drawerCount openDrawerCount uncountedDrawerCount figures { ${POS_REPORT_FIGURES_FIELDS} } variance } }`);
+export const POS_REPORT_HOURS_QUERY = reportQuery('PosReportHours', 'hours { hour saleCount itemCount salesTotal }');
+export const POS_REPORT_CASHIERS_QUERY = reportQuery('PosReportCashiers', 'cashiers { rows { staffId name externalRef saleCount itemCount salesTotal cashRefundCount cashRefunds returnCount returnGross returnApprovalCount tillDiscountCount tillDiscountGross } refundsNotAttributed }');
+const PRODUCT_FIGURES = 'soldQuantity returnedQuantity listGross discounts salesGross returnedGross netGross netOfTax tax';
+export const POS_REPORT_PRODUCTS_QUERY = `query PosReportProducts($input: PosReportInput, $products: PosReportProductsInput) { posReport(input: $input) { ${HEADER} products(input: $products) { items { productVariantId productId name sku customItems netQuantity ${PRODUCT_FIGURES} } totalItems totals { ${PRODUCT_FIGURES} } } } }`;
+const TAX_ROW = 'description taxRate pricesIncludeTax salesGross salesNet salesTax returnsGross returnsNet returnsTax apportionedRefundsGross apportionedRefundsNet apportionedRefundsTax netGross netNet netTax taxOnTotal rounding';
+export const POS_REPORT_TAX_QUERY = reportQuery('PosReportTax', `tax { rows { ${TAX_ROW} } days { businessDay rows { ${TAX_ROW} } } lineAllocationRounding }`);
+export const POS_REPORT_RETURNS_QUERY = reportQuery('PosReportReturns', 'returns { available kinds { kind returnCount gross } reasons { reasonCode lineCount quantity gross } restockedQuantity writtenOffQuantity gross awaitingSettlementCount awaitingSettlementGross noReceiptCount noReceiptGross noReceiptCashGross noReceiptStoreCreditGross }');
+export const POS_REPORT_DISCOUNTS_QUERY = reportQuery('PosReportDiscounts', 'discounts { tillGross tillNet tillSaleCount reasonsAvailable reasons { reasonCode reasonName count gross net } notLoggedGross promotions { description lineCount gross net } promotionsGross }');
+/** A product page: at most this many rows. */
+export const POS_REPORT_PRODUCTS_MAX_PAGE = 200;
+/** ... and this many when `limit` is omitted. */
+export const POS_REPORT_PRODUCTS_DEFAULT_PAGE = 50;
+/** `{ input }` when there is one, else nothing: the engine's defaults apply to an absent input. */
+export function reportVariables(input) {
+    if (!input)
+        return {};
+    const sent = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== ''));
+    return Object.keys(sent).length === 0 ? {} : { input: sent };
+}
+export function createPosReportsModule(transport) {
+    const read = async (query, input, options) => {
+        const data = await transport.graphql({ api: 'admin', query, variables: reportVariables(input) }, options);
+        return data.posReport;
+    };
+    return {
+        summary: (input, options) => read(POS_REPORT_SUMMARY_QUERY, input, options),
+        tenders: (input, options) => read(POS_REPORT_TENDERS_QUERY, input, options),
+        locations: (input, options) => read(POS_REPORT_LOCATIONS_QUERY, input, options),
+        hours: (input, options) => read(POS_REPORT_HOURS_QUERY, input, options),
+        cashiers: (input, options) => read(POS_REPORT_CASHIERS_QUERY, input, options),
+        tax: (input, options) => read(POS_REPORT_TAX_QUERY, input, options),
+        returns: (input, options) => read(POS_REPORT_RETURNS_QUERY, input, options),
+        discounts: (input, options) => read(POS_REPORT_DISCOUNTS_QUERY, input, options),
+        products: (input, options) => {
+            const take = Math.min(Math.max(Math.trunc(options?.limit ?? POS_REPORT_PRODUCTS_DEFAULT_PAGE), 1), POS_REPORT_PRODUCTS_MAX_PAGE);
+            const page = async (skip) => {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: POS_REPORT_PRODUCTS_QUERY,
+                    variables: {
+                        ...reportVariables(input),
+                        products: { skip, take, ...(options?.sort ? { sort: options.sort } : {}) },
+                    },
+                }, options);
+                const { products, ...report } = data.posReport;
+                const listed = pageFromVendureList(products, skip, take, (cursor) => page(readOffsetCursor(cursor)));
+                return Object.assign(listed, { report, totals: products.totals });
+            };
+            return page(options?.after === undefined ? 0 : readOffsetCursor(options.after));
+        },
+    };
+}

package/dist/pos/returns.d.ts

@@ -0,0 +1,244 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Till returns and voids (POS engine sprint 20): goods of a completed till sale back, refunded to
+ * the sale's own payments, or the whole sale voided. A headless till (a machine principal with
+ * `x-location`) is a supported caller: its CREDENTIAL is the manager gate, so no staff or approval
+ * token is sent. Money is integer minor units of the order's currency.
+ *
+ * `quote` is a read: what the units would refund, to which payments, and why it cannot be done now
+ * (`blockedBy`, never thrown). `create` and `void` re-compute under the order's money turn and
+ * refuse a total other than `expectedTotal` (`POS_RETURN_AMOUNT_CHANGED`, another return was made
+ * meanwhile). Refusals that mean NOTHING moved: `POS_RETURN_INVALID` (`extensions.reason`),
+ * `POS_RETURN_AMOUNT_CHANGED`, `POS_RETURN_WINDOW_ENDED` (send `overrideWindow`),
+ * `POS_RETURN_REFUND_UNKNOWN`, `POS_RETURN_SPLIT_CARD`, `POS_RETURN_EXCEEDS_REFUNDABLE`,
+ * `POS_RETURN_SALE_NOT_COMPLETED`, `POS_VOID_NOT_ALLOWED` (`extensions.reason`),
+ * `POS_RETURNS_UNAVAILABLE`, `POS_SESSION_REQUIRED` (a cash refund needs an open drawer),
+ * `REFUND_REFUSED`, `REFUND_METHOD_UNAVAILABLE`, `LIVE_CONNECTION_REFUSED`.
+ * `IDEMPOTENCY_OUTCOME_UNKNOWN` is neither: a card refund reached the provider and the outcome is
+ * unknown; never retry under a new key. A card refund the provider did not confirm answers
+ * `complete: false` with that refund's `outcome: 'unknown'`; a repeat under the SAME key answers
+ * `complete: true` once it was reconciled as made.
+ *
+ * `payout: 'STORED_VALUE'` (engine C6b) pays a return out to the sale's OWN customer's store credit
+ * instead of refunding it: no refund, no provider, no drawer; `quote(...).storedValuePayout` says
+ * whether it can (`reason` `no_customer`, `no_method`, `not_entitled` when not), and `create`
+ * refuses `POS_RETURN_STORE_CREDIT_UNAVAILABLE` (`extensions.reason`) when it cannot, nothing moved.
+ * `quote` and `create` need an engine with C6b (an older one refuses their documents); `void`
+ * keeps its sprint-20 selection and reads on any engine.
+ *
+ * The customer's consent to store credit (owner ruling Q4, EU consumer law CRD art. 13(1)): a
+ * store-credit payout asks whether the customer expressly agreed to store credit instead of a
+ * refund to their payment when `quote(...).storedValuePayout.asksConsent` says so, and `create`
+ * sends the answer as `customerAgreed`. The engine records it on the store credit; never a
+ * condition. `quote` reads `asksConsent` on an engine before it too (the document without it,
+ * `false`: such an engine takes no answer).
+ */
+export type PosReturnKind = 'RETURN' | 'VOID';
+/** Where a return's value goes (C6b): REFUND (the default) or the customer's store credit. */
+export type PosReturnPayout = 'REFUND' | 'STORED_VALUE';
+export interface PosReturnQuoteInput {
+    orderId: string;
+    /** RETURN when omitted; VOID ignores lines. */
+    kind?: PosReturnKind;
+    lines?: Array<{
+        orderLineId: string;
+        quantity: number;
+    }>;
+    cashFirst?: boolean;
+    /** REFUND when omitted (C6b). */
+    payout?: PosReturnPayout;
+}
+/** Whether a sale's return can go to its customer's store credit (C6b). */
+export interface PosReturnStoredValuePayout {
+    available: boolean;
+    /** no_customer, no_method or not_entitled when it cannot. More may come. */
+    reason: string | null;
+    /**
+     * Ask the customer whether they expressly agreed to store credit before this payout, and send
+     * the answer as `PosReturnCreateInput.customerAgreed` (owner ruling Q4): true exactly when the
+     * payout is available. `false` from an engine before the field, which takes no answer, and on a
+     * webshop order's quote, which never pays out to store credit.
+     */
+    asksConsent: boolean;
+}
+/** The store credit a return was paid out to (C6b). */
+export interface PosReturnStoredValueCredit {
+    accountId: string;
+    entryId: string;
+    amount: number;
+}
+export interface PosReturnQuoteLine {
+    orderLineId: string;
+    name: string;
+    sku: string | null;
+    customItem: boolean;
+    restockable: boolean;
+    soldQuantity: number;
+    returnedQuantity: number;
+    returnableQuantity: number;
+    quantity: number;
+    refundAmount: number;
+}
+export interface PosReturnLeg {
+    paymentId: string;
+    /** cash, card or other. More may come. */
+    kind: string;
+    method: string;
+    amount: number;
+}
+export interface PosReturnQuote {
+    orderId: string;
+    kind: PosReturnKind;
+    currencyCode: string;
+    receiptNumber: string | null;
+    lines: PosReturnQuoteLine[];
+    total: number;
+    legs: PosReturnLeg[];
+    cashPaidOut: number;
+    returnWindowEndsAt: string | null;
+    outsideWindow: boolean;
+    refundedOutsideReturns: number;
+    restockLocationName: string | null;
+    /** A POS_RETURN_* / POS_VOID_NOT_ALLOWED / REFUND_METHOD_UNAVAILABLE code, or null. More may come. */
+    blockedBy: string | null;
+    blockedReason: string | null;
+    /** Whether the return can go to the customer's store credit (C6b). */
+    storedValuePayout: PosReturnStoredValuePayout;
+}
+export interface PosReturnLineInput {
+    orderLineId: string;
+    quantity: number;
+    /** damaged, defective, wrong_item, not_as_described, arrived_late, no_longer_needed, order_error, other. */
+    reasonCode: string;
+    restock: boolean;
+}
+export interface PosReturnCreateInput {
+    orderId: string;
+    lines: PosReturnLineInput[];
+    /** `quote(...).total` as shown. */
+    expectedTotal: number;
+    overrideWindow?: boolean;
+    cashFirst?: boolean;
+    /** REFUND when omitted (C6b). STORED_VALUE: the whole return to the sale's customer's store credit. */
+    payout?: PosReturnPayout;
+    /**
+     * A STORED_VALUE payout whose quote said `asksConsent`: whether the customer expressly agreed to
+     * store credit instead of a refund to their payment (EU consumer law, CRD art. 13(1)), as staff
+     * asked them. The engine records it on the store credit with who stated it
+     * (`StoredValueEntry.customerAgreed`); never a condition, nothing is refused for it. Part of the
+     * request: a repeat under the same key sends the same answer, another answer is
+     * `IDEMPOTENCY_CONFLICT`. Sent only when given (true or false): left out or null, the request is
+     * what it always was. An engine before the field refuses a call that gives it, and that refusal
+     * is surfaced, never retried without the answer.
+     */
+    customerAgreed?: boolean | null;
+}
+export interface PosVoidInput {
+    orderId: string;
+    /** `quote({ orderId, kind: 'VOID' }).total` as shown. */
+    expectedTotal: number;
+}
+export interface PosReturnRefund {
+    paymentId: string;
+    kind: string;
+    method: string;
+    amount: number;
+    refundId: string;
+    /** made, or unknown. More may come. */
+    outcome: string;
+}
+export interface PosReturnResult {
+    orderId: string;
+    returnId: string;
+    /** The return's RMA code. */
+    returnCode: string;
+    kind: PosReturnKind;
+    total: number;
+    refunds: PosReturnRefund[];
+    cashPaidOut: number;
+    complete: boolean;
+    /**
+     * What a STORED_VALUE payout credited (C6b); null for a refund. Absent on `void`, which never
+     * pays out to store credit and keeps the sprint-20 selection (it reads on an engine before C6b).
+     */
+    storedValueCredit?: PosReturnStoredValueCredit | null;
+}
+/** A webshop order by its code AND its customer's email (engine C3/34). */
+export interface PosOnlineOrderRef {
+    orderCode: string;
+    emailAddress: string;
+}
+/** What a till may know of a webshop order before a return (engine C3/34). */
+export interface PosOnlineOrder {
+    orderId: string;
+    orderCode: string;
+    placedAt: string | null;
+    state: string;
+    currencyCode: string;
+    totalWithTax: number;
+    customerName: string | null;
+    /** The payment a return goes back to (its method's name); null when none can. */
+    refundMethodName: string | null;
+    returnableUnits: number;
+    /** POS_ONLINE_RETURN_BACK_OFFICE / POS_ONLINE_RETURN_NOTHING_RETURNABLE, or null. More may come. */
+    blockedBy: string | null;
+    blockedReason: string | null;
+}
+/** An online return's quote: the till quote plus what it refunds of delivery (engine C3/34). */
+export interface PosOnlineReturnQuote extends PosReturnQuote {
+    /** Delivery refunded: only when the return brings the whole order back inside the window. */
+    shippingRefund: number;
+    /** `online`. More may come. */
+    source: string;
+}
+export interface PosOnlineReturnInput {
+    order: PosOnlineOrderRef;
+    lines: PosReturnLineInput[];
+    /** `onlineQuote(...).total` as shown, delivery included. */
+    expectedTotal: number;
+    overrideWindow?: boolean;
+}
+export interface PosReturnsModule {
+    /** What a return (or a void) would do now. Writes nothing. */
+    quote(input: PosReturnQuoteInput, options?: Call): Promise<PosReturnQuote>;
+    /** Return items: the key is REQUIRED (`options.idempotencyKey`). */
+    create(input: PosReturnCreateInput, options: Call & {
+        idempotencyKey: string;
+    }): Promise<PosReturnResult>;
+    /** Void a sale: the key is REQUIRED (`options.idempotencyKey`). */
+    void(input: PosVoidInput, options: Call & {
+        idempotencyKey: string;
+    }): Promise<PosReturnResult>;
+    /**
+     * A webshop order of this store by its code AND its customer's email (engine C3/34), re-verified
+     * on every call. An unknown code, a wrong email or another store's order is ONE refusal,
+     * `POS_ONLINE_ORDER_NOT_FOUND`; a till sale `POS_ONLINE_ORDER_IS_TILL_SALE`.
+     */
+    findOnlineOrder(ref: PosOnlineOrderRef, options?: Call): Promise<PosOnlineOrder>;
+    /** What returning these units of the webshop order would refund now (engine C3/34). */
+    onlineQuote(input: {
+        order: PosOnlineOrderRef;
+        lines?: Array<{
+            orderLineId: string;
+            quantity: number;
+        }>;
+    }, options?: Call): Promise<PosOnlineReturnQuote>;
+    /**
+     * Return a webshop order's items at the credential's location, refunded to ONE online payment
+     * (engine C3/34). The key is REQUIRED. A provider that answers later or never confirms answers
+     * `complete: false` with the refund's `outcome` `pending` / `unknown` (do not refund again).
+     */
+    onlineReturn(input: PosOnlineReturnInput, options: Call & {
+        idempotencyKey: string;
+    }): Promise<PosReturnResult>;
+}
+export declare const POS_RETURN_QUOTE_QUERY = "query PosReturnQuote($input: PosReturnQuoteInput!) { posReturnQuote(input: $input) { orderId kind currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } total legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason storedValuePayout { available reason asksConsent } } }";
+/** The quote for an engine before the till's consent (owner ruling Q4): no `asksConsent`. */
+export declare const POS_RETURN_QUOTE_QUERY_BEFORE_CONSENT = "query PosReturnQuote($input: PosReturnQuoteInput!) { posReturnQuote(input: $input) { orderId kind currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } total legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason storedValuePayout { available reason } } }";
+export declare const POS_RETURN_MUTATION = "mutation PosReturn($input: PosReturnInput!) { posReturn(input: $input) { orderId returnId returnCode kind total refunds { paymentId kind method amount refundId outcome } cashPaidOut complete storedValueCredit { accountId entryId amount } } }";
+export declare const POS_VOID_SALE_MUTATION = "mutation PosVoidSale($input: PosVoidSaleInput!) { posVoidSale(input: $input) { orderId returnId returnCode kind total refunds { paymentId kind method amount refundId outcome } cashPaidOut complete } }";
+export declare const POS_ONLINE_ORDER_QUERY = "query PosOnlineOrder($input: PosOnlineOrderRefInput!) { posOnlineOrder(input: $input) { orderId orderCode placedAt state currencyCode totalWithTax customerName refundMethodName returnableUnits blockedBy blockedReason } }";
+export declare const POS_ONLINE_RETURN_QUOTE_QUERY = "query PosOnlineReturnQuote($input: PosOnlineReturnQuoteInput!) { posOnlineReturnQuote(input: $input) { orderId kind currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } total legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason storedValuePayout { available reason } shippingRefund source } }";
+export declare const POS_ONLINE_RETURN_MUTATION = "mutation PosOnlineReturn($input: PosOnlineReturnInput!) { posOnlineReturn(input: $input) { orderId returnId returnCode kind total refunds { paymentId kind method amount refundId outcome } cashPaidOut complete } }";
+export declare function createPosReturnsModule(transport: Transport): PosReturnsModule;