@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/utils/jpegFromUri.ts

@@ -0,0 +1,42 @@
+/**
+ * Helpers for reading a captured photo into JPEG bytes.
+ *
+ * Vision-Camera writes captures to a `file://` path; consumers convert that
+ * path into either base64 (for the Iris HMAC envelope) or raw bytes (for
+ * binary WebSocket frames + direct PUT to signed URLs).
+ *
+ * Why not `fetch(uri).then(r => r.blob()).then(b => b.arrayBuffer())`?
+ *
+ * React Native's Blob polyfill does NOT implement `Blob.arrayBuffer()`
+ * (it's web-only). Calling it crashes with
+ * `TypeError: blob.arrayBuffer is not a function`. The reliable path on
+ * iOS + Android is the native `File.arrayBuffer()` from
+ * `expo-file-system` v19+, which reads directly from disk into an
+ * ArrayBuffer without going through the JS Blob bridge.
+ */
+
+import { File } from 'expo-file-system';
+import { bytesToBase64 } from './base64';
+
+export interface JpegFromUri {
+  bytes: Uint8Array;
+  base64: string;
+  byteLength: number;
+}
+
+/**
+ * Reads a `file://` URI into JPEG bytes + base64 representation.
+ *
+ * Accepts both forms vision-camera returns (`/var/mobile/...` without a
+ * scheme on iOS; `file:///data/...` on Android). Normalises to `file://`.
+ */
+export async function readJpegFromUri(uri: string): Promise<JpegFromUri> {
+  const normalised = uri.startsWith('file://') || uri.startsWith('http')
+    ? uri
+    : `file://${uri}`;
+  const file = new File(normalised);
+  const buf = await file.arrayBuffer();
+  const bytes = new Uint8Array(buf);
+  const base64 = bytesToBase64(bytes);
+  return { bytes, base64, byteLength: bytes.byteLength };
+}

package/src/utils/keepAwake.ts

@@ -0,0 +1,62 @@
+/**
+ * Thin wrapper around `expo-keep-awake` that prevents the device from
+ * locking the screen while the SDK is in the foreground. Without this,
+ * Android's screen-timeout policy kicks in during camera-heavy steps
+ * (LIVENESS_MATCH, DOCUMENTS_OCR) where the user is holding still and
+ * not interacting with the touchscreen — the screen dims, then locks,
+ * and the session is interrupted.
+ *
+ * Implementation is `require`-based so the SDK keeps working in bare
+ * React Native setups where `expo-keep-awake` may not be installed —
+ * in that case both calls degrade to no-ops and the host is expected to
+ * manage the wake lock itself.
+ */
+
+import { log } from './log';
+
+const TAG = 'velion-onboarding-sdk';
+
+let activated = false;
+
+interface ExpoKeepAwakeModule {
+  activateKeepAwakeAsync?: (tag?: string) => Promise<void>;
+  deactivateKeepAwake?: (tag?: string) => Promise<void> | void;
+}
+
+function loadModule(): ExpoKeepAwakeModule | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('expo-keep-awake');
+    return (mod?.default ?? mod) as ExpoKeepAwakeModule;
+  } catch {
+    return null;
+  }
+}
+
+export function activateScreenKeepAwake(): void {
+  if (activated) return;
+  const mod = loadModule();
+  if (!mod?.activateKeepAwakeAsync) {
+    log.info(
+      '[keep-awake] expo-keep-awake unavailable; host should manage the wake lock if screen-lock is unwanted during the flow',
+    );
+    return;
+  }
+  activated = true;
+  void mod.activateKeepAwakeAsync(TAG).catch((err: unknown) => {
+    activated = false;
+    log.warn('[keep-awake] activate failed', err);
+  });
+}
+
+export function deactivateScreenKeepAwake(): void {
+  if (!activated) return;
+  const mod = loadModule();
+  activated = false;
+  if (!mod?.deactivateKeepAwake) return;
+  try {
+    void mod.deactivateKeepAwake(TAG);
+  } catch (err) {
+    log.warn('[keep-awake] deactivate failed', err);
+  }
+}

