@webority/mobile-core 0.0.23

package/lib/module/download/adapters/expoFs.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+/**
+ * expo reports a directory as a URI with a trailing slash, and the download
+ * module joins a directory to a file name with a `/` of its own.
+ */
+const asDirectoryPath = uri => uri.replace(/\/+$/, '');
+export const adaptExpoFileSystem = mod => {
+  const lib = mod?.default ?? mod;
+  if (typeof lib?.File !== 'function' || typeof lib.File.prototype?.write !== 'function') {
+    return null;
+  }
+  const {
+    File,
+    Directory,
+    Paths
+  } = lib;
+  const documents = asDirectoryPath(Paths.document.uri);
+  return {
+    dirs: {
+      documents,
+      cache: asDirectoryPath(Paths.cache.uri),
+      // expo exposes no public Downloads directory, so a "downloads" request
+      // lands in the app's documents directory instead of the shared folder.
+      downloads: documents
+    },
+    write: (path, bytes) => {
+      const file = new File(path);
+      file.create({
+        intermediates: true,
+        overwrite: true
+      });
+      file.write(bytes);
+      return Promise.resolve();
+    },
+    exists: path => Promise.resolve(new File(path).exists),
+    stat: path => Promise.resolve({
+      size: new File(path).size
+    }),
+    unlink: path => {
+      new File(path).delete();
+      return Promise.resolve();
+    },
+    // The download module calls this for a directory that usually already
+    // exists, so it must be idempotent rather than throw on the second run.
+    mkdir: path => {
+      new Directory(path).create({
+        intermediates: true,
+        idempotent: true
+      });
+      return Promise.resolve();
+    }
+  };
+};
+//# sourceMappingURL=expoFs.js.map

package/lib/module/download/adapters/shared.js

@@ -0,0 +1,8 @@
+"use strict";
+
+/** Coerce a driver-supplied size, which some report as a string. */
+export const asNumber = value => {
+  const n = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(n) ? n : 0;
+};
+//# sourceMappingURL=shared.js.map

package/lib/module/download/index.js

