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

package/src/lib/model/product-channel.js

@@ -0,0 +1,86 @@
+/**
+ * @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 shopping channels ask of a product beyond what the store shows
+ * (AGL-3637): the brand, the manufacturer's identifiers, the condition and
+ * Google's category. Entered in the product editor's channel fields and read
+ * by the product catalog the store publishes to other plugins
+ * (`server/product-catalog.ts`). Every field is optional: a channel feed
+ * falls back to the store's defaults and says what is missing.
+ */ export const PRODUCT_CHANNEL_CONDITIONS = [
+    'new',
+    'refurbished',
+    'used'
+];
+/** Digits only, at most 14: what a barcode field holds once spaces and dashes are gone. */ export function normalizeGtin(value) {
+    return String(value != null ? value : '').replace(/[\s-]/g, '').replace(/[^0-9]/g, '').slice(0, 14);
+}
+const text = (value, max)=>String(value != null ? value : '').replace(/\s+/g, ' ').trim().slice(0, max);
+/**
+ * A stored product's channel facts made safe; `undefined` when nothing is
+ * set. Never throws: the field is written by the editor, the importer and the
+ * REST API, and read on every feed fetch.
+ */ export function normalizeProductChannelFacts(value) {
+    var _raw_condition;
+    if (!value || typeof value !== 'object') return undefined;
+    const raw = value;
+    const facts = {};
+    const brand = text(raw['brand'], 70);
+    if (brand) facts.brand = brand;
+    const gtin = normalizeGtin(raw['gtin']);
+    if (gtin.length >= 8) facts.gtin = gtin;
+    const mpn = text(raw['mpn'], 70);
+    if (mpn) facts.mpn = mpn;
+    const condition = String((_raw_condition = raw['condition']) != null ? _raw_condition : '').trim().toLowerCase();
+    if (PRODUCT_CHANNEL_CONDITIONS.includes(condition)) {
+        facts.condition = condition;
+    }
+    const category = text(raw['googleProductCategory'], 750);
+    if (category) facts.googleProductCategory = category;
+    return Object.keys(facts).length ? facts : undefined;
+}
+/**
+ * Channel facts as the product editor stages them, keystroke by keystroke:
+ * what {@link normalizeProductChannelFacts} keeps, except that a field being
+ * typed is kept as typed — a barcode shorter than eight digits, a brand with
+ * the space before its next word. The editor runs this on every keystroke, so
+ * the strict form would erase the field under the cursor; readers normalize
+ * what is stored, so a half-typed value never reaches a channel.
+ */ export function draftProductChannelFacts(value) {
+    var _raw_condition;
+    if (!value || typeof value !== 'object') return undefined;
+    const raw = value;
+    const facts = {};
+    const typed = (field, max)=>{
+        var _raw_field;
+        return String((_raw_field = raw[field]) != null ? _raw_field : '').replace(/^\s+/, '').slice(0, max);
+    };
+    const brand = typed('brand', 70);
+    if (brand) facts.brand = brand;
+    const gtin = normalizeGtin(raw['gtin']);
+    if (gtin) facts.gtin = gtin;
+    const mpn = typed('mpn', 70);
+    if (mpn) facts.mpn = mpn;
+    const condition = String((_raw_condition = raw['condition']) != null ? _raw_condition : '').trim().toLowerCase();
+    if (PRODUCT_CHANNEL_CONDITIONS.includes(condition)) {
+        facts.condition = condition;
+    }
+    const category = typed('googleProductCategory', 750);
+    if (category) facts.googleProductCategory = category;
+    return Object.keys(facts).length ? facts : undefined;
+}
+
+//# sourceMappingURL=product-channel.js.map

