@laconius/core 0.1.0

package/src/endpoints.ts

@@ -0,0 +1,133 @@
+import {
+  DEFAULT_OCC_PREFIX,
+  type EndpointValue,
+  type LaconiusConfig,
+  type LaconiusEndpoints,
+} from './config';
+
+/**
+ * Core's own endpoints: site context. Every value is a URL with its query string, never a bare
+ * path, so field selection lives in the template rather than at the call site.
+ *
+ * `baseSites` is the one endpoint built without the base-site segment.
+ */
+export const defaultCoreEndpoints: Pick<
+  LaconiusEndpoints,
+  'baseSites' | 'languages' | 'currencies' | 'countries' | 'regions'
+> = {
+  baseSites: 'basesites?fields=FULL',
+  languages: 'languages',
+  currencies: 'currencies',
+  countries: 'countries',
+  regions: 'countries/${isoCode}/regions?fields=regions(name,isocode,isocodeShort)',
+};
+
+/** Endpoints that are addressed outside the base-site segment. */
+const SITE_LESS_ENDPOINTS = new Set<string>(['baseSites']);
+
+export type EndpointParams = {
+  /** Values for `${placeholder}` segments in the template. URI-encoded on interpolation. */
+  urlParams?: Record<string, string | number>;
+  /** Merged into the query string the template already carries. Caller params win. */
+  queryParams?: Record<string, string | number | boolean | undefined>;
+};
+
+/**
+ * Named scope -> `default` scope -> plain string -> `undefined`.
+ *
+ * Spartacus' final fallback — using the endpoint key itself as the path — is deliberately
+ * dropped: it turns a configuration mistake into a mysterious 404.
+ */
+export function resolveEndpointValue(
+  endpoints: Partial<Record<string, EndpointValue>>,
+  key: string,
+  scope?: string,
+): string | undefined {
+  const value = endpoints[key];
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return value;
+  if (scope && value[scope] !== undefined) return value[scope];
+  return value['default'];
+}
+
+function interpolate(
+  template: string,
+  urlParams: Record<string, string | number> = {},
+): string {
+  return template.replace(/\$\{(\w+)\}/g, (_match, name: string) => {
+    const value = urlParams[name];
+    if (value === undefined) {
+      throw new Error(
+        `[laconius] Missing url parameter "${name}" for endpoint template "${template}".`,
+      );
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+
+/**
+ * Merges `queryParams` into the query string the template already carries, caller wins.
+ *
+ * Template values are kept verbatim — an OCC `fields` expression is already in the shape the
+ * backend wants, and re-encoding its parentheses breaks it.
+ */
+export function mergeQueryString(
+  template: string,
+  queryParams: Record<string, string | number | boolean | undefined> = {},
+): string {
+  const separator = template.indexOf('?');
+  const path = separator === -1 ? template : template.slice(0, separator);
+  const existing = separator === -1 ? '' : template.slice(separator + 1);
+
+  const params = new Map<string, string>();
+  for (const pair of existing.split('&')) {
+    if (!pair) continue;
+    const equals = pair.indexOf('=');
+    if (equals === -1) params.set(pair, '');
+    else params.set(pair.slice(0, equals), pair.slice(equals + 1));
+  }
+  for (const [key, value] of Object.entries(queryParams)) {
+    if (value === undefined) continue;
+    params.set(encodeURIComponent(key), encodeURIComponent(String(value)));
+  }
+
+  const query = [...params]
+    .map(([key, value]) => (value === '' ? key : `${key}=${value}`))
+    .join('&');
+  return query ? `${path}?${query}` : path;
+}
+
+export type EndpointResolver = {
+  /** Full URL for an endpoint key. Throws an error naming the key when it is not configured. */
+  getEndpoint(key: string, params?: EndpointParams, scope?: string): string;
+  /** Lets an adapter branch on presence instead of crashing. */
+  isConfigured(key: string, scope?: string): boolean;
+};
+
+export function createEndpointResolver(config: LaconiusConfig): EndpointResolver {
+  const endpoints = config.backend.occ.endpoints ?? {};
+  const { baseUrl, baseSite } = config.backend.occ;
+  const prefix = config.backend.occ.prefix ?? DEFAULT_OCC_PREFIX;
+
+  return {
+    isConfigured(key, scope) {
+      return resolveEndpointValue(endpoints, key, scope) !== undefined;
+    },
+    getEndpoint(key, params = {}, scope) {
+      const template = resolveEndpointValue(endpoints, key, scope);
+      if (template === undefined) {
+        throw new Error(
+          `[laconius] No endpoint configured for "${key}"${
+            scope ? ` (scope "${scope}")` : ''
+          }. Add it to backend.occ.endpoints.`,
+        );
+      }
+      const resolved = mergeQueryString(
+        interpolate(template, params.urlParams),
+        params.queryParams,
+      );
+      const site = SITE_LESS_ENDPOINTS.has(key) ? '' : `/${baseSite}`;
+      return `${baseUrl.replace(/\/$/, '')}${prefix}${site}/${resolved}`;
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,104 @@
+/** One entry of OCC's `errors[]` envelope. `type` is open-ended and customer-extensible. */
+export type OccError = {
+  type?: string;
+  reason?: string;
+  subject?: string;
+  subjectType?: string;
+  message?: string;
+};
+
+/**
+ * The one error type Laconius throws for a failed request.
+ *
+ * An OCC business error is data, not a status code: `InsufficientStockError` and a network
+ * timeout are the same `status` to a shopper who needs to be told different things.
+ */
+export class LaconiusHttpError extends Error {
+  /** 0 when the request never reached the server. */
+  readonly status: number;
+  readonly url: string;
+  /** Parsed `errors[]`, empty when the payload carried none. */
+  readonly occErrors: OccError[];
+  /** Raw payload, for the app's telemetry. */
+  readonly body?: unknown;
+
+  constructor(init: {
+    status: number;
+    url: string;
+    occErrors?: OccError[];
+    body?: unknown;
+    message?: string;
+  }) {
+    const occErrors = init.occErrors ?? [];
+    super(
+      init.message ??
+        occErrors[0]?.message ??
+        `Request to ${init.url} failed with status ${init.status}`,
+    );
+    this.name = 'LaconiusHttpError';
+    this.status = init.status;
+    this.url = init.url;
+    this.occErrors = occErrors;
+    this.body = init.body;
+  }
+}
+
+/** Parses OCC's `errors[]` envelope out of an arbitrary payload. */
+export function parseOccErrors(body: unknown): OccError[] {
+  if (typeof body !== 'object' || body === null) return [];
+  const errors = (body as { errors?: unknown }).errors;
+  if (!Array.isArray(errors)) return [];
+  return errors.filter(
+    (entry): entry is OccError => typeof entry === 'object' && entry !== null,
+  );
+}
+
+/** `getOccError(error)` for the first one, `getOccError(error, 'InsufficientStockError')` to match. */
+export function getOccError(
+  error: unknown,
+  type?: string,
+): OccError | undefined {
+  if (!(error instanceof LaconiusHttpError)) return undefined;
+  if (type === undefined) return error.occErrors[0];
+  return error.occErrors.find((occError) => occError.type === type);
+}
+
+const STATUS_KEYS: Record<number, string> = {
+  400: 'badRequest',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'notFound',
+  409: 'conflict',
+};
+
+/**
+ * A translated sentence for a shopper:
+ * OCC `type`/`reason` -> OCC `type` -> status class -> unknown.
+ *
+ * Never falls through to a raw backend string: that leaks internals and is untranslated by
+ * definition.
+ */
+export function getErrorMessage(
+  error: unknown,
+  t: (key: string, params?: Record<string, unknown>) => string,
+): string {
+  const unknown = 'errors.http.unknown';
+  if (!(error instanceof LaconiusHttpError)) return t(unknown);
+
+  const occError = error.occErrors[0];
+  if (occError?.type) {
+    if (occError.reason) {
+      const key = `errors.occ.${occError.type}.${occError.reason}`;
+      const message = t(key);
+      if (message !== key) return message;
+    }
+    const key = `errors.occ.${occError.type}`;
+    const message = t(key);
+    if (message !== key) return message;
+  }
+
+  if (error.status === 0) return t('errors.http.offline');
+  const statusKey =
+    STATUS_KEYS[error.status] ?? (error.status >= 500 ? 'serverError' : undefined);
+  return statusKey ? t(`errors.http.${statusKey}`) : t(unknown);
+}

package/src/i18n.ts

@@ -0,0 +1,108 @@
+import type { TranslationTree } from './config';
+
+const warned = new Set<string>();
+
+/**
+ * Hermes ships `Intl` on Android only, so on iOS `Intl.PluralRules` is undefined and constructing
+ * it throws — the one place where "the platform already does it" was not true.
+ *
+ * ponytail: English one/other fallback. The translations Laconius ships are English, and an app
+ * with a language whose plural rules are richer either sets `i18n.translate` or polyfills
+ * `Intl.PluralRules` (`@formatjs/intl-pluralrules`), which this picks up on its own.
+ */
+function pluralCategory(count: number, language: string): string {
+  const PluralRules = globalThis.Intl?.PluralRules;
+  if (!PluralRules) return count === 1 ? 'one' : 'other';
+  return new PluralRules(language.replace('_', '-')).select(count);
+}
+
+function isDev(): boolean {
+  return process.env.NODE_ENV !== 'production';
+}
+
+/** Dotted lookup into a nested translation chunk. */
+export function lookupKey(
+  tree: TranslationTree | undefined,
+  key: string,
+): string | undefined {
+  if (!tree) return undefined;
+  let node: string | TranslationTree | undefined = tree;
+  for (const segment of key.split('.')) {
+    if (typeof node !== 'object' || node === null) return undefined;
+    node = node[segment];
+  }
+  return typeof node === 'string' ? node : undefined;
+}
+
+/** `pt_BR` and `pt-BR` both fall back to `pt`, matching OCC's isoCode shapes. */
+function languageChain(language: string, fallbackLanguage?: string): string[] {
+  const chain = [language];
+  const base = language.split(/[-_]/)[0];
+  if (base && base !== language) chain.push(base);
+  if (fallbackLanguage && !chain.includes(fallbackLanguage)) {
+    chain.push(fallbackLanguage);
+  }
+  return chain;
+}
+
+export function interpolate(
+  template: string,
+  params: Record<string, unknown> = {},
+): string {
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, name: string) => {
+    const value = params[name];
+    return value === undefined ? match : String(value);
+  });
+}
+
+export type Translator = (
+  key: string,
+  params?: Record<string, unknown>,
+) => string;
+
+/**
+ * Key lookup, `{{param}}` interpolation and `Intl.PluralRules` — the three things Laconius
+ * needs from an i18n runtime, in place of taking one as a peer dependency.
+ *
+ * A missing key returns the key itself: warned once in development, silent in production.
+ * A blank label is invisible; a printed key is a bug report.
+ */
+export function createTranslator(options: {
+  translations?: Record<string, TranslationTree>;
+  language: string;
+  fallbackLanguage?: string;
+  /** An app that already runs an i18n runtime sets this, and Laconius resolves nothing itself. */
+  translate?: Translator;
+}): Translator {
+  if (options.translate) return options.translate;
+
+  const chain = languageChain(options.language, options.fallbackLanguage);
+
+  const resolve = (key: string): string | undefined => {
+    for (const language of chain) {
+      const value = lookupKey(options.translations?.[language], key);
+      if (value !== undefined) return value;
+    }
+    return undefined;
+  };
+
+  return (key, params) => {
+    let template: string | undefined;
+
+    const count = params?.['count'];
+    if (typeof count === 'number') {
+      const category = pluralCategory(count, options.language);
+      template = resolve(`${key}_${category}`) ?? resolve(`${key}_other`);
+    }
+    template ??= resolve(key);
+
+    if (template === undefined) {
+      if (isDev() && !warned.has(key)) {
+        warned.add(key);
+        console.warn(`[laconius] Missing translation key "${key}".`);
+      }
+      return key;
+    }
+    return interpolate(template, params);
+  };
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+export {
+  DEFAULT_OCC_PREFIX,
+  deepMerge,
+  defaultCapabilities,
+  type DeepPartial,
+  type EndpointValue,
+  type LaconiusAdapters,
+  type LaconiusAppConfig,
+  type LaconiusAuthConfig,
+  type LaconiusCmsConfig,
+  type LaconiusConfig,
+  type LaconiusConfigChunk,
+  type LaconiusConverters,
+  type LaconiusEndpoints,
+  type LaconiusUiConfig,
+  type TranslationTree,
+} from './config';
+export { coreDefaults, createLaconiusConfig } from './create-config';
+
+export {
+  createEndpointResolver,
+  defaultCoreEndpoints,
+  mergeQueryString,
+  resolveEndpointValue,
+  type EndpointParams,
+  type EndpointResolver,
+} from './endpoints';
+
+export {
+  createHttpClient,
+  type LaconiusHttpClient,
+  type LaconiusRequest,
+} from './client';
+
+export {
+  LaconiusHttpError,
+  getErrorMessage,
+  getOccError,
+  parseOccErrors,
+  type OccError,
+} from './errors';
+
+export {
+  SecureStorageError,
+  createAuthClient,
+  createDiscovery,
+  type AuthClient,
+  type TokenSet,
+} from './auth';
+
+export { singleFlight } from './single-flight';
+
+export {
+  resolveCurrency,
+  resolveLanguage,
+  selectUserId,
+  useSessionStore,
+  useSiteContextStore,
+  type SessionState,
+  type SiteContextState,
+} from './stores';
+
+export {
+  applyConverters,
+  createConverterRegistry,
+  type Converter,
+  type ConverterRegistry,
+} from './converters';
+
+export {
+  absolutizeMedia,
+  defaultMediaFormats,
+  defaultMediaRoles,
+  getFormatsUpToMaxFormat,
+  getGalleryImages,
+  getMediaBaseUrl,
+  getPrimaryImage,
+  normalizeImages,
+  resolveMediaCandidates,
+  resolveMediaUrl,
+  sortFormats,
+  type MediaContainer,
+  type MediaSource,
+} from './media';
+
+export {
+  createTranslator,
+  interpolate,
+  lookupKey,
+  type Translator,
+} from './i18n';
+export { defaultCoreTranslations } from './translations';
+
+export {
+  getRuntime,
+  laconiusQueryKey,
+  setActiveRuntime,
+  type LaconiusRuntime,
+} from './runtime';
+
+export {
+  defaultSiteContextAdapter,
+  siteContextQueries,
+  useBaseSites,
+  useCurrencies,
+  useLanguages,
+  type SiteContextAdapter,
+} from './site-context';
+
+export {
+  LaconiusProvider,
+  createDefaultQueryClient,
+  useIsLoggedIn,
+  useIsOnline,
+  useLaconius,
+  useLaconiusConfig,
+  useLogout,
+  useSiteContext,
+  useTranslation,
+  type LaconiusProviderProps,
+} from './provider';
+
+export type * from './models';

package/src/media.ts

@@ -0,0 +1,209 @@
+import type { LaconiusConfig } from './config';
+import type { Image, ImageGroup, Images } from './models';
+
+/**
+ * Format code to width in pixels, ported from Spartacus'
+ * `core-libs/storefront/recipes/config/default-media.config.ts`.
+ *
+ * The codes are widths, not device classes. Mapping a phone to `mobile` (400px) would upscale a
+ * hero 3x on a @3x screen, so nothing here maps device to format.
+ */
+export const defaultMediaFormats: Record<string, number> = {
+  cartIcon: 65,
+  thumbnail: 96,
+  product: 284,
+  mobile: 400,
+  zoom: 515,
+  tablet: 770,
+  desktop: 1140,
+  widescreen: 1400,
+};
+
+/** A role caps the candidate set; it does not select a single asset. No role means no cap. */
+export const defaultMediaRoles: Record<string, string> = {
+  cartIcon: 'cartIcon',
+  thumbnail: 'thumbnail',
+  product: 'product',
+};
+
+/** What `expo-image` accepts as one entry of an `ImageSource[]`. */
+export type MediaSource = { uri: string; width?: number; height?: number };
+
+export type MediaContainer = ImageGroup | Image | undefined;
+
+export function getMediaBaseUrl(config: LaconiusConfig): string {
+  return config.backend.media?.baseUrl ?? config.backend.occ.baseUrl;
+}
+
+/**
+ * Absolutises an OCC media path. Absolute URLs, protocol-relative URLs and `data:` URIs are
+ * returned untouched — Spartacus absolutises `data:` URIs in one of its two paths and breaks
+ * them there.
+ */
+export function resolveMediaUrl(
+  media: Image | undefined,
+  baseUrl: string,
+): string | undefined {
+  const url = media?.url;
+  if (!url) return undefined;
+  if (/^(https?:)?\/\//.test(url) || url.startsWith('data:')) return url;
+  return `${baseUrl.replace(/\/$/, '')}${url.startsWith('/') ? '' : '/'}${url}`;
+}
+
+/** Format codes ascending by width, unknown widths last in declaration order. */
+export function sortFormats(
+  formats: Record<string, number>,
+): { code: string; width: number }[] {
+  return Object.entries(formats)
+    .map(([code, width]) => ({ code, width }))
+    .sort((a, b) => a.width - b.width);
+}
+
+/**
+ * Formats up to and including `maxFormat`. An unknown `maxFormat` caps nothing, which is
+ * Spartacus' behaviour and the safe one: a typo shows a big image, not no image.
+ */
+export function getFormatsUpToMaxFormat<T extends { code: string }>(
+  formats: T[],
+  maxFormat?: string,
+): T[] {
+  const maxIndex = formats.findIndex((format) => format.code === maxFormat);
+  return maxIndex === -1 ? formats : formats.slice(0, maxIndex + 1);
+}
+
+/**
+ * The candidate set for one media container, widths attached.
+ *
+ * `expo-image` picks the source that best fits the measured container at the screen scale, so
+ * the caller never decides "which format" and never passes the container size.
+ */
+export function resolveMediaCandidates(
+  media: MediaContainer,
+  options: {
+    baseUrl: string;
+    role?: string;
+    /** Explicit cap, overriding the one the role implies. */
+    maxFormat?: string;
+    formats?: Record<string, number>;
+    roles?: Record<string, string>;
+  },
+): MediaSource[] {
+  if (!media) return [];
+
+  const formats = options.formats ?? defaultMediaFormats;
+  const roles = options.roles ?? defaultMediaRoles;
+  const cap = options.maxFormat ?? (options.role ? roles[options.role] : undefined);
+
+  const container = media as ImageGroup;
+  const known = getFormatsUpToMaxFormat(sortFormats(formats), cap).filter(
+    (format) => isImage(container[format.code]),
+  );
+
+  if (known.length > 0) {
+    return known.flatMap(({ code, width }) => {
+      const uri = resolveMediaUrl(container[code], options.baseUrl);
+      return uri ? [{ uri, width }] : [];
+    });
+  }
+
+  // A bare `Image` (CMS media often is one), or a container whose format codes are unknown.
+  const single = isImage(media) ? (media as Image) : firstImage(container);
+  const uri = resolveMediaUrl(single, options.baseUrl);
+  return uri ? [{ uri }] : [];
+}
+
+function isImage(value: unknown): value is Image {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Image).url === 'string'
+  );
+}
+
+function firstImage(container: ImageGroup): Image | undefined {
+  for (const value of Object.values(container)) {
+    if (isImage(value)) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Absolutises every media URL inside a payload, on the way in.
+ *
+ * One mechanism for CMS media and product images alike ([chapter 08](../../../docs/spec/08-media.md)),
+ * where Spartacus has two unrelated ones. The walk is shape-agnostic because media reaches the
+ * client as an `Image`, as a group keyed by format code, and as arrays of either.
+ */
+export function absolutizeMedia<T>(value: T, baseUrl: string): T {
+  if (Array.isArray(value)) {
+    return value.map((item) => absolutizeMedia(item, baseUrl)) as T;
+  }
+  if (typeof value !== 'object' || value === null) return value;
+
+  const entries = Object.entries(value as Record<string, unknown>).map(([key, item]) =>
+    isImage(item)
+      ? [key, { ...item, url: resolveMediaUrl(item, baseUrl) }]
+      : [key, absolutizeMedia(item, baseUrl)],
+  );
+  return Object.fromEntries(entries) as T;
+}
+
+/**
+ * The `PRIMARY` group of a normalized `Images`, which is what a card, a thumbnail and a gallery's
+ * first slide all want. OCC only ever sends one primary image, so an array here is a payload
+ * oddity rather than a case to support.
+ */
+export function getPrimaryImage(images: Images | undefined): ImageGroup | undefined {
+  const primary = images?.['PRIMARY'];
+  return Array.isArray(primary) ? primary[0] : primary;
+}
+
+/** The `GALLERY` groups in `galleryIndex` order, with the primary image first when there is one. */
+export function getGalleryImages(images: Images | undefined): ImageGroup[] {
+  const gallery = images?.['GALLERY'];
+  const groups = Array.isArray(gallery) ? gallery.filter(Boolean) : gallery ? [gallery] : [];
+  if (groups.length > 0) return groups;
+  const primary = getPrimaryImage(images);
+  return primary ? [primary] : [];
+}
+
+/**
+ * Reshapes OCC's flat `Image[]` into `images.PRIMARY.zoom` / `images.GALLERY[i].thumbnail`,
+ * ported from `core-libs/core/src/occ/adapters/product/converters/product-image-normalizer.ts:36-100`.
+ *
+ * Lives in core because product payloads and cart entry products carry the same flat list —
+ * one mechanism ([chapter 08](../../../docs/spec/08-media.md)), and no `cart -> product` edge
+ * exists to borrow it over ([chapter 01](../../../docs/spec/01-packages.md)).
+ *
+ * URLs are **not** absolutised here: a converter is a pure function with no access to config, so
+ * adapters absolutise the whole payload afterwards through `absolutizeMedia`.
+ */
+export function normalizeImages(source: Image[] | undefined): Images {
+  const images: Images = {};
+  for (const image of source ?? []) {
+    if (!image.imageType || !image.format) continue;
+
+    const group = groupFor(images, image);
+    group[image.format] = image;
+  }
+  return images;
+}
+
+/** `galleryIndex` is what makes an image type a list, not the type code. */
+function groupFor(images: Images, image: Image): ImageGroup {
+  const type = image.imageType as string;
+  if (image.galleryIndex === undefined) {
+    const existing = images[type];
+    if (existing && !Array.isArray(existing)) return existing;
+    const group: ImageGroup = {};
+    images[type] = group;
+    return group;
+  }
+
+  const existing = images[type];
+  const groups: ImageGroup[] = Array.isArray(existing) ? existing : [];
+  images[type] = groups;
+  const group = groups[image.galleryIndex] ?? {};
+  groups[image.galleryIndex] = group;
+  return group;
+}