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

package/src/lib/model/shippingeasy.js

@@ -0,0 +1,267 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { orderIsTestMode } from "./commerce-orders.js";
+import { shippingLines, shippingOrderNumber, gramsToOunces } from "./order-shipping-export.js";
+import { shipStationCanImport, weightsOfProducts } from "./shipstation.js";
+/*
+ * SHIPPINGEASY'S ORDER API, AS PURE DATA (AGL-3633).
+ *
+ * ShippingEasy is the opposite direction of ShipStation's Custom Store: it
+ * does not pull. The store PUSHES each order into the merchant's own
+ * ShippingEasy account with the merchant's API key and secret, and
+ * ShippingEasy POSTs a shipment notification to the store's callback URL when
+ * a label is bought (ShippingEasy API reference v1.1 and the official Ruby
+ * client, read 2026-10-07):
+ *
+ * - `POST /api/stores/{store_api_key}/orders` with `{ order: { … } }` creates
+ *   an order; `POST /api/stores/{store_api_key}/orders/{external_order_identifier}/cancellations`
+ *   cancels one; `GET /api/stores/{store_api_key}/orders/{external_order_identifier}` finds one.
+ * - Every request carries `api_key`, `api_timestamp` (Unix seconds) and
+ *   `api_signature` in its query string: the hex HMAC-SHA256, under the API
+ *   secret, of `METHOD&path&query&body` — the query being every other
+ *   parameter sorted by name and form-encoded, the body left off when empty.
+ * - The shipment callback is signed the same way, over the callback's own
+ *   path, query and raw body.
+ *
+ * This module builds the order, the canonical query and the callback reading.
+ * The HMAC, the HTTP and the route live in `server/shippingeasy.ts`.
+ */ /** Where ShippingEasy's API answers. A deployment may point elsewhere with `SHIPPINGEASY_API_BASE_URL`. */ export 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 const SHIPPINGEASY_TIMESTAMP_TOLERANCE_MS = 60 * 60 * 1000;
+/** The status an order arrives in ShippingEasy with. */ export 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 function shippingEasyFormComponent(value) {
+    return encodeURIComponent(value).replace(/[!'()~]/g, (char)=>`%${char.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%20/g, '+');
+}
+/** The parameters sorted by name and joined `a=1&b=2`, as the signature reads them. `api_signature` is never part of it. */ export function shippingEasyCanonicalQuery(params) {
+    return Object.keys(params).filter((name)=>name !== 'api_signature').sort().map((name)=>`${shippingEasyFormComponent(name)}=${shippingEasyFormComponent(params[name])}`).join('&');
+}
+/** The plaintext a request's signature is the HMAC of: `METHOD&path&query&body`, the body left off when empty. */ export function shippingEasySignaturePlaintext(input) {
+    const parts = [
+        input.method.toUpperCase(),
+        input.path,
+        shippingEasyCanonicalQuery(input.params)
+    ];
+    if (input.body) parts.push(input.body);
+    return parts.join('&');
+}
+/**
+ * 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 function shippingEasyIntent(order, docId) {
+    var _order_status, _order_lineItems, _order_fulfillments;
+    if (order.requiresShipping === false) return null;
+    const status = (_order_status = order.status) != null ? _order_status : 'pending';
+    if (status === 'cancelled' || status === 'refunded') return 'cancel';
+    if (status !== 'paid' && status !== 'partially_fulfilled') return null;
+    if (orderIsTestMode(_extends({}, order, {
+        $id: docId
+    }))) return null;
+    if (!shipStationCanImport(order)) return null;
+    return shippingLines({
+        lineItems: (_order_lineItems = order.lineItems) != null ? _order_lineItems : [],
+        fulfillments: (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []
+    }).length ? 'create' : null;
+}
+/*==========================================
+ * THE ORDER
+ *=========================================*/ /** Cents as ShippingEasy's decimal dollars, `"12.50"`. */ function money(cents) {
+    const value = Math.round(Number(cents != null ? cents : 0));
+    return (Number.isFinite(value) ? value / 100 : 0).toFixed(2);
+}
+/** Text trimmed and bounded, or `undefined` when there is none. */ function bounded(value, max) {
+    const text = value === null || value === undefined ? '' : String(value).trim();
+    return text ? text.slice(0, max) : undefined;
+}
+/** A full name as ShippingEasy's first and last name: the last word is the last name. */ export function splitPersonName(name) {
+    const words = String(name != null ? name : '').trim().split(/\s+/).filter(Boolean);
+    if (!words.length) return {};
+    if (words.length === 1) return {
+        first_name: words[0].slice(0, 100)
+    };
+    return {
+        first_name: words.slice(0, -1).join(' ').slice(0, 100),
+        last_name: words[words.length - 1].slice(0, 100)
+    };
+}
+/** The order identifier ShippingEasy keeps: the order number the merchant sees, else the document id. */ export function shippingEasyExternalId(order, docId) {
+    return shippingOrderNumber(order, docId);
+}
+function facts(products, productId, variantId) {
+    var _products_productId, _variants_;
+    const variants = (_products_productId = products[productId]) != null ? _products_productId : {};
+    return _extends({}, (_variants_ = variants['']) != null ? _variants_ : {}, variantId && variants[variantId] || {});
+}
+/** Drops the keys whose value is `undefined`, so the JSON names only what is known. */ function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry])=>entry !== undefined));
+}
+/**
+ * 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 function shippingEasyOrderPayload(source, products = {}) {
+    var _order_createdAtMs, _order_shippingAddress, _order_billingAddress, _order_lineItems, _order_fulfillments, _ship_country, _ref, _bill_country;
+    const { docId, order } = source;
+    const created = Number((_order_createdAtMs = order.createdAtMs) != null ? _order_createdAtMs : 0) || Date.now();
+    const ship = (_order_shippingAddress = order.shippingAddress) != null ? _order_shippingAddress : {};
+    const bill = (_order_billingAddress = order.billingAddress) != null ? _order_billingAddress : {};
+    const totals = order.totals;
+    const email = bounded(order.customerEmail, 100);
+    const weights = weightsOfProducts(products);
+    const lineItems = shippingLines({
+        lineItems: (_order_lineItems = order.lineItems) != null ? _order_lineItems : [],
+        fulfillments: (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []
+    }, weights).map(({ lineItemId, line, quantity, unitGrams })=>{
+        var _known_options, _bounded, _line_unitAmountCents;
+        const known = facts(products, line.productId, line.variantId);
+        const options = Object.entries((_known_options = known.options) != null ? _known_options : {}).filter(([name, value])=>String(name).trim() && String(value).trim()).slice(0, 10);
+        return compact({
+            item_name: (_bounded = bounded(`${line.name}${line.variantLabel ? ` (${line.variantLabel})` : ''}`, 200)) != null ? _bounded : 'Item',
+            sku: bounded(line.sku || (line.variantId ? `${line.productId}-${line.variantId}` : line.productId), 100),
+            ext_line_item_id: String(lineItemId),
+            ext_product_id: bounded(line.productId, 100),
+            unit_price: money(line.unitAmountCents),
+            total_excluding_tax: money(Math.round(Number((_line_unitAmountCents = line.unitAmountCents) != null ? _line_unitAmountCents : 0)) * quantity),
+            weight_in_ounces: unitGrams !== null ? gramsToOunces(unitGrams).toFixed(2) : undefined,
+            quantity: String(quantity),
+            product_options: options.length ? Object.fromEntries(options) : undefined
+        });
+    });
+    const recipient = compact(_extends({}, splitPersonName(ship.name || order.customerName), {
+        email,
+        phone_number: bounded(ship.phone || order.customerPhone, 50),
+        address: bounded(ship.line1, 200),
+        address2: bounded(ship.line2, 200),
+        city: bounded(ship.city, 100),
+        state: bounded(ship.state, 100),
+        postal_code: bounded(ship.postalCode, 50),
+        country: bounded(String((_ship_country = ship.country) != null ? _ship_country : '').toUpperCase(), 2),
+        base_cost: money(totals == null ? void 0 : totals.shippingCents),
+        cost_excluding_tax: money(totals == null ? void 0 : totals.shippingCents),
+        items_total: String(lineItems.reduce((sum, item)=>sum + Number(item['quantity']), 0)),
+        items_shipped: '0',
+        line_items: lineItems
+    }));
+    const billName = splitPersonName(bill.name || order.customerName);
+    return {
+        order: compact({
+            external_order_identifier: shippingEasyExternalId(order, docId),
+            ordered_at: new Date(created).toISOString(),
+            order_status: SHIPPINGEASY_AWAITING_SHIPMENT,
+            total_including_tax: money((_ref = totals == null ? void 0 : totals.totalCents) != null ? _ref : order.amountCents),
+            total_tax: money(totals == null ? void 0 : totals.taxCents),
+            subtotal_including_tax: money(totals == null ? void 0 : totals.itemsCents),
+            discount_amount: money(totals == null ? void 0 : totals.discountCents),
+            base_shipping_cost: money(totals == null ? void 0 : totals.shippingCents),
+            shipping_cost_excluding_tax: money(totals == null ? void 0 : totals.shippingCents),
+            notes: bounded(order.note, 1000),
+            billing_first_name: billName.first_name,
+            billing_last_name: billName.last_name,
+            billing_address: bounded(bill.line1, 200),
+            billing_address2: bounded(bill.line2, 200),
+            billing_city: bounded(bill.city, 100),
+            billing_state: bounded(bill.state, 100),
+            billing_postal_code: bounded(bill.postalCode, 50),
+            billing_country: bounded(String((_bill_country = bill.country) != null ? _bill_country : '').toUpperCase(), 2),
+            billing_phone_number: bounded(bill.phone || order.customerPhone, 50),
+            billing_email: email,
+            recipients: [
+                recipient
+            ]
+        })
+    };
+}
+/*==========================================
+ * THE SHIPMENT CALLBACK
+ *=========================================*/ /**
+ * 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 const SHIPPINGEASY_SHIPPED_STATES = new Set([
+    'label_ready',
+    'label_printed',
+    'drop_shipped'
+]);
+const asObject = (value)=>value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const asArray = (value)=>Array.isArray(value) ? value : [];
+const asText = (value)=>value === null || value === undefined ? '' : String(value).trim();
+/**
+ * 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 function readShippingEasyCallback(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    } catch (unused) {
+        return {
+            problem: 'The callback is not JSON.'
+        };
+    }
+    const shipment = asObject(asObject(parsed)['shipment']);
+    if (!Object.keys(shipment).length) return {
+        problem: 'The callback names no shipment.'
+    };
+    const carrier = asText(shipment['carrier_key']);
+    const service = asText(shipment['carrier_service_key']);
+    const trackingNumber = asText(shipment['tracking_number']).slice(0, 100);
+    const notices = [];
+    for (const entry of asArray(shipment['orders'])){
+        const order = asObject(entry);
+        const external = asText(order['external_order_identifier']).slice(0, 200);
+        if (!external) continue;
+        const items = [];
+        for (const recipient of asArray(order['recipients'])){
+            for (const raw of asArray(asObject(recipient)['line_items'])){
+                const line = asObject(raw);
+                const quantity = Math.floor(Number(line['quantity']));
+                if (!Number.isFinite(quantity) || quantity <= 0) continue;
+                items.push({
+                    lineItemId: asText(line['ext_line_item_id']) || null,
+                    sku: asText(line['sku']) || null,
+                    name: asText(line['item_name']) || null,
+                    quantity
+                });
+            }
+        }
+        notices.push({
+            orderNumber: external,
+            orderId: null,
+            carrier,
+            service,
+            trackingNumber,
+            items
+        });
+    }
+    return {
+        shipmentId: asText(shipment['id']) || null,
+        workflowState: asText(shipment['workflow_state']).toLowerCase(),
+        notices
+    };
+}
+
+//# sourceMappingURL=shippingeasy.js.map

package/src/lib/model/shippingeasy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/shippingeasy.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 { HostOrder, OrderStatus } from './commerce-orders'\nimport { orderIsTestMode } from './commerce-orders'\nimport { shippingLines, shippingOrderNumber, gramsToOunces } from './order-shipping-export'\nimport {\n  shipStationCanImport,\n  weightsOfProducts,\n  type ShipNotice,\n  type ShipNoticeItem,\n  type ShipStationOrderSource,\n  type ShipStationProductFacts,\n  type ShipStationProducts,\n} from './shipstation'\n\n/*\n * SHIPPINGEASY'S ORDER API, AS PURE DATA (AGL-3633).\n *\n * ShippingEasy is the opposite direction of ShipStation's Custom Store: it\n * does not pull. The store PUSHES each order into the merchant's own\n * ShippingEasy account with the merchant's API key and secret, and\n * ShippingEasy POSTs a shipment notification to the store's callback URL when\n * a label is bought (ShippingEasy API reference v1.1 and the official Ruby\n * client, read 2026-10-07):\n *\n * - `POST /api/stores/{store_api_key}/orders` with `{ order: { … } }` creates\n *   an order; `POST /api/stores/{store_api_key}/orders/{external_order_identifier}/cancellations`\n *   cancels one; `GET /api/stores/{store_api_key}/orders/{external_order_identifier}` finds one.\n * - Every request carries `api_key`, `api_timestamp` (Unix seconds) and\n *   `api_signature` in its query string: the hex HMAC-SHA256, under the API\n *   secret, of `METHOD&path&query&body` — the query being every other\n *   parameter sorted by name and form-encoded, the body left off when empty.\n * - The shipment callback is signed the same way, over the callback's own\n *   path, query and raw body.\n *\n * This module builds the order, the canonical query and the callback reading.\n * The HMAC, the HTTP and the route live in `server/shippingeasy.ts`.\n */\n\n/** Where ShippingEasy's API answers. A deployment may point elsewhere with `SHIPPINGEASY_API_BASE_URL`. */\nexport const SHIPPINGEASY_DEFAULT_BASE_URL = 'https://app.shippingeasy.com'\n\n/** How far a signed callback's `api_timestamp` may be from now: the Ruby client's own hour. */\nexport const SHIPPINGEASY_TIMESTAMP_TOLERANCE_MS = 60 * 60 * 1000\n\n/** The status an order arrives in ShippingEasy with. */\nexport const SHIPPINGEASY_AWAITING_SHIPMENT = 'awaiting_shipment'\n\n/**\n * A value form-encoded as Ruby's `URI.encode_www_form_component` writes it,\n * which is what ShippingEasy's signature was computed over: letters, digits\n * and `*-._` as they are, a space as `+`, every other byte as `%XX` upper-case.\n */\nexport function shippingEasyFormComponent(value: string): string {\n  return encodeURIComponent(value)\n    .replace(/[!'()~]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)\n    .replace(/%20/g, '+')\n}\n\n/** The parameters sorted by name and joined `a=1&b=2`, as the signature reads them. `api_signature` is never part of it. */\nexport function shippingEasyCanonicalQuery(params: Readonly<Record<string, string>>): string {\n  return Object.keys(params)\n    .filter((name) => name !== 'api_signature')\n    .sort()\n    .map((name) => `${shippingEasyFormComponent(name)}=${shippingEasyFormComponent(params[name])}`)\n    .join('&')\n}\n\n/** The plaintext a request's signature is the HMAC of: `METHOD&path&query&body`, the body left off when empty. */\nexport function shippingEasySignaturePlaintext(input: {\n  method: string\n  path: string\n  params: Readonly<Record<string, string>>\n  body?: string | null\n}): string {\n  const parts = [input.method.toUpperCase(), input.path, shippingEasyCanonicalQuery(input.params)]\n  if (input.body) parts.push(input.body)\n  return parts.join('&')\n}\n\n/*==========================================\n * WHAT TO DO WITH AN ORDER\n *=========================================*/\n\n/** What a changed order asks of ShippingEasy. */\nexport type ShippingEasyIntent = 'create' | 'cancel' | null\n\n/**\n * Whether an order goes to ShippingEasy, comes back out of it, or neither.\n *\n * - A paid or partly shipped order with something to ship and a full\n *   ship-to address is CREATED. A test-mode order never is: ShippingEasy is\n *   the merchant's real label account, and a label bought for a test order\n *   is real postage.\n * - A canceled or fully refunded order is CANCELED there, which the caller\n *   does only when it once sent the order.\n * - Anything else (pending, shipped, delivered) asks nothing.\n */\nexport function shippingEasyIntent(\n  order: Partial<HostOrder> & { livemode?: unknown; requiresShipping?: unknown },\n  docId: string,\n): ShippingEasyIntent {\n  if (order.requiresShipping === false) return null\n  const status = (order.status ?? 'pending') as OrderStatus\n  if (status === 'cancelled' || status === 'refunded') return 'cancel'\n  if (status !== 'paid' && status !== 'partially_fulfilled') return null\n  if (orderIsTestMode({ ...order, $id: docId })) return null\n  if (!shipStationCanImport(order)) return null\n  return shippingLines({ lineItems: order.lineItems ?? [], fulfillments: order.fulfillments ?? [] }).length ? 'create' : null\n}\n\n/*==========================================\n * THE ORDER\n *=========================================*/\n\n/** Cents as ShippingEasy's decimal dollars, `\"12.50\"`. */\nfunction money(cents: unknown): string {\n  const value = Math.round(Number(cents ?? 0))\n  return (Number.isFinite(value) ? value / 100 : 0).toFixed(2)\n}\n\n/** Text trimmed and bounded, or `undefined` when there is none. */\nfunction bounded(value: unknown, max: number): string | undefined {\n  const text = value === null || value === undefined ? '' : String(value).trim()\n  return text ? text.slice(0, max) : undefined\n}\n\n/** A full name as ShippingEasy's first and last name: the last word is the last name. */\nexport function splitPersonName(name: unknown): { first_name?: string; last_name?: string } {\n  const words = String(name ?? '').trim().split(/\\s+/).filter(Boolean)\n  if (!words.length) return {}\n  if (words.length === 1) return { first_name: words[0].slice(0, 100) }\n  return { first_name: words.slice(0, -1).join(' ').slice(0, 100), last_name: words[words.length - 1].slice(0, 100) }\n}\n\n/** The order identifier ShippingEasy keeps: the order number the merchant sees, else the document id. */\nexport function shippingEasyExternalId(order: Pick<HostOrder, 'number'>, docId: string): string {\n  return shippingOrderNumber(order, docId)\n}\n\nfunction facts(products: ShipStationProducts, productId: string, variantId?: string): ShipStationProductFacts {\n  const variants = products[productId] ?? {}\n  return { ...(variants[''] ?? {}), ...((variantId && variants[variantId]) || {}) }\n}\n\n/** Drops the keys whose value is `undefined`, so the JSON names only what is known. */\nfunction compact<T extends Record<string, unknown>>(value: T): T {\n  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T\n}\n\n/**\n * The `{ order }` body that creates an order in ShippingEasy. The items are\n * what is LEFT to ship, so a partly shipped order sent after its first parcel\n * asks for the rest; each carries its line's index as `ext_line_item_id`,\n * which the shipment callback hands back to name the line.\n */\nexport function shippingEasyOrderPayload(\n  source: ShipStationOrderSource,\n  products: ShipStationProducts = {},\n): { order: Record<string, unknown> } {\n  const { docId, order } = source\n  const created = Number(order.createdAtMs ?? 0) || Date.now()\n  const ship = order.shippingAddress ?? {}\n  const bill = order.billingAddress ?? {}\n  const totals = order.totals\n  const email = bounded(order.customerEmail, 100)\n  const weights = weightsOfProducts(products)\n  const lineItems = shippingLines({ lineItems: order.lineItems ?? [], fulfillments: order.fulfillments ?? [] }, weights).map(\n    ({ lineItemId, line, quantity, unitGrams }) => {\n      const known = facts(products, line.productId, line.variantId)\n      const options = Object.entries(known.options ?? {})\n        .filter(([name, value]) => String(name).trim() && String(value).trim())\n        .slice(0, 10)\n      return compact({\n        item_name: bounded(`${line.name}${line.variantLabel ? ` (${line.variantLabel})` : ''}`, 200) ?? 'Item',\n        sku: bounded(line.sku || (line.variantId ? `${line.productId}-${line.variantId}` : line.productId), 100),\n        ext_line_item_id: String(lineItemId),\n        ext_product_id: bounded(line.productId, 100),\n        unit_price: money(line.unitAmountCents),\n        total_excluding_tax: money(Math.round(Number(line.unitAmountCents ?? 0)) * quantity),\n        weight_in_ounces: unitGrams !== null ? gramsToOunces(unitGrams).toFixed(2) : undefined,\n        quantity: String(quantity),\n        product_options: options.length ? Object.fromEntries(options) : undefined,\n      })\n    },\n  )\n  const recipient = compact({\n    ...splitPersonName(ship.name || order.customerName),\n    email,\n    phone_number: bounded(ship.phone || order.customerPhone, 50),\n    address: bounded(ship.line1, 200),\n    address2: bounded(ship.line2, 200),\n    city: bounded(ship.city, 100),\n    state: bounded(ship.state, 100),\n    postal_code: bounded(ship.postalCode, 50),\n    country: bounded(String(ship.country ?? '').toUpperCase(), 2),\n    base_cost: money(totals?.shippingCents),\n    cost_excluding_tax: money(totals?.shippingCents),\n    items_total: String(lineItems.reduce((sum, item) => sum + Number(item['quantity']), 0)),\n    items_shipped: '0',\n    line_items: lineItems,\n  })\n  const billName = splitPersonName(bill.name || order.customerName)\n  return {\n    order: compact({\n      external_order_identifier: shippingEasyExternalId(order, docId),\n      ordered_at: new Date(created).toISOString(),\n      order_status: SHIPPINGEASY_AWAITING_SHIPMENT,\n      total_including_tax: money(totals?.totalCents ?? order.amountCents),\n      total_tax: money(totals?.taxCents),\n      subtotal_including_tax: money(totals?.itemsCents),\n      discount_amount: money(totals?.discountCents),\n      base_shipping_cost: money(totals?.shippingCents),\n      shipping_cost_excluding_tax: money(totals?.shippingCents),\n      notes: bounded(order.note, 1000),\n      billing_first_name: billName.first_name,\n      billing_last_name: billName.last_name,\n      billing_address: bounded(bill.line1, 200),\n      billing_address2: bounded(bill.line2, 200),\n      billing_city: bounded(bill.city, 100),\n      billing_state: bounded(bill.state, 100),\n      billing_postal_code: bounded(bill.postalCode, 50),\n      billing_country: bounded(String(bill.country ?? '').toUpperCase(), 2),\n      billing_phone_number: bounded(bill.phone || order.customerPhone, 50),\n      billing_email: email,\n      recipients: [recipient],\n    }),\n  }\n}\n\n/*==========================================\n * THE SHIPMENT CALLBACK\n *=========================================*/\n\n/**\n * The label states that mean a parcel is on its way. `label_pending` is not\n * bought yet and `cancelled` was voided, so neither ships anything.\n */\nexport const SHIPPINGEASY_SHIPPED_STATES: ReadonlySet<string> = new Set(['label_ready', 'label_printed', 'drop_shipped'])\n\n/** What one callback says. */\nexport interface ShippingEasyCallback {\n  /** ShippingEasy's own shipment id, for the log. */\n  shipmentId: string | null\n  workflowState: string\n  /** One notice per order the shipment carries, in the shape every connector records. */\n  notices: ShipNotice[]\n}\n\ntype Json = Record<string, unknown>\nconst asObject = (value: unknown): Json => (value && typeof value === 'object' && !Array.isArray(value) ? (value as Json) : {})\nconst asArray = (value: unknown): unknown[] => (Array.isArray(value) ? value : [])\nconst asText = (value: unknown): string => (value === null || value === undefined ? '' : String(value).trim())\n\n/**\n * A shipment callback's JSON read into notices, or the reason it cannot be.\n * Each order of the shipment is one notice under the shipment's tracking\n * number; its items are the recipients' line items, named back by the\n * `ext_line_item_id` the order was sent with, else by SKU.\n */\nexport function readShippingEasyCallback(body: string): ShippingEasyCallback | { problem: string } {\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(body)\n  } catch {\n    return { problem: 'The callback is not JSON.' }\n  }\n  const shipment = asObject(asObject(parsed)['shipment'])\n  if (!Object.keys(shipment).length) return { problem: 'The callback names no shipment.' }\n  const carrier = asText(shipment['carrier_key'])\n  const service = asText(shipment['carrier_service_key'])\n  const trackingNumber = asText(shipment['tracking_number']).slice(0, 100)\n  const notices: ShipNotice[] = []\n  for (const entry of asArray(shipment['orders'])) {\n    const order = asObject(entry)\n    const external = asText(order['external_order_identifier']).slice(0, 200)\n    if (!external) continue\n    const items: ShipNoticeItem[] = []\n    for (const recipient of asArray(order['recipients'])) {\n      for (const raw of asArray(asObject(recipient)['line_items'])) {\n        const line = asObject(raw)\n        const quantity = Math.floor(Number(line['quantity']))\n        if (!Number.isFinite(quantity) || quantity <= 0) continue\n        items.push({\n          lineItemId: asText(line['ext_line_item_id']) || null,\n          sku: asText(line['sku']) || null,\n          name: asText(line['item_name']) || null,\n          quantity,\n        })\n      }\n    }\n    notices.push({ orderNumber: external, orderId: null, carrier, service, trackingNumber, items })\n  }\n  return {\n    shipmentId: asText(shipment['id']) || null,\n    workflowState: asText(shipment['workflow_state']).toLowerCase(),\n    notices,\n  }\n}\n"],"names":["orderIsTestMode","shippingLines","shippingOrderNumber","gramsToOunces","shipStationCanImport","weightsOfProducts","SHIPPINGEASY_DEFAULT_BASE_URL","SHIPPINGEASY_TIMESTAMP_TOLERANCE_MS","SHIPPINGEASY_AWAITING_SHIPMENT","shippingEasyFormComponent","value","encodeURIComponent","replace","char","charCodeAt","toString","toUpperCase","shippingEasyCanonicalQuery","params","Object","keys","filter","name","sort","map","join","shippingEasySignaturePlaintext","input","parts","method","path","body","push","shippingEasyIntent","order","docId","requiresShipping","status","$id","lineItems","fulfillments","length","money","cents","Math","round","Number","isFinite","toFixed","bounded","max","text","undefined","String","trim","slice","splitPersonName","words","split","Boolean","first_name","last_name","shippingEasyExternalId","facts","products","productId","variantId","variants","compact","fromEntries","entries","entry","shippingEasyOrderPayload","source","ship","bill","created","createdAtMs","Date","now","shippingAddress","billingAddress","totals","email","customerEmail","weights","lineItemId","line","quantity","unitGrams","known","options","item_name","variantLabel","sku","ext_line_item_id","ext_product_id","unit_price","unitAmountCents","total_excluding_tax","weight_in_ounces","product_options","recipient","customerName","phone_number","phone","customerPhone","address","line1","address2","line2","city","state","postal_code","postalCode","country","base_cost","shippingCents","cost_excluding_tax","items_total","reduce","sum","item","items_shipped","line_items","billName","external_order_identifier","ordered_at","toISOString","order_status","total_including_tax","totalCents","amountCents","total_tax","taxCents","subtotal_including_tax","itemsCents","discount_amount","discountCents","base_shipping_cost","shipping_cost_excluding_tax","notes","note","billing_first_name","billing_last_name","billing_address","billing_address2","billing_city","billing_state","billing_postal_code","billing_country","billing_phone_number","billing_email","recipients","SHIPPINGEASY_SHIPPED_STATES","Set","asObject","Array","isArray","asArray","asText","readShippingEasyCallback","parsed","JSON","parse","problem","shipment","carrier","service","trackingNumber","notices","external","items","raw","floor","orderNumber","orderId","shipmentId","workflowState","toLowerCase"],"mappings":"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"}

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

@@ -0,0 +1,125 @@
+/**
+ * @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, OrderStatus } from './commerce-orders';
+import { type ProductWeights } from './order-shipping-export';
+export declare const SHIPSTATION_STATUS_NAMES: {
+    readonly unpaid: "unpaid";
+    readonly paid: "paid";
+    readonly shipped: "shipped";
+    readonly canceled: "canceled";
+    readonly onHold: "on_hold";
+};
+/** An Aglyn order status as the feed names it to ShipStation. */
+export declare function shipStationOrderStatus(status: OrderStatus): string;
+/** Orders per page of the feed. ShipStation follows `pages` until it has them all. */
+export declare const SHIPSTATION_PAGE_SIZE = 100;
+/** The widest window one request may ask for: a year, which no import needs. */
+export declare const SHIPSTATION_MAX_WINDOW_MS: number;
+/** Epoch milliseconds as ShipStation's `MM/dd/yyyy HH:mm`, in UTC. */
+export declare function formatShipStationDate(ms: number): string;
+/**
+ * ShipStation's `MM/dd/yyyy HH:mm` (UTC; seconds and AM/PM tolerated) as
+ * epoch milliseconds, or `null` when the text is not a date. An ISO date is
+ * read too, for a merchant testing the URL by hand.
+ */
+export declare function parseShipStationDate(value: unknown): number | null;
+/** What the feed knows about one variant of a product, read once per page. */
+export interface ShipStationProductFacts {
+    grams?: number;
+    imageUrl?: string;
+    /** The variant's option choices: `{ Size: 'L', Color: 'Blue' }`. */
+    options?: Readonly<Record<string, string>>;
+}
+/** Product id → variant id (`''` for the product itself) → its facts. */
+export type ShipStationProducts = Readonly<Record<string, Readonly<Record<string, ShipStationProductFacts>>>>;
+/** The weights the shared shipping reading takes, from the products' facts. */
+export declare function weightsOfProducts(products: ShipStationProducts): ProductWeights;
+/**
+ * Free text as a CDATA section, as the guide asks. A `]]>` inside the text
+ * would end the section early, so it is split across two sections — the
+ * standard escape, which reads back as the same characters.
+ */
+export declare function xmlCdata(value: unknown, max: number): string;
+/** A plain value (a number, a date, a code) with the five XML entities escaped. */
+export declare function xmlText(value: unknown, max?: number): string;
+/** One order as the feed needs it: the stored order and its document id. */
+export interface ShipStationOrderSource {
+    docId: string;
+    order: Partial<HostOrder> & {
+        createdAtMs?: number;
+        updatedAtMs?: number;
+    };
+}
+/**
+ * Whether ShipStation can take this order at all: it insists on a ship-to
+ * name, street, city, postal code and two-letter country. An order without
+ * them could never become a label, and one invalid `<Order>` fails the whole
+ * import, so it is left out of the feed rather than sent with a guess.
+ */
+export declare function shipStationCanImport(order: Partial<HostOrder>): boolean;
+/** One `<Order>` element of the feed. */
+export declare function shipStationOrderXml(source: ShipStationOrderSource, products?: ShipStationProducts): string;
+/** The whole `<Orders>` document for one page. */
+export declare function shipStationOrdersXml(orders: readonly string[], pages: number): string;
+/** One shipped line of a notice. */
+export interface ShipNoticeItem {
+    lineItemId: string | null;
+    sku: string | null;
+    name: string | null;
+    quantity: number;
+}
+/** What a ShipNotice says, from its query string and its body together. */
+export interface ShipNotice {
+    orderNumber: string | null;
+    orderId: string | null;
+    carrier: string;
+    service: string;
+    trackingNumber: string;
+    items: ShipNoticeItem[];
+}
+/**
+ * A `<ShipNotice>` body read into a notice, or the reason it cannot be.
+ *
+ * Read by name, not by a general parser: the notice is a fixed, flat set of
+ * elements, and a document type declaration is refused outright, so no
+ * entity is ever defined or expanded beyond XML's five. The query string's
+ * `order_number`, `carrier`, `service` and `tracking_number` win when
+ * present — the guide names them first — and the body fills the rest.
+ */
+export declare function readShipNotice(xml: string, query: Readonly<Record<string, string | undefined>>): ShipNotice | {
+    problem: string;
+};
+/**
+ * ShipStation's carrier code as a name a buyer reads and `trackingUrlFor`
+ * knows — `usps` → `USPS`, `fedex` → `FedEx`. An unknown code is passed on
+ * as sent, upper-cased at the first letter.
+ */
+export declare function shipStationCarrierName(code: string): string;
+/**
+ * Which order lines and how many units a notice ships, against the order.
+ * An item is found by the `LineItemID` the feed sent (the line's index),
+ * then by SKU among the lines still to ship. `null` lines means the notice
+ * named no items: everything still to ship went in this parcel. An item that
+ * names no line of this order is reported, not guessed at.
+ */
+export declare function shipNoticeLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>, items: readonly ShipNoticeItem[]): {
+    lines: Array<{
+        lineItemId: number;
+        quantity: number;
+    }> | null;
+    unknown: string[];
+};