package/src/utils/log.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Lightweight log gate.
+ *
+ * `log.info()` is silent unless either:
+ *   - `__DEV__` is true (Metro bundler injects this in development), or
+ *   - the host explicitly opted in via `VelionConfig.debug = true`.
+ *
+ * `log.warn()` / `log.error()` always go through. They sit on top of `console.*`
+ * so the host's logging pipeline (Sentry, Datadog, …) keeps capturing them.
+ */
+
+declare const __DEV__: boolean | undefined;
+
+let runtimeDebugEnabled = false;
+
+/** Enables verbose logging at runtime. Called from VelionOnboarding when `config.debug === true`. */
+export function setDebugEnabled(enabled: boolean): void {
+  runtimeDebugEnabled = enabled;
+}
+
+/** Internal — true when `log.info` should produce output. */
+function infoEnabled(): boolean {
+  return (typeof __DEV__ !== 'undefined' && __DEV__ === true) || runtimeDebugEnabled;
+}
+
+export const log = {
+  info(...args: unknown[]): void {
+    if (!infoEnabled()) return;
+    console.info('[VelionSDK]', ...args);
+  },
+  warn(...args: unknown[]): void {
+    console.warn('[VelionSDK]', ...args);
+  },
+  error(...args: unknown[]): void {
+    console.error('[VelionSDK]', ...args);
+  },
+};

package/src/utils/osGeocoder.ts

@@ -0,0 +1,75 @@
+/**
+ * Reverse geocoding via the OS-native geocoder, bypassing Google's REST API
+ * entirely.
+ *
+ * Why this exists:
+ *   - The Google Geocoding Web Service is HTTP REST. It does not honour
+ *     iOS/Android application restrictions on the API key, so a key tightly
+ *     locked to a bundle ID still fails with REQUEST_DENIED when called from
+ *     fetch().
+ *   - The OS geocoder (CLGeocoder on iOS / android.location.Geocoder on
+ *     Android) needs no Google key and respects the platform conventions
+ *     users expect. Coverage in urban LATAM is excellent; rural coverage on
+ *     iOS uses Apple Maps (lower than Google in remote zones) but the
+ *     downstream OCR step normally recovers the printed address either way.
+ *   - Keeps the SDK to one Google Maps key whose only purpose is rendering
+ *     the map via the native Maps SDK — that one IS protected by the iOS /
+ *     Android app restriction.
+ *
+ * Returns the same `ParsedAddressFields` shape that the previous Google
+ * Geocoding caller produced, so downstream code (`AddressDetailsForm`,
+ * payload assembly) doesn't change.
+ */
+
+import * as Location from 'expo-location';
+import {
+  type ParsedAddressFields,
+} from './parseGoogleAddressComponents';
+import { log } from './log';
+
+export interface ReverseGeocodeArgs {
+  latitude: number;
+  longitude: number;
+  /** `'es'` or `'en'` — passed through to the OS where supported. */
+  locale?: string;
+}
+
+/**
+ * Returns parsed structured address fields, or `null` when the OS geocoder
+ * has no match.
+ */
+export async function reverseGeocode(
+  args: ReverseGeocodeArgs,
+): Promise<(ParsedAddressFields & { latitude: number; longitude: number }) | null> {
+  let results: Location.LocationGeocodedAddress[];
+  try {
+    results = await Location.reverseGeocodeAsync({
+      latitude: args.latitude,
+      longitude: args.longitude,
+    });
+  } catch (err) {
+    log.warn('[os-geocoder] reverse failed', err);
+    return null;
+  }
+  if (!results || results.length === 0) {
+    log.info('[os-geocoder] no results');
+    return null;
+  }
+  const top = results[0]!;
+  const isoCc = top.isoCountryCode ?? '';
+  return {
+    country: isoCc.toUpperCase(),
+    state: top.region ?? '',
+    city: top.city ?? '',
+    // OS reports neighborhoods inconsistently across platforms; map `district`
+    // (Apple) / `subregion` (Android fallback) to our `district` field and
+    // leave `neighborhood` empty so the user can fill it manually.
+    district: top.district ?? top.subregion ?? '',
+    neighborhood: '',
+    street: top.street ?? '',
+    number: top.streetNumber ?? '',
+    zip_code: top.postalCode ?? '',
+    latitude: args.latitude,
+    longitude: args.longitude,
+  };
+}

package/src/utils/parseGoogleAddressComponents.ts

