@laconius/core 0.1.0

package/src/models.ts

@@ -0,0 +1,384 @@
+/**
+ * Shared domain model types. Types only: zero runtime, no converters, no adapters.
+ *
+ * Ported from Spartacus `core-libs/core/src/model/{image,product,misc,address,consent}.model.ts`
+ * (Apache-2.0, see NOTICE). Two deliberate divergences:
+ * - `enum` becomes a string union, so this module emits nothing at runtime.
+ * - Date-typed fields become `string`: OCC returns ISO strings and never `Date`.
+ */
+
+export type ImageType = 'PRIMARY' | 'GALLERY';
+
+export interface Image {
+  altText?: string;
+  role?: string;
+  format?: string;
+  galleryIndex?: number;
+  imageType?: ImageType;
+  url?: string;
+  width?: number;
+  height?: number;
+}
+
+/** One format code (`thumbnail`, `zoom`, …) per entry. */
+export interface ImageGroup {
+  [format: string]: Image;
+}
+
+export interface Images {
+  [imageType: string]: ImageGroup | ImageGroup[];
+}
+
+export type PriceType = 'BUY' | 'FROM';
+
+export interface Price {
+  currencyIso?: string;
+  formattedValue?: string;
+  maxQuantity?: number;
+  minQuantity?: number;
+  priceType?: PriceType;
+  value?: number;
+}
+
+export interface PriceRange {
+  maxPrice?: Price;
+  minPrice?: Price;
+}
+
+export interface Stock {
+  isValueRounded?: boolean;
+  stockLevel?: number;
+  stockLevelStatus?: string;
+}
+
+export interface Currency {
+  active?: boolean;
+  isocode?: string;
+  name?: string;
+  symbol?: string;
+}
+
+export interface Language {
+  active?: boolean;
+  isocode?: string;
+  name?: string;
+  nativeName?: string;
+}
+
+export interface Country {
+  isocode?: string;
+  name?: string;
+}
+
+export type CountryType = 'BILLING' | 'SHIPPING';
+
+export interface Region {
+  countryIso?: string;
+  isocode?: string;
+  isocodeShort?: string;
+  name?: string;
+}
+
+export interface City {
+  regionIso?: string;
+  isocode?: string;
+  name?: string;
+}
+
+export interface CityDistrict {
+  cityIso?: string;
+  isocode?: string;
+  name?: string;
+}
+
+export interface Title {
+  code?: string;
+  name?: string;
+}
+
+export interface Address {
+  id?: string;
+  title?: string;
+  titleCode?: string;
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  companyName?: string;
+  line1?: string;
+  line2?: string;
+  postalCode?: string;
+  town?: string;
+  city?: City;
+  region?: Region;
+  district?: string;
+  cityDistrict?: CityDistrict;
+  country?: Country;
+  cellphone?: string;
+  defaultAddress?: boolean;
+  shippingAddress?: boolean;
+  formattedAddress?: string;
+  phone?: string;
+  visibleInAddressBook?: boolean;
+}
+
+export interface User {
+  currency?: Currency;
+  customerId?: string;
+  deactivationDate?: string;
+  defaultAddress?: Address;
+  displayUid?: string;
+  firstName?: string;
+  language?: Language;
+  lastName?: string;
+  name?: string;
+  title?: string;
+  titleCode?: string;
+  uid?: string;
+  roles?: string[];
+  lastCartId?: string;
+  hasOrder?: boolean;
+}
+
+export interface Principal {
+  name?: string;
+  uid?: string;
+}
+
+export interface CaptchaConfig {
+  enabled: boolean;
+  publicKey?: string;
+}
+
+export interface BaseStore {
+  currencies?: Currency[];
+  defaultCurrency?: Currency;
+  languages?: Language[];
+  defaultLanguage?: Language;
+  paymentProvider?: string;
+}
+
+export interface BaseSite {
+  channel?: string;
+  defaultLanguage?: Language;
+  locale?: string;
+  name?: string;
+  theme?: string;
+  uid?: string;
+  stores?: BaseStore[];
+  urlPatterns?: string[];
+  urlEncodingAttributes?: string[];
+  baseStore?: BaseStore;
+  requiresAuthentication?: boolean;
+  isolated?: boolean;
+  captchaConfig?: CaptchaConfig;
+}
+
+export interface PaginationModel {
+  currentPage?: number;
+  pageSize?: number;
+  sort?: string;
+  totalPages?: number;
+  totalResults?: number;
+}
+
+export interface SortModel {
+  code?: string;
+  name?: string;
+  selected?: boolean;
+}
+
+export interface Category {
+  code?: string;
+  name?: string;
+  image?: Image;
+  url?: string;
+}
+
+export interface FeatureUnit {
+  name?: string;
+  symbol?: string;
+  unitType?: string;
+}
+
+export interface FeatureValue {
+  value?: string;
+}
+
+export interface Feature {
+  code?: string;
+  comparable?: boolean;
+  description?: string;
+  featureUnit?: FeatureUnit;
+  featureValues?: FeatureValue[];
+  name?: string;
+  range?: boolean;
+  type?: string;
+}
+
+export interface Classification {
+  code?: string;
+  features?: Feature[];
+  name?: string;
+}
+
+export interface PromotionRestriction {
+  description?: string;
+  restrictionType?: string;
+}
+
+export interface Promotion {
+  code?: string;
+  couldFireMessages?: string[];
+  description?: string;
+  enabled?: boolean;
+  endDate?: string;
+  firedMessages?: string[];
+  priority?: number;
+  productBanner?: Image;
+  promotionGroup?: string;
+  promotionType?: string;
+  restrictions?: PromotionRestriction[];
+  startDate?: string;
+  title?: string;
+}
+
+export type VariantType =
+  | 'ApparelSizeVariantProduct'
+  | 'ApparelStyleVariantProduct'
+  | 'ElectronicsColorVariantProduct';
+
+export type VariantQualifier =
+  | 'size'
+  | 'style'
+  | 'color'
+  | 'thumbnail'
+  | 'product'
+  | 'styleSwatch'
+  | 'rollupProperty';
+
+export interface VariantOptionQualifier {
+  image?: Image;
+  name?: string;
+  qualifier?: VariantQualifier;
+  value?: string;
+}
+
+export interface VariantOption {
+  code?: string;
+  priceData?: Price;
+  stock?: Stock;
+  url?: string;
+  variantOptionQualifiers?: VariantOptionQualifier[];
+}
+
+export interface VariantCategory {
+  hasImage?: boolean;
+  name?: string;
+  priority?: number;
+}
+
+export interface VariantValueCategory {
+  name?: string;
+  sequence?: number;
+  superCategories?: VariantCategory[];
+}
+
+export interface VariantMatrixElement {
+  elements?: VariantMatrixElement[];
+  isLeaf?: boolean;
+  parentVariantCategory?: VariantCategory;
+  variantOption?: VariantOption;
+  variantValueCategory?: VariantValueCategory;
+}
+
+export interface BaseOption {
+  options?: VariantOption[];
+  selected?: VariantOption;
+  variantType?: VariantType;
+}
+
+export interface Review {
+  alias?: string;
+  comment?: string;
+  date?: string;
+  headline?: string;
+  id?: string;
+  principal?: User;
+  rating?: number;
+}
+
+export interface ProductReference {
+  description?: string;
+  preselected?: boolean;
+  quantity?: number;
+  referenceType?: string;
+  target?: Product;
+}
+
+export interface ProductReferences {
+  [referenceType: string]: ProductReference[];
+}
+
+export interface FutureStock {
+  date?: string;
+  formattedDate?: string;
+  stock?: Stock;
+}
+
+/** Unit of measure used for product stock availability (`productAvailabilities`). */
+export interface SapUnit {
+  code?: string;
+  name?: string;
+  availabilityCode?: string;
+  sapCode?: string;
+}
+
+export type ProductType = 'PHYSICAL' | 'SERVICE' | 'SUBSCRIPTION';
+
+export interface Product {
+  availableForPickup?: boolean;
+  averageRating?: number;
+  baseOptions?: BaseOption[];
+  baseProduct?: string;
+  categories?: Category[];
+  classifications?: Classification[];
+  code?: string;
+  description?: string;
+  futureStocks?: FutureStock[];
+  images?: Images;
+  manufacturer?: string;
+  multidimensional?: boolean;
+  name?: string;
+  nameHtml?: string;
+  numberOfReviews?: number;
+  potentialPromotions?: Promotion[];
+  price?: Price;
+  priceRange?: PriceRange;
+  productReferences?: ProductReferences;
+  purchasable?: boolean;
+  reviews?: Review[];
+  sapUnit?: SapUnit;
+  stock?: Stock;
+  summary?: string;
+  url?: string;
+  variantMatrix?: VariantMatrixElement[];
+  variantOptions?: VariantOption[];
+  variantType?: VariantType;
+  volumePrices?: Price[];
+  volumePricesFlag?: boolean;
+  productTypes?: ProductType;
+}
+
+export interface Consent {
+  code?: string;
+  consentGivenDate?: string;
+  consentWithdrawnDate?: string;
+}
+
+export interface ConsentTemplate {
+  id?: string;
+  name?: string;
+  description?: string;
+  version?: number;
+  currentConsent?: Consent;
+}

