@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/commerce-tax-decision.d.ts

@@ -0,0 +1,222 @@
+/**
+ * @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 { TaxSettings } from './commerce-tax';
+/**
+ * Whether a storefront sale computes tax, and — when it does not — WHY
+ * (AGL-1999).
+ *
+ * ## The defect this exists to remove
+ *
+ * Nothing seeds `hosts/{hostId}/settings/store`. It is written only when the
+ * merchant opens the Taxes card and saves. Until then `tax.mode` is
+ * `undefined`, and every server-side branch tested for a specific string:
+ *
+ *   checkout.ts       `mode === 'stripe'` / `mode === 'manual'`
+ *   cart-checkout.ts  `mode === 'stripe'` / `mode === 'manual'`
+ *   draft-order.ts    `mode === 'stripe'` / `mode === 'manual'`
+ *   pos-order.ts      `mode === 'manual'`
+ *
+ * `undefined` matched neither. No branch was taken, no tax was computed, and
+ * no path refused the sale — so buy-now, cart, draft orders and POS all
+ * charged the shopper an untaxed total. The `{ mode: 'manual' }` default that
+ * makes this look safe lives ONLY in the console card's local state
+ * (`tax-settings-card.component.tsx`) and never reaches Firestore unless the
+ * merchant presses Save. A merchant who never visits the card — the default
+ * state of every new storefront — sold untaxed, and was never told.
+ *
+ * The failure is silent in both directions: the shopper is undercharged, and
+ * the merchant accrues an unremitted liability nobody mentioned. Undercharging
+ * cannot be recovered — by the time anyone notices, the shopper is gone.
+ *
+ * ## The decision taken (AGL-1999 option 1, with an explicit opt-out)
+ *
+ * **An unset tax mode REFUSES the sale.** This follows the precedent AGL-1791
+ * set for shipping: a destination no zone covers is refused, not silently
+ * zero-rated. Refusal is recoverable — the merchant sees it and configures —
+ * where undercharging is not.
+ *
+ * Defaulting to `stripe` instead was rejected, and not on ergonomics: Stripe
+ * Tax computes storefront sessions against AGLYN's registrations with
+ * `liability: self` (MEASURED — see `storefront-tax.ts`), so defaulting there
+ * silently makes Aglyn the collecting party for merchants who never asked.
+ * That is a legal position (AGL-1904 / AGL-1956), it belongs to counsel, and a
+ * default is the wrong way to take it.
+ *
+ * **But refusing every unconfigured store would be wrong too**, because plenty
+ * of merchants genuinely owe no tax — under a nexus threshold, or selling
+ * non-taxable goods. So `mode: 'none'` is a first-class, RECORDED decision
+ * meaning "I have decided not to collect", and it is honoured silently. The
+ * refusal is reserved for the one state that is not a decision at all: nobody
+ * has answered the question yet.
+ *
+ * A merchant who opens the card and saves `manual` with no rates still
+ * collects nothing. That is fine and deliberate — they were asked and they
+ * answered. The point is never that tax gets collected; it is that a human
+ * decided.
+ *
+ * Pure and total, so every path can share one answer instead of four
+ * hand-rolled string tests that already drifted once (AGL-1953).
+ */
+export type StorefrontTaxDecision = 
+/** Stripe Tax computes it. See the AGL-1904 liability note. */
+{
+    kind: 'stripe-automatic';
+}
+/** The merchant's own configured rate for the store origin. */
+ | {
+    kind: 'manual';
+}
+/** This PRODUCT is exempt; the store's mode is irrelevant to it. */
+ | {
+    kind: 'exempt';
+    reason: string;
+}
+/** The merchant decided not to collect. Honoured, and recorded. */
+ | {
+    kind: 'none';
+    reason: string;
+}
+/** Nobody has decided. The sale must be refused, not zero-rated. */
+ | {
+    kind: 'undecided';
+    reason: string;
+};
+export interface StorefrontTaxDecisionInput {
+    /** `hosts/{hostId}/settings/store.tax`, absent doc included. */
+    settings: TaxSettings | undefined | null;
+    /** The product's own `taxExempt` flag, where the path has one. */
+    taxExempt?: boolean;
+}
+/**
+ * What every storefront sales-tax path should do about tax, and why.
+ *
+ * Reservations deliberately do NOT call this: a stay is not goods, lodging is
+ * a different regime from the sales rate the AGL-285 editor configures, and
+ * that no-tax outcome is its own stated decision in `reserve.ts`.
+ */
+export declare function storefrontTaxDecision(input: StorefrontTaxDecisionInput): StorefrontTaxDecision;
+/**
+ * The message a refused shopper's merchant needs to act on. Kept beside the
+ * decision so all four paths refuse in the same words.
+ */
+export declare const STOREFRONT_TAX_UNDECIDED_MESSAGE: string;
+/**
+ * A second refusal, for the two states that ARE decisions but that the path
+ * about to run cannot honour (AGL-2145).
+ *
+ * `storefrontTaxDecision` above answers "did a human decide?", and its
+ * docblock is careful about the difference between an undecided store and one
+ * that decided to collect nothing. Both of the states below sit outside that
+ * distinction: the merchant decided to collect tax, and the sale then charged
+ * zero anyway, silently, leaving the liability with them.
+ *
+ *  1. **Manual mode with no store origin.** `resolveTaxRate` opens with
+ *     `if (!country) return null`, and every caller reads that null as "no
+ *     rate applies" — the same value it returns for a shopper in a
+ *     jurisdiction the merchant has no rate for, which is a legitimate zero.
+ *     An empty `origin.country` is not a jurisdiction miss, it is an
+ *     unfinished settings card: the merchant chose Manual, and *every* order
+ *     is then untaxed regardless of who buys. A merchant who saved `manual`
+ *     with an origin and no matching rates still collects nothing, and that
+ *     stays fine — they answered, and the answer applies per shopper.
+ *
+ *  2. **Stripe-automatic at the REGISTER.** `pos-order.ts` sends the whole
+ *     basket as one opaque `In-store purchase` line at `totals.totalCents` and
+ *     sets no `automatic_tax[enabled]` — it cannot, there is no customer
+ *     address at a till — and the cash and folio tenders never reach Stripe at
+ *     all. So a store that chose "Stripe computes my tax" got **zero** tax on
+ *     every in-person sale, on both tenders, with no refusal and no log. This
+ *     is the same defect AGL-1999 closed for the three online paths, still
+ *     open at the one place a shopper stands in front of you.
+ *
+ * `inPerson` is what separates them: (2) is a property of the REGISTER, not of
+ * the store, and online Stripe-Tax sales are correct and must not be refused.
+ *
+ * Returns the message to refuse with, or null to proceed. Never a boolean —
+ * the four paths must refuse in the merchant's own words, and a boolean is how
+ * four hand-rolled strings drift.
+ */
+export declare function storefrontTaxMisconfiguration(settings: TaxSettings | undefined | null, options?: {
+    inPerson?: boolean;
+}): string | null;
+/** @see storefrontTaxMisconfiguration — case 1. */
+export declare const STOREFRONT_TAX_NO_ORIGIN_MESSAGE: string;
+/** @see storefrontTaxMisconfiguration — case 2. */
+export declare const STOREFRONT_TAX_POS_STRIPE_MESSAGE: string;
+/**
+ * WHICH MACHINERY produced the tax on a storefront sale (AGL-1904).
+ *
+ * The canonical home for the union, because two different things need it:
+ * the `storefrontTaxCollected` record that Aglyn's own return reads
+ * (`server/storefront-tax.ts`, which re-exports this) and the `taxMode` field
+ * stamped on the merchant's ORDER (AGL-2451). One union, so the two can never
+ * disagree about what a value means.
+ *
+ *   - **`stripe-automatic`** — Stripe Tax computed it, against whichever
+ *     account `automatic_tax.liability` names. On a storefront session that is
+ *     AGLYN's platform account (MEASURED — see `server/storefront-tax.ts`).
+ *   - **`manual`** — the merchant's own configured rate, applied to their own
+ *     declared origin. Aglyn's registrations never enter into it.
+ *   - **`none`** — no tax was charged on this sale.
+ *
+ * ABSENT is a fourth state and is NOT `none`: it means "not recorded", which
+ * is what every order written before AGL-2451 genuinely is. Nothing may
+ * default it — see `describeOrderTaxMode` and the warning on `liftLegacyOrder`.
+ */
+export type StorefrontTaxMode = 'stripe-automatic' | 'manual' | 'none';
+/**
+ * THE derivation, in one place, for every path that resolves a tax mode.
+ *
+ * `automatic` is `automatic_tax.enabled` on the Stripe object, or
+ * `decision.kind === 'stripe-automatic'` where the sale never reaches Stripe
+ * at all (the register's cash and folio tenders). It is **never** "were there
+ * tax lines": a manual-mode subscription renewal carries a real Stripe Tax
+ * Rate (AGL-1751) and a manual cart or draft order has since AGL-1953, so
+ * their invoices and sessions arrive with populated tax breakdowns that are
+ * byte-indistinguishable from a Stripe Tax one. Summing lines would silently
+ * book merchant-configured tax as Aglyn-collected. **Read the flag.**
+ *
+ * `taxCents` only ever separates `manual` from `none`, and only when the flag
+ * is off: a `stripe-automatic` sale stays `stripe-automatic` at zero tax,
+ * because "Stripe Tax answered not-collecting" is itself the audit answer to
+ * why a jurisdiction is absent from a return.
+ */
+export declare function storefrontTaxMode(input: {
+    automatic: boolean;
+    taxCents: number;
+}): StorefrontTaxMode;
+/**
+ * The same derivation, from a `StorefrontTaxDecision` — for the paths that
+ * resolve tax before any Stripe object exists (`pos-order.ts`,
+ * `draft-order.ts`). `exempt` and `none` both charge nothing and land on
+ * `none`; `undecided` never reaches a write, because every caller refuses it.
+ */
+export declare function storefrontTaxModeForDecision(decision: StorefrontTaxDecision, taxCents: number): StorefrontTaxMode;
+/**
+ * How the tax on ONE order was computed, in the merchant's words (AGL-2451).
+ *
+ * Describes the MECHANISM and makes **no remittance determination** — the same
+ * constraint AGL-2440's report ships under. Who owes which authority what is a
+ * legal conclusion that attaches by operation of law (AGL-1904/AGL-1956); it
+ * belongs to counsel, and a sentence in an order dialog is the wrong place to
+ * take it.
+ *
+ * An absent mode answers "not recorded", never "no tax" — every order written
+ * before this shipped has no stamp, and rendering that as `none` would state a
+ * tax fact nobody recorded.
+ */
+export declare function describeOrderTaxMode(mode: StorefrontTaxMode | undefined | null): string;

