@aglyn/plugins-commerce 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/model/own-store-tax-summary.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @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 TaxReturnOperatorSalesPart } from '@aglyn/aglyn/plugin-manager/plugin-tax-return-sources';
+/**
+ * The workspace whose stores are the platform's own, from the environment,
+ * or `null` when none is named: `POS_HARDWARE_SELLER_ORG_ID`, read whether or
+ * not the in-person hardware sale is on, because the workspace is the
+ * platform's own either way.
+ */
+export declare function platformOwnStoreOrgId(env: Record<string, string | undefined>): string | null;
+/** One of the platform's own stores, as the return reads it. */
+export interface OwnStore {
+    hostId: string;
+    /** How the breakdown names it. */
+    name: string;
+    /** Where the store taxes its counter sales from: its own address's region. */
+    origin: {
+        country?: string | null;
+        state?: string | null;
+    } | null;
+}
+/** An order of an own store, as the return reads it. */
+export interface OwnStoreOrderInput {
+    hostId: string;
+    orderId: string;
+    status?: unknown;
+    channel?: unknown;
+    fulfillmentMethod?: unknown;
+    channelSource?: {
+        taxRemittedByChannel?: unknown;
+    } | null;
+    totals?: {
+        totalCents?: unknown;
+        taxCents?: unknown;
+    } | null;
+    /** Legacy single-product orders. */
+    amountCents?: unknown;
+    refundedCents?: unknown;
+    paidAtMs?: unknown;
+    createdAtMs?: unknown;
+    cancelledAtMs?: unknown;
+    updatedAtMs?: unknown;
+    timeline?: Array<{
+        atMs?: unknown;
+        event?: unknown;
+    }> | null;
+    livemode?: unknown;
+    checkoutSessionId?: unknown;
+    payments?: Array<{
+        status?: unknown;
+        livemode?: unknown;
+    }> | null;
+    shippingAddress?: {
+        country?: unknown;
+        state?: unknown;
+    } | null;
+    billingAddress?: {
+        country?: unknown;
+        state?: unknown;
+    } | null;
+}
+export type OwnStoreChannel = 'online' | 'in-person';
+/** How a row counts in the period. */
+export type OwnStoreInPeriod = 'sale' | 'refund' | 'sale and refund';
+/** One order as the working papers carry it: amounts and the region, no buyer. */
+export interface OwnStoreTaxRow {
+    hostId: string;
+    store: string;
+    orderId: string;
+    channel: OwnStoreChannel;
+    status: string | null;
+    paidAt: string | null;
+    jurisdiction: string;
+    totalSalesCents: number;
+    taxableSalesCents: number;
+    /** Whether the base is the one Stripe stated, or the whole sale less tax. */
+    taxableBase: 'stated' | 'whole sale' | 'untaxed';
+    taxCents: number;
+    refundedCents: number;
+    refundedAt: string | null;
+    inPeriodAs: OwnStoreInPeriod;
+}
+export interface OwnStoreTaxSummary {
+    periodStart: string;
+    periodEnd: string;
+    /** Live sales paid in the period. */
+    orders: number;
+    totalSalesCents: number;
+    /** The parts the return folds into its filing figures, one per store and channel. */
+    parts: TaxReturnOperatorSalesPart[];
+    excluded: {
+        testModeOrders: number;
+        /** Sold on an outside marketplace that remits the tax itself. */
+        marketplaceRemitted: number;
+    };
+    attention: {
+        untaxedOrders: number;
+        ordersMissingRegion: number;
+        canceledWithoutRefund: number;
+    };
+}
+/** When the order was paid, or null for one that never was. See the module note. */
+export declare function ownStoreOrderPaidAt(order: OwnStoreOrderInput): number | null;
+/** When the order's latest refund was made, or null when nothing was refunded. */
+export declare function ownStoreOrderRefundedAt(order: OwnStoreOrderInput): number | null;
+/**
+ * Whether a sale was made in test mode. A register payment states its mode,
+ * and every one must be live for the sale to be; otherwise the order's own
+ * reading applies, where an order nothing marks is live.
+ */
+export declare function ownStoreOrderIsTestMode(order: OwnStoreOrderInput): boolean;
+/** Which of a store's parts an order is in. */
+export declare function ownStoreOrderChannel(order: OwnStoreOrderInput): OwnStoreChannel;
+/** Where an order is taxed. See the module note. */
+export declare function ownStoreOrderJurisdiction(order: OwnStoreOrderInput, store: OwnStore | undefined): string;
+/** The part id a store's channel folds in under. */
+export declare function ownStorePartId(hostId: string, channel: OwnStoreChannel): string;
+/**
+ * The period's figures from the own stores' orders read for it.
+ * `statedBases` maps an order id to the taxable base Stripe stated for it,
+ * where its tax row is in hand.
+ */
+export declare function ownStoreTaxSummary(input: {
+    stores: readonly OwnStore[];
+    orders: readonly OwnStoreOrderInput[];
+    period: {
+        start: Date;
+        end: Date;
+    };
+    statedBases?: ReadonlyMap<string, number>;
+}): {
+    summary: OwnStoreTaxSummary;
+    rows: OwnStoreTaxRow[];
+};
+/** The taxable base a Stripe tax row states: the largest line's, since each level restates one base. */
+export declare function statedTaxableBase(lines: ReadonlyArray<{
+    taxableAmountCents?: unknown;
+} | null | undefined> | null | undefined): number | null;

package/src/lib/model/own-store-tax-summary.js

