@dloizides/tenant-theme-web 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@dloizides/tenant-theme-web` are documented here.
+
+## [1.0.0]
+
+### Added
+
+- Initial extraction (task #195) of the byte-identical tenant-theme stack shared by `erevna-web`
+  and `katalogos-web`:
+  - `fetchTenantTheme(tenantId, opts)` — ETag-conditional fetch + DTO -> `TenantThemeConfig` mapping
+    via an injected `httpGet` transport, an app-supplied `defaultThemeConfig` fallback palette, and
+    an optional `baseURL`.
+  - `saveTenantTheme(tenantId, config, httpPut)` + `toApiThemeRequest(config)` — the PUT body mapper.
+  - `toTenantThemeConfig` / `hasThemeData` — DTO mapper helpers.
+  - localStorage ETag cache (`readThemeCache`/`writeThemeCache`/`clearThemeCache`/
+    `clearAllThemeCaches`) with the `tenant-theme-{id}` key convention + 24h expiry, plus an
+    injectable `configureThemeCacheLogger`.
+  - The config/DTO/cache/port type surface.
+- Intentionally react-query-free: the consuming app owns its `QueryClient` and theme hooks, and the
+  theme preset VALUES stay per-app.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @dloizides/tenant-theme-web
+
+Product-agnostic RN-web **tenant-theme client** for the dloizides.com portfolio.
+
+Owns the tenant-theme logic that `erevna-web` and `katalogos-web` shared byte-for-byte:
+
+- `fetchTenantTheme(tenantId, opts)` — ETag-conditional `GET /api/tenants/{id}/theme`, mapping
+  the flat API DTO into a `TenantThemeConfig` (returns `{ themeConfig, etag, notModified }`).
+- `saveTenantTheme(tenantId, config, httpPut)` + `toApiThemeRequest(config)` — the
+  `PUT /api/tenants/{id}/theme` body mapper.
+- `toTenantThemeConfig` / `hasThemeData` — the DTO mapper helpers.
+- A localStorage **ETag cache**: `readThemeCache`, `writeThemeCache`, `clearThemeCache`,
+  `clearAllThemeCaches` (24h expiry, `tenant-theme-{id}` key convention).
+
+App-specific concerns are **ports** the consumer supplies:
+
+- the **HTTP transport** (`httpGet` / `httpPut`) — wire to the app's axios apiClient /
+  `@dloizides/bff-web-client` / Orval mutator;
+- the **theme preset VALUES** (`defaultThemeConfig`) — each product keeps its own palette;
+- the **API base URL** (`baseURL`).
+
+This package is intentionally **react-query-free** — the consuming app owns its `QueryClient` and
+its theme hooks. It never imports a product, realm, hardcoded URL, or palette.
+
+## Quick start
+
+```ts
+import {
+  fetchTenantTheme,
+  saveTenantTheme,
+  readThemeCache,
+  writeThemeCache,
+  configureThemeCacheLogger,
+  type HttpGet,
+  type HttpPut,
+} from '@dloizides/tenant-theme-web';
+
+import { DEFAULT_THEME_CONFIG } from '../theme/presets'; // app-owned palette
+import { apiClient } from '../lib/api/apiClient';
+
+// 1. Wire the transports
+const httpGet: HttpGet = (args) => apiClient.request({ method: 'GET', ...args });
+const httpPut: HttpPut = (args) => apiClient.request({ method: 'PUT', ...args }).then((r) => r.data);
+
+// 2. Optional: route cache-failure warnings to your logger
+configureThemeCacheLogger((ctx, msg, err) => loggingService.warn(ctx, msg, err));
+
+// 3. Fetch (ETag-conditional)
+const cached = readThemeCache(tenantId);
+const res = await fetchTenantTheme(tenantId, {
+  httpGet,
+  defaultThemeConfig: DEFAULT_THEME_CONFIG,
+  baseURL: env.IDENTITY_API_URL,
+  cachedEtag: cached?.etag,
+});
+if (!res.notModified && res.themeConfig) {
+  writeThemeCache(tenantId, res.themeConfig, res.etag ?? '');
+}
+
+// 4. Save
+await saveTenantTheme(tenantId, config, httpPut);
+```
+
+## Ports
+
+| Port | Type | Owned by | Notes |
+|------|------|----------|-------|
+| `httpGet` | `HttpGet` | app | Must resolve for statuses `validateStatus` accepts (2xx + 304), reject otherwise with axios-style `error.response.status`. |
+| `httpPut` | `HttpPut` | app | Resolves with the parsed response body. |
+| `defaultThemeConfig` | `TenantThemeConfig` | app | The product's `DEFAULT_THEME_CONFIG` fallback palette. |
+| `baseURL` | `string?` | app | Identity API base; omit to use the transport's own base. |
+| cache warn logger | `ThemeCacheWarn?` | app | Via `configureThemeCacheLogger`; defaults to silent. |
+
+## Scripts
+
+```bash
+npm run build      # tsup -> dual CJS/ESM + d.ts
+npm test           # jest (100% coverage gate)
+npm run lint       # eslint
+npm run typecheck  # tsc --noEmit
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,253 @@
+/**
+ * Shared types for `@dloizides/tenant-theme-web`.
+ *
+ * The package owns the tenant-theme *logic* (the ETag-conditional fetch, the
+ * DTO -> config mapper, the localStorage ETag cache, the save-request body
+ * mapper). Every app-specific concern is a **port** the consuming app supplies:
+ * its HTTP transport ({@link HttpGet} / {@link HttpPut}) and its theme preset
+ * *values* (the `defaultThemeConfig` fallback). The package never imports a
+ * product, realm, hardcoded URL, or hardcoded palette.
+ */
+/**
+ * Mode-specific color tokens shared by both light and dark configurations.
+ * All values are hex strings (e.g. '#ffffff'). The *shape* is owned by this
+ * package; the actual values per preset stay per-app.
+ */
+interface ThemeModeColors {
+    /** Page/body background */
+    background: string;
+    /** Cards, panels */
+    surface: string;
+    /** Modals, dropdowns */
+    surfaceElevated: string;
+    /** Primary text */
+    text: string;
+    /** Secondary/muted text */
+    textSecondary: string;
+    /** Default borders */
+    border: string;
+    /** Divider lines */
+    divider: string;
+}
+/** Optional semantic/status color overrides. Omitted values fall back to defaults. */
+interface SemanticColorOverrides {
+    success?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+}
+/** Optional typography overrides. */
+interface TypographyConfig {
+    /** System font family name */
+    fontFamily?: string;
+    /** Heading size multiplier (default 1.0) */
+    headingScale?: number;
+}
+/** Branding assets stored as ContentService references. */
+interface BrandingConfig {
+    /** GUID referencing a ContentService item for the logo */
+    logoContentId: string | null;
+    /** GUID referencing a ContentService item for the favicon */
+    faviconContentId: string | null;
+    /** Which built-in preset was used as the base */
+    presetId: string | null;
+}
+/**
+ * Per-tenant theme configuration. Kept flat and small (~2-5KB) since it is
+ * fetched on every app load. All color values are hex strings.
+ */
+interface TenantThemeConfig {
+    /** Brand primary color (hex) */
+    primary: string;
+    /** Brand secondary color (hex) */
+    secondary: string;
+    /** Accent/highlight color (hex) */
+    accent: string;
+    /** Optional semantic/status color overrides */
+    semantic?: SemanticColorOverrides;
+    /** Light mode tokens */
+    light: ThemeModeColors;
+    /** Dark mode tokens */
+    dark: ThemeModeColors;
+    /** Optional typography overrides */
+    typography?: TypographyConfig;
+    /** Branding assets */
+    branding: BrandingConfig;
+}
+/** Colors DTO returned by the API. */
+interface ApiThemeColorsDto {
+    primary?: string | null;
+    primaryLight?: string | null;
+    primaryDark?: string | null;
+    secondary?: string | null;
+    background?: string | null;
+    surface?: string | null;
+    error?: string | null;
+    onPrimary?: string | null;
+    onBackground?: string | null;
+    onSurface?: string | null;
+}
+/** Raw response shape from GET /api/tenants/{tenantId}/theme */
+interface ApiThemeResponseDto {
+    presetId?: string | null;
+    colors?: ApiThemeColorsDto | null;
+    darkColors?: ApiThemeColorsDto | null;
+    typography?: {
+        fontFamily?: string | null;
+        headerScale?: number | null;
+        bodyScale?: number | null;
+    } | null;
+    logoContentId?: string | null;
+    faviconContentId?: string | null;
+}
+/** Colors sub-DTO of the save (PUT) request body. */
+interface ApiThemeRequestColors {
+    primary: string;
+    secondary: string;
+    background: string;
+    surface: string;
+    error: string | null;
+    onBackground: string;
+    onSurface: string;
+}
+/** Request body for PUT /api/tenants/{tenantId}/theme. */
+interface ApiThemeRequest {
+    presetId: string | null;
+    colors: ApiThemeRequestColors;
+    darkColors: ApiThemeRequestColors;
+    typography: {
+        fontFamily: string | null;
+        headerScale: number | null;
+    } | null;
+    logoContentId: string | null;
+    faviconContentId: string | null;
+}
+/** Minimal HTTP response shape the package reads (status + data + headers). */
+interface HttpResponse<TData = unknown> {
+    status: number;
+    data: TData;
+    headers: Record<string, unknown>;
+}
+/** Arguments for the {@link HttpGet} port. */
+interface HttpGetArgs {
+    url: string;
+    baseURL?: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+    /** Treat these statuses as resolved (not thrown). Mirrors axios `validateStatus`. */
+    validateStatus: (status: number) => boolean;
+}
+/**
+ * App-supplied GET transport. The app wires this to its axios/BFF apiClient.
+ * Must resolve for any status that {@link HttpGetArgs.validateStatus} accepts,
+ * and reject (with an axios-style `error.response.status`) otherwise.
+ */
+type HttpGet = <TData = unknown>(args: HttpGetArgs) => Promise<HttpResponse<TData>>;
+/** Arguments for the {@link HttpPut} port. */
+interface HttpPutArgs<TBody = unknown> {
+    url: string;
+    headers: Record<string, string>;
+    data: TBody;
+}
+/**
+ * App-supplied PUT transport. The app wires this to its Orval mutator / BFF
+ * apiClient. Resolves with the parsed response body.
+ */
+type HttpPut = <TResp = unknown, TBody = unknown>(args: HttpPutArgs<TBody>) => Promise<TResp>;
+/** Shape of the cached theme data stored in localStorage. */
+interface CachedThemeData {
+    config: TenantThemeConfig;
+    logoUrl: string | null;
+    faviconUrl: string | null;
+    etag: string;
+    cachedAt: number;
+}
+
+/** Options for {@link fetchTenantTheme}. */
+interface FetchTenantThemeOptions {
+    signal?: AbortSignal;
+    /** Cached ETag to send as the If-None-Match header. */
+    cachedEtag?: string;
+    /** App-supplied GET transport (wire to the app's apiClient/bff-web-client). */
+    httpGet: HttpGet;
+    /** App-supplied fallback palette (the product's DEFAULT_THEME_CONFIG). */
+    defaultThemeConfig: TenantThemeConfig;
+    /** Optional API base URL. Omit to use the transport's own base. */
+    baseURL?: string;
+}
+/** Frontend-facing response shape consumed by the theme hook. */
+interface TenantThemeResponse {
+    themeConfig: TenantThemeConfig | null;
+    etag: string | null;
+    /** True when the server returned 304 Not Modified (use cached data). */
+    notModified: boolean;
+}
+/**
+ * Fetch the tenant theme configuration via the app-supplied transport and
+ * transform the API DTO into {@link TenantThemeConfig}. Returns a null config
+ * when the tenant has no theme configured (200 empty DTO or 404).
+ *
+ * Supports ETag-based conditional requests:
+ * - Pass `cachedEtag` to send the If-None-Match header
+ * - On 304 Not Modified, returns `{ notModified: true }` so the caller uses
+ *   its cached data
+ */
+declare function fetchTenantTheme(tenantId: string, options: FetchTenantThemeOptions): Promise<TenantThemeResponse>;
+
+/**
+ * Transforms a raw API DTO into a {@link TenantThemeConfig}, filling any missing
+ * field from the app-supplied `defaultThemeConfig`.
+ */
+declare function toTenantThemeConfig(dto: ApiThemeResponseDto, defaultThemeConfig: TenantThemeConfig): TenantThemeConfig;
+/** True when the DTO carries any theme payload worth mapping. */
+declare function hasThemeData(dto: ApiThemeResponseDto): boolean;
+
+/**
+ * Tenant-theme save (PUT) logic.
+ *
+ * Maps a {@link TenantThemeConfig} into the API's UpdateTenantThemeRequest body
+ * and PUTs it via the app-supplied {@link HttpPut} transport.
+ *
+ * Endpoint: PUT /api/tenants/{tenantId}/theme
+ */
+
+/** Response shape from PUT /api/tenants/{tenantId}/theme */
+interface SaveThemeResponse {
+    success: boolean;
+}
+/** Maps a frontend {@link TenantThemeConfig} to the API's request body. */
+declare function toApiThemeRequest(config: TenantThemeConfig): ApiThemeRequest;
+/**
+ * Save the tenant theme via the app-supplied PUT transport.
+ */
+declare function saveTenantTheme(tenantId: string, config: TenantThemeConfig, httpPut: HttpPut): Promise<SaveThemeResponse>;
+
+declare const CACHE_KEY_PREFIX = "tenant-theme-";
+declare const MAX_CACHE_AGE_MS: number;
+/** Minimal warn-only logger contract for cache failures. */
+type ThemeCacheWarn = (context: string, message: string, error?: unknown) => void;
+/**
+ * Supply a warn logger the cache calls when a localStorage operation fails.
+ * Pass `undefined` to revert to silent (no-op) behavior.
+ */
+declare function configureThemeCacheLogger(logger: ThemeCacheWarn | undefined): void;
+/**
+ * Read cached theme data from localStorage.
+ * Returns null if cache is missing, expired, or corrupt.
+ */
+declare function readThemeCache(tenantId: string): CachedThemeData | null;
+/**
+ * Write theme data to localStorage cache.
+ */
+declare function writeThemeCache(tenantId: string, config: TenantThemeConfig, etag: string): void;
+/**
+ * Clear cached theme data for a specific tenant.
+ */
+declare function clearThemeCache(tenantId: string): void;
+/**
+ * Clear all tenant theme caches from localStorage.
+ * Used during logout to remove any tenant-specific data.
+ */
+declare function clearAllThemeCaches(): void;
+
+export { type ApiThemeColorsDto, type ApiThemeRequest, type ApiThemeRequestColors, type ApiThemeResponseDto, type BrandingConfig, CACHE_KEY_PREFIX, type CachedThemeData, type FetchTenantThemeOptions, type HttpGet, type HttpGetArgs, type HttpPut, type HttpPutArgs, type HttpResponse, MAX_CACHE_AGE_MS, type SaveThemeResponse, type SemanticColorOverrides, type TenantThemeConfig, type TenantThemeResponse, type ThemeCacheWarn, type ThemeModeColors, type TypographyConfig, clearAllThemeCaches, clearThemeCache, configureThemeCacheLogger, fetchTenantTheme, hasThemeData, readThemeCache, saveTenantTheme, toApiThemeRequest, toTenantThemeConfig, writeThemeCache };

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Shared types for `@dloizides/tenant-theme-web`.
+ *
+ * The package owns the tenant-theme *logic* (the ETag-conditional fetch, the
+ * DTO -> config mapper, the localStorage ETag cache, the save-request body
+ * mapper). Every app-specific concern is a **port** the consuming app supplies:
+ * its HTTP transport ({@link HttpGet} / {@link HttpPut}) and its theme preset
+ * *values* (the `defaultThemeConfig` fallback). The package never imports a
+ * product, realm, hardcoded URL, or hardcoded palette.
+ */
+/**
+ * Mode-specific color tokens shared by both light and dark configurations.
+ * All values are hex strings (e.g. '#ffffff'). The *shape* is owned by this
+ * package; the actual values per preset stay per-app.
+ */
+interface ThemeModeColors {
+    /** Page/body background */
+    background: string;
+    /** Cards, panels */
+    surface: string;
+    /** Modals, dropdowns */
+    surfaceElevated: string;
+    /** Primary text */
+    text: string;
+    /** Secondary/muted text */
+    textSecondary: string;
+    /** Default borders */
+    border: string;
+    /** Divider lines */
+    divider: string;
+}
+/** Optional semantic/status color overrides. Omitted values fall back to defaults. */
+interface SemanticColorOverrides {
+    success?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+}
+/** Optional typography overrides. */
+interface TypographyConfig {
+    /** System font family name */
+    fontFamily?: string;
+    /** Heading size multiplier (default 1.0) */
+    headingScale?: number;
+}
+/** Branding assets stored as ContentService references. */
+interface BrandingConfig {
+    /** GUID referencing a ContentService item for the logo */
+    logoContentId: string | null;
+    /** GUID referencing a ContentService item for the favicon */
+    faviconContentId: string | null;
+    /** Which built-in preset was used as the base */
+    presetId: string | null;
+}
+/**
+ * Per-tenant theme configuration. Kept flat and small (~2-5KB) since it is
+ * fetched on every app load. All color values are hex strings.
+ */
+interface TenantThemeConfig {
+    /** Brand primary color (hex) */
+    primary: string;
+    /** Brand secondary color (hex) */
+    secondary: string;
+    /** Accent/highlight color (hex) */
+    accent: string;
+    /** Optional semantic/status color overrides */
+    semantic?: SemanticColorOverrides;
+    /** Light mode tokens */
+    light: ThemeModeColors;
+    /** Dark mode tokens */
+    dark: ThemeModeColors;
+    /** Optional typography overrides */
+    typography?: TypographyConfig;
+    /** Branding assets */
+    branding: BrandingConfig;
+}
+/** Colors DTO returned by the API. */
+interface ApiThemeColorsDto {
+    primary?: string | null;
+    primaryLight?: string | null;
+    primaryDark?: string | null;
+    secondary?: string | null;
+    background?: string | null;
+    surface?: string | null;
+    error?: string | null;
+    onPrimary?: string | null;
+    onBackground?: string | null;
+    onSurface?: string | null;
+}
+/** Raw response shape from GET /api/tenants/{tenantId}/theme */
+interface ApiThemeResponseDto {
+    presetId?: string | null;
+    colors?: ApiThemeColorsDto | null;
+    darkColors?: ApiThemeColorsDto | null;
+    typography?: {
+        fontFamily?: string | null;
+        headerScale?: number | null;
+        bodyScale?: number | null;
+    } | null;
+    logoContentId?: string | null;
+    faviconContentId?: string | null;
+}
+/** Colors sub-DTO of the save (PUT) request body. */
+interface ApiThemeRequestColors {
+    primary: string;
+    secondary: string;
+    background: string;
+    surface: string;
+    error: string | null;
+    onBackground: string;
+    onSurface: string;
+}
+/** Request body for PUT /api/tenants/{tenantId}/theme. */
+interface ApiThemeRequest {
+    presetId: string | null;
+    colors: ApiThemeRequestColors;
+    darkColors: ApiThemeRequestColors;
+    typography: {
+        fontFamily: string | null;
+        headerScale: number | null;
+    } | null;
+    logoContentId: string | null;
+    faviconContentId: string | null;
+}
+/** Minimal HTTP response shape the package reads (status + data + headers). */
+interface HttpResponse<TData = unknown> {
+    status: number;
+    data: TData;
+    headers: Record<string, unknown>;
+}
+/** Arguments for the {@link HttpGet} port. */
+interface HttpGetArgs {
+    url: string;
+    baseURL?: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+    /** Treat these statuses as resolved (not thrown). Mirrors axios `validateStatus`. */
+    validateStatus: (status: number) => boolean;
+}
+/**
+ * App-supplied GET transport. The app wires this to its axios/BFF apiClient.
+ * Must resolve for any status that {@link HttpGetArgs.validateStatus} accepts,
+ * and reject (with an axios-style `error.response.status`) otherwise.
+ */
+type HttpGet = <TData = unknown>(args: HttpGetArgs) => Promise<HttpResponse<TData>>;
+/** Arguments for the {@link HttpPut} port. */
+interface HttpPutArgs<TBody = unknown> {
+    url: string;
+    headers: Record<string, string>;
+    data: TBody;
+}
+/**
+ * App-supplied PUT transport. The app wires this to its Orval mutator / BFF
+ * apiClient. Resolves with the parsed response body.
+ */
+type HttpPut = <TResp = unknown, TBody = unknown>(args: HttpPutArgs<TBody>) => Promise<TResp>;
+/** Shape of the cached theme data stored in localStorage. */
+interface CachedThemeData {
+    config: TenantThemeConfig;
+    logoUrl: string | null;
+    faviconUrl: string | null;
+    etag: string;
+    cachedAt: number;
+}
+
+/** Options for {@link fetchTenantTheme}. */
+interface FetchTenantThemeOptions {
+    signal?: AbortSignal;
+    /** Cached ETag to send as the If-None-Match header. */
+    cachedEtag?: string;
+    /** App-supplied GET transport (wire to the app's apiClient/bff-web-client). */
+    httpGet: HttpGet;
+    /** App-supplied fallback palette (the product's DEFAULT_THEME_CONFIG). */
+    defaultThemeConfig: TenantThemeConfig;
+    /** Optional API base URL. Omit to use the transport's own base. */
+    baseURL?: string;
+}
+/** Frontend-facing response shape consumed by the theme hook. */
+interface TenantThemeResponse {
+    themeConfig: TenantThemeConfig | null;
+    etag: string | null;
+    /** True when the server returned 304 Not Modified (use cached data). */
+    notModified: boolean;
+}
+/**
+ * Fetch the tenant theme configuration via the app-supplied transport and
+ * transform the API DTO into {@link TenantThemeConfig}. Returns a null config
+ * when the tenant has no theme configured (200 empty DTO or 404).
+ *
+ * Supports ETag-based conditional requests:
+ * - Pass `cachedEtag` to send the If-None-Match header
+ * - On 304 Not Modified, returns `{ notModified: true }` so the caller uses
+ *   its cached data
+ */
+declare function fetchTenantTheme(tenantId: string, options: FetchTenantThemeOptions): Promise<TenantThemeResponse>;
+
+/**
+ * Transforms a raw API DTO into a {@link TenantThemeConfig}, filling any missing
+ * field from the app-supplied `defaultThemeConfig`.
+ */
+declare function toTenantThemeConfig(dto: ApiThemeResponseDto, defaultThemeConfig: TenantThemeConfig): TenantThemeConfig;
+/** True when the DTO carries any theme payload worth mapping. */
+declare function hasThemeData(dto: ApiThemeResponseDto): boolean;
+
+/**
+ * Tenant-theme save (PUT) logic.
+ *
+ * Maps a {@link TenantThemeConfig} into the API's UpdateTenantThemeRequest body
+ * and PUTs it via the app-supplied {@link HttpPut} transport.
+ *
+ * Endpoint: PUT /api/tenants/{tenantId}/theme
+ */
+
+/** Response shape from PUT /api/tenants/{tenantId}/theme */
+interface SaveThemeResponse {
+    success: boolean;
+}
+/** Maps a frontend {@link TenantThemeConfig} to the API's request body. */
+declare function toApiThemeRequest(config: TenantThemeConfig): ApiThemeRequest;
+/**
+ * Save the tenant theme via the app-supplied PUT transport.
+ */
+declare function saveTenantTheme(tenantId: string, config: TenantThemeConfig, httpPut: HttpPut): Promise<SaveThemeResponse>;
+
+declare const CACHE_KEY_PREFIX = "tenant-theme-";
+declare const MAX_CACHE_AGE_MS: number;
+/** Minimal warn-only logger contract for cache failures. */
+type ThemeCacheWarn = (context: string, message: string, error?: unknown) => void;
+/**
+ * Supply a warn logger the cache calls when a localStorage operation fails.
+ * Pass `undefined` to revert to silent (no-op) behavior.
+ */
+declare function configureThemeCacheLogger(logger: ThemeCacheWarn | undefined): void;
+/**
+ * Read cached theme data from localStorage.
+ * Returns null if cache is missing, expired, or corrupt.
+ */
+declare function readThemeCache(tenantId: string): CachedThemeData | null;
+/**
+ * Write theme data to localStorage cache.
+ */
+declare function writeThemeCache(tenantId: string, config: TenantThemeConfig, etag: string): void;
+/**
+ * Clear cached theme data for a specific tenant.
+ */
+declare function clearThemeCache(tenantId: string): void;
+/**
+ * Clear all tenant theme caches from localStorage.
+ * Used during logout to remove any tenant-specific data.
+ */
+declare function clearAllThemeCaches(): void;
+
+export { type ApiThemeColorsDto, type ApiThemeRequest, type ApiThemeRequestColors, type ApiThemeResponseDto, type BrandingConfig, CACHE_KEY_PREFIX, type CachedThemeData, type FetchTenantThemeOptions, type HttpGet, type HttpGetArgs, type HttpPut, type HttpPutArgs, type HttpResponse, MAX_CACHE_AGE_MS, type SaveThemeResponse, type SemanticColorOverrides, type TenantThemeConfig, type TenantThemeResponse, type ThemeCacheWarn, type ThemeModeColors, type TypographyConfig, clearAllThemeCaches, clearThemeCache, configureThemeCacheLogger, fetchTenantTheme, hasThemeData, readThemeCache, saveTenantTheme, toApiThemeRequest, toTenantThemeConfig, writeThemeCache };