@trustchex/react-native-sdk 1.478.7 → 1.481.1

package/src/Shared/Libs/diagnostics.ts

@@ -0,0 +1,251 @@
+/**
+ * Diagnostics collector for the "Report a scanning issue" feature.
+ *
+ * Accumulates a PII-light technical snapshot of a single scan session — camera
+ * quality, MRZ consensus, and (the highest-value, most device-specific part) a
+ * structured per-step NFC/eID read log. The result screen serialises this into
+ * the diagnostic email the user reviews and sends to support.
+ *
+ * Design notes:
+ * - This is a MODULE-LEVEL SINGLETON so the deep camera/EID call stack can record
+ *   into it without threading a prop/context through every layer. Call `reset()`
+ *   at the start of a scan flow.
+ * - It stores only TECHNICAL signals (counts, timings, brightness, APDU status
+ *   words, pass/fail). It deliberately holds NO identity data, images, MRZ text,
+ *   keys, or nonces — the scanned identity/images shown to the user come from the
+ *   result screen's own state, not from here, and are attached separately with
+ *   the user's explicit review in the email draft.
+ */
+
+/** A single step of the NFC/eID read, with its outcome and timing. */
+export interface NfcStep {
+  /** Step name: 'open' | 'selectMF' | 'readCardAccess' | 'paceAuth' | 'bacAuth'
+   * | 'selectApplet' | 'readDG1' | 'readDG2' | … */
+  step: string;
+  ok: boolean;
+  ms: number;
+  /** APDU status word (hex, e.g. "6982") when the step failed at the APDU level. */
+  sw?: string;
+  /** Coarse, non-PII error CATEGORY when the step failed (e.g. "auth_failed",
+   * "tag_lost", "reading_error") — never the raw error text. */
+  error?: string;
+}
+
+export interface NfcDiagnostics {
+  attempted: boolean;
+  chipDetected: boolean;
+  /** 'PACE' | 'BAC' | 'none' */
+  authProtocol: 'PACE' | 'BAC' | 'none';
+  paceFellBackToBac: boolean;
+  /** PACE object identifier string when PACE was attempted. */
+  paceOid?: string;
+  /** Why PACE wasn't used / fell back: 'no_card_access' | 'no_pace_info' |
+   * 'pace_failed'. Distinguishes device/chip-specific PACE issues. */
+  paceFallbackReason?: string;
+  steps: NfcStep[];
+  /** Name of the first failing step, if any. */
+  failureStep?: string;
+  /** Coarse category: 'auth_failed' | 'tag_lost' | 'timeout' | 'unsupported'
+   * | 'not_enabled' | 'user_cancelled' | 'reading_error' | null */
+  errorCategory?: string;
+  retryCount: number;
+  succeeded: boolean;
+}
+
+export interface CameraDiagnostics {
+  frames: number;
+  frameW: number;
+  frameH: number;
+  avgBrightness: number;
+  minBrightness: number;
+  maxBrightness: number;
+  hadLowBrightness: boolean;
+  hadBlurryFrames: boolean;
+  /**
+   * The thresholds the measured values were judged against, so support can read
+   * "117 measured vs 65 floor" rather than just a pass/fail flag. Recorded once.
+   */
+  thresholds?: {
+    brightnessLow?: number;
+    brightnessHigh?: number;
+    minBrightness?: number;
+    blur?: number;
+  };
+}
+
+export interface MrzDiagnostics {
+  framesProcessed: number;
+  reachedStable: boolean;
+  stabilityFrames: number;
+  /** Smallest winning vote margin across contested cells at acceptance. */
+  minContestedMargin: number;
+  /**
+   * Largest MRZ-band pixel height seen (max OCR'd text-block height). Compared
+   * to the ~16px/character ML Kit floor, this explains "scans on device A,
+   * fails on device B" — a smaller band falls below the OCR resolution floor.
+   */
+  maxMrzBandHeightPx?: number;
+  format?: string;
+  /** Per-field check-digit outcomes: 'pass' | 'fail' (no values, no PII). */
+  checkDigits?: Record<string, 'pass' | 'fail'>;
+  /** True when the Turkish leading-serial-letter check-digit convention was used
+   * to accept the document number (set at report-build time from the final MRZ). */
+  turkishLetterPrefixApplied: boolean;
+}
+
+export interface DiagnosticsSnapshot {
+  schemaVersion: number;
+  generatedAt: string;
+  documentType?: string;
+  dataSource?: string;
+  totalDurationMs: number;
+  camera: CameraDiagnostics;
+  mrz: MrzDiagnostics;
+  nfc: NfcDiagnostics;
+  /** Sanitised, non-PII error entries collected during the session. */
+  errors: Array<{ code?: string; category?: string; screen?: string }>;
+}
+
+const emptyCamera = (): CameraDiagnostics => ({
+  frames: 0,
+  frameW: 0,
+  frameH: 0,
+  avgBrightness: 0,
+  minBrightness: 0,
+  maxBrightness: 0,
+  hadLowBrightness: false,
+  hadBlurryFrames: false,
+});
+
+const emptyMrz = (): MrzDiagnostics => ({
+  framesProcessed: 0,
+  reachedStable: false,
+  stabilityFrames: 0,
+  minContestedMargin: 0,
+  turkishLetterPrefixApplied: false,
+});
+
+const emptyNfc = (): NfcDiagnostics => ({
+  attempted: false,
+  chipDetected: false,
+  authProtocol: 'none',
+  paceFellBackToBac: false,
+  steps: [],
+  retryCount: 0,
+  succeeded: false,
+});
+
+/**
+ * Accumulates one scan session's diagnostics. A single shared instance is
+ * exported below; tests can construct their own.
+ */
+export class DiagnosticsCollector {
+  private startedAtMs = 0;
+  private documentType?: string;
+  private dataSource?: string;
+  private camera = emptyCamera();
+  private mrz = emptyMrz();
+  private nfc = emptyNfc();
+  private errors: DiagnosticsSnapshot['errors'] = [];
+
+  /** Begin a fresh session — call when a scan flow starts. */
+  reset(nowMs: number): void {
+    this.startedAtMs = nowMs;
+    this.documentType = undefined;
+    this.dataSource = undefined;
+    this.camera = emptyCamera();
+    this.mrz = emptyMrz();
+    this.nfc = emptyNfc();
+    this.errors = [];
+  }
+
+  setDocument(documentType?: string, dataSource?: string): void {
+    if (documentType) this.documentType = documentType;
+    if (dataSource) this.dataSource = dataSource;
+  }
+
+  /** Merge a camera snapshot (called periodically as frames arrive). */
+  setCamera(c: Partial<CameraDiagnostics>): void {
+    this.camera = { ...this.camera, ...c };
+  }
+
+  /** Merge MRZ consensus metrics. `reachedStable` is STICKY (once true, stays
+   * true) so a later frame's flicker can't unset that the scan did stabilise;
+   * `maxMrzBandHeightPx` keeps the largest seen. */
+  setMrz(m: Partial<MrzDiagnostics>): void {
+    const reachedStable = this.mrz.reachedStable || m.reachedStable === true;
+    const maxMrzBandHeightPx =
+      Math.max(
+        this.mrz.maxMrzBandHeightPx ?? 0,
+        m.maxMrzBandHeightPx ?? 0
+      ) || undefined;
+    this.mrz = { ...this.mrz, ...m, reachedStable, maxMrzBandHeightPx };
+  }
+
+  // ---- NFC: the structured per-step log ----
+
+  nfcAttemptStarted(): void {
+    // A fresh attempt: bump retry count if a previous attempt left steps.
+    if (this.nfc.attempted) this.nfc.retryCount += 1;
+    this.nfc.attempted = true;
+  }
+
+  nfcChipDetected(): void {
+    this.nfc.chipDetected = true;
+  }
+
+  nfcSetAuth(protocol: 'PACE' | 'BAC' | 'none', oid?: string): void {
+    this.nfc.authProtocol = protocol;
+    if (oid) this.nfc.paceOid = oid;
+  }
+
+  nfcPaceFellBackToBac(reason?: string): void {
+    this.nfc.paceFellBackToBac = true;
+    if (reason && !this.nfc.paceFallbackReason) {
+      this.nfc.paceFallbackReason = reason;
+    }
+  }
+
+  /** Record one completed step. Keep messages short and free of PII. */
+  nfcStep(step: NfcStep): void {
+    this.nfc.steps.push(step);
+    if (!step.ok && !this.nfc.failureStep) {
+      this.nfc.failureStep = step.step;
+    }
+  }
+
+  nfcResult(succeeded: boolean, errorCategory?: string): void {
+    this.nfc.succeeded = succeeded;
+    if (succeeded) {
+      // The read ultimately succeeded — transient per-attempt failures (e.g. a
+      // recovered DG2 retry, or the expected EF.CardAccess 6982 on a BAC-only
+      // card) must NOT be reported as the outcome. Clear the failure markers.
+      this.nfc.failureStep = undefined;
+      this.nfc.errorCategory = undefined;
+    } else if (errorCategory) {
+      this.nfc.errorCategory = errorCategory;
+    }
+  }
+
+  addError(e: { code?: string; category?: string; screen?: string }): void {
+    this.errors.push(e);
+  }
+
+  /** Build the serialisable snapshot. */
+  snapshot(nowMs: number, isoNow: string): DiagnosticsSnapshot {
+    return {
+      schemaVersion: 1,
+      generatedAt: isoNow,
+      documentType: this.documentType,
+      dataSource: this.dataSource,
+      totalDurationMs: this.startedAtMs ? Math.max(0, nowMs - this.startedAtMs) : 0,
+      camera: { ...this.camera },
+      mrz: { ...this.mrz },
+      nfc: { ...this.nfc, steps: this.nfc.steps.map((s) => ({ ...s })) },
+      errors: this.errors.map((e) => ({ ...e })),
+    };
+  }
+}
+
+/** Shared session-scoped collector used across the scan flow. */
+export const diagnostics = new DiagnosticsCollector();

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -43,8 +43,29 @@ export interface MRZFrameInput {
    * focus-weighted voting beats unweighted.
    */
   weight?: number;
+  /**
+   * Optional OCR confidence for this frame, in [0, 1] — e.g. ML Kit's mean
+   * per-symbol confidence over the MRZ characters (Android bundled library only;
+   * iOS ML Kit exposes no symbol confidence). When present it MULTIPLIES `weight`,
+   * so a frame the recognizer was unsure about contributes proportionally fewer
+   * votes than a confident one of the same sharpness. This is the per-frame form
+   * of confidence-weighted voting: it can't misalign cells (unlike threading
+   * per-column confidence through the column-shifting line reconstruction), yet
+   * still lets confident frames dominate look-alike ties (A↔4, S↔5, B↔8).
+   *
+   * A confidence floor is applied so a single near-zero frame is down-weighted
+   * but never fully silenced (it may still hold the only vote for some cell).
+   */
+  confidence?: number;
 }
 