package/src/lib/model/product-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/product-channel.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 * What shopping channels ask of a product beyond what the store shows\n * (AGL-3637): the brand, the manufacturer's identifiers, the condition and\n * Google's category. Entered in the product editor's channel fields and read\n * by the product catalog the store publishes to other plugins\n * (`server/product-catalog.ts`). Every field is optional: a channel feed\n * falls back to the store's defaults and says what is missing.\n */\nexport interface ProductChannelFacts {\n  /** The brand a shopper knows it by; at most 70 characters. */\n  brand?: string\n  /**\n   * The product's GTIN (UPC, EAN, ISBN, JAN or ITF-14), digits only. For a\n   * product with several configurations each variant's barcode is its own.\n   */\n  gtin?: string\n  /** The manufacturer's part number; at most 70 characters. */\n  mpn?: string\n  condition?: 'new' | 'refurbished' | 'used'\n  /** A Google product taxonomy id (`2271`) or full path. */\n  googleProductCategory?: string\n}\n\nexport const PRODUCT_CHANNEL_CONDITIONS = ['new', 'refurbished', 'used'] as const\n\n/** Digits only, at most 14: what a barcode field holds once spaces and dashes are gone. */\nexport function normalizeGtin(value: unknown): string {\n  return String(value ?? '')\n    .replace(/[\\s-]/g, '')\n    .replace(/[^0-9]/g, '')\n    .slice(0, 14)\n}\n\nconst text = (value: unknown, max: number): string =>\n  String(value ?? '')\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .slice(0, max)\n\n/**\n * A stored product's channel facts made safe; `undefined` when nothing is\n * set. Never throws: the field is written by the editor, the importer and the\n * REST API, and read on every feed fetch.\n */\nexport function normalizeProductChannelFacts(value: unknown): ProductChannelFacts | undefined {\n  if (!value || typeof value !== 'object') return undefined\n  const raw = value as Record<string, unknown>\n  const facts: ProductChannelFacts = {}\n  const brand = text(raw['brand'], 70)\n  if (brand) facts.brand = brand\n  const gtin = normalizeGtin(raw['gtin'])\n  if (gtin.length >= 8) facts.gtin = gtin\n  const mpn = text(raw['mpn'], 70)\n  if (mpn) facts.mpn = mpn\n  const condition = String(raw['condition'] ?? '').trim().toLowerCase()\n  if ((PRODUCT_CHANNEL_CONDITIONS as readonly string[]).includes(condition)) {\n    facts.condition = condition as ProductChannelFacts['condition']\n  }\n  const category = text(raw['googleProductCategory'], 750)\n  if (category) facts.googleProductCategory = category\n  return Object.keys(facts).length ? facts : undefined\n}\n\n/**\n * Channel facts as the product editor stages them, keystroke by keystroke:\n * what {@link normalizeProductChannelFacts} keeps, except that a field being\n * typed is kept as typed — a barcode shorter than eight digits, a brand with\n * the space before its next word. The editor runs this on every keystroke, so\n * the strict form would erase the field under the cursor; readers normalize\n * what is stored, so a half-typed value never reaches a channel.\n */\nexport function draftProductChannelFacts(value: unknown): ProductChannelFacts | undefined {\n  if (!value || typeof value !== 'object') return undefined\n  const raw = value as Record<string, unknown>\n  const facts: ProductChannelFacts = {}\n  const typed = (field: string, max: number) => String(raw[field] ?? '').replace(/^\\s+/, '').slice(0, max)\n  const brand = typed('brand', 70)\n  if (brand) facts.brand = brand\n  const gtin = normalizeGtin(raw['gtin'])\n  if (gtin) facts.gtin = gtin\n  const mpn = typed('mpn', 70)\n  if (mpn) facts.mpn = mpn\n  const condition = String(raw['condition'] ?? '').trim().toLowerCase()\n  if ((PRODUCT_CHANNEL_CONDITIONS as readonly string[]).includes(condition)) {\n    facts.condition = condition as ProductChannelFacts['condition']\n  }\n  const category = typed('googleProductCategory', 750)\n  if (category) facts.googleProductCategory = category\n  return Object.keys(facts).length ? facts : undefined\n}\n"],"names":["PRODUCT_CHANNEL_CONDITIONS","normalizeGtin","value","String","replace","slice","text","max","trim","normalizeProductChannelFacts","raw","undefined","facts","brand","gtin","length","mpn","condition","toLowerCase","includes","category","googleProductCategory","Object","keys","draftProductChannelFacts","typed","field"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;CAOC,GAgBD,OAAO,MAAMA,6BAA6B;IAAC;IAAO;IAAe;CAAO,CAAS;AAEjF,yFAAyF,GACzF,OAAO,SAASC,cAAcC,KAAc;IAC1C,OAAOC,OAAOD,gBAAAA,QAAS,IACpBE,OAAO,CAAC,UAAU,IAClBA,OAAO,CAAC,WAAW,IACnBC,KAAK,CAAC,GAAG;AACd;AAEA,MAAMC,OAAO,CAACJ,OAAgBK,MAC5BJ,OAAOD,gBAAAA,QAAS,IACbE,OAAO,CAAC,QAAQ,KAChBI,IAAI,GACJH,KAAK,CAAC,GAAGE;AAEd;;;;CAIC,GACD,OAAO,SAASE,6BAA6BP,KAAc;QAUhCQ;IATzB,IAAI,CAACR,SAAS,OAAOA,UAAU,UAAU,OAAOS;IAChD,MAAMD,MAAMR;IACZ,MAAMU,QAA6B,CAAC;IACpC,MAAMC,QAAQP,KAAKI,GAAG,CAAC,QAAQ,EAAE;IACjC,IAAIG,OAAOD,MAAMC,KAAK,GAAGA;IACzB,MAAMC,OAAOb,cAAcS,GAAG,CAAC,OAAO;IACtC,IAAII,KAAKC,MAAM,IAAI,GAAGH,MAAME,IAAI,GAAGA;IACnC,MAAME,MAAMV,KAAKI,GAAG,CAAC,MAAM,EAAE;IAC7B,IAAIM,KAAKJ,MAAMI,GAAG,GAAGA;IACrB,MAAMC,YAAYd,QAAOO,iBAAAA,GAAG,CAAC,YAAY,YAAhBA,iBAAoB,IAAIF,IAAI,GAAGU,WAAW;IACnE,IAAI,AAAClB,2BAAiDmB,QAAQ,CAACF,YAAY;QACzEL,MAAMK,SAAS,GAAGA;IACpB;IACA,MAAMG,WAAWd,KAAKI,GAAG,CAAC,wBAAwB,EAAE;IACpD,IAAIU,UAAUR,MAAMS,qBAAqB,GAAGD;IAC5C,OAAOE,OAAOC,IAAI,CAACX,OAAOG,MAAM,GAAGH,QAAQD;AAC7C;AAEA;;;;;;;CAOC,GACD,OAAO,SAASa,yBAAyBtB,KAAc;QAW5BQ;IAVzB,IAAI,CAACR,SAAS,OAAOA,UAAU,UAAU,OAAOS;IAChD,MAAMD,MAAMR;IACZ,MAAMU,QAA6B,CAAC;IACpC,MAAMa,QAAQ,CAACC,OAAenB;YAAuBG;eAAPP,QAAOO,aAAAA,GAAG,CAACgB,MAAM,YAAVhB,aAAc,IAAIN,OAAO,CAAC,QAAQ,IAAIC,KAAK,CAAC,GAAGE;;IACpG,MAAMM,QAAQY,MAAM,SAAS;IAC7B,IAAIZ,OAAOD,MAAMC,KAAK,GAAGA;IACzB,MAAMC,OAAOb,cAAcS,GAAG,CAAC,OAAO;IACtC,IAAII,MAAMF,MAAME,IAAI,GAAGA;IACvB,MAAME,MAAMS,MAAM,OAAO;IACzB,IAAIT,KAAKJ,MAAMI,GAAG,GAAGA;IACrB,MAAMC,YAAYd,QAAOO,iBAAAA,GAAG,CAAC,YAAY,YAAhBA,iBAAoB,IAAIF,IAAI,GAAGU,WAAW;IACnE,IAAI,AAAClB,2BAAiDmB,QAAQ,CAACF,YAAY;QACzEL,MAAMK,SAAS,GAAGA;IACpB;IACA,MAAMG,WAAWK,MAAM,yBAAyB;IAChD,IAAIL,UAAUR,MAAMS,qBAAqB,GAAGD;IAC5C,OAAOE,OAAOC,IAAI,CAACX,OAAOG,MAAM,GAAGH,QAAQD;AAC7C"}

