@lacspace/order 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+# @lacspace/order
+
+**A headless order-lifecycle engine — an immutable order model with a state machine, price snapshotting & timestamped history.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/order?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/order)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/order?label=minzip)](https://bundlephobia.com/package/@lacspace/order)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/order)
+[![license](https://img.shields.io/npm/l/@lacspace/order?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> The order spine between a cart and a courier. A tiny set of **pure functions** over a plain `Order` object — snapshot line prices, drive a status **state machine**, mint order numbers, and keep a **timestamped history**. No React, no store, no floats.
+
+- 🧊 **Immutable** — every op returns a brand-new order; your input is never mutated
+- 🔁 **State machine** — a validated status graph (`pending → placed → paid → … → completed`)
+- 📸 **Snapshotted** — line prices are frozen at order time, so catalogue changes never rewrite history
+- 🪙 **Exact money** — integer **minor units** everywhere, so you never lose a penny
+- 💾 **Serializable** — `Order` is plain data, safe to `JSON.stringify` and persist
+- ⚡ Isomorphic — Node, edge runtimes & browsers · 📦 ESM + CJS · fully typed · zero deps
+
+## Install
+
+```bash
+npm i @lacspace/order      # or pnpm add / yarn add / bun add
+```
+
+## Create an order
+
+```ts
+import { createOrder } from "@lacspace/order";
+
+const order = createOrder({
+  currency: "USD",
+  customer: { id: "u_1", name: "Ada", email: "ada@example.com" },
+  lines: [
+    { sku: "tee", name: "Tee", unitPrice: 1999, qty: 2, taxRate: 0.2 }, // $19.99
+    { sku: "cap", name: "Cap", unitPrice: 999, qty: 1, taxRate: 0.2 },
+  ],
+  discount: 500, // minor units
+  shipping: 999,
+});
+
+order.totals; // { subtotal, discount, tax, shipping, total } — all integer minor units
+order.status; // "pending"
+order.lines[0].total; // 3998 — snapshotted at order time
+```
+
+`total = subtotal - discount + tax + shipping`, clamped to never go below `0`. Tax defaults to the sum of `round(line.total * line.taxRate)` per line, or you can pass an explicit `tax` in minor units.
+
+## Drive the lifecycle
+
+```ts
+import { transition } from "@lacspace/order";
+
+let o = createOrder({ currency: "USD", lines });
+o = transition(o, "placed", { note: "checkout complete" });
+o = transition(o, "paid", { at: Date.now() });
+o = transition(o, "processing");
+// illegal jumps throw:
+transition(o, "delivered"); // OrderError { code: "invalid-transition" }
+
+o.history; // [{ status, at, note? }, …] — one event per hop
+```
+
+### The status graph
+
+`pending → placed → paid → processing → fulfilled → shipped → delivered → completed`, with `on_hold`, `cancelled` and `refunded` branches. `completed`, `cancelled` and `refunded` are terminal.
+
+## Edit before payment, lock after
+
+```ts
+import { addLine, updateQty, removeLine } from "@lacspace/order";
+
+let o = transition(createOrder({ currency: "USD", lines }), "placed");
+o = addLine(o, { sku: "sticker", unitPrice: 100, qty: 3 }); // totals recomputed
+o = updateQty(o, "sticker", 1); // qty 0 removes the line
+
+o = transition(o, "paid");
+addLine(o, { sku: "x", unitPrice: 1, qty: 1 }); // OrderError { code: "locked" }
+```
+
+## Numbering
+
+```ts
+import { orderNumber, randomOrderId } from "@lacspace/order";
+
+orderNumber(1); // "ORD-20260905-0001" (deterministic given seq + date)
+orderNumber(42, { prefix: "INV", pad: 6, separator: "/" }); // "INV/20260905/000042"
+randomOrderId({ prefix: "ord" }); // "ord_k3f9x1a7q2mz" — crypto-random short id
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `createOrder(input)` | build an immutable order; snapshots line totals, computes totals, seeds history |
+| `transition(order, to, opts?)` | validated status change; appends a history event; throws on illegal moves |
+| `addLine` / `removeLine` / `updateQty` | edit lines & recompute totals — allowed only while `pending`/`placed` |
+| `canTransition(from, to)` / `isTerminal(s)` | raw state-machine queries |
+| `canCancel` / `canRefund` / `canShip` / `canFulfill` | convenience predicates over an order |
+| `orderNumber(seq, opts?)` | deterministic human order number, e.g. `"ORD-20260905-0001"` |
+| `randomOrderId(opts?)` | crypto-random short id (falls back to `Math.random` with a warning) |
+| `ORDER_TRANSITIONS` | the status → allowed-next-statuses map |
+| `OrderError` | thrown with codes `"invalid-transition"` / `"locked"` |
+
+Types exported: `OrderStatus`, `OrderLine`, `OrderLineInput`, `StatusEvent`, `OrderTotals`, `Order`, `CreateOrderInput`.
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+<!-- LACSPACE-DEV-PLATFORM -->
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/order` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+// src/index.ts
+var ORDER_TRANSITIONS = {
+  pending: ["placed", "cancelled"],
+  placed: ["paid", "cancelled", "on_hold"],
+  paid: ["processing", "refunded", "on_hold", "cancelled"],
+  processing: ["fulfilled", "on_hold", "cancelled", "refunded"],
+  fulfilled: ["shipped", "refunded"],
+  shipped: ["delivered", "refunded"],
+  delivered: ["completed", "refunded"],
+  on_hold: ["placed", "paid", "processing", "cancelled"],
+  completed: [],
+  cancelled: [],
+  refunded: []
+};
+function canTransition(from, to) {
+  return ORDER_TRANSITIONS[from].includes(to);
+}
+function isTerminal(status) {
+  return ORDER_TRANSITIONS[status].length === 0;
+}
+var OrderError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "OrderError";
+    this.code = code;
+  }
+};
+function canCancel(order) {
+  return canTransition(order.status, "cancelled");
+}
+function canRefund(order) {
+  return canTransition(order.status, "refunded");
+}
+function canShip(order) {
+  return canTransition(order.status, "shipped");
+}
+function canFulfill(order) {
+  return canTransition(order.status, "fulfilled");
+}
+function snapshotLine(input) {
+  const qty = Math.max(0, Math.trunc(input.qty));
+  const unitPrice = Math.trunc(input.unitPrice);
+  const line = {
+    id: input.id ?? input.sku,
+    sku: input.sku,
+    name: input.name ?? input.sku,
+    unitPrice,
+    qty,
+    total: unitPrice * qty
+  };
+  if (input.taxRate !== void 0) line.taxRate = input.taxRate;
+  if (input.meta !== void 0) line.meta = input.meta;
+  return line;
+}
+function computeTotals(lines, opts) {
+  const subtotal = lines.reduce((sum, l) => sum + l.total, 0);
+  const discount = Math.max(0, Math.trunc(opts.discount ?? 0));
+  const shipping = Math.max(0, Math.trunc(opts.shipping ?? 0));
+  const tax = opts.tax !== void 0 ? Math.max(0, Math.trunc(opts.tax)) : lines.reduce((sum, l) => sum + Math.round(l.total * (l.taxRate ?? 0)), 0);
+  const total = Math.max(0, subtotal - discount + tax + shipping);
+  return { subtotal, discount, tax, shipping, total };
+}
+function createOrder(input) {
+  const now = input.now ?? Date.now();
+  const lines = input.lines.map(snapshotLine);
+  const totals = computeTotals(lines, input);
+  const status = input.status ?? "pending";
+  const id = input.id ?? randomOrderId({ prefix: "ord" });
+  const order = {
+    id,
+    number: input.number ?? id,
+    status,
+    currency: input.currency,
+    lines,
+    totals,
+    history: [{ status, at: now }],
+    createdAt: now,
+    updatedAt: now
+  };
+  if (input.customer !== void 0) order.customer = input.customer;
+  if (input.meta !== void 0) order.meta = input.meta;
+  return order;
+}
+function transition(order, to, opts) {
+  if (!canTransition(order.status, to)) {
+    throw new OrderError(
+      `Cannot transition order from "${order.status}" to "${to}".`,
+      "invalid-transition"
+    );
+  }
+  const at = opts?.at ?? Date.now();
+  const event = { status: to, at };
+  if (opts?.note !== void 0) event.note = opts.note;
+  return {
+    ...order,
+    status: to,
+    history: [...order.history, event],
+    updatedAt: at
+  };
+}
+var EDITABLE_STATUSES = ["pending", "placed"];
+function assertEditable(order) {
+  if (!EDITABLE_STATUSES.includes(order.status)) {
+    throw new OrderError(
+      `Order is locked for editing in status "${order.status}"; lines can only change while pending or placed.`,
+      "locked"
+    );
+  }
+}
+function reprice(order, lines, now) {
+  const at = now ?? Date.now();
+  return {
+    ...order,
+    lines,
+    totals: computeTotals(lines, {
+      discount: order.totals.discount,
+      shipping: order.totals.shipping
+    }),
+    updatedAt: at
+  };
+}
+function addLine(order, line, now) {
+  assertEditable(order);
+  return reprice(order, [...order.lines, snapshotLine(line)], now);
+}
+function removeLine(order, lineId, now) {
+  assertEditable(order);
+  return reprice(
+    order,
+    order.lines.filter((l) => l.id !== lineId),
+    now
+  );
+}
+function updateQty(order, lineId, qty, now) {
+  assertEditable(order);
+  const next = Math.max(0, Math.trunc(qty));
+  const lines = order.lines.map(
+    (l) => l.id === lineId ? { ...l, qty: next, total: l.unitPrice * next } : l
+  ).filter((l) => l.qty > 0);
+  return reprice(order, lines, now);
+}
+function pad(n, width) {
+  const s = String(Math.abs(Math.trunc(n)));
+  return s.length >= width ? s : "0".repeat(width - s.length) + s;
+}
+function orderNumber(seq, opts) {
+  const prefix = opts?.prefix ?? "ORD";
+  const date = opts?.date ?? /* @__PURE__ */ new Date();
+  const width = opts?.pad ?? 4;
+  const sep = opts?.separator ?? "-";
+  const y = date.getFullYear();
+  const m = pad(date.getMonth() + 1, 2);
+  const d = pad(date.getDate(), 2);
+  return `${prefix}${sep}${y}${m}${d}${sep}${pad(seq, width)}`;
+}
+var ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function randomBytes(out) {
+  const g = typeof globalThis !== "undefined" ? globalThis : {};
+  if (g.crypto && typeof g.crypto.getRandomValues === "function") {
+    g.crypto.getRandomValues(out);
+    return out;
+  }
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(
+      "[@lacspace/order] globalThis.crypto is unavailable; falling back to Math.random for randomOrderId (not cryptographically secure)."
+    );
+  }
+  for (let i = 0; i < out.length; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+function randomOrderId(opts) {
+  const bytes = randomBytes(new Uint8Array(16));
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += ID_ALPHABET[bytes[i] % ID_ALPHABET.length];
+  }
+  const prefix = opts?.prefix;
+  return prefix ? `${prefix}_${out}` : out;
+}
+
+exports.ORDER_TRANSITIONS = ORDER_TRANSITIONS;
+exports.OrderError = OrderError;
+exports.addLine = addLine;
+exports.canCancel = canCancel;
+exports.canFulfill = canFulfill;
+exports.canRefund = canRefund;
+exports.canShip = canShip;
+exports.canTransition = canTransition;
+exports.createOrder = createOrder;
+exports.isTerminal = isTerminal;
+exports.orderNumber = orderNumber;
+exports.randomOrderId = randomOrderId;
+exports.removeLine = removeLine;
+exports.transition = transition;
+exports.updateQty = updateQty;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/order — a headless order-lifecycle engine.\n *\n * The spine between a cart and a courier: a pure, immutable and serializable\n * `Order` model with a state machine, order-number generation, line-item price\n * snapshotting, and a timestamped status history. Every operation returns a\n * brand-new `Order`; the input is never mutated, so the state plays nicely with\n * React, Redux, Zustand, signals, or a plain JSON column in your database.\n *\n * All money is expressed in **integer minor units** (cents, paise, satoshi…).\n * There are no floats stored anywhere, so you never lose a penny to rounding.\n *\n * Isomorphic — no Node built-ins. The only platform API touched is\n * `globalThis.crypto` for random ids, and that access is guarded.\n */\n\n/* -------------------------------------------------------------------------- */\n/*  Status + state machine                                                    */\n/* -------------------------------------------------------------------------- */\n\n/** Every status an order can hold across its lifecycle. */\nexport type OrderStatus =\n  | \"pending\"\n  | \"placed\"\n  | \"paid\"\n  | \"processing\"\n  | \"fulfilled\"\n  | \"shipped\"\n  | \"delivered\"\n  | \"completed\"\n  | \"on_hold\"\n  | \"cancelled\"\n  | \"refunded\";\n\n/**\n * The allowed forward transitions for each status. Terminal statuses\n * (`completed`, `cancelled`, `refunded`) map to an empty array.\n */\nexport const ORDER_TRANSITIONS: Record<OrderStatus, OrderStatus[]> = {\n  pending: [\"placed\", \"cancelled\"],\n  placed: [\"paid\", \"cancelled\", \"on_hold\"],\n  paid: [\"processing\", \"refunded\", \"on_hold\", \"cancelled\"],\n  processing: [\"fulfilled\", \"on_hold\", \"cancelled\", \"refunded\"],\n  fulfilled: [\"shipped\", \"refunded\"],\n  shipped: [\"delivered\", \"refunded\"],\n  delivered: [\"completed\", \"refunded\"],\n  on_hold: [\"placed\", \"paid\", \"processing\", \"cancelled\"],\n  completed: [],\n  cancelled: [],\n  refunded: [],\n};\n\n/** Is moving from `from` to `to` a legal transition? */\nexport function canTransition(from: OrderStatus, to: OrderStatus): boolean {\n  return ORDER_TRANSITIONS[from].includes(to);\n}\n\n/** Is `status` a terminal state (no further transitions possible)? */\nexport function isTerminal(status: OrderStatus): boolean {\n  return ORDER_TRANSITIONS[status].length === 0;\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Model                                                                      */\n/* -------------------------------------------------------------------------- */\n\n/** A single, price-snapshotted line in the order. All money in minor units. */\nexport interface OrderLine {\n  /** Stable identifier for this line. */\n  id: string;\n  /** Stock-keeping unit / catalogue reference. */\n  sku: string;\n  /** Human-readable name, snapshotted at order time. */\n  name: string;\n  /** Price per unit, in integer minor units, snapshotted at order time. */\n  unitPrice: number;\n  /** Quantity. */\n  qty: number;\n  /** Optional per-line tax rate in the range `0..1` (e.g. `0.2` = 20%). */\n  taxRate?: number;\n  /** Line total = `unitPrice * qty`, in integer minor units. */\n  total: number;\n  /** Arbitrary attached data (variant, image…). */\n  meta?: Record<string, unknown>;\n}\n\n/** A timestamped entry in the order's status history. */\nexport interface StatusEvent {\n  status: OrderStatus;\n  /** Epoch milliseconds. */\n  at: number;\n  /** Optional human note describing the change. */\n  note?: string;\n}\n\n/** Computed monetary totals for an order. All integer minor units. */\nexport interface OrderTotals {\n  subtotal: number;\n  discount: number;\n  tax: number;\n  shipping: number;\n  total: number;\n}\n\n/** The order state. Plain data — safe to `JSON.stringify` and persist. */\nexport interface Order {\n  /** Internal, opaque id. */\n  id: string;\n  /** Human-facing order number, e.g. `\"ORD-20260905-0001\"`. */\n  number: string;\n  status: OrderStatus;\n  /** ISO-4217 currency code, e.g. `\"USD\"`. Purely informational. */\n  currency: string;\n  customer?: { id?: string; name?: string; email?: string };\n  lines: OrderLine[];\n  totals: OrderTotals;\n  history: StatusEvent[];\n  /** Epoch milliseconds. */\n  createdAt: number;\n  /** Epoch milliseconds. */\n  updatedAt: number;\n  meta?: Record<string, unknown>;\n}\n\n/** Error thrown by order operations. Carries an optional machine `code`. */\nexport class OrderError extends Error {\n  code?: string;\n  constructor(message: string, code?: string) {\n    super(message);\n    this.name = \"OrderError\";\n    this.code = code;\n  }\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Convenience predicates (derived from ORDER_TRANSITIONS)                    */\n/* -------------------------------------------------------------------------- */\n\n/** Can this order still be cancelled from its current status? */\nexport function canCancel(order: Order): boolean {\n  return canTransition(order.status, \"cancelled\");\n}\n\n/** Can this order still be refunded from its current status? */\nexport function canRefund(order: Order): boolean {\n  return canTransition(order.status, \"refunded\");\n}\n\n/** Can this order transition to `shipped` from its current status? */\nexport function canShip(order: Order): boolean {\n  return canTransition(order.status, \"shipped\");\n}\n\n/** Can this order transition to `fulfilled` from its current status? */\nexport function canFulfill(order: Order): boolean {\n  return canTransition(order.status, \"fulfilled\");\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Internal helpers                                                           */\n/* -------------------------------------------------------------------------- */\n\n/** Input shape for a single line when building or amending an order. */\nexport interface OrderLineInput {\n  id?: string;\n  sku: string;\n  name?: string;\n  unitPrice: number;\n  qty: number;\n  taxRate?: number;\n  meta?: Record<string, unknown>;\n}\n\nfunction snapshotLine(input: OrderLineInput): OrderLine {\n  const qty = Math.max(0, Math.trunc(input.qty));\n  const unitPrice = Math.trunc(input.unitPrice);\n  const line: OrderLine = {\n    id: input.id ?? input.sku,\n    sku: input.sku,\n    name: input.name ?? input.sku,\n    unitPrice,\n    qty,\n    total: unitPrice * qty,\n  };\n  if (input.taxRate !== undefined) line.taxRate = input.taxRate;\n  if (input.meta !== undefined) line.meta = input.meta;\n  return line;\n}\n\nfunction computeTotals(\n  lines: OrderLine[],\n  opts: { discount?: number; shipping?: number; tax?: number },\n): OrderTotals {\n  const subtotal = lines.reduce((sum, l) => sum + l.total, 0);\n  const discount = Math.max(0, Math.trunc(opts.discount ?? 0));\n  const shipping = Math.max(0, Math.trunc(opts.shipping ?? 0));\n  const tax =\n    opts.tax !== undefined\n      ? Math.max(0, Math.trunc(opts.tax))\n      : lines.reduce((sum, l) => sum + Math.round(l.total * (l.taxRate ?? 0)), 0);\n  const total = Math.max(0, subtotal - discount + tax + shipping);\n  return { subtotal, discount, tax, shipping, total };\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Construction & transitions                                                 */\n/* -------------------------------------------------------------------------- */\n\n/** Input to {@link createOrder}. */\nexport interface CreateOrderInput {\n  lines: OrderLineInput[];\n  currency: string;\n  customer?: { id?: string; name?: string; email?: string };\n  /** Flat discount in integer minor units. */\n  discount?: number;\n  /** Flat shipping in integer minor units. */\n  shipping?: number;\n  /** Explicit tax override in minor units; otherwise derived per-line. */\n  tax?: number;\n  /** Initial status. Defaults to `\"pending\"`. */\n  status?: OrderStatus;\n  /** Epoch milliseconds for `createdAt`/first history event. Defaults to now. */\n  now?: number;\n  /** Opaque id. Defaults to a random id. */\n  id?: string;\n  /** Human-facing number. Defaults to the id. */\n  number?: string;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Build a new, immutable `Order`. Each line is **snapshotted** (its `total` is\n * computed from `unitPrice * qty`) so later catalogue price changes never\n * mutate an existing order. Totals are computed and the history is seeded with\n * one `StatusEvent` for the initial status.\n */\nexport function createOrder(input: CreateOrderInput): Order {\n  const now = input.now ?? Date.now();\n  const lines = input.lines.map(snapshotLine);\n  const totals = computeTotals(lines, input);\n  const status = input.status ?? \"pending\";\n  const id = input.id ?? randomOrderId({ prefix: \"ord\" });\n  const order: Order = {\n    id,\n    number: input.number ?? id,\n    status,\n    currency: input.currency,\n    lines,\n    totals,\n    history: [{ status, at: now }],\n    createdAt: now,\n    updatedAt: now,\n  };\n  if (input.customer !== undefined) order.customer = input.customer;\n  if (input.meta !== undefined) order.meta = input.meta;\n  return order;\n}\n\n/**\n * Transition an order to a new status. Validates via {@link canTransition} and\n * throws an `OrderError` (code `\"invalid-transition\"`) on an illegal move.\n * Returns a **new** order with the updated status, an appended history event\n * and a fresh `updatedAt`.\n */\nexport function transition(\n  order: Order,\n  to: OrderStatus,\n  opts?: { at?: number; note?: string },\n): Order {\n  if (!canTransition(order.status, to)) {\n    throw new OrderError(\n      `Cannot transition order from \"${order.status}\" to \"${to}\".`,\n      \"invalid-transition\",\n    );\n  }\n  const at = opts?.at ?? Date.now();\n  const event: StatusEvent = { status: to, at };\n  if (opts?.note !== undefined) event.note = opts.note;\n  return {\n    ...order,\n    status: to,\n    history: [...order.history, event],\n    updatedAt: at,\n  };\n}\n\n/** Statuses during which line edits are still permitted. */\nconst EDITABLE_STATUSES: OrderStatus[] = [\"pending\", \"placed\"];\n\nfunction assertEditable(order: Order): void {\n  if (!EDITABLE_STATUSES.includes(order.status)) {\n    throw new OrderError(\n      `Order is locked for editing in status \"${order.status}\"; lines can only change while pending or placed.`,\n      \"locked\",\n    );\n  }\n}\n\nfunction reprice(order: Order, lines: OrderLine[], now?: number): Order {\n  const at = now ?? Date.now();\n  return {\n    ...order,\n    lines,\n    totals: computeTotals(lines, {\n      discount: order.totals.discount,\n      shipping: order.totals.shipping,\n    }),\n    updatedAt: at,\n  };\n}\n\n/**\n * Add a line to a pre-payment order and recompute totals. Throws\n * `OrderError` (code `\"locked\"`) once the order is `paid` or beyond.\n */\nexport function addLine(order: Order, line: OrderLineInput, now?: number): Order {\n  assertEditable(order);\n  return reprice(order, [...order.lines, snapshotLine(line)], now);\n}\n\n/**\n * Remove a line by id from a pre-payment order and recompute totals. Throws\n * `OrderError` (code `\"locked\"`) once the order is `paid` or beyond.\n */\nexport function removeLine(order: Order, lineId: string, now?: number): Order {\n  assertEditable(order);\n  return reprice(\n    order,\n    order.lines.filter((l) => l.id !== lineId),\n    now,\n  );\n}\n\n/**\n * Set an absolute quantity for a line on a pre-payment order and recompute\n * totals. A `qty <= 0` removes the line. Throws `OrderError` (code `\"locked\"`)\n * once the order is `paid` or beyond.\n */\nexport function updateQty(\n  order: Order,\n  lineId: string,\n  qty: number,\n  now?: number,\n): Order {\n  assertEditable(order);\n  const next = Math.max(0, Math.trunc(qty));\n  const lines = order.lines\n    .map((l) =>\n      l.id === lineId ? { ...l, qty: next, total: l.unitPrice * next } : l,\n    )\n    .filter((l) => l.qty > 0);\n  return reprice(order, lines, now);\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Numbering                                                                  */\n/* -------------------------------------------------------------------------- */\n\nfunction pad(n: number, width: number): string {\n  const s = String(Math.abs(Math.trunc(n)));\n  return s.length >= width ? s : \"0\".repeat(width - s.length) + s;\n}\n\n/**\n * Build a deterministic, human-facing order number from a sequence.\n *\n * @example\n * orderNumber(1); // \"ORD-20260905-0001\" (with today's date)\n */\nexport function orderNumber(\n  seq: number,\n  opts?: { prefix?: string; date?: Date; pad?: number; separator?: string },\n): string {\n  const prefix = opts?.prefix ?? \"ORD\";\n  const date = opts?.date ?? new Date();\n  const width = opts?.pad ?? 4;\n  const sep = opts?.separator ?? \"-\";\n  const y = date.getFullYear();\n  const m = pad(date.getMonth() + 1, 2);\n  const d = pad(date.getDate(), 2);\n  return `${prefix}${sep}${y}${m}${d}${sep}${pad(seq, width)}`;\n}\n\nconst ID_ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Fill `out` with random bytes, preferring `crypto`, falling back to Math.random. */\nfunction randomBytes(out: Uint8Array): Uint8Array {\n  const g: { crypto?: Crypto } =\n    typeof globalThis !== \"undefined\" ? globalThis : {};\n  if (g.crypto && typeof g.crypto.getRandomValues === \"function\") {\n    g.crypto.getRandomValues(out);\n    return out;\n  }\n  // Fallback: platform has no Web Crypto. Not cryptographically strong.\n  if (typeof console !== \"undefined\" && typeof console.warn === \"function\") {\n    console.warn(\n      \"[@lacspace/order] globalThis.crypto is unavailable; falling back to Math.random for randomOrderId (not cryptographically secure).\",\n    );\n  }\n  for (let i = 0; i < out.length; i++) out[i] = Math.floor(Math.random() * 256);\n  return out;\n}\n\n/**\n * Generate a crypto-random short id, e.g. `\"ord_k3f9x1a7q2mz\"`. Uses\n * `globalThis.crypto.getRandomValues` when available, otherwise falls back to\n * `Math.random` with a warning.\n */\nexport function randomOrderId(opts?: { prefix?: string }): string {\n  const bytes = randomBytes(new Uint8Array(16));\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    out += ID_ALPHABET[bytes[i]! % ID_ALPHABET.length];\n  }\n  const prefix = opts?.prefix;\n  return prefix ? `${prefix}_${out}` : out;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,187 @@
+/**
+ * @lacspace/order — a headless order-lifecycle engine.
+ *
+ * The spine between a cart and a courier: a pure, immutable and serializable
+ * `Order` model with a state machine, order-number generation, line-item price
+ * snapshotting, and a timestamped status history. Every operation returns a
+ * brand-new `Order`; the input is never mutated, so the state plays nicely with
+ * React, Redux, Zustand, signals, or a plain JSON column in your database.
+ *
+ * All money is expressed in **integer minor units** (cents, paise, satoshi…).
+ * There are no floats stored anywhere, so you never lose a penny to rounding.
+ *
+ * Isomorphic — no Node built-ins. The only platform API touched is
+ * `globalThis.crypto` for random ids, and that access is guarded.
+ */
+/** Every status an order can hold across its lifecycle. */
+type OrderStatus = "pending" | "placed" | "paid" | "processing" | "fulfilled" | "shipped" | "delivered" | "completed" | "on_hold" | "cancelled" | "refunded";
+/**
+ * The allowed forward transitions for each status. Terminal statuses
+ * (`completed`, `cancelled`, `refunded`) map to an empty array.
+ */
+declare const ORDER_TRANSITIONS: Record<OrderStatus, OrderStatus[]>;
+/** Is moving from `from` to `to` a legal transition? */
+declare function canTransition(from: OrderStatus, to: OrderStatus): boolean;
+/** Is `status` a terminal state (no further transitions possible)? */
+declare function isTerminal(status: OrderStatus): boolean;
+/** A single, price-snapshotted line in the order. All money in minor units. */
+interface OrderLine {
+    /** Stable identifier for this line. */
+    id: string;
+    /** Stock-keeping unit / catalogue reference. */
+    sku: string;
+    /** Human-readable name, snapshotted at order time. */
+    name: string;
+    /** Price per unit, in integer minor units, snapshotted at order time. */
+    unitPrice: number;
+    /** Quantity. */
+    qty: number;
+    /** Optional per-line tax rate in the range `0..1` (e.g. `0.2` = 20%). */
+    taxRate?: number;
+    /** Line total = `unitPrice * qty`, in integer minor units. */
+    total: number;
+    /** Arbitrary attached data (variant, image…). */
+    meta?: Record<string, unknown>;
+}
+/** A timestamped entry in the order's status history. */
+interface StatusEvent {
+    status: OrderStatus;
+    /** Epoch milliseconds. */
+    at: number;
+    /** Optional human note describing the change. */
+    note?: string;
+}
+/** Computed monetary totals for an order. All integer minor units. */
+interface OrderTotals {
+    subtotal: number;
+    discount: number;
+    tax: number;
+    shipping: number;
+    total: number;
+}
+/** The order state. Plain data — safe to `JSON.stringify` and persist. */
+interface Order {
+    /** Internal, opaque id. */
+    id: string;
+    /** Human-facing order number, e.g. `"ORD-20260905-0001"`. */
+    number: string;
+    status: OrderStatus;
+    /** ISO-4217 currency code, e.g. `"USD"`. Purely informational. */
+    currency: string;
+    customer?: {
+        id?: string;
+        name?: string;
+        email?: string;
+    };
+    lines: OrderLine[];
+    totals: OrderTotals;
+    history: StatusEvent[];
+    /** Epoch milliseconds. */
+    createdAt: number;
+    /** Epoch milliseconds. */
+    updatedAt: number;
+    meta?: Record<string, unknown>;
+}
+/** Error thrown by order operations. Carries an optional machine `code`. */
+declare class OrderError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+/** Can this order still be cancelled from its current status? */
+declare function canCancel(order: Order): boolean;
+/** Can this order still be refunded from its current status? */
+declare function canRefund(order: Order): boolean;
+/** Can this order transition to `shipped` from its current status? */
+declare function canShip(order: Order): boolean;
+/** Can this order transition to `fulfilled` from its current status? */
+declare function canFulfill(order: Order): boolean;
+/** Input shape for a single line when building or amending an order. */
+interface OrderLineInput {
+    id?: string;
+    sku: string;
+    name?: string;
+    unitPrice: number;
+    qty: number;
+    taxRate?: number;
+    meta?: Record<string, unknown>;
+}
+/** Input to {@link createOrder}. */
+interface CreateOrderInput {
+    lines: OrderLineInput[];
+    currency: string;
+    customer?: {
+        id?: string;
+        name?: string;
+        email?: string;
+    };
+    /** Flat discount in integer minor units. */
+    discount?: number;
+    /** Flat shipping in integer minor units. */
+    shipping?: number;
+    /** Explicit tax override in minor units; otherwise derived per-line. */
+    tax?: number;
+    /** Initial status. Defaults to `"pending"`. */
+    status?: OrderStatus;
+    /** Epoch milliseconds for `createdAt`/first history event. Defaults to now. */
+    now?: number;
+    /** Opaque id. Defaults to a random id. */
+    id?: string;
+    /** Human-facing number. Defaults to the id. */
+    number?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Build a new, immutable `Order`. Each line is **snapshotted** (its `total` is
+ * computed from `unitPrice * qty`) so later catalogue price changes never
+ * mutate an existing order. Totals are computed and the history is seeded with
+ * one `StatusEvent` for the initial status.
+ */
+declare function createOrder(input: CreateOrderInput): Order;
+/**
+ * Transition an order to a new status. Validates via {@link canTransition} and
+ * throws an `OrderError` (code `"invalid-transition"`) on an illegal move.
+ * Returns a **new** order with the updated status, an appended history event
+ * and a fresh `updatedAt`.
+ */
+declare function transition(order: Order, to: OrderStatus, opts?: {
+    at?: number;
+    note?: string;
+}): Order;
+/**
+ * Add a line to a pre-payment order and recompute totals. Throws
+ * `OrderError` (code `"locked"`) once the order is `paid` or beyond.
+ */
+declare function addLine(order: Order, line: OrderLineInput, now?: number): Order;
+/**
+ * Remove a line by id from a pre-payment order and recompute totals. Throws
+ * `OrderError` (code `"locked"`) once the order is `paid` or beyond.
+ */
+declare function removeLine(order: Order, lineId: string, now?: number): Order;
+/**
+ * Set an absolute quantity for a line on a pre-payment order and recompute
+ * totals. A `qty <= 0` removes the line. Throws `OrderError` (code `"locked"`)
+ * once the order is `paid` or beyond.
+ */
+declare function updateQty(order: Order, lineId: string, qty: number, now?: number): Order;
+/**
+ * Build a deterministic, human-facing order number from a sequence.
+ *
+ * @example
+ * orderNumber(1); // "ORD-20260905-0001" (with today's date)
+ */
+declare function orderNumber(seq: number, opts?: {
+    prefix?: string;
+    date?: Date;
+    pad?: number;
+    separator?: string;
+}): string;
+/**
+ * Generate a crypto-random short id, e.g. `"ord_k3f9x1a7q2mz"`. Uses
+ * `globalThis.crypto.getRandomValues` when available, otherwise falls back to
+ * `Math.random` with a warning.
+ */
+declare function randomOrderId(opts?: {
+    prefix?: string;
+}): string;
+
+export { type CreateOrderInput, ORDER_TRANSITIONS, type Order, OrderError, type OrderLine, type OrderLineInput, type OrderStatus, type OrderTotals, type StatusEvent, addLine, canCancel, canFulfill, canRefund, canShip, canTransition, createOrder, isTerminal, orderNumber, randomOrderId, removeLine, transition, updateQty };

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @lacspace/order — a headless order-lifecycle engine.
+ *
+ * The spine between a cart and a courier: a pure, immutable and serializable
+ * `Order` model with a state machine, order-number generation, line-item price
+ * snapshotting, and a timestamped status history. Every operation returns a
+ * brand-new `Order`; the input is never mutated, so the state plays nicely with
+ * React, Redux, Zustand, signals, or a plain JSON column in your database.
+ *
+ * All money is expressed in **integer minor units** (cents, paise, satoshi…).
+ * There are no floats stored anywhere, so you never lose a penny to rounding.
+ *
+ * Isomorphic — no Node built-ins. The only platform API touched is
+ * `globalThis.crypto` for random ids, and that access is guarded.
+ */
+/** Every status an order can hold across its lifecycle. */
+type OrderStatus = "pending" | "placed" | "paid" | "processing" | "fulfilled" | "shipped" | "delivered" | "completed" | "on_hold" | "cancelled" | "refunded";
+/**
+ * The allowed forward transitions for each status. Terminal statuses
+ * (`completed`, `cancelled`, `refunded`) map to an empty array.
+ */
+declare const ORDER_TRANSITIONS: Record<OrderStatus, OrderStatus[]>;
+/** Is moving from `from` to `to` a legal transition? */
+declare function canTransition(from: OrderStatus, to: OrderStatus): boolean;
+/** Is `status` a terminal state (no further transitions possible)? */
+declare function isTerminal(status: OrderStatus): boolean;
+/** A single, price-snapshotted line in the order. All money in minor units. */
+interface OrderLine {
+    /** Stable identifier for this line. */
+    id: string;
+    /** Stock-keeping unit / catalogue reference. */
+    sku: string;
+    /** Human-readable name, snapshotted at order time. */
+    name: string;
+    /** Price per unit, in integer minor units, snapshotted at order time. */
+    unitPrice: number;
+    /** Quantity. */
+    qty: number;
+    /** Optional per-line tax rate in the range `0..1` (e.g. `0.2` = 20%). */
+    taxRate?: number;
+    /** Line total = `unitPrice * qty`, in integer minor units. */
+    total: number;
+    /** Arbitrary attached data (variant, image…). */
+    meta?: Record<string, unknown>;
+}
+/** A timestamped entry in the order's status history. */
+interface StatusEvent {
+    status: OrderStatus;
+    /** Epoch milliseconds. */
+    at: number;
+    /** Optional human note describing the change. */
+    note?: string;
+}
+/** Computed monetary totals for an order. All integer minor units. */
+interface OrderTotals {
+    subtotal: number;
+    discount: number;
+    tax: number;
+    shipping: number;
+    total: number;
+}
+/** The order state. Plain data — safe to `JSON.stringify` and persist. */
+interface Order {
+    /** Internal, opaque id. */
+    id: string;
+    /** Human-facing order number, e.g. `"ORD-20260905-0001"`. */
+    number: string;
+    status: OrderStatus;
+    /** ISO-4217 currency code, e.g. `"USD"`. Purely informational. */
+    currency: string;
+    customer?: {
+        id?: string;
+        name?: string;
+        email?: string;
+    };
+    lines: OrderLine[];
+    totals: OrderTotals;
+    history: StatusEvent[];
+    /** Epoch milliseconds. */
+    createdAt: number;
+    /** Epoch milliseconds. */
+    updatedAt: number;
+    meta?: Record<string, unknown>;
+}
+/** Error thrown by order operations. Carries an optional machine `code`. */
+declare class OrderError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+/** Can this order still be cancelled from its current status? */
+declare function canCancel(order: Order): boolean;
+/** Can this order still be refunded from its current status? */
+declare function canRefund(order: Order): boolean;
+/** Can this order transition to `shipped` from its current status? */
+declare function canShip(order: Order): boolean;
+/** Can this order transition to `fulfilled` from its current status? */
+declare function canFulfill(order: Order): boolean;
+/** Input shape for a single line when building or amending an order. */
+interface OrderLineInput {
+    id?: string;
+    sku: string;
+    name?: string;
+    unitPrice: number;
+    qty: number;
+    taxRate?: number;
+    meta?: Record<string, unknown>;
+}
+/** Input to {@link createOrder}. */
+interface CreateOrderInput {
+    lines: OrderLineInput[];
+    currency: string;
+    customer?: {
+        id?: string;
+        name?: string;
+        email?: string;
+    };
+    /** Flat discount in integer minor units. */
+    discount?: number;
+    /** Flat shipping in integer minor units. */
+    shipping?: number;
+    /** Explicit tax override in minor units; otherwise derived per-line. */
+    tax?: number;
+    /** Initial status. Defaults to `"pending"`. */
+    status?: OrderStatus;
+    /** Epoch milliseconds for `createdAt`/first history event. Defaults to now. */
+    now?: number;
+    /** Opaque id. Defaults to a random id. */
+    id?: string;
+    /** Human-facing number. Defaults to the id. */
+    number?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Build a new, immutable `Order`. Each line is **snapshotted** (its `total` is
+ * computed from `unitPrice * qty`) so later catalogue price changes never
+ * mutate an existing order. Totals are computed and the history is seeded with
+ * one `StatusEvent` for the initial status.
+ */
+declare function createOrder(input: CreateOrderInput): Order;
+/**
+ * Transition an order to a new status. Validates via {@link canTransition} and
+ * throws an `OrderError` (code `"invalid-transition"`) on an illegal move.
+ * Returns a **new** order with the updated status, an appended history event
+ * and a fresh `updatedAt`.
+ */
+declare function transition(order: Order, to: OrderStatus, opts?: {
+    at?: number;
+    note?: string;
+}): Order;
+/**
+ * Add a line to a pre-payment order and recompute totals. Throws
+ * `OrderError` (code `"locked"`) once the order is `paid` or beyond.
+ */
+declare function addLine(order: Order, line: OrderLineInput, now?: number): Order;
+/**
+ * Remove a line by id from a pre-payment order and recompute totals. Throws
+ * `OrderError` (code `"locked"`) once the order is `paid` or beyond.
+ */
+declare function removeLine(order: Order, lineId: string, now?: number): Order;
+/**
+ * Set an absolute quantity for a line on a pre-payment order and recompute
+ * totals. A `qty <= 0` removes the line. Throws `OrderError` (code `"locked"`)
+ * once the order is `paid` or beyond.
+ */
+declare function updateQty(order: Order, lineId: string, qty: number, now?: number): Order;
+/**
+ * Build a deterministic, human-facing order number from a sequence.
+ *
+ * @example
+ * orderNumber(1); // "ORD-20260905-0001" (with today's date)
+ */
+declare function orderNumber(seq: number, opts?: {
+    prefix?: string;
+    date?: Date;
+    pad?: number;
+    separator?: string;
+}): string;
+/**
+ * Generate a crypto-random short id, e.g. `"ord_k3f9x1a7q2mz"`. Uses
+ * `globalThis.crypto.getRandomValues` when available, otherwise falls back to
+ * `Math.random` with a warning.
+ */
+declare function randomOrderId(opts?: {
+    prefix?: string;
+}): string;
+
+export { type CreateOrderInput, ORDER_TRANSITIONS, type Order, OrderError, type OrderLine, type OrderLineInput, type OrderStatus, type OrderTotals, type StatusEvent, addLine, canCancel, canFulfill, canRefund, canShip, canTransition, createOrder, isTerminal, orderNumber, randomOrderId, removeLine, transition, updateQty };

package/dist/index.js

@@ -0,0 +1,183 @@
+// src/index.ts
+var ORDER_TRANSITIONS = {
+  pending: ["placed", "cancelled"],
+  placed: ["paid", "cancelled", "on_hold"],
+  paid: ["processing", "refunded", "on_hold", "cancelled"],
+  processing: ["fulfilled", "on_hold", "cancelled", "refunded"],
+  fulfilled: ["shipped", "refunded"],
+  shipped: ["delivered", "refunded"],
+  delivered: ["completed", "refunded"],
+  on_hold: ["placed", "paid", "processing", "cancelled"],
+  completed: [],
+  cancelled: [],
+  refunded: []
+};
+function canTransition(from, to) {
+  return ORDER_TRANSITIONS[from].includes(to);
+}
+function isTerminal(status) {
+  return ORDER_TRANSITIONS[status].length === 0;
+}
+var OrderError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "OrderError";
+    this.code = code;
+  }
+};
+function canCancel(order) {
+  return canTransition(order.status, "cancelled");
+}
+function canRefund(order) {
+  return canTransition(order.status, "refunded");
+}
+function canShip(order) {
+  return canTransition(order.status, "shipped");
+}
+function canFulfill(order) {
+  return canTransition(order.status, "fulfilled");
+}
+function snapshotLine(input) {
+  const qty = Math.max(0, Math.trunc(input.qty));
+  const unitPrice = Math.trunc(input.unitPrice);
+  const line = {
+    id: input.id ?? input.sku,
+    sku: input.sku,
+    name: input.name ?? input.sku,
+    unitPrice,
+    qty,
+    total: unitPrice * qty
+  };
+  if (input.taxRate !== void 0) line.taxRate = input.taxRate;
+  if (input.meta !== void 0) line.meta = input.meta;
+  return line;
+}
+function computeTotals(lines, opts) {
+  const subtotal = lines.reduce((sum, l) => sum + l.total, 0);
+  const discount = Math.max(0, Math.trunc(opts.discount ?? 0));
+  const shipping = Math.max(0, Math.trunc(opts.shipping ?? 0));
+  const tax = opts.tax !== void 0 ? Math.max(0, Math.trunc(opts.tax)) : lines.reduce((sum, l) => sum + Math.round(l.total * (l.taxRate ?? 0)), 0);
+  const total = Math.max(0, subtotal - discount + tax + shipping);
+  return { subtotal, discount, tax, shipping, total };
+}
+function createOrder(input) {
+  const now = input.now ?? Date.now();
+  const lines = input.lines.map(snapshotLine);
+  const totals = computeTotals(lines, input);
+  const status = input.status ?? "pending";
+  const id = input.id ?? randomOrderId({ prefix: "ord" });
+  const order = {
+    id,
+    number: input.number ?? id,
+    status,
+    currency: input.currency,
+    lines,
+    totals,
+    history: [{ status, at: now }],
+    createdAt: now,
+    updatedAt: now
+  };
+  if (input.customer !== void 0) order.customer = input.customer;
+  if (input.meta !== void 0) order.meta = input.meta;
+  return order;
+}
+function transition(order, to, opts) {
+  if (!canTransition(order.status, to)) {
+    throw new OrderError(
+      `Cannot transition order from "${order.status}" to "${to}".`,
+      "invalid-transition"
+    );
+  }
+  const at = opts?.at ?? Date.now();
+  const event = { status: to, at };
+  if (opts?.note !== void 0) event.note = opts.note;
+  return {
+    ...order,
+    status: to,
+    history: [...order.history, event],
+    updatedAt: at
+  };
+}
+var EDITABLE_STATUSES = ["pending", "placed"];
+function assertEditable(order) {
+  if (!EDITABLE_STATUSES.includes(order.status)) {
+    throw new OrderError(
+      `Order is locked for editing in status "${order.status}"; lines can only change while pending or placed.`,
+      "locked"
+    );
+  }
+}
+function reprice(order, lines, now) {
+  const at = now ?? Date.now();
+  return {
+    ...order,
+    lines,
+    totals: computeTotals(lines, {
+      discount: order.totals.discount,
+      shipping: order.totals.shipping
+    }),
+    updatedAt: at
+  };
+}
+function addLine(order, line, now) {
+  assertEditable(order);
+  return reprice(order, [...order.lines, snapshotLine(line)], now);
+}
+function removeLine(order, lineId, now) {
+  assertEditable(order);
+  return reprice(
+    order,
+    order.lines.filter((l) => l.id !== lineId),
+    now
+  );
+}
+function updateQty(order, lineId, qty, now) {
+  assertEditable(order);
+  const next = Math.max(0, Math.trunc(qty));
+  const lines = order.lines.map(
+    (l) => l.id === lineId ? { ...l, qty: next, total: l.unitPrice * next } : l
+  ).filter((l) => l.qty > 0);
+  return reprice(order, lines, now);
+}
+function pad(n, width) {
+  const s = String(Math.abs(Math.trunc(n)));
+  return s.length >= width ? s : "0".repeat(width - s.length) + s;
+}
+function orderNumber(seq, opts) {
+  const prefix = opts?.prefix ?? "ORD";
+  const date = opts?.date ?? /* @__PURE__ */ new Date();
+  const width = opts?.pad ?? 4;
+  const sep = opts?.separator ?? "-";
+  const y = date.getFullYear();
+  const m = pad(date.getMonth() + 1, 2);
+  const d = pad(date.getDate(), 2);
+  return `${prefix}${sep}${y}${m}${d}${sep}${pad(seq, width)}`;
+}
+var ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function randomBytes(out) {
+  const g = typeof globalThis !== "undefined" ? globalThis : {};
+  if (g.crypto && typeof g.crypto.getRandomValues === "function") {
+    g.crypto.getRandomValues(out);
+    return out;
+  }
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(
+      "[@lacspace/order] globalThis.crypto is unavailable; falling back to Math.random for randomOrderId (not cryptographically secure)."
+    );
+  }
+  for (let i = 0; i < out.length; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+function randomOrderId(opts) {
+  const bytes = randomBytes(new Uint8Array(16));
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += ID_ALPHABET[bytes[i] % ID_ALPHABET.length];
+  }
+  const prefix = opts?.prefix;
+  return prefix ? `${prefix}_${out}` : out;
+}
+
+export { ORDER_TRANSITIONS, OrderError, addLine, canCancel, canFulfill, canRefund, canShip, canTransition, createOrder, isTerminal, orderNumber, randomOrderId, removeLine, transition, updateQty };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/order — a headless order-lifecycle engine.\n *\n * The spine between a cart and a courier: a pure, immutable and serializable\n * `Order` model with a state machine, order-number generation, line-item price\n * snapshotting, and a timestamped status history. Every operation returns a\n * brand-new `Order`; the input is never mutated, so the state plays nicely with\n * React, Redux, Zustand, signals, or a plain JSON column in your database.\n *\n * All money is expressed in **integer minor units** (cents, paise, satoshi…).\n * There are no floats stored anywhere, so you never lose a penny to rounding.\n *\n * Isomorphic — no Node built-ins. The only platform API touched is\n * `globalThis.crypto` for random ids, and that access is guarded.\n */\n\n/* -------------------------------------------------------------------------- */\n/*  Status + state machine                                                    */\n/* -------------------------------------------------------------------------- */\n\n/** Every status an order can hold across its lifecycle. */\nexport type OrderStatus =\n  | \"pending\"\n  | \"placed\"\n  | \"paid\"\n  | \"processing\"\n  | \"fulfilled\"\n  | \"shipped\"\n  | \"delivered\"\n  | \"completed\"\n  | \"on_hold\"\n  | \"cancelled\"\n  | \"refunded\";\n\n/**\n * The allowed forward transitions for each status. Terminal statuses\n * (`completed`, `cancelled`, `refunded`) map to an empty array.\n */\nexport const ORDER_TRANSITIONS: Record<OrderStatus, OrderStatus[]> = {\n  pending: [\"placed\", \"cancelled\"],\n  placed: [\"paid\", \"cancelled\", \"on_hold\"],\n  paid: [\"processing\", \"refunded\", \"on_hold\", \"cancelled\"],\n  processing: [\"fulfilled\", \"on_hold\", \"cancelled\", \"refunded\"],\n  fulfilled: [\"shipped\", \"refunded\"],\n  shipped: [\"delivered\", \"refunded\"],\n  delivered: [\"completed\", \"refunded\"],\n  on_hold: [\"placed\", \"paid\", \"processing\", \"cancelled\"],\n  completed: [],\n  cancelled: [],\n  refunded: [],\n};\n\n/** Is moving from `from` to `to` a legal transition? */\nexport function canTransition(from: OrderStatus, to: OrderStatus): boolean {\n  return ORDER_TRANSITIONS[from].includes(to);\n}\n\n/** Is `status` a terminal state (no further transitions possible)? */\nexport function isTerminal(status: OrderStatus): boolean {\n  return ORDER_TRANSITIONS[status].length === 0;\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Model                                                                      */\n/* -------------------------------------------------------------------------- */\n\n/** A single, price-snapshotted line in the order. All money in minor units. */\nexport interface OrderLine {\n  /** Stable identifier for this line. */\n  id: string;\n  /** Stock-keeping unit / catalogue reference. */\n  sku: string;\n  /** Human-readable name, snapshotted at order time. */\n  name: string;\n  /** Price per unit, in integer minor units, snapshotted at order time. */\n  unitPrice: number;\n  /** Quantity. */\n  qty: number;\n  /** Optional per-line tax rate in the range `0..1` (e.g. `0.2` = 20%). */\n  taxRate?: number;\n  /** Line total = `unitPrice * qty`, in integer minor units. */\n  total: number;\n  /** Arbitrary attached data (variant, image…). */\n  meta?: Record<string, unknown>;\n}\n\n/** A timestamped entry in the order's status history. */\nexport interface StatusEvent {\n  status: OrderStatus;\n  /** Epoch milliseconds. */\n  at: number;\n  /** Optional human note describing the change. */\n  note?: string;\n}\n\n/** Computed monetary totals for an order. All integer minor units. */\nexport interface OrderTotals {\n  subtotal: number;\n  discount: number;\n  tax: number;\n  shipping: number;\n  total: number;\n}\n\n/** The order state. Plain data — safe to `JSON.stringify` and persist. */\nexport interface Order {\n  /** Internal, opaque id. */\n  id: string;\n  /** Human-facing order number, e.g. `\"ORD-20260905-0001\"`. */\n  number: string;\n  status: OrderStatus;\n  /** ISO-4217 currency code, e.g. `\"USD\"`. Purely informational. */\n  currency: string;\n  customer?: { id?: string; name?: string; email?: string };\n  lines: OrderLine[];\n  totals: OrderTotals;\n  history: StatusEvent[];\n  /** Epoch milliseconds. */\n  createdAt: number;\n  /** Epoch milliseconds. */\n  updatedAt: number;\n  meta?: Record<string, unknown>;\n}\n\n/** Error thrown by order operations. Carries an optional machine `code`. */\nexport class OrderError extends Error {\n  code?: string;\n  constructor(message: string, code?: string) {\n    super(message);\n    this.name = \"OrderError\";\n    this.code = code;\n  }\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Convenience predicates (derived from ORDER_TRANSITIONS)                    */\n/* -------------------------------------------------------------------------- */\n\n/** Can this order still be cancelled from its current status? */\nexport function canCancel(order: Order): boolean {\n  return canTransition(order.status, \"cancelled\");\n}\n\n/** Can this order still be refunded from its current status? */\nexport function canRefund(order: Order): boolean {\n  return canTransition(order.status, \"refunded\");\n}\n\n/** Can this order transition to `shipped` from its current status? */\nexport function canShip(order: Order): boolean {\n  return canTransition(order.status, \"shipped\");\n}\n\n/** Can this order transition to `fulfilled` from its current status? */\nexport function canFulfill(order: Order): boolean {\n  return canTransition(order.status, \"fulfilled\");\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Internal helpers                                                           */\n/* -------------------------------------------------------------------------- */\n\n/** Input shape for a single line when building or amending an order. */\nexport interface OrderLineInput {\n  id?: string;\n  sku: string;\n  name?: string;\n  unitPrice: number;\n  qty: number;\n  taxRate?: number;\n  meta?: Record<string, unknown>;\n}\n\nfunction snapshotLine(input: OrderLineInput): OrderLine {\n  const qty = Math.max(0, Math.trunc(input.qty));\n  const unitPrice = Math.trunc(input.unitPrice);\n  const line: OrderLine = {\n    id: input.id ?? input.sku,\n    sku: input.sku,\n    name: input.name ?? input.sku,\n    unitPrice,\n    qty,\n    total: unitPrice * qty,\n  };\n  if (input.taxRate !== undefined) line.taxRate = input.taxRate;\n  if (input.meta !== undefined) line.meta = input.meta;\n  return line;\n}\n\nfunction computeTotals(\n  lines: OrderLine[],\n  opts: { discount?: number; shipping?: number; tax?: number },\n): OrderTotals {\n  const subtotal = lines.reduce((sum, l) => sum + l.total, 0);\n  const discount = Math.max(0, Math.trunc(opts.discount ?? 0));\n  const shipping = Math.max(0, Math.trunc(opts.shipping ?? 0));\n  const tax =\n    opts.tax !== undefined\n      ? Math.max(0, Math.trunc(opts.tax))\n      : lines.reduce((sum, l) => sum + Math.round(l.total * (l.taxRate ?? 0)), 0);\n  const total = Math.max(0, subtotal - discount + tax + shipping);\n  return { subtotal, discount, tax, shipping, total };\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Construction & transitions                                                 */\n/* -------------------------------------------------------------------------- */\n\n/** Input to {@link createOrder}. */\nexport interface CreateOrderInput {\n  lines: OrderLineInput[];\n  currency: string;\n  customer?: { id?: string; name?: string; email?: string };\n  /** Flat discount in integer minor units. */\n  discount?: number;\n  /** Flat shipping in integer minor units. */\n  shipping?: number;\n  /** Explicit tax override in minor units; otherwise derived per-line. */\n  tax?: number;\n  /** Initial status. Defaults to `\"pending\"`. */\n  status?: OrderStatus;\n  /** Epoch milliseconds for `createdAt`/first history event. Defaults to now. */\n  now?: number;\n  /** Opaque id. Defaults to a random id. */\n  id?: string;\n  /** Human-facing number. Defaults to the id. */\n  number?: string;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Build a new, immutable `Order`. Each line is **snapshotted** (its `total` is\n * computed from `unitPrice * qty`) so later catalogue price changes never\n * mutate an existing order. Totals are computed and the history is seeded with\n * one `StatusEvent` for the initial status.\n */\nexport function createOrder(input: CreateOrderInput): Order {\n  const now = input.now ?? Date.now();\n  const lines = input.lines.map(snapshotLine);\n  const totals = computeTotals(lines, input);\n  const status = input.status ?? \"pending\";\n  const id = input.id ?? randomOrderId({ prefix: \"ord\" });\n  const order: Order = {\n    id,\n    number: input.number ?? id,\n    status,\n    currency: input.currency,\n    lines,\n    totals,\n    history: [{ status, at: now }],\n    createdAt: now,\n    updatedAt: now,\n  };\n  if (input.customer !== undefined) order.customer = input.customer;\n  if (input.meta !== undefined) order.meta = input.meta;\n  return order;\n}\n\n/**\n * Transition an order to a new status. Validates via {@link canTransition} and\n * throws an `OrderError` (code `\"invalid-transition\"`) on an illegal move.\n * Returns a **new** order with the updated status, an appended history event\n * and a fresh `updatedAt`.\n */\nexport function transition(\n  order: Order,\n  to: OrderStatus,\n  opts?: { at?: number; note?: string },\n): Order {\n  if (!canTransition(order.status, to)) {\n    throw new OrderError(\n      `Cannot transition order from \"${order.status}\" to \"${to}\".`,\n      \"invalid-transition\",\n    );\n  }\n  const at = opts?.at ?? Date.now();\n  const event: StatusEvent = { status: to, at };\n  if (opts?.note !== undefined) event.note = opts.note;\n  return {\n    ...order,\n    status: to,\n    history: [...order.history, event],\n    updatedAt: at,\n  };\n}\n\n/** Statuses during which line edits are still permitted. */\nconst EDITABLE_STATUSES: OrderStatus[] = [\"pending\", \"placed\"];\n\nfunction assertEditable(order: Order): void {\n  if (!EDITABLE_STATUSES.includes(order.status)) {\n    throw new OrderError(\n      `Order is locked for editing in status \"${order.status}\"; lines can only change while pending or placed.`,\n      \"locked\",\n    );\n  }\n}\n\nfunction reprice(order: Order, lines: OrderLine[], now?: number): Order {\n  const at = now ?? Date.now();\n  return {\n    ...order,\n    lines,\n    totals: computeTotals(lines, {\n      discount: order.totals.discount,\n      shipping: order.totals.shipping,\n    }),\n    updatedAt: at,\n  };\n}\n\n/**\n * Add a line to a pre-payment order and recompute totals. Throws\n * `OrderError` (code `\"locked\"`) once the order is `paid` or beyond.\n */\nexport function addLine(order: Order, line: OrderLineInput, now?: number): Order {\n  assertEditable(order);\n  return reprice(order, [...order.lines, snapshotLine(line)], now);\n}\n\n/**\n * Remove a line by id from a pre-payment order and recompute totals. Throws\n * `OrderError` (code `\"locked\"`) once the order is `paid` or beyond.\n */\nexport function removeLine(order: Order, lineId: string, now?: number): Order {\n  assertEditable(order);\n  return reprice(\n    order,\n    order.lines.filter((l) => l.id !== lineId),\n    now,\n  );\n}\n\n/**\n * Set an absolute quantity for a line on a pre-payment order and recompute\n * totals. A `qty <= 0` removes the line. Throws `OrderError` (code `\"locked\"`)\n * once the order is `paid` or beyond.\n */\nexport function updateQty(\n  order: Order,\n  lineId: string,\n  qty: number,\n  now?: number,\n): Order {\n  assertEditable(order);\n  const next = Math.max(0, Math.trunc(qty));\n  const lines = order.lines\n    .map((l) =>\n      l.id === lineId ? { ...l, qty: next, total: l.unitPrice * next } : l,\n    )\n    .filter((l) => l.qty > 0);\n  return reprice(order, lines, now);\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Numbering                                                                  */\n/* -------------------------------------------------------------------------- */\n\nfunction pad(n: number, width: number): string {\n  const s = String(Math.abs(Math.trunc(n)));\n  return s.length >= width ? s : \"0\".repeat(width - s.length) + s;\n}\n\n/**\n * Build a deterministic, human-facing order number from a sequence.\n *\n * @example\n * orderNumber(1); // \"ORD-20260905-0001\" (with today's date)\n */\nexport function orderNumber(\n  seq: number,\n  opts?: { prefix?: string; date?: Date; pad?: number; separator?: string },\n): string {\n  const prefix = opts?.prefix ?? \"ORD\";\n  const date = opts?.date ?? new Date();\n  const width = opts?.pad ?? 4;\n  const sep = opts?.separator ?? \"-\";\n  const y = date.getFullYear();\n  const m = pad(date.getMonth() + 1, 2);\n  const d = pad(date.getDate(), 2);\n  return `${prefix}${sep}${y}${m}${d}${sep}${pad(seq, width)}`;\n}\n\nconst ID_ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Fill `out` with random bytes, preferring `crypto`, falling back to Math.random. */\nfunction randomBytes(out: Uint8Array): Uint8Array {\n  const g: { crypto?: Crypto } =\n    typeof globalThis !== \"undefined\" ? globalThis : {};\n  if (g.crypto && typeof g.crypto.getRandomValues === \"function\") {\n    g.crypto.getRandomValues(out);\n    return out;\n  }\n  // Fallback: platform has no Web Crypto. Not cryptographically strong.\n  if (typeof console !== \"undefined\" && typeof console.warn === \"function\") {\n    console.warn(\n      \"[@lacspace/order] globalThis.crypto is unavailable; falling back to Math.random for randomOrderId (not cryptographically secure).\",\n    );\n  }\n  for (let i = 0; i < out.length; i++) out[i] = Math.floor(Math.random() * 256);\n  return out;\n}\n\n/**\n * Generate a crypto-random short id, e.g. `\"ord_k3f9x1a7q2mz\"`. Uses\n * `globalThis.crypto.getRandomValues` when available, otherwise falls back to\n * `Math.random` with a warning.\n */\nexport function randomOrderId(opts?: { prefix?: string }): string {\n  const bytes = randomBytes(new Uint8Array(16));\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    out += ID_ALPHABET[bytes[i]! % ID_ALPHABET.length];\n  }\n  const prefix = opts?.prefix;\n  return prefix ? `${prefix}_${out}` : out;\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/order",
+  "version": "1.0.0",
+  "description": "Headless order-lifecycle engine — an immutable order model with a state machine, order-number generation, line-item price snapshotting and timestamped status history. Integer minor units, zero-dependency, isomorphic (Node, edge, browser).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "order",
+    "order-management",
+    "ecommerce",
+    "state-machine",
+    "order-status",
+    "checkout",
+    "fulfillment",
+    "minor-units",
+    "headless",
+    "immutable",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/order",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "order"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}