+/**
+ * Floor applied to a frame's confidence multiplier. A frame ML Kit was very
+ * unsure about still contributes (it may carry the only reading of a cell), but
+ * at a fraction of a confident frame's weight.
+ */
+const MIN_CONFIDENCE_WEIGHT = 0.25;
+
 export interface MRZConsensus {
   /** Best consensus MRZ (newline-joined fixed-width lines), or null if none yet. */
   mrz: string | null;
@@ -57,6 +78,18 @@ export interface MRZConsensus {
    * last `stabilityTarget` contributing frames. Callers should advance only then.
    */
   stable: boolean;
+  /**
+   * How many consecutive contributing frames the current (valid) consensus has
+   * stayed unchanged. Diagnostic: convergence speed across devices.
+   */
+  stableStreak: number;
+  /**
+   * Smallest winning vote margin across all CONTESTED cells of the best format
+   * (cells where >1 distinct char was voted). Higher = more confident reading;
+   * a low value at acceptance means a look-alike was barely resolved. Infinity
+   * when no cell is contested (a perfectly clean read). Diagnostic only.
+   */
+  minContestedMargin: number;
 }
 
 export interface MRZFrameAggregatorOptions {
@@ -244,7 +277,15 @@ export class MRZFrameAggregator {
    * consensus is returned.
    */
   addFrame(input: MRZFrameInput): MRZConsensus {
-    const weight = input.weight && input.weight > 0 ? input.weight : 1;
+    const baseWeight = input.weight && input.weight > 0 ? input.weight : 1;
+    // Fold OCR confidence into the weight (clamped to [floor, 1]). Absent
+    // confidence leaves the weight unchanged, so callers without per-symbol
+    // confidence (e.g. iOS ML Kit) keep the prior sharpness-only behaviour.
+    const confidenceFactor =
+      typeof input.confidence === 'number' && Number.isFinite(input.confidence)
+        ? Math.min(1, Math.max(MIN_CONFIDENCE_WEIGHT, input.confidence))
+        : 1;
+    const weight = baseWeight * confidenceFactor;
     const lines = linesForFrame(input.text);
 
     if (lines) {
@@ -311,18 +352,30 @@ export class MRZFrameAggregator {
    * is what turns "looks valid this frame" into "the camera agrees across frames".
    */
   private consensusIsConfident(format: string): boolean {
+    return this.minContestedMargin(format) >= this.minMargin;
+  }
+
+  /**
+   * Smallest winning vote margin across all CONTESTED cells (where >1 distinct
+   * char was voted). Returns Infinity when no cell is contested. Used both to
+   * gate confidence and to surface a diagnostic of how narrowly a look-alike was
+   * resolved at acceptance.
+   */
+  private minContestedMargin(format: string): number {
     const geom = FORMAT_GEOMETRY[format];
     const tally = this.tallies[format];
+    let min = Infinity;
     for (let li = 0; li < geom.lines; li++) {
       for (let ci = 0; ci < geom.width; ci++) {
         const cell = tally[li][ci];
         const weights = Object.values(cell);
         if (weights.length < 2) continue; // uncontested cell — no ambiguity
         weights.sort((a, b) => b - a);
-        if (weights[0] - weights[1] < this.minMargin) return false;
+        const margin = weights[0] - weights[1];
+        if (margin < min) min = margin;
       }
     }
-    return true;
+    return min;
   }
 
   /** Read out the winning character per cell for a format. */
@@ -365,6 +418,8 @@ export class MRZFrameAggregator {
         validation: null,
         frames: this.frameCount,
         stable: false,
+        stableStreak: 0,
+        minContestedMargin: Infinity,
       };
     }
 
@@ -415,6 +470,9 @@ export class MRZFrameAggregator {
       frames: this.frameCount,
       stable:
         bestValid && confident && this.stableStreak >= this.stabilityTarget,
+      stableStreak: this.stableStreak,
+      minContestedMargin:
+        bestFormat != null ? this.minContestedMargin(bestFormat) : Infinity,
     };
   }
 }

package/src/Shared/Libs/native-device-info.utils.ts

@@ -1,6 +1,122 @@
 import { Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
+/**
+ * Full, non-PII device details for the support diagnostic report. Device-
+ * specific scanning/NFC issues correlate with hardware, OS level, memory and
+ * NFC capability, so we capture a broad-but-safe set. Excludes anything that
+ * identifies a person (uniqueId is a per-install vendor id, not PII, and is kept
+ * only for correlating repeat reports from the same device).
+ */
+export interface DeviceDetails {
+  platform: string; // 'ios' | 'android'
+  systemName: string; // 'iOS' | 'Android'
+  systemVersion: string;
+  apiLevel?: number; // Android API level
+  brand: string;
+  manufacturer: string;
+  model: string;
+  deviceId: string; // hardware model code, e.g. "iPhone16,1" / "tegu"
+  deviceType: string; // Handset / Tablet / …
+  isTablet: boolean;
+  isEmulator: boolean;
+  hasNotch: boolean;
+  totalMemoryMB?: number;
+  usedMemoryMB?: number;
+  totalDiskMB?: number;
+  freeDiskMB?: number;
+  batteryLevel?: number; // 0..1
+  appVersion: string;
+  buildNumber: string;
+  bundleId: string;
+  fontScale?: number;
+  installerPackage?: string;
+}
+
+/** Resolve an async getter to a number, tolerating failure. */
+const num = async (p: Promise<number>): Promise<number | undefined> => {
+  try {
+    const v = await p;
+    return typeof v === 'number' && isFinite(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Resolve an async getter, falling back on failure. */
+const safe = async <T>(p: Promise<T>, fallback: T): Promise<T> => {
+  try {
+    return await p;
+  } catch {
+    return fallback;
+  }
+};
+
+/** Read a synchronous getter, tolerating failure. */
+const sync = <T>(fn: () => T, fallback: T): T => {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+};
+
+/** Gather the full non-PII device profile for a diagnostic report. */
+export const gatherDeviceDetails = async (): Promise<DeviceDetails> => {
+  const bytesToMB = (b?: number) =>
+    b === undefined ? undefined : Math.round(b / (1024 * 1024));
+  const isAndroid = Platform.OS === 'android';
+
+  const [
+    manufacturer,
+    isEmulator,
+    apiLevel,
+    installerPackage,
+    totalMemory,
+    usedMemory,
+    totalDisk,
+    freeDisk,
+    batteryLevel,
+    fontScale,
+  ] = await Promise.all([
+    safe(DeviceInfo.getManufacturer(), 'unknown'),
+    safe(DeviceInfo.isEmulator(), false),
+    isAndroid ? num(DeviceInfo.getApiLevel()) : Promise.resolve(undefined),
+    safe(DeviceInfo.getInstallerPackageName(), 'unknown'),
+    num(DeviceInfo.getTotalMemory()),
+    num(DeviceInfo.getUsedMemory()),
+    num(DeviceInfo.getTotalDiskCapacity()),
+    num(DeviceInfo.getFreeDiskStorage()),
+    num(DeviceInfo.getBatteryLevel()),
+    num(DeviceInfo.getFontScale()),
+  ]);
+
+  return {
+    platform: Platform.OS,
+    systemName: isAndroid ? 'Android' : 'iOS',
+    systemVersion: sync(() => DeviceInfo.getSystemVersion(), 'unknown'),
+    apiLevel,
+    brand: sync(() => DeviceInfo.getBrand(), 'unknown'),
+    manufacturer,
+    model: sync(() => DeviceInfo.getModel(), 'unknown'),
+    deviceId: sync(() => DeviceInfo.getDeviceId(), 'unknown'),
+    deviceType: sync(() => DeviceInfo.getDeviceType(), 'unknown'),
+    isTablet: sync(() => DeviceInfo.isTablet(), false),
+    isEmulator,
+    hasNotch: sync(() => DeviceInfo.hasNotch(), false),
+    totalMemoryMB: bytesToMB(totalMemory),
+    usedMemoryMB: bytesToMB(usedMemory),
+    totalDiskMB: bytesToMB(totalDisk),
+    freeDiskMB: bytesToMB(freeDisk),
+    batteryLevel,
+    appVersion: sync(() => DeviceInfo.getVersion(), 'unknown'),
+    buildNumber: sync(() => DeviceInfo.getBuildNumber(), 'unknown'),
+    bundleId: sync(() => DeviceInfo.getBundleId(), 'unknown'),
+    fontScale,
+    installerPackage,
+  };
+};
+
 export const NativeDeviceInfo = {
   generateHumanReadableIdentifier: async (): Promise<string> => {
     try {

package/src/Shared/Libs/sendDiagnosticReport.ts

@@ -0,0 +1,165 @@
+/**
+ * Assembles and shares the support diagnostic report.
+ *
+ * `react-native-share` is an OPTIONAL dependency: the host app opts into the
+ * diagnostic feature by installing it. When it's present we open the OS share
+ * sheet with the full report (the user picks email / WhatsApp / Drive / etc. and
+ * reviews before sending); when it's absent the feature is silently unavailable
+ * — `isDiagnosticSharingAvailable()` returns false and the result-screen button
+ * renders nothing, so apps that don't want it incur no dependency.
+ *
+ * Attached files (staged to a temp dir via react-native-fs, already an SDK dep):
+ *  - `diagnostics.json` — technical signals (device, camera, MRZ, NFC steps),
+ *  - `scan-data.json`   — the scanned identity data (PII; user reviews it),
+ *  - the captured document/face images.
+ *
+ * The readable summary rides as the share `message` so it's visible in the
+ * draft regardless of the chosen app.
+ */
+import RNFS from 'react-native-fs';
+import { diagnostics } from './diagnostics';
+import { gatherDeviceDetails } from './native-device-info.utils';
+import {
+  buildDiagnosticReport,
+  type ScanDataForReport,
+} from './diagnosticReport';
+import { logError } from './debug.utils';
+
+// `react-native-share` is OPTIONAL. Load it softly so the SDK bundles and runs
+// without it; only host apps that installed it get the diagnostic feature. A
+// static `import` would make Metro fail to resolve the module when it's absent,
+// so we use a guarded require and keep the reference typed loosely.
+type ShareModule = {
+  open: (options: Record<string, unknown>) => Promise<unknown>;
+};
+
+let shareModule: ShareModule | null | undefined;
+
+const loadShare = (): ShareModule | null => {
+  if (shareModule !== undefined) return shareModule;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require('react-native-share');
+    shareModule = (mod?.default ?? mod) as ShareModule;
+  } catch {
+    shareModule = null; // not installed — feature unavailable
+  }
+  return shareModule;
+};
+
+/**
+ * Whether diagnostic sharing is available (i.e. `react-native-share` is
+ * installed in the host app). The result-screen button hides itself when false.
+ */
+export const isDiagnosticSharingAvailable = (): boolean => loadShare() != null;
+
+export interface DiagnosticImage {
+  /** Stable file name without extension, e.g. "mrz-side". */
+  name: string;
+  base64: string;
+  mime: 'jpg' | 'png';
+}
+
+export interface SendDiagnosticParams {
+  scan: ScanDataForReport;
+  sdkVersion: string;
+  sessionId?: string;
+  /** base64 images to attach (MRZ side / front / face / NFC chip face). */
+  images?: DiagnosticImage[];
+}
+
+
+const writeTemp = async (
+  dir: string,
+  name: string,
+  data: string,
+  encoding: 'utf8' | 'base64'
+): Promise<string> => {
+  const path = `${dir}/${name}`;
+  await RNFS.writeFile(path, data, encoding);
+  return path.startsWith('file://') ? path : `file://${path}`;
+};
+
+export interface SendResult {
+  shared: boolean;
+  /** True when the user dismissed the share sheet (not an error). */
+  dismissed?: boolean;
+}
+
+/**
+ * Build the report, stage attachments, and present the share sheet. Returns
+ * { shared } — false on error, with `dismissed` set when the user cancelled.
+ */
+export const sendDiagnosticReport = async (
+  params: SendDiagnosticParams
+): Promise<SendResult> => {
+  const share = loadShare();
+  if (!share) {
+    // Optional dependency not installed — nothing to do.
+    return { shared: false };
+  }
+  const { scan, sdkVersion, sessionId, images = [] } = params;
+  const now = Date.now();
+  const iso = new Date(now).toISOString();
+
+  const device = await gatherDeviceDetails();
+  const report = buildDiagnosticReport({
+    diag: diagnostics.snapshot(now, iso),
+    device,
+    scan,
+    sdkVersion,
+    sessionId,
+  });
+
+  const dir = `${RNFS.TemporaryDirectoryPath}/trustchex-diagnostics-${now}`;
+  try {
+    await RNFS.mkdir(dir);
+    const urls: string[] = [];
+    urls.push(
+      await writeTemp(dir, 'diagnostics.json', report.diagnosticsJson, 'utf8')
+    );
+    urls.push(
+      await writeTemp(dir, 'scan-data.json', report.scanDataJson, 'utf8')
+    );
+    for (const img of images) {
+      if (!img.base64) continue;
+      urls.push(
+        await writeTemp(dir, `${img.name}.${img.mime}`, img.base64, 'base64')
+      );
+    }
+
+    try {
+      await share.open({
+        title: report.subject,
+        subject: report.subject, // used by email targets
+        message: report.body,
+        urls,
+        // Per-file MIME types so targets render attachments correctly.
+        filenames: urls.map((u) => u.split('/').pop() ?? 'attachment'),
+        failOnCancel: false,
+      });
+      return { shared: true };
+    } catch (shareErr) {
+      // react-native-share throws on user cancel unless failOnCancel:false; treat
+      // a cancel as a non-error dismissal.
+      const msg =
+        shareErr instanceof Error ? shareErr.message : String(shareErr);
+      if (/cancel|dismiss|user did not share/i.test(msg)) {
+        return { shared: false, dismissed: true };
+      }
+      throw shareErr;
+    }
+  } catch (e) {
+    logError(
+      'Diagnostics',
+      'Failed to share diagnostic report',
+      e instanceof Error ? e.message : String(e)
+    );
+    return { shared: false };
+  } finally {
+    // Best-effort cleanup — temp files are short-lived.
+    setTimeout(() => {
+      RNFS.unlink(dir).catch(() => {});
+    }, 60_000);
+  }
+};

package/src/Translation/Resources/en.ts

@@ -53,6 +53,12 @@ export default {
   'resultScreen.demoVerbalConsentTitle': 'Title',
   'resultScreen.demoVerbalConsentText': 'Text',
   'resultScreen.demoStartOver': 'Start Over',
+  'diagnosticReport.button': 'Report a scanning issue',
+  'diagnosticReport.noticeTitle': 'Share diagnostic report',
+  'diagnosticReport.noticeBody':
+    'This opens a draft with your scan data, document images and technical details so support can help resolve a scanning issue. Review it before sending.',
+  'diagnosticReport.continue': 'Continue',
+  'diagnosticReport.cancel': 'Cancel',
   'livenessDetectionScreen.guideHeader': 'Face Verification',
   'livenessDetectionScreen.guideText':
     'Please ensure the following for best results:',

package/src/Translation/Resources/tr.ts

@@ -53,6 +53,12 @@ export default {
   'resultScreen.demoVerbalConsentTitle': 'Başlık',
   'resultScreen.demoVerbalConsentText': 'Metin',
   'resultScreen.demoStartOver': 'Baştan Başla',
+  'diagnosticReport.button': 'Tarama sorununu bildir',
+  'diagnosticReport.noticeTitle': 'Tanılama raporu paylaş',
+  'diagnosticReport.noticeBody':
+    'Bu işlem; tarama verilerinizi, belge görüntülerinizi ve teknik ayrıntıları içeren bir taslak açar; böylece destek ekibi tarama sorununu çözebilir. Göndermeden önce gözden geçirin.',
+  'diagnosticReport.continue': 'Devam et',
+  'diagnosticReport.cancel': 'İptal',
   'livenessDetectionScreen.guideHeader': 'Yüz Doğrulaması',
   'livenessDetectionScreen.guideText':
     'En iyi sonuç için lütfen şunları sağlayın:',