package/src/lib/model/commerce-tax-decision.js

@@ -0,0 +1,165 @@
+/**
+ * @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.
+ */ /**
+ * What every storefront sales-tax path should do about tax, and why.
+ *
+ * Reservations deliberately do NOT call this: a stay is not goods, lodging is
+ * a different regime from the sales rate the AGL-285 editor configures, and
+ * that no-tax outcome is its own stated decision in `reserve.ts`.
+ */ export function storefrontTaxDecision(input) {
+    var _input_settings;
+    // The product flag wins over the store mode, exactly as the inline
+    // `&& !lifted.taxExempt` tests did — an exempt product is exempt whichever
+    // machinery the store uses.
+    if (input.taxExempt === true) {
+        return {
+            kind: 'exempt',
+            reason: 'the product is marked tax-exempt'
+        };
+    }
+    const mode = (_input_settings = input.settings) == null ? void 0 : _input_settings.mode;
+    if (mode === 'stripe') return {
+        kind: 'stripe-automatic'
+    };
+    if (mode === 'manual') return {
+        kind: 'manual'
+    };
+    if (mode === 'none') {
+        return {
+            kind: 'none',
+            reason: 'the store has decided not to collect sales tax'
+        };
+    }
+    // Anything else — an absent settings document, an absent `mode`, or a value
+    // written by a future version this build does not know — is NOT a decision.
+    // Refusing an unrecognised string is deliberate: guessing at it is how the
+    // original defect behaved.
+    return {
+        kind: 'undecided',
+        reason: 'no one has chosen how this store handles sales tax'
+    };
+}
+/**
+ * The message a refused shopper's merchant needs to act on. Kept beside the
+ * decision so all four paths refuse in the same words.
+ */ export const STOREFRONT_TAX_UNDECIDED_MESSAGE = 'This store has not set up sales tax yet, so we can’t take the order. ' + 'The store owner can fix this in Commerce → Settings → Taxes.';
+/**
+ * A second refusal, for the two states that ARE decisions but that the path
+ * about to run cannot honour (AGL-2145).
+ *
+ * `storefrontTaxDecision` above answers "did a human decide?", and its
+ * docblock is careful about the difference between an undecided store and one
+ * that decided to collect nothing. Both of the states below sit outside that
+ * distinction: the merchant decided to collect tax, and the sale then charged
+ * zero anyway, silently, leaving the liability with them.
+ *
+ *  1. **Manual mode with no store origin.** `resolveTaxRate` opens with
+ *     `if (!country) return null`, and every caller reads that null as "no
+ *     rate applies" — the same value it returns for a shopper in a
+ *     jurisdiction the merchant has no rate for, which is a legitimate zero.
+ *     An empty `origin.country` is not a jurisdiction miss, it is an
+ *     unfinished settings card: the merchant chose Manual, and *every* order
+ *     is then untaxed regardless of who buys. A merchant who saved `manual`
+ *     with an origin and no matching rates still collects nothing, and that
+ *     stays fine — they answered, and the answer applies per shopper.
+ *
+ *  2. **Stripe-automatic at the REGISTER.** `pos-order.ts` sends the whole
+ *     basket as one opaque `In-store purchase` line at `totals.totalCents` and
+ *     sets no `automatic_tax[enabled]` — it cannot, there is no customer
+ *     address at a till — and the cash and folio tenders never reach Stripe at
+ *     all. So a store that chose "Stripe computes my tax" got **zero** tax on
+ *     every in-person sale, on both tenders, with no refusal and no log. This
+ *     is the same defect AGL-1999 closed for the three online paths, still
+ *     open at the one place a shopper stands in front of you.
+ *
+ * `inPerson` is what separates them: (2) is a property of the REGISTER, not of
+ * the store, and online Stripe-Tax sales are correct and must not be refused.
+ *
+ * Returns the message to refuse with, or null to proceed. Never a boolean —
+ * the four paths must refuse in the merchant's own words, and a boolean is how
+ * four hand-rolled strings drift.
+ */ export function storefrontTaxMisconfiguration(settings, options = {}) {
+    var _ref;
+    var _settings_origin;
+    const mode = settings == null ? void 0 : settings.mode;
+    if (mode === 'manual' && !String((_ref = settings == null ? void 0 : (_settings_origin = settings.origin) == null ? void 0 : _settings_origin.country) != null ? _ref : '').trim()) {
+        return STOREFRONT_TAX_NO_ORIGIN_MESSAGE;
+    }
+    if (mode === 'stripe' && options.inPerson === true) {
+        return STOREFRONT_TAX_POS_STRIPE_MESSAGE;
+    }
+    return null;
+}
+/** @see storefrontTaxMisconfiguration — case 1. */ export const STOREFRONT_TAX_NO_ORIGIN_MESSAGE = 'This store collects sales tax manually but has no store address set, so ' + 'no rate can be applied. The store owner can add it in Commerce → ' + 'Settings → Taxes.';
+/** @see storefrontTaxMisconfiguration — case 2. */ export const STOREFRONT_TAX_POS_STRIPE_MESSAGE = 'This store uses automatic tax, which the register can’t calculate for an ' + 'in-person sale. The store owner can switch Taxes to Manual and add a rate ' + 'for the store address in Commerce → Settings → Taxes.';
+/**
+ * THE derivation, in one place, for every path that resolves a tax mode.
+ *
+ * `automatic` is `automatic_tax.enabled` on the Stripe object, or
+ * `decision.kind === 'stripe-automatic'` where the sale never reaches Stripe
+ * at all (the register's cash and folio tenders). It is **never** "were there
+ * tax lines": a manual-mode subscription renewal carries a real Stripe Tax
+ * Rate (AGL-1751) and a manual cart or draft order has since AGL-1953, so
+ * their invoices and sessions arrive with populated tax breakdowns that are
+ * byte-indistinguishable from a Stripe Tax one. Summing lines would silently
+ * book merchant-configured tax as Aglyn-collected. **Read the flag.**
+ *
+ * `taxCents` only ever separates `manual` from `none`, and only when the flag
+ * is off: a `stripe-automatic` sale stays `stripe-automatic` at zero tax,
+ * because "Stripe Tax answered not-collecting" is itself the audit answer to
+ * why a jurisdiction is absent from a return.
+ */ export function storefrontTaxMode(input) {
+    var _input_taxCents;
+    if (input.automatic) return 'stripe-automatic';
+    return Number((_input_taxCents = input.taxCents) != null ? _input_taxCents : 0) > 0 ? 'manual' : 'none';
+}
+/**
+ * The same derivation, from a `StorefrontTaxDecision` — for the paths that
+ * resolve tax before any Stripe object exists (`pos-order.ts`,
+ * `draft-order.ts`). `exempt` and `none` both charge nothing and land on
+ * `none`; `undecided` never reaches a write, because every caller refuses it.
+ */ export function storefrontTaxModeForDecision(decision, taxCents) {
+    return storefrontTaxMode({
+        automatic: decision.kind === 'stripe-automatic',
+        taxCents
+    });
+}
+/**
+ * How the tax on ONE order was computed, in the merchant's words (AGL-2451).
+ *
+ * Describes the MECHANISM and makes **no remittance determination** — the same
+ * constraint AGL-2440's report ships under. Who owes which authority what is a
+ * legal conclusion that attaches by operation of law (AGL-1904/AGL-1956); it
+ * belongs to counsel, and a sentence in an order dialog is the wrong place to
+ * take it.
+ *
+ * An absent mode answers "not recorded", never "no tax" — every order written
+ * before this shipped has no stamp, and rendering that as `none` would state a
+ * tax fact nobody recorded.
+ */ export function describeOrderTaxMode(mode) {
+    if (mode === 'stripe-automatic') {
+        return 'Calculated automatically by Stripe Tax at checkout, from the shopper’s address.';
+    }
+    if (mode === 'manual') {
+        return 'Calculated from this store’s own configured tax rate.';
+    }
+    if (mode === 'none') {
+        return 'No sales tax was calculated on this order.';
+    }
+    return 'How this tax was calculated was not recorded on this order.';
+}
+
+//# sourceMappingURL=commerce-tax-decision.js.map

