@laconius/cart 0.1.0

package/lib/typescript/src/models.d.ts

@@ -0,0 +1,122 @@
+import type { Currency, Price, Principal, Product, Promotion } from '@laconius/core';
+/**
+ * Cart models, ported from Spartacus `feature-libs/cart/base/root/models/cart.model.ts`
+ * (Apache-2.0, see NOTICE), minus the B2B, saved-cart and pickup-in-store noise
+ * ([chapter 03](../../../docs/spec/03-occ-layer.md)).
+ *
+ * `CartModification` is copied **exactly**: it encodes protocol rather than data — a cart
+ * mutation answers with an adjusted quantity and a status, and an API returning `void` there
+ * would be wrong.
+ */
+export interface Voucher {
+    appliedValue?: Price;
+    code?: string;
+    currency?: Currency;
+    description?: string;
+    freeShipping?: boolean;
+    name?: string;
+    value?: number;
+    valueFormatted?: string;
+    valueString?: string;
+    voucherCode?: string;
+}
+export interface PromotionOrderEntryConsumed {
+    adjustedUnitPrice?: number;
+    code?: string;
+    orderEntryNumber?: number;
+    quantity?: number;
+}
+export interface PromotionResult {
+    consumedEntries?: PromotionOrderEntryConsumed[];
+    description?: string;
+    promotion?: Promotion;
+}
+export interface DeliveryMode {
+    code?: string;
+    deliveryCost?: Price;
+    description?: string;
+    name?: string;
+}
+export interface OrderEntry {
+    basePrice?: Price;
+    deliveryMode?: DeliveryMode;
+    entryNumber?: number;
+    product?: Product;
+    quantity?: number;
+    totalPrice?: Price;
+    updateable?: boolean;
+    promotions?: PromotionResult[];
+}
+export interface Cart {
+    appliedOrderPromotions?: PromotionResult[];
+    appliedProductPromotions?: PromotionResult[];
+    appliedVouchers?: Voucher[];
+    calculated?: boolean;
+    code?: string;
+    deliveryCost?: Price;
+    deliveryItemsQuantity?: number;
+    deliveryMode?: DeliveryMode;
+    description?: string;
+    entries?: OrderEntry[];
+    /** ISO string: OCC returns strings and never `Date`. */
+    expirationTime?: string;
+    guid?: string;
+    name?: string;
+    net?: boolean;
+    orderDiscounts?: Price;
+    pickupItemsQuantity?: number;
+    potentialOrderPromotions?: PromotionResult[];
+    potentialProductPromotions?: PromotionResult[];
+    productDiscounts?: Price;
+    site?: string;
+    store?: string;
+    subTotal?: Price;
+    totalDiscounts?: Price;
+    totalItems?: number;
+    totalPrice?: Price;
+    totalPriceWithTax?: Price;
+    totalTax?: Price;
+    totalUnitCount?: number;
+    user?: Principal;
+}
+export interface CartModification {
+    deliveryModeChanged?: boolean;
+    entry?: OrderEntry;
+    quantity?: number;
+    quantityAdded?: number;
+    statusCode?: string;
+    statusMessage?: string;
+}
+export interface CartModificationList {
+    cartModifications?: CartModification[];
+}
+export type CartValidationStatusCode = 'noStock' | 'lowStock' | 'reviewConfiguration' | 'pricingError' | 'unresolvableIssues' | 'below_min_quantity' | 'exceed_max_quantity';
+export type AddToCartInput = {
+    productCode: string;
+    quantity?: number;
+};
+/**
+ * What every cart mutation resolves to. It carries the cart id it acted on: with lazy creation,
+ * an `onSuccess` closing over `activeCartId` writes the wrong cache entry
+ * ([chapter 04](../../../docs/spec/04-state.md)).
+ */
+export type CartMutationResult = {
+    cart: Cart;
+    cartId: string;
+    modification?: CartModification;
+};
+export type CartMergeFailure = {
+    entry: OrderEntry;
+    /** The `LaconiusHttpError` that rejected the replay. */
+    error: unknown;
+};
+/**
+ * The one place Laconius returns errors as data rather than throwing them: a partial replay is
+ * not a failure, and silently dropping the rejected entries is exactly what users notice
+ * ([chapter 09](../../../docs/spec/09-i18n-and-errors.md)).
+ */
+export type CartMergeResult = {
+    replayed: OrderEntry[];
+    failed: CartMergeFailure[];
+};
+//# sourceMappingURL=models.d.ts.map

