@laconius/core 0.1.0

package/src/auth.ts

@@ -0,0 +1,223 @@
+import * as AuthSession from 'expo-auth-session';
+import * as SecureStore from 'expo-secure-store';
+
+import type { LaconiusAuthConfig, LaconiusConfig } from './config';
+import { singleFlight } from './single-flight';
+import { selectUserId, useSessionStore } from './stores';
+
+const REFRESH_TOKEN_KEY = 'laconius.refreshToken';
+
+/** Refresh-token storage failed. Treated as "no stored session", never as a crash. */
+export class SecureStorageError extends Error {
+  constructor(operation: string, cause: unknown) {
+    super(`[laconius] Secure storage ${operation} failed.`);
+    this.name = 'SecureStorageError';
+    this.cause = cause;
+  }
+}
+
+export type TokenSet = {
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch milliseconds. */
+  expiresAt?: number;
+};
+
+/**
+ * Built from config, never from the server's discovery document: that document is wrong about
+ * its own server (it never advertises `none` for token endpoint auth, which demonstrably works).
+ */
+export function createDiscovery(
+  authServerUrl: string,
+): AuthSession.DiscoveryDocument {
+  const base = authServerUrl.replace(/\/$/, '');
+  return {
+    authorizationEndpoint: `${base}/oauth/authorize`,
+    tokenEndpoint: `${base}/oauth/token`,
+    revocationEndpoint: `${base}/oauth/revoke`,
+  };
+}
+
+export type AuthClient = {
+  /** Authorization Code + PKCE. Returns the token set, or `undefined` when the user cancelled. */
+  login: () => Promise<TokenSet | undefined>;
+  logout: () => Promise<void>;
+  /** Single-flight: concurrent callers share one token request. */
+  refresh: () => Promise<TokenSet | undefined>;
+  /** Cold start: read the stored refresh token and exchange it once. */
+  hydrate: () => Promise<TokenSet | undefined>;
+  /** Refreshes proactively when the access token is within 60s of expiry. */
+  getAccessToken: () => Promise<string | undefined>;
+  getUserId: () => string;
+};
+
+const EXPIRY_SKEW_MS = 60_000;
+
+export function createAuthClient(config: LaconiusConfig): AuthClient {
+  const auth: LaconiusAuthConfig = config.auth;
+  const discovery = createDiscovery(auth.authServerUrl);
+  const report = (error: unknown) => config.onError?.(error, {});
+
+  const storeRefreshToken = async (token: string | undefined) => {
+    try {
+      if (token === undefined) {
+        await SecureStore.deleteItemAsync(REFRESH_TOKEN_KEY);
+      } else {
+        await SecureStore.setItemAsync(REFRESH_TOKEN_KEY, token, {
+          requireAuthentication: auth.requireBiometricUnlock ?? false,
+        });
+      }
+    } catch (error) {
+      report(new SecureStorageError('write', error));
+    }
+  };
+
+  const readRefreshToken = async (): Promise<string | undefined> => {
+    try {
+      return (await SecureStore.getItemAsync(REFRESH_TOKEN_KEY)) ?? undefined;
+    } catch (error) {
+      // Biometric re-enrolment invalidates the key: that is "no stored session".
+      report(new SecureStorageError('read', error));
+      return undefined;
+    }
+  };
+
+  const adopt = async (tokens: TokenSet): Promise<TokenSet> => {
+    useSessionStore.getState().setSession({
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAt: tokens.expiresAt,
+    });
+    if (tokens.refreshToken) await storeRefreshToken(tokens.refreshToken);
+    return tokens;
+  };
+
+  const fromTokenResponse = (response: AuthSession.TokenResponse): TokenSet => ({
+    accessToken: response.accessToken,
+    refreshToken: response.refreshToken,
+    expiresAt: response.expiresIn
+      ? (response.issuedAt + response.expiresIn) * 1000
+      : undefined,
+  });
+
+  const fromTokenProvider = async (): Promise<TokenSet | undefined> => {
+    if (!auth.tokenProvider) return undefined;
+    const token = await auth.tokenProvider();
+    return {
+      accessToken: token.access_token,
+      refreshToken: token.refresh_token,
+      expiresAt: Date.now() + token.expires_in * 1000,
+    };
+  };
+
+  const expire = async () => {
+    useSessionStore.getState().clearSession();
+    await storeRefreshToken(undefined);
+    auth.onAuthExpired?.();
+  };
+
+  const refresh = singleFlight(async (): Promise<TokenSet | undefined> => {
+    const refreshToken = useSessionStore.getState().refreshToken;
+    try {
+      if (refreshToken) {
+        const response = await AuthSession.refreshAsync(
+          { clientId: auth.clientId, refreshToken },
+          discovery,
+        );
+        return await adopt(fromTokenResponse(response));
+      }
+      const provided = await fromTokenProvider();
+      if (provided) return await adopt(provided);
+    } catch (error) {
+      report(error);
+    }
+    await expire();
+    return undefined;
+  });
+
+  return {
+    refresh,
+
+    async login() {
+      const provided = await fromTokenProvider();
+      if (provided) return adopt(provided);
+
+      // Imperative API, never `useAuthRequest`: refresh must be callable outside React.
+      const request = await AuthSession.loadAsync(
+        {
+          clientId: auth.clientId,
+          redirectUri: auth.redirectUri,
+          responseType: AuthSession.ResponseType.Code,
+          usePKCE: true,
+          scopes: [],
+        },
+        discovery,
+      );
+      const result = await request.promptAsync(discovery);
+      if (result.type !== 'success') return undefined;
+
+      const response = await AuthSession.exchangeCodeAsync(
+        {
+          clientId: auth.clientId,
+          redirectUri: auth.redirectUri,
+          code: result.params['code'] ?? '',
+          extraParams: request.codeVerifier
+            ? { code_verifier: request.codeVerifier }
+            : {},
+        },
+        discovery,
+      );
+      return adopt(fromTokenResponse(response));
+    },
+
+    async logout() {
+      const { accessToken, refreshToken } = useSessionStore.getState();
+      const token = refreshToken ?? accessToken;
+      if (token && discovery.revocationEndpoint) {
+        try {
+          // No Authorization header: the rebuilt authorization server reads one as *client*
+          // authentication, and a PKCE public client has no secret — the request comes back
+          // `invalid_client` and the token stays alive. Unauthenticated, revoke returns 200 and
+          // the refresh token is dead (verified live, ticket 23).
+          await fetch(discovery.revocationEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: `token=${encodeURIComponent(token)}&token_type_hint=${
+              refreshToken ? 'refresh_token' : 'access_token'
+            }&client_id=${encodeURIComponent(auth.clientId)}`,
+          });
+        } catch (error) {
+          // A failed revoke still logs out locally.
+          report(error);
+        }
+      }
+      useSessionStore.getState().clearSession();
+      await storeRefreshToken(undefined);
+    },
+
+    async hydrate() {
+      const stored = await readRefreshToken();
+      if (!stored) return undefined;
+      useSessionStore.getState().setSession({ refreshToken: stored });
+      return refresh();
+    },
+
+    async getAccessToken() {
+      const { accessToken, expiresAt } = useSessionStore.getState();
+      if (accessToken && (!expiresAt || Date.now() < expiresAt - EXPIRY_SKEW_MS)) {
+        return accessToken;
+      }
+      if (!accessToken && !useSessionStore.getState().refreshToken) {
+        return undefined;
+      }
+      return (await refresh())?.accessToken;
+    },
+
+    getUserId() {
+      const userId = selectUserId(useSessionStore.getState());
+      return (
+        auth.decorateUserId?.(userId, config.backend.occ.baseSite) ?? userId
+      );
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,133 @@
+import type { AuthClient } from './auth';
+import type { LaconiusConfig } from './config';
+import { createEndpointResolver, type EndpointResolver } from './endpoints';
+import { LaconiusHttpError, parseOccErrors } from './errors';
+import { resolveCurrency, resolveLanguage } from './stores';
+
+/** Endpoints that must never carry an `Authorization` header. */
+const ANONYMOUS_ENDPOINTS = new Set<string>(['baseSites']);
+
+export type LaconiusRequest = {
+  /** Endpoint key, resolved through `backend.occ.endpoints`. */
+  endpoint: string;
+  scope?: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  urlParams?: Record<string, string | number>;
+  queryParams?: Record<string, string | number | boolean | undefined>;
+  /** Sent as JSON. */
+  body?: unknown;
+  /** Sent as `application/x-www-form-urlencoded` (OCC wants this for product reviews). */
+  form?: Record<string, string>;
+  headers?: Record<string, string>;
+  /** Skip the `Authorization` header even when a session exists. */
+  anonymous?: boolean;
+  signal?: AbortSignal;
+};
+
+export type LaconiusHttpClient = {
+  request<T>(options: LaconiusRequest): Promise<T>;
+  endpoints: EndpointResolver;
+};
+
+/**
+ * Lives outside React so refresh and session reads work from anywhere.
+ *
+ * `lang` and `curr` are appended here rather than by adapters — the same division Spartacus
+ * draws with an interceptor.
+ */
+export function createHttpClient(
+  config: LaconiusConfig,
+  auth: AuthClient,
+): LaconiusHttpClient {
+  const endpoints = createEndpointResolver(config);
+
+  async function send<T>(options: LaconiusRequest, retrying: boolean): Promise<T> {
+    const anonymous =
+      options.anonymous || ANONYMOUS_ENDPOINTS.has(options.endpoint);
+
+    const url = endpoints.getEndpoint(
+      options.endpoint,
+      {
+        urlParams: { userId: auth.getUserId(), ...options.urlParams },
+        queryParams: {
+          lang: resolveLanguage(config),
+          curr: resolveCurrency(config),
+          ...options.queryParams,
+        },
+      },
+      options.scope,
+    );
+
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (options.form) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    } else if (options.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    if (!anonymous) {
+      const token = await auth.getAccessToken();
+      if (token) headers['Authorization'] = `Bearer ${token}`;
+    }
+    // Never overwrite a header the caller set.
+    Object.assign(headers, options.headers);
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method: options.method ?? 'GET',
+        headers,
+        body: options.form
+          ? new URLSearchParams(options.form).toString()
+          : options.body !== undefined
+            ? JSON.stringify(options.body)
+            : undefined,
+        signal: options.signal,
+      });
+    } catch (cause) {
+      const error = new LaconiusHttpError({
+        status: 0,
+        url,
+        message: cause instanceof Error ? cause.message : 'Network request failed',
+      });
+      config.onError?.(error, { url });
+      throw error;
+    }
+
+    const payload = await readPayload(response);
+
+    if (!response.ok) {
+      if (response.status === 401 && !anonymous && !retrying) {
+        const refreshed = await auth.refresh();
+        if (refreshed) return send<T>(options, true);
+      }
+      const error = new LaconiusHttpError({
+        status: response.status,
+        url,
+        occErrors: parseOccErrors(payload),
+        body: payload,
+      });
+      config.onError?.(error, { url });
+      throw error;
+    }
+
+    return payload as T;
+  }
+
+  return {
+    endpoints,
+    request(options) {
+      return send(options, false);
+    },
+  };
+}
+
+async function readPayload(response: Response): Promise<unknown> {
+  if (response.status === 204) return undefined;
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}

