feat: scaffold mrz, nfc, and qr feature directories

packages/mobile-sdk-alpha/docs/ARCHITECTURE_CHECKLIST.md

@@ -0,0 +1,63 @@
+# Architecture
+
+> Detailed task prompts are listed in [ARCHITECTURE_PROMPTS.md](./ARCHITECTURE_PROMPTS.md).
+
+## Overview
+
+The alpha SDK follows an adapter-first, React Native–oriented design. Tree-shakable named exports and `"sideEffects": false` keep bundles lean. While React Native is the only supported platform today, the structure below leaves room to add web, Capacitor, or Cordova targets without major refactors.
+
+## Architecture Checklist (easy → hard)
+
+### 1. Modular feature directories ✅ COMPLETED
+
+- [x] Group new capabilities (e.g., `mrz/`, `nfc/`, `qr/`) in their own folders
+- [x] Re-export from `src/index.ts` using explicit named exports (avoid `export *`)
+- [x] Create `src/nfc/`, `src/mrz/`, and `src/qr/` modules
+- [x] Implement proper error handling with `notImplemented` helper
+- [x] Use type aliases instead of empty interfaces for better tree shaking
+
+### 2. Bridge layer for native events
+
+- [ ] Wrap `NativeModules`/`NativeEventEmitter` so features register listeners through a shared adapter
+- [ ] Create unified event handling interface
+- [ ] Implement platform-specific event bridges
+
+### 3. Exception classes
+
+- [ ] Add typed errors (`InitError`, `LivenessError`, etc.)
+- [ ] Surface typed errors instead of generic `Error`
+- [ ] Ensure consistent error categorization
+
+### 4. SDK lifecycle management
+
+- [ ] Evolve `createSelfClient` into an SDK class
+- [ ] Add `initialize`/`deinitialize` methods
+- [ ] Implement stored config management
+
+### 5. Package targets
+
+- [ ] Keep React Native build first
+- [ ] Scaffold entry points for web environments
+- [ ] Prepare for future environments (Capacitor/Cordova)
+
+### 6. Dogfood in `/app`
+
+- [ ] Integrate the SDK into the monorepo's `app` workspace
+- [ ] Validate real flows
+- [ ] Replace existing MRZ/NFC modules with SDK adapters
+
+### 7. Android demo app
+
+- [ ] Ship a minimal React Native Android project
+- [ ] Demonstrate MRZ → NFC → proof generation flow
+- [ ] Provide build and run instructions
+
+## Working in Parallel
+
+Architecture tasks above can proceed alongside the SDK migration checklist. Steps completed in the migration doc (currently through step 2) unblock items 3–5, so teams can tackle architecture and migration independently.
+
+## Additional Notes
+
+- Favor small, sensical abstractions over premature generality.
+- Maintain tree-shakability by avoiding side effects in new modules.
+- Document new APIs and flows under `docs/` as they solidify.

packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md

@@ -22,8 +22,8 @@ yarn build
 <details>
 <summary><strong>Split features into dedicated folders</strong></summary>
 
-1. Under `src/`, create folders like `liveness/` and `detection/` as features are added.
-2. Re-export feature APIs from `src/index.ts` to keep tree shaking intact.
+1. Under `src/`, create folders like `mrz/`, `nfc/`, and `qr/` as features are added.
+2. Re-export feature APIs from `src/index.ts` using explicit named exports to keep tree shaking intact.
 
 </details>
 

packages/mobile-sdk-alpha/docs/MIGRATION_CHECKLIST.md

@@ -2,10 +2,15 @@
 
 > Detailed task prompts are listed in [MIGRATION_PROMPTS.md](./MIGRATION_PROMPTS.md).
 
-## 1. Processing helpers (MRZ & NFC)
+- [x] Group new capabilities into modular directories and re-export them from `src/index.ts` using named exports (initial stubs: `mrz/`, `nfc/`, `qr/`).
+
+## 1. Processing helpers (MRZ & NFC) ✅ COMPLETED
 
 - [x] Finalize MRZ utilities and add an NFC response parser.
 - [x] Re-export helpers through the SDK entry point.
+- [x] Create modular structure with `src/nfc/`, `src/mrz/`, and `src/qr/` modules.
+- [x] Implement proper error handling using `notImplemented` helper.
+- [x] Use type aliases instead of empty interfaces for better tree shaking.
 
 ## 2. Validation module
 

packages/mobile-sdk-alpha/docs/MIGRATION_PROMPTS.md

@@ -7,6 +7,7 @@ Each chapter from the migration checklist includes granular tasks below. Pick ta
 ## Before you start
 
 - Run `yarn find:migration` to locate and open `.cursor/rules/mobile-sdk-migration.mdc` for full context.
+- Group new capabilities in their own directories (e.g., `processing/`, `validation/`, `mrz/`, `nfc/`, `qr/`) and re-export them from `src/index.ts` using explicit named exports.
 
 ## Pre-flight checks
 