package/src/lib/model/product-modifiers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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.
+ */
+/** One choice in a modifier group. `priceCents` is added to the item, 0 for free. */
+export interface ProductModifierOption {
+    id: string;
+    name: string;
+    priceCents: number;
+}
+/**
+ * A set of choices offered together ("Milk", "Add-ons"). `min` of 1 or more
+ * makes it required; `max` caps how many can be picked (1 = pick one).
+ */
+export interface ProductModifierGroup {
+    id: string;
+    name: string;
+    min: number;
+    max: number;
+    options: ProductModifierOption[];
+}
+/** A modifier as the order line keeps it: names and price as sold. */
+export interface OrderLineModifier {
+    groupId: string;
+    optionId: string;
+    group: string;
+    name: string;
+    priceCents: number;
+}
+/** What the register sends for a line: the option ids it picked, nothing priced. */
+export interface ModifierSelection {
+    groupId: string;
+    optionId: string;
+}
+export declare const POS_MAX_MODIFIER_GROUPS = 10;
+export declare const POS_MAX_MODIFIER_OPTIONS = 20;
+/** $1,000 on one modifier: anything larger is a product, not an add-on. */
+export declare const POS_MAX_MODIFIER_PRICE_CENTS = 100000;
+/** Why a product's modifier groups cannot be saved, or null when they can. */
+export declare function modifierGroupsProblem(groups: unknown): string | null;
+/** The product's groups, or none when they are missing or malformed. */
+export declare function productModifierGroups(product: {
+    modifierGroups?: unknown;
+}): ProductModifierGroup[];
+/** Whether a group must be answered before the item can be added. */
+export declare function modifierGroupRequired(group: ProductModifierGroup): boolean;
+/**
+ * Prices a line's chosen modifiers from the PRODUCT, in group order, and
+ * checks every group's minimum and maximum. Unknown ids, a repeated choice
+ * and a group answered past its maximum are refused with what to fix.
+ */
+export interface ResolvedLineModifiers {
+    ok: boolean;
+    /** The chosen modifiers, in group order; empty when not `ok`. */
+    modifiers: OrderLineModifier[];
+    /** What they add to one unit, in cents. */
+    extraCents: number;
+    /** What to fix, when not `ok`. */
+    error?: string;
+}
+export declare function resolveLineModifiers(product: {
+    name?: string;
+    modifierGroups?: unknown;
+}, raw: unknown): ResolvedLineModifiers;
+/** The label a line prints: the variant, then each modifier (`Large / Oat milk, Extra shot`). */
+export declare function lineLabelWithModifiers(variantLabel: string | undefined, modifiers: readonly Pick<OrderLineModifier, 'name'>[]): string;
+/** Two lines merge only when they are the same item with the same choices. */
+export declare function modifierSelectionKey(selection: readonly ModifierSelection[] | undefined): string;