package/src/config.ts

@@ -0,0 +1,191 @@
+import type { ComponentType } from 'react';
+import type { QueryClient } from '@tanstack/react-query';
+
+import type { SiteContextAdapter } from './site-context';
+
+/**
+ * An endpoint value is a URL template, optionally split into named scopes.
+ * Values carry their own query string (`fields=…`); the builder merges caller params into it.
+ */
+export type EndpointValue = string | Record<string, string>;
+
+/**
+ * Endpoint keys. Feature packages add their own by declaration merging:
+ *
+ * ```ts
+ * declare module '@laconius/core' {
+ *   interface LaconiusEndpoints { productSearch: string | Record<'default' | 'carousel', string> }
+ * }
+ * ```
+ */
+export interface LaconiusEndpoints {
+  baseSites: string;
+  languages: string;
+  currencies: string;
+  countries: string;
+  regions: string;
+}
+
+/** Converter keys, extended by declaration merging exactly like endpoint keys. */
+export interface LaconiusConverters {
+  baseSite: unknown;
+  language: unknown;
+  currency: unknown;
+  country: unknown;
+  region: unknown;
+}
+
+/** Adapter slots, extended by declaration merging. Replacing one is the route to a non-OCC backend. */
+export interface LaconiusAdapters {
+  siteContext: SiteContextAdapter;
+}
+
+export type TranslationTree = { [key: string]: string | TranslationTree };
+
+/** Extended by `@laconius/ui` with themes, components and colour scheme. */
+export interface LaconiusUiConfig {
+  media?: {
+    /** Format code to width in pixels. Widths, not device classes. */
+    formats?: Record<string, number>;
+    /** Role to the largest format code that role may use. */
+    roles?: Record<string, string>;
+  };
+}
+
+/** Extended by `@laconius/cms` with the component registry and layout config. */
+export interface LaconiusCmsConfig {
+  htmlRenderer?: ComponentType<{ html: string }>;
+}
+
+export interface LaconiusAuthConfig {
+  clientId: string;
+  redirectUri: string;
+  authServerUrl: string;
+  /** Passed to `expo-secure-store` as `requireAuthentication`. Off by default. */
+  requireBiometricUnlock?: boolean;
+  /** Identity-provider slot. Laconius stores and refreshes whatever it is handed. */
+  tokenProvider?: () => Promise<{
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+  }>;
+  /** Multisite isolation hook, replacing Spartacus' `AuthMultisiteIsolationService`. */
+  decorateUserId?: (userId: string, baseSite: string) => string;
+  /** Called when the session dies. Core never navigates. */
+  onAuthExpired?: () => void;
+}
+
+export interface LaconiusConfig {
+  backend: {
+    occ: {
+      baseUrl: string;
+      baseSite: string;
+      /** Defaults to `/occ/v2`. */
+      prefix?: string;
+      endpoints?: Partial<LaconiusEndpoints>;
+    };
+    media?: { baseUrl?: string };
+    adapters?: Partial<LaconiusAdapters>;
+  };
+  auth: LaconiusAuthConfig;
+  context: {
+    languages: string[];
+    currencies: string[];
+    defaultLanguage?: string;
+    defaultCurrency?: string;
+  };
+  /** The three known version-gated endpoints. Defaults are the 221121.x baseline. */
+  capabilities?: {
+    jsonVouchers?: boolean;
+    productAvailabilities?: boolean;
+    userScopedCms?: boolean;
+  };
+  converters?: Partial<Record<keyof LaconiusConverters, unknown[]>>;
+  cms?: LaconiusCmsConfig;
+  ui?: LaconiusUiConfig;
+  i18n?: {
+    fallbackLanguage?: string;
+    translations?: Record<string, TranslationTree>;
+    /** Set this and Laconius resolves nothing itself. */
+    translate?: (key: string, params?: Record<string, unknown>) => string;
+  };
+  query?: {
+    queryClient?: QueryClient;
+    wireOnlineManager?: boolean;
+    wireFocusManager?: boolean;
+  };
+  /** Observation only: it does not render. */
+  onError?: (error: unknown, ctx: { url?: string }) => void;
+}
+
+type Primitive = string | number | boolean | symbol | bigint | null | undefined;
+
+export type DeepPartial<T> = T extends Primitive
+  ? T
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends readonly (infer _U)[]
+      ? T
+      : { [K in keyof T]?: DeepPartial<T[K]> };
+
+/** What a feature package exports as `defaultProductConfig` and friends. */
+export type LaconiusConfigChunk = DeepPartial<LaconiusConfig>;
+
+/** The app's own chunk. `backend.occ` and `auth` are what the provider refuses to start without. */
+export type LaconiusAppConfig = LaconiusConfigChunk & {
+  backend: DeepPartial<LaconiusConfig['backend']> & {
+    occ: { baseUrl: string; baseSite: string };
+  };
+  auth: LaconiusAuthConfig;
+};
+
+export const DEFAULT_OCC_PREFIX = '/occ/v2';
+
+export const defaultCapabilities = {
+  jsonVouchers: true,
+  productAvailabilities: true,
+  userScopedCms: true,
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+/**
+ * Objects deep-merge, arrays are replaced, `undefined` is ignored.
+ *
+ * Arrays are never concatenated: a default you cannot remove is a bug. Everything that would
+ * want concatenation exports a `default*` array the app spreads explicitly.
+ */
+export function deepMerge<T>(base: T, override: unknown): T {
+  if (override === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(override)) return override as T;
+
+  const result: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(override)) {
+    const next = override[key];
+    if (next === undefined) continue;
+    result[key] = isPlainObject(result[key])
+      ? deepMerge(result[key], next)
+      : next;
+  }
+  return result as T;
+}
+
+/** @internal Use `createLaconiusConfig`, which seeds core's own defaults first. */
+export function createLaconiusConfigInternal(
+  app: LaconiusAppConfig,
+  chunks: LaconiusConfigChunk[],
+): LaconiusConfig {
+  const merged = chunks.reduce<unknown>((acc, chunk) => deepMerge(acc, chunk), {});
+  const config = deepMerge(merged, app) as LaconiusConfig;
+  return {
+    ...config,
+    capabilities: { ...defaultCapabilities, ...config.capabilities },
+  };
+}