package/src/provider.tsx

@@ -0,0 +1,229 @@
+import {
+  QueryClient,
+  QueryClientProvider,
+  focusManager,
+  onlineManager,
+  useQueryClient,
+} from '@tanstack/react-query';
+import * as Network from 'expo-network';
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+import { createAuthClient } from './auth';
+import { createHttpClient } from './client';
+import type { LaconiusConfig } from './config';
+import { createConverterRegistry } from './converters';
+import { LaconiusHttpError } from './errors';
+import { createTranslator, type Translator } from './i18n';
+import { setActiveRuntime, type LaconiusRuntime } from './runtime';
+import {
+  resolveCurrency,
+  resolveLanguage,
+  useSessionStore,
+  useSiteContextStore,
+} from './stores';
+
+const LaconiusContext = createContext<LaconiusRuntime | undefined>(undefined);
+
+/**
+ * Fails loud at mount: without a backend the app does not exist, and failing at request forty
+ * only hides the cause. Individual unconfigured endpoints degrade through `isConfigured()`.
+ */
+function assertValidConfig(config: LaconiusConfig): void {
+  const missing: string[] = [];
+  if (!config.backend?.occ?.baseUrl) missing.push('backend.occ.baseUrl');
+  if (!config.backend?.occ?.baseSite) missing.push('backend.occ.baseSite');
+  if (config.auth) {
+    for (const key of ['clientId', 'redirectUri', 'authServerUrl'] as const) {
+      if (!config.auth[key]) missing.push(`auth.${key}`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `[laconius] Incomplete configuration: ${missing.join(', ')} ${
+        missing.length === 1 ? 'is' : 'are'
+      } required.`,
+    );
+  }
+}
+
+/** Retry policy of chapter 09, overridable through `queryClient.setQueryDefaults`. */
+export function createDefaultQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 5 * 60_000,
+        gcTime: 30 * 60_000,
+        retry: (failureCount, error) => {
+          if (error instanceof LaconiusHttpError) {
+            // 401 is not retried here: the client already refreshes once and retries once.
+            if (error.status >= 400 && error.status < 500) return false;
+          }
+          return failureCount < 2;
+        },
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000),
+      },
+      // A retried `POST /entries` can double an order line.
+      mutations: { retry: false },
+    },
+  });
+}
+
+export type LaconiusProviderProps = {
+  config: LaconiusConfig;
+  children: ReactNode;
+  /** Rendered while the stored session is exchanged. Defaults to nothing. */
+  fallback?: ReactNode;
+};
+
+export function LaconiusProvider({
+  config,
+  children,
+  fallback = null,
+}: LaconiusProviderProps) {
+  const runtime = useMemo<LaconiusRuntime>(() => {
+    assertValidConfig(config);
+    const auth = createAuthClient(config);
+    const runtime: LaconiusRuntime = {
+      config,
+      auth,
+      client: createHttpClient(config, auth),
+      converters: createConverterRegistry(config),
+    };
+    setActiveRuntime(runtime);
+    return runtime;
+  }, [config]);
+
+  useEffect(() => () => setActiveRuntime(undefined), []);
+
+  const queryClient = useMemo(
+    () => config.query?.queryClient ?? createDefaultQueryClient(),
+    [config.query?.queryClient],
+  );
+
+  useEffect(() => {
+    if (config.query?.wireOnlineManager === false) return;
+    return onlineManager.setEventListener((setOnline) => {
+      const subscription = Network.addNetworkStateListener((state) => {
+        setOnline(state.isInternetReachable ?? state.isConnected ?? true);
+      });
+      return () => subscription.remove();
+    });
+  }, [config.query?.wireOnlineManager]);
+
+  useEffect(() => {
+    if (config.query?.wireFocusManager === false) return;
+    const subscription = AppState.addEventListener(
+      'change',
+      (status: AppStateStatus) => focusManager.setFocused(status === 'active'),
+    );
+    return () => subscription.remove();
+  }, [config.query?.wireFocusManager]);
+
+  // Cold start: exchange the stored refresh token once, before the first authenticated call.
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    runtime.auth
+      .hydrate()
+      .catch((error: unknown) => config.onError?.(error, {}))
+      .finally(() => {
+        if (!cancelled) setHydrated(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, config]);
+
+  return (
+    <LaconiusContext.Provider value={runtime}>
+      <QueryClientProvider client={queryClient}>
+        {hydrated ? children : fallback}
+      </QueryClientProvider>
+    </LaconiusContext.Provider>
+  );
+}
+
+export function useLaconius(): LaconiusRuntime {
+  const runtime = useContext(LaconiusContext);
+  if (!runtime) {
+    throw new Error(
+      '[laconius] useLaconius must be used inside <LaconiusProvider>.',
+    );
+  }
+  return runtime;
+}
+
+export const useLaconiusConfig = (): LaconiusConfig => useLaconius().config;
+
+/** Re-renders on a language change, so a switch retranslates and refetches in one move. */
+export function useTranslation(): Translator {
+  const { config } = useLaconius();
+  // Subscribed for the re-render; the value itself comes from `resolveLanguage`, which is where
+  // a stored value that the config no longer offers is dropped.
+  const language = useSiteContextStore((state) => state.language);
+  return useMemo(
+    () =>
+      createTranslator({
+        translations: config.i18n?.translations,
+        language: resolveLanguage(config) ?? 'en',
+        fallbackLanguage: config.i18n?.fallbackLanguage,
+        translate: config.i18n?.translate,
+      }),
+    [config, language],
+  );
+}
+
+export function useSiteContext() {
+  const { config } = useLaconius();
+  // Subscriptions, not values: reading the store directly here would show a currency the client
+  // is no longer sending, because `resolveCurrency` drops one the config no longer offers.
+  useSiteContextStore((state) => state.language);
+  useSiteContextStore((state) => state.currency);
+  const setLanguage = useSiteContextStore((state) => state.setLanguage);
+  const setCurrency = useSiteContextStore((state) => state.setCurrency);
+  return {
+    language: resolveLanguage(config),
+    currency: resolveCurrency(config),
+    languages: config.context.languages,
+    currencies: config.context.currencies,
+    baseSite: config.backend.occ.baseSite,
+    setLanguage,
+    setCurrency,
+  };
+}
+
+/** `true` while the session store holds an access token. */
+export function useIsLoggedIn(): boolean {
+  return useSessionStore((state) => Boolean(state.accessToken));
+}
+
+/** The app owns offline UI; the provider only wires `onlineManager`. */
+export function useIsOnline(): boolean {
+  return useSyncExternalStore(
+    (onChange) => onlineManager.subscribe(onChange),
+    () => onlineManager.isOnline(),
+    () => true,
+  );
+}
+
+/**
+ * Revoke, clear, and drop Laconius' queries — never `queryClient.clear()`, which would wipe the
+ * app's own. Site context and recently-viewed deliberately survive.
+ */
+export function useLogout(): () => Promise<void> {
+  const { auth } = useLaconius();
+  const queryClient = useQueryClient();
+  return async () => {
+    await auth.logout();
+    queryClient.removeQueries({ queryKey: ['laconius'] });
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,57 @@
+import type { AuthClient } from './auth';
+import type { LaconiusHttpClient } from './client';
+import type { LaconiusConfig } from './config';
+import type { ConverterRegistry } from './converters';
+import { resolveCurrency, resolveLanguage } from './stores';
+
+/** Everything a query factory needs without a React context to read it from. */
+export type LaconiusRuntime = {
+  config: LaconiusConfig;
+  client: LaconiusHttpClient;
+  auth: AuthClient;
+  converters: ConverterRegistry;
+};
+
+let active: LaconiusRuntime | undefined;
+
+/** Set by `LaconiusProvider` during render, so factories work before any effect runs. */
+export function setActiveRuntime(runtime: LaconiusRuntime | undefined): void {
+  active = runtime;
+}
+
+/**
+ * The runtime, for `queryOptions` factories used outside React (`prefetchQuery`,
+ * `ensureQueryData`).
+ */
+export function getRuntime(): LaconiusRuntime {
+  if (!active) {
+    throw new Error(
+      '[laconius] No LaconiusProvider is mounted. Wrap your app in <LaconiusProvider config={…}>.',
+    );
+  }
+  return active;
+}
+
+/**
+ * `['laconius', <feature>, { site, lang, curr, user }, ...args]`.
+ *
+ * The context object is in every key, including product: customer-group pricing depends on the
+ * user. The `'laconius'` prefix is what makes `removeQueries(['laconius'])` safe.
+ */
+export function laconiusQueryKey(
+  feature: string,
+  ...args: unknown[]
+): unknown[] {
+  const { config, auth } = getRuntime();
+  return [
+    'laconius',
+    feature,
+    {
+      site: config.backend.occ.baseSite,
+      lang: resolveLanguage(config),
+      curr: resolveCurrency(config),
+      user: auth.getUserId(),
+    },
+    ...args,
+  ];
+}

package/src/single-flight.ts

@@ -0,0 +1,23 @@
+/**
+ * Collapses concurrent calls onto one in-flight promise: N 401s cause one refresh.
+ *
+ * The next call after settlement starts a fresh one.
+ */
+export function singleFlight<T>(fn: () => Promise<T>): () => Promise<T> {
+  let inFlight: Promise<T> | undefined;
+
+  return () => {
+    if (!inFlight) {
+      const promise = fn();
+      inFlight = promise;
+      promise
+        .finally(() => {
+          if (inFlight === promise) inFlight = undefined;
+        })
+        .catch(() => {
+          // The caller owns the rejection; this chain exists only to clear the slot.
+        });
+    }
+    return inFlight;
+  };
+}