@webority/mobile-core 0.0.23

package/lib/module/geolocation/index.js

@@ -0,0 +1,347 @@
+"use strict";
+
+import * as ExpoLocation from 'expo-location';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Logger } from "../logger/index.js";
+import { Permissions } from "../permissions/index.js";
+// expo-location is a REQUIRED peer (unlike the other Expo permission
+// packages, which are optional and registered only when an app opts in by
+// importing their own entry point) — anything that reaches this module
+// already forces Metro to resolve expo-location, so self-registering its
+// permission kinds here costs nothing extra and makes Geolocation's
+// permission gating work without a separate app-level import.
+import "../permissions/location.js";
+import { adaptExpoLocation } from "./adapters/expoLocation.js";
+const PREFIX = '[@webority/mobile-core]';
+export class GeolocationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'GeolocationError';
+    this.code = code;
+    // Babel downlevels `class extends Error`, which breaks `instanceof` for
+    // subclasses unless the prototype is restored explicitly.
+    Object.setPrototypeOf(this, GeolocationError.prototype);
+  }
+}
+
+/** Minimal shape of the native geolocation module we depend on. */
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_RETRIES = 1;
+const DEFAULT_RETRY_DELAY_MS = 800;
+
+/** Only what a test or the showcase injected; null means use expo-location. */
+let backend = null;
+
+/**
+ * expo-location is a required peer, so the JS module always resolves. What can
+ * be missing is the NATIVE side: an app that installed the package without
+ * running the native install gets a module whose calls are absent. Checking the
+ * two the adapter needs is what lets `isAvailable` mean something and makes the
+ * error below reachable.
+ *
+ * An INJECTED backend is taken on trust, like every other seam in this package.
+ */
+const hasNativeLocation = mod => typeof mod?.getCurrentPositionAsync === 'function' && typeof mod?.watchPositionAsync === 'function';
+let expoBackend;
+const resolveBackend = () => {
+  if (backend) {
+    return backend;
+  }
+  if (expoBackend === undefined) {
+    const mod = ExpoLocation;
+    expoBackend = hasNativeLocation(mod) ? adaptExpoLocation(mod) : null;
+  }
+  return expoBackend;
+};
+
+/**
+ * Replace the geolocation provider. Intended for TESTS and for the showcase,
+ * which injects a denying provider to demo the permission and services-off
+ * errors; an app gets expo-location without wiring anything. Pass `null` to
+ * restore it.
+ */
+export const setGeolocationImplementation = impl => {
+  backend = impl;
+};
+const requireBackend = op => {
+  const b = resolveBackend();
+  if (!b) {
+    throw new GeolocationError('unsupported', `${PREFIX} No geolocation provider is available; cannot ${op}. ` + 'expo-location did not load, which on a real build means the native ' + 'module was not linked.');
+  }
+  return b;
+};
+
+/**
+ * Android reports "location services are switched off" through the same code 2
+ * that also covers a genuine failure to fix a position, and the two need
+ * different handling: one is fixed by the user in system settings, the other is
+ * worth retrying. The message is the only signal that separates them.
+ */
+const SERVICES_OFF_PATTERN = /(location|gps)[^.]{0,40}(disabled|switched off|turned off|not enabled)|no location provider|settings_not_satisfied|location services (are |is )?off/i;
+const toGeoError = raw => {
+  if (raw instanceof GeolocationError) {
+    return raw;
+  }
+  const native = raw ?? {};
+  const detail = typeof native.message === 'string' && native.message.length > 0 ? native.message : 'the provider gave no reason';
+  switch (native.code) {
+    case 1:
+      return new GeolocationError('permission-denied', `${PREFIX} Location permission was denied (${detail}). Request the ` + 'location permission before calling, or send the user to settings.');
+    case 2:
+      return SERVICES_OFF_PATTERN.test(detail) ? new GeolocationError('services-disabled', `${PREFIX} Location services are switched off (${detail}). Ask the user ` + 'to enable location in system settings; retrying will not help.') : new GeolocationError('position-unavailable', `${PREFIX} No position fix (${detail}).`);
+    case 3:
+      return new GeolocationError('timeout', `${PREFIX} Location request timed out (${detail}).`);
+    case 4:
+    case 5:
+      return new GeolocationError('services-disabled', `${PREFIX} Location services are unavailable on this device (${detail}). ` + 'Ask the user to enable location, or install Google Play services.');
+    default:
+      return new GeolocationError('position-unavailable', `${PREFIX} Location request failed (${detail}).`);
+  }
+};
+const RETRYABLE = ['timeout', 'position-unavailable'];
+const normalizeCoords = raw => {
+  const coords = raw?.coords;
+  if (!coords || !Number.isFinite(coords.latitude) || !Number.isFinite(coords.longitude)) {
+    return null;
+  }
+  return {
+    latitude: coords.latitude,
+    longitude: coords.longitude,
+    // An absent radius is treated as infinitely bad rather than perfect, so a
+    // provider that omits it can never satisfy `minimumAccuracyM` by accident.
+    accuracy: Number.isFinite(coords.accuracy) ? coords.accuracy : Number.POSITIVE_INFINITY,
+    altitude: Number.isFinite(coords.altitude) ? coords.altitude : null,
+    heading: Number.isFinite(coords.heading) ? coords.heading : null,
+    speed: Number.isFinite(coords.speed) ? coords.speed : null
+  };
+};
+const normalizePosition = raw => {
+  const coords = normalizeCoords(raw);
+  if (!coords) {
+    return null;
+  }
+  return {
+    coords,
+    timestamp: Number.isFinite(raw?.timestamp) ? raw?.timestamp : Date.now()
+  };
+};
+const toNativeOptions = options => {
+  const native = {
+    enableHighAccuracy: (options.accuracy ?? 'fine') === 'fine',
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maximumAge: options.maximumAgeMs ?? 0
+  };
+  if (options.distanceFilterM !== undefined) {
+    native.distanceFilter = options.distanceFilterM;
+  }
+  return native;
+};
+const sleep = ms => new Promise(resolve => {
+  setTimeout(resolve, ms);
+});
+const ensureLocationPermission = async () => {
+  const status = await Permissions.ensure('location');
+  if (status === 'granted' || status === 'limited') {
+    return;
+  }
+  if (status === 'unavailable') {
+    Logger.warn(`${PREFIX} Location permission status is unavailable (expo-location is not installed, ` + 'or the check failed); attempting the location request anyway.');
+    return;
+  }
+  throw new GeolocationError('permission-denied', `${PREFIX} Location permission is "${status}". Grant it before requesting a position` + (status === 'blocked' ? ', or call Permissions.openSettings() to let the user fix it.' : '.'));
+};
+const positionOnce = (b, options) => {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    // The native timeout is passed through as well, but a provider that never
+    // calls back at all would otherwise hang the caller forever.
+    const timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      reject(new GeolocationError('timeout', `${PREFIX} Location request timed out after ${timeoutMs}ms. Raise timeoutMs, or use ` + "accuracy: 'coarse' where a network fix is good enough."));
+    }, timeoutMs);
+    const settle = run => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      run();
+    };
+    const onSuccess = raw => settle(() => {
+      const position = normalizePosition(raw);
+      if (!position) {
+        reject(new GeolocationError('position-unavailable', `${PREFIX} The provider returned a fix without usable coordinates.`));
+        return;
+      }
+      const floor = options.minimumAccuracyM;
+      if (floor !== undefined && position.coords.accuracy > floor) {
+        reject(new GeolocationError('position-unavailable', `${PREFIX} Fix accuracy ${position.coords.accuracy}m is worse than the required ` + `${floor}m.`));
+        return;
+      }
+      resolve(position);
+    });
+    const onError = error => settle(() => reject(toGeoError(error)));
+    try {
+      b.getCurrentPosition(onSuccess, onError, toNativeOptions(options));
+    } catch (error) {
+      settle(() => reject(toGeoError(error)));
+    }
+  });
+};
+const getCurrentPosition = async (options = {}) => {
+  const b = requireBackend('get the current position');
+  await ensureLocationPermission();
+  const attempts = Math.max(0, Math.trunc(options.retries ?? DEFAULT_RETRIES)) + 1;
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  let lastError = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await positionOnce(b, options);
+    } catch (error) {
+      const geoError = toGeoError(error);
+      if (!RETRYABLE.includes(geoError.code)) {
+        throw geoError;
+      }
+      lastError = geoError;
+      if (attempt < attempts - 1 && retryDelayMs > 0) {
+        await sleep(retryDelayMs);
+      }
+    }
+  }
+  throw lastError ?? new GeolocationError('position-unavailable', `${PREFIX} Location request failed.`);
+};
+const watchPosition = (listener, options = {}) => {
+  const b = requireBackend('watch the position');
+  let cancelled = false;
+  let watchId = null;
+  const stop = () => {
+    if (cancelled) {
+      return;
+    }
+    cancelled = true;
+    if (watchId !== null) {
+      b.clearWatch(watchId);
+      watchId = null;
+    }
+  };
+  const fail = error => {
+    const geoError = toGeoError(error);
+    Logger.error(geoError.message);
+    options.onError?.(geoError);
+  };
+  void ensureLocationPermission().then(() => {
+    // The caller can unsubscribe while the permission gate is still pending;
+    // registering afterwards would leak a watch nothing can clear.
+    if (cancelled) {
+      return;
+    }
+    watchId = b.watchPosition(raw => {
+      if (cancelled) {
+        return;
+      }
+      const position = normalizePosition(raw);
+      if (!position) {
+        return;
+      }
+      const floor = options.minimumAccuracyM;
+      if (floor !== undefined && position.coords.accuracy > floor) {
+        return;
+      }
+      listener(position);
+    }, error => {
+      if (!cancelled) {
+        fail(error);
+      }
+    }, toNativeOptions(options));
+  }).catch(fail);
+  return stop;
+};
+const isAvailable = () => resolveBackend() !== null;
+export const Geolocation = {
+  getCurrentPosition,
+  watchPosition,
+  isAvailable
+};
+export const useCurrentPosition = (options = {}) => {
+  const {
+    enabled = true,
+    accuracy,
+    timeoutMs,
+    maximumAgeMs,
+    retries,
+    minimumAccuracyM,
+    retryDelayMs
+  } = options;
+  const [state, setState] = useState({
+    position: null,
+    error: null,
+    loading: enabled
+  });
+  const mountedRef = useRef(true);
+  // Identifies the in-flight request so a slow earlier fix cannot overwrite the
+  // result of a later refresh().
+  const requestRef = useRef(0);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // Every dependency is a primitive read off `options`, so an inline options
+  // object (the normal call shape) does not re-create this on every render.
+  const run = useCallback(() => {
+    requestRef.current += 1;
+    const token = requestRef.current;
+    setState(prev => prev.loading ? prev : {
+      ...prev,
+      loading: true
+    });
+    const accept = next => {
+      if (mountedRef.current && requestRef.current === token) {
+        setState(next);
+      }
+    };
+    getCurrentPosition({
+      accuracy,
+      timeoutMs,
+      maximumAgeMs,
+      retries,
+      minimumAccuracyM,
+      retryDelayMs
+    }).then(position => accept({
+      position,
+      error: null,
+      loading: false
+    }), error => accept({
+      position: null,
+      error: toGeoError(error),
+      loading: false
+    }));
+  }, [accuracy, timeoutMs, maximumAgeMs, retries, minimumAccuracyM, retryDelayMs]);
+  useEffect(() => {
+    if (!enabled) {
+      // Discard any in-flight request so its result cannot land after opting out.
+      requestRef.current += 1;
+      setState(prev => prev.loading || prev.position !== null || prev.error !== null ? {
+        position: null,
+        error: null,
+        loading: false
+      } : prev);
+      return;
+    }
+    run();
+  }, [enabled, run]);
+  return {
+    position: state.position,
+    error: state.error,
+    loading: state.loading,
+    refresh: run
+  };
+};
+//# sourceMappingURL=index.js.map

