@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/commerce.js

@@ -0,0 +1,739 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { nameSearchFields } from "@aglyn/aglyn/app-utils/name-search";
+/**
+ * Commerce catalog v1 (AGL-276): products with options/variants,
+ * hierarchical categories, tags, and manual/smart collections. Pure
+ * model + helpers — no I/O; the products hub and storefront APIs operate
+ * over these shapes. Documents live under `hosts/{hostId}/products`,
+ * `.../productCategories`, and `.../collections`; the legacy Commerce
+ * Starter product doc (AGL-90: name/priceUsd/inventory) lifts into this
+ * shape via `liftLegacyProduct`, so existing docs keep working.
+ */ /*
+ * THERE IS NO STOREFRONT FEE CONSTANT, and that absence is load-bearing
+ * (AGL-2295).
+ *
+ * `COMMERCE_PLATFORM_FEE_PERCENT = 2` lived here with ZERO call sites. It
+ * asserted a flat 2% that agrees with the plan table for exactly one cell
+ * (Starter, physical) and disagrees with the other fifteen — Starter digital
+ * is 5%, Pro digital 3%, Business 2%, Scale 1%, and every physical rate above
+ * Starter is 0%. Nothing was wrong while nothing read it; the cost was that
+ * the next reader wiring it up would silently re-price every plan, and a
+ * constant sitting in the model beside the types reads like the answer.
+ *
+ * The single source is `resolveTransactionFeePct(org, productType)` in
+ * `plan-entitlements.ts`, resolved PER REQUEST from the org — because it
+ * depends on the plan, on per-org staff overrides, and on whether the
+ * subscription is still alive. A constant cannot express any of that.
+ * `commerce-fee-single-source.spec.ts` fails the build if one comes back.
+ */ /** Product price ceiling (whole USD). */ export const COMMERCE_MAX_PRICE_USD = 10000;
+/**
+ * The register ids within the plan's `posRegisters` cap (AGL-482), ranked
+ * by creation order — the same ordering `pos-order.ts` enforces at sale
+ * time. Registers beyond the cap (e.g. after a Business→Pro downgrade) are
+ * excluded so the console/POS can dim or hide them instead of surfacing a
+ * checkout 403. `cap` of `Infinity` returns all.
+ */ export function registersWithinCap(registers, cap) {
+    const createdMs = (r)=>{
+        var _ref, _ref1;
+        var _r_createdAt_toMillis, _r_createdAt, _r_createdAt1;
+        return (_ref = (_ref1 = (_r_createdAt = r.createdAt) == null ? void 0 : (_r_createdAt_toMillis = _r_createdAt.toMillis) == null ? void 0 : _r_createdAt_toMillis.call(_r_createdAt)) != null ? _ref1 : (_r_createdAt1 = r.createdAt) == null ? void 0 : _r_createdAt1.seconds) != null ? _ref : 0;
+    };
+    const ranked = [
+        ...registers
+    ].sort((a, b)=>createdMs(a) - createdMs(b) || a.$id.localeCompare(b.$id));
+    return new Set(ranked.slice(0, Math.max(0, cap)).map((r)=>r.$id));
+}
+/** Variant ceiling per product (Shopify parity). */ export const COMMERCE_MAX_VARIANTS = 100;
+export const COMMERCE_MAX_OPTIONS = 3;
+export const COMMERCE_MAX_OPTION_VALUES = 25;
+export const COMMERCE_SLUG_MAX_LENGTH = 80;
+/** Lowercase-kebab slug from a product/category/collection name. */ export function commerceSlug(name) {
+    return String(name != null ? name : '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, COMMERCE_SLUG_MAX_LENGTH);
+}
+/**
+ * The search keys a product write carries, so the catalog can be searched by
+ * the QUERY rather than by the rows a listener happened to fetch (AGL-2501).
+ *
+ * The hub lists `limit(500)`, and the search compared what that returned — so
+ * a product past the window answered "no products match", which reads as the
+ * product not existing rather than as the search not reaching it. Filtering
+ * server-side needs fields Firestore can index, and neither of the two things
+ * a merchant searches by is one:
+ *
+ *   - A NAME needs case-insensitive contains, which Firestore has no operator
+ *     for. `nameSearchFields` denormalizes it into the three shapes that are
+ *     indexable — an exact key, word-prefix tokens for `array-contains`, and
+ *     the key reversed so "ends with" becomes a prefix range.
+ *   - A SKU lives inside `variants`, an array of OBJECTS, and Firestore cannot
+ *     query a field inside one. Flattened here into a top-level array so a SKU
+ *     is one `array-contains`.
+ *
+ * ⛔ A SKU therefore matches WHOLE, not as a substring: "abc-123" finds it and
+ * "123" does not. That is the right way round for a SKU, which is a value
+ * somebody copies rather than half-remembers — unlike a name, where the tokens
+ * above buy word-prefix matching precisely because names are half-remembered.
+ *
+ * `barcodes` is the same flattening for the same reason, and it is the one the
+ * register depends on: a keyboard-wedge scanner types the code and presses
+ * Enter, so the lookup has to be exact and has to reach the whole catalog. A
+ * scan is never a half-remembered value.
+ *
+ * Lower-cased because the translator lower-cases the typed query before it
+ * builds the `array-contains`; stored and typed have to be normalized the same
+ * way or the two silently disagree.
+ *
+ * ⚠️ Each array is OMITTED when a product has none, rather than written as
+ * `[]`. `isNotEmpty` is served as `!= null`, and an empty array is not null —
+ * so a product with no SKUs at all would answer "has a SKU" for every row.
+ *
+ * ⚠️ Spread this at EVERY write that sets a product's name or variants. A
+ * write that sets the name without it leaves the keys describing the previous
+ * name, and the product becomes findable only by what it used to be called.
+ */ export function productSearchFields(product) {
+    const flatten = (read)=>{
+        var _product_variants;
+        return [
+            ...new Set(((_product_variants = product.variants) != null ? _product_variants : []).map((variant)=>{
+                var _read;
+                return ((_read = read(variant)) != null ? _read : '').trim().toLowerCase();
+            }).filter(Boolean))
+        ];
+    };
+    const skus = flatten((variant)=>variant.sku);
+    const barcodes = flatten((variant)=>variant.barcode);
+    return _extends({}, nameSearchFields(product.name), skus.length ? {
+        skus
+    } : {}, barcodes.length ? {
+        barcodes
+    } : {});
+}
+/**
+ * Cartesian product of option values → the variant option combinations
+ * the products hub materializes into a variants matrix. Empty/absent
+ * options yield a single default combination ({}).
+ */ export function expandVariantMatrix(options) {
+    const usable = (options != null ? options : []).filter((option)=>{
+        var _ref;
+        var _option_values;
+        return option.name && ((_ref = (_option_values = option.values) == null ? void 0 : _option_values.length) != null ? _ref : 0) > 0;
+    });
+    if (usable.length === 0) return [
+        {}
+    ];
+    let combos = [
+        {}
+    ];
+    for (const option of usable){
+        const next = [];
+        for (const combo of combos){
+            for (const value of option.values){
+                next.push(_extends({}, combo, {
+                    [option.name]: value
+                }));
+            }
+        }
+        combos = next;
+        if (combos.length > COMMERCE_MAX_VARIANTS) {
+            return combos.slice(0, COMMERCE_MAX_VARIANTS);
+        }
+    }
+    return combos;
+}
+/**
+ * The option axes renamed, with every variant's selection carried to the new
+ * name in place (AGL-3066).
+ *
+ * A variant keeps its selections keyed by option NAME, so a rename has to move
+ * each key rather than rebuild the matrix: a rebuild matches variants by name
+ * and value, finds none under the new name, and replaces every variant with a
+ * new id holding the first variant's price and stock and no SKU, barcode,
+ * compare-at price or weight. Moving the key keeps the id every order line
+ * and stock movement refers to, and every field a person set.
+ *
+ * `names` holds one entry per option, in order; an entry that is not a string
+ * keeps that option's name. Each selection keeps its position among a
+ * variant's selections, because a variant is labeled by them in order.
+ *
+ * Two options may share a name for a moment while a person types. A variant
+ * cannot hold two selections under one name, so while the new names are not
+ * all different nothing is moved, and `validateProduct` refuses the product.
+ * The selection left under the old name is found again by its value once the
+ * names differ, so typing through a duplicate loses nothing.
+ */ export function renameProductOptions(product, names) {
+    var _product_options, _product_variants;
+    const current = (_product_options = product.options) != null ? _product_options : [];
+    const options = current.map((option, index)=>{
+        const name = names[index];
+        return typeof name === 'string' ? _extends({}, option, {
+            name
+        }) : option;
+    });
+    const next = options.map((option)=>option.name);
+    if (new Set(next).size !== next.length) return {
+        options,
+        variants: product.variants
+    };
+    const variants = ((_product_variants = product.variants) != null ? _product_variants : []).map((variant)=>{
+        const selections = variant.options;
+        if (!selections) return variant;
+        const axisOf = optionAxesOf(current, selections);
+        const moved = {};
+        let changed = false;
+        for (const [key, value] of Object.entries(selections)){
+            const axis = axisOf.get(key);
+            const name = axis === undefined ? key : next[axis];
+            if (name !== key) changed = true;
+            moved[name] = value;
+        }
+        return changed ? _extends({}, variant, {
+            options: moved
+        }) : variant;
+    });
+    return {
+        options,
+        variants
+    };
+}
+/**
+ * Which option each of a variant's selections belongs to: the option of the
+ * same name first, and then, for a selection under a name no option has any
+ * longer, the one remaining option whose values hold its value. A selection
+ * that fits neither belongs to no option and is left as it is.
+ */ function optionAxesOf(options, selections) {
+    const axisOf = new Map();
+    const taken = new Set();
+    options.forEach((option, index)=>{
+        if (Object.prototype.hasOwnProperty.call(selections, option.name) && !axisOf.has(option.name)) {
+            axisOf.set(option.name, index);
+            taken.add(index);
+        }
+    });
+    for (const [key, value] of Object.entries(selections)){
+        if (axisOf.has(key)) continue;
+        const axis = options.findIndex((option, index)=>{
+            var _option_values;
+            return !taken.has(index) && ((_option_values = option.values) != null ? _option_values : []).includes(value);
+        });
+        if (axis === -1) continue;
+        axisOf.set(key, axis);
+        taken.add(axis);
+    }
+    return axisOf;
+}
+/**
+ * Whether a variant has a price a sale can charge (AGL-2916).
+ *
+ * A product proposed by AI is created with every price left empty for the
+ * merchant to set, so a stored variant can lack one. `Number(undefined)` is
+ * no price, and neither is `null`, which `Number` reads as zero: a sale door
+ * that priced either would charge nothing, or fail at the processor.
+ */ export function variantHasPrice(variant) {
+    const price = variant == null ? void 0 : variant.priceUsd;
+    return typeof price === 'number' && Number.isFinite(price) && price >= 0;
+}
+/** Whether any variant of a product still needs its price set (AGL-2916). */ export function productPriceMissing(product) {
+    var _product_variants;
+    return ((_product_variants = product.variants) != null ? _product_variants : []).some((variant)=>!variantHasPrice(variant));
+}
+/**
+ * The fields proposed copy changes on a product (AGL-2916), in the shape the
+ * editor stores them: only the fields `values` names. Tags and categories are
+ * each kept once; the search listing keeps its share image; and option names
+ * rename the product's options through `renameProductOptions`, keeping every
+ * variant, only when they name each option once with a name of its own.
+ */ export function productCopyPatch(product, values) {
+    var _product_options;
+    var _values_optionNames;
+    const patch = {};
+    if (typeof values.description === 'string') patch.description = values.description;
+    if (Array.isArray(values.tags)) {
+        patch.tags = [
+            ...new Set(values.tags.map((tag)=>tag.trim()).filter(Boolean))
+        ];
+    }
+    if (Array.isArray(values.categoryIds)) {
+        patch.categoryIds = [
+            ...new Set(values.categoryIds.filter(Boolean))
+        ];
+    }
+    if (typeof values.seoTitle === 'string' || typeof values.seoDescription === 'string') {
+        patch.seo = _extends({}, product.seo, typeof values.seoTitle === 'string' ? {
+            title: values.seoTitle
+        } : {}, typeof values.seoDescription === 'string' ? {
+            description: values.seoDescription
+        } : {});
+    }
+    const options = (_product_options = product.options) != null ? _product_options : [];
+    const names = (_values_optionNames = values.optionNames) == null ? void 0 : _values_optionNames.map((name)=>name.trim());
+    if (names && options.length > 0 && names.length === options.length && names.every(Boolean) && new Set(names).size === names.length && names.some((name, index)=>name !== options[index].name)) {
+        Object.assign(patch, renameProductOptions(product, names));
+    }
+    return patch;
+}
+/**
+ * The document a proposed product is created as (AGL-2916): a `draft`, under
+ * a slug no product in `takenSlugs` has, with one variant for each
+ * combination of its options and NO price on any of them. Prices are the
+ * merchant's to set: the editor refuses to save the product until every
+ * variant has one, and no sale door sells a variant without one
+ * (`variantHasPrice`). The search keys travel with the name, as on every
+ * create path.
+ */ export function unpricedProductDraft(proposal, takenSlugs, nowMs) {
+    const name = proposal.name.trim().slice(0, 120);
+    const base = commerceSlug(name) || 'product';
+    let slug = base;
+    for(let suffix = 2; takenSlugs.has(slug); suffix += 1)slug = `${base}-${suffix}`;
+    const seen = new Set();
+    const options = proposal.options.map((option)=>({
+            name: option.name.trim(),
+            values: [
+                ...new Set(option.values.map((value)=>value.trim()).filter(Boolean))
+            ].slice(0, COMMERCE_MAX_OPTION_VALUES)
+        })).filter((option)=>{
+        if (!option.name || !option.values.length || seen.has(option.name)) return false;
+        seen.add(option.name);
+        return true;
+    }).slice(0, COMMERCE_MAX_OPTIONS);
+    const variants = options.length ? expandVariantMatrix(options).map((combo, index)=>({
+            id: `v${nowMs.toString(36)}${index}`,
+            options: combo
+        })) : [
+        {
+            id: 'default'
+        }
+    ];
+    const seoTitle = proposal.seoTitle.trim();
+    const seoDescription = proposal.seoDescription.trim();
+    return _extends({}, productSearchFields({
+        name
+    }), {
+        slug,
+        type: proposal.type,
+        status: 'draft',
+        description: proposal.description,
+        tags: [
+            ...new Set(proposal.tags.map((tag)=>tag.trim()).filter(Boolean))
+        ]
+    }, options.length ? {
+        options
+    } : {}, {
+        variants
+    }, seoTitle || seoDescription ? {
+        seo: _extends({}, seoTitle ? {
+            title: seoTitle
+        } : {}, seoDescription ? {
+            description: seoDescription
+        } : {})
+    } : {}, {
+        createdAtMs: nowMs,
+        updatedAtMs: nowMs
+    });
+}
+/** Variant whose option selections match exactly; undefined if none. */ export function findVariant(product, selections) {
+    var _product_variants;
+    return (_product_variants = product.variants) == null ? void 0 : _product_variants.find((variant)=>{
+        var _variant_options;
+        const options = (_variant_options = variant.options) != null ? _variant_options : {};
+        const keys = new Set([
+            ...Object.keys(options),
+            ...Object.keys(selections)
+        ]);
+        for (const key of keys){
+            if (options[key] !== selections[key]) return false;
+        }
+        return true;
+    });
+}
+/** [min, max] price across variants; [0, 0] when there are none. */ export function productPriceRange(product) {
+    var _product_variants;
+    const prices = ((_product_variants = product.variants) != null ? _product_variants : []).map((variant)=>Number(variant.priceUsd)).filter((price)=>Number.isFinite(price) && price >= 0);
+    if (prices.length === 0) return [
+        0,
+        0
+    ];
+    return [
+        Math.min(...prices),
+        Math.max(...prices)
+    ];
+}
+/** Sum of tracked inventory; null when every variant is untracked. */ export function productInventory(product) {
+    var _product_variants;
+    let total = null;
+    for (const variant of (_product_variants = product.variants) != null ? _product_variants : []){
+        if (variant.inventory == null) continue;
+        total = (total != null ? total : 0) + Number(variant.inventory);
+    }
+    return total;
+}
+/**
+ * Whether `quantity` of a variant is purchasable (AGL-281): untracked
+ * stock always is; tracked stock honors the product's oversell policy.
+ */ export function canPurchase(product, variantId, quantity = 1) {
+    var _product_variants, _product_variants1;
+    const variant = variantId ? (_product_variants = product.variants) == null ? void 0 : _product_variants.find((item)=>item.id === variantId) : (_product_variants1 = product.variants) == null ? void 0 : _product_variants1[0];
+    if (!variant) return false;
+    if (variant.inventory == null) return true;
+    if (product.oversellPolicy === 'backorder') return true;
+    return Number(variant.inventory) >= quantity;
+}
+export function stockShortfall(product, variantId, quantity = 1) {
+    var _product_variants, _product_variants1;
+    if (canPurchase(product, variantId, quantity)) return null;
+    const variant = variantId ? (_product_variants = product.variants) == null ? void 0 : _product_variants.find((item)=>item.id === variantId) : (_product_variants1 = product.variants) == null ? void 0 : _product_variants1[0];
+    // `canPurchase` answers false for a variant that does not exist at all. That
+    // is not a stock shortfall and must not be reported as "0 in stock" — the
+    // register's own line builder falls back to `variants[0]`, so the case is
+    // unreachable from the counter, and inventing a count for it would be the
+    // one failure mode this feature must not have.
+    if (!variant || variant.inventory == null) return null;
+    return {
+        available: Math.max(0, Math.round(Number(variant.inventory) || 0))
+    };
+}
+/**
+ * Whether stock tracking MEANS anything on a product (AGL-1744).
+ *
+ * `canPurchase` above gates every checkout on stock, subscription sessions
+ * included, but nothing ever decrements for a subscription — not on the
+ * initial charge (the `commerce-subscription` webhook branch deliberately
+ * writes no order and touches no inventory, AGL-1732) and not on renewal
+ * (`invoice.payment_succeeded` is unhandled repo-wide, AGL-1743). So on a
+ * subscription-only product that gate is permanently satisfied: one unit of
+ * stock sells an unlimited number of subscriptions, and the count never
+ * moves however many boxes ship. The merchant set a number, the system
+ * checks it on every sale, and the number is never true.
+ *
+ * AGL-1750 resolved the half AGL-1744 had to leave open: every paid invoice
+ * of a PHYSICAL subscription now mints an order and decrements its variant's
+ * stock (the `invoice.paid` branch of the commerce webhook), opening cycle
+ * included. So the honest split is now three-way:
+ *
+ *   - `subscriptionOptional` ("Both") products have a real one-time path —
+ *     the cart only ever builds `mode: 'payment'` sessions, and buy-now with
+ *     `billing: 'once'` records a plain order — and that path decrements
+ *     honestly. Withdrawing stock tracking there would delete a working
+ *     control and re-open the AGL-1711 oversell on the half that works.
+ *   - a PHYSICAL subscription box consumes a unit every cycle, and since
+ *     AGL-1750 the cycle's own order decrements it — the count moves as the
+ *     boxes ship, so the number the merchant sets is kept true again.
+ *   - a DIGITAL or SERVICE subscription-only product still has no
+ *     decrementing path anywhere, so the field stays withdrawn there: one
+ *     unit would still sell unlimited subscriptions.
+ *
+ * This says nothing about what `canPurchase` returns — that is the gate for
+ * every other purchase path and is deliberately untouched. This is a console
+ * predicate: it stops the editor inviting a merchant to set a number the
+ * system will never keep true.
+ */ export function stockTrackingApplies(product) {
+    return !product.subscription || product.subscriptionOptional === true || product.type === 'physical';
+}
+/**
+ * Resolves the Stripe Checkout mode for a product + the buyer's
+ * requested billing choice (AGL-545). The product doc is authoritative:
+ * - no `subscription` → always one-time (the request field is ignored)
+ * - `subscription` without `subscriptionOptional` → always subscription
+ *   (a forged `billing: 'once'` cannot buy a subscription product once)
+ * - `subscriptionOptional` → the buyer chooses; absent/invalid choices
+ *   default to one-time, matching the PDP default.
+ */ export function resolveCheckoutBillingMode(product, requested) {
+    if (!product.subscription) return 'payment';
+    if (!product.subscriptionOptional) return 'subscription';
+    return requested === 'subscribe' ? 'subscription' : 'payment';
+}
+/**
+ * Applies a stock delta to one variant, flooring at zero (race-window
+ * sales can't drive the display negative), and returns the new variants
+ * array — callers persist it plus the `productInventory` denormalization.
+ * With `locationId`, the delta lands in that location's bucket and the
+ * flat `inventory` re-sums across locations (AGL-286).
+ */ export function adjustVariantInventory(product, variantId, delta, locationId) {
+    var _product_variants;
+    return ((_product_variants = product.variants) != null ? _product_variants : []).map((variant)=>{
+        if (variant.id !== variantId || variant.inventory == null) return variant;
+        if (locationId && variant.inventoryByLocation) {
+            var _variant_inventoryByLocation_locationId;
+            const buckets = _extends({}, variant.inventoryByLocation, {
+                [locationId]: Math.max(0, Number((_variant_inventoryByLocation_locationId = variant.inventoryByLocation[locationId]) != null ? _variant_inventoryByLocation_locationId : 0) + delta)
+            });
+            return _extends({}, variant, {
+                inventoryByLocation: buckets,
+                inventory: Object.values(buckets).reduce((sum, count)=>sum + Number(count), 0)
+            });
+        }
+        return _extends({}, variant, {
+            inventory: Math.max(0, Number(variant.inventory) + delta)
+        });
+    });
+}
+/**
+ * What `adjustVariantInventory` will ACTUALLY move the count by (AGL-2149).
+ *
+ * The floor in that helper is not a rounding detail, it is a silent absorber. A
+ * backorder product (`oversellPolicy: 'backorder'`, which `canPurchase` admits
+ * at any stock level) sitting at 0 sells 3: `Math.max(0, 0 + -3)` is 0, so the
+ * count does not move — correctly, since inventory is a shelf count and shelves
+ * do not go negative — but the ledger row said `-3` and every reversal read it
+ * as three units to put back. Cancelling that order handed the merchant 3 units
+ * that never existed and a stock badge that offers them for sale.
+ *
+ * Removing the floor is not the alternative: every reader of `inventory` — the
+ * badges, `canPurchase`, `productInventory`, `isLowStock` — assumes it cannot
+ * go negative, and a negative count would be a far wider change than the bug.
+ * So the clamp stays and the amount it absorbed is recorded instead.
+ *
+ * Deliberately mirrors `adjustVariantInventory`'s own arithmetic, including
+ * which field the clamp applies to in the location-tracked case, so the two
+ * cannot disagree about what happened.
+ */ export function appliedVariantInventoryDelta(product, variantId, delta, locationId) {
+    var _product_variants;
+    const variant = ((_product_variants = product.variants) != null ? _product_variants : []).find((item)=>item.id === variantId);
+    if (!variant || variant.inventory == null) return 0;
+    if (locationId && variant.inventoryByLocation) {
+        var _variant_inventoryByLocation_locationId;
+        const before = Number((_variant_inventoryByLocation_locationId = variant.inventoryByLocation[locationId]) != null ? _variant_inventoryByLocation_locationId : 0);
+        return Math.max(0, before + delta) - before;
+    }
+    const before = Number(variant.inventory);
+    return Math.max(0, before + delta) - before;
+}
+/**
+ * Moves stock between two locations of a tracked variant (AGL-286).
+ * Quantity clamps to what the source location holds; the flat total is
+ * unchanged by construction.
+ */ export function transferVariantInventory(product, variantId, fromLocationId, toLocationId, quantity) {
+    var _product_variants;
+    return ((_product_variants = product.variants) != null ? _product_variants : []).map((variant)=>{
+        var _variant_inventoryByLocation, _buckets_fromLocationId, _buckets_toLocationId;
+        if (variant.id !== variantId || variant.inventory == null) return variant;
+        const buckets = _extends({}, (_variant_inventoryByLocation = variant.inventoryByLocation) != null ? _variant_inventoryByLocation : {});
+        const available = Math.max(0, Number((_buckets_fromLocationId = buckets[fromLocationId]) != null ? _buckets_fromLocationId : 0));
+        const moved = Math.min(available, Math.max(0, Math.round(quantity)));
+        if (moved === 0) return variant;
+        buckets[fromLocationId] = available - moved;
+        buckets[toLocationId] = Math.max(0, Number((_buckets_toLocationId = buckets[toLocationId]) != null ? _buckets_toLocationId : 0)) + moved;
+        return _extends({}, variant, {
+            inventoryByLocation: buckets
+        });
+    });
+}
+/** True when tracked stock is at/below the product's alert threshold. */ export function isLowStock(product) {
+    const threshold = product.lowStockThreshold;
+    if (threshold == null || !(threshold >= 0)) return false;
+    const total = productInventory(product);
+    return total != null && total <= threshold;
+}
+function ruleMatches(product, rule) {
+    const value = rule.value;
+    switch(rule.field){
+        case 'tag':
+            {
+                var _product_tags;
+                const tags = (_product_tags = product.tags) != null ? _product_tags : [];
+                const has = tags.includes(String(value));
+                return rule.op === 'neq' ? !has : has;
+            }
+        case 'categoryId':
+            {
+                var _product_categoryIds;
+                const ids = (_product_categoryIds = product.categoryIds) != null ? _product_categoryIds : [];
+                const has = ids.includes(String(value));
+                return rule.op === 'neq' ? !has : has;
+            }
+        case 'priceUsd':
+            {
+                const [min, max] = productPriceRange(product);
+                const numeric = Number(value);
+                if (!Number.isFinite(numeric)) return false;
+                if (rule.op === 'lt') return min < numeric;
+                if (rule.op === 'gt') return max > numeric;
+                if (rule.op === 'neq') return min !== numeric || max !== numeric;
+                return min <= numeric && numeric <= max;
+            }
+        case 'name':
+            {
+                var _product_name;
+                const name = ((_product_name = product.name) != null ? _product_name : '').toLowerCase();
+                const needle = String(value).toLowerCase();
+                if (rule.op === 'contains') return name.includes(needle);
+                if (rule.op === 'neq') return name !== needle;
+                return name === needle;
+            }
+        case 'type':
+            {
+                const matches = product.type === value;
+                return rule.op === 'neq' ? !matches : matches;
+            }
+        default:
+            return false;
+    }
+}
+/**
+ * Smart-collection membership: draft/archived/deleted products never
+ * match; manual collections answer from productIds.
+ */ export function matchesCollection(product, collection, productId) {
+    var _collection_rules;
+    if (product.deletedAt || product.status !== 'active') return false;
+    if (collection.mode === 'manual') {
+        var _collection_productIds;
+        return productId != null && ((_collection_productIds = collection.productIds) != null ? _collection_productIds : []).includes(productId);
+    }
+    const rules = (_collection_rules = collection.rules) != null ? _collection_rules : [];
+    if (rules.length === 0) return false;
+    const matcher = (rule)=>ruleMatches(product, rule);
+    return collection.matchAll === false ? rules.some(matcher) : rules.every(matcher);
+}
+/**
+ * Lifts a legacy Commerce Starter doc (AGL-90: flat name/priceUsd/
+ * inventory/imageUrl) into the catalog shape with a single default
+ * variant. Already-lifted docs pass through unchanged.
+ */ export function liftLegacyProduct(raw) {
+    var _raw_priceUsd, _raw_name, _raw_name1, _raw_type, _raw_status, _raw_inventory;
+    if (Array.isArray(raw.variants) && raw.variants.length > 0) {
+        return raw;
+    }
+    const priceUsd = Number((_raw_priceUsd = raw.priceUsd) != null ? _raw_priceUsd : 0);
+    return _extends({}, raw, {
+        name: (_raw_name = raw.name) != null ? _raw_name : 'Product',
+        slug: raw.slug || commerceSlug((_raw_name1 = raw.name) != null ? _raw_name1 : 'product'),
+        type: (_raw_type = raw.type) != null ? _raw_type : 'physical',
+        status: (_raw_status = raw.status) != null ? _raw_status : 'active',
+        variants: [
+            {
+                id: 'default',
+                priceUsd: Number.isFinite(priceUsd) ? priceUsd : 0,
+                inventory: (_raw_inventory = raw.inventory) != null ? _raw_inventory : null
+            }
+        ]
+    });
+}
+/** Actionable error, or null when the product is storable. */ export function validateProduct(product) {
+    var _product_options, _product_variants;
+    var _product_name;
+    if (!((_product_name = product.name) == null ? void 0 : _product_name.trim())) return 'Product name is required';
+    if (!product.slug || product.slug !== commerceSlug(product.slug)) {
+        return 'Slug must be lowercase letters, numbers, and dashes';
+    }
+    if (![
+        'physical',
+        'digital',
+        'service'
+    ].includes(product.type)) {
+        return 'Unknown product type';
+    }
+    if (![
+        'draft',
+        'active',
+        'archived'
+    ].includes(product.status)) {
+        return 'Unknown product status';
+    }
+    const options = (_product_options = product.options) != null ? _product_options : [];
+    if (options.length > COMMERCE_MAX_OPTIONS) {
+        return `At most ${COMMERCE_MAX_OPTIONS} options per product`;
+    }
+    for (const option of options){
+        var _ref;
+        var _option_name, _option_values;
+        if (!((_option_name = option.name) == null ? void 0 : _option_name.trim())) return 'Option names are required';
+        if (((_ref = (_option_values = option.values) == null ? void 0 : _option_values.length) != null ? _ref : 0) === 0) {
+            return `Option "${option.name}" needs at least one value`;
+        }
+        if (option.values.length > COMMERCE_MAX_OPTION_VALUES) {
+            return `Option "${option.name}" has too many values`;
+        }
+        if (new Set(option.values).size !== option.values.length) {
+            return `Option "${option.name}" has duplicate values`;
+        }
+    }
+    // A variant keys its selections by option name, so two options with one
+    // name cannot both be selected (AGL-3066).
+    if (new Set(options.map((option)=>option.name.trim())).size !== options.length) {
+        return 'Each option needs its own name';
+    }
+    const variants = (_product_variants = product.variants) != null ? _product_variants : [];
+    if (variants.length === 0) return 'Products need at least one variant';
+    if (variants.length > COMMERCE_MAX_VARIANTS) {
+        return `At most ${COMMERCE_MAX_VARIANTS} variants per product`;
+    }
+    const ids = new Set();
+    const skus = new Set();
+    for (const variant of variants){
+        if (!variant.id) return 'Variants need stable ids';
+        if (ids.has(variant.id)) return 'Variant ids must be unique';
+        ids.add(variant.id);
+        if (variant.priceUsd === undefined || variant.priceUsd === null) {
+            return 'Set a price for every variant';
+        }
+        const price = Number(variant.priceUsd);
+        if (!Number.isFinite(price) || price < 0) {
+            return 'Variant prices must be zero or more';
+        }
+        if (price > COMMERCE_MAX_PRICE_USD) {
+            return `Prices are capped at $${COMMERCE_MAX_PRICE_USD}`;
+        }
+        if (variant.sku) {
+            if (skus.has(variant.sku)) return 'Variant SKUs must be unique';
+            skus.add(variant.sku);
+        }
+        if (variant.compareAtPriceUsd != null && Number(variant.compareAtPriceUsd) <= price) {
+            return 'Compare-at price must exceed the price';
+        }
+    }
+    return null;
+}
+/** Actionable error, or null when the collection is storable. */ export function validateCollection(collection) {
+    var _collection_name;
+    if (!((_collection_name = collection.name) == null ? void 0 : _collection_name.trim())) return 'Collection name is required';
+    if (!collection.slug || collection.slug !== commerceSlug(collection.slug)) {
+        return 'Slug must be lowercase letters, numbers, and dashes';
+    }
+    if (collection.mode !== 'manual' && collection.mode !== 'smart') {
+        return 'Unknown collection mode';
+    }
+    if (collection.mode === 'smart') {
+        var _collection_rules;
+        const rules = (_collection_rules = collection.rules) != null ? _collection_rules : [];
+        if (rules.length === 0) return 'Smart collections need at least one rule';
+        for (const rule of rules){
+            if (![
+                'tag',
+                'categoryId',
+                'priceUsd',
+                'name',
+                'type'
+            ].includes(rule.field)) {
+                return 'Unknown rule field';
+            }
+            if (![
+                'eq',
+                'neq',
+                'lt',
+                'gt',
+                'contains'
+            ].includes(rule.op)) {
+                return 'Unknown rule operator';
+            }
+            if (rule.value === '' || rule.value == null) {
+                return 'Rule values are required';
+            }
+        }
+    }
+    return null;
+}
+
+//# sourceMappingURL=commerce.js.map