package/src/lib/model/product-modifiers.js

@@ -0,0 +1,140 @@
+/**
+ * @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.
+ */ /*==========================================
+ * REGISTER MODIFIERS AND QUICK KEYS (AGL-3607).
+ *
+ * A modifier is a choice added to an item as it is rung up — "Oat milk",
+ * "Extra shot +$0.75", "No onions" — that is not a stocked variant. Groups
+ * live on the product (`modifierGroups`); the register sends the chosen
+ * option ids with each line and the SERVER prices them from the product
+ * document, so a register never names what a modifier costs.
+ *
+ * A chosen modifier is folded into the line's `variantLabel` as well as kept
+ * structured in `modifiers`: every receipt, email, order view and export
+ * already prints the label, so the choice reaches all of them without each
+ * learning a new field.
+ *=========================================*/ /** One choice in a modifier group. `priceCents` is added to the item, 0 for free. */ export const POS_MAX_MODIFIER_GROUPS = 10;
+export const POS_MAX_MODIFIER_OPTIONS = 20;
+/** $1,000 on one modifier: anything larger is a product, not an add-on. */ export const POS_MAX_MODIFIER_PRICE_CENTS = 100000;
+/** Why a product's modifier groups cannot be saved, or null when they can. */ export function modifierGroupsProblem(groups) {
+    if (groups == null) return null;
+    if (!Array.isArray(groups)) return 'Modifiers must be a list';
+    if (groups.length > POS_MAX_MODIFIER_GROUPS) {
+        return `At most ${POS_MAX_MODIFIER_GROUPS} modifier groups per product`;
+    }
+    const groupIds = new Set();
+    for (const group of groups){
+        var _group_name;
+        if (!(group == null ? void 0 : group.id) || groupIds.has(group.id)) return 'Modifier groups need unique ids';
+        groupIds.add(group.id);
+        if (!String((_group_name = group.name) != null ? _group_name : '').trim()) return 'Name every modifier group';
+        const options = Array.isArray(group.options) ? group.options : [];
+        if (options.length === 0) return `Add a choice to “${group.name}”`;
+        if (options.length > POS_MAX_MODIFIER_OPTIONS) {
+            return `“${group.name}” has more than ${POS_MAX_MODIFIER_OPTIONS} choices`;
+        }
+        const optionIds = new Set();
+        for (const option of options){
+            var _option_name;
+            if (!(option == null ? void 0 : option.id) || optionIds.has(option.id)) return 'Modifier choices need unique ids';
+            optionIds.add(option.id);
+            if (!String((_option_name = option.name) != null ? _option_name : '').trim()) return `Name every choice in “${group.name}”`;
+            const price = option.priceCents;
+            if (!Number.isInteger(price) || price < 0 || price > POS_MAX_MODIFIER_PRICE_CENTS) {
+                return `“${option.name}” needs a price of $0 to $1,000`;
+            }
+        }
+        const { min, max } = group;
+        if (!Number.isInteger(min) || min < 0) return `“${group.name}” needs a minimum of 0 or more`;
+        if (!Number.isInteger(max) || max < 1 || max > options.length) {
+            return `“${group.name}” allows 1 to ${options.length} choices`;
+        }
+        if (min > max) return `“${group.name}” requires more choices than it allows`;
+    }
+    return null;
+}
+/** The product's groups, or none when they are missing or malformed. */ export function productModifierGroups(product) {
+    const groups = product == null ? void 0 : product.modifierGroups;
+    if (!Array.isArray(groups) || modifierGroupsProblem(groups)) return [];
+    return groups;
+}
+/** Whether a group must be answered before the item can be added. */ export function modifierGroupRequired(group) {
+    return group.min > 0;
+}
+export function resolveLineModifiers(product, raw) {
+    const refuse = (error)=>({
+            ok: false,
+            modifiers: [],
+            extraCents: 0,
+            error
+        });
+    const groups = productModifierGroups(product);
+    const picks = (Array.isArray(raw) ? raw : []).slice(0, POS_MAX_MODIFIER_GROUPS * POS_MAX_MODIFIER_OPTIONS).map((entry)=>{
+        var _ref, _ref1;
+        return {
+            groupId: String((_ref = entry == null ? void 0 : entry.groupId) != null ? _ref : ''),
+            optionId: String((_ref1 = entry == null ? void 0 : entry.optionId) != null ? _ref1 : '')
+        };
+    });
+    const seen = new Set();
+    for (const pick of picks){
+        const key = `${pick.groupId}:${pick.optionId}`;
+        if (seen.has(key)) return refuse(`A choice on ${product.name} was picked twice.`);
+        seen.add(key);
+        const group = groups.find((entry)=>entry.id === pick.groupId);
+        if (!group || !group.options.some((option)=>option.id === pick.optionId)) {
+            return refuse(`A choice on ${product.name} is no longer offered. Remove it and add it again.`);
+        }
+    }
+    const modifiers = [];
+    for (const group of groups){
+        const chosen = group.options.filter((option)=>picks.some((pick)=>pick.groupId === group.id && pick.optionId === option.id));
+        if (chosen.length < group.min) {
+            return refuse(`Choose ${group.name.toLowerCase()} for ${product.name}.`);
+        }
+        if (chosen.length > group.max) {
+            return refuse(`Choose at most ${group.max} for ${group.name.toLowerCase()} on ${product.name}.`);
+        }
+        for (const option of chosen){
+            modifiers.push({
+                groupId: group.id,
+                optionId: option.id,
+                group: group.name,
+                name: option.name,
+                priceCents: option.priceCents
+            });
+        }
+    }
+    return {
+        ok: true,
+        modifiers,
+        extraCents: modifiers.reduce((sum, modifier)=>sum + modifier.priceCents, 0)
+    };
+}
+/** The label a line prints: the variant, then each modifier (`Large / Oat milk, Extra shot`). */ export function lineLabelWithModifiers(variantLabel, modifiers) {
+    const added = modifiers.map((modifier)=>modifier.name).join(', ');
+    return [
+        variantLabel,
+        added
+    ].filter(Boolean).join(' / ');
+}
+/** Two lines merge only when they are the same item with the same choices. */ export function modifierSelectionKey(selection) {
+    return [
+        ...selection != null ? selection : []
+    ].map((pick)=>`${pick.groupId}:${pick.optionId}`).sort().join('|');
+}
+
+//# sourceMappingURL=product-modifiers.js.map