package/lib/module/index.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * The main barrel deliberately does NOT re-export the modules that need a native
+ * package. Metro resolves requires statically, so anything reachable from here
+ * is resolved for every consumer, which would make an optional peer mandatory
+ * for anyone importing anything at all. Those live behind their own import
+ * paths instead:
+ *
+ *   @webority/mobile-core/permissions  per kind, its own Expo module
+ *   @webority/mobile-core/compressor   expo-image-manipulator + expo-file-system
+ *   @webority/mobile-core/geolocation  a geolocation provider
+ *   @webority/mobile-core/sqlite       expo-sqlite
+ *   @webority/mobile-core/download     a filesystem module
+ *   @webority/mobile-core/share        expo-sharing
+ *   @webority/mobile-core/smsRetriever Android only, own TurboModule
+ *
+ * One more path is separate for size, not for a native package:
+ *
+ *   @webority/mobile-core/phone/countries  245 English country names
+ *
+ * Token storage is the exception and IS on the main barrel, because the HTTP
+ * client reads the bearer token. It needs no optional peer: the backend is
+ * expo-secure-store, and `expo` is required anyway.
+ */
+// API clients
+export { buildCurl, logCurl } from "./api/curl.js";
+export { default as publicClient } from "./api/publicClient.js";
+export { attachRetry, isRetryableStatus } from "./api/retry.js";
+export { default as userClient, injectStore, injectUserAuth, RequestOfflineError, resetRefreshState, SESSION_TERMINATION_CODES } from "./api/userClient.js";
+// Auth / token storage
+export { ACCESS_TOKEN_KEY, getToken, REFRESH_TOKEN_KEY, removeToken, setKeychainImplementation, storeToken } from "./auth/authStore.js";
+export { decodeJWT, getJWTExpiry, isJWTExpired } from "./auth/jwt.js";
+// Configuration
+export { getConfig, getConfigValue, resetConfig, setConfig } from "./config/index.js";
+// Deep links
+export { DeepLink, parseDeepLink, useDeepLink } from "./deepLink/index.js";
+// Formatters
+export { AsYouType, addDays, clampNationalNumber, countryFlagEmoji, detectPhoneCountry, diffMs, formatCompactNumber, formatCurrency, formatDate, formatDateDDMMMYYYY, formatDateISO, formatDatePattern, formatDateTime, formatNumber, formatPercent, formatPhone, formatPhoneAsTyped, formatRelativeTime, formatTime, formatTime12h, formatTimeInWindowsZone, formatTimeInZone, getCountries, getCountryCallingCode, getInitials, getPhoneCountries, isDateAfter, isDateBefore, isSameDay, isSupportedCountry, isValidNationalNumber, isValidPhoneNumber, maxNationalNumberLength, normalizePhone, parsePhoneNumber, parsePhoneNumberFromString, splitPhoneNumber, startOfDay, validatePhoneNumberLength } from "./formatters/index.js";
+// Initialization
+export { initWebority } from "./initSDK.js";
+export { initUserAuth } from "./initUserAuth.js";
+// Logger
+export { configureLogger, getDeviceContext, Logger, setDeviceContext, setRemoteLogger } from "./logger/index.js";
+// Network status (the NetworkStatusBanner UI lives in @webority/mobile-ui)
+export { addNetworkStatusListener, getNetworkStatus, setNetworkStatusImplementation, useNetworkStatus } from "./network/index.js";
+// Storage: the API and the seam. No native package is required; wire one with
+// setStorageImplementation to get persistence.
+export { isStorageAvailable, Storage, setStorageImplementation } from "./storage/index.js";
+// Validators
+export { isAadhaar, isAlphanumeric, isBetween, isEmail, isGstin, isHexColor, isIfsc, isIndianMobile, isIndianPincode, isInteger, isNonEmpty, isNumeric, isPan, isPhone, isStrongPassword, isUrl, maxLength, minLength } from "./validators/index.js";
+// Version check (the ForceUpdateDialog UI lives in @webority/mobile-ui)
+export { setDeviceInfoImplementation, useVersionCheck, VersionCheck } from "./versionCheck/index.js";
+//# sourceMappingURL=index.js.map

