@webority/mobile-core 0.1.0 → 0.2.1

package/lib/typescript/commonjs/redux/rootReducer.d.ts

@@ -0,0 +1,19 @@
+import { type ActionFromReducersMapObject, type Reducer, type ReducersMapObject, type StateFromReducersMapObject } from '@reduxjs/toolkit';
+/**
+ * Clears every slice, the RTK Query cache included, in one dispatch. Dispatch it on logout
+ * (decision 22). Not a tidy-up: a slice left behind paints the previous user's data on the
+ * next sign-in before fresh fetches land, which on a shared device is a data leak.
+ */
+export declare const resetState: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"app/resetState">;
+export interface RootReducerOptions<K extends string> {
+    /** Slices that survive a reset because they belong to the device, not the user (theme, onboarding seen). */
+    preserve?: readonly K[];
+}
+/**
+ * `combineReducers(reducers)` that answers `resetState` by handing every slice `undefined`,
+ * so each returns its initial state. The RTK Query api reducer is in `reducers`, so its
+ * cache empties too, and a request still in flight is dropped when it lands because its
+ * cache entry no longer exists.
+ */
+export declare function createRootReducer<M extends ReducersMapObject>(reducers: M, options?: RootReducerOptions<Extract<keyof M, string>>): Reducer<StateFromReducersMapObject<M>, ActionFromReducersMapObject<M>>;
+//# sourceMappingURL=rootReducer.d.ts.map

package/lib/typescript/commonjs/redux/serializableCheck.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Action paths the serializable check skips in every Webority store (decision 22: the check
+ * stays on and ignores named paths only). Setting `ignoredActionPaths` replaces Redux
+ * Toolkit's default list, so an app spreads this constant and appends its own paths, each
+ * with a one-line reason:
+ *
+ *   serializableCheck: { ignoredActionPaths: [...SERIALIZABLE_IGNORED_ACTION_PATHS, 'payload.at'] }
+ *
+ * `meta.arg`: a thunk's or RTK Query call's own argument, which may hold a File, a Blob or
+ * an AbortSignal and is never stored. `meta.baseQueryMeta`: the base query's request and
+ * response metadata, never stored. `ApiError` itself is plain data and needs no exemption.
+ */
+export declare const SERIALIZABLE_IGNORED_ACTION_PATHS: readonly string[];
+//# sourceMappingURL=serializableCheck.d.ts.map

package/lib/typescript/commonjs/versionCheck/buildNumber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build-number arithmetic for the server-driven update check, shared word for
+ * word by web-core and mobile-core.
+ *
+ * The API's `X-Min-App-Version` is the lowest internal build number it still
+ * supports for the calling client kind, and the app's own build number is an
+ * integer too (`VERSION_INTERNAL` on mobile, `appBuild` on web). The comparison
+ * is integer against integer, never semver against semver.
+ */
+/** A non-negative integer from a config or native value, or `null` when it is not one. */
+export declare const parseBuildNumber: (value: string | number | null | undefined) => number | null;
+/** True only when a minimum is known and the build is strictly below it. */
+export declare const isBuildBelowMinimum: (build: number, minimum: number | null) => boolean;
+//# sourceMappingURL=buildNumber.d.ts.map

package/lib/typescript/commonjs/versionCheck/index.d.ts

@@ -2,31 +2,39 @@ import { type Environment } from '../config';
 /**
  * Minimal device-info shape we depend on.
  *
- * This is a LAST RESORT, not the primary path. `Platform.OS` already gives the
- * platform, and every Webority app carries its own store id and version in
- * `appsettings.Compiled.json` — so `setConfig({ appId, appVersion })` covers
- * both remaining values without a native module. The injector below exists for
- * apps that would rather hand us a `react-native-device-info` instance than
- * wire two config keys.
+ * This is a LAST RESORT, not the primary path. Every Webority app carries its
+ * store id and build number in `appsettings.Compiled.json`, so
+ * `setConfig({ appId, appBuild })` covers both without a native module, and
+ * expo-application covers an app that wires neither. `getBuildNumber` is
+ * optional so an injector written before the server-driven check still fits;
+ * without it the build number comes from expo-application.
  */
 interface DeviceInfoLike {
     getBundleId: () => string;
     getVersion: () => string;
+    getBuildNumber?: () => string;
 }
 /**
  * Supply the app identity from a native module instead of config.
- * Prefer `setConfig({ appId, appVersion })` — it needs no native dependency.
+ * Prefer `setConfig({ appId, appBuild })` — it needs no native dependency.
  * Pass `null` to clear.
  */
 export declare const setDeviceInfoImplementation: (impl: DeviceInfoLike | null) => void;
 export type Platform = 'ios' | 'android' | string;