package/src/lib/model/commerce-tax-decision.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-tax-decision.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\nimport type { TaxSettings } from './commerce-tax'\n\n/**\n * Whether a storefront sale computes tax, and — when it does not — WHY\n * (AGL-1999).\n *\n * ## The defect this exists to remove\n *\n * Nothing seeds `hosts/{hostId}/settings/store`. It is written only when the\n * merchant opens the Taxes card and saves. Until then `tax.mode` is\n * `undefined`, and every server-side branch tested for a specific string:\n *\n *   checkout.ts       `mode === 'stripe'` / `mode === 'manual'`\n *   cart-checkout.ts  `mode === 'stripe'` / `mode === 'manual'`\n *   draft-order.ts    `mode === 'stripe'` / `mode === 'manual'`\n *   pos-order.ts      `mode === 'manual'`\n *\n * `undefined` matched neither. No branch was taken, no tax was computed, and\n * no path refused the sale — so buy-now, cart, draft orders and POS all\n * charged the shopper an untaxed total. The `{ mode: 'manual' }` default that\n * makes this look safe lives ONLY in the console card's local state\n * (`tax-settings-card.component.tsx`) and never reaches Firestore unless the\n * merchant presses Save. A merchant who never visits the card — the default\n * state of every new storefront — sold untaxed, and was never told.\n *\n * The failure is silent in both directions: the shopper is undercharged, and\n * the merchant accrues an unremitted liability nobody mentioned. Undercharging\n * cannot be recovered — by the time anyone notices, the shopper is gone.\n *\n * ## The decision taken (AGL-1999 option 1, with an explicit opt-out)\n *\n * **An unset tax mode REFUSES the sale.** This follows the precedent AGL-1791\n * set for shipping: a destination no zone covers is refused, not silently\n * zero-rated. Refusal is recoverable — the merchant sees it and configures —\n * where undercharging is not.\n *\n * Defaulting to `stripe` instead was rejected, and not on ergonomics: Stripe\n * Tax computes storefront sessions against AGLYN's registrations with\n * `liability: self` (MEASURED — see `storefront-tax.ts`), so defaulting there\n * silently makes Aglyn the collecting party for merchants who never asked.\n * That is a legal position (AGL-1904 / AGL-1956), it belongs to counsel, and a\n * default is the wrong way to take it.\n *\n * **But refusing every unconfigured store would be wrong too**, because plenty\n * of merchants genuinely owe no tax — under a nexus threshold, or selling\n * non-taxable goods. So `mode: 'none'` is a first-class, RECORDED decision\n * meaning \"I have decided not to collect\", and it is honoured silently. The\n * refusal is reserved for the one state that is not a decision at all: nobody\n * has answered the question yet.\n *\n * A merchant who opens the card and saves `manual` with no rates still\n * collects nothing. That is fine and deliberate — they were asked and they\n * answered. The point is never that tax gets collected; it is that a human\n * decided.\n *\n * Pure and total, so every path can share one answer instead of four\n * hand-rolled string tests that already drifted once (AGL-1953).\n */\nexport type StorefrontTaxDecision =\n  /** Stripe Tax computes it. See the AGL-1904 liability note. */\n  | { kind: 'stripe-automatic' }\n  /** The merchant's own configured rate for the store origin. */\n  | { kind: 'manual' }\n  /** This PRODUCT is exempt; the store's mode is irrelevant to it. */\n  | { kind: 'exempt'; reason: string }\n  /** The merchant decided not to collect. Honoured, and recorded. */\n  | { kind: 'none'; reason: string }\n  /** Nobody has decided. The sale must be refused, not zero-rated. */\n  | { kind: 'undecided'; reason: string }\n\nexport interface StorefrontTaxDecisionInput {\n  /** `hosts/{hostId}/settings/store.tax`, absent doc included. */\n  settings: TaxSettings | undefined | null\n  /** The product's own `taxExempt` flag, where the path has one. */\n  taxExempt?: boolean\n}\n\n/**\n * What every storefront sales-tax path should do about tax, and why.\n *\n * Reservations deliberately do NOT call this: a stay is not goods, lodging is\n * a different regime from the sales rate the AGL-285 editor configures, and\n * that no-tax outcome is its own stated decision in `reserve.ts`.\n */\nexport function storefrontTaxDecision(\n  input: StorefrontTaxDecisionInput,\n): StorefrontTaxDecision {\n  // The product flag wins over the store mode, exactly as the inline\n  // `&& !lifted.taxExempt` tests did — an exempt product is exempt whichever\n  // machinery the store uses.\n  if (input.taxExempt === true) {\n    return {\n      kind: 'exempt',\n      reason: 'the product is marked tax-exempt',\n    }\n  }\n  const mode = input.settings?.mode\n  if (mode === 'stripe') return { kind: 'stripe-automatic' }\n  if (mode === 'manual') return { kind: 'manual' }\n  if (mode === 'none') {\n    return {\n      kind: 'none',\n      reason: 'the store has decided not to collect sales tax',\n    }\n  }\n  // Anything else — an absent settings document, an absent `mode`, or a value\n  // written by a future version this build does not know — is NOT a decision.\n  // Refusing an unrecognised string is deliberate: guessing at it is how the\n  // original defect behaved.\n  return {\n    kind: 'undecided',\n    reason: 'no one has chosen how this store handles sales tax',\n  }\n}\n\n/**\n * The message a refused shopper's merchant needs to act on. Kept beside the\n * decision so all four paths refuse in the same words.\n */\nexport const STOREFRONT_TAX_UNDECIDED_MESSAGE =\n  'This store has not set up sales tax yet, so we can’t take the order. ' +\n  'The store owner can fix this in Commerce → Settings → Taxes.'\n\n/**\n * A second refusal, for the two states that ARE decisions but that the path\n * about to run cannot honour (AGL-2145).\n *\n * `storefrontTaxDecision` above answers \"did a human decide?\", and its\n * docblock is careful about the difference between an undecided store and one\n * that decided to collect nothing. Both of the states below sit outside that\n * distinction: the merchant decided to collect tax, and the sale then charged\n * zero anyway, silently, leaving the liability with them.\n *\n *  1. **Manual mode with no store origin.** `resolveTaxRate` opens with\n *     `if (!country) return null`, and every caller reads that null as \"no\n *     rate applies\" — the same value it returns for a shopper in a\n *     jurisdiction the merchant has no rate for, which is a legitimate zero.\n *     An empty `origin.country` is not a jurisdiction miss, it is an\n *     unfinished settings card: the merchant chose Manual, and *every* order\n *     is then untaxed regardless of who buys. A merchant who saved `manual`\n *     with an origin and no matching rates still collects nothing, and that\n *     stays fine — they answered, and the answer applies per shopper.\n *\n *  2. **Stripe-automatic at the REGISTER.** `pos-order.ts` sends the whole\n *     basket as one opaque `In-store purchase` line at `totals.totalCents` and\n *     sets no `automatic_tax[enabled]` — it cannot, there is no customer\n *     address at a till — and the cash and folio tenders never reach Stripe at\n *     all. So a store that chose \"Stripe computes my tax\" got **zero** tax on\n *     every in-person sale, on both tenders, with no refusal and no log. This\n *     is the same defect AGL-1999 closed for the three online paths, still\n *     open at the one place a shopper stands in front of you.\n *\n * `inPerson` is what separates them: (2) is a property of the REGISTER, not of\n * the store, and online Stripe-Tax sales are correct and must not be refused.\n *\n * Returns the message to refuse with, or null to proceed. Never a boolean —\n * the four paths must refuse in the merchant's own words, and a boolean is how\n * four hand-rolled strings drift.\n */\nexport function storefrontTaxMisconfiguration(\n  settings: TaxSettings | undefined | null,\n  options: { inPerson?: boolean } = {},\n): string | null {\n  const mode = settings?.mode\n  if (mode === 'manual' && !String(settings?.origin?.country ?? '').trim()) {\n    return STOREFRONT_TAX_NO_ORIGIN_MESSAGE\n  }\n  if (mode === 'stripe' && options.inPerson === true) {\n    return STOREFRONT_TAX_POS_STRIPE_MESSAGE\n  }\n  return null\n}\n\n/** @see storefrontTaxMisconfiguration — case 1. */\nexport const STOREFRONT_TAX_NO_ORIGIN_MESSAGE =\n  'This store collects sales tax manually but has no store address set, so ' +\n  'no rate can be applied. The store owner can add it in Commerce → ' +\n  'Settings → Taxes.'\n\n/** @see storefrontTaxMisconfiguration — case 2. */\nexport const STOREFRONT_TAX_POS_STRIPE_MESSAGE =\n  'This store uses automatic tax, which the register can’t calculate for an ' +\n  'in-person sale. The store owner can switch Taxes to Manual and add a rate ' +\n  'for the store address in Commerce → Settings → Taxes.'\n\n/**\n * WHICH MACHINERY produced the tax on a storefront sale (AGL-1904).\n *\n * The canonical home for the union, because two different things need it:\n * the `storefrontTaxCollected` record that Aglyn's own return reads\n * (`server/storefront-tax.ts`, which re-exports this) and the `taxMode` field\n * stamped on the merchant's ORDER (AGL-2451). One union, so the two can never\n * disagree about what a value means.\n *\n *   - **`stripe-automatic`** — Stripe Tax computed it, against whichever\n *     account `automatic_tax.liability` names. On a storefront session that is\n *     AGLYN's platform account (MEASURED — see `server/storefront-tax.ts`).\n *   - **`manual`** — the merchant's own configured rate, applied to their own\n *     declared origin. Aglyn's registrations never enter into it.\n *   - **`none`** — no tax was charged on this sale.\n *\n * ABSENT is a fourth state and is NOT `none`: it means \"not recorded\", which\n * is what every order written before AGL-2451 genuinely is. Nothing may\n * default it — see `describeOrderTaxMode` and the warning on `liftLegacyOrder`.\n */\nexport type StorefrontTaxMode = 'stripe-automatic' | 'manual' | 'none'\n\n/**\n * THE derivation, in one place, for every path that resolves a tax mode.\n *\n * `automatic` is `automatic_tax.enabled` on the Stripe object, or\n * `decision.kind === 'stripe-automatic'` where the sale never reaches Stripe\n * at all (the register's cash and folio tenders). It is **never** \"were there\n * tax lines\": a manual-mode subscription renewal carries a real Stripe Tax\n * Rate (AGL-1751) and a manual cart or draft order has since AGL-1953, so\n * their invoices and sessions arrive with populated tax breakdowns that are\n * byte-indistinguishable from a Stripe Tax one. Summing lines would silently\n * book merchant-configured tax as Aglyn-collected. **Read the flag.**\n *\n * `taxCents` only ever separates `manual` from `none`, and only when the flag\n * is off: a `stripe-automatic` sale stays `stripe-automatic` at zero tax,\n * because \"Stripe Tax answered not-collecting\" is itself the audit answer to\n * why a jurisdiction is absent from a return.\n */\nexport function storefrontTaxMode(input: {\n  automatic: boolean\n  taxCents: number\n}): StorefrontTaxMode {\n  if (input.automatic) return 'stripe-automatic'\n  return Number(input.taxCents ?? 0) > 0 ? 'manual' : 'none'\n}\n\n/**\n * The same derivation, from a `StorefrontTaxDecision` — for the paths that\n * resolve tax before any Stripe object exists (`pos-order.ts`,\n * `draft-order.ts`). `exempt` and `none` both charge nothing and land on\n * `none`; `undecided` never reaches a write, because every caller refuses it.\n */\nexport function storefrontTaxModeForDecision(\n  decision: StorefrontTaxDecision,\n  taxCents: number,\n): StorefrontTaxMode {\n  return storefrontTaxMode({\n    automatic: decision.kind === 'stripe-automatic',\n    taxCents,\n  })\n}\n\n/**\n * How the tax on ONE order was computed, in the merchant's words (AGL-2451).\n *\n * Describes the MECHANISM and makes **no remittance determination** — the same\n * constraint AGL-2440's report ships under. Who owes which authority what is a\n * legal conclusion that attaches by operation of law (AGL-1904/AGL-1956); it\n * belongs to counsel, and a sentence in an order dialog is the wrong place to\n * take it.\n *\n * An absent mode answers \"not recorded\", never \"no tax\" — every order written\n * before this shipped has no stamp, and rendering that as `none` would state a\n * tax fact nobody recorded.\n */\nexport function describeOrderTaxMode(\n  mode: StorefrontTaxMode | undefined | null,\n): string {\n  if (mode === 'stripe-automatic') {\n    return 'Calculated automatically by Stripe Tax at checkout, from the shopper’s address.'\n  }\n  if (mode === 'manual') {\n    return 'Calculated from this store’s own configured tax rate.'\n  }\n  if (mode === 'none') {\n    return 'No sales tax was calculated on this order.'\n  }\n  return 'How this tax was calculated was not recorded on this order.'\n}\n"],"names":["storefrontTaxDecision","input","taxExempt","kind","reason","mode","settings","STOREFRONT_TAX_UNDECIDED_MESSAGE","storefrontTaxMisconfiguration","options","String","origin","country","trim","STOREFRONT_TAX_NO_ORIGIN_MESSAGE","inPerson","STOREFRONT_TAX_POS_STRIPE_MESSAGE","storefrontTaxMode","automatic","Number","taxCents","storefrontTaxModeForDecision","decision","describeOrderTaxMode"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA+ED;;;;;;CAMC,GACD,OAAO,SAASA,sBACdC,KAAiC;QAWpBA;IATb,mEAAmE;IACnE,2EAA2E;IAC3E,4BAA4B;IAC5B,IAAIA,MAAMC,SAAS,KAAK,MAAM;QAC5B,OAAO;YACLC,MAAM;YACNC,QAAQ;QACV;IACF;IACA,MAAMC,QAAOJ,kBAAAA,MAAMK,QAAQ,qBAAdL,gBAAgBI,IAAI;IACjC,IAAIA,SAAS,UAAU,OAAO;QAAEF,MAAM;IAAmB;IACzD,IAAIE,SAAS,UAAU,OAAO;QAAEF,MAAM;IAAS;IAC/C,IAAIE,SAAS,QAAQ;QACnB,OAAO;YACLF,MAAM;YACNC,QAAQ;QACV;IACF;IACA,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,2BAA2B;IAC3B,OAAO;QACLD,MAAM;QACNC,QAAQ;IACV;AACF;AAEA;;;CAGC,GACD,OAAO,MAAMG,mCACX,0EACA,+DAA8D;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCC,GACD,OAAO,SAASC,8BACdF,QAAwC,EACxCG,UAAkC,CAAC,CAAC;;QAGHH;IADjC,MAAMD,OAAOC,4BAAAA,SAAUD,IAAI;IAC3B,IAAIA,SAAS,YAAY,CAACK,eAAOJ,6BAAAA,mBAAAA,SAAUK,MAAM,qBAAhBL,iBAAkBM,OAAO,mBAAI,IAAIC,IAAI,IAAI;QACxE,OAAOC;IACT;IACA,IAAIT,SAAS,YAAYI,QAAQM,QAAQ,KAAK,MAAM;QAClD,OAAOC;IACT;IACA,OAAO;AACT;AAEA,iDAAiD,GACjD,OAAO,MAAMF,mCACX,6EACA,sEACA,oBAAmB;AAErB,iDAAiD,GACjD,OAAO,MAAME,oCACX,8EACA,+EACA,wDAAuD;AAwBzD;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASC,kBAAkBhB,KAGjC;QAEeA;IADd,IAAIA,MAAMiB,SAAS,EAAE,OAAO;IAC5B,OAAOC,QAAOlB,kBAAAA,MAAMmB,QAAQ,YAAdnB,kBAAkB,KAAK,IAAI,WAAW;AACtD;AAEA;;;;;CAKC,GACD,OAAO,SAASoB,6BACdC,QAA+B,EAC/BF,QAAgB;IAEhB,OAAOH,kBAAkB;QACvBC,WAAWI,SAASnB,IAAI,KAAK;QAC7BiB;IACF;AACF;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASG,qBACdlB,IAA0C;IAE1C,IAAIA,SAAS,oBAAoB;QAC/B,OAAO;IACT;IACA,IAAIA,SAAS,UAAU;QACrB,OAAO;IACT;IACA,IAAIA,SAAS,QAAQ;QACnB,OAAO;IACT;IACA,OAAO;AACT"}

package/src/lib/model/commerce-tax.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @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.
+ */
+/**
+ * Taxes v1 (AGL-285): manual rates per region resolved most-specific
+ * first (country+state beats country), or Stripe Tax automatic
+ * calculation when the host opts in. Settings live on the
+ * `hosts/{hostId}/settings/store` doc under `tax`. Pure — checkout and
+ * POS call these; Stripe Tax mode bypasses them entirely.
+ */
+export interface TaxRate {
+    /** ISO-3166 alpha-2, e.g. 'US'. */
+    country: string;
+    /** Region/state code, e.g. 'TX'; absent = whole country. */
+    state?: string;
+    /** Percent, e.g. 8.25. */
+    pct: number;
+    /** Receipt label, e.g. 'TX sales tax'. */
+    label?: string;
+}
+/**
+ * A FLAT, merchant-entered rate for a regime the goods sales-tax machinery
+ * above does not describe (AGL-1969 lodging, AGL-2028 services).
+ *
+ * ## Why this is not another `TaxRate`
+ *
+ * `rates[]` is a SALES tax table resolved against an address, most-specific
+ * first. Lodging (occupancy/hotel tax) and service tax are separate regimes
+ * with their own rates, their own registration and their own return, and the
+ * number a merchant typed into the goods table is not the right number for a
+ * night or an appointment. Reading `rates[]` for either would be confidently
+ * wrong rather than merely absent — which is exactly why `reserve.ts` and
+ * `bookings/server.ts` charged nothing at all until the merchant was given a
+ * field of their own to answer in.
+ *
+ * ## Off is the default and the default is load-bearing
+ *
+ * An absent, zero, negative, non-finite or out-of-range `pct` resolves to
+ * ZERO. Nothing an existing merchant is charging today moves because this
+ * shipped; a rate applies only once a merchant has typed one and saved.
+ *
+ * ## It is always MANUAL, in every store mode
+ *
+ * Deliberately independent of `TaxSettings.mode`. Stripe Tax cannot compute
+ * either regime from these sessions — it needs a lodging or service tax code
+ * no handler here sends — so a `mode: 'stripe'` store would otherwise have no
+ * way to collect them at all. Riding as an ordinary line item makes the
+ * derived `taxMode` read `manual`: the merchant's own rate, never computed
+ * against Aglyn's registrations (AGL-1904).
+ *
+ * ## Aglyn takes NO position on what is owed
+ *
+ * This is a calculator the merchant configures, records and can read back. It
+ * states no view on whether a jurisdiction imposes the tax, on who must
+ * register, or on who must remit — those attach by operation of law and
+ * belong to counsel (AGL-1904).
+ *
+ * ⚠️ The sentence that used to stand here — "Terms §10.3 already puts the
+ * question on the merchant" — is FALSE as of 2026-08-24 (AGL-1956). Aglyn
+ * accepts marketplace-facilitator status, ToS §10.3 no longer assigns sales
+ * tax to the merchant, and the new ToS §10.7 says Aglyn calculates, collects
+ * and remits it WHERE IT HAS A FACILITATOR OBLIGATION. Do not cite §10.3 as
+ * authority for merchant-facing tax copy again.
+ *
+ * What is still true, and is why this module did not change: these FLAT RATES
+ * are the manual/lodging/service path, which never touches Aglyn's
+ * registrations and is not what §10.7 covers. The rates a merchant types here
+ * remain theirs to determine.
+ *
+ * The merchant-facing copy this note used to call an OWED follow-up is DONE.
+ * `storefront-tax-summary-card.component.tsx` said "Aglyn does not make that
+ * determination for you" and was rewritten to §10.7 in `f7e5465f5`.
+ * `tax-settings-card.component.tsx` was read and needed no change — it governs
+ * exactly these flat lodging/service rates, which §10.7 does not reach, so it
+ * was already saying the right thing about the right taxes. Recorded rather
+ * than deleted: the next reader should not have to re-derive that the second
+ * card's silence is correct rather than overlooked.
+ */
+export interface FlatTaxRate {
+    /** Percent, e.g. 6. Absent or non-positive = off, which is the default. */
+    pct?: number;
+    /** Receipt label, e.g. 'Occupancy tax'. */
+    label?: string;
+}
+/** What a flat rate resolved to for one charge. */
+export interface ResolvedFlatTax {
+    taxCents: number;
+    /** The label to put on the receipt line; empty when there is no tax. */
+    label: string;
+    /** The percentage actually applied — 0 when the rate is off or invalid. */
+    pct: number;
+}
+/**
+ * The highest percentage this accepts. A rate above 100% is a decimal-point
+ * typo (`825` for `8.25`), not a jurisdiction, and multiplying a guest's
+ * deposit by nine because of one is a far worse failure than collecting
+ * nothing. Out of range resolves to OFF rather than being clamped to a number
+ * the merchant did not choose — and the editor says so on screen, so the
+ * refusal is never silent.
+ */
+export declare const FLAT_TAX_MAX_PCT = 100;
+/** True when a typed percentage is one this will actually apply. */
+export declare function isUsableFlatTaxPct(pct: unknown): boolean;
+/**
+ * Tax cents for a flat merchant rate on one charged amount, EXCLUSIVE — added
+ * on top of the price, never back-calculated out of it.
+ *
+ * `pricesIncludeTax` is deliberately not consulted: it is a goods-pricing
+ * setting, and honouring it here would mean a merchant types a lodging rate,
+ * saves, and the guest's total does not move — a setting that reads as
+ * configured while collecting nothing is the AGL-1999 failure restated.
+ *
+ * Pure and total. Unusable input answers zero and never throws.
+ */
+export declare function resolveFlatTaxCents(rate: FlatTaxRate | undefined | null, chargeCents: number, fallbackLabel: string): ResolvedFlatTax;
+export interface TaxSettings {
+    /**
+     * 'manual' rates below, 'stripe' for Stripe Tax automatic, or 'none' —
+     * an EXPLICIT decision not to collect (AGL-1999). `undefined` is not a
+     * fourth mode: it means nobody has decided, and `storefrontTaxDecision`
+     * refuses the sale rather than zero-rating it silently.
+     */
+    mode?: 'manual' | 'stripe' | 'none';
+    /** Displayed prices already include tax (VAT-style). */
+    pricesIncludeTax?: boolean;
+    /**
+     * Store origin (AGL-285): the legacy single-product checkout taxes by
+     * origin because the buyer address arrives inside Stripe Checkout;
+     * Checkout v2 (AGL-296) collects the address first and taxes by
+     * destination.
+     */
+    origin?: TaxAddress;
+    rates?: TaxRate[];
+    /**
+     * OCCUPANCY / LODGING tax on a reservation deposit (AGL-1969). Off unless
+     * the merchant sets it — see `FlatTaxRate`. Read by `reserve.ts` only.
+     */
+    lodging?: FlatTaxRate;
+    /**
+     * SERVICE tax on a paid booking (AGL-2028). Off unless the merchant sets
+     * it — see `FlatTaxRate`. Read by the bookings plugin only.
+     *
+     * ITS EXISTENCE IS THE OPT-IN. AGL-2000 declined to apply the goods
+     * `rates[]` to an appointment partly because nothing said the merchant
+     * meant those settings to cover bookings — they are another plugin's
+     * surface. A field of its own, labelled for services and blank until
+     * somebody fills it in, is the merchant saying so explicitly. Reading
+     * `rates[]` for a booking is still wrong and still nothing does it.
+     */
+    service?: FlatTaxRate;
+}
+export interface TaxAddress {
+    country?: string;
+    state?: string;
+}
+/** Most-specific matching rate, or null (no tax). */
+export declare function resolveTaxRate(settings: TaxSettings | undefined, address: TaxAddress): TaxRate | null;
+/**
+ * Tax cents for a taxable amount. Exclusive pricing adds on top;
+ * inclusive pricing back-calculates the contained tax (for receipts —
+ * the charge total does not change).
+ */
+export declare function computeTaxCents(taxableCents: number, pct: number, pricesIncludeTax?: boolean): number;