@@ -0,0 +1,288 @@
+/**
+ * @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.
+ */ /*==========================================
+ * THE PLATFORM'S OWN STORES, SUMMED FOR ONE FILING PERIOD (AGL-4038).
+ *
+ * The platform can sell from a store of its own like any merchant: card
+ * readers at an event's register, apparel online, anything it decides to
+ * sell later. Every one of those sales is the platform's OWN sale, so they
+ * fold into its return's filing figures beside its invoices, whatever the
+ * product. This module turns the orders of those stores into the figures the
+ * return folds in, one part per store and channel.
+ *
+ * WHICH STORES ARE THE PLATFORM'S OWN is configuration, never an id in code:
+ * every site of the workspace `POS_HARDWARE_SELLER_ORG_ID` names, the
+ * workspace the deployment already names as owning its own store
+ * ({@link platformOwnStoreOrgId}). A merchant's store is never one of them,
+ * so a merchant's sale is never folded in: it stays a facilitated sale on
+ * the storefront card.
+ *
+ * THE RULES, each pinned by `own-store-tax-summary.spec.ts`, the same as the
+ * hardware shop's (`pos-hardware-tax-summary.ts`) so the two read alike:
+ *
+ * - **A sale is in the period it was PAID**, half-open: the order's
+ *   `paidAtMs`, else its `paid` timeline event, else when it was placed for
+ *   an order that was paid. Its status today does not move it: an order paid
+ *   in the period and canceled later is still a sale of that period. An
+ *   order that was never paid (a voided register sale, a lapsed draft) is no
+ *   sale at all.
+ * - **Total sales** are the receipts excluding the tax: the total less the
+ *   tax. A tip is outside the total already and is never a sale.
+ * - **Taxable sales** are the base Stripe Tax stated for the sale where its
+ *   tax row is in hand, else the whole sale less tax when tax was charged
+ *   (the store taxes what it sells), else nothing — and an untaxed sale is
+ *   counted out loud.
+ * - **A refund is in the period it was MADE**, by the latest refund on the
+ *   order's timeline, stated beside the sales and never netted from them. An
+ *   order keeps only its latest refund stamp, as the platform's invoices do.
+ *   The refunded tax is the order's own tax in the refund's share of the
+ *   total.
+ * - **Test-mode sales are not sales**: left out and counted.
+ * - **A sale on an outside marketplace that remits the tax itself** is the
+ *   marketplace's to report: left out and counted.
+ * - **Where it is taxed**: a register or pickup sale where the store is; any
+ *   other where it ships, or the billing address; neither is `unknown`,
+ *   counted out loud.
+ *
+ * A card reader sold at the register is in its register sale here, and the
+ * hardware section does not fold it in again (`pos-hardware-tax-return-
+ * source.ts`); the store's tax rows leave the storefront card
+ * (`tax-return-source.ts`). Each sale is counted once.
+ *
+ * Integer cents throughout. Pure and total: no Firestore, no clock.
+ *=========================================*/ import { emptyTaxReturnOperatorFigures } from "@aglyn/aglyn/plugin-manager/plugin-tax-return-sources";
+import { taxJurisdictionKey } from "@aglyn/aglyn/app-utils/tax-jurisdiction-figures";
+import { orderIsTestMode } from "./commerce-orders.js";
+import { POS_HARDWARE_ENV } from "./pos-hardware.js";
+const ORG_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+ * The workspace whose stores are the platform's own, from the environment,
+ * or `null` when none is named: `POS_HARDWARE_SELLER_ORG_ID`, read whether or
+ * not the in-person hardware sale is on, because the workspace is the
+ * platform's own either way.
+ */ export function platformOwnStoreOrgId(env) {
+    var _env_POS_HARDWARE_ENV_sellerOrgId;
+    const orgId = String((_env_POS_HARDWARE_ENV_sellerOrgId = env[POS_HARDWARE_ENV.sellerOrgId]) != null ? _env_POS_HARDWARE_ENV_sellerOrgId : '').trim();
+    return ORG_ID.test(orgId) ? orgId : null;
+}
+const cents = (value)=>{
+    const parsed = Math.round(Number(value != null ? value : 0));
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+const stamp = (value)=>typeof value === 'number' && Number.isFinite(value) ? value : null;
+const text = (value)=>typeof value === 'string' && value ? value : null;
+/** The latest stamp of a timeline event named one of `names`, or null. */ function latestEvent(order, names) {
+    let latest = null;
+    for (const event of Array.isArray(order.timeline) ? order.timeline : []){
+        var _ref;
+        if (!names.includes(String((_ref = event == null ? void 0 : event.event) != null ? _ref : ''))) continue;
+        const at = stamp(event == null ? void 0 : event.atMs);
+        if (at !== null && (latest === null || at > latest)) latest = at;
+    }
+    return latest;
+}
+/** The first `paid` event, which is when the sale was paid. */ function firstPaidEvent(order) {
+    let first = null;
+    for (const event of Array.isArray(order.timeline) ? order.timeline : []){
+        if ((event == null ? void 0 : event.event) !== 'paid') continue;
+        const at = stamp(event == null ? void 0 : event.atMs);
+        if (at !== null && (first === null || at < first)) first = at;
+    }
+    return first;
+}
+/** When the order was paid, or null for one that never was. See the module note. */ export function ownStoreOrderPaidAt(order) {
+    var _stamp, _order_status;
+    const paid = (_stamp = stamp(order.paidAtMs)) != null ? _stamp : firstPaidEvent(order);
+    if (paid !== null) return paid;
+    const status = String((_order_status = order.status) != null ? _order_status : '');
+    const neverPaid = status === 'pending' || status === 'cancelled' && cents(order.refundedCents) <= 0;
+    return neverPaid ? null : stamp(order.createdAtMs);
+}
+/** When the order's latest refund was made, or null when nothing was refunded. */ export function ownStoreOrderRefundedAt(order) {
+    var _ref, _ref1, _latestEvent;
+    if (cents(order.refundedCents) <= 0) return null;
+    return (_ref = (_ref1 = (_latestEvent = latestEvent(order, [
+        'refund',
+        'refunded'
+    ])) != null ? _latestEvent : stamp(order.cancelledAtMs)) != null ? _ref1 : stamp(order.updatedAtMs)) != null ? _ref : ownStoreOrderPaidAt(order);
+}
+/**
+ * Whether a sale was made in test mode. A register payment states its mode,
+ * and every one must be live for the sale to be; otherwise the order's own
+ * reading applies, where an order nothing marks is live.
+ */ export function ownStoreOrderIsTestMode(order) {
+    var _text;
+    const modes = (Array.isArray(order.payments) ? order.payments : []).filter((payment)=>(payment == null ? void 0 : payment.status) === 'succeeded' && typeof (payment == null ? void 0 : payment.livemode) === 'boolean').map((payment)=>payment.livemode);
+    if (modes.length) return !modes.every(Boolean);
+    return orderIsTestMode({
+        livemode: order.livemode,
+        checkoutSessionId: (_text = text(order.checkoutSessionId)) != null ? _text : undefined,
+        $id: order.orderId
+    });
+}
+/** Which of a store's parts an order is in. */ export function ownStoreOrderChannel(order) {
+    return order.channel === 'pos' ? 'in-person' : 'online';
+}
+/** Where an order is taxed. See the module note. */ export function ownStoreOrderJurisdiction(order, store) {
+    var _order_shippingAddress, _order_billingAddress;
+    if (ownStoreOrderChannel(order) === 'in-person' || order.fulfillmentMethod === 'pickup') {
+        var _ref;
+        return taxJurisdictionKey((_ref = store == null ? void 0 : store.origin) != null ? _ref : null);
+    }
+    const shipped = taxJurisdictionKey((_order_shippingAddress = order.shippingAddress) != null ? _order_shippingAddress : null);
+    return shipped !== 'unknown' ? shipped : taxJurisdictionKey((_order_billingAddress = order.billingAddress) != null ? _order_billingAddress : null);
+}
+/** The part id a store's channel folds in under. */ export function ownStorePartId(hostId, channel) {
+    return `ownStore:${hostId}:${channel}`;
+}
+function partLabel(store, hostId, channel) {
+    const name = (store == null ? void 0 : store.name) || hostId;
+    return channel === 'in-person' ? `${name} — sold in person` : `${name} — sold online`;
+}
+/**
+ * The period's figures from the own stores' orders read for it.
+ * `statedBases` maps an order id to the taxable base Stripe stated for it,
+ * where its tax row is in hand.
+ */ export function ownStoreTaxSummary(input) {
+    var _input_orders;
+    const { period } = input;
+    const startMs = period.start.getTime();
+    const endMs = period.end.getTime();
+    const within = (at)=>at !== null && at >= startMs && at < endMs;
+    const stores = new Map(input.stores.map((store)=>[
+            store.hostId,
+            store
+        ]));
+    const parts = new Map();
+    const summary = {
+        periodStart: period.start.toISOString(),
+        periodEnd: period.end.toISOString(),
+        orders: 0,
+        totalSalesCents: 0,
+        parts: [],
+        excluded: {
+            testModeOrders: 0,
+            marketplaceRemitted: 0
+        },
+        attention: {
+            untaxedOrders: 0,
+            ordersMissingRegion: 0,
+            canceledWithoutRefund: 0
+        }
+    };
+    const rows = [];
+    const seen = new Set();
+    for (const order of (_input_orders = input.orders) != null ? _input_orders : []){
+        var _parts_get, _part_byJurisdiction, _jurisdiction, _, _ref;
+        var _order_channelSource, _order_totals, _order_totals1, _input_statedBases;
+        // Only an own store's order, and each once: the reader merges queries.
+        if (!(order == null ? void 0 : order.orderId) || !stores.has(order.hostId)) continue;
+        const key = `${order.hostId}/${order.orderId}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const paidAt = ownStoreOrderPaidAt(order);
+        const refundedAt = ownStoreOrderRefundedAt(order);
+        const sale = within(paidAt);
+        const refund = within(refundedAt);
+        if (!sale && !refund) continue;
+        if (ownStoreOrderIsTestMode(order)) {
+            if (sale) summary.excluded.testModeOrders += 1;
+            continue;
+        }
+        if (order.channel === 'marketplace' && ((_order_channelSource = order.channelSource) == null ? void 0 : _order_channelSource.taxRemittedByChannel) === true) {
+            if (sale) summary.excluded.marketplaceRemitted += 1;
+            continue;
+        }
+        const store = stores.get(order.hostId);
+        const channel = ownStoreOrderChannel(order);
+        const jurisdiction = ownStoreOrderJurisdiction(order, store);
+        const partId = ownStorePartId(order.hostId, channel);
+        const part = (_parts_get = parts.get(partId)) != null ? _parts_get : (()=>{
+            const created = {
+                id: partId,
+                label: partLabel(store, order.hostId, channel),
+                byJurisdiction: {}
+            };
+            parts.set(partId, created);
+            return created;
+        })();
+        const bucket = (_ = (_part_byJurisdiction = part.byJurisdiction)[_jurisdiction = jurisdiction]) != null ? _ : _part_byJurisdiction[_jurisdiction] = emptyTaxReturnOperatorFigures();
+        const total = cents((_ref = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref : order.amountCents);
+        const tax = Math.min(cents((_order_totals1 = order.totals) == null ? void 0 : _order_totals1.taxCents), total);
+        const sales = total - tax;
+        const stated = (_input_statedBases = input.statedBases) == null ? void 0 : _input_statedBases.get(order.orderId);
+        const taxableBase = typeof stated === 'number' && Number.isFinite(stated) ? 'stated' : tax > 0 ? 'whole sale' : 'untaxed';
+        const taxable = taxableBase === 'stated' ? Math.min(cents(stated), sales) : taxableBase === 'whole sale' ? sales : 0;
+        if (sale) {
+            var _order_status;
+            summary.orders += 1;
+            summary.totalSalesCents += sales;
+            bucket.transactionCount += 1;
+            bucket.totalSalesCents += sales;
+            bucket.taxableSalesCents += taxable;
+            bucket.taxCollectedCents += tax;
+            if (tax === 0) summary.attention.untaxedOrders += 1;
+            if (jurisdiction === 'unknown') summary.attention.ordersMissingRegion += 1;
+            const status = String((_order_status = order.status) != null ? _order_status : '');
+            if ((status === 'cancelled' || status === 'refunded') && cents(order.refundedCents) <= 0) {
+                summary.attention.canceledWithoutRefund += 1;
+            }
+        }
+        const refunded = Math.min(cents(order.refundedCents), total);
+        if (refund) {
+            // A whole refund gives back the order's own tax; a partial one is split
+            // in the order's own ratio.
+            const refundedTax = refunded >= total ? tax : total > 0 ? Math.round(refunded * tax / total) : 0;
+            bucket.refundCount += 1;
+            bucket.refundedSalesCents += refunded - refundedTax;
+            bucket.refundedTaxCents += refundedTax;
+        }
+        rows.push({
+            hostId: order.hostId,
+            store: (store == null ? void 0 : store.name) || order.hostId,
+            orderId: order.orderId,
+            channel,
+            status: text(order.status),
+            paidAt: paidAt === null ? null : new Date(paidAt).toISOString(),
+            jurisdiction,
+            totalSalesCents: sales,
+            taxableSalesCents: taxable,
+            taxableBase,
+            taxCents: tax,
+            refundedCents: refunded,
+            refundedAt: refundedAt === null ? null : new Date(refundedAt).toISOString(),
+            inPeriodAs: sale && refund ? 'sale and refund' : sale ? 'sale' : 'refund'
+        });
+    }
+    summary.parts = [
+        ...parts.values()
+    ];
+    return {
+        summary,
+        rows
+    };
+}
+/** The taxable base a Stripe tax row states: the largest line's, since each level restates one base. */ export function statedTaxableBase(lines) {
+    let base = null;
+    for (const line of lines != null ? lines : []){
+        const value = Number(line == null ? void 0 : line.taxableAmountCents);
+        if ((line == null ? void 0 : line.taxableAmountCents) === null || (line == null ? void 0 : line.taxableAmountCents) === undefined || !Number.isFinite(value)) continue;
+        base = base === null ? Math.round(value) : Math.max(base, Math.round(value));
+    }
+    return base;
+}
+
+//# sourceMappingURL=own-store-tax-summary.js.map

package/src/lib/model/own-store-tax-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/own-store-tax-summary.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * THE PLATFORM'S OWN STORES, SUMMED FOR ONE FILING PERIOD (AGL-4038).\n *\n * The platform can sell from a store of its own like any merchant: card\n * readers at an event's register, apparel online, anything it decides to\n * sell later. Every one of those sales is the platform's OWN sale, so they\n * fold into its return's filing figures beside its invoices, whatever the\n * product. This module turns the orders of those stores into the figures the\n * return folds in, one part per store and channel.\n *\n * WHICH STORES ARE THE PLATFORM'S OWN is configuration, never an id in code:\n * every site of the workspace `POS_HARDWARE_SELLER_ORG_ID` names, the\n * workspace the deployment already names as owning its own store\n * ({@link platformOwnStoreOrgId}). A merchant's store is never one of them,\n * so a merchant's sale is never folded in: it stays a facilitated sale on\n * the storefront card.\n *\n * THE RULES, each pinned by `own-store-tax-summary.spec.ts`, the same as the\n * hardware shop's (`pos-hardware-tax-summary.ts`) so the two read alike:\n *\n * - **A sale is in the period it was PAID**, half-open: the order's\n *   `paidAtMs`, else its `paid` timeline event, else when it was placed for\n *   an order that was paid. Its status today does not move it: an order paid\n *   in the period and canceled later is still a sale of that period. An\n *   order that was never paid (a voided register sale, a lapsed draft) is no\n *   sale at all.\n * - **Total sales** are the receipts excluding the tax: the total less the\n *   tax. A tip is outside the total already and is never a sale.\n * - **Taxable sales** are the base Stripe Tax stated for the sale where its\n *   tax row is in hand, else the whole sale less tax when tax was charged\n *   (the store taxes what it sells), else nothing — and an untaxed sale is\n *   counted out loud.\n * - **A refund is in the period it was MADE**, by the latest refund on the\n *   order's timeline, stated beside the sales and never netted from them. An\n *   order keeps only its latest refund stamp, as the platform's invoices do.\n *   The refunded tax is the order's own tax in the refund's share of the\n *   total.\n * - **Test-mode sales are not sales**: left out and counted.\n * - **A sale on an outside marketplace that remits the tax itself** is the\n *   marketplace's to report: left out and counted.\n * - **Where it is taxed**: a register or pickup sale where the store is; any\n *   other where it ships, or the billing address; neither is `unknown`,\n *   counted out loud.\n *\n * A card reader sold at the register is in its register sale here, and the\n * hardware section does not fold it in again (`pos-hardware-tax-return-\n * source.ts`); the store's tax rows leave the storefront card\n * (`tax-return-source.ts`). Each sale is counted once.\n *\n * Integer cents throughout. Pure and total: no Firestore, no clock.\n *=========================================*/\n\nimport {\n  emptyTaxReturnOperatorFigures,\n  type TaxReturnOperatorFigures,\n  type TaxReturnOperatorSalesPart,\n} from '@aglyn/aglyn/plugin-manager/plugin-tax-return-sources'\nimport { taxJurisdictionKey } from '@aglyn/aglyn/app-utils/tax-jurisdiction-figures'\nimport { orderIsTestMode } from './commerce-orders'\nimport { POS_HARDWARE_ENV } from './pos-hardware'\n\nconst ORG_ID = /^[A-Za-z0-9_-]{1,128}$/\n\n/**\n * The workspace whose stores are the platform's own, from the environment,\n * or `null` when none is named: `POS_HARDWARE_SELLER_ORG_ID`, read whether or\n * not the in-person hardware sale is on, because the workspace is the\n * platform's own either way.\n */\nexport function platformOwnStoreOrgId(env: Record<string, string | undefined>): string | null {\n  const orgId = String(env[POS_HARDWARE_ENV.sellerOrgId] ?? '').trim()\n  return ORG_ID.test(orgId) ? orgId : null\n}\n\n/** One of the platform's own stores, as the return reads it. */\nexport interface OwnStore {\n  hostId: string\n  /** How the breakdown names it. */\n  name: string\n  /** Where the store taxes its counter sales from: its own address's region. */\n  origin: { country?: string | null; state?: string | null } | null\n}\n\n/** An order of an own store, as the return reads it. */\nexport interface OwnStoreOrderInput {\n  hostId: string\n  orderId: string\n  status?: unknown\n  channel?: unknown\n  fulfillmentMethod?: unknown\n  channelSource?: { taxRemittedByChannel?: unknown } | null\n  totals?: { totalCents?: unknown; taxCents?: unknown } | null\n  /** Legacy single-product orders. */\n  amountCents?: unknown\n  refundedCents?: unknown\n  paidAtMs?: unknown\n  createdAtMs?: unknown\n  cancelledAtMs?: unknown\n  updatedAtMs?: unknown\n  timeline?: Array<{ atMs?: unknown; event?: unknown }> | null\n  livemode?: unknown\n  checkoutSessionId?: unknown\n  payments?: Array<{ status?: unknown; livemode?: unknown }> | null\n  shippingAddress?: { country?: unknown; state?: unknown } | null\n  billingAddress?: { country?: unknown; state?: unknown } | null\n}\n\nexport type OwnStoreChannel = 'online' | 'in-person'\n\n/** How a row counts in the period. */\nexport type OwnStoreInPeriod = 'sale' | 'refund' | 'sale and refund'\n\n/** One order as the working papers carry it: amounts and the region, no buyer. */\nexport interface OwnStoreTaxRow {\n  hostId: string\n  store: string\n  orderId: string\n  channel: OwnStoreChannel\n  status: string | null\n  paidAt: string | null\n  jurisdiction: string\n  totalSalesCents: number\n  taxableSalesCents: number\n  /** Whether the base is the one Stripe stated, or the whole sale less tax. */\n  taxableBase: 'stated' | 'whole sale' | 'untaxed'\n  taxCents: number\n  refundedCents: number\n  refundedAt: string | null\n  inPeriodAs: OwnStoreInPeriod\n}\n\nexport interface OwnStoreTaxSummary {\n  periodStart: string\n  periodEnd: string\n  /** Live sales paid in the period. */\n  orders: number\n  totalSalesCents: number\n  /** The parts the return folds into its filing figures, one per store and channel. */\n  parts: TaxReturnOperatorSalesPart[]\n  excluded: {\n    testModeOrders: number\n    /** Sold on an outside marketplace that remits the tax itself. */\n    marketplaceRemitted: number\n  }\n  attention: {\n    untaxedOrders: number\n    ordersMissingRegion: number\n    canceledWithoutRefund: number\n  }\n}\n\nconst cents = (value: unknown): number => {\n  const parsed = Math.round(Number(value ?? 0))\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\nconst stamp = (value: unknown): number | null =>\n  typeof value === 'number' && Number.isFinite(value) ? value : null\n\nconst text = (value: unknown): string | null => (typeof value === 'string' && value ? value : null)\n\n/** The latest stamp of a timeline event named one of `names`, or null. */\nfunction latestEvent(order: OwnStoreOrderInput, names: readonly string[]): number | null {\n  let latest: number | null = null\n  for (const event of Array.isArray(order.timeline) ? order.timeline : []) {\n    if (!names.includes(String(event?.event ?? ''))) continue\n    const at = stamp(event?.atMs)\n    if (at !== null && (latest === null || at > latest)) latest = at\n  }\n  return latest\n}\n\n/** The first `paid` event, which is when the sale was paid. */\nfunction firstPaidEvent(order: OwnStoreOrderInput): number | null {\n  let first: number | null = null\n  for (const event of Array.isArray(order.timeline) ? order.timeline : []) {\n    if (event?.event !== 'paid') continue\n    const at = stamp(event?.atMs)\n    if (at !== null && (first === null || at < first)) first = at\n  }\n  return first\n}\n\n/** When the order was paid, or null for one that never was. See the module note. */\nexport function ownStoreOrderPaidAt(order: OwnStoreOrderInput): number | null {\n  const paid = stamp(order.paidAtMs) ?? firstPaidEvent(order)\n  if (paid !== null) return paid\n  const status = String(order.status ?? '')\n  const neverPaid = status === 'pending' || (status === 'cancelled' && cents(order.refundedCents) <= 0)\n  return neverPaid ? null : stamp(order.createdAtMs)\n}\n\n/** When the order's latest refund was made, or null when nothing was refunded. */\nexport function ownStoreOrderRefundedAt(order: OwnStoreOrderInput): number | null {\n  if (cents(order.refundedCents) <= 0) return null\n  return (\n    latestEvent(order, ['refund', 'refunded']) ??\n    stamp(order.cancelledAtMs) ??\n    stamp(order.updatedAtMs) ??\n    ownStoreOrderPaidAt(order)\n  )\n}\n\n/**\n * Whether a sale was made in test mode. A register payment states its mode,\n * and every one must be live for the sale to be; otherwise the order's own\n * reading applies, where an order nothing marks is live.\n */\nexport function ownStoreOrderIsTestMode(order: OwnStoreOrderInput): boolean {\n  const modes = (Array.isArray(order.payments) ? order.payments : [])\n    .filter((payment) => payment?.status === 'succeeded' && typeof payment?.livemode === 'boolean')\n    .map((payment) => payment.livemode as boolean)\n  if (modes.length) return !modes.every(Boolean)\n  return orderIsTestMode({\n    livemode: order.livemode,\n    checkoutSessionId: text(order.checkoutSessionId) ?? undefined,\n    $id: order.orderId,\n  })\n}\n\n/** Which of a store's parts an order is in. */\nexport function ownStoreOrderChannel(order: OwnStoreOrderInput): OwnStoreChannel {\n  return order.channel === 'pos' ? 'in-person' : 'online'\n}\n\n/** Where an order is taxed. See the module note. */\nexport function ownStoreOrderJurisdiction(order: OwnStoreOrderInput, store: OwnStore | undefined): string {\n  if (ownStoreOrderChannel(order) === 'in-person' || order.fulfillmentMethod === 'pickup') {\n    return taxJurisdictionKey(store?.origin ?? null)\n  }\n  const shipped = taxJurisdictionKey(order.shippingAddress ?? null)\n  return shipped !== 'unknown' ? shipped : taxJurisdictionKey(order.billingAddress ?? null)\n}\n\n/** The part id a store's channel folds in under. */\nexport function ownStorePartId(hostId: string, channel: OwnStoreChannel): string {\n  return `ownStore:${hostId}:${channel}`\n}\n\nfunction partLabel(store: OwnStore | undefined, hostId: string, channel: OwnStoreChannel): string {\n  const name = store?.name || hostId\n  return channel === 'in-person' ? `${name} — sold in person` : `${name} — sold online`\n}\n\n/**\n * The period's figures from the own stores' orders read for it.\n * `statedBases` maps an order id to the taxable base Stripe stated for it,\n * where its tax row is in hand.\n */\nexport function ownStoreTaxSummary(input: {\n  stores: readonly OwnStore[]\n  orders: readonly OwnStoreOrderInput[]\n  period: { start: Date; end: Date }\n  statedBases?: ReadonlyMap<string, number>\n}): { summary: OwnStoreTaxSummary; rows: OwnStoreTaxRow[] } {\n  const { period } = input\n  const startMs = period.start.getTime()\n  const endMs = period.end.getTime()\n  const within = (at: number | null) => at !== null && at >= startMs && at < endMs\n  const stores = new Map(input.stores.map((store) => [store.hostId, store]))\n  const parts = new Map<string, TaxReturnOperatorSalesPart>()\n  const summary: OwnStoreTaxSummary = {\n    periodStart: period.start.toISOString(),\n    periodEnd: period.end.toISOString(),\n    orders: 0,\n    totalSalesCents: 0,\n    parts: [],\n    excluded: { testModeOrders: 0, marketplaceRemitted: 0 },\n    attention: { untaxedOrders: 0, ordersMissingRegion: 0, canceledWithoutRefund: 0 },\n  }\n  const rows: OwnStoreTaxRow[] = []\n  const seen = new Set<string>()\n\n  for (const order of input.orders ?? []) {\n    // Only an own store's order, and each once: the reader merges queries.\n    if (!order?.orderId || !stores.has(order.hostId)) continue\n    const key = `${order.hostId}/${order.orderId}`\n    if (seen.has(key)) continue\n    seen.add(key)\n\n    const paidAt = ownStoreOrderPaidAt(order)\n    const refundedAt = ownStoreOrderRefundedAt(order)\n    const sale = within(paidAt)\n    const refund = within(refundedAt)\n    if (!sale && !refund) continue\n    if (ownStoreOrderIsTestMode(order)) {\n      if (sale) summary.excluded.testModeOrders += 1\n      continue\n    }\n    if (order.channel === 'marketplace' && order.channelSource?.taxRemittedByChannel === true) {\n      if (sale) summary.excluded.marketplaceRemitted += 1\n      continue\n    }\n\n    const store = stores.get(order.hostId)\n    const channel = ownStoreOrderChannel(order)\n    const jurisdiction = ownStoreOrderJurisdiction(order, store)\n    const partId = ownStorePartId(order.hostId, channel)\n    const part =\n      parts.get(partId) ??\n      (() => {\n        const created: TaxReturnOperatorSalesPart = {\n          id: partId,\n          label: partLabel(store, order.hostId, channel),\n          byJurisdiction: {},\n        }\n        parts.set(partId, created)\n        return created\n      })()\n    const bucket: TaxReturnOperatorFigures = (part.byJurisdiction[jurisdiction] ??= emptyTaxReturnOperatorFigures())\n\n    const total = cents(order.totals?.totalCents ?? order.amountCents)\n    const tax = Math.min(cents(order.totals?.taxCents), total)\n    const sales = total - tax\n    const stated = input.statedBases?.get(order.orderId)\n    const taxableBase: OwnStoreTaxRow['taxableBase'] =\n      typeof stated === 'number' && Number.isFinite(stated) ? 'stated' : tax > 0 ? 'whole sale' : 'untaxed'\n    const taxable =\n      taxableBase === 'stated' ? Math.min(cents(stated), sales) : taxableBase === 'whole sale' ? sales : 0\n\n    if (sale) {\n      summary.orders += 1\n      summary.totalSalesCents += sales\n      bucket.transactionCount += 1\n      bucket.totalSalesCents += sales\n      bucket.taxableSalesCents += taxable\n      bucket.taxCollectedCents += tax\n      if (tax === 0) summary.attention.untaxedOrders += 1\n      if (jurisdiction === 'unknown') summary.attention.ordersMissingRegion += 1\n      const status = String(order.status ?? '')\n      if ((status === 'cancelled' || status === 'refunded') && cents(order.refundedCents) <= 0) {\n        summary.attention.canceledWithoutRefund += 1\n      }\n    }\n\n    const refunded = Math.min(cents(order.refundedCents), total)\n    if (refund) {\n      // A whole refund gives back the order's own tax; a partial one is split\n      // in the order's own ratio.\n      const refundedTax = refunded >= total ? tax : total > 0 ? Math.round((refunded * tax) / total) : 0\n      bucket.refundCount += 1\n      bucket.refundedSalesCents += refunded - refundedTax\n      bucket.refundedTaxCents += refundedTax\n    }\n\n    rows.push({\n      hostId: order.hostId,\n      store: store?.name || order.hostId,\n      orderId: order.orderId,\n      channel,\n      status: text(order.status),\n      paidAt: paidAt === null ? null : new Date(paidAt).toISOString(),\n      jurisdiction,\n      totalSalesCents: sales,\n      taxableSalesCents: taxable,\n      taxableBase,\n      taxCents: tax,\n      refundedCents: refunded,\n      refundedAt: refundedAt === null ? null : new Date(refundedAt).toISOString(),\n      inPeriodAs: sale && refund ? 'sale and refund' : sale ? 'sale' : 'refund',\n    })\n  }\n  summary.parts = [...parts.values()]\n  return { summary, rows }\n}\n\n/** The taxable base a Stripe tax row states: the largest line's, since each level restates one base. */\nexport function statedTaxableBase(\n  lines: ReadonlyArray<{ taxableAmountCents?: unknown } | null | undefined> | null | undefined,\n): number | null {\n  let base: number | null = null\n  for (const line of lines ?? []) {\n    const value = Number(line?.taxableAmountCents)\n    if (line?.taxableAmountCents === null || line?.taxableAmountCents === undefined || !Number.isFinite(value)) continue\n    base = base === null ? Math.round(value) : Math.max(base, Math.round(value))\n  }\n  return base\n}\n"],"names":["emptyTaxReturnOperatorFigures","taxJurisdictionKey","orderIsTestMode","POS_HARDWARE_ENV","ORG_ID","platformOwnStoreOrgId","env","orgId","String","sellerOrgId","trim","test","cents","value","parsed","Math","round","Number","isFinite","stamp","text","latestEvent","order","names","latest","event","Array","isArray","timeline","includes","at","atMs","firstPaidEvent","first","ownStoreOrderPaidAt","paid","paidAtMs","status","neverPaid","refundedCents","createdAtMs","ownStoreOrderRefundedAt","cancelledAtMs","updatedAtMs","ownStoreOrderIsTestMode","modes","payments","filter","payment","livemode","map","length","every","Boolean","checkoutSessionId","undefined","$id","orderId","ownStoreOrderChannel","channel","ownStoreOrderJurisdiction","store","fulfillmentMethod","origin","shipped","shippingAddress","billingAddress","ownStorePartId","hostId","partLabel","name","ownStoreTaxSummary","input","period","startMs","start","getTime","endMs","end","within","stores","Map","parts","summary","periodStart","toISOString","periodEnd","orders","totalSalesCents","excluded","testModeOrders","marketplaceRemitted","attention","untaxedOrders","ordersMissingRegion","canceledWithoutRefund","rows","seen","Set","part","jurisdiction","has","key","add","paidAt","refundedAt","sale","refund","channelSource","taxRemittedByChannel","get","partId","created","id","label","byJurisdiction","set","bucket","total","totals","totalCents","amountCents","tax","min","taxCents","sales","stated","statedBases","taxableBase","taxable","transactionCount","taxableSalesCents","taxCollectedCents","refunded","refundedTax","refundCount","refundedSalesCents","refundedTaxCents","push","Date","inPeriodAs","values","statedTaxableBase","lines","base","line","taxableAmountCents","max"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAkD2C,GAE3C,SACEA,6BAA6B,QAGxB,wDAAuD;AAC9D,SAASC,kBAAkB,QAAQ,kDAAiD;AACpF,SAASC,eAAe,QAAQ,uBAAmB;AACnD,SAASC,gBAAgB,QAAQ,oBAAgB;AAEjD,MAAMC,SAAS;AAEf;;;;;CAKC,GACD,OAAO,SAASC,sBAAsBC,GAAuC;QACtDA;IAArB,MAAMC,QAAQC,QAAOF,oCAAAA,GAAG,CAACH,iBAAiBM,WAAW,CAAC,YAAjCH,oCAAqC,IAAII,IAAI;IAClE,OAAON,OAAOO,IAAI,CAACJ,SAASA,QAAQ;AACtC;AA+EA,MAAMK,QAAQ,CAACC;IACb,MAAMC,SAASC,KAAKC,KAAK,CAACC,OAAOJ,gBAAAA,QAAS;IAC1C,OAAOI,OAAOC,QAAQ,CAACJ,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA,MAAMK,QAAQ,CAACN,QACb,OAAOA,UAAU,YAAYI,OAAOC,QAAQ,CAACL,SAASA,QAAQ;AAEhE,MAAMO,OAAO,CAACP,QAAmC,OAAOA,UAAU,YAAYA,QAAQA,QAAQ;AAE9F,wEAAwE,GACxE,SAASQ,YAAYC,KAAyB,EAAEC,KAAwB;IACtE,IAAIC,SAAwB;IAC5B,KAAK,MAAMC,SAASC,MAAMC,OAAO,CAACL,MAAMM,QAAQ,IAAIN,MAAMM,QAAQ,GAAG,EAAE,CAAE;;QACvE,IAAI,CAACL,MAAMM,QAAQ,CAACrB,eAAOiB,yBAAAA,MAAOA,KAAK,mBAAI,MAAM;QACjD,MAAMK,KAAKX,MAAMM,yBAAAA,MAAOM,IAAI;QAC5B,IAAID,OAAO,QAASN,CAAAA,WAAW,QAAQM,KAAKN,MAAK,GAAIA,SAASM;IAChE;IACA,OAAON;AACT;AAEA,6DAA6D,GAC7D,SAASQ,eAAeV,KAAyB;IAC/C,IAAIW,QAAuB;IAC3B,KAAK,MAAMR,SAASC,MAAMC,OAAO,CAACL,MAAMM,QAAQ,IAAIN,MAAMM,QAAQ,GAAG,EAAE,CAAE;QACvE,IAAIH,CAAAA,yBAAAA,MAAOA,KAAK,MAAK,QAAQ;QAC7B,MAAMK,KAAKX,MAAMM,yBAAAA,MAAOM,IAAI;QAC5B,IAAID,OAAO,QAASG,CAAAA,UAAU,QAAQH,KAAKG,KAAI,GAAIA,QAAQH;IAC7D;IACA,OAAOG;AACT;AAEA,kFAAkF,GAClF,OAAO,SAASC,oBAAoBZ,KAAyB;QAC9CH,QAESG;IAFtB,MAAMa,QAAOhB,SAAAA,MAAMG,MAAMc,QAAQ,aAApBjB,SAAyBa,eAAeV;IACrD,IAAIa,SAAS,MAAM,OAAOA;IAC1B,MAAME,SAAS7B,QAAOc,gBAAAA,MAAMe,MAAM,YAAZf,gBAAgB;IACtC,MAAMgB,YAAYD,WAAW,aAAcA,WAAW,eAAezB,MAAMU,MAAMiB,aAAa,KAAK;IACnG,OAAOD,YAAY,OAAOnB,MAAMG,MAAMkB,WAAW;AACnD;AAEA,gFAAgF,GAChF,OAAO,SAASC,wBAAwBnB,KAAyB;QAG7DD,MAAAA,OAAAA;IAFF,IAAIT,MAAMU,MAAMiB,aAAa,KAAK,GAAG,OAAO;IAC5C,QACElB,QAAAA,SAAAA,eAAAA,YAAYC,OAAO;QAAC;QAAU;KAAW,aAAzCD,eACAF,MAAMG,MAAMoB,aAAa,aADzBrB,QAEAF,MAAMG,MAAMqB,WAAW,aAFvBtB,OAGAa,oBAAoBZ;AAExB;AAEA;;;;CAIC,GACD,OAAO,SAASsB,wBAAwBtB,KAAyB;QAO1CF;IANrB,MAAMyB,QAAQ,AAACnB,CAAAA,MAAMC,OAAO,CAACL,MAAMwB,QAAQ,IAAIxB,MAAMwB,QAAQ,GAAG,EAAE,AAAD,EAC9DC,MAAM,CAAC,CAACC,UAAYA,CAAAA,2BAAAA,QAASX,MAAM,MAAK,eAAe,QAAOW,2BAAAA,QAASC,QAAQ,MAAK,WACpFC,GAAG,CAAC,CAACF,UAAYA,QAAQC,QAAQ;IACpC,IAAIJ,MAAMM,MAAM,EAAE,OAAO,CAACN,MAAMO,KAAK,CAACC;IACtC,OAAOnD,gBAAgB;QACrB+C,UAAU3B,MAAM2B,QAAQ;QACxBK,iBAAiB,GAAElC,QAAAA,KAAKE,MAAMgC,iBAAiB,aAA5BlC,QAAiCmC;QACpDC,KAAKlC,MAAMmC,OAAO;IACpB;AACF;AAEA,6CAA6C,GAC7C,OAAO,SAASC,qBAAqBpC,KAAyB;IAC5D,OAAOA,MAAMqC,OAAO,KAAK,QAAQ,cAAc;AACjD;AAEA,kDAAkD,GAClD,OAAO,SAASC,0BAA0BtC,KAAyB,EAAEuC,KAA2B;QAI3DvC,wBACyBA;IAJ5D,IAAIoC,qBAAqBpC,WAAW,eAAeA,MAAMwC,iBAAiB,KAAK,UAAU;;QACvF,OAAO7D,2BAAmB4D,yBAAAA,MAAOE,MAAM,mBAAI;IAC7C;IACA,MAAMC,UAAU/D,oBAAmBqB,yBAAAA,MAAM2C,eAAe,YAArB3C,yBAAyB;IAC5D,OAAO0C,YAAY,YAAYA,UAAU/D,oBAAmBqB,wBAAAA,MAAM4C,cAAc,YAApB5C,wBAAwB;AACtF;AAEA,kDAAkD,GAClD,OAAO,SAAS6C,eAAeC,MAAc,EAAET,OAAwB;IACrE,OAAO,CAAC,SAAS,EAAES,OAAO,CAAC,EAAET,SAAS;AACxC;AAEA,SAASU,UAAUR,KAA2B,EAAEO,MAAc,EAAET,OAAwB;IACtF,MAAMW,OAAOT,CAAAA,yBAAAA,MAAOS,IAAI,KAAIF;IAC5B,OAAOT,YAAY,cAAc,GAAGW,KAAK,iBAAiB,CAAC,GAAG,GAAGA,KAAK,cAAc,CAAC;AACvF;AAEA;;;;CAIC,GACD,OAAO,SAASC,mBAAmBC,KAKlC;QAmBqBA;IAlBpB,MAAM,EAAEC,MAAM,EAAE,GAAGD;IACnB,MAAME,UAAUD,OAAOE,KAAK,CAACC,OAAO;IACpC,MAAMC,QAAQJ,OAAOK,GAAG,CAACF,OAAO;IAChC,MAAMG,SAAS,CAACjD,KAAsBA,OAAO,QAAQA,MAAM4C,WAAW5C,KAAK+C;IAC3E,MAAMG,SAAS,IAAIC,IAAIT,MAAMQ,MAAM,CAAC9B,GAAG,CAAC,CAACW,QAAU;YAACA,MAAMO,MAAM;YAAEP;SAAM;IACxE,MAAMqB,QAAQ,IAAID;IAClB,MAAME,UAA8B;QAClCC,aAAaX,OAAOE,KAAK,CAACU,WAAW;QACrCC,WAAWb,OAAOK,GAAG,CAACO,WAAW;QACjCE,QAAQ;QACRC,iBAAiB;QACjBN,OAAO,EAAE;QACTO,UAAU;YAAEC,gBAAgB;YAAGC,qBAAqB;QAAE;QACtDC,WAAW;YAAEC,eAAe;YAAGC,qBAAqB;YAAGC,uBAAuB;QAAE;IAClF;IACA,MAAMC,OAAyB,EAAE;IACjC,MAAMC,OAAO,IAAIC;IAEjB,KAAK,MAAM5E,UAASkD,gBAAAA,MAAMe,MAAM,YAAZf,gBAAgB,EAAE,CAAE;YA0BpCU,YAUwCiB,sBAAoBC,eAApBD;YApBH7E,sBAsBnBA,eACOA,gBAEZkD;QAxCf,uEAAuE;QACvE,IAAI,EAAClD,yBAAAA,MAAOmC,OAAO,KAAI,CAACuB,OAAOqB,GAAG,CAAC/E,MAAM8C,MAAM,GAAG;QAClD,MAAMkC,MAAM,GAAGhF,MAAM8C,MAAM,CAAC,CAAC,EAAE9C,MAAMmC,OAAO,EAAE;QAC9C,IAAIwC,KAAKI,GAAG,CAACC,MAAM;QACnBL,KAAKM,GAAG,CAACD;QAET,MAAME,SAAStE,oBAAoBZ;QACnC,MAAMmF,aAAahE,wBAAwBnB;QAC3C,MAAMoF,OAAO3B,OAAOyB;QACpB,MAAMG,SAAS5B,OAAO0B;QACtB,IAAI,CAACC,QAAQ,CAACC,QAAQ;QACtB,IAAI/D,wBAAwBtB,QAAQ;YAClC,IAAIoF,MAAMvB,QAAQM,QAAQ,CAACC,cAAc,IAAI;YAC7C;QACF;QACA,IAAIpE,MAAMqC,OAAO,KAAK,iBAAiBrC,EAAAA,uBAAAA,MAAMsF,aAAa,qBAAnBtF,qBAAqBuF,oBAAoB,MAAK,MAAM;YACzF,IAAIH,MAAMvB,QAAQM,QAAQ,CAACE,mBAAmB,IAAI;YAClD;QACF;QAEA,MAAM9B,QAAQmB,OAAO8B,GAAG,CAACxF,MAAM8C,MAAM;QACrC,MAAMT,UAAUD,qBAAqBpC;QACrC,MAAM8E,eAAexC,0BAA0BtC,OAAOuC;QACtD,MAAMkD,SAAS5C,eAAe7C,MAAM8C,MAAM,EAAET;QAC5C,MAAMwC,QACJjB,aAAAA,MAAM4B,GAAG,CAACC,mBAAV7B,aACA,AAAC,CAAA;YACC,MAAM8B,UAAsC;gBAC1CC,IAAIF;gBACJG,OAAO7C,UAAUR,OAAOvC,MAAM8C,MAAM,EAAET;gBACtCwD,gBAAgB,CAAC;YACnB;YACAjC,MAAMkC,GAAG,CAACL,QAAQC;YAClB,OAAOA;QACT,CAAA;QACF,MAAMK,UAAoClB,IAAAA,CAAAA,uBAAAA,KAAKgB,cAAc,CAAA,CAACf,gBAAAA,aAAa,YAAjCD,IAAAA,oBAAmB,CAACC,cAAa,GAAKpG;QAEhF,MAAMsH,QAAQ1G,eAAMU,gBAAAA,MAAMiG,MAAM,qBAAZjG,cAAckG,UAAU,mBAAIlG,MAAMmG,WAAW;QACjE,MAAMC,MAAM3G,KAAK4G,GAAG,CAAC/G,OAAMU,iBAAAA,MAAMiG,MAAM,qBAAZjG,eAAcsG,QAAQ,GAAGN;QACpD,MAAMO,QAAQP,QAAQI;QACtB,MAAMI,UAAStD,qBAAAA,MAAMuD,WAAW,qBAAjBvD,mBAAmBsC,GAAG,CAACxF,MAAMmC,OAAO;QACnD,MAAMuE,cACJ,OAAOF,WAAW,YAAY7G,OAAOC,QAAQ,CAAC4G,UAAU,WAAWJ,MAAM,IAAI,eAAe;QAC9F,MAAMO,UACJD,gBAAgB,WAAWjH,KAAK4G,GAAG,CAAC/G,MAAMkH,SAASD,SAASG,gBAAgB,eAAeH,QAAQ;QAErG,IAAInB,MAAM;gBAScpF;YARtB6D,QAAQI,MAAM,IAAI;YAClBJ,QAAQK,eAAe,IAAIqC;YAC3BR,OAAOa,gBAAgB,IAAI;YAC3Bb,OAAO7B,eAAe,IAAIqC;YAC1BR,OAAOc,iBAAiB,IAAIF;YAC5BZ,OAAOe,iBAAiB,IAAIV;YAC5B,IAAIA,QAAQ,GAAGvC,QAAQS,SAAS,CAACC,aAAa,IAAI;YAClD,IAAIO,iBAAiB,WAAWjB,QAAQS,SAAS,CAACE,mBAAmB,IAAI;YACzE,MAAMzD,SAAS7B,QAAOc,gBAAAA,MAAMe,MAAM,YAAZf,gBAAgB;YACtC,IAAI,AAACe,CAAAA,WAAW,eAAeA,WAAW,UAAS,KAAMzB,MAAMU,MAAMiB,aAAa,KAAK,GAAG;gBACxF4C,QAAQS,SAAS,CAACG,qBAAqB,IAAI;YAC7C;QACF;QAEA,MAAMsC,WAAWtH,KAAK4G,GAAG,CAAC/G,MAAMU,MAAMiB,aAAa,GAAG+E;QACtD,IAAIX,QAAQ;YACV,wEAAwE;YACxE,4BAA4B;YAC5B,MAAM2B,cAAcD,YAAYf,QAAQI,MAAMJ,QAAQ,IAAIvG,KAAKC,KAAK,CAAC,AAACqH,WAAWX,MAAOJ,SAAS;YACjGD,OAAOkB,WAAW,IAAI;YACtBlB,OAAOmB,kBAAkB,IAAIH,WAAWC;YACxCjB,OAAOoB,gBAAgB,IAAIH;QAC7B;QAEAtC,KAAK0C,IAAI,CAAC;YACRtE,QAAQ9C,MAAM8C,MAAM;YACpBP,OAAOA,CAAAA,yBAAAA,MAAOS,IAAI,KAAIhD,MAAM8C,MAAM;YAClCX,SAASnC,MAAMmC,OAAO;YACtBE;YACAtB,QAAQjB,KAAKE,MAAMe,MAAM;YACzBmE,QAAQA,WAAW,OAAO,OAAO,IAAImC,KAAKnC,QAAQnB,WAAW;YAC7De;YACAZ,iBAAiBqC;YACjBM,mBAAmBF;YACnBD;YACAJ,UAAUF;YACVnF,eAAe8F;YACf5B,YAAYA,eAAe,OAAO,OAAO,IAAIkC,KAAKlC,YAAYpB,WAAW;YACzEuD,YAAYlC,QAAQC,SAAS,oBAAoBD,OAAO,SAAS;QACnE;IACF;IACAvB,QAAQD,KAAK,GAAG;WAAIA,MAAM2D,MAAM;KAAG;IACnC,OAAO;QAAE1D;QAASa;IAAK;AACzB;AAEA,sGAAsG,GACtG,OAAO,SAAS8C,kBACdC,KAA4F;IAE5F,IAAIC,OAAsB;IAC1B,KAAK,MAAMC,QAAQF,gBAAAA,QAAS,EAAE,CAAE;QAC9B,MAAMlI,QAAQI,OAAOgI,wBAAAA,KAAMC,kBAAkB;QAC7C,IAAID,CAAAA,wBAAAA,KAAMC,kBAAkB,MAAK,QAAQD,CAAAA,wBAAAA,KAAMC,kBAAkB,MAAK3F,aAAa,CAACtC,OAAOC,QAAQ,CAACL,QAAQ;QAC5GmI,OAAOA,SAAS,OAAOjI,KAAKC,KAAK,CAACH,SAASE,KAAKoI,GAAG,CAACH,MAAMjI,KAAKC,KAAK,CAACH;IACvE;IACA,OAAOmI;AACT"}

package/src/lib/model/plugin-permissions.d.ts

@@ -14,10 +14,84 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { HostAccessRole } from '@aglyn/aglyn/foundation/definitions/organization.types';
+import type { PluginOrgPermissionDeclaration } from '@aglyn/aglyn/plugin-manager/plugin-entitlements';
 import type { PluginPermission } from '@aglyn/aglyn/plugin-manager/plugin-permissions';
+/**
+ * The register's finer permissions (AGL-4047), each a part of `managePos`
+ * (Use the point of sale). Each REFINES it: never held without it, and,
+ * where no custom role or override sets one, it follows `managePos` — so a
+ * member keeps exactly the register they had until somebody narrows it.
+ */
+export type PosRegisterPermission = 'posSell' | 'posRefund' | 'posDiscount' | 'posCashDrawer' | 'posDevices';
+/**
+ * The register's keys and `posBuyHardware`, which stands on its own
+ * (AGL-4047): it FOLLOWS `managePos` where no custom role or override sets
+ * it, so every member keeps the hardware shop they had, but it may be
+ * granted without the register — a bookkeeper who orders the store's readers
+ * and never rings a sale.
+ */
+export type PosPermission = PosRegisterPermission | 'posBuyHardware';
 /**
  * Commerce's plugin-declared permissions (AGL-435) — the reference
  * adopter. Pure data: the client barrel and /server entry both register
  * it, so console gating and API-side resolution agree.
  */
 export declare const COMMERCE_PERMISSIONS: readonly PluginPermission[];
+/** One finer register key's label, for a refusal or a disabled control's reason. */
+export declare function posPermissionLabel(permission: PosPermission): string;
+/**
+ * Whether a resolved permission map allows one of the register's finer
+ * actions (AGL-4047): `managePos`, and the finer key not refused. A map
+ * that does not carry the finer key at all follows `managePos` — the
+ * resolvers always carry it once commerce has registered, so an absent key
+ * is a map built before that, which keeps the register it had.
+ *
+ * `posBuyHardware` stands on its own: its own verdict when the map carries
+ * one, granted with or without `managePos`, and `managePos`'s when it does
+ * not.
+ */
+export declare function holdsPosPermission(permissions: Readonly<Record<string, boolean | undefined>> | null | undefined, permission: PosPermission): boolean;
+/**
+ * Whether a member may open the hardware shop at all (AGL-4047): see what
+ * it offers and what the store ordered. Whoever works the register, and
+ * whoever may buy hardware without working it.
+ */
+export declare function mayVisitPosHardwareShop(permissions: Readonly<Record<string, boolean | undefined>> | null | undefined): boolean;
+/** The refusal a register route answers when a finer key is not held. */
+export declare function posPermissionRefusal(permission: PosPermission): string;
+/** The reservation keys. */
+export type ReservationPermission = 'commerce.reservations' | 'commerce.walkIns';
+/** Commerce's keys whose preset is the site role (AGL-4047). */
+export type CommerceSitePermission = ReservationPermission | 'commerce.orders' | 'commerce.giftCards' | 'commerce.paymentMethods' | 'commerce.shippingConnections';
+/** Who held reservations on a site before they were keys: Admin, Editor and Author. */
+export declare const RESERVATION_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>>;
+/**
+ * Who worked a site's orders and gift cards before they were keys: the site's
+ * Admin and Editor (an Author edits the catalog and never touched an order).
+ */
+export declare const ORDERS_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>>;
+/**
+ * Who changed a site's payment methods and its shipping app connections
+ * before they were keys: the site's Admin alone (an Editor could see them, as
+ * whoever works the orders still can).
+ */
+export declare const STORE_SETTINGS_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>>;
+/** The same, per workspace role: the answer with no site named. */
+export declare const STORE_SETTINGS_ORG_ROLE_PRESET: {
+    readonly owner: true;
+    readonly admin: true;
+    readonly editor: false;
+    readonly viewer: false;
+};
+/**
+ * The reservation keys as commerce declares them into the org permission
+ * catalog (AGL-4047), registered beside `COMMERCE_PERMISSIONS`.
+ */
+export declare const COMMERCE_SITE_PERMISSIONS: readonly PluginOrgPermissionDeclaration[];
+/** The refusal a door answers when a commerce site key is not held: names the permission. */
+export declare function commerceSitePermissionRefusal(key: CommerceSitePermission): string;
+/** One reservation key's label, for a refusal. */
+export declare function reservationPermissionLabel(permission: ReservationPermission): string;
+/** The refusal a reservation route answers when its key is not held; names the permission, never a role. */
+export declare function reservationPermissionRefusal(permission: ReservationPermission): string;