@@ -0,0 +1,242 @@
+"use strict";
+
+import * as ExpoFileSystem from 'expo-file-system';
+import { Platform } from 'react-native';
+import { Logger } from "../logger/index.js";
+import { Permissions } from "../permissions/index.js";
+import { adaptExpoFileSystem } from "./adapters/expoFs.js";
+import { asNumber } from "./adapters/shared.js";
+const PREFIX = '[@webority/mobile-core]';
+
+/** Android stopped requiring a storage permission for a Downloads write at API 29. */
+const SCOPED_STORAGE_API_LEVEL = 29;
+
+/** A file can take far longer than the 30 s the fleet's JSON clients allow. */
+const DOWNLOAD_TIMEOUT_MS = 300000;
+
+/**
+ * The slice of a filesystem module this module actually uses. expo-file-system
+ * is adapted onto it, and a test or the showcase can inject its own with
+ * `setFileSystemImplementation`.
+ */
+
+/**
+ * The slice of an HTTP client a download needs. The app's axios instance
+ * (mobile-core's `userClient` or `publicClient`, or its own) satisfies it as is,
+ * so whatever that client adds to a request (bearer token, tenant header, refresh
+ * and retry on 401) applies to the download too. Declared structurally, as
+ * mobile-support's client is, so no axios type leaks into the declarations.
+ */
+
+export class DownloadError extends Error {
+  constructor(code, message, status) {
+    super(`${PREFIX} ${message}`);
+    this.name = 'DownloadError';
+    this.code = code;
+    this.status = status;
+    // Babel's class transform can drop the prototype link, which makes
+    // `instanceof DownloadError` false in the transpiled build.
+    Object.setPrototypeOf(this, DownloadError.prototype);
+  }
+}
+const describe = error => error instanceof Error ? error.message : String(error);
+
+/** Only what a test or the showcase injected; null means use expo-file-system. */
+let backend = null;
+
+/**
+ * expo-file-system, adapted once and memoised. The adapter is shape-checked, so
+ * a build where the native module did not link returns null and the guided
+ * error below still fires rather than a confusing property access.
+ */
+let expoBackend;
+const resolveBackend = () => {
+  if (backend) {
+    return backend;
+  }
+  if (expoBackend === undefined) {
+    expoBackend = adaptExpoFileSystem(ExpoFileSystem);
+  }
+  return expoBackend;
+};
+
+/**
+ * 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 const setFileSystemImplementation = impl => {
+  backend = impl;
+};
+const requireBackend = () => {
+  const fs = resolveBackend();
+  if (!fs) {
+    throw new DownloadError('unsupported', 'No filesystem module is available, so files cannot be downloaded. ' + 'expo-file-system did not load, which on a real build means the native module ' + 'was not linked.');
+  }
+  return fs;
+};
+const stripControlChars = value => Array.from(value).filter(char => (char.codePointAt(0) ?? 0) > 0x1f).join('');
+const lastSegment = raw => {
+  const segments = raw.split(/[/\\]/);
+  return stripControlChars(segments[segments.length - 1] ?? '').trim();
+};
+
+/**
+ * Reduce a caller- or server-supplied name to a single path segment: `../../evil.pdf`
+ * must land inside the destination directory as `evil.pdf` rather than escaping it.
+ */
+const sanitiseFileName = raw => {
+  const base = lastSegment(raw);
+  if (base === '' || base === '.' || base === '..') {
+    throw new DownloadError('write-failed', `"${raw}" does not contain a usable file name. Pass an explicit fileName.`);
+  }
+  return base;
+};
+const fileNameFromUrl = url => {
+  const withoutQuery = url.split('#')[0]?.split('?')[0] ?? '';
+  const last = withoutQuery.split('/').pop() ?? '';
+  let decoded = last;
+  try {
+    decoded = decodeURIComponent(last);
+  } catch {
+    // A malformed escape sequence is not a reason to fail the download.
+  }
+  const base = lastSegment(decoded);
+  return base === '' || base === '.' || base === '..' ? 'download' : base;
+};
+const androidApiLevel = () => typeof Platform.Version === 'number' ? Platform.Version : Number.parseInt(String(Platform.Version), 10);
+const ensureStoragePermission = async destination => {
+  if (Platform.OS !== 'android' || destination !== 'downloads') {
+    return;
+  }
+  if (androidApiLevel() >= SCOPED_STORAGE_API_LEVEL) {
+    return;
+  }
+  const status = await Permissions.ensure('storage');
+  if (status === 'granted' || status === 'limited') {
+    return;
+  }
+  throw new DownloadError('permission-denied', `Storage permission is "${status}", so nothing can be written to the Downloads folder ` + 'on this Android version. Ask the user to grant it (Permissions.openSettings()), or ' + 'download to the "documents" destination instead.');
+};
+const emptyFile = url => new DownloadError('empty-file', `The download of ${url} produced an empty file, so nothing was saved. ` + 'Check that the URL is correct and that the request carried the credentials the ' + 'server expects.');
+const requestFailed = (error, options, fileName) => {
+  if (options.signal?.aborted) {
+    return new DownloadError('aborted', `The download of ${fileName} was aborted.`);
+  }
+  const e = error ?? {};
+  // By name, not instanceof: a second copy of mobile-core would fail instanceof.
+  if (e.name === 'RequestOfflineError') {
+    return new DownloadError('network', `The device is offline, so ${options.url} was not downloaded.`);
+  }
+  const status = e.response?.status;
+  if (typeof status === 'number') {
+    return new DownloadError('http-error', `The server answered ${status} for ${options.url}, so no file was saved.`, status);
+  }
+  return new DownloadError('network', `The download of ${options.url} failed: ${describe(error)}`);
+};
+const discardPartial = async (fs, path) => {
+  try {
+    if (await fs.exists(path)) {
+      await fs.unlink(path);
+    }
+  } catch (error) {
+    Logger.warn(`${PREFIX} Failed to remove the partial download at ${path}`, error);
+  }
+};
+
+/**
+ * Download a file to the device through the app's own HTTP client, so it is
+ * authenticated exactly as the app's other calls are. The whole file is held
+ * in memory before it is written, which suits documents and reports rather
+ * than large media.
+ *
+ * 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
+ * reported as `empty-file` and nothing is kept.
+ */
+export const downloadFile = async options => {
+  const fs = requireBackend();
+  const destination = options.destination ?? 'documents';
+  const fileName = options.fileName ? sanitiseFileName(options.fileName) : fileNameFromUrl(options.url);
+  await ensureStoragePermission(destination);
+  const directory = fs.dirs[destination];
+  const path = `${directory}/${fileName}`;
+  if (options.signal?.aborted) {
+    throw new DownloadError('aborted', `The download of ${fileName} was aborted before it started.`);
+  }
+  let reuseExisting = false;
+  try {
+    await fs.mkdir(directory);
+    const exists = await fs.exists(path);
+    if (exists && options.overwrite === false) {
+      reuseExisting = true;
+    } else if (exists) {
+      await fs.unlink(path);
+    }
+  } catch (error) {
+    throw new DownloadError('write-failed', `Could not prepare ${path} for writing: ${describe(error)}`);
+  }
+  if (reuseExisting) {
+    const stat = await fs.stat(path);
+    return {
+      path,
+      bytes: asNumber(stat?.size),
+      mimeType: options.mimeType,
+      fromCache: true
+    };
+  }
+  const {
+    onProgress
+  } = options;
+  let data;
+  try {
+    ({
+      data
+    } = await options.client.get(options.url, {
+      headers: {
+        Accept: '*/*',
+        ...options.headers
+      },
+      responseType: 'arraybuffer',
+      timeout: DOWNLOAD_TIMEOUT_MS,
+      signal: options.signal,
+      onDownloadProgress: onProgress ? ({
+        loaded,
+        total = 0
+      }) => onProgress(loaded, total, total > 0 ? loaded / total : 0) : undefined
+    }));
+  } catch (error) {
+    throw requestFailed(error, options, fileName);
+  }
+  if (options.signal?.aborted) {
+    throw new DownloadError('aborted', `The download of ${fileName} was aborted.`);
+  }
+  const received = new Uint8Array(data ?? new ArrayBuffer(0));
+  if (received.byteLength === 0) {
+    throw emptyFile(options.url);
+  }
+  try {
+    await fs.write(path, received);
+  } catch (error) {
+    await discardPartial(fs, path);
+    throw new DownloadError('write-failed', `Could not write ${path}: ${describe(error)}`);
+  }
+  let bytes = 0;
+  try {
+    bytes = (await fs.exists(path)) ? asNumber((await fs.stat(path)).size) : 0;
+  } catch (error) {
+    await discardPartial(fs, path);
+    throw new DownloadError('write-failed', `The download of ${fileName} finished but ${path} could not be read back: ${describe(error)}`);
+  }
+  if (bytes <= 0) {
+    await discardPartial(fs, path);
+    throw emptyFile(options.url);
+  }
+  return {
+    path,
+    bytes,
+    mimeType: options.mimeType,
+    fromCache: false
+  };
+};
+//# sourceMappingURL=index.js.map