package/lib/typescript/src/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/models.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/normalizer.d.ts

@@ -0,0 +1,24 @@
+import { type Image, type Product } from '@laconius/core';
+import type { Cart, OrderEntry } from './models.js';
+/** An entry as OCC answers it: the product's images are still a flat list. */
+export type OccOrderEntry = Omit<OrderEntry, 'product'> & {
+    product?: Omit<Product, 'images'> & {
+        images?: Image[];
+    };
+};
+export type OccCart = Omit<Cart, 'entries'> & {
+    entries?: OccOrderEntry[];
+};
+/**
+ * Reshapes every entry product's flat image list through core's `normalizeImages` — the same
+ * mechanism the product adapter uses ([chapter 08](../../../docs/spec/08-media.md)). URLs are
+ * not absolutised here: converters are pure, so the adapter absolutises the whole payload
+ * afterwards.
+ */
+export declare function normalizeCartImages(source: OccCart, target?: Cart): Cart;
+/**
+ * Ported from `feature-libs/cart/base/core/utils/utils.ts`: an anonymous cart is addressed by
+ * its `guid`, a logged-in user's cart by its `code`.
+ */
+export declare function getCartId(cart: Cart | undefined, userId: string): string;
+//# sourceMappingURL=normalizer.d.ts.map

package/lib/typescript/src/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../../src/normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,aAAU,CAAC;AAEjD,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG;IACxD,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;KAAE,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAaxE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/lib/typescript/src/queries.d.ts

@@ -0,0 +1,47 @@
+import type { AddToCartInput, Cart, CartMergeResult, CartMutationResult } from './models.js';
+/**
+ * `queryOptions` factory, so an app can `prefetchQuery` the cart without forking the library.
+ * The key is `['laconius','cart',{ctx},cartId]` — the context object carries the user, which is
+ * what keeps an anonymous cart and a user cart apart in the cache.
+ */
+export declare const cartQueries: {
+    detail: (cartId: string) => import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<Cart, Error, Cart, readonly unknown[]>, "queryFn"> & {
+        queryFn?: import("@tanstack/react-query").QueryFunction<Cart, readonly unknown[], never> | undefined;
+    } & import("@tanstack/react-query").QueryKeyWithDataTag<readonly unknown[], Cart, Error>;
+};
+/**
+ * The active cart. Empty (no request) until an add creates one — the anonymous cart is lazy —
+ * except for a logged-in user with no stored id, whose latest cart OCC addresses as the literal
+ * `current`.
+ */
+export declare function useActiveCart(): import("@tanstack/react-query").UseQueryResult<Cart, Error>;
+/**
+ * Not optimistic: stock and price come from the server, and rolling back a `lowStock` result is
+ * ugly ([chapter 04](../../../docs/spec/04-state.md)). OCC answers the POST with a
+ * `CartModification`, so one follow-up read is what lets `setQueryData` replace invalidation.
+ */
+export declare function useAddToCart(): import("@tanstack/react-query").UseMutationResult<CartMutationResult, Error, AddToCartInput, unknown>;
+type EntrySnapshot = {
+    previous?: Cart;
+    queryKey?: unknown[];
+};
+/** Optimistic: the quantity flips immediately, the totals arrive with the response. */
+export declare function useUpdateCartEntry(): import("@tanstack/react-query").UseMutationResult<CartMutationResult, Error, {
+    entryNumber: number;
+    quantity: number;
+}, EntrySnapshot>;
+/** Optimistic: the row disappears immediately, the totals arrive with the response. */
+export declare function useRemoveCartEntry(): import("@tanstack/react-query").UseMutationResult<CartMutationResult, Error, {
+    entryNumber: number;
+}, EntrySnapshot>;
+export declare function useApplyVoucher(): import("@tanstack/react-query").UseMutationResult<CartMutationResult, Error, string, unknown>;
+export declare function useRemoveVoucher(): import("@tanstack/react-query").UseMutationResult<CartMutationResult, Error, string, unknown>;
+/**
+ * Persist-then-replay, never the native merge — the backend rejects a native merge after a
+ * redirect login, and every React Native login is one
+ * ([chapter 05](../../../docs/spec/05-auth-session.md)). Call it after a successful login;
+ * `useLogin()` takes an `onLoggedIn` callback and the template joins them.
+ */
+export declare function useMergeAnonymousCart(): import("@tanstack/react-query").UseMutationResult<CartMergeResult, Error, void, unknown>;
+export {};
+//# sourceMappingURL=queries.d.ts.map

