diff --git a/packages/mobile-sdk-alpha/docs/ARCHITECTURE.md b/packages/mobile-sdk-alpha/docs/ARCHITECTURE.md deleted file mode 100644 index b4241be36..000000000 --- a/packages/mobile-sdk-alpha/docs/ARCHITECTURE.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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** – group new capabilities (e.g., `liveness/`, `detection/`) in their own folders and re-export from `src/index.ts`. -2. **Bridge layer for native events** – wrap `NativeModules`/`NativeEventEmitter` so features register listeners through a shared adapter. -3. **Exception classes** – add typed errors (`InitError`, `LivenessError`, etc.) and surface them instead of generic `Error`. -4. **SDK lifecycle management** – evolve `createSelfClient` into an SDK class with `initialize`/`deinitialize` and stored config. -5. **Package targets** – keep React Native build first, but scaffold entry points for web and future environments (Capacitor/Cordova). -6. **Dogfood in `/app`** – integrate the SDK into the monorepo's `app` workspace to validate real flows. -7. **Android demo app** – ship a minimal React Native Android project demonstrating MRZ → NFC → proof generation. - -## 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. diff --git a/packages/mobile-sdk-alpha/docs/ARCHITECTURE_CHECKLIST.md b/packages/mobile-sdk-alpha/docs/ARCHITECTURE_CHECKLIST.md new file mode 100644 index 000000000..d5e3bb197 --- /dev/null +++ b/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. diff --git a/packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md b/packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md index 0bd4d915d..d8b4d9159 100644 --- a/packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md +++ b/packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md @@ -22,8 +22,8 @@ yarn build
Split features into dedicated folders -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.
diff --git a/packages/mobile-sdk-alpha/docs/MIGRATION_CHECKLIST.md b/packages/mobile-sdk-alpha/docs/MIGRATION_CHECKLIST.md index 9264a32ff..8cd04e4c7 100644 --- a/packages/mobile-sdk-alpha/docs/MIGRATION_CHECKLIST.md +++ b/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 diff --git a/packages/mobile-sdk-alpha/docs/MIGRATION_PROMPTS.md b/packages/mobile-sdk-alpha/docs/MIGRATION_PROMPTS.md index 6f3b68e58..14c270758 100644 --- a/packages/mobile-sdk-alpha/docs/MIGRATION_PROMPTS.md +++ b/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
Test MRZ parsing utilities @@ -34,17 +35,20 @@ yarn build
Add NFC response parser -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.
Expose processing utilities -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.
diff --git a/packages/mobile-sdk-alpha/src/browser.ts b/packages/mobile-sdk-alpha/src/browser.ts index 92da5366c..3bc0ff122 100644 --- a/packages/mobile-sdk-alpha/src/browser.ts +++ b/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'; diff --git a/packages/mobile-sdk-alpha/src/index.ts b/packages/mobile-sdk-alpha/src/index.ts index 9f86cb0a1..5e3f50287 100644 --- a/packages/mobile-sdk-alpha/src/index.ts +++ b/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'; diff --git a/packages/mobile-sdk-alpha/src/mrz/index.ts b/packages/mobile-sdk-alpha/src/mrz/index.ts new file mode 100644 index 000000000..8a6513e14 --- /dev/null +++ b/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; + +// 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 { + // Surface a consistent, typed error for unimplemented features + throw notImplemented('scanMRZ'); +} diff --git a/packages/mobile-sdk-alpha/src/nfc/index.ts b/packages/mobile-sdk-alpha/src/nfc/index.ts new file mode 100644 index 000000000..6b1ce042b --- /dev/null +++ b/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; + +// 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 { + // Surface a consistent, typed error for unimplemented features + throw notImplemented('scanNFC'); +} diff --git a/packages/mobile-sdk-alpha/src/qr/index.ts b/packages/mobile-sdk-alpha/src/qr/index.ts new file mode 100644 index 000000000..e912d6790 --- /dev/null +++ b/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; + +/** + * 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 { + // Surface a consistent, typed error for unimplemented features + throw notImplemented('scanQRProof'); +}