@webority-technologies/mobile-core 0.0.1 → 0.0.3

package/lib/module/storage/index.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import KvStore from 'expo-sqlite/kv-store';
 import { Logger } from "../logger/index.js";
 
 /**
@@ -7,25 +8,31 @@ import { Logger } from "../logger/index.js";
  * Lets us avoid a hard import on `@react-native-async-storage/async-storage`.
  */
 
+/** Only what a test or the showcase injected; null means use expo-sqlite/kv-store. */
 let backend = null;
-let resolved = false;
-const resolveBackend = () => {
-  if (resolved) {
-    return backend;
-  }
-  resolved = true;
-  try {
-    const mod = require('@react-native-async-storage/async-storage');
-    backend = mod.default ?? mod;
-  } catch {
-    backend = null;
-  }
-  return backend;
-};
+
+/**
+ * expo-sqlite's key/value store, imported directly.
+ *
+ * It deliberately implements the AsyncStorage v1 surface — `getItem`,
+ * `setItem`, `removeItem`, `multiGet`, `multiSet`, `multiRemove`, `clear`,
+ * `getAllKeys`, with v1's shapes — which is exactly what this module already
+ * speaks, so there is nothing to convert. Verified against expo-sqlite 57.0.2.
+ */
+const resolveBackend = () => backend ?? KvStore;
+
+/**
+ * Always true now that the backend ships with the library. Kept because callers
+ * whose use of storage is an OPTIMISATION branch on it, and removing it would
+ * be a breaking change for no gain.
+ */
+export const isStorageAvailable = () => resolveBackend() !== null;
 const requireBackend = op => {
   const b = resolveBackend();
   if (!b) {
-    const err = new Error(`[Storage] @react-native-async-storage/async-storage is not installed; cannot ${op}. ` + 'Install the peer dep or call setStorageImplementation() with a custom backend.');
+    // Only reachable if a caller injected something falsy; the default backend
+    // ships with the library, so there is no "not installed" case any more.
+    const err = new Error(`[Storage] no storage backend available; cannot ${op}.`);
     Logger.error(err.message);
     throw err;
   }
@@ -33,12 +40,11 @@ const requireBackend = op => {
 };
 
 /**
- * Inject a custom storage backend (e.g. MMKV adapter) at runtime.
- * Pass `null` to reset to the default AsyncStorage backend.
+ * Replace the storage backend. Intended for TESTS and for the showcase; an app
+ * gets expo-sqlite/kv-store without wiring anything. Pass `null` to restore it.
  */
 export const setStorageImplementation = impl => {
   backend = impl;
-  resolved = true;
 };
 const safeJsonParse = raw => {
   if (raw == null) {
@@ -92,6 +98,10 @@ const setJson = async (key, value) => {
 const multiGet = async keys => {
   try {
     const b = requireBackend('multiGet');
+    // v3 first: its Record is already this function's return shape.
+    if (b.getMany) {
+      return await b.getMany([...keys]);
+    }
     if (!b.multiGet) {
       const out = {};
       await Promise.all(keys.map(async k => {
@@ -113,6 +123,11 @@ const multiGet = async keys => {
 const multiSet = async entries => {
   try {
     const b = requireBackend('multiSet');
+    // v3 first: it takes the Record this function already receives.
+    if (b.setMany) {
+      await b.setMany(entries);
+      return true;
+    }
     const pairs = Object.entries(entries);
     if (!b.multiSet) {
       await Promise.all(pairs.map(([k, v]) => b.setItem(k, v)));
@@ -128,6 +143,10 @@ const multiSet = async entries => {
 const multiRemove = async keys => {
   try {
     const b = requireBackend('multiRemove');
+    if (b.removeMany) {
+      await b.removeMany([...keys]);
+      return true;
+    }
     if (!b.multiRemove) {
       await Promise.all(keys.map(k => b.removeItem(k)));
       return true;
@@ -171,7 +190,7 @@ const getAllKeys = async () => {
  * All operations swallow errors (logging them) and return a falsy result
  * so that storage problems never crash the app.
  *
- * Backed by `@react-native-async-storage/async-storage` by default;
+ * Backed by `expo-sqlite/kv-store` by default;
  * override with `setStorageImplementation()` for MMKV or custom adapters.
  */
 export const Storage = {

package/lib/module/types/globals.d.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * The expo-application jest mock is exposed on globalThis so a test can blank a
+ * value to reach the "no identity anywhere" path. expo ships these as module
+ * constants, which cannot be reassigned through the ES binding from a test file.
+ */
+
+export {};
+//# sourceMappingURL=globals.d.js.map

package/lib/module/utils/imageCompression.js

@@ -1,20 +1,56 @@
 "use strict";
 
+import { ImageManipulator } from 'expo-image-manipulator';
 import { Logger } from "../logger/index.js";
-let compressor = null;
-let resolved = false;
-const resolveCompressor = () => {
-  if (resolved) {
-    return compressor;
-  }
-  resolved = true;
-  try {
-    compressor = require('react-native-compressor');
-  } catch {
-    Logger.warn('[imageCompression] react-native-compressor is not installed; ' + 'compressImage() will return the original URI unchanged.');
-    compressor = null;
+/** expo's SaveFormat values, inlined to keep this file free of enum imports. */
+const EXPO_FORMAT = {
+  jpg: 'jpeg',
+  png: 'png',
+  webp: 'webp'
+};
+
+/**
+ * expo-image-manipulator, adapted to the compressor shape this module speaks.
+ *
+ * Written against the CONTEXTUAL api rather than `manipulateAsync`, which 57
+ * marks deprecated. Only ONE edge is constrained: expo treats a given width and
+ * height as targets and would distort the image, where maxWidth/maxHeight here
+ * mean a box to fit inside. The smaller bound is used so the result fits
+ * whichever way round the image is.
+ */
+const expoCompressorBackend = {
+  Image: {
+    compress: async (uri, options) => {
+      const context = ImageManipulator.manipulate(uri);
+      const {
+        maxWidth,
+        maxHeight
+      } = options;
+      if (typeof maxWidth === 'number' || typeof maxHeight === 'number') {
+        context.resize({
+          width: Math.min(maxWidth ?? Number.POSITIVE_INFINITY, maxHeight ?? Number.POSITIVE_INFINITY)
+        });
+      }
+      const image = await context.renderAsync();
+      const result = await image.saveAsync({
+        compress: options.quality,
+        format: EXPO_FORMAT[options.output ?? 'jpg'] ?? 'jpeg'
+      });
+      return result.uri;
+    }
   }
-  return compressor;
+};
+
+/** Only what a test or the showcase injected; null means use expo-image-manipulator. */
+let compressor = null;
+const resolveCompressor = () => compressor ?? expoCompressorBackend;
+
+/**
+ * Replace the compressor. Intended for TESTS and for the showcase; an app gets
+ * expo-image-manipulator without wiring anything. Pass `null` to restore it.
+ */
+export const setImageCompressorImplementation = impl => {
+  compressor = impl;
 };
 const EIGHT_MB = 8 * 1024 * 1024;
 const THREE_MB = 3 * 1024 * 1024;

package/lib/module/utils/index.js

@@ -1,4 +1,4 @@
 "use strict";
 
-export { compressImage } from "./imageCompression.js";
+export { compressImage, setImageCompressorImplementation } from "./imageCompression.js";
 //# sourceMappingURL=index.js.map

package/lib/module/versionCheck/index.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import * as Application from 'expo-application';
 import { useEffect, useState } from 'react';
 // Type-only — erased at compile time; react-native stays lazily required below.
 
@@ -17,6 +18,26 @@ import { Logger } from "../logger/index.js";
  * wire two config keys.
  */
 
+/**
+ * expo-application, read at call time.
+ *
+ * `applicationId` and `nativeApplicationVersion` are module CONSTANTS rather
+ * than functions, so they are read inside the accessors rather than captured
+ * here — capturing would snapshot them before the native module has
+ * initialised.
+ *
+ * `setConfig({ appId, appVersion })` still WINS over this: a Webority app
+ * already carries both in appsettings.Compiled.json, and config is checked
+ * first. This is the fallback for an app that would rather read its identity
+ * from the binary it is actually running, which is the one place the two can
+ * disagree.
+ */
+const expoApplicationBackend = {
+  getBundleId: () => Application.applicationId ?? '',
+  getVersion: () => Application.nativeApplicationVersion ?? ''
+};
+
+/** Only what a test or the showcase injected; null means use expo-application. */
 let deviceInfo = null;
 
 /**
@@ -46,8 +67,9 @@ const getBundleId = () => {
   if (fromConfig) {
     return fromConfig;
   }
-  if (deviceInfo) {
-    return deviceInfo.getBundleId();
+  const fromDevice = (deviceInfo ?? expoApplicationBackend).getBundleId();
+  if (fromDevice) {
+    return fromDevice;
   }
   throw missing('store identifier', 'appId');
 };
@@ -56,8 +78,9 @@ const getVersion = () => {
   if (fromConfig) {
     return fromConfig;
   }
-  if (deviceInfo) {
-    return deviceInfo.getVersion();
+  const fromDevice = (deviceInfo ?? expoApplicationBackend).getVersion();
+  if (fromDevice) {
+    return fromDevice;
   }
   throw missing('version', 'appVersion');
 };

package/lib/typescript/commonjs/api/baseUrl.d.ts

@@ -0,0 +1,20 @@
+import type { AxiosInstance } from 'axios';
+/**
+ * Resolves `baseURL` PER REQUEST rather than at module evaluation.
+ *
+ * `axios.create({ baseURL: getConfigValue('baseUrl') })` reads the value once,
+ * when the module is first imported — which happens the moment anything touches
+ * the package barrel, long before an app's startup code can call `setConfig`.
+ * The result was a client permanently pinned to `undefined` and a `setConfig`
+ * that appeared to do nothing, with no error anywhere: requests just went to a
+ * relative URL.
+ *
+ * A consumer cannot fix that by ordering its own imports, because the import
+ * that loses the race is usually one it never wrote. So the clients stop
+ * capturing the value and ask for it per request instead.
+ *
+ * An explicit per-request `baseURL` still wins, which is what keeps a one-off
+ * call to a different host possible.
+ */
+export declare const applyConfiguredBaseUrl: (client: AxiosInstance) => void;
+//# sourceMappingURL=baseUrl.d.ts.map

package/lib/typescript/commonjs/api/curl.d.ts

@@ -0,0 +1,18 @@
+import type { AxiosRequestConfig } from 'axios';
+/**
+ * Builds a copy-pasteable curl command for a request, with every credential
+ * replaced by a placeholder.
+ *
+ * The redaction is the point, not a nicety. An unredacted version of this in a
+ * consumer app put `Authorization: Bearer <token>` and the login request's
+ * plaintext password into the device console of a *release* staging build.
+ * A curl line is worth having; a curl line that has to be trusted not to be
+ * enabled in the wrong build is not.
+ */
+export declare const buildCurl: (config: AxiosRequestConfig) => string;
+/**
+ * Logs the curl equivalent of a request. Never throws: a failure to describe a
+ * request must not be able to fail the request itself.
+ */
+export declare const logCurl: (config: AxiosRequestConfig) => void;
+//# sourceMappingURL=curl.d.ts.map

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

@@ -0,0 +1,27 @@
+import type { AxiosError, AxiosInstance } from 'axios';
+export interface RetryPolicy {
+    retries?: number;
+    /** `attempt` is 1-based: 1 is the first retry, not the original request. */
+    retryDelayMs?: (attempt: number) => number;
+    shouldRetry?: (error: AxiosError) => boolean;
+    onRetry?: (attempt: number, error: AxiosError) => void;
+}
+declare module 'axios' {
+    interface AxiosRequestConfig {
+        /** `false` opts a single request out of retrying; an object overrides the client policy. */
+        retry?: boolean | RetryPolicy;
+    }
+}
+/**
+ * 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.
+ */
+export declare const isRetryableStatus: (status: number | undefined) => boolean;
+export declare const attachRetry: (client: AxiosInstance, policy?: RetryPolicy) => void;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -45,5 +45,16 @@ export interface RefreshableStore {
 declare const userClient: AxiosInstance;
 export declare const injectStore: <S>(_store: S) => void;
 export declare const injectAuthActions: (actions: AuthActions) => void;
+/**
+ * Clear any in-flight token refresh and reject everything queued behind it.
+ * Call this on logout.
+ *
+ * Without it, a refresh that was already in flight when the user logged out
+ * resolves afterwards and replays every queued request with a token for a
+ * session that has ended. The queue is module state, so it survives the logout
+ * entirely: nothing else clears it. A consumer app hit this and hand-wrote the
+ * same function locally, which is how it was found.
+ */
+export declare const resetRefreshState: () => void;
 export default userClient;
 //# sourceMappingURL=userClient.d.ts.map

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

@@ -2,6 +2,15 @@ import type * as KeychainModule from 'react-native-keychain';
 /**
  * Token data persisted in the keychain.
  */
+/**
+ * The two keys the library itself reads. Everything in the library that needs
+ * the bearer token, the HTTP client, the download module and the authenticated
+ * image cache, resolves it through these rather than repeating the literal, so
+ * one of them cannot silently drift and start reading a key nothing writes.
+ * Apps are free to store their own tokens under any other key.
+ */
+export declare const ACCESS_TOKEN_KEY = "accessToken";
+export declare const REFRESH_TOKEN_KEY = "refreshToken";
 export interface StoredToken {
     token: string;
     expiry: string;
@@ -11,20 +20,34 @@ export interface StoredToken {
  * Lets us avoid a hard import on `react-native-keychain`, so an app that never
  * stores a token does not have to install it.
  */
+/**
+ * The GENERIC password API, not the internet-credentials one.
+ *
+ * `kSecClassInternetPassword` exists for credentials bound to a server, protocol
+ * and port, and it integrates with Safari and AutoFill. A bearer token keyed by
+ * a name like "accessToken" is none of those things, and the library was only
+ * satisfying that API's required `server` argument by passing the key twice,
+ * once as the server and once as the service. That is misuse of the class.
+ *
+ * `kSecClassGenericPassword` is the class for app-local secrets, which is what a
+ * token is. It is what expo-secure-store uses underneath, and what the consumer
+ * app being migrated had already chosen for itself.
+ */
 interface KeychainLike {
-    setInternetCredentials: (server: string, username: string, password: string, options?: {
+    setGenericPassword: (username: string, password: string, options?: {
         service?: string;
     }) => Promise<unknown>;
-    getInternetCredentials: (server: string, options?: {
+    getGenericPassword: (options?: {
         service?: string;
     }) => Promise<KeychainModule.UserCredentials | false>;
-    resetInternetCredentials: (options: {
-        service: string;
+    resetGenericPassword: (options?: {
+        service?: string;
     }) => Promise<unknown>;
 }
 /**
- * Inject a custom keychain backend at runtime.
- * Pass `null` to reset to the default react-native-keychain backend.
+ * Replace the secure-store backend. Intended for TESTS and for the showcase,
+ * which injects a failing store to demo the write-failure path; it is not how
+ * an app configures the library. Pass `null` to restore expo-secure-store.
  */
 export declare const setKeychainImplementation: (impl: KeychainLike | null) => void;
 /**

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

@@ -27,6 +27,12 @@ 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;
+    /**
+     * 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;
 }
 /**
  * Set global configuration for all Webority packages

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

@@ -0,0 +1,54 @@
+export interface ParsedLink {
+    /** The original URL, trimmed. */
+    url: string;
+    /** Lower-cased scheme without `://`, or '' when the URL carried none. */
+    scheme: string;
+    /**
+     * The authority for http(s) URLs. Custom schemes put the first route segment
+     * there (`myapp://order/12`), so for those `host` is `segments[0]` and stays
+     * part of `path` so one route pattern matches both link shapes.
+     */
+    host: string;
+    /** Route path with no leading or trailing slash. */
+    path: string;
+    segments: string[];
+    /** Query values, decoded. A repeated key keeps its last occurrence. */
+    query: Record<string, string>;
+}
+export interface DeepLinkRoute {
+    /** A path pattern with `:param` segments (`order/:id`), or a RegExp on `path`. */
+    match: string | RegExp;
+    requiresAuth?: boolean;
+    handler: (link: ParsedLink, params: Record<string, string>) => void;
+}
+export interface DeepLinkConfig {
+    routes: DeepLinkRoute[];
+    /** Navigator readiness. Links arriving before this is true are queued. */
+    isReady?: () => boolean;
+    isAuthenticated?: () => boolean;
+    /** Called when an auth-gated link is stashed; the app sends the user to login. */
+    onUnauthenticated?: (link: ParsedLink) => void;
+    onUnmatched?: (link: ParsedLink) => void;
+}
+/**
+ * Parse a deep-link URL. Returns null for anything that is not a usable URL so
+ * a hostile or truncated link can never throw on the native event path.
+ */
+export declare const parseDeepLink: (url: string) => ParsedLink | null;
+export declare const DeepLink: {
+    configure: (next: DeepLinkConfig) => void;
+    start: () => Promise<void>;
+    stop: () => void;
+    handleUrl: (url: string) => void;
+    setReady: (ready: boolean) => void;
+    /** Replay the stashed link, once. Call after a successful login. */
+    replayPending: () => void;
+    getPending: () => ParsedLink | null;
+};
+/**
+ * Configure and start the deep-link service for the lifetime of a component.
+ * The stored config delegates to the latest render, so new route closures do
+ * not tear down and re-subscribe the native listener.
+ */
+export declare const useDeepLink: (deepLinkConfig: DeepLinkConfig) => void;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/download/adapters/expoFs.d.ts

@@ -0,0 +1,45 @@
+import type { FileSystemLike } from '../index';
+/**
+ * expo-file-system. Shape verified against 57.0.6, where the legacy function
+ * API (`downloadAsync`, `getInfoAsync`) still exists on the main entry point
+ * but every one of those functions THROWS at runtime; they now live behind
+ * `expo-file-system/legacy`. This adapter therefore uses the class API only.
+ *
+ * The REQUIRE lives in the entry point beside this file, never here.
+ */
+interface ExpoFileLike {
+    readonly uri: string;
+    readonly exists: boolean;
+    readonly size: number;
+    delete: () => void;
+}
+interface ExpoDirectoryLike {
+    readonly uri: string;
+    create: (options?: {
+        intermediates?: boolean;
+        idempotent?: boolean;
+    }) => void;
+}
+interface ExpoDownloadTaskLike {
+    downloadAsync: () => Promise<ExpoFileLike | null>;
+    cancel: () => void;
+}
+export interface ExpoFileSystemModuleLike {
+    File: (new (uri: string) => ExpoFileLike) & {
+        createDownloadTask: (url: string, destination: ExpoFileLike, options?: {
+            headers?: Record<string, string>;
+            onProgress?: (progress: {
+                bytesWritten: number;
+                totalBytes: number;
+            }) => void;
+        }) => ExpoDownloadTaskLike;
+    };
+    Directory: new (uri: string) => ExpoDirectoryLike;
+    Paths: {
+        document: ExpoDirectoryLike;
+        cache: ExpoDirectoryLike;
+    };
+}
+export declare const adaptExpoFileSystem: (mod: unknown) => FileSystemLike | null;
+export {};
+//# sourceMappingURL=expoFs.d.ts.map

package/lib/typescript/commonjs/download/adapters/shared.d.ts

@@ -0,0 +1,3 @@
+/** Coerce a driver-supplied size, which some report as a string. */
+export declare const asNumber: (value: unknown) => number;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1,76 @@
+export interface FileSystemDirs {
+    documents: string;
+    cache: string;
+    downloads: string;
+}
+export interface FileSystemDownloadRequest {
+    url: string;
+    path: string;
+    headers: Record<string, string>;
+    onProgress?: (received: number, total: number) => void;
+}
+export interface FileSystemDownloadHandle {
+    promise: Promise<{
+        status?: number;
+        bytes?: number;
+    }>;
+    cancel?: () => void;
+}
+/**
+ * The slice of a native filesystem module this module actually uses. Both
+ * `react-native-blob-util` and `react-native-fs` are adapted onto it, and an app
+ * can inject its own with `setFileSystemImplementation`.
+ */
+export interface FileSystemLike {
+    dirs: FileSystemDirs;
+    download: (request: FileSystemDownloadRequest) => FileSystemDownloadHandle;
+    exists: (path: string) => Promise<boolean>;
+    stat: (path: string) => Promise<{
+        size: number;
+    }>;
+    unlink: (path: string) => Promise<void>;
+    mkdir: (path: string) => Promise<void>;
+}
+export type DownloadDestination = 'documents' | 'cache' | 'downloads';
+export interface DownloadOptions {
+    url: string;
+    fileName?: string;
+    destination?: DownloadDestination;
+    headers?: Record<string, string>;
+    authenticated?: boolean;
+    mimeType?: string;
+    onProgress?: (received: number, total: number, fraction: number) => void;
+    overwrite?: boolean;
+    signal?: AbortSignal;
+}
+export interface DownloadResult {
+    path: string;
+    bytes: number;
+    mimeType?: string;
+    fromCache: boolean;
+}
+export type DownloadErrorCode = 'unsupported' | 'permission-denied' | 'network' | 'http-error' | 'write-failed' | 'aborted' | 'empty-file';
+export declare class DownloadError extends Error {
+    readonly code: DownloadErrorCode;
+    readonly status?: number;
+    constructor(code: DownloadErrorCode, message: string, status?: number);
+}
+/**
+ * Replace the filesystem backend. Intended for TESTS and for the showcase,
+ * which injects a denying backend to demo the permission error; an app gets
+ * expo-file-system without wiring anything. Pass `null` to restore it.
+ */
+export declare const setFileSystemImplementation: (impl: FileSystemLike | null) => void;
+/**
+ * Download a file to the device, attaching the stored bearer token by default.
+ *
+ * A finished download is always verified to be non-empty: a 0-byte file looks
+ * like a success to every caller and then wedges whatever consumes it, so it is
+ * deleted and reported as `empty-file`.
+ */
+export declare const downloadFile: (options: DownloadOptions) => Promise<DownloadResult>;
+/**
+ * Hand a downloaded file to the OS, to open in whichever app claims it.
+ */
+export declare const openFile: (path: string, mimeType?: string) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -4,5 +4,6 @@ export type { DateInput, DateStyle, TimeStyle } from './date';
 export { formatDate, formatDateTime, formatRelativeTime, formatTime } from './date';
 export { getInitials } from './initials';
 export { formatCompactNumber, formatNumber, formatPercent } from './number';
-export { formatPhone, normalizePhone } from './phone';
+export type { FormatPhoneOptions, PhoneCountry, PhoneNumber } from './phone';
+export { detectPhoneCountry, formatPhone, isValidPhoneNumber, normalizePhone, parsePhoneNumber, parsePhoneNumberFromString } from './phone';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,13 +1,39 @@
+/**
+ * Real cross-country validation, re-exported rather than reimplemented.
+ * formatPhone/normalizePhone/detectPhoneCountry below are a fast, dependency-
+ * light DISPLAY formatter for a fixed set of countries; they are not a
+ * validator. Real phone number plans have country-specific area-code and
+ * mobile-prefix rules that only a maintained metadata table gets right -
+ * hand-rolling that risks silently-wrong validation for a country nobody
+ * tests against. Both live here so consumers get one phone module, not two.
+ */
+export type { PhoneNumber } from 'libphonenumber-js';
+export { isValidPhoneNumber, parsePhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
+export type PhoneCountry = 'IN' | 'US' | 'GB' | 'AE' | 'AU' | 'SG' | 'CA';
+export interface FormatPhoneOptions {
+    defaultCountryCode?: string;
+    country?: PhoneCountry;
+    includeCountryCode?: boolean;
+}
 /**
  * Strip everything except digits and a leading `+` (preserved if present).
  */
 export declare const normalizePhone: (input: string) => string;
+/**
+ * Detect the country of a phone number: from its own `+` country code when
+ * present, otherwise from `defaultCountryCode`. Returns null when neither
+ * carries a recognised calling code.
+ */
+export declare const detectPhoneCountry: (input: string, defaultCountryCode?: string) => PhoneCountry | null;
 /**
  * Format a phone number for human display.
  *
  * - Indian mobile (10 digits) → `XXXXX XXXXX`
  * - With `+91` country code → `+91 XXXXX XXXXX`
+ * - A number that already carries a recognised country code is grouped for
+ *   that country regardless of `defaultCountryCode`.
  * - Other inputs are returned as `+CC NNNN NNNN…` best-effort grouping.
  */
-export declare const formatPhone: (input: string, defaultCountryCode?: string) => string;
+export declare function formatPhone(input: string, defaultCountryCode?: string): string;
+export declare function formatPhone(input: string, options?: FormatPhoneOptions): string;
 //# sourceMappingURL=phone.d.ts.map