@myazahq/kyc-sdk-react-native 2.0.0

package/src/screens/SubmittedStep.tsx

@@ -0,0 +1,177 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { mapToKycError, safeReportError } from '../services/errors';
+import type { KYCError, KYCSubmission } from '../types/verification';
+import { useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { MyazaButton } from '../components/MyazaButton';
+import { MyazaAlert } from '../components/MyazaAlert';
+import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
+import { Icon } from '../components/Icon';
+import { fillTokens } from '../utils/tokens';
+
+// Terminal screen — 1:1 with the Flutter SDK's SubmittedScreen. Calls
+// submitAsync on mount; renders submitting / success / error views with the same
+// badges + copy. The header title is empty for this step.
+
+type Phase = 'submitting' | 'success' | 'error';
+
+const DEFAULT_SUCCESS_TITLE = 'Verification Submitted!';
+const DEFAULT_SUCCESS_DESCRIPTION =
+  "Your identity verification has been submitted for review. You'll be notified of the result.";
+
+const ERROR_TITLES: Record<string, string> = {
+  insufficient_credits: 'Credits Exhausted',
+  invalid_api_key: 'Authentication Failed',
+  feature_disabled: 'Verification Unavailable',
+  upload_failed: 'Upload Failed',
+  network_error: 'Connection Failed',
+};
+
+export function SubmittedStep({ onClose }: { onClose: () => void }): React.ReactElement {
+  const { colors } = useTheme();
+  const config = useKycConfig();
+  const store = useKycStore();
+  const existingResult = useKyc((s) => s.submissionResult);
+
+  const [phase, setPhase] = useState<Phase>('submitting');
+  const [error, setError] = useState<KYCError | null>(null);
+  const [retry, setRetry] = useState<{ attempt: number; total: number } | null>(null);
+  const reportedRef = useRef(false);
+  const kickedRef = useRef(false);
+
+  const submit = React.useCallback(async () => {
+    setPhase('submitting');
+    setError(null);
+    setRetry(null);
+    try {
+      const result = await store.getState().submitAsync((attempt, total) => setRetry({ attempt, total }));
+      const submission: KYCSubmission = {
+        verificationId: result.verificationId,
+        status: 'pending',
+        metadata: config.metadata ?? {},
+        submittedAt: new Date().toISOString(),
+      };
+      config.onSubmit?.(submission);
+      setPhase('success');
+    } catch (err) {
+      const kycError = mapToKycError(err, 'verify');
+      setError(kycError);
+      if (!reportedRef.current) {
+        reportedRef.current = true;
+        safeReportError(config.onError, kycError);
+      }
+      setPhase('error');
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, config]);
+
+  useEffect(() => {
+    if (existingResult) {
+      setPhase('success');
+      return;
+    }
+    if (!kickedRef.current) {
+      kickedRef.current = true;
+      void submit();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  if (phase === 'submitting') {
+    const retrying = retry != null;
+    return (
+      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center', paddingVertical: spacing.xl }}>
+        <MyazaPulseLoader />
+        <View style={{ height: spacing.lg }} />
+        <MyazaText variant="heading3" style={{ textAlign: 'center' }}>
+          {retrying ? 'Reconnecting…' : 'Submitting your verification…'}
+        </MyazaText>
+        <View style={{ height: spacing.sm }} />
+        <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+          {retrying ? `Connection issue — retrying (${retry!.attempt}/${retry!.total})…` : 'Please wait a moment.'}
+        </MyazaText>
+      </View>
+    );
+  }
+
+  if (phase === 'error' && error) {
+    const title = ERROR_TITLES[error.code] ?? 'Submission Failed';
+    const canRetry = error.code === 'network_error';
+    return (
+      <View style={{ flex: 1, justifyContent: 'space-between' }}>
+        <View style={{ alignItems: 'center' }}>
+          <View style={{ height: spacing.xl }} />
+          <Badge bg={colors.errorBg} border={`${colors.error}4D`}>
+            <Icon name="alert" size={44} color={colors.error} />
+          </Badge>
+          <View style={{ height: spacing.lg }} />
+          <MyazaText variant="heading1" style={{ textAlign: 'center' }}>
+            {title}
+          </MyazaText>
+          <View style={{ height: spacing.md }} />
+          <View style={{ width: '100%', paddingHorizontal: spacing.md }}>
+            <MyazaAlert variant="error" title="What happened" message={error.message} />
+          </View>
+        </View>
+        <View style={{ flexDirection: 'row', gap: spacing.md }}>
+          {canRetry ? (
+            <View style={{ flex: 1 }}>
+              <MyazaButton label="Try Again" variant="outline" leadingIcon="refresh" onPress={() => void submit()} />
+            </View>
+          ) : null}
+          <View style={{ flex: 1 }}>
+            <MyazaButton label="Close" onPress={onClose} />
+          </View>
+        </View>
+      </View>
+    );
+  }
+
+  // success
+  const title = config.success?.title ? fillTokens(config.success.title, config.userData) : DEFAULT_SUCCESS_TITLE;
+  const description = config.success?.description
+    ? fillTokens(config.success.description, config.userData)
+    : DEFAULT_SUCCESS_DESCRIPTION;
+
+  return (
+    <View style={{ flex: 1, justifyContent: 'space-between' }}>
+      <View style={{ alignItems: 'center' }}>
+        <View style={{ height: spacing.xl }} />
+        <Badge bg={colors.successBg} border={`${colors.success}4D`}>
+          <Icon name="check" size={44} color={colors.success} />
+        </Badge>
+        <View style={{ height: spacing.lg }} />
+        <MyazaText variant="heading1" style={{ textAlign: 'center' }}>
+          {title}
+        </MyazaText>
+        <View style={{ height: spacing.sm }} />
+        <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+          {description}
+        </MyazaText>
+      </View>
+      <MyazaButton label="Done" onPress={onClose} />
+    </View>
+  );
+}
+
+function Badge({ bg, border, children }: { bg: string; border: string; children: React.ReactNode }): React.ReactElement {
+  return (
+    <View
+      style={{
+        width: 88,
+        height: 88,
+        borderRadius: radius.full,
+        backgroundColor: bg,
+        borderWidth: 2,
+        borderColor: border,
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+    >
+      {children}
+    </View>
+  );
+}

package/src/services/api.ts

@@ -0,0 +1,291 @@
+import { SDK_VERSION } from './deviceMetadata';
+
+// ---------------------------------------------------------------------------
+// HTTP client — talks to the only endpoints the SDK calls (upload / verify /
+// status / config / health). Mirrors the web SDK's `services/api.ts`. Multipart
+// uploads append a real `Blob` (read from the local file URI via `uriToBlob`),
+// NOT the classic RN `{ uri, name, type }` part — Expo SDK 54+ installs a
+// WinterCG `fetch` whose serializer rejects the `{ uri }` form.
+// ---------------------------------------------------------------------------
+
+export class KYCApiError extends Error {
+  statusCode: number;
+  code?: string;
+  body?: Record<string, unknown>;
+
+  constructor(message: string, statusCode: number, code?: string, body?: Record<string, unknown>) {
+    super(message);
+    this.name = 'KYCApiError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.body = body;
+    Object.setPrototypeOf(this, KYCApiError.prototype);
+  }
+}
+
+function baseHeaders(apiKey: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    'X-SDK-Version': SDK_VERSION,
+  };
+}
+
+/**
+ * Read a local file URI (`file://…`, `content://…`, `ph://…`) into a Blob.
+ *
+ * Uses `XMLHttpRequest` (not the global `fetch`) on purpose: React Native's XHR
+ * has built-in blob support for local URIs and is NOT shadowed by the WinterCG
+ * `fetch` Expo installs — so this works regardless of which `fetch` is global.
+ * The resulting Blob is what the multipart upload appends (Expo-fetch's
+ * serializer accepts a Blob; the classic RN `{ uri }` part it rejects).
+ */
+function uriToBlob(uri: string, mimeType: string): Promise<Blob> {
+  return new Promise<Blob>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open('GET', uri, true);
+    xhr.responseType = 'blob';
+    xhr.onload = () => {
+      const blob = xhr.response as Blob | null;
+      if (blob) {
+        // Ensure the part carries the right content-type even if the platform
+        // didn't infer one from the URI.
+        resolve(blob.type ? blob : blob.slice(0, blob.size, mimeType));
+      } else {
+        reject(new Error(`Could not read file at ${uri}`));
+      }
+    };
+    xhr.onerror = () => reject(new Error(`Failed to read file at ${uri}`));
+    xhr.send();
+  });
+}
+
+async function handleResponse<T>(res: Response): Promise<T> {
+  // Some endpoints return an empty body — read as text first so JSON.parse
+  // isn't called on "" (which throws).
+  const text = await res.text();
+  let data: unknown = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { message: text };
+    }
+  }
+  if (!res.ok) {
+    const errObj = typeof data === 'object' && data !== null ? (data as Record<string, unknown>) : {};
+    const message = String(errObj.message ?? errObj.error ?? `Request failed with status ${res.status}`);
+    const code = typeof errObj.error === 'string' ? errObj.error : undefined;
+    throw new KYCApiError(message, res.status, code, errObj);
+  }
+  return data as T;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Media kinds the SDK can upload — document/selfie photos plus best-effort videos. */
+export type MediaUploadType =
+  | 'document_front'
+  | 'document_back'
+  | 'selfie'
+  | 'document_front_video'
+  | 'document_back_video'
+  | 'liveness_video';
+
+/**
+ * A file to upload, in React Native's multipart shape. `uri` points at a
+ * local file (camera capture / gallery pick); `name`/`type` populate the
+ * multipart part's filename + Content-Type.
+ */
+export interface UploadFile {
+  uri: string;
+  name?: string;
+  /** Raw mime type (codec params are stripped before sending). */
+  type?: string;
+}
+
+export interface UploadResponse {
+  mediaId: string;
+}
+
+export interface VerifyRequest {
+  country: string;
+  idType: string;
+  idNumber?: string;
+  userData?: {
+    firstName?: string;
+    lastName?: string;
+    dateOfBirth?: string;
+  };
+  mediaIds: {
+    documentFront?: string;
+    documentBack?: string;
+    selfie?: string;
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+    livenessVideo?: string;
+  };
+  metadata: {
+    requestId: string;
+    device?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+}
+
+export interface VerifyResponse {
+  verificationId: string;
+  status: 'pending';
+}
+
+/**
+ * Minimal, publishable-safe status from `GET /api/kyc/status/:id` — no PII,
+ * scores, or result data; only the lifecycle state and an org-safe reason.
+ */
+export interface VerificationStatusResponse {
+  verificationId: string;
+  status: 'pending' | 'verified' | 'failed' | 'not_found' | 'error';
+  reason?: string | null;
+  reasonCode?: string | null;
+  createdAt: string;
+  completedAt?: string;
+}
+
+export interface SdkConfigIdType {
+  country: string;
+  idType: string;
+  features: {
+    documentVerification: boolean;
+    livenessCheck: boolean;
+    govDbCheck: boolean;
+  };
+}
+
+/** Org branding configured server-side, returned with the SDK config. */
+export interface SdkConfigBranding {
+  logo?: string;
+  companyName?: string;
+  primaryColor?: string;
+}
+
+export interface SdkConfigResponse {
+  environment: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
+  idTypes: SdkConfigIdType[];
+  branding?: SdkConfigBranding;
+}
+
+export interface HealthResponse {
+  status: string;
+}
+
+// The mime types the server accepts (must mirror the server's upload allowlist).
+const IMAGE_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp'] as const;
+const VIDEO_MIME_TYPES = ['video/webm', 'video/mp4'] as const;
+
+const MIME_EXTENSIONS: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/webp': 'webp',
+  'video/webm': 'webm',
+  'video/mp4': 'mp4',
+};
+
+/**
+ * Drop codec params from a file's type (e.g. `video/mp4;codecs=...` →
+ * `video/mp4`) and fall back to a sane default per media kind when the value
+ * isn't one the server recognizes. RN cameras record mp4, so videos default
+ * to `video/mp4` (the web SDK defaults to `video/webm`).
+ */
+function normalizeMimeType(rawType: string | undefined, type: MediaUploadType): string {
+  const base = (rawType?.split(';')[0] ?? '').trim().toLowerCase();
+  const isVideo = type.endsWith('_video');
+  const allowed: readonly string[] = isVideo ? VIDEO_MIME_TYPES : IMAGE_MIME_TYPES;
+  if (allowed.includes(base)) return base;
+  return isVideo ? 'video/mp4' : 'image/jpeg';
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createKYCApi(baseUrl: string, apiKey: string) {
+  const base = `${baseUrl}/api/kyc`;
+  const headers = baseHeaders(apiKey);
+
+  // JSON request to our own server (verify, status, config, health).
+  async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const res = await fetch(`${base}${path}`, {
+      ...init,
+      headers: {
+        ...headers,
+        ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+        ...init.headers,
+      },
+    });
+    return handleResponse<T>(res);
+  }
+
+  return {
+    /**
+     * Single multipart upload: the local file is POSTed to our server, which
+     * stores it and returns the `mediaId` referenced later by /verify.
+     */
+    async upload(file: UploadFile, type: MediaUploadType, maxBytes?: number): Promise<string> {
+      const mimeType = normalizeMimeType(file.type, type);
+      const name = file.name ?? `${type}.${MIME_EXTENSIONS[mimeType]}`;
+      const form = new FormData();
+
+      // Read the local file (`file://…`) into a Blob and append THAT, not a
+      // `{ uri, name, type }` object. Expo SDK 54+ installs a WinterCG `fetch`
+      // whose multipart serializer (expo/src/winter/fetch/convertFormData) only
+      // accepts string | Blob | { bytes() } and throws "Unsupported FormDataPart
+      // implementation" on the classic RN `{ uri }` part. A Blob satisfies both
+      // Expo-fetch and React Native's own networking. The Blob carries its own
+      // content-type; pass the filename as the 3rd append arg.
+      const blob = await uriToBlob(file.uri, mimeType);
+      // Hard size ceiling (used for best-effort videos): reject locally rather than
+      // wasting an upload the server will refuse. A 4xx KYCApiError is terminal, so
+      // withRetry won't retry it and the caller drops the media.
+      if (maxBytes != null && blob.size > maxBytes) {
+        throw new KYCApiError(
+          `File too large (${(blob.size / 1024 / 1024).toFixed(1)}MB > ${(maxBytes / 1024 / 1024).toFixed(0)}MB)`,
+          413,
+          'file_too_large',
+        );
+      }
+      form.append('file', blob, name);
+      form.append('type', type);
+
+      // Don't set Content-Type — the fetch impl adds the multipart boundary.
+      const res = await fetch(`${base}/upload`, {
+        method: 'POST',
+        headers,
+        body: form,
+      });
+      const { mediaId } = await handleResponse<UploadResponse>(res);
+      return mediaId;
+    },
+
+    async verify(body: VerifyRequest): Promise<VerifyResponse> {
+      return request<VerifyResponse>('/verify', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
+    async status(verificationId: string): Promise<VerificationStatusResponse> {
+      return request<VerificationStatusResponse>(`/status/${verificationId}`);
+    },
+
+    async config(): Promise<SdkConfigResponse> {
+      return request<SdkConfigResponse>('/config');
+    },
+
+    async health(): Promise<HealthResponse> {
+      // Public endpoint — no auth needed, but the shared headers are harmless.
+      return request<HealthResponse>('/health');
+    },
+  };
+}
+
+export type KYCApi = ReturnType<typeof createKYCApi>;

package/src/services/cardCrop.ts

@@ -0,0 +1,52 @@
+// Pure card-crop geometry — no native imports, so it's unit-testable in the
+// plain-node jest env. The RN mirror of the math in the Flutter SDK's
+// `_cropCardWorker`: the live-camera preview is shown BoxFit.cover in a fixed 3:4
+// box with the ID-card guide centred at 88% width and `aspect` height; this maps
+// that guide rectangle to pixel coordinates of the captured photo.
+
+/** A crop rectangle in source-image pixels. */
+export interface CropRect {
+  originX: number;
+  originY: number;
+  width: number;
+  height: number;
+}
+
+const VIEW_AR = 3 / 4; // viewfinder box width ÷ height
+const GUIDE_WIDTH_FRACTION = 0.88; // card width as a fraction of the box (overlay GW/VB_W)
+
+/**
+ * Given the photo's pixel size and the guide `aspect` (width ÷ height), return
+ * the card-guide crop rect in photo pixels:
+ *   1. the cover-fit 3:4 box shows a centred 3:4 slice of the photo,
+ *   2. the guide is centred in that slice (88% wide, `aspect` ratio).
+ */
+export function cardCropRect(imageW: number, imageH: number, aspect: number): CropRect {
+  const photoAR = imageW / imageH;
+  let visW: number;
+  let visH: number;
+  let offX: number;
+  let offY: number;
+  if (photoAR > VIEW_AR) {
+    visH = imageH;
+    visW = imageH * VIEW_AR;
+    offX = (imageW - visW) / 2;
+    offY = 0;
+  } else {
+    visW = imageW;
+    visH = imageW / VIEW_AR;
+    offX = 0;
+    offY = (imageH - visH) / 2;
+  }
+  const leftFraction = (1 - GUIDE_WIDTH_FRACTION) / 2;
+  // card height ÷ box height = (cardWidthFrac · boxWidth / aspect) / boxHeight,
+  // and boxWidth ÷ boxHeight = VIEW_AR.
+  const heightFraction = (GUIDE_WIDTH_FRACTION * VIEW_AR) / aspect;
+  const topFraction = (1 - heightFraction) / 2;
+  return {
+    originX: offX + leftFraction * visW,
+    originY: offY + topFraction * visH,
+    width: GUIDE_WIDTH_FRACTION * visW,
+    height: heightFraction * visH,
+  };
+}