@@ -0,0 +1,123 @@
+/**
+ * Maps Google Geocoder / Places `address_components` into
+ * `AddressInfoPayload` fields.
+ *
+ * The wire shape used here is whatever the Google Geocoding REST API
+ * returns: `{ long_name, short_name, types: string[] }`.
+ */
+
+export interface GoogleAddressComponent {
+  long_name: string;
+  short_name: string;
+  types: string[];
+}
+
+export interface ParsedAddressFields {
+  country: string;
+  state: string;
+  city: string;
+  district?: string;
+  neighborhood?: string;
+  street: string;
+  number: string;
+  zip_code: string;
+}
+
+function pick(
+  components: GoogleAddressComponent[],
+  type: string,
+  useShort: boolean,
+): string {
+  const c = components.find((x) => x.types.includes(type));
+  if (!c) return '';
+  return useShort ? c.short_name : c.long_name;
+}
+
+/**
+ * Parses `address_components` from a Geocoder result or Place result.
+ * Applies fallbacks so required API fields are usually non-empty when Google
+ * returns a result.
+ */
+export function parseGoogleAddressComponents(
+  components: GoogleAddressComponent[] | null | undefined,
+  formattedAddress: string | undefined,
+  lat: number,
+  lng: number,
+): ParsedAddressFields & { latitude: number; longitude: number } {
+  const list = components ?? [];
+  const firstLine = formattedAddress?.split(',')[0]?.trim() ?? '';
+
+  const country = pick(list, 'country', true).toUpperCase();
+  const state =
+    pick(list, 'administrative_area_level_1', false) ||
+    pick(list, 'administrative_area_level_2', false);
+  const city =
+    pick(list, 'locality', false) ||
+    pick(list, 'administrative_area_level_2', false) ||
+    pick(list, 'administrative_area_level_3', false) ||
+    pick(list, 'sublocality_level_1', false);
+  const district =
+    pick(list, 'sublocality_level_1', false) ||
+    pick(list, 'sublocality', false) ||
+    pick(list, 'administrative_area_level_3', false) ||
+    undefined;
+  const neighborhood = pick(list, 'neighborhood', false) || undefined;
+  const route = pick(list, 'route', false);
+  const streetNumber = pick(list, 'street_number', false);
+  const postal = pick(list, 'postal_code', false);
+
+  let street = route;
+  if (!street && firstLine) street = firstLine;
+  if (!street) street = '—';
+
+  const number = streetNumber || 'S/N';
+  const zip_code = postal || '0000';
+
+  let cityOut = city;
+  if (!cityOut) cityOut = state || '—';
+  let stateOut = state;
+  if (!stateOut) stateOut = cityOut;
+
+  const out: ParsedAddressFields & { latitude: number; longitude: number } = {
+    country: country || 'XX',
+    state: stateOut,
+    city: cityOut,
+    street,
+    number,
+    zip_code,
+    latitude: lat,
+    longitude: lng,
+  };
+  if (district) out.district = district;
+  if (neighborhood) out.neighborhood = neighborhood;
+  return out;
+}
+
+/**
+ * True when the parsed address has enough required fields to send to the
+ * backend.
+ */
+export function isAddressSelectionComplete(
+  parsed: ParsedAddressFields,
+  required: {
+    state?: boolean | undefined;
+    city?: boolean | undefined;
+    street?: boolean | undefined;
+    number?: boolean | undefined;
+    postal?: boolean | undefined;
+  } = {},
+): boolean {
+  const reqState = required.state !== false;
+  const reqCity = required.city !== false;
+  const reqStreet = required.street !== false;
+  const reqNumber = required.number !== false;
+  const reqPostal = required.postal !== false;
+  return (
+    parsed.country.length === 2 &&
+    (!reqState || parsed.state.length > 0) &&
+    (!reqCity || parsed.city.length > 0) &&
+    (!reqStreet || parsed.street.length > 0) &&
+    (!reqNumber || parsed.number.length > 0) &&
+    (!reqPostal || parsed.zip_code.length > 0)
+  );
+}

package/src/utils/personNameNormalize.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalizes a single name field (given names or surnames) for API submission.
+ *
+ * - Trims leading/trailing whitespace
+ * - Applies Unicode NFC (composed form) for consistent encoding
+ * - Splits on any run of whitespace and rejoins with a single ASCII space,
+ *   so multiple internal spaces or line breaks become one separator between words
+ */
+export function normalizePersonNameSegment(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return '';
+  }
+  const nfc = trimmed.normalize('NFC');
+  const words = nfc.split(/\s+/).filter((w) => w.length > 0);
+  return words.join(' ');
+}