package/lib/module/initSDK.js

@@ -0,0 +1,61 @@
+"use strict";
+
+/**
+ * Simple initialization API for Webority packages
+ * One function to configure everything needed
+ */
+
+import { setKeychainImplementation } from "./auth/authStore.js";
+import { setConfig } from "./config/index.js";
+import { Logger } from "./logger/index.js";
+import { setNetworkStatusImplementation } from "./network/networkStatus.js";
+import { setStorageImplementation } from "./storage/index.js";
+/**
+ * Initialize Webority packages with your project configuration.
+ *
+ * @example
+ * // Basic setup
+ * initWebority({
+ *   baseUrl: 'https://api.myapp.com'
+ * });
+ *
+ * @example
+ * // Full configuration
+ * initWebority({
+ *   baseUrl: 'https://api.myapp.com',
+ *   loggingEnabled: __DEV__,
+ *   logLevel: 'warn',
+ *   environment: __DEV__ ? 'Development' : 'Production'
+ * });
+ */
+export const initWebority = config => {
+  if (!config.baseUrl) {
+    throw new Error('baseUrl is required for Webority packages initialization');
+  }
+  setConfig({
+    baseUrl: config.baseUrl,
+    loggingEnabled: config.loggingEnabled ?? true,
+    logLevel: config.logLevel || 'info',
+    environment: config.environment || 'Development',
+    country: (config.country || 'in').toLowerCase(),
+    appId: config.appId ?? null,
+    appVersion: config.appVersion ?? null,
+    logCurl: config.logCurl ?? false
+  });
+
+  // Only what the caller actually passed is wired. Calling a setter with
+  // `undefined` would reset a backend an app had already injected by hand,
+  // which is why each is guarded rather than passed straight through.
+  const backends = config.backends;
+  if (backends?.storage) {
+    setStorageImplementation(backends.storage);
+  }
+  if (backends?.keychain) {
+    setKeychainImplementation(backends.keychain);
+  }
+  if (backends?.network) {
+    setNetworkStatusImplementation(backends.network);
+  }
+  Logger.info('[@webority/mobile-core] initialized');
+};
+//# sourceMappingURL=initSDK.js.map