package/lib/typescript/src/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/queries.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,eAAe,EACf,kBAAkB,EAEnB,MAAM,aAAU,CAAC;AAIlB;;;;GAIG;AACH,eAAO,MAAM,WAAW;qBACL,MAAM;;;CAwBxB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,gEAQ5B;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,0GAsB3B;AAED,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AA0B/D,uFAAuF;AACvF,wBAAgB,kBAAkB;iBAOf,MAAM;cACT,MAAM;kBAkBrB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB;iBAMf,MAAM;kBAgBxB;AAED,wBAAgB,eAAe,kGAa9B;AAED,wBAAgB,gBAAgB,kGAa/B;AAkBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,6FAyCpC"}

package/lib/typescript/src/store.d.ts

@@ -0,0 +1,25 @@
+export type ActiveCartState = {
+    /** Cart `code` for a logged-in user, `guid` for an anonymous one. */
+    cartId?: string;
+    setCartId: (cartId: string | undefined) => void;
+    clearCartId: () => void;
+};
+/**
+ * The only client-side cart state: the entity itself is server state in TanStack Query
+ * ([chapter 04](../../../docs/spec/04-state.md)). Persisted, so the id survives a restart and
+ * OCC reprices; a dead id resets itself through the 404 path in the query.
+ */
+export declare const useActiveCartIdStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<ActiveCartState>, "setState" | "persist"> & {
+    setState(partial: ActiveCartState | Partial<ActiveCartState> | ((state: ActiveCartState) => ActiveCartState | Partial<ActiveCartState>), replace?: false | undefined): unknown;
+    setState(state: ActiveCartState | ((state: ActiveCartState) => ActiveCartState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<ActiveCartState, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: ActiveCartState) => void) => () => void;
+        onFinishHydration: (fn: (state: ActiveCartState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<ActiveCartState, unknown, unknown>>;
+    };
+}>;
+//# sourceMappingURL=store.d.ts.map

package/lib/typescript/src/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/store.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAChD,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAYhC,CAAC"}

package/lib/typescript/src/translations.d.ts

@@ -0,0 +1,29 @@
+/** English strings for the defaults in this package. Other languages are the app's. */
+export declare const defaultCartTranslations: {
+    en: {
+        cart: {
+            title: string;
+            addToCart: string;
+            itemAdded: string;
+            itemRemoved: string;
+            quantityUpdated: string;
+            remove: string;
+            removeItem: string;
+            empty: string;
+            entryCount_one: string;
+            entryCount_other: string;
+            subtotal: string;
+            discounts: string;
+            delivery: string;
+            tax: string;
+            total: string;
+            voucher: {
+                placeholder: string;
+                apply: string;
+                applied: string;
+                remove: string;
+            };
+        };
+    };
+};
+//# sourceMappingURL=translations.d.ts.map

package/lib/typescript/src/translations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translations.d.ts","sourceRoot":"","sources":["../../../src/translations.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BnC,CAAC"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@laconius/cart",
+  "version": "0.1.0",
+  "description": "Laconius cart: cart queries and mutations with a lazily created anonymous cart, optimistic quantity and remove, vouchers, the anonymous-cart replay merge, the activeCartId store, the cart components and the MiniCart CMS default.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/*.test.*"
+  ],
+  "sideEffects": [
+    "./src/store.ts",
+    "./lib/module/store.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@laconius/cms": "0.1.0",
+    "@laconius/core": "0.1.0",
+    "@laconius/ui": "0.1.0",
+    "@tanstack/react-query": "^5",
+    "expo-sqlite": "*",
+    "react": ">=19.0.0",
+    "react-native": "*",
+    "zustand": "^5"
+  },
+  "devDependencies": {
+    "@laconius/cms": "0.1.0",
+    "@laconius/core": "0.1.0",
+    "@laconius/ui": "0.1.0",
+    "@tanstack/react-query": "^5.102.8",
+    "@types/react": "~19.2.2",
+    "expo-sqlite": "~57.0.2",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-builder-bob": "^0.43.0",
+    "typescript": "~6.0.3",
+    "vitest": "^3.2.4",
+    "zustand": "^5.0.15"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ],
+    "exclude": "**/*.test.{ts,tsx}"
+  },
+  "scripts": {
+    "build": "bob build",
+    "clean": "rm -rf lib",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,187 @@
+import {
+  absolutizeMedia,
+  getMediaBaseUrl,
+  type Converter,
+  type LaconiusRuntime,
+} from '@laconius/core';
+
+import type { Cart, CartModification, CartModificationList } from './models';
+import { normalizeCartImages, type OccCart } from './normalizer';
+
+export type CartAdapter = {
+  load(runtime: LaconiusRuntime, cartId: string): Promise<Cart>;
+  loadAll(runtime: LaconiusRuntime): Promise<Cart[]>;
+  create(
+    runtime: LaconiusRuntime,
+    options?: { oldCartId?: string; toMergeCartGuid?: string },
+  ): Promise<Cart>;
+  remove(runtime: LaconiusRuntime, cartId: string): Promise<void>;
+  addEntry(
+    runtime: LaconiusRuntime,
+    cartId: string,
+    productCode: string,
+    quantity: number,
+  ): Promise<CartModification>;
+  updateEntry(
+    runtime: LaconiusRuntime,
+    cartId: string,
+    entryNumber: number,
+    quantity: number,
+  ): Promise<CartModification>;
+  removeEntry(
+    runtime: LaconiusRuntime,
+    cartId: string,
+    entryNumber: number,
+  ): Promise<void>;
+  applyVoucher(
+    runtime: LaconiusRuntime,
+    cartId: string,
+    voucherId: string,
+  ): Promise<void>;
+  removeVoucher(
+    runtime: LaconiusRuntime,
+    cartId: string,
+    voucherId: string,
+  ): Promise<void>;
+  validate(runtime: LaconiusRuntime, cartId: string): Promise<CartModificationList>;
+};
+
+/** Runs the `cart` stack and absolutises the media it reshaped, in that order. */
+function toCart(runtime: LaconiusRuntime, source: OccCart | undefined): Cart {
+  const cart = runtime.converters.convert<OccCart, Cart>(source ?? {}, 'cart');
+  return absolutizeMedia(cart, getMediaBaseUrl(runtime.config));
+}
+
+function toModification(runtime: LaconiusRuntime, source: unknown): CartModification {
+  return runtime.converters.convert<unknown, CartModification>(
+    source ?? {},
+    'cartModification',
+  );
+}
+
+export const defaultCartAdapter: CartAdapter = {
+  /** `cartId` may be the literal `current` for a logged-in user. */
+  async load(runtime, cartId) {
+    const payload = await runtime.client.request<OccCart>({
+      endpoint: 'cart',
+      urlParams: { cartId },
+    });
+    return toCart(runtime, payload);
+  },
+
+  async loadAll(runtime) {
+    const response = await runtime.client.request<{ carts?: OccCart[] }>({
+      endpoint: 'carts',
+    });
+    return (response?.carts ?? []).map((cart) => toCart(runtime, cart));
+  },
+
+  /**
+   * `oldCartId` / `toMergeCartGuid` exist for endpoint parity, but Laconius never merges
+   * natively: every React Native login is a redirect login, and the backend rejects a native
+   * merge after one — the merge is always persist-then-replay
+   * ([chapter 05](../../../docs/spec/05-auth-session.md)).
+   */
+  async create(runtime, options = {}) {
+    const payload = await runtime.client.request<OccCart>({
+      endpoint: 'createCart',
+      method: 'POST',
+      queryParams: {
+        oldCartId: options.oldCartId,
+        toMergeCartGuid: options.toMergeCartGuid,
+      },
+    });
+    return toCart(runtime, payload);
+  },
+
+  async remove(runtime, cartId) {
+    await runtime.client.request<void>({
+      endpoint: 'deleteCart',
+      method: 'DELETE',
+      urlParams: { cartId },
+    });
+  },
+
+  async addEntry(runtime, cartId, productCode, quantity) {
+    const payload = await runtime.client.request<unknown>({
+      endpoint: 'addEntries',
+      method: 'POST',
+      urlParams: { cartId },
+      body: { quantity, product: { code: productCode } },
+    });
+    return toModification(runtime, payload);
+  },
+
+  async updateEntry(runtime, cartId, entryNumber, quantity) {
+    const payload = await runtime.client.request<unknown>({
+      endpoint: 'updateEntries',
+      method: 'PATCH',
+      urlParams: { cartId, entryNumber },
+      body: { quantity },
+    });
+    return toModification(runtime, payload);
+  },
+
+  async removeEntry(runtime, cartId, entryNumber) {
+    await runtime.client.request<void>({
+      endpoint: 'removeEntries',
+      method: 'DELETE',
+      urlParams: { cartId, entryNumber },
+    });
+  },
+
+  /** The JSON pair when `capabilities.jsonVouchers` is on, the legacy pair when it is off. */
+  async applyVoucher(runtime, cartId, voucherId) {
+    if (runtime.config.capabilities?.jsonVouchers) {
+      await runtime.client.request<void>({
+        endpoint: 'cartApplyVoucher',
+        method: 'POST',
+        urlParams: { cartId },
+        body: { voucherId },
+      });
+      return;
+    }
+    await runtime.client.request<void>({
+      endpoint: 'cartVoucher',
+      method: 'POST',
+      urlParams: { cartId },
+      queryParams: { voucherId },
+    });
+  },
+
+  async removeVoucher(runtime, cartId, voucherId) {
+    if (runtime.config.capabilities?.jsonVouchers) {
+      await runtime.client.request<void>({
+        endpoint: 'cartRemoveVoucher',
+        method: 'POST',
+        urlParams: { cartId },
+        body: { voucherId },
+      });
+      return;
+    }
+    await runtime.client.request<void>({
+      endpoint: 'cartVoucher',
+      scope: 'delete',
+      method: 'DELETE',
+      urlParams: { cartId, voucherId },
+    });
+  },
+
+  async validate(runtime, cartId) {
+    const payload = await runtime.client.request<CartModificationList>({
+      endpoint: 'validate',
+      method: 'POST',
+      urlParams: { cartId },
+    });
+    return payload ?? {};
+  },
+};
+
+export function cartAdapter(runtime: LaconiusRuntime): CartAdapter {
+  return { ...defaultCartAdapter, ...runtime.config.backend.adapters?.cart };
+}
+
+export const defaultCartConverters = {
+  cart: [normalizeCartImages] as Converter<OccCart, Cart>[],
+  cartModification: [] as Converter<unknown, CartModification>[],
+};