package/src/lib/model/product-modifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/product-modifiers.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 * REGISTER MODIFIERS AND QUICK KEYS (AGL-3607).\n *\n * A modifier is a choice added to an item as it is rung up — \"Oat milk\",\n * \"Extra shot +$0.75\", \"No onions\" — that is not a stocked variant. Groups\n * live on the product (`modifierGroups`); the register sends the chosen\n * option ids with each line and the SERVER prices them from the product\n * document, so a register never names what a modifier costs.\n *\n * A chosen modifier is folded into the line's `variantLabel` as well as kept\n * structured in `modifiers`: every receipt, email, order view and export\n * already prints the label, so the choice reaches all of them without each\n * learning a new field.\n *=========================================*/\n\n/** One choice in a modifier group. `priceCents` is added to the item, 0 for free. */\nexport interface ProductModifierOption {\n  id: string\n  name: string\n  priceCents: number\n}\n\n/**\n * A set of choices offered together (\"Milk\", \"Add-ons\"). `min` of 1 or more\n * makes it required; `max` caps how many can be picked (1 = pick one).\n */\nexport interface ProductModifierGroup {\n  id: string\n  name: string\n  min: number\n  max: number\n  options: ProductModifierOption[]\n}\n\n/** A modifier as the order line keeps it: names and price as sold. */\nexport interface OrderLineModifier {\n  groupId: string\n  optionId: string\n  group: string\n  name: string\n  priceCents: number\n}\n\n/** What the register sends for a line: the option ids it picked, nothing priced. */\nexport interface ModifierSelection {\n  groupId: string\n  optionId: string\n}\n\nexport const POS_MAX_MODIFIER_GROUPS = 10\nexport const POS_MAX_MODIFIER_OPTIONS = 20\n/** $1,000 on one modifier: anything larger is a product, not an add-on. */\nexport const POS_MAX_MODIFIER_PRICE_CENTS = 100_000\n\n/** Why a product's modifier groups cannot be saved, or null when they can. */\nexport function modifierGroupsProblem(groups: unknown): string | null {\n  if (groups == null) return null\n  if (!Array.isArray(groups)) return 'Modifiers must be a list'\n  if (groups.length > POS_MAX_MODIFIER_GROUPS) {\n    return `At most ${POS_MAX_MODIFIER_GROUPS} modifier groups per product`\n  }\n  const groupIds = new Set<string>()\n  for (const group of groups as ProductModifierGroup[]) {\n    if (!group?.id || groupIds.has(group.id)) return 'Modifier groups need unique ids'\n    groupIds.add(group.id)\n    if (!String(group.name ?? '').trim()) return 'Name every modifier group'\n    const options = Array.isArray(group.options) ? group.options : []\n    if (options.length === 0) return `Add a choice to “${group.name}”`\n    if (options.length > POS_MAX_MODIFIER_OPTIONS) {\n      return `“${group.name}” has more than ${POS_MAX_MODIFIER_OPTIONS} choices`\n    }\n    const optionIds = new Set<string>()\n    for (const option of options) {\n      if (!option?.id || optionIds.has(option.id)) return 'Modifier choices need unique ids'\n      optionIds.add(option.id)\n      if (!String(option.name ?? '').trim()) return `Name every choice in “${group.name}”`\n      const price = option.priceCents\n      if (!Number.isInteger(price) || price < 0 || price > POS_MAX_MODIFIER_PRICE_CENTS) {\n        return `“${option.name}” needs a price of $0 to $1,000`\n      }\n    }\n    const { min, max } = group\n    if (!Number.isInteger(min) || min < 0) return `“${group.name}” needs a minimum of 0 or more`\n    if (!Number.isInteger(max) || max < 1 || max > options.length) {\n      return `“${group.name}” allows 1 to ${options.length} choices`\n    }\n    if (min > max) return `“${group.name}” requires more choices than it allows`\n  }\n  return null\n}\n\n/** The product's groups, or none when they are missing or malformed. */\nexport function productModifierGroups(product: {\n  modifierGroups?: unknown\n}): ProductModifierGroup[] {\n  const groups = product?.modifierGroups\n  if (!Array.isArray(groups) || modifierGroupsProblem(groups)) return []\n  return groups as ProductModifierGroup[]\n}\n\n/** Whether a group must be answered before the item can be added. */\nexport function modifierGroupRequired(group: ProductModifierGroup): boolean {\n  return group.min > 0\n}\n\n/**\n * Prices a line's chosen modifiers from the PRODUCT, in group order, and\n * checks every group's minimum and maximum. Unknown ids, a repeated choice\n * and a group answered past its maximum are refused with what to fix.\n */\nexport interface ResolvedLineModifiers {\n  ok: boolean\n  /** The chosen modifiers, in group order; empty when not `ok`. */\n  modifiers: OrderLineModifier[]\n  /** What they add to one unit, in cents. */\n  extraCents: number\n  /** What to fix, when not `ok`. */\n  error?: string\n}\n\nexport function resolveLineModifiers(\n  product: { name?: string; modifierGroups?: unknown },\n  raw: unknown,\n): ResolvedLineModifiers {\n  const refuse = (error: string): ResolvedLineModifiers => ({\n    ok: false,\n    modifiers: [],\n    extraCents: 0,\n    error,\n  })\n  const groups = productModifierGroups(product)\n  const picks: ModifierSelection[] = (Array.isArray(raw) ? raw : [])\n    .slice(0, POS_MAX_MODIFIER_GROUPS * POS_MAX_MODIFIER_OPTIONS)\n    .map((entry: any) => ({\n      groupId: String(entry?.groupId ?? ''),\n      optionId: String(entry?.optionId ?? ''),\n    }))\n  const seen = new Set<string>()\n  for (const pick of picks) {\n    const key = `${pick.groupId}:${pick.optionId}`\n    if (seen.has(key)) return refuse(`A choice on ${product.name} was picked twice.`)\n    seen.add(key)\n    const group = groups.find((entry) => entry.id === pick.groupId)\n    if (!group || !group.options.some((option) => option.id === pick.optionId)) {\n      return refuse(`A choice on ${product.name} is no longer offered. Remove it and add it again.`)\n    }\n  }\n  const modifiers: OrderLineModifier[] = []\n  for (const group of groups) {\n    const chosen = group.options.filter((option) =>\n      picks.some((pick) => pick.groupId === group.id && pick.optionId === option.id),\n    )\n    if (chosen.length < group.min) {\n      return refuse(`Choose ${group.name.toLowerCase()} for ${product.name}.`)\n    }\n    if (chosen.length > group.max) {\n      return refuse(`Choose at most ${group.max} for ${group.name.toLowerCase()} on ${product.name}.`)\n    }\n    for (const option of chosen) {\n      modifiers.push({\n        groupId: group.id,\n        optionId: option.id,\n        group: group.name,\n        name: option.name,\n        priceCents: option.priceCents,\n      })\n    }\n  }\n  return {\n    ok: true,\n    modifiers,\n    extraCents: modifiers.reduce((sum, modifier) => sum + modifier.priceCents, 0),\n  }\n}\n\n/** The label a line prints: the variant, then each modifier (`Large / Oat milk, Extra shot`). */\nexport function lineLabelWithModifiers(\n  variantLabel: string | undefined,\n  modifiers: readonly Pick<OrderLineModifier, 'name'>[],\n): string {\n  const added = modifiers.map((modifier) => modifier.name).join(', ')\n  return [variantLabel, added].filter(Boolean).join(' / ')\n}\n\n/** Two lines merge only when they are the same item with the same choices. */\nexport function modifierSelectionKey(selection: readonly ModifierSelection[] | undefined): string {\n  return [...(selection ?? [])]\n    .map((pick) => `${pick.groupId}:${pick.optionId}`)\n    .sort()\n    .join('|')\n}\n"],"names":["POS_MAX_MODIFIER_GROUPS","POS_MAX_MODIFIER_OPTIONS","POS_MAX_MODIFIER_PRICE_CENTS","modifierGroupsProblem","groups","Array","isArray","length","groupIds","Set","group","id","has","add","String","name","trim","options","optionIds","option","price","priceCents","Number","isInteger","min","max","productModifierGroups","product","modifierGroups","modifierGroupRequired","resolveLineModifiers","raw","refuse","error","ok","modifiers","extraCents","picks","slice","map","entry","groupId","optionId","seen","pick","key","find","some","chosen","filter","toLowerCase","push","reduce","sum","modifier","lineLabelWithModifiers","variantLabel","added","join","Boolean","modifierSelectionKey","selection","sort"],"mappings":"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"}

