@webority/mobile-core 0.1.0 → 0.2.0

package/lib/module/versionCheck/index.js

@@ -1 +1 @@
-import*as e from"expo-application";import{useEffect as r,useState as t}from"react";import{getConfigValue as n}from"../config/index.js";import{Logger as o}from"../logger/index.js";const i={getBundleId:()=>e.applicationId??"",getVersion:()=>e.nativeApplicationVersion??""};let a=null;export const setDeviceInfoImplementation=e=>{a=e};const missing=(e,r)=>{const t=new Error(`[VersionCheck] the app's ${e} is not available. Call setConfig({ ${r}: '...' }) — every Webority app already has this value in appsettings.Compiled.json — or setDeviceInfoImplementation() with a native provider.`);return o.error(t.message),t},getSystemName=()=>{const{Platform:e}=require("react-native");return e.OS},getBundleId=()=>{const e=n("appId");if(e)return e;const r=(a??i).getBundleId();if(r)return r;throw missing("store identifier","appId")},getCountry=()=>n("country","in").toLowerCase(),parseVersion=e=>{o.info(`Parsing version: ${e}`);const r=e.replace(/[^0-9.]/g,"").split(".").map(Number);return{major:r[0]||0,minor:r[1]||0,patch:r[2]||0,prerelease:e.includes("-")?e.split("-")[1]??"":""}},versionCompare=(e,r)=>{if(o.info(`Comparing current version: ${e} with latest version: ${r}`),!r)return{needsUpdate:!1,updateType:null,notice:"Error: could not get latest version"};try{const t=((e,r)=>{if(o.info(`Comparing versions: ${e} and ${r}`),e===r)return null;const t=parseVersion(e),n=parseVersion(r);return t.major<n.major?"major":t.major>n.major?null:t.minor<n.minor?"minor":t.minor>n.minor?null:t.patch<n.patch?"patch":t.patch>n.patch?null:t.prerelease&&!n.prerelease?"prerelease":!t.prerelease&&n.prerelease?null:t.prerelease<n.prerelease?"prerelease":(t.prerelease,n.prerelease,null)})(e,r);return{needsUpdate:!!t,updateType:t}}catch(t){const n=t instanceof Error?t.message:String(t);o.error(`Error comparing versions: ${n}`);const i=e!==r&&r>e;return{needsUpdate:i,updateType:i?"minor":null,notice:n.replace(/^Invalid Version:/,"Not a valid version:")}}},lookupVersion=async(e,r)=>{o.info(`Looking up version for platform: ${e}, identifier: ${r}`);const t=getCountry(),n="ios"===e?`https://itunes.apple.com/lookup?bundleId=${r}&country=${t}&_=${(new Date).valueOf()}`:`https://play.google.com/store/apps/details?id=${r}&hl=${t}`;return"ios"===e?(async e=>{let r;o.info(`Fetching iOS version from URL: ${e}`);try{r=await fetch(e)}catch{throw o.error("Error connecting to iTunes."),new Error("Error connecting to iTunes.")}const t=await r.json();if(!t||!("results"in t))throw o.error("Unknown error connecting to iTunes."),new Error("Unknown error connecting to iTunes.");if(!t.results.length)throw o.error("App for this bundle ID not found."),new Error("App for this bundle ID not found.");const n=t.results[0];return{version:n.version||null,released:n.currentVersionReleaseDate||n.releaseDate||null,notes:n.releaseNotes||"",url:n.trackViewUrl||n.artistViewUrl||n.sellerUrl||null,country:getCountry(),lastChecked:(new Date).toISOString()}})(n):(async e=>{let r;o.info(`Fetching Android version from URL: ${e}`);try{r=await fetch(e,{headers:{"User-Agent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36","sec-fetch-site":"same-origin"}})}catch(e){const r=e instanceof Error?e.message:String(e);throw o.error(`Error fetching data from Google Play Store: ${r}`),new Error("Error fetching data from Google Play Store.")}if(!r.ok){if(404===r.status)throw o.error("App with app ID not found in Google Play."),new Error("App with app ID not found in Google Play.");throw o.error(`Error fetching data: ${r.statusText}`),new Error(r.statusText)}const t=await r.text();let n=t.match(/\[\[\[['"]((\d+\.)+\d+)['"]\]\],/);if(n||(n=t.match(/Current Version[^\d]+((\d+\.)+\d+)/i)),n||(n=t.match(/itemprop="softwareVersion"[^>]*>((\d+\.)+\d+)</i)),!n){const e=t.match(/(\d+\.\d+(\.\d+)?)/g);n=e&&e.length>0?[null,e[0]]:null}const i=n?n[1]??null:null;i||o.warn("Could not extract version from Play Store. Using fallback method.");const a=t.match(/<div itemprop="description">(.*?)<\/div>/),s=a?a[1]??"":"";return{version:i,releasedAt:(new Date).toISOString(),notes:s,url:e,lastChecked:(new Date).toISOString()}})(n)},checkForUpdates=async()=>{const e=getSystemName().toLowerCase(),r=getBundleId(),t=(()=>{const e=n("appVersion");if(e)return e;const r=(a??i).getVersion();if(r)return r;throw missing("version","appVersion")})();let s=0,l=null;for(;s<=3;)try{o.info(`Checking if new version is available (attempt ${s+1}/4)`),o.info(`Platform: ${e}, identifier: ${r}, current version: ${t}`);const n=await lookupVersion(e,r),i=versionCompare(t,n.version);return{isNewVersionAvailable:i.needsUpdate,updateType:i.updateType,url:n.url}}catch(e){l=e;const r=e instanceof Error?e.message:String(e);if(o.error(`Error checking version (attempt ${s+1}/4): ${r}`),3===s)throw e;s++,o.info("Retrying version check in 3000ms..."),await new Promise(e=>setTimeout(e,3e3))}throw l instanceof Error?l:new Error("Failed to check for updates after multiple attempts")},getFallbackStoreUrl=()=>{const e=getSystemName().toLowerCase(),r=getBundleId(),t=getCountry();return"ios"===e?`https://apps.apple.com/${t}/app/${r}`:`https://play.google.com/store/apps/details?id=${r}&hl=${t}`};export const VersionCheck={isNewVersionAvailable:async()=>checkForUpdates(),openUpdateUrl:async e=>{const{Linking:r}=require("react-native");try{if(e)o.info(`Opening app store URL: ${e}`),await r.openURL(e);else{const e=getFallbackStoreUrl();o.info(`Opening fallback store URL: ${e}`),await r.openURL(e)}return!0}catch(t){const n=t instanceof Error?t.message:String(t);o.error(`Failed to open store URL: ${n}`);try{if(e){const e=getFallbackStoreUrl();return o.info(`Trying fallback store URL: ${e}`),await r.openURL(e),!0}}catch(e){const r=e instanceof Error?e.message:String(e);o.error(`Failed to open fallback URL: ${r}`)}return!1}},getFallbackStoreUrl:getFallbackStoreUrl};export const useVersionCheck=(e,i=n("environment","Development"))=>{const[a,s]=t({isUpdateRequired:!1,updateUrl:null});return r(()=>{let r=!0;return e&&"Production"===i&&(async()=>{try{const{isNewVersionAvailable:e,url:t}=await VersionCheck.isNewVersionAvailable();e&&r?(o.info("Update required. URL:",t||"Not available yet"),s({isUpdateRequired:!0,updateUrl:t})):r&&o.info("App is up to date")}catch(e){o.error("Error checking app version:",e)}})(),()=>{r=!1}},[e,i]),a};export default VersionCheck;
+"use strict";import*as Application from"expo-application";import{useMemo,useSyncExternalStore}from"react";import{addMinAppVersionListener,getMinAppVersion}from"../api/minAppVersion.js";import{getConfigValue}from"../config/index.js";import{Logger}from"../logger/index.js";import{isBuildBelowMinimum,parseBuildNumber}from"./buildNumber.js";const expoApplicationBackend={getBundleId:()=>Application.applicationId??"",getVersion:()=>Application.nativeApplicationVersion??"",getBuildNumber:()=>Application.nativeBuildVersion??""};let deviceInfo=null;export const setDeviceInfoImplementation=e=>{deviceInfo=e};const missing=(e,r)=>{const t=new Error(`[VersionCheck] the app's ${e} is not available. Call setConfig({ ${r}: ... }) — every Webority app already has this value in appsettings.Compiled.json — or setDeviceInfoImplementation() with a native provider.`);return Logger.error(t.message),t},getSystemName=()=>{const{Platform:e}=require("react-native");return e.OS},getBundleId=()=>{const e=getConfigValue("appId");if(e)return e;const r=(deviceInfo??expoApplicationBackend).getBundleId();if(r)return r;throw missing("store identifier","appId")},getBuildNumber=()=>{const e=parseBuildNumber(getConfigValue("appBuild"));if(null!==e)return e;const r=parseBuildNumber(deviceInfo?.getBuildNumber?.()??expoApplicationBackend.getBuildNumber());if(null!==r)return r;throw missing("build number","appBuild")},getCountry=()=>getConfigValue("country","in").toLowerCase(),subscribeMinimum=e=>addMinAppVersionListener(()=>e()),getFallbackStoreUrl=()=>{const e=getSystemName().toLowerCase(),r=getCountry();if("ios"===e){const e=getConfigValue("appStoreId");return e?`https://apps.apple.com/${r}/app/id${e}`:`https://apps.apple.com/${r}/app/${getBundleId()}`}return`https://play.google.com/store/apps/details?id=${getBundleId()}&hl=${r}`},storeUrlOrNull=()=>{try{return getFallbackStoreUrl()}catch{return null}},checkForUpdates=()=>{const e=isBuildBelowMinimum(getBuildNumber(),getMinAppVersion());return{isNewVersionAvailable:e,updateType:e?"major":null,url:e?storeUrlOrNull():null}};export const VersionCheck={isNewVersionAvailable:async()=>checkForUpdates(),openUpdateUrl:async e=>{const{Linking:r}=require("react-native");try{if(e)Logger.info(`Opening app store URL: ${e}`),await r.openURL(e);else{const e=getFallbackStoreUrl();Logger.info(`Opening fallback store URL: ${e}`),await r.openURL(e)}return!0}catch(t){const i=t instanceof Error?t.message:String(t);Logger.error(`Failed to open store URL: ${i}`);try{if(e){const e=getFallbackStoreUrl();return Logger.info(`Trying fallback store URL: ${e}`),await r.openURL(e),!0}}catch(e){const r=e instanceof Error?e.message:String(e);Logger.error(`Failed to open fallback URL: ${r}`)}return!1}},getFallbackStoreUrl:getFallbackStoreUrl};const NOT_REQUIRED={isUpdateRequired:!1,updateUrl:null};export const useVersionCheck=(e,r=getConfigValue("environment","Development"))=>{const t=useSyncExternalStore(subscribeMinimum,getMinAppVersion,getMinAppVersion);return useMemo(()=>{if(!e||"Production"!==r||null===t)return NOT_REQUIRED;try{if(!isBuildBelowMinimum(getBuildNumber(),t))return NOT_REQUIRED}catch{return NOT_REQUIRED}return{isUpdateRequired:!0,updateUrl:storeUrlOrNull()}},[e,r,t])};export default VersionCheck;export{isBuildBelowMinimum,parseBuildNumber}from"./buildNumber.js";

package/lib/typescript/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/api/tokenRefresh.d.ts

@@ -1,3 +1,4 @@
+import { type SessionEndReason } from '../auth/authStore';
 import type { UserAuthOptions } from '../initUserAuth';
 /**
  * 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/commonjs/api/userClient.d.ts

@@ -1,7 +1,7 @@
 import { type AxiosInstance } from 'axios';
 import '../types/axios';
 export type { RefreshableStore } from './tokenRefresh';
-export { injectStore, injectUserAuth, resetRefreshState } from './tokenRefresh';
+export { injectStore, injectUserAuth, resetRefreshState, SIGN_OUT_REASON_HEADER } from './tokenRefresh';
 /**
  * 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/commonjs/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/commonjs/auth/index.d.ts

@@ -1,5 +1,5 @@
-export type { StoredToken } from './authStore';
-export { getToken, removeToken, storeToken } from './authStore';
+export type { LegacyTokenKeys, SessionEndDetail, SessionEndedListener, SessionEndReason, StoredToken } from './authStore';
+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';
 export type { JwtClaims } from './jwt';
 export { decodeJWT, getJWTExpiry, isJWTExpired } from './jwt';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/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/commonjs/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/commonjs/errors/index.d.ts

@@ -0,0 +1,3 @@
+export type { ApiError } from './extractApiError';
+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';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/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/commonjs/formatters/date.d.ts

@@ -1,19 +1,19 @@
+import { type DateValue, type FormatDateOptions, type FormatDateTimeOptions, type FormatTimeOptions } from './house';
 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.

package/lib/typescript/commonjs/formatters/dateMath.d.ts

@@ -21,9 +21,11 @@ export declare const diffMs: (a: DateInput, b: DateInput) => number;
 export declare const startOfDay: (value: DateInput) => Date | null;
 /**
  * Adds (or, with a negative count, subtracts) whole calendar days in the
- * device's local timezone. Returns null for unparseable input.
+ * device's local timezone. Returns null for a missing or unparseable date or
+ * count, so the result can go straight to `formatDate`. Same name and meaning
+ * as `@webority/web-core`'s `addDays`.
  */
-export declare const addDays: (value: DateInput, count: number) => Date | null;
+export declare const addDays: (value: DateInput | null | undefined, count: number) => Date | null;
 /**
  * Small dayjs/moment-style token formatter — YYYY/YY, MMMM/MMM/MM/M,
  * DD/D, dddd/ddd, HH/H (24h), hh/h (12h), mm/m, ss/s, A/a (upper/lower AM/PM).

package/lib/typescript/commonjs/formatters/formatConfig.d.ts

@@ -0,0 +1,48 @@
+/**
+ * App-wide settings for the house formatters. This file is byte-identical in
+ * @webority/mobile-core and @webority/web-core, so a screen formats the same
+ * instant the same way on a phone and in a browser.
+ *
+ * Zone policy: an India-market product shows every instant in IST, unlabelled
+ * (the default). A product whose users span time zones opts into the viewer's
+ * own zone; times then carry a zone label so an instant is never ambiguous.
+ *
+ * Text policy: with no locale configured, every formatter prints the house
+ * text, assembled here so it reads the same on every engine ("08-Apr-2026",
+ * "8:05 PM", "1,23,456.79"). Configuring a locale hands the words and
+ * separators to Intl for that locale: month names, digit separators, the
+ * 12- or 24-hour clock and its AM/PM casing, zone names and relative phrases.
+ * The date order stays DD-MMM-YYYY either way.
+ */
+/** `'IST'`: every instant in India Standard Time. `'viewer'`: the device or browser zone, labelled. */
+export type ZoneMode = 'IST' | 'viewer';
+/** How the integer part of a number is grouped. */
+export type NumberGrouping = 'indian' | 'international' | 'none';
+export interface FormatterConfig {
+    /** Default zone for every date and time formatter. */
+    zone: ZoneMode;
+    /**
+     * BCP-47 locale. Left at its default (en-IN), it only picks the house digit
+     * grouping. Configured (`configureFormatters({ locale })`), it switches every
+     * formatter to Intl's text for that locale: en-IN gives "08-Sept-2026" and
+     * "IST", de-DE gives "1.234,5" and "20:05".
+     */
+    locale: string;
+    /** What every formatter returns for a missing or unreadable value. */
+    empty: string;
+}
+/**
+ * Set the zone mode, locale or empty placeholder for the whole app. Call it
+ * once at startup; a key left out (or undefined) keeps its current value.
+ * Passing nothing restores the defaults (IST, en-IN, "-", house text).
+ */
+export declare const configureFormatters: (config?: Partial<FormatterConfig>) => void;
+/** The settings in force, as a copy. */
+export declare const getFormatterConfig: () => FormatterConfig;
+/** Whether the app set `key` through `configureFormatters`, rather than leaving the default. */
+export declare const isFormatterConfigured: (key: keyof FormatterConfig) => boolean;
+/** The configured locale when the app set one (Intl text), else null (house text). */
+export declare const configuredLocale: () => string | null;
+/** The grouping a locale implies: Indian for a locale whose region is IN. */
+export declare const groupingForLocale: (locale: string) => NumberGrouping;
+//# sourceMappingURL=formatConfig.d.ts.map