+/**
+ * A required update always reports `'major'`: the server states a minimum
+ * build, not the size of the change, and `'major'` is the value consumers
+ * already treat as "must update".
+ */
 export type UpdateType = 'major' | 'minor' | 'patch' | 'prerelease' | null;
+/** @deprecated Store versions are no longer parsed; the minimum is a build number. */
 export interface ParsedVersion {
     major: number;
     minor: number;
     patch: number;
     prerelease: string;
 }
+/** @deprecated The store is no longer read; the minimum comes from `X-Min-App-Version`. */
 export interface VersionData {
     version: string | null;
     released?: string | null;
@@ -36,6 +44,7 @@ export interface VersionData {
     country?: string;
     lastChecked: string;
 }
+/** @deprecated The store is no longer read; the minimum comes from `X-Min-App-Version`. */
 export interface VersionComparison {
     needsUpdate: boolean;
     updateType: UpdateType;
@@ -52,29 +61,31 @@ export interface UpdateInfo {
 }
 export interface VersionCheckType {
     /**
-     * Check if a new version is available.
-     * Includes retry logic and proper error handling.
+     * Whether this build is below the minimum the API last sent in
+     * `X-Min-App-Version`. Resolves "no update" until a reply carried one, and
+     * rejects only when the app's build number is unknown.
      */
     isNewVersionAvailable: () => Promise<VersionCheckResult>;
     /**
      * Opens the appropriate store URL to update the app.
-     * Uses the provided URL or falls back to direct store URLs.
+     * Uses the provided URL or falls back to the direct store URL.
      */
     openUpdateUrl: (url?: string | null) => Promise<boolean>;
-    /**
-     * Get the fallback store URL.
-     * Useful when URL from version check fails.
-     */
+    /** The store URL for this app on this platform. */
     getFallbackStoreUrl: () => string;
 }
 export declare const VersionCheck: VersionCheckType;
 /**
- * Custom hook to check for required app updates.
+ * Whether this build must update, from the minimum the API sends in
+ * `X-Min-App-Version`. Re-renders the moment a reply raises the minimum, so a
+ * minimum raised mid-session opens the ForceUpdateDialog without a restart.
  *
- * @param isAppReady - Whether the app is ready to perform the check
- * @param environment - The app environment (defaults to the one in config)
+ * @param isAppReady - Whether the app is ready to show the prompt
+ * @param environment - The app environment (defaults to the one in config); the
+ *   check runs in `'Production'` only
  */
 export declare const useVersionCheck: (isAppReady: boolean, environment?: Environment) => UpdateInfo;
 export default VersionCheck;
+export { isBuildBelowMinimum, parseBuildNumber } from './buildNumber';
 export type { DeviceInfoLike };
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/api/clientHeaders.d.ts

@@ -0,0 +1,25 @@
+import type { AxiosInstance } from 'axios';
+export declare const CLIENT_BUILD_HEADER = "X-Client-Build";
+export declare const CLIENT_KIND_HEADER = "X-Client-Kind";
+export declare const ACCOUNT_ID_HEADER = "X-Account-Id";
+/** The server picks session rules and the minimum version per kind; the names match its enum. */
+export type ClientKind = 'Browser' | 'MobileApp';
+export declare const CLIENT_KIND: ClientKind;
+/** `<appVersion>+<commit>`, `<appVersion>` when no commit was stamped, `null` before init. */
+export declare const getClientBuild: () => string | null;
+/**
+ * Stamps X-Client-Kind and X-Client-Build on every request. A value the app
+ * already set (a default header, or a per-request one) wins, so an app that
+ * wired them by hand keeps working unchanged.
+ */
+export declare const applyClientHeaders: (client: AxiosInstance) => void;
+export type AccountIdProvider = () => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * Sets X-Account-Id from the app's provider on every send, overwriting, so a
+ * request replayed after a refresh or an account switch carries the current
+ * account rather than the one it first went out with. `null` sends none.
+ */
+export declare const applyAccountIdHeader: (headers: {
+    set: (name: string, value: string) => unknown;
+}, provider: AccountIdProvider | undefined) => Promise<void>;
+//# sourceMappingURL=clientHeaders.d.ts.map

package/lib/typescript/module/api/minAppVersion.d.ts

@@ -0,0 +1,24 @@
+import type { AxiosInstance } from 'axios';
+/**
+ * The lowest internal build number (the integer `VERSION_INTERNAL`) the API
+ * still serves for this client kind. The API sends it on every response,
+ * errors included; cross-origin it is readable only when the API lists it in
+ * `Access-Control-Expose-Headers`.
+ */
+export declare const MIN_APP_VERSION_HEADER = "X-Min-App-Version";
+export type MinAppVersionListener = (minAppVersion: number) => void;
+/** The floor the API last named, or `null` before any response carried one. */
+export declare const getMinAppVersion: () => number | null;
+/**
+ * Called with the floor whenever it changes, and at once with the known floor
+ * when one has already arrived, so a late subscriber misses nothing. Returns
+ * the unsubscribe function. The versionCheck module is the one subscriber an
+ * app normally needs.
+ */
+export declare const addMinAppVersionListener: (listener: MinAppVersionListener) => (() => void);
+/**
+ * Reads the floor off every response the client receives, a rejected one too:
+ * a 426 Upgrade Required is exactly the case the floor exists for.
+ */
+export declare const readMinAppVersion: (client: AxiosInstance) => void;
+//# sourceMappingURL=minAppVersion.d.ts.map

package/lib/typescript/module/api/requestDefaults.d.ts

@@ -0,0 +1,21 @@
+import type { AxiosInstance } from 'axios';
+/**
+ * A fresh v4 uuid. `crypto.randomUUID` exists only in a secure context (HTTPS or localhost) and
+ * not at all on Hermes, so the id falls back to `getRandomValues`, then to `Math.random`. A
+ * correlation id only has to be unique enough to find one request in the logs; it is never a secret.
+ */
+export declare const newCorrelationId: () => string;
+/**
+ * Applies the configured timeout and the correlation id per request, read on every send so a
+ * value set after import still applies (the same reason `applyConfiguredBaseUrl` exists).
+ * - `timeoutMs`: used when the request carries no timeout of its own; a request's own axios
+ *   `timeout` wins. 0, either way, means no timeout (axios's own meaning).
+ * - `correlationIdHeader`: a fresh uuid unless the request already carries one. A retry
+ *   resends the same config, so it keeps the id the first attempt went out with.
+ *
+ * axios fills a missing `timeout` with its own default of 0, which would make "this request
+ * set none" and "this request asked for none" look alike. The client's default is therefore
+ * cleared, so an unset timeout reaches the interceptor as undefined.
+ */
+export declare const applyRequestDefaults: (client: AxiosInstance) => void;
+//# sourceMappingURL=requestDefaults.d.ts.map

package/lib/typescript/module/api/retry.d.ts

@@ -1,4 +1,4 @@
-import type { AxiosError, AxiosInstance } from 'axios';
+import { type AxiosError, type AxiosInstance } from 'axios';
 export interface RetryPolicy {
     retries?: number;
     /** `attempt` is 1-based: 1 is the first retry, not the original request. */
@@ -13,15 +13,29 @@ declare module 'axios' {
     }
 }
 /**
- * Status-based ONLY, deliberately: a bare network error (no `error.response`)
- * is never retryable. Both clients carry non-idempotent requests, login and OTP
- * on the public one and every write on the user one, and a broken connection
- * says nothing about whether the request reached the server. Retrying can
- * therefore create a second session, or a duplicate record, that the user never
- * sees. A generic network-error retry rule is not a substitute: it decides on
- * the transport alone and never looks at the HTTP method, so it retries POSTs
- * as readily as GETs.
+ * A write carrying this header asserts that the API deduplicates it, which is
+ * the only thing that makes a POST or PATCH safe to send twice.
  */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
 export declare const isRetryableStatus: (status: number | undefined) => boolean;
+export declare const isNeverSentError: (error: AxiosError) => boolean;
+/**
+ * The wait a refusal named, in milliseconds: the `Retry-After` header (seconds)
+ * or a `retryAfterSeconds` body field. `null` when it named none. Cross-origin,
+ * the header is readable only when the API lists it in `Access-Control-Expose-Headers`.
+ */
+export declare const retryAfterMs: (error: AxiosError) => number | null;
+/**
+ * The one retry rule both platforms share:
+ * - a request that provably never reached the server is resent, whatever its method;
+ * - GET, HEAD, OPTIONS, PUT and DELETE are resent on 429, any 5xx, a timeout or a
+ *   dropped connection, because a second one leaves the server as one would;
+ * - POST and PATCH are resent only on 429 or 503 (the server refused before
+ *   doing the work) AND only when they carry an `Idempotency-Key`; otherwise never;
+ * - a refusal that names a wait longer than 30 seconds is final;
+ * - a cancelled request is never resent.
+ * A request that knows better passes its own `shouldRetry`.
+ */
+export declare const isRetryableFailure: (error: AxiosError) => boolean;
 export declare const attachRetry: (client: AxiosInstance, policy?: RetryPolicy) => void;
 //# sourceMappingURL=retry.d.ts.map

package/lib/typescript/module/api/tokenRefresh.d.ts

@@ -1,3 +1,4 @@
+import { type SessionEndReason } from '../auth/authStore.js';
 import type { UserAuthOptions } from '../initUserAuth.js';
 /**
  * The one token-refresh flow in the library, run by userClient's interceptors.
@@ -27,17 +28,28 @@ export declare const injectUserAuth: (options: UserAuthOptions) => void;
  */
 export declare const resetRefreshState: () => void;
 export declare const getErrorMessage: (error: unknown) => string;
+/** The app's account-id provider, once initUserAuth has run with one. */
+export declare const getAccountIdProvider: () => UserAuthOptions["accountId"];
 /** The refresh endpoint's path, once initUserAuth has run. */
 export declare const getRefreshPath: () => string | undefined;
 export declare const dispatchLogout: () => Promise<void>;
+export declare const SIGN_OUT_REASON_HEADER = "X-Sign-Out-Reason";
+/** The server's sign-out reason from response headers (AxiosHeaders or a plain object), or null. */
+export declare const readSignOutReason: (headers: unknown) => string | null;
+/**
+ * The session is over: clear it (tokens and session user removed, listeners told why, with
+ * the server's reason), then dispatch the app's logout.
+ */
+export declare const endSessionAndLogout: (reason: SessionEndReason, signOutReason: string | null) => Promise<void>;
 export declare const isRefreshInFlight: () => boolean;
 /** Wait for the in-flight refresh without joining it: resolved or rejected by processQueue. */
 export declare const queueBehindRefresh: () => Promise<string>;
 /**
  * Refresh the access token, joining a refresh already in flight rather than
  * starting a second one. Every request queued behind it is replayed on success
- * and rejected on failure. Logs out only when the failure proves the session
- * is over; a network error, timeout or 5xx keeps it and rejects.
+ * and rejected on failure. Ends the session (`clearSession('rejected')`, then
+ * logout) only when the failure proves it is over; a network error, timeout or
+ * 5xx keeps it and rejects.
  */
 export declare const refreshAccessToken: () => Promise<string>;
 //# sourceMappingURL=tokenRefresh.d.ts.map

package/lib/typescript/module/api/userClient.d.ts

@@ -1,7 +1,7 @@
 import { type AxiosInstance } from 'axios';
 import '../types/axios.js';
 export type { RefreshableStore } from './tokenRefresh.js';
-export { injectStore, injectUserAuth, resetRefreshState } from './tokenRefresh.js';
+export { injectStore, injectUserAuth, resetRefreshState, SIGN_OUT_REASON_HEADER } from './tokenRefresh.js';
 /**
  * Thrown by the request interceptor when the device is offline, before the
  * request ever reaches the adapter (and therefore the network). Distinct from

package/lib/typescript/module/auth/authStore.d.ts

@@ -10,10 +10,56 @@
  */
 export declare const ACCESS_TOKEN_KEY = "accessToken";
 export declare const REFRESH_TOKEN_KEY = "refreshToken";
+/**
+ * Where the signed-in user's profile snapshot is kept between launches. It is
+ * not a secret, and a profile can outgrow what the keychain takes comfortably,
+ * so it lives in `Storage`, not the secure store.
+ */
+export declare const SESSION_USER_KEY = "sessionUser";
 export interface StoredToken {
     token: string;
     expiry: string;
 }
+/**
+ * Why a session ended, handed to every `addSessionEndedListener` listener.
+ * - `signedOut`: the app ended it (the default for `clearSession`).
+ * - `rejected`: the refresh endpoint refused the refresh token.
+ * - `terminated`: the API reported the session dead (security stamp, admin).
+ * - `corrupt`: a stored token could not be read back as a token.
+ * - `otherTab`: web only. Another tab signed out of the shared session; never
+ *   emitted here, declared so both platforms share one type.
+ */
+export type SessionEndReason = 'signedOut' | 'rejected' | 'terminated' | 'corrupt' | 'otherTab';
+/** What else is known about a session end, beside its reason. */
+export interface SessionEndDetail {
+    /**
+     * The server's own name for why it ended the session, from the sign-out-reason response
+     * header (`X-Sign-Out-Reason` by default, `initUserAuth({ signOutReasonHeader })`), on a
+     * terminated session or a refused refresh. `null` when the server named none, and always
+     * `null` for `signedOut` and `corrupt` unless the app passes one.
+     */
+    signOutReason: string | null;
+}
+export type SessionEndedListener = (reason: SessionEndReason, detail: SessionEndDetail) => void;
+/**
+ * The keys an app stored its session under before it adopted this library. `initUserAuth`
+ * takes them as `legacyKeys`; the first token read that finds the library's keys empty moves a
+ * session found there (see `getToken`). On mobile the token keys are secure-store services and
+ * `sessionUser` is a `Storage` key. Each token may be the bare string or the library's own
+ * `{ token, expiry }` JSON.
+ */
+export interface LegacyTokenKeys {
+    accessToken: string;
+    refreshToken: string;
+    /** The old key of the signed-in user's profile snapshot, if the app kept one. */
+    sessionUser?: string;
+}
+/**
+ * The expiry given to a migrated refresh token whose expiry the old store never kept and which
+ * is not a JWT. The server stays the judge: a refresh token it no longer honours is refused at
+ * the first refresh, which ends the session exactly as it would have ended before.
+ */
+export declare const LEGACY_REFRESH_TOKEN_LIFETIME_MS: number;
 /**
  * The shape this module speaks to its store through. expo-secure-store is
  * adapted to it below; an app or a test can supply anything else of this shape
@@ -75,5 +121,35 @@ export declare const getToken: (key: string) => Promise<StoredToken | null>;
  * Remove token by key.
  */
 export declare const removeToken: (key: string) => Promise<void>;
+/**
+ * Keep the signed-in user's profile snapshot so the app can paint the signed-in
+ * shell at launch before the profile fetch returns. Rejects when the write
+ * fails, like `storeToken`.
+ */
+export declare const storeSessionUser: <T>(user: T) => Promise<void>;
+/**
+ * The stored user, or null. An unreadable snapshot is removed and reported,
+ * but does not end the session: it is a cache the next profile fetch refills.
+ */
+export declare const getSessionUser: <T>() => Promise<T | null>;
+export declare const removeSessionUser: () => Promise<void>;
+/** Set by `initUserAuth({ legacyKeys })`; `null` turns the migration off. */
+export declare const setLegacyTokenKeys: (keys: LegacyTokenKeys | null) => void;
+/**
+ * Be told when the session ends, with the reason. Returns the unsubscribe.
+ * Fires once per session end, whichever path ended it; the app reacts here
+ * (clear its state, route to sign-in, show why) instead of each caller doing it.
+ */
+export declare const addSessionEndedListener: (listener: SessionEndedListener) => (() => void);
+/**
+ * End the session: remove both tokens and the session user, then tell every
+ * `addSessionEndedListener` listener why. Safe to call more than once: the
+ * listeners hear only the call that found a session to end, so the refresh
+ * flow and the app's own sign-out can both call it without a double event.
+ * The library calls it itself with `rejected` when the refresh endpoint refuses
+ * the refresh token and `terminated` when the API reports the session dead,
+ * with the server's sign-out reason in `detail`.
+ */
+export declare const clearSession: (reason?: SessionEndReason, detail?: Partial<SessionEndDetail>) => Promise<void>;
 export type { KeychainLike, SecureCredentials };
 //# sourceMappingURL=authStore.d.ts.map

package/lib/typescript/module/auth/index.d.ts

@@ -1,5 +1,5 @@
-export type { StoredToken } from './authStore.js';
-export { getToken, removeToken, storeToken } from './authStore.js';
+export type { LegacyTokenKeys, SessionEndDetail, SessionEndedListener, SessionEndReason, StoredToken } from './authStore.js';
+export { ACCESS_TOKEN_KEY, addSessionEndedListener, clearSession, getSessionUser, getToken, LEGACY_REFRESH_TOKEN_LIFETIME_MS, REFRESH_TOKEN_KEY, removeSessionUser, removeToken, SESSION_USER_KEY, setLegacyTokenKeys, storeSessionUser, storeToken } from './authStore.js';
 export type { JwtClaims } from './jwt.js';
 export { decodeJWT, getJWTExpiry, isJWTExpired } from './jwt.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/config/index.d.ts

@@ -2,7 +2,7 @@
  * Configuration management for Webority packages
  * Provides a flexible way to inject configuration without hard dependencies
  */
-export type LogLevel = 'info' | 'warn' | 'error';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export type Environment = 'Development' | 'Production' | 'Staging';
 export interface Config {
     /** API base URL (required before making API calls) */
@@ -15,7 +15,7 @@ export interface Config {
     environment: Environment;
     /**
      * ISO 3166-1 alpha-2 country code (lowercase) used by the version-check
-     * module to scope App Store / Play Store lookups. Defaults to `'in'`.
+     * module to build the App Store / Play Store link. Defaults to `'in'`.
      */
     country: string;
     /**
@@ -27,12 +27,38 @@ export interface Config {
     appId: string | null;
     /** The app's user-visible version string, e.g. `'1.4.2'`. Same rationale as `appId`. */
     appVersion: string | null;
+    /** The short git sha stamped into the build; with `appVersion` it makes the X-Client-Build header. */
+    commit: string | null;
+    /**
+     * The app's internal build number (`VERSION_INTERNAL`: Android versionCode,
+     * iOS CFBundleVersion). The version check compares it with the API's
+     * `X-Min-App-Version`. Falls back to expo-application when unset.
+     */
+    appBuild: number | null;
+    /**
+     * The numeric Apple App Store id (the digits after `id` in the store link).
+     * The App Store does not resolve a bundle id, so the iOS update button needs it.
+     */
+    appStoreId: string | null;
     /**
      * Log a copy-pasteable curl command for every API request. Credentials are
      * redacted either way, but this is still request-level noise, so it stays off
      * unless an app asks for it while debugging.
      */
     logCurl: boolean;
+    /**
+     * Request timeout for both clients, in milliseconds. A request overrides it with its own
+     * axios `timeout`. Default 30000.
+     */
+    timeoutMs: number;
+    /** How many times a failed request is resent under the retry rule. 0 turns retrying off. Default 3. */
+    retries: number;
+    /**
+     * Header that carries a fresh id (a uuid) on every request, for tracing one request across
+     * the app, the API and its logs. A retry keeps the id it first went out with. `null`
+     * sends none. Default `'X-Correlation-Id'`.
+     */
+    correlationIdHeader: string | null;
 }
 /**
  * Info lines (each token refresh, each unauthorised URL) reach the device log
@@ -40,6 +66,9 @@ export interface Config {
  * errors only.
  */
 export declare const DEFAULT_LOG_LEVEL: LogLevel;
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_RETRIES = 3;
+export declare const DEFAULT_CORRELATION_ID_HEADER = "X-Correlation-Id";
 /**
  * Set global configuration for all Webority packages
  */

package/lib/typescript/module/errors/extractApiError.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Normalizes any failure a thunk, a service or the RTK Query base query can see into one
+ * `ApiError`. Identical source in @webority/web-core and @webority/mobile-core.
+ *
+ * Bodies read, newest first: the fleet body `{ code, message, traceId, errors }` (D-077),
+ * where `errors` is a ModelState dictionary (`{ Field: ["msg"] }`) or a list of
+ * `{ field, message, reference }` (a refusal that names its fields),
+ * ProblemDetails `{ title, detail, errors }` from APIs not yet moved, legacy `{ error }` and
+ * `{ message }`, and a plain-text body.
+ *
+ * Message precedence is fixed (react.md): first field error, then `message`, `detail`, a
+ * legacy `error`, `title`, then `Request failed (<status>)`. `title` is last because it is
+ * the ProblemDetails category ("Bad Request"), not the curated sentence.
+ *
+ * Two things never become `message`: a 5xx body (our failure, nothing the user can act on)
+ * and anything that reads like an exception dump. The server's text goes on `detail` for
+ * the logger instead.
+ */
+export interface ApiError {
+    /** Stable snake_case branch key from the server (`not_found`, `validation_failed`). Branch on it, never render it. */
+    code: string | null;
+    /** The only user-facing string. */
+    message: string;
+    /** camelCase field path to its first message, ready for react-hook-form `setError`. */
+    fieldErrors: Record<string, string>;
+    /** HTTP status, or 0 when no response arrived. */
+    status: number;
+    /** True when no answer arrived (offline, network drop, timeout): a retry is worth offering. */
+    offline: boolean;
+    /** The server's trace id, for a support reference. */
+    traceId: string | null;
+    /** What the server or runtime actually said. For the logger, never for the screen. */
+    detail: string | null;
+}
+export declare const SERVER_FAILURE_MESSAGE = "Something went wrong on our side. Please try again in a moment.";
+export declare const OFFLINE_MESSAGE = "You appear to be offline. Check your connection and try again.";
+export declare const TIMEOUT_MESSAGE = "That took too long to respond. Check your connection and try again.";
+export declare const UNEXPECTED_MESSAGE = "Something went wrong. Please try again.";
+/** `code` for a request the caller cancelled (axios `CanceledError`). Never toasted. */
+export declare const REQUEST_CANCELED_CODE = "request_canceled";
+/** `code` for a response that failed schema validation at the service boundary. */
+export declare const CONTRACT_ERROR_CODE = "contract_error";
+/** `code` for a request that got no answer in time (axios `ECONNABORTED` / `ETIMEDOUT`). `offline` is true. */
+export declare const TIMEOUT_CODE = "timeout";
+/** `code` for a request that never reached the server (offline, DNS, CORS, a dropped connection). `offline` is true. */
+export declare const NETWORK_CODE = "network";
+/** `Items[0].UnitPrice` -> `items[0].unitPrice`; `$.email` (System.Text.Json path) -> `email`. */
+export declare const toFieldPath: (key: string) => string;
+export declare const isApiError: (value: unknown) => value is ApiError;
+export declare function extractApiError(error: unknown): ApiError;
+/**
+ * True when no answer arrived (offline, a dropped connection, a timeout), so the caller cannot
+ * tell what the server did. The same as `extractApiError(error).offline`.
+ */
+export declare const isNoResponse: (error: unknown) => boolean;
+/**
+ * The sentence a screen shows for a failure: the server's own curated message when it sent one,
+ * otherwise the screen's `fallback` ("We couldn't save the project."), otherwise the library's
+ * generic sentence. A lost answer always reads as the connection message, because "check your
+ * connection" is more accurate than any screen's fallback. A 5xx, a cancelled request and a body
+ * with no usable sentence count as "the server said nothing usable".
+ *
+ * `fallback: null` is the "say nothing" mode, for a screen that shows only what the server
+ * curated (a live panel that keeps its last result): it returns null when the server said
+ * nothing usable, and still the connection message for a lost answer.
+ */
+export declare function apiErrorMessage(error: unknown, fallback?: string): string;
+export declare function apiErrorMessage(error: unknown, fallback: string | null): string | null;
+//# sourceMappingURL=extractApiError.d.ts.map

package/lib/typescript/module/errors/index.d.ts

@@ -0,0 +1,3 @@
+export type { ApiError } from './extractApiError.js';
+export { apiErrorMessage, CONTRACT_ERROR_CODE, extractApiError, isApiError, isNoResponse, NETWORK_CODE, OFFLINE_MESSAGE, REQUEST_CANCELED_CODE, SERVER_FAILURE_MESSAGE, TIMEOUT_CODE, TIMEOUT_MESSAGE, toFieldPath, UNEXPECTED_MESSAGE } from './extractApiError.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/formatters/currency.d.ts

@@ -1,24 +1,39 @@
-export interface FormatCurrencyOptions {
+/**
+ * The currency keys plus any other `Intl.NumberFormatOptions` (`currencyDisplay`, `notation`,
+ * `signDisplay`, ...), passed through to Intl.NumberFormat.
+ */
+export interface FormatCurrencyOptions extends Omit<Intl.NumberFormatOptions, 'style' | 'currency'> {
     /** ISO 4217 currency code. Defaults to `'INR'`. */
     currency?: string;
-    /** BCP-47 locale tag. Defaults to `'en-IN'` (Indian numbering system). */
+    /** BCP-47 locale tag. Defaults to the configured locale, else `'en-IN'` (Indian numbering system). */
     locale?: string;
-    /** Minimum fraction digits. Defaults to 0 for whole amounts, 2 otherwise. */
+    /** Minimum fraction digits. Defaults to 0 for whole amounts, else the currency's own (2 for INR, 0 for JPY). */
     minimumFractionDigits?: number;
-    /** Maximum fraction digits. Defaults to 2. */
+    /** Maximum fraction digits. Defaults to the currency's own. */
     maximumFractionDigits?: number;
     /** Strip the currency symbol — useful when the symbol is rendered separately. */
     stripSymbol?: boolean;
+    /**
+     * What a missing amount prints. Defaults to the configured placeholder once the app has
+     * configured a locale or an `empty` (`configureFormatters`), else `''`.
+     */
+    empty?: string;
 }
 /**
  * Format an amount as currency. Defaults to **INR** with Indian numbering (`en-IN`),
- * which matches the standard convention across Webority projects.
+ * which matches the standard convention across Webority projects. Called with no
+ * options: "₹1,50,000" for 150000, "₹1,234.50" for 1234.5, and `''` for a missing amount.
+ * Once the app configures a locale (`configureFormatters({ locale })`), the amount is
+ * written in that locale and a missing amount prints the configured placeholder ("-").
+ * A numeric string reads as its number. For money the API carries in minor units (paise),
+ * use `formatMinor`.
  *
  * @example
  * formatCurrency(150000)            // ₹1,50,000
  * formatCurrency(1234.5)            // ₹1,234.50
- * formatCurrency(99, { currency: 'USD', locale: 'en-US' }) // $99.00
+ * formatCurrency(99, { currency: 'USD', locale: 'en-US' }) // $99
  * formatCurrency(150000, { stripSymbol: true })            // 1,50,000
+ * formatCurrency(1500000, { notation: 'compact' })         // ₹15L
  */
-export declare const formatCurrency: (amount: number | null | undefined, options?: FormatCurrencyOptions) => string;
+export declare const formatCurrency: (amount: number | string | null | undefined, options?: FormatCurrencyOptions) => string;
 //# sourceMappingURL=currency.d.ts.map

package/lib/typescript/module/formatters/date.d.ts

@@ -1,19 +1,19 @@
+import { type DateValue, type FormatDateOptions, type FormatDateTimeOptions, type FormatTimeOptions } from './house.js';
 export type DateInput = Date | string | number;
 export type DateStyle = 'short' | 'medium' | 'long' | 'full';
 export type TimeStyle = 'short' | 'medium' | 'long';
-/**
- * Locale-aware date formatter. Defaults to `'medium'` style and `'en-IN'` locale,
- * matching the Indian-locale convention used across Webority apps.
- */
-export declare const formatDate: (value: DateInput, style?: DateStyle, locale?: string) => string;
-/**
- * Locale-aware time formatter (24-hour fallback when Intl is unavailable).
- */
-export declare const formatTime: (value: DateInput, style?: TimeStyle, locale?: string) => string;
-/**
- * Combined date + time formatter.
- */
-export declare const formatDateTime: (value: DateInput, dateStyle?: DateStyle, timeStyle?: TimeStyle, locale?: string) => string;
+/** "08-Apr-2026" in the configured zone; a bare calendar date stays that day. */
+export declare function formatDate(value: DateValue, options?: FormatDateOptions): string;
+/** Intl `dateStyle` output, `'en-IN'` by default. */
+export declare function formatDate(value: DateInput, style: DateStyle, locale?: string): string;
+/** "8:05 PM" in IST, labelled in any other zone. */
+export declare function formatTime(value: DateValue, options?: FormatTimeOptions): string;
+/** Intl `timeStyle` output (24-hour fallback when Intl is unavailable). */
+export declare function formatTime(value: DateInput, style: TimeStyle, locale?: string): string;
+/** "08-Apr-2026, 8:05 PM" in IST, labelled in any other zone. */
+export declare function formatDateTime(value: DateValue, options?: FormatDateTimeOptions): string;
+/** Intl `dateStyle` + `timeStyle` output. */
+export declare function formatDateTime(value: DateInput, dateStyle: DateStyle, timeStyle?: TimeStyle, locale?: string): string;
 /**
  * Returns a humanized relative-time string (e.g. "5 minutes ago", "in 3 days").
  * Uses `Intl.RelativeTimeFormat` when available; otherwise a sensible English fallback.