package/lib/module/initUserAuth.js

@@ -0,0 +1,33 @@
+"use strict";
+
+import { injectStore, injectUserAuth } from "./api/userClient.js";
+import { Logger } from "./logger/index.js";
+
+/** The tokens a refresh response carries, with their expiry timestamps. */
+
+/**
+ * How the library calls the app's refresh endpoint. The call goes through
+ * `publicClient`, and the new tokens are stored under the library's own keys.
+ */
+
+/**
+ * Wire the user client to the app: the Redux store it dispatches `logout` to,
+ * and the refresh endpoint it calls when an access token expires or a request
+ * answers 401. Only a 400 or 401 from that endpoint, or a missing or expired
+ * refresh token, logs out; a network error, timeout or 5xx keeps the session.
+ *
+ * @example
+ * initUserAuth(store, { logout, refresh: { path: '/Account/RefreshToken' } });
+ */
+export const initUserAuth = (store, options) => {
+  if (!store) {
+    throw new Error('Redux store is required for user package initialization');
+  }
+  if (!options.logout || !options.refresh?.path) {
+    throw new Error('initUserAuth needs a logout action and refresh.path');
+  }
+  injectStore(store);
+  injectUserAuth(options);
+  Logger.info('[@webority/mobile-core] user auth wired to the store');
+};
+//# sourceMappingURL=initUserAuth.js.map