package/src/converters.ts

@@ -0,0 +1,47 @@
+import type { LaconiusConfig, LaconiusConverters } from './config';
+
+/** Spartacus' populator pattern with dependency injection removed. */
+export type Converter<S, T> = (source: S, target?: T) => T;
+
+/**
+ * Reduces a converter stack so each converter enriches the previous one's partial target.
+ *
+ * The seed is explicit because it is easy to re-derive wrong: an empty stack returns the source
+ * unchanged, and otherwise the first converter is called with `target === undefined`.
+ */
+export function applyConverters<S, T>(
+  source: S,
+  converters: readonly Converter<S, T>[] | undefined,
+): T {
+  if (!converters || converters.length === 0) {
+    return source as unknown as T;
+  }
+  return converters.reduce<T | undefined>(
+    (target, convert) => convert(source, target),
+    undefined,
+  ) as T;
+}
+
+export type ConverterRegistry = {
+  convert<S, T>(source: S, key: keyof LaconiusConverters): T;
+  convertAll<S, T>(sources: S[] | undefined, key: keyof LaconiusConverters): T[];
+};
+
+/** Converters are registered by explicit spread of a feature's exported defaults. */
+export function createConverterRegistry(
+  config: LaconiusConfig,
+): ConverterRegistry {
+  const registered = config.converters ?? {};
+  const stackFor = <S, T>(key: keyof LaconiusConverters) =>
+    registered[key] as readonly Converter<S, T>[] | undefined;
+
+  return {
+    convert<S, T>(source: S, key: keyof LaconiusConverters) {
+      return applyConverters<S, T>(source, stackFor<S, T>(key));
+    },
+    convertAll<S, T>(sources: S[] | undefined, key: keyof LaconiusConverters) {
+      const converters = stackFor<S, T>(key);
+      return (sources ?? []).map((source) => applyConverters<S, T>(source, converters));
+    },
+  };
+}