package/lib/module/formatters/currency.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const hasIntlNumber = () => typeof Intl !== 'undefined' && typeof Intl.NumberFormat === 'function';
+const indianGroupingFallback = (n, fractionDigits) => {
+  // Indian numbering: 1,23,45,678.90 (last 3 digits, then groups of 2).
+  const sign = n < 0 ? '-' : '';
+  const abs = Math.abs(n);
+  const fixed = abs.toFixed(fractionDigits);
+  const [intPart, decPart] = fixed.split('.');
+  const last3 = intPart.length > 3 ? intPart.slice(-3) : intPart;
+  const rest = intPart.length > 3 ? intPart.slice(0, -3) : '';
+  const grouped = rest ? rest.replace(/\B(?=(\d{2})+(?!\d))/g, ',') + ',' + last3 : last3;
+  return sign + grouped + (decPart ? `.${decPart}` : '');
+};
+
+/**
+ * Format an amount as currency. Defaults to **INR** with Indian numbering (`en-IN`),
+ * which matches the standard convention across Webority projects.
+ *
+ * @example
+ * formatCurrency(150000)            // ₹1,50,000
+ * formatCurrency(1234.5)            // ₹1,234.50
+ * formatCurrency(99, { currency: 'USD', locale: 'en-US' }) // $99.00
+ * formatCurrency(150000, { stripSymbol: true })            // 1,50,000
+ */
+export const formatCurrency = (amount, options = {}) => {
+  if (amount == null || Number.isNaN(amount)) {
+    return '';
+  }
+  const {
+    currency = 'INR',
+    locale = 'en-IN',
+    minimumFractionDigits,
+    maximumFractionDigits = 2,
+    stripSymbol = false
+  } = options;
+  const minFrac = minimumFractionDigits ?? (Number.isInteger(amount) ? 0 : 2);
+  if (hasIntlNumber()) {
+    try {
+      const formatted = new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: minFrac,
+        maximumFractionDigits
+      }).format(amount);
+      if (!stripSymbol) {
+        return formatted;
+      }
+      // Strip currency code/symbol while keeping digits, separators and sign.
+      return formatted.replace(/[^\d,.\s\-+]/g, '').trim();
+    } catch {
+      /* fall through to fallback */
+    }
+  }
+  const numeric = indianGroupingFallback(amount, minFrac);
+  if (stripSymbol) {
+    return numeric;
+  }
+  if (currency === 'INR') {
+    return `₹${numeric}`;
+  }
+  return `${currency} ${numeric}`;
+};
+//# sourceMappingURL=currency.js.map

