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

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

@@ -14,9 +14,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Orders model v1 (AGL-283): line items snapshot the product/variant at
+ * purchase time (renames and price changes never rewrite history), a
+ * small status machine gates transitions, and totals are integer cents.
+ * Docs live at `hosts/{hostId}/orders/{id}`; the Stripe webhook creates
+ * them and the orders console (AGL-287) drives transitions. Pure — no
+ * I/O here.
+ */
+import type { OrderLineModifier } from './product-modifiers';
 import type { PaymentRisk } from '@aglyn/aglyn/app-utils/payment-risk';
 import type { ProductType } from './commerce';
 import type { StorefrontTaxMode } from './commerce-tax-decision';
+import type { OrderPayment } from './commerce-pos';
 export type OrderStatus = 'pending' | 'paid' | 'partially_fulfilled' | 'fulfilled' | 'delivered' | 'cancelled' | 'refunded';
 /**
  * Where the sale came through. `subscription` is a recurring cycle of a
@@ -27,7 +37,48 @@ export type OrderStatus = 'pending' | 'paid' | 'partially_fulfilled' | 'fulfille
  * there is nothing to ship, and AGL-1732's "a subscription is not an order"
  * stands for them.
  */
-export type OrderChannel = 'online' | 'pos' | 'draft' | 'subscription';
+export type OrderChannel = 'online' | 'pos' | 'draft' | 'subscription' | 'marketplace';
+/**
+ * Where an order sold on an outside channel came from (AGL-3638): a
+ * marketplace that took the buyer's money and pays the merchant out. Written
+ * once, by the import that recorded the order (`server/channel-orders.ts`).
+ */
+export interface OrderChannelSource {
+    /** The importer's id for the channel, e.g. `ebay`. */
+    channelId: string;
+    /** What the merchant calls it, e.g. `eBay`. */
+    channelLabel: string;
+    /** The channel's own order id, the import's idempotency key. */
+    externalOrderId: string;
+    /** What the merchant sees on the channel. */
+    externalRef: string;
+    /** Which order line each of the channel's lines became, for a shipment sent back to it. */
+    lines: Array<{
+        lineIndex: number;
+        externalLineId: string;
+    }>;
+    /** ISO 4217, upper case: the currency every amount on the order is in. */
+    currency: string;
+    /** The channel collected this order's tax and remits it, as the marketplace facilitator. */
+    taxRemittedByChannel: true;
+    /**
+     * What the channel charged the merchant for the sale, RECORDED for the
+     * merchant's books and never charged by Aglyn; `null` until the channel
+     * says.
+     */
+    fees: Array<{
+        label: string;
+        amountCents: number;
+    }> | null;
+    feesTotalCents: number | null;
+    /**
+     * How the goods leave (AGL-3644): `courier`, handed to the channel's own
+     * courier (a delivery app); absent reads as `ship`.
+     */
+    handoff?: 'ship' | 'courier';
+    /** The channel's ids of the refunds and adjustments recorded on the order, so each is recorded once (AGL-3644). */
+    refundIds?: string[];
+}
 /** Snapshot of what was bought — self-contained for history. */
 export interface OrderLineItem {
     productId: string;
@@ -38,8 +89,13 @@ export interface OrderLineItem {
     sku?: string;
     productType?: ProductType;
     quantity: number;
-    /** Per-unit price in cents at purchase time. */
+    /** Per-unit price in cents at purchase time, its modifiers included. */
     unitAmountCents: number;
+    /**
+     * Choices added at the register (AGL-3607), as sold. Already folded into
+     * `variantLabel` and `unitAmountCents`; kept for reports and reorders.
+     */
+    modifiers?: OrderLineModifier[];
     /** Supplier at purchase time (dropship routing, AGL-289). */
     supplierId?: string;
     /** Fulfillment id once this line ships (AGL-288). */
@@ -54,6 +110,35 @@ export interface OrderTotals {
     totalCents: number;
     /** Aglyn platform fee (Connect application fee, AGL-278/307). */
     feeCents: number;
+    /**
+     * Gratuity taken at the register (AGL-3607), on top of `totalCents` and
+     * never inside it: a tip is the merchant's, not a sale, so it stays out of
+     * revenue figures and out of the platform's take.
+     */
+    tipCents?: number;
+    /**
+     * Optional lines the buyer added at checkout from another plugin's offer
+     * (AGL-3635) — package protection — summed. Inside `totalCents`, never in
+     * `itemsCents`: an extra is not goods, so no fulfillment, stock or
+     * platform take reads it.
+     */
+    extrasCents?: number;
+}
+/**
+ * One optional line the buyer took at checkout (AGL-3635), as core's
+ * checkout-extras seam records it: whose offer it was, what it was called
+ * and what it cost. Never a line item: it does not ship and is never
+ * refunded by line.
+ */
+export interface OrderExtra {
+    /** `{pluginId}.{key}`. */
+    id: string;
+    pluginId: string;
+    key: string;
+    label: string;
+    amountCents: number;
+    /** The offering plugin's quote id. */
+    quoteRef?: string;
 }
 export interface OrderAddress {
     name?: string;
@@ -74,10 +159,36 @@ export interface OrderTimelineEvent {
 }
 export interface OrderFulfillment {
     id: string;
+    /** The lines this fulfillment touches; `lines` says how many units of each. */
     lineItemIds: number[];
+    /**
+     * Units per line (AGL-3611). Absent on a fulfillment written before
+     * quantities, which reads as every unit of each line in `lineItemIds`.
+     */
+    lines?: Array<{
+        lineItemId: number;
+        quantity: number;
+    }>;
     carrier?: string;
     trackingNumber?: string;
     trackingUrl?: string;
+    /** A shipping label bought for this parcel, when a shipping plugin bought one. */
+    labelUrl?: string;
+    /** The shipping plugin's id for that label (AGL-3612), so a retry finds this shipment. */
+    labelRef?: string;
+    /**
+     * Where the carrier says the parcel is (AGL-3612): `pre_transit`,
+     * `in_transit`, `out_for_delivery`, `delivered`, `exception` or `returned`,
+     * written by a tracking webhook through the shipment-records seam.
+     */
+    trackingStatus?: string;
+    trackingStatusAtMs?: number;
+    /** Absent reads as `active`; a cancelled fulfillment ships nothing. */
+    status?: 'active' | 'cancelled';
+    cancelledAtMs?: number;
+    updatedAtMs?: number;
+    /** Whether the buyer was to be told about this shipment. */
+    notify?: boolean;
     atMs: number;
 }
 /**
@@ -239,8 +350,12 @@ export interface OrderUnresolvedLine {
 export interface HostOrder {
     /** Human order number, sequential per host (e.g. #1042). */
     number?: number;
+    /** Optional lines the buyer added at checkout (AGL-3635); see {@link OrderExtra}. */
+    extras?: OrderExtra[];
     status: OrderStatus;
     channel?: OrderChannel;
+    /** The outside channel an order with channel `marketplace` was sold on (AGL-3638). */
+    channelSource?: OrderChannelSource;
     /**
      * Which location's stock this sale came off, for the multi-location counts
      * of AGL-286. Written by the POS register, the only sale path that decrements
@@ -251,6 +366,37 @@ export interface HostOrder {
      * erases the restock.
      */
     locationId?: string;
+    /**
+     * The register a POS sale was rung on, and the console user who rang it
+     * (AGL-472, AGL-3607).
+     */
+    registerId?: string;
+    cashierId?: string;
+    /**
+     * The register shift the sale was rung in (AGL-3609), which the shift's X
+     * and Z reports count it under.
+     */
+    shiftId?: string;
+    /**
+     * The person the cashier attached at the register (AGL-3609), as the
+     * person-records seam names them: which record system, and its id there.
+     */
+    customerRecord?: {
+        kind: string;
+        id: string;
+    };
+    /**
+     * Every payment toward a register sale (AGL-3607): one per tender, until
+     * the balance due is zero. Read through `orderPayments`, which infers one
+     * payment for an order written before the ledger existed.
+     */
+    payments?: OrderPayment[];
+    /** How the customer asked for their receipt at the register (AGL-3608). */
+    receiptRequest?: {
+        channel: 'email' | 'sms' | 'print' | 'none';
+        to?: string;
+        atMs: number;
+    };
     /**
      * The register discount that was applied, and the member who applied it
      * (AGL-2161). Present only on a POS order that carries a discount.
@@ -296,6 +442,23 @@ export interface HostOrder {
     taxMode?: StorefrontTaxMode;
     customerEmail?: string | null;
     customerName?: string | null;
+    /**
+     * The buyer's phone for order texts (AGL-3610), written only by a flow that
+     * asked for it for that purpose — never copied from a shipping address,
+     * which a buyer gives the carrier, not the store.
+     */
+    customerPhone?: string | null;
+    /**
+     * Which buyer messages this order has sent (AGL-3610), keyed by
+     * `buyerNotificationMarker` — the idempotency record `notifyOrderBuyer`
+     * claims in a transaction before it sends, so a retried webhook or a second
+     * click never mails the buyer twice.
+     */
+    buyerNotifications?: Record<string, {
+        state: 'sending' | 'sent';
+        channel: 'email' | 'sms';
+        atMs: number;
+    }>;
     /** Storefront customer id once accounts exist (AGL-294). */
     customerId?: string;
     shippingAddress?: OrderAddress;
@@ -511,6 +674,12 @@ export interface CheckoutSessionTotalsParts {
      * invisible to `total_details.amount_discount`, so it is added to it.
      */
     pricedInDiscountCents?: number;
+    /**
+     * The optional lines the buyer took (AGL-3635). Inside `amount_total` as
+     * ordinary Stripe lines, so the parts only sum to the charge with it
+     * named; recorded only when there is one.
+     */
+    extrasCents?: number;
 }
 export declare function computeCheckoutSessionTotals(lineItems: OrderLineItem[], session: CheckoutSessionTotalsSource | null | undefined, parts?: CheckoutSessionTotalsParts): OrderTotals;
 /** The buy-now Checkout Session as the webhook sees it — metadata included. */

package/src/lib/model/commerce-orders.js

@@ -1,4 +1,3 @@
-import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -21,7 +20,9 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * Docs live at `hosts/{hostId}/orders/{id}`; the Stripe webhook creates
  * them and the orders console (AGL-287) drives transitions. Pure — no
  * I/O here.
- */ import { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+import { lineRequiresShipping, orderLineFulfillmentStates } from "./order-fulfillment.js";
 /**
  * Legal status transitions. Refund/cancel policies: anything paid can
  * refund; only unfulfilled orders cancel (refund instead once shipped).
@@ -238,8 +239,11 @@ export function computeCheckoutSessionTotals(lineItems, session, parts) {
         discountCents: Number((_ref5 = details == null ? void 0 : details.amount_discount) != null ? _ref5 : 0) + Number((_ref6 = parts == null ? void 0 : parts.pricedInDiscountCents) != null ? _ref6 : 0)
     });
     const amountTotal = Number((_ref7 = session == null ? void 0 : session.amount_total) != null ? _ref7 : NaN);
-    return _extends({}, totals, {
-        totalCents: Number.isFinite(amountTotal) ? amountTotal : totals.totalCents
+    const extrasCents = wholeCents(parts == null ? void 0 : parts.extrasCents);
+    return _extends({}, totals, extrasCents > 0 ? {
+        extrasCents
+    } : {}, {
+        totalCents: Number.isFinite(amountTotal) ? amountTotal : totals.totalCents + extrasCents
     });
 }
 /** Non-negative integer cents from an untyped metadata value; 0 otherwise. */ function metadataCents(value) {
@@ -637,14 +641,12 @@ export function computeCheckoutSessionTotals(lineItems, session, parts) {
  * `fulfilled` cannot transition to `fulfilled`. The buyer was told their whole
  * order shipped with one carrier and one tracking number.
  */ export function coveredLineItemIds(order) {
-    var _order_fulfillments;
+    // Quantity-aware since AGL-3611: a line is covered once every unit of it is
+    // on an active fulfillment, so a line shipped 2 of 5 is still open and a
+    // cancelled fulfillment covers nothing.
     const covered = new Set();
-    for (const fulfillment of (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []){
-        var _ref;
-        for (const index of (_ref = fulfillment == null ? void 0 : fulfillment.lineItemIds) != null ? _ref : []){
-            const line = Math.round(Number(index));
-            if (Number.isFinite(line) && line >= 0) covered.add(line);
-        }
+    for (const state of orderLineFulfillmentStates(order)){
+        if (state.quantity > 0 && state.remainingQuantity === 0) covered.add(state.lineItemId);
     }
     return covered;
 }
@@ -680,7 +682,9 @@ export function computeCheckoutSessionTotals(lineItems, session, parts) {
     var _order_lineItems;
     const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
     if (lines.length === 0) return 'fulfilled';
-    return lines.every((_line, index)=>covered.has(index)) ? 'fulfilled' : 'partially_fulfilled';
+    // A digital or service line has nothing to ship (AGL-3611), so it never
+    // holds the order open.
+    return lines.every((line, index)=>covered.has(index) || !lineRequiresShipping(line)) ? 'fulfilled' : 'partially_fulfilled';
 }
 /**
  * Statuses under which an order grants NO entitlement at all (AGL-2454).
@@ -848,7 +852,8 @@ export function computeCheckoutSessionTotals(lineItems, session, parts) {
     online: 'Online',
     pos: 'POS',
     draft: 'Draft',
-    subscription: 'Subscription'
+    subscription: 'Subscription',
+    marketplace: 'Marketplace'
 };
 /** Human label for a channel, tolerating a legacy/unknown value. */ export function orderChannelLabel(channel) {
     var _ref, _ORDER_CHANNEL_LABELS_;
@@ -860,10 +865,15 @@ export function computeCheckoutSessionTotals(lineItems, session, parts) {
  * this expression; a refunded order counted as revenue on whichever one
  * was written first.
  */ export function orderNetCents(order) {
-    var _ref, _ref1, _order_refundedCents;
-    var _order_totals;
+    var _ref, _ref1, _order_refundedCents, _ref2;
+    var _order_totals, _order_totals1;
     const gross = Number((_ref = (_ref1 = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref1 : order.amountCents) != null ? _ref : 0);
-    return gross - Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0);
+    const refunded = Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0);
+    // A register tip sits outside `totalCents` (AGL-3607), so a refund that
+    // handed the tip back too must not take the tip out of the SALE's revenue a
+    // second time: what comes off is capped at what the sale itself was.
+    const tipCents = Number((_ref2 = (_order_totals1 = order.totals) == null ? void 0 : _order_totals1.tipCents) != null ? _ref2 : 0);
+    return gross - (tipCents > 0 ? Math.min(refunded, gross) : refunded);
 }
 /** Milliseconds an order was created at, across every writer's field shape. */ export function orderCreatedAtMs(order) {
     var _order_createdAt, _order_createdAt_toDate, _order_createdAt1;