package/src/utils/sdkError.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Helpers to normalize thrown values into SdkError for consistent onError delivery.
+ */
+
+import { SdkErrorCode, type SdkError } from '../types';
+
+/**
+ * Returns true if the value looks like an SdkError (has code and message).
+ */
+export function isSdkError(value: unknown): value is SdkError {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'code' in value &&
+    typeof (value as SdkError).code === 'string' &&
+    'message' in value &&
+    typeof (value as SdkError).message === 'string'
+  );
+}
+
+/**
+ * Normalizes any thrown value to an SdkError so it can be passed to rejectStep/onError.
+ * Use when catching in a flow that must always end with an event to the implementer.
+ */
+export function toSdkError(
+  err: unknown,
+  defaultCode: SdkErrorCode,
+  defaultMessage: string,
+): SdkError {
+  if (isSdkError(err)) {
+    return err;
+  }
+  const message =
+    err instanceof Error ? err.message : typeof err === 'string' ? err : defaultMessage;
+  return {
+    code: defaultCode,
+    message: message || defaultMessage,
+    cause: err,
+  };
+}

package/src/utils/sdkVersion.ts

@@ -0,0 +1,6 @@
+/**
+ * Compile-time SDK version string sent on every authenticated request as
+ * `X-Velion-SDK-Version`. Bump it together with `sdk/package.json#version`
+ * on every release.
+ */
+export const SDK_VERSION = '0.1.0' as const;

package/src/utils/stepConfig.ts

@@ -0,0 +1,75 @@
+import type {
+  DocumentCaptureMode,
+  DocumentsOcrStepConfig,
+  HumanBasicInfoStepConfig,
+  TermsAndConditionsItem,
+  TermsAndConditionsStepConfig,
+} from '../types';
+
+export function resolveDocumentOptionsFromStepConfig(
+  cfg: HumanBasicInfoStepConfig | undefined,
+): Array<{ value: string; label: string }> | undefined {
+  const rows = cfg?.accepted_country_documents;
+  if (!Array.isArray(rows)) return undefined;
+  const out: Array<{ value: string; label: string }> = [];
+  for (const country of rows) {
+    const docs = country?.document_types;
+    if (!Array.isArray(docs)) continue;
+    for (const d of docs) {
+      const id = d?.id;
+      if (!id || typeof id !== 'string') continue;
+      out.push({
+        value: id,
+        label: typeof d.display_value === 'string' && d.display_value.trim().length > 0
+          ? d.display_value
+          : id,
+      });
+    }
+  }
+  return out.length > 0 ? dedupeByValue(out) : undefined;
+}
+
+export function resolveCaptureModeFromStepConfig(
+  cfg: DocumentsOcrStepConfig | undefined,
+): DocumentCaptureMode | undefined {
+  const methods = cfg?.capture_methods;
+  if (!methods) return undefined;
+  const camera = methods.camera_scan !== false;
+  const upload = methods.upload !== false;
+  if (camera && upload) return 'both';
+  if (camera) return 'camera';
+  if (upload) return 'file';
+  return 'both';
+}
+
+export function resolveTermsFromStepConfig(
+  cfg: TermsAndConditionsStepConfig | undefined,
+): TermsAndConditionsItem[] | undefined {
+  const terms = cfg?.terms;
+  if (!Array.isArray(terms)) return undefined;
+  const parsed: TermsAndConditionsItem[] = [];
+  for (const [index, term] of terms.entries()) {
+    const title = typeof term?.title === 'string' ? term.title.trim() : '';
+    const url = typeof term?.url === 'string' ? term.url.trim() : '';
+    if (!title && !url) continue;
+    parsed.push({
+      id: `term-${index + 1}`,
+      description: title || url,
+      ...(url && { link: url }),
+    });
+  }
+  return parsed.length > 0 ? parsed : undefined;
+}
+
+function dedupeByValue(
+  options: Array<{ value: string; label: string }>,
+): Array<{ value: string; label: string }> {
+  const seen = new Set<string>();
+  const out: Array<{ value: string; label: string }> = [];
+  for (const opt of options) {
+    if (seen.has(opt.value)) continue;
+    seen.add(opt.value);
+    out.push(opt);
+  }
+  return out;
+}

package/src/utils/taxInfoConfig.ts

@@ -0,0 +1,14 @@
+import type { TaxInfoConfig } from '../types';
+
+/**
+ * Normalizes selectable lists for TAX_INFO. Options come only from the backend
+ * `current_step.config.accepted_tax_information` (see TaxInfoModule); there are no SDK defaults.
+ */
+export function resolveTaxInfoConfig(config: Partial<TaxInfoConfig> | undefined): TaxInfoConfig {
+  const categories = config?.taxpayerCategories;
+  const fiscal = config?.fiscalIdentifierTypes;
+  return {
+    taxpayerCategories: Array.isArray(categories) ? categories : [],
+    fiscalIdentifierTypes: Array.isArray(fiscal) ? fiscal : [],
+  };
+}