package/src/create-config.ts

@@ -0,0 +1,29 @@
+import {
+  createLaconiusConfigInternal,
+  type LaconiusAppConfig,
+  type LaconiusConfig,
+  type LaconiusConfigChunk,
+} from './config';
+import { defaultCoreEndpoints } from './endpoints';
+import { defaultMediaFormats, defaultMediaRoles } from './media';
+import { defaultCoreTranslations } from './translations';
+
+/** What core contributes before any feature chunk: its endpoints, media table and strings. */
+export const coreDefaults: LaconiusConfigChunk = {
+  backend: { occ: { endpoints: defaultCoreEndpoints } },
+  ui: { media: { formats: defaultMediaFormats, roles: defaultMediaRoles } },
+  i18n: { fallbackLanguage: 'en', translations: defaultCoreTranslations },
+};
+
+/**
+ * Deep-merges core's defaults, then the feature chunks in order, then the app chunk last, so an
+ * override is written where the reader expects it.
+ *
+ * Objects deep-merge, arrays are replaced, `undefined` is ignored.
+ */
+export function createLaconiusConfig(
+  app: LaconiusAppConfig,
+  featureChunks: LaconiusConfigChunk[] = [],
+): LaconiusConfig {
+  return createLaconiusConfigInternal(app, [coreDefaults, ...featureChunks]);
+}