@zappie/sdk 0.1.0 → 0.1.2

package/dist/cart/index.js

@@ -0,0 +1,768 @@
+// src/cart/index.ts
+import { asError, ZappieError } from "../errors.js";
+import { multiplyMoney, sumMoney } from "../internal/money-math.js";
+import { money } from "../money.js";
+import { ZappieCartError } from "./errors.js";
+import { estimateUnitPrice } from "./price.js";
+import { freezeLine, lineInput, reconcile } from "./reconcile.js";
+import { createCartStorage, parseCart, validFulfilment } from "./storage.js";
+import {
+  issue,
+  normalizeInput,
+  resolveVariant,
+  validateLine
+} from "./validate.js";
+import { wireFulfilment, wireLine } from "./wire.js";
+var EMPTY_CART = Object.freeze({
+  lines: Object.freeze([]),
+  count: 0,
+  subtotal: null,
+  fulfilment: null,
+  promoCode: null,
+  state: { status: "ready" },
+  issues: Object.freeze([]),
+  isHydrated: false
+});
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+  }
+  return value;
+}
+function identity(input) {
+  return JSON.stringify([
+    input.itemId,
+    input.menuId,
+    input.variantId,
+    input.note ?? "",
+    [...input.choices ?? []].sort(
+      (a, b) => a.groupId.localeCompare(b.groupId) || a.choiceId.localeCompare(b.choiceId)
+    ),
+    Object.entries(input.inputs ?? {}).sort(([a], [b]) => a.localeCompare(b))
+  ]);
+}
+function createCart(deps) {
+  const { config, menu: menus, store, events } = deps;
+  const ttl = config.cart?.ttl ?? 7 * 24 * 60 * 60 * 1e3;
+  if (!Number.isFinite(ttl) || ttl <= 0) {
+    throw new ZappieError(
+      "invalid_request",
+      "Cart ttl must be positive milliseconds"
+    );
+  }
+  let snapshot = EMPTY_CART;
+  let menu;
+  let branch;
+  let selected = config.branch;
+  let updatedAt = 0;
+  let timer;
+  let revision = 0;
+  let quoteRevision = 0;
+  let moveSequence = 0;
+  let refreshSequence = 0;
+  let mounted = 0;
+  let detach;
+  let hydration;
+  let lifecycle = 0;
+  let legacy;
+  const listeners = /* @__PURE__ */ new Set();
+  const prefix = `zappie:cart:v1:${config.store}:`;
+  const scope = config.cart?.storageScope;
+  const keyFor = (id) => `${prefix}${id}${scope ? `:${scope}` : ""}`;
+  const key = () => keyFor(branch.id);
+  const storage = createCartStorage(
+    config.storage,
+    (message) => events.emit("warning", { message })
+  );
+  const readSaved = (id) => {
+    let raw = storage.read(keyFor(id));
+    if (raw === null && scope) {
+      raw = storage.read(prefix + id);
+      if (raw !== null) {
+        storage.remove(prefix + id);
+        storage.write(keyFor(id), raw);
+      }
+    }
+    return raw;
+  };
+  let quotes;
+  let loadingQuotes;
+  const quoteClient = () => loadingQuotes ?? (loadingQuotes = import("./quote-client.js").then(
+    ({ createQuoteClient }) => quotes = createQuoteClient(deps.transport, deps.context),
+    (error) => {
+      loadingQuotes = void 0;
+      throw error;
+    }
+  ));
+  const publish = (patch) => {
+    snapshot = deepFreeze({
+      ...snapshot,
+      ...patch,
+      branchId: branch?.id
+    });
+    for (const fn of [...listeners]) {
+      try {
+        fn();
+      } catch (error) {
+        events.emit("error", { error: asError(error) });
+      }
+    }
+  };
+  const attention = (issues, quote) => issues.some((i) => i.severity !== "info") ? { status: "needs_attention", issues, ...quote ? { quote } : {} } : quote ? { status: "quoted", quote } : { status: "ready" };
+  const cancel = () => {
+    revision++;
+    quoteRevision++;
+    clearTimeout(timer);
+    quotes?.cancel();
+  };
+  const persist = () => {
+    const value = {
+      v: 1,
+      lines: snapshot.lines.map((line) => ({
+        ...lineInput(line),
+        id: line.id,
+        name: line.name,
+        addedAt: line.addedAt,
+        unitPrice: line.unitPrice
+      })),
+      fulfilment: snapshot.fulfilment,
+      promoCode: snapshot.promoCode,
+      menuVersion: menu.version,
+      updatedAt
+    };
+    storage.write(key(), JSON.stringify(value));
+  };
+  const schedule = () => {
+    clearTimeout(timer);
+    if (snapshot.lines.length) {
+      timer = setTimeout(() => {
+        void cart.quote().catch(() => {
+        });
+      }, 300);
+    }
+  };
+  const recompute = (lines, pending = snapshot.issues.filter((i) => i.source === "local"), patch = {}) => {
+    const currency = store.peek().currency;
+    const result = reconcile(lines, menu, branch, currency, pending);
+    const subtotal = result.priced ? sumMoney(
+      result.lines.map((l) => l.lineSubtotal),
+      money(0, currency)
+    ) : null;
+    publish({
+      ...patch,
+      lines: result.lines,
+      count: result.lines.reduce((n, l) => n + l.quantity, 0),
+      subtotal,
+      issues: result.issues,
+      state: attention(result.issues)
+    });
+    for (const i of result.issues) {
+      events.emit("cart_issue", { code: i.code });
+    }
+  };
+  const changed = (lines = snapshot.lines, patch = {}) => {
+    cancel();
+    recompute(lines, void 0, patch);
+    updatedAt = Date.now();
+    persist();
+    schedule();
+  };
+  const choose = (value) => {
+    const found = store.peek()?.branches.find((b) => b.id === value.branchId);
+    if (!found) {
+      throw new ZappieError(
+        "branch_not_found",
+        "Load the storefront branch before using its cart"
+      );
+    }
+    menu = value;
+    branch = found;
+    selected = found.id;
+  };
+  const load = (raw, writeBack = true) => {
+    cancel();
+    let saved;
+    try {
+      saved = raw ? parseCart(raw) : void 0;
+      if (saved && Date.now() - saved.updatedAt > ttl) {
+        saved = void 0;
+        storage.remove(key());
+        events.emit("cart_expired", { branchId: branch.id });
+      }
+    } catch {
+      storage.remove(key());
+      storage.warning("Invalid saved cart discarded");
+    }
+    updatedAt = saved?.updatedAt ?? Date.now();
+    const idle = Date.now() - updatedAt;
+    let fulfilment = saved?.fulfilment ?? null;
+    if (fulfilment?.branchId !== branch.id || idle > 864e5 && fulfilment.type === "delivery") {
+      fulfilment = null;
+    }
+    if (fulfilment && "scheduledFor" in fulfilment && fulfilment.scheduledFor && Date.parse(fulfilment.scheduledFor) < Date.now()) {
+      fulfilment = { ...fulfilment };
+      delete fulfilment.scheduledFor;
+    }
+    const lines = (saved?.lines ?? []).map((line) => ({
+      ...line,
+      ...idle > 864e5 ? { inputs: {} } : {}
+    }));
+    const result = reconcile(lines, menu, branch, store.peek().currency);
+    recompute(result.lines, result.issues, {
+      fulfilment,
+      promoCode: saved?.promoCode ?? null,
+      isHydrated: true
+    });
+    if (raw !== null && writeBack) {
+      persist();
+    }
+    storage.sweep(prefix, key(), ttl);
+  };
+  const ensure = () => {
+    const id = branch?.id ?? store.peek()?.branches.find(
+      (b) => b.id === selected || b.slug === selected || !selected && b.isDefault
+    )?.id ?? (!selected ? store.peek()?.branches[0]?.id : void 0);
+    if (snapshot.isHydrated) {
+      return;
+    }
+    const loaded = menu ?? (id ? deps.workingSet.peek(id, []) : void 0);
+    if (!loaded || !store.peek()) {
+      throw new ZappieError(
+        "invalid_request",
+        "Load the store and menu before editing the cart"
+      );
+    }
+    choose(loaded);
+    const raw = readSaved(branch.id);
+    let migrated = [];
+    if (raw === null && legacy) {
+      try {
+        migrated = legacy(storage.read);
+      } catch {
+        storage.warning("Invalid legacy cart discarded");
+      }
+    }
+    load(raw);
+    if (raw === null && legacy) {
+      persist();
+    }
+    for (const input of migrated.slice(0, 100)) {
+      try {
+        cart.add(input.itemId, input);
+      } catch {
+        events.emit("cart_issue", { code: "item_unavailable" });
+      }
+    }
+  };
+  const refresh = async () => {
+    const id = branch?.id;
+    const seq = moveSequence;
+    const request = ++refreshSequence;
+    const rev = revision;
+    if (!id || !menu) {
+      return;
+    }
+    if (!snapshot.lines.length) {
+      return;
+    }
+    if (menu.completeness !== "partial") {
+      const version = await deps.transport.getMenuVersion({
+        ...deps.context(),
+        branchId: id
+      });
+      if (version.version === menu.version) {
+        return;
+      }
+    }
+    const value = await deps.workingSet.read(
+      id,
+      snapshot.lines.map((l) => l.itemId),
+      true
+    );
+    if (seq !== moveSequence || request !== refreshSequence || rev !== revision || JSON.stringify(value) === JSON.stringify(menu)) {
+      return;
+    }
+    menu = value;
+    cancel();
+    recompute(snapshot.lines);
+    persist();
+    schedule();
+  };
+  const current = (itemId) => {
+    const candidate = deps.workingSet.peek(branch.id, [
+      ...snapshot.lines.map((l) => l.itemId),
+      itemId
+    ]);
+    if (candidate.items[itemId]) {
+      menu = candidate;
+    }
+  };
+  const validated = (raw, id, addedAt) => {
+    current(raw.itemId);
+    const item = Object.hasOwn(menu.items, raw.itemId) ? menu.items[raw.itemId] : void 0;
+    const problems = validateLine(item, raw, { menu, branch });
+    if (problems.length || !item) {
+      throw new ZappieCartError(problems);
+    }
+    const input = normalizeInput(item, raw);
+    const variant = resolveVariant(item, input);
+    const choices = (input.choices ?? []).map((c) => ({
+      ...c,
+      quantity: c.quantity ?? 1
+    }));
+    const unitPrice = estimateUnitPrice(item, {
+      choices,
+      variantId: variant.id
+    });
+    return freezeLine({
+      id: id ?? `line_${Array.from(globalThis.crypto.getRandomValues(new Uint8Array(10)), (byte) => "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz-"[byte & 63]).join("")}`,
+      itemId: item.id,
+      ...input.menuId !== void 0 ? { menuId: input.menuId } : {},
+      name: item.name,
+      quantity: input.quantity,
+      choices,
+      inputs: input.inputs ?? {},
+      variantId: variant.id,
+      ...input.note !== void 0 ? { note: input.note } : {},
+      unitPrice,
+      lineSubtotal: multiplyMoney(unitPrice, input.quantity),
+      addedAt: addedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  const offMenu = events.on("menu:updated", ({ branchId, version }) => {
+    if (branch?.id === branchId) {
+      const value = menus.peek(branchId);
+      if (value && value.completeness !== "partial" && value.version === version && value.version !== menu?.version) {
+        refreshSequence++;
+        menu = value;
+        cancel();
+        recompute(snapshot.lines);
+        persist();
+        schedule();
+      }
+    }
+  });
+  const cart = {
+    get branchId() {
+      return snapshot.branchId;
+    },
+    get lines() {
+      return snapshot.lines;
+    },
+    get count() {
+      return snapshot.count;
+    },
+    get subtotal() {
+      return snapshot.subtotal;
+    },
+    get fulfilment() {
+      return snapshot.fulfilment;
+    },
+    get promoCode() {
+      return snapshot.promoCode;
+    },
+    get state() {
+      return snapshot.state;
+    },
+    get issues() {
+      return snapshot.issues;
+    },
+    get isHydrated() {
+      return snapshot.isHydrated;
+    },
+    getSnapshot: () => snapshot,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    async hydrate() {
+      if (snapshot.isHydrated) {
+        return refresh();
+      }
+      const life = lifecycle;
+      hydration ?? (hydration = (async () => {
+        const value = await store.get();
+        const target = value.branches.find(
+          (b) => b.id === selected || b.slug === selected
+        ) ?? (!selected ? value.branches.find((b) => b.isDefault) ?? value.branches[0] : void 0);
+        if (!target) {
+          throw new ZappieError(
+            "branch_not_found",
+            "Cart branch is unavailable"
+          );
+        }
+        let inputs = snapshot.lines;
+        if (!snapshot.isHydrated) {
+          const raw = readSaved(target.id);
+          try {
+            const saved = raw ? parseCart(raw) : void 0;
+            inputs = saved && Date.now() - saved.updatedAt <= ttl ? saved.lines : raw === null ? legacy?.(storage.read) ?? [] : [];
+          } catch {
+            inputs = [];
+          }
+        }
+        const loaded = await deps.workingSet.read(
+          target.id,
+          inputs.map((l) => l.itemId)
+        );
+        if (life !== lifecycle) {
+          return;
+        }
+        choose(loaded);
+        ensure();
+        if (loaded.completeness !== "partial") {
+          await refresh();
+        }
+      })().finally(() => {
+        hydration = void 0;
+      }));
+      return hydration;
+    },
+    mount() {
+      mounted++;
+      if (!detach && typeof window !== "undefined") {
+        const onStorage = (event) => {
+          if (branch && event.key === key() && storage.accepts(event.storageArea)) {
+            const raw = event.newValue;
+            let ids;
+            try {
+              ids = raw ? parseCart(raw).lines.map((l) => l.itemId) : [];
+            } catch {
+              load(raw, false);
+              return;
+            }
+            const cached = deps.workingSet.peek(branch.id, ids);
+            if (cached.completeness !== "partial" || ids.every((id) => cached.items[id])) {
+              menu = cached;
+              load(raw, false);
+              schedule();
+              return;
+            }
+            const rev = revision;
+            const request = ++refreshSequence;
+            const life = lifecycle;
+            void deps.workingSet.read(branch.id, ids).then((value) => {
+              if (life === lifecycle && rev === revision && request === refreshSequence) {
+                menu = value;
+                load(raw, false);
+                schedule();
+              }
+            }).catch(
+              (error) => events.emit("error", { error: asError(error) })
+            );
+          }
+        };
+        const onFocus = () => {
+          void refresh().catch(
+            (error) => events.emit("error", { error: asError(error) })
+          );
+        };
+        window.addEventListener("storage", onStorage);
+        window.addEventListener("focus", onFocus);
+        detach = () => {
+          window.removeEventListener("storage", onStorage);
+          window.removeEventListener("focus", onFocus);
+        };
+      }
+      if (mounted === 1) {
+        void cart.hydrate().catch(
+          (error) => events.emit("error", { error: asError(error) })
+        );
+      }
+      let active = true;
+      return () => {
+        if (active) {
+          active = false;
+          mounted--;
+          if (mounted === 0) {
+            detach?.();
+            detach = void 0;
+            cancel();
+          }
+        }
+      };
+    },
+    dispose() {
+      lifecycle++;
+      moveSequence++;
+      offMenu();
+      cancel();
+      detach?.();
+      detach = void 0;
+      listeners.clear();
+    },
+    validate(input) {
+      ensure();
+      current(input.itemId);
+      const problems = validateLine(
+        Object.hasOwn(menu.items, input.itemId) ? menu.items[input.itemId] : void 0,
+        input,
+        { menu, branch }
+      );
+      return problems.length ? { ok: false, issues: problems } : { ok: true };
+    },
+    add(item, input = {}) {
+      ensure();
+      let line = validated({
+        ...input,
+        itemId: typeof item === "string" ? item : item.id
+      });
+      const existing = snapshot.lines.find(
+        (l) => identity(lineInput(l)) === identity(lineInput(line))
+      );
+      if (existing) {
+        line = validated(
+          { ...lineInput(line), quantity: existing.quantity + line.quantity },
+          existing.id,
+          existing.addedAt
+        );
+      } else if (snapshot.lines.length >= 100) {
+        throw new ZappieCartError([
+          issue("quantity_limit", "A cart can contain at most 100 lines")
+        ]);
+      }
+      changed(
+        existing ? snapshot.lines.map((l) => l.id === existing.id ? line : l) : [...snapshot.lines, line]
+      );
+      events.emit("add_to_cart", {
+        itemId: line.itemId,
+        quantity: line.quantity - (existing?.quantity ?? 0),
+        value: multiplyMoney(
+          line.unitPrice,
+          line.quantity - (existing?.quantity ?? 0)
+        )
+      });
+      return line;
+    },
+    update(lineId, patch) {
+      ensure();
+      const old = snapshot.lines.find((l) => l.id === lineId);
+      if (!old) {
+        throw new ZappieCartError([
+          issue("item_not_found", "Cart line not found")
+        ]);
+      }
+      const input = { ...lineInput(old), ...patch };
+      if (patch.choices && !patch.variantId) {
+        delete input.variantId;
+      }
+      let line = validated(input, old.id, old.addedAt);
+      const duplicate = snapshot.lines.find(
+        (l) => l.id !== lineId && identity(lineInput(l)) === identity(lineInput(line))
+      );
+      if (duplicate) {
+        line = validated(
+          { ...lineInput(line), quantity: line.quantity + duplicate.quantity },
+          old.id,
+          old.addedAt
+        );
+      }
+      changed(
+        snapshot.lines.filter((l) => l.id !== duplicate?.id).map((l) => l.id === lineId ? line : l)
+      );
+      events.emit("update_cart_line", {
+        lineId,
+        itemId: line.itemId,
+        quantity: line.quantity
+      });
+      return line;
+    },
+    remove(lineId) {
+      ensure();
+      const line = snapshot.lines.find((l) => l.id === lineId);
+      changed(snapshot.lines.filter((l) => l.id !== lineId));
+      if (line) {
+        events.emit("remove_from_cart", {
+          itemId: line.itemId,
+          quantity: line.quantity,
+          value: line.lineSubtotal
+        });
+      }
+    },
+    clear() {
+      ensure();
+      changed([], { fulfilment: null, promoCode: null });
+    },
+    setFulfilment(value) {
+      ensure();
+      if (!validFulfilment(value) || value.branchId !== branch.id) {
+        throw new ZappieCartError([
+          issue(
+            "fulfilment_unavailable",
+            "Select fulfilment for the cart's branch"
+          )
+        ]);
+      }
+      changed(snapshot.lines, { fulfilment: structuredClone(value) });
+    },
+    setPromoCode(code) {
+      ensure();
+      changed(snapshot.lines, { promoCode: code?.trim() || null });
+    },
+    async moveTo(branchId) {
+      ensure();
+      const seq = ++moveSequence;
+      cancel();
+      publish({ state: attention(snapshot.issues) });
+      const value = await deps.workingSet.read(
+        branchId,
+        snapshot.lines.map((l) => l.itemId)
+      );
+      if (seq !== moveSequence) {
+        return;
+      }
+      const oldKey = key();
+      const oldLines = snapshot.lines;
+      choose(value);
+      const kept = oldLines.filter(
+        (line) => !validateLine(value.items[line.itemId], lineInput(line), {
+          menu: value,
+          branch
+        }).length
+      );
+      changed(kept, { fulfilment: null, promoCode: null });
+      const dropped = oldLines.filter((line) => !kept.includes(line)).map((line) => ({
+        ...issue(
+          "item_unavailable",
+          `${line.name} is unavailable at this branch`
+        ),
+        severity: "warning",
+        lineId: line.id
+      }));
+      const issues = [...snapshot.issues, ...dropped];
+      publish({ issues, state: attention(issues) });
+      if (oldKey !== key()) {
+        storage.remove(oldKey);
+      }
+    },
+    async quote(opts = {}) {
+      ensure();
+      clearTimeout(timer);
+      if (opts.force) {
+        events.emit("view_cart", {});
+      }
+      const body = {
+        branch_id: branch.id,
+        lines: snapshot.lines.map(wireLine),
+        ...snapshot.fulfilment ? { fulfilment: wireFulfilment(snapshot.fulfilment) } : {},
+        ...snapshot.promoCode ? { promo_code: snapshot.promoCode } : {},
+        menu_version: menu.version
+      };
+      const seq = revision;
+      const attempt = ++quoteRevision;
+      publish({ state: { status: "quoting" } });
+      try {
+        const client = await quoteClient();
+        return await client.get(body, opts.force ?? false, (quote) => {
+          if (seq !== revision) {
+            return;
+          }
+          const local = snapshot.issues.filter((i) => i.source === "local");
+          const remote = quote.issues.filter(
+            (q) => !local.some(
+              (l) => l.code === q.code && l.lineId === q.lineId && l.groupId === q.groupId
+            )
+          );
+          const issues = [...local, ...remote];
+          publish({ issues, state: attention(issues, quote) });
+          for (const i of remote) {
+            events.emit("cart_issue", { code: i.code });
+          }
+          if (quote.menuVersion !== menu.version || quote.issues.some((i) => i.code === "menu_version_stale")) {
+            void refresh().catch(
+              (error) => events.emit("error", { error: asError(error) })
+            );
+          }
+        });
+      } catch (error) {
+        if (seq === revision && attempt === quoteRevision) {
+          const local = snapshot.issues.filter((i) => i.source === "local");
+          publish({ issues: local, state: attention(local) });
+          events.emit("quote_failed", { code: asError(error).code });
+        }
+        throw error instanceof Error && error.name === "AbortError" ? error : asError(error);
+      }
+    },
+    applyFix(problem, fix = problem.fixes[0]) {
+      if (!snapshot.issues.includes(problem) || !fix || !problem.fixes.some((f) => JSON.stringify(f) === JSON.stringify(fix))) {
+        throw new ZappieError(
+          "invalid_request",
+          "Choose a current cart issue and one of its fixes"
+        );
+      }
+      switch (fix.action) {
+        case "remove_line": {
+          if (problem.lineId) {
+            cart.remove(problem.lineId);
+          }
+          return;
+        }
+        case "remove_promo":
+          cart.setPromoCode(null);
+          return;
+        case "set_quantity": {
+          if (problem.lineId) {
+            cart.update(problem.lineId, { quantity: fix.quantity });
+          }
+          return;
+        }
+        case "accept_price": {
+          quotes?.accept(problem);
+          const issues = snapshot.issues.filter((i) => i !== problem);
+          const quote = "quote" in snapshot.state ? snapshot.state.quote : void 0;
+          const accepted = quote ? {
+            ...quote,
+            issues: quote.issues.filter(
+              (i) => !(i.code === problem.code && i.lineId === problem.lineId)
+            )
+          } : void 0;
+          publish({ issues, state: attention(issues, accepted) });
+          return;
+        }
+        default:
+          throw new ZappieError(
+            "invalid_request",
+            `${fix.action} needs the shopper's selection; use update or setFulfilment`
+          );
+      }
+    },
+    toCheckoutPayload() {
+      ensure();
+      const blocking = snapshot.issues.filter((i) => i.severity === "blocking");
+      if (!snapshot.lines.length || !snapshot.fulfilment) {
+        blocking.push(
+          issue(
+            "fulfilment_unavailable",
+            "Add items and select fulfilment before checkout"
+          )
+        );
+      }
+      if (blocking.length) {
+        throw new ZappieCartError(blocking);
+      }
+      return {
+        lines: snapshot.lines.map(wireLine),
+        fulfilment: structuredClone(snapshot.fulfilment),
+        ...snapshot.promoCode ? { promo_code: snapshot.promoCode } : {},
+        menu_version: menu.version
+      };
+    }
+  };
+  return {
+    cart: Object.freeze(cart),
+    cartCatalogue: () => menu,
+    setLegacyReader(reader) {
+      legacy = reader;
+    }
+  };
+}
+export {
+  EMPTY_CART,
+  createCart
+};
+//# sourceMappingURL=index.js.map