package/lib/module/formatters/date.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const toDate = value => {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+};
+const hasIntl = () => typeof Intl !== 'undefined' && typeof Intl.DateTimeFormat === 'function';
+const PAD = n => n < 10 ? `0${n}` : `${n}`;
+const fallbackDate = (d, style) => {
+  const day = PAD(d.getDate());
+  const monthShort = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][d.getMonth()];
+  const monthLong = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'][d.getMonth()];
+  const year = d.getFullYear();
+  const weekdayLong = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][d.getDay()];
+  switch (style) {
+    case 'short':
+      return `${day}/${PAD(d.getMonth() + 1)}/${year}`;
+    case 'long':
+      return `${day} ${monthLong} ${year}`;
+    case 'full':
+      return `${weekdayLong}, ${day} ${monthLong} ${year}`;
+    case 'medium':
+    default:
+      return `${day} ${monthShort} ${year}`;
+  }
+};
+const fallbackTime = (d, style) => {
+  const hh = PAD(d.getHours());
+  const mm = PAD(d.getMinutes());
+  if (style === 'short') {
+    return `${hh}:${mm}`;
+  }
+  const ss = PAD(d.getSeconds());
+  return `${hh}:${mm}:${ss}`;
+};
+
+/**
+ * Locale-aware date formatter. Defaults to `'medium'` style and `'en-IN'` locale,
+ * matching the Indian-locale convention used across Webority apps.
+ */
+export const formatDate = (value, style = 'medium', locale = 'en-IN') => {
+  const d = toDate(value);
+  if (!d) {
+    return '';
+  }
+  if (hasIntl()) {
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: style
+      }).format(d);
+    } catch {
+      /* fall through to fallback */
+    }
+  }
+  return fallbackDate(d, style);
+};
+
+/**
+ * Locale-aware time formatter (24-hour fallback when Intl is unavailable).
+ */
+export const formatTime = (value, style = 'short', locale = 'en-IN') => {
+  const d = toDate(value);
+  if (!d) {
+    return '';
+  }
+  if (hasIntl()) {
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        timeStyle: style
+      }).format(d);
+    } catch {
+      /* fall through */
+    }
+  }
+  return fallbackTime(d, style);
+};
+
+/**
+ * Combined date + time formatter.
+ */
+export const formatDateTime = (value, dateStyle = 'medium', timeStyle = 'short', locale = 'en-IN') => {
+  const d = toDate(value);
+  if (!d) {
+    return '';
+  }
+  if (hasIntl()) {
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle,
+        timeStyle
+      }).format(d);
+    } catch {
+      /* fall through */
+    }
+  }
+  return `${fallbackDate(d, dateStyle)}, ${fallbackTime(d, timeStyle)}`;
+};
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const MONTH = 30 * DAY;
+const YEAR = 365 * DAY;
+
+/**
+ * Returns a humanized relative-time string (e.g. "5 minutes ago", "in 3 days").
+ * Uses `Intl.RelativeTimeFormat` when available; otherwise a sensible English fallback.
+ */
+export const formatRelativeTime = (value, base = new Date(), locale = 'en-IN') => {
+  const target = toDate(value);
+  const now = toDate(base);
+  if (!target || !now) {
+    return '';
+  }
+  const diffMs = target.getTime() - now.getTime();
+  const abs = Math.abs(diffMs);
+  let unit;
+  let amount;
+  if (abs < MINUTE) {
+    unit = 'second';
+    amount = Math.round(diffMs / SECOND);
+  } else if (abs < HOUR) {
+    unit = 'minute';
+    amount = Math.round(diffMs / MINUTE);
+  } else if (abs < DAY) {
+    unit = 'hour';
+    amount = Math.round(diffMs / HOUR);
+  } else if (abs < WEEK) {
+    unit = 'day';
+    amount = Math.round(diffMs / DAY);
+  } else if (abs < MONTH) {
+    unit = 'week';
+    amount = Math.round(diffMs / WEEK);
+  } else if (abs < YEAR) {
+    unit = 'month';
+    amount = Math.round(diffMs / MONTH);
+  } else {
+    unit = 'year';
+    amount = Math.round(diffMs / YEAR);
+  }
+  const Rtf = hasIntl() ? Intl.RelativeTimeFormat : undefined;
+  if (typeof Rtf === 'function') {
+    try {
+      return new Rtf(locale, {
+        numeric: 'auto'
+      }).format(amount, unit);
+    } catch {
+      /* fall through */
+    }
+  }
+  const past = amount < 0;
+  const n = Math.abs(amount);
+  const u = n === 1 ? unit : `${unit}s`;
+  return past ? `${n} ${u} ago` : `in ${n} ${u}`;
+};
+//# sourceMappingURL=date.js.map