@@ -21,7 +22,7 @@ yarn lint
 yarn build
 ```
 
-## 1. Processing helpers (MRZ & NFC)
+## 1. Processing helpers (MRZ & NFC) ✅ COMPLETED
 
 <details>
 <summary><strong>Test MRZ parsing utilities</strong></summary>
@@ -34,17 +35,20 @@ yarn build
 <details>
 <summary><strong>Add NFC response parser</strong></summary>
 
-1. Create `src/processing/nfc.ts` exporting a pure function to parse NFC chip responses into DG1/DG2 structures.
+1. ✅ Create `src/processing/nfc.ts` exporting a pure function to parse NFC chip responses into DG1/DG2 structures.
 2. Write tests in `tests/processing/nfc.test.ts`.
-3. Ensure no React Native dependencies.
+3. ✅ Ensure no React Native dependencies.
 
 </details>
 
 <details>
 <summary><strong>Expose processing utilities</strong></summary>
 
-1. Update `src/index.ts` to re-export MRZ and NFC helpers.
-2. Document them in `README.md` under a "Processing utilities" section.
+1. ✅ Update `src/index.ts` to re-export MRZ and NFC helpers.
+2. ✅ Create modular structure with `src/nfc/`, `src/mrz/`, and `src/qr/` modules.
+3. ✅ Implement proper error handling using `notImplemented` helper.
+4. ✅ Use type aliases instead of empty interfaces for better tree shaking.
+5. Document them in `README.md` under a "Processing utilities" section.
 
 </details>
 

packages/mobile-sdk-alpha/src/browser.ts

@@ -34,10 +34,13 @@ export type {
 
 // Core functions
 export type { SdkErrorCategory } from './errors';
+export { type DG1, type DG2, type NFCScanOptions, type ParsedNFCResponse, parseNFCResponse, scanNFC } from './nfc';
+export { type MRZScanOptions, extractMRZInfo, formatDateToYYMMDD, scanMRZ } from './mrz';
+export { type QRProofOptions, scanQRProof } from './qr';
 export { SCANNER_ERROR_CODES, notImplemented, sdkError } from './errors';
+
 export { createSelfClient } from './client';
 export { defaultConfig } from './config/defaults';
-
-export { extractMRZInfo, formatDateToYYMMDD } from './processing/mrz';
+export { mergeConfig } from './config/merge';
 // Error handling
 export { webScannerShim } from './adapters/web/shims';

packages/mobile-sdk-alpha/src/index.ts

@@ -30,13 +30,17 @@ export type {
   WsConn,
 } from './types/public';
 
-export type { DG1, DG2, ParsedNFCResponse } from './processing/nfc';
-// Core functions
+// NFC module
 export type { SdkErrorCategory } from './errors';
+// MRZ module
+export { type DG1, type DG2, type NFCScanOptions, type ParsedNFCResponse, parseNFCResponse, scanNFC } from './nfc';
+// QR module
+export { type MRZScanOptions, extractMRZInfo, formatDateToYYMMDD, scanMRZ } from './mrz';
+// Core functions
+export { type QRProofOptions, scanQRProof } from './qr';
 export { SCANNER_ERROR_CODES, notImplemented, sdkError } from './errors';
 export { createSelfClient } from './client';
 export { defaultConfig } from './config/defaults';
-export { extractMRZInfo, formatDateToYYMMDD } from './processing/mrz';
-export { parseNFCResponse } from './processing/nfc';
+export { mergeConfig } from './config/merge';
 // Error handling
 export { webScannerShim } from './adapters/web/shims';

packages/mobile-sdk-alpha/src/mrz/index.ts

@@ -0,0 +1,21 @@
+import { notImplemented } from '../errors';
+import type { ScanResult } from '../types/public';
+
+/**
+ * Options for MRZ scanning.
+ * Reserved for future use; currently no options are accepted.
+ */
+export type MRZScanOptions = Record<string, never>;
+
+// Re-export processing functions
+export { extractMRZInfo, formatDateToYYMMDD } from '../processing/mrz';
+
+/**
+ * Scan MRZ (Machine Readable Zone) on a passport or ID card.
+ * @param _opts MRZ scanning options (currently unused)
+ * @returns Promise resolving to scan result
+ */
+export async function scanMRZ(_opts: MRZScanOptions): Promise<ScanResult> {
+  // Surface a consistent, typed error for unimplemented features
+  throw notImplemented('scanMRZ');
+}

packages/mobile-sdk-alpha/src/nfc/index.ts

@@ -0,0 +1,24 @@
+import { notImplemented } from '../errors';
+import type { ScanResult } from '../types/public';
+
+// Re-export types from processing
+export type { DG1, DG2, ParsedNFCResponse } from '../processing/nfc';
+
+/**
+ * Options for NFC scanning.
+ * Reserved for future use; currently no options are accepted.
+ */
+export type NFCScanOptions = Record<string, never>;
+
+// Re-export processing functions
+export { parseNFCResponse } from '../processing/nfc';
+
+/**
+ * Scan NFC chip on a passport or ID card.
+ * @param _opts NFC scanning options (currently unused)
+ * @returns Promise resolving to scan result
+ */
+export async function scanNFC(_opts: NFCScanOptions): Promise<ScanResult> {
+  // Surface a consistent, typed error for unimplemented features
+  throw notImplemented('scanNFC');
+}

packages/mobile-sdk-alpha/src/qr/index.ts

@@ -0,0 +1,18 @@
+import { notImplemented } from '../errors';
+import type { ScanResult } from '../types/public';
+
+/**
+ * Options for QR proof scanning.
+ * Reserved for future use; currently no options are accepted.
+ */
+export type QRProofOptions = Record<string, never>;
+
+/**
+ * Scan QR code containing proof data.
+ * @param _opts QR proof scanning options (currently unused)
+ * @returns Promise resolving to scan result
+ */
+export async function scanQRProof(_opts: QRProofOptions): Promise<ScanResult> {
+  // Surface a consistent, typed error for unimplemented features
+  throw notImplemented('scanQRProof');
+}