package/src/lib/model/shippingeasy.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @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 { HostOrder } from './commerce-orders';
+import { type ShipNotice, type ShipStationOrderSource, type ShipStationProducts } from './shipstation';
+/** Where ShippingEasy's API answers. A deployment may point elsewhere with `SHIPPINGEASY_API_BASE_URL`. */
+export declare const SHIPPINGEASY_DEFAULT_BASE_URL = "https://app.shippingeasy.com";
+/** How far a signed callback's `api_timestamp` may be from now: the Ruby client's own hour. */
+export declare const SHIPPINGEASY_TIMESTAMP_TOLERANCE_MS: number;
+/** The status an order arrives in ShippingEasy with. */
+export declare const SHIPPINGEASY_AWAITING_SHIPMENT = "awaiting_shipment";
+/**
+ * A value form-encoded as Ruby's `URI.encode_www_form_component` writes it,
+ * which is what ShippingEasy's signature was computed over: letters, digits
+ * and `*-._` as they are, a space as `+`, every other byte as `%XX` upper-case.
+ */
+export declare function shippingEasyFormComponent(value: string): string;
+/** The parameters sorted by name and joined `a=1&b=2`, as the signature reads them. `api_signature` is never part of it. */
+export declare function shippingEasyCanonicalQuery(params: Readonly<Record<string, string>>): string;
+/** The plaintext a request's signature is the HMAC of: `METHOD&path&query&body`, the body left off when empty. */
+export declare function shippingEasySignaturePlaintext(input: {
+    method: string;
+    path: string;
+    params: Readonly<Record<string, string>>;
+    body?: string | null;
+}): string;
+/** What a changed order asks of ShippingEasy. */
+export type ShippingEasyIntent = 'create' | 'cancel' | null;
+/**
+ * Whether an order goes to ShippingEasy, comes back out of it, or neither.
+ *
+ * - A paid or partly shipped order with something to ship and a full
+ *   ship-to address is CREATED. A test-mode order never is: ShippingEasy is
+ *   the merchant's real label account, and a label bought for a test order
+ *   is real postage.
+ * - A canceled or fully refunded order is CANCELED there, which the caller
+ *   does only when it once sent the order.
+ * - Anything else (pending, shipped, delivered) asks nothing.
+ */
+export declare function shippingEasyIntent(order: Partial<HostOrder> & {
+    livemode?: unknown;
+    requiresShipping?: unknown;
+}, docId: string): ShippingEasyIntent;
+/** A full name as ShippingEasy's first and last name: the last word is the last name. */
+export declare function splitPersonName(name: unknown): {
+    first_name?: string;
+    last_name?: string;
+};
+/** The order identifier ShippingEasy keeps: the order number the merchant sees, else the document id. */
+export declare function shippingEasyExternalId(order: Pick<HostOrder, 'number'>, docId: string): string;
+/**
+ * The `{ order }` body that creates an order in ShippingEasy. The items are
+ * what is LEFT to ship, so a partly shipped order sent after its first parcel
+ * asks for the rest; each carries its line's index as `ext_line_item_id`,
+ * which the shipment callback hands back to name the line.
+ */
+export declare function shippingEasyOrderPayload(source: ShipStationOrderSource, products?: ShipStationProducts): {
+    order: Record<string, unknown>;
+};
+/**
+ * The label states that mean a parcel is on its way. `label_pending` is not
+ * bought yet and `cancelled` was voided, so neither ships anything.
+ */
+export declare const SHIPPINGEASY_SHIPPED_STATES: ReadonlySet<string>;
+/** What one callback says. */
+export interface ShippingEasyCallback {
+    /** ShippingEasy's own shipment id, for the log. */
+    shipmentId: string | null;
+    workflowState: string;
+    /** One notice per order the shipment carries, in the shape every connector records. */
+    notices: ShipNotice[];
+}
+/**
+ * A shipment callback's JSON read into notices, or the reason it cannot be.
+ * Each order of the shipment is one notice under the shipment's tracking
+ * number; its items are the recipients' line items, named back by the
+ * `ext_line_item_id` the order was sent with, else by SKU.
+ */
+export declare function readShippingEasyCallback(body: string): ShippingEasyCallback | {
+    problem: string;
+};