@laconius/cart 0.1.0

package/src/queries.ts

@@ -0,0 +1,288 @@
+import {
+  LaconiusHttpError,
+  getRuntime,
+  laconiusQueryKey,
+  useIsLoggedIn,
+} from '@laconius/core';
+import {
+  queryOptions,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type QueryClient,
+} from '@tanstack/react-query';
+
+import { cartAdapter } from './adapter';
+import type {
+  AddToCartInput,
+  Cart,
+  CartMergeResult,
+  CartMutationResult,
+  OrderEntry,
+} from './models';
+import { getCartId } from './normalizer';
+import { useActiveCartIdStore } from './store';
+
+/**
+ * `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 const cartQueries = {
+  detail: (cartId: string) =>
+    queryOptions<Cart>({
+      queryKey: laconiusQueryKey('cart', cartId),
+      /** Prices and stock go stale the moment someone else buys ([chapter 04](../../../docs/spec/04-state.md)). */
+      staleTime: 0,
+      queryFn: async () => {
+        const runtime = getRuntime();
+        try {
+          const cart = await cartAdapter(runtime).load(runtime, cartId);
+          // `current` resolves to a real id; keep the store on it so mutations address it.
+          const id = getCartId(cart, runtime.auth.getUserId());
+          const store = useActiveCartIdStore.getState();
+          if (id && id !== store.cartId) store.setCartId(id);
+          return cart;
+        } catch (error) {
+          // A dead persisted id silently resets to an empty cart; retry already skips 4xx.
+          if (error instanceof LaconiusHttpError && error.status === 404) {
+            useActiveCartIdStore.getState().clearCartId();
+            return {};
+          }
+          throw 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 function useActiveCart() {
+  const storedId = useActiveCartIdStore((state) => state.cartId);
+  const loggedIn = useIsLoggedIn();
+  const cartId = storedId ?? (loggedIn ? 'current' : undefined);
+  return useQuery({
+    ...cartQueries.detail(cartId ?? ''),
+    enabled: Boolean(cartId),
+  });
+}
+
+/** Writes the returned cart under the returned id — never the closed-over one. */
+function writeCart(queryClient: QueryClient, result: CartMutationResult): void {
+  queryClient.setQueryData(laconiusQueryKey('cart', result.cartId), result.cart);
+}
+
+function requireCartId(): string {
+  const cartId = useActiveCartIdStore.getState().cartId;
+  if (!cartId) {
+    throw new Error('[laconius] No active cart. Add an item before mutating entries.');
+  }
+  return cartId;
+}
+
+/**
+ * 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 function useAddToCart() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async ({
+      productCode,
+      quantity = 1,
+    }: AddToCartInput): Promise<CartMutationResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      let cartId = useActiveCartIdStore.getState().cartId;
+      if (!cartId) {
+        // Lazy: created inside the first add, never eagerly at mount.
+        const created = await adapter.create(runtime);
+        cartId = getCartId(created, runtime.auth.getUserId());
+        useActiveCartIdStore.getState().setCartId(cartId);
+      }
+      const modification = await adapter.addEntry(runtime, cartId, productCode, quantity);
+      const cart = await adapter.load(runtime, cartId);
+      return { cart, cartId, modification };
+    },
+    onSuccess: (result) => writeCart(queryClient, result),
+  });
+}
+
+type EntrySnapshot = { previous?: Cart; queryKey?: unknown[] };
+
+async function snapshotEntries(
+  queryClient: QueryClient,
+  mutate: (entries: OrderEntry[]) => OrderEntry[],
+): Promise<EntrySnapshot> {
+  const cartId = useActiveCartIdStore.getState().cartId;
+  if (!cartId) return {};
+  const queryKey = laconiusQueryKey('cart', cartId);
+  await queryClient.cancelQueries({ queryKey });
+  const previous = queryClient.getQueryData<Cart>(queryKey);
+  if (previous?.entries) {
+    queryClient.setQueryData<Cart>(queryKey, {
+      ...previous,
+      entries: mutate(previous.entries),
+    });
+  }
+  return { previous, queryKey };
+}
+
+function rollback(queryClient: QueryClient, snapshot: EntrySnapshot | undefined): void {
+  if (snapshot?.previous && snapshot.queryKey) {
+    queryClient.setQueryData(snapshot.queryKey, snapshot.previous);
+  }
+}
+
+/** Optimistic: the quantity flips immediately, the totals arrive with the response. */
+export function useUpdateCartEntry() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async ({
+      entryNumber,
+      quantity,
+    }: {
+      entryNumber: number;
+      quantity: number;
+    }): Promise<CartMutationResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      const cartId = requireCartId();
+      const modification = await adapter.updateEntry(runtime, cartId, entryNumber, quantity);
+      const cart = await adapter.load(runtime, cartId);
+      return { cart, cartId, modification };
+    },
+    onMutate: ({ entryNumber, quantity }) =>
+      snapshotEntries(queryClient, (entries) =>
+        entries.map((entry) =>
+          entry.entryNumber === entryNumber ? { ...entry, quantity } : entry,
+        ),
+      ),
+    onError: (_error, _input, snapshot) => rollback(queryClient, snapshot),
+    onSuccess: (result) => writeCart(queryClient, result),
+  });
+}
+
+/** Optimistic: the row disappears immediately, the totals arrive with the response. */
+export function useRemoveCartEntry() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async ({
+      entryNumber,
+    }: {
+      entryNumber: number;
+    }): Promise<CartMutationResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      const cartId = requireCartId();
+      await adapter.removeEntry(runtime, cartId, entryNumber);
+      const cart = await adapter.load(runtime, cartId);
+      return { cart, cartId };
+    },
+    onMutate: ({ entryNumber }) =>
+      snapshotEntries(queryClient, (entries) =>
+        entries.filter((entry) => entry.entryNumber !== entryNumber),
+      ),
+    onError: (_error, _input, snapshot) => rollback(queryClient, snapshot),
+    onSuccess: (result) => writeCart(queryClient, result),
+  });
+}
+
+export function useApplyVoucher() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (voucherId: string): Promise<CartMutationResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      const cartId = requireCartId();
+      await adapter.applyVoucher(runtime, cartId, voucherId);
+      const cart = await adapter.load(runtime, cartId);
+      return { cart, cartId };
+    },
+    onSuccess: (result) => writeCart(queryClient, result),
+  });
+}
+
+export function useRemoveVoucher() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (voucherId: string): Promise<CartMutationResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      const cartId = requireCartId();
+      await adapter.removeVoucher(runtime, cartId, voucherId);
+      const cart = await adapter.load(runtime, cartId);
+      return { cart, cartId };
+    },
+    onSuccess: (result) => writeCart(queryClient, result),
+  });
+}
+
+/**
+ * The anonymous cart cannot be fetched once the `Authorization` header exists, so the entries
+ * come from the cache snapshot — the "read before starting the flow" of
+ * [chapter 05](../../../docs/spec/05-auth-session.md). The query key's context object carries
+ * the user, which is what keeps that snapshot addressable after login.
+ */
+function findAnonymousCart(queryClient: QueryClient): Cart | undefined {
+  for (const [key, data] of queryClient.getQueriesData<Cart>({
+    queryKey: ['laconius', 'cart'],
+  })) {
+    const context = key[2] as { user?: string } | undefined;
+    if (context?.user === 'anonymous' && data?.entries?.length) return data;
+  }
+  return undefined;
+}
+
+/**
+ * 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 function useMergeAnonymousCart() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (): Promise<CartMergeResult> => {
+      const runtime = getRuntime();
+      const adapter = cartAdapter(runtime);
+      const entries = findAnonymousCart(queryClient)?.entries ?? [];
+
+      // The anonymous id belonged to the previous session.
+      const store = useActiveCartIdStore.getState();
+      store.clearCartId();
+      if (entries.length === 0) return { replayed: [], failed: [] };
+
+      let cart: Cart;
+      try {
+        cart = await adapter.load(runtime, 'current');
+      } catch {
+        cart = await adapter.create(runtime);
+      }
+      const cartId = getCartId(cart, runtime.auth.getUserId());
+      store.setCartId(cartId);
+
+      const replayed: OrderEntry[] = [];
+      const failed: CartMergeResult['failed'] = [];
+      for (const entry of entries) {
+        const productCode = entry.product?.code;
+        if (!productCode) continue;
+        try {
+          await adapter.addEntry(runtime, cartId, productCode, entry.quantity ?? 1);
+          replayed.push(entry);
+        } catch (error) {
+          failed.push({ entry, error });
+        }
+      }
+      return { replayed, failed };
+    },
+    // Login invalidates everything: customer-group pricing depends on the user.
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ['laconius'] });
+    },
+  });
+}

package/src/store.ts

@@ -0,0 +1,46 @@
+import { useSessionStore } from '@laconius/core';
+import AsyncStorage from 'expo-sqlite/kv-store';
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+
+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 const useActiveCartIdStore = create<ActiveCartState>()(
+  persist(
+    (set) => ({
+      setCartId: (cartId) => set({ cartId }),
+      clearCartId: () => set({ cartId: undefined }),
+    }),
+    {
+      name: 'laconius.activeCartId',
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({ cartId: state.cartId }),
+    },
+  ),
+);
+
+/**
+ * Logout drops the id — it belonged to the previous session ([chapter 04](../../../docs/spec/04-state.md)).
+ * Core cannot do it (no `core -> cart` edge exists), so the store watches the session: an access
+ * token disappearing is a session ending, whoever caused it. Login is the other direction and is
+ * handled by `useMergeAnonymousCart`.
+ *
+ * This runs at import time, which is why `package.json` lists this module under `sideEffects`
+ * rather than declaring the package side-effect-free: without that entry a bundler may drop the
+ * module when a consumer imports nothing from it, and the id would outlive the session.
+ */
+useSessionStore.subscribe((state, previous) => {
+  if (previous.accessToken && !state.accessToken) {
+    useActiveCartIdStore.getState().clearCartId();
+  }
+});

package/src/translations.ts

@@ -0,0 +1,28 @@
+/** English strings for the defaults in this package. Other languages are the app's. */
+export const defaultCartTranslations = {
+  en: {
+    cart: {
+      title: 'Cart',
+      addToCart: 'Add to cart',
+      itemAdded: 'Added to cart.',
+      itemRemoved: 'Removed from cart.',
+      quantityUpdated: 'Quantity updated.',
+      remove: 'Remove',
+      removeItem: 'Remove {{name}} from cart',
+      empty: 'Your cart is empty.',
+      entryCount_one: '{{count}} item',
+      entryCount_other: '{{count}} items',
+      subtotal: 'Subtotal',
+      discounts: 'Discounts',
+      delivery: 'Delivery',
+      tax: 'Tax',
+      total: 'Total',
+      voucher: {
+        placeholder: 'Voucher code',
+        apply: 'Apply',
+        applied: 'Applied vouchers',
+        remove: 'Remove voucher {{code}}',
+      },
+    },
+  },
+};