@credebl/ssi-mobile-core 2.0.3-alpha-20260410105148 → 2.1.0

package/README.md

@@ -1,194 +1,513 @@
-# Mobile SDK Core - React Context Integration
+# @credebl/ssi-mobile-core
 
-This package provides React context integration for the MobileSDK, allowing you to access the SDK instance globally throughout your React application.
+Core package for the CREDEBL Mobile SDK. Handles wallet initialization, DID operations, credential storage, key management, and React context integration.
 
-## Features
+See the [root README](../../README.md) for prerequisites and project-level setup.
 
-- **Global SDK Access**: Access the MobileSDK instance from any component
-- **Type Safety**: Full TypeScript support with proper typing
-- **State Management**: Built-in state management for SDK initialization
-- **React Integration**: Follows React best practices and patterns
+---
 
 ## Installation
 
 ```bash
-npm install @credebl/mobile-sdk-core
+npm install @credebl/ssi-mobile-core @openwallet-foundation/askar-react-native
 # or
-yarn add @credebl/mobile-sdk-core
-# or
-pnpm add @credebl/mobile-sdk-core
+yarn add @credebl/ssi-mobile-core @openwallet-foundation/askar-react-native
+```
+
+**iOS:**
+```bash
+cd ios && pod install
 ```
 
-## Quick Start
+**Android** — ensure `minSdkVersion` >= 24 in `android/app/build.gradle`.
+
+---
+
+## API Reference
+
+### Setup
+
+#### `MobileSDKProvider`
 
-### 1. Wrap your app with the SDKProvider
+Wrap your entire app with this provider. Every hook in this package must be used inside it.
 
 ```tsx
-import { SDKProvider } from '@credebl/mobile-sdk-core';
+import { MobileSDKProvider } from '@credebl/ssi-mobile-core'
 
-function App() {
+export default function App() {
   return (
-    <SDKProvider>
-      {/* Your app components */}
-    </SDKProvider>
-  );
+    <MobileSDKProvider>
+      {/* your app */}
+    </MobileSDKProvider>
+  )
 }
 ```
 
-### 2. Initialize the SDK in a component
+---
+
+#### `useMobileSDKInitializer()`
+
+Initializes the SDK. Call this once on app startup, inside `MobileSDKProvider`.
 
 ```tsx
-import { useSDKInitializer } from '@credebl/mobile-sdk-core';
+import { useEffect } from 'react'
+import { useMobileSDKInitializer, ConsoleLogger, LogLevel } from '@credebl/ssi-mobile-core'
 
 function AppInitializer() {
-  const { initializeSDK, isInitialized } = useSDKInitializer();
+  const { initializeSDK, isInitialized } = useMobileSDKInitializer()
 
   useEffect(() => {
     if (!isInitialized) {
-      initializeSDK();
+      initializeSDK({
+        agentConfig: {
+          label: 'My Wallet',
+          logger: new ConsoleLogger(LogLevel.debug),
+        },
+        askarConfig: {
+          id: 'my-wallet-id',
+          key: 'my-wallet-key',
+        },
+        modules: {},
+      })
     }
-  }, [initializeSDK, isInitialized]);
+  }, [isInitialized])
 
-  return null; // This component doesn't render anything
+  return null
 }
 ```
 
-### 3. Use the SDK anywhere in your app
+| Return value | Type | Description |
+|---|---|---|
+| `initializeSDK` | `(options) => Promise<MobileSDK>` | Call with your config to start the SDK |
+| `isInitialized` | `boolean` | `true` once the SDK is ready |
+| `sdk` | `MobileSDK \| null` | The SDK instance after initialization |
+
+---
+
+#### `useMobileSDK()`
+
+Access the SDK instance from any component inside `MobileSDKProvider`.
 
 ```tsx
-import { useSDK } from '@credebl/mobile-sdk-core';
+import { useMobileSDK } from '@credebl/ssi-mobile-core'
 
-function SomeComponent() {
-  const { sdk, isInitialized } = useSDK();
-  
-  if (!isInitialized || !sdk) {
-    return <div>SDK not initialized</div>;
-  }
-  
-  const handleAction = () => {
-    // Use sdk methods here
-    console.log('SDK is ready:', sdk);
-  };
-  
-  return <button onClick={handleAction}>Perform Action</button>;
+function MyComponent() {
+  const { sdk, isInitialized } = useMobileSDK()
+
+  if (!isInitialized || !sdk) return <Text>Loading...</Text>
+
+  return <Button title="Ready" onPress={() => console.log(sdk)} />
 }
 ```
 
-## API Reference
+When using extra modules (like DIDComm), pass the module type:
 
-### SDKProvider
+```tsx
+import { DidCommSDK } from '@credebl/ssi-mobile-didcomm'
+
+type AppModules = { didcomm: DidCommSDK }
+
+const { sdk } = useMobileSDK<AppModules>()
+// sdk.modules.didcomm is now typed correctly
+```
+
+| Return value | Type | Description |
+|---|---|---|
+| `sdk` | `MobileSDK<T>` | The initialized SDK instance |
+| `isInitialized` | `boolean` | `true` once the SDK is ready |
+| `initialize` | `(sdk) => void` | Manually set the SDK (advanced use) |
+| `shutdown` | `() => void` | Shut down the SDK |
 
-The main context provider that wraps your app and provides the SDK context.
+---
 
-**Props:**
-- `children`: React nodes to be wrapped by the provider
+#### `MobileSDK.AppProvider`
 
-### useSDK
+Provides the underlying `Agent` to credential and record hooks. Wrap the parts of your app that use credential hooks with this.
 
-Hook to access the SDK context. Must be used within an SDKProvider.
+```tsx
+import { MobileSDK } from '@credebl/ssi-mobile-core'
 
-**Returns:**
-- `sdk`: The MobileSDK instance or null if not initialized
-- `setSDK`: Function to set the SDK instance
-- `isInitialized`: Boolean indicating if the SDK is initialized
+function App() {
+  return (
+    <MobileSDKProvider>
+      <MobileSDK.AppProvider>
+        {/* hooks like useW3cCredentialRecords() work here */}
+      </MobileSDK.AppProvider>
+    </MobileSDKProvider>
+  )
+}
+```
 
-### useSDKInitializer
+---
 
-Hook to handle SDK initialization logic.
+### DID Operations
 
-**Returns:**
-- `initializeSDK`: Function to initialize the SDK
-- `isInitialized`: Boolean indicating if the SDK is initialized
+All methods below are called on the `sdk` instance returned by `useMobileSDK()`.
 
-## Example Implementation
+#### `sdk.createDid(options)`
 
-Here's a complete example of how to set up and use the SDK context:
+Create a new DID and store it in the wallet.
 
 ```tsx
-import React, { useEffect } from 'react';
-import { SDKProvider, useSDK, useSDKInitializer } from '@credebl/mobile-sdk-core';
+// Create a did:key
+const didRecord = await sdk.createDid({ method: 'key' })
+
+// Create a did:jwk with a specific key type
+const didRecord = await sdk.createDid({
+  method: 'jwk',
+  options: { keyType: 'Ed25519' },
+})
+```
 
-// Component to initialize the SDK
-function SDKInitializer() {
-  const { initializeSDK, isInitialized } = useSDKInitializer();
+---
 
-  useEffect(() => {
-    if (!isInitialized) {
-      initializeSDK();
-    }
-  }, [initializeSDK, isInitialized]);
+#### `sdk.getDids(options?)`
 
-  return null;
-}
+Retrieve DIDs that were created by this wallet.
 
-// Component that uses the SDK
-function SDKUser() {
-  const { sdk, isInitialized } = useSDK();
+```tsx
+// Get all DIDs
+const dids = await sdk.getDids({})
 
-  if (!isInitialized || !sdk) {
-    return <div>Loading SDK...</div>;
-  }
+// Filter by method
+const keyDids = await sdk.getDids({ method: 'key' })
 
-  return (
-    <div>
-      <h2>SDK Ready!</h2>
-      <p>SDK instance: {sdk.constructor.name}</p>
-    </div>
-  );
-}
+// Look up a specific DID
+const dids = await sdk.getDids({ did: 'did:key:z6Mk...' })
+```
 
-// Main app component
-function App() {
-  return (
-    <SDKProvider>
-      <SDKInitializer />
-      <SDKUser />
-    </SDKProvider>
-  );
-}
+---
+
+#### `sdk.resolveDid({ did })`
+
+Resolve a DID document — works for any DID, not just ones in the wallet.
 
-export default App;
+```tsx
+const result = await sdk.resolveDid({ did: 'did:key:z6Mk...' })
+console.log(result.didDocument)
 ```
 
-## Error Handling
+---
+
+#### `sdk.addTagToDid({ did, tag, tagValue })`
 
-The `useSDK` hook will throw an error if used outside of an SDKProvider:
+Attach a custom tag to a DID record so you can look it up later.
 
 ```tsx
-function ComponentOutsideProvider() {
-  try {
-    const { sdk } = useSDK(); // This will throw an error
-  } catch (error) {
-    console.error('SDK context not available:', error.message);
-  }
-}
+await sdk.addTagToDid({
+  did: 'did:key:z6Mk...',
+  tag: 'purpose',
+  tagValue: 'authentication',
+})
+
+// Later, find it by tag
+const dids = await sdk.getDids({ tag: 'purpose', tagValue: 'authentication' })
+```
+
+---
+
+### Credential Storage
+
+#### `sdk.deleteCredential({ id, format })`
+
+Delete a stored credential by ID and format.
+
+```tsx
+import { CredentialRecord } from '@credebl/ssi-mobile-core'
+
+await sdk.deleteCredential({
+  id: 'credential-id',
+  format: CredentialRecord.SdJwt, // or CredentialRecord.Mdoc / CredentialRecord.W3c
+})
+```
+
+---
+
+#### `sdk.storeOpenIdCredential(credential)`
+
+Manually store a credential record received via OpenID4VC.
+
+```tsx
+// credential is a W3cCredentialRecord, SdJwtVcRecord, or MdocRecord
+await sdk.storeOpenIdCredential(credentialRecord)
+```
+
+---
+
+#### `sdk.setTagsToCredential({ credId, tags, format? })`
+
+Attach custom tags to a credential for later filtering.
+
+```tsx
+await sdk.setTagsToCredential({
+  credId: 'credential-id',
+  tags: { status: 'active', issuer: 'university' },
+})
+```
+
+---
+
+#### `sdk.getCredentialsByTag({ tags, format? })`
+
+Query credentials by their custom tags.
+
+```tsx
+const creds = await sdk.getCredentialsByTag({
+  tags: { status: 'active' },
+})
+
+// Filter by format
+const sdJwtCreds = await sdk.getCredentialsByTag({
+  tags: { issuer: 'university' },
+  format: CredentialRecord.SdJwt,
+})
+```
+
+---
+
+### Generic Records
+
+Use generic records to store arbitrary structured data in the wallet (e.g. app settings, user preferences, custom metadata).
+
+#### `sdk.addGenericRecord({ content, tags?, id? })`
+
+```tsx
+const record = await sdk.addGenericRecord({
+  content: { theme: 'dark', notifications: true },
+  tags: { type: 'settings' },
+})
+console.log(record.id)
+```
+
+---
+
+#### `sdk.getGenericRecord(id)`
+
+```tsx
+const record = await sdk.getGenericRecord(record.id)
+```
+
+---
+
+#### `sdk.findGenericRecordsByQuery(query)`
+
+```tsx
+const records = await sdk.findGenericRecordsByQuery({ type: 'settings' })
 ```
 
-## Best Practices
+---
+
+#### `sdk.updateGenericRecord(record)`
+
+```tsx
+record.content.theme = 'light'
+await sdk.updateGenericRecord(record)
+```
 
-1. **Initialize Early**: Initialize the SDK as early as possible in your app lifecycle
-2. **Error Boundaries**: Wrap your app with error boundaries to handle SDK initialization errors
-3. **Loading States**: Always check `isInitialized` before using the SDK
-4. **Type Safety**: Use TypeScript for better development experience and error catching
+---
 
-## Troubleshooting
+#### `sdk.deleteGenericRecord(id)`
 
-### Common Issues
+```tsx
+await sdk.deleteGenericRecord(record.id)
+```
 
-1. **"useSDK must be used within an SDKProvider"**
-   - Ensure your component is wrapped with SDKProvider
-   - Check that the provider is imported correctly
+---
 
-2. **SDK not initializing**
-   - Verify that `initializeSDK()` is being called
-   - Check browser console for any errors
-   - Ensure all required dependencies are installed
+### Wallet Management
 
-3. **Type errors**
-   - Make sure you're using TypeScript
-   - Check that all imports are correct
-   - Verify that the MobileSDK class is properly exported
+#### `sdk.exportWallet(exportToStore)`
 
-## Contributing
+Export the wallet to a different storage location (useful for backup).
 
-This package is part of the CredeBL Mobile SDK ecosystem. For contributions, please refer to the main project documentation.
+```tsx
+await sdk.exportWallet({
+  id: 'backup-wallet-id',
+  key: 'backup-wallet-key',
+  path: '/path/to/backup/file',
+})
+```
+
+---
+
+### Key Management
+
+#### `sdk.createKey(options)`
+
+Create a cryptographic key pair stored in the wallet.
+
+```tsx
+const keyPair = await sdk.createKey({ keyType: 'Ed25519' })
+console.log(keyPair.keyId)
+```
+
+---
+
+#### `sdk.signData(options)`
+
+Sign data with a key from the wallet.
+
+```tsx
+const signature = await sdk.signData({
+  keyId: keyPair.keyId,
+  data: new Uint8Array([1, 2, 3]),
+})
+```
+
+---
+
+#### `sdk.verifyData(options)`
+
+Verify that a signature was produced by a given key.
+
+```tsx
+const isValid = await sdk.verifyData({
+  keyId: keyPair.keyId,
+  data: new Uint8Array([1, 2, 3]),
+  signature,
+})
+```
+
+---
+
+#### `sdk.createJwsCompact({ header, payload, keyId })`
+
+Create a compact JWS (JSON Web Signature) token.
+
+```tsx
+const jws = await sdk.createJwsCompact({
+  header: { alg: 'EdDSA' },
+  payload: { sub: 'user-123', iat: Math.floor(Date.now() / 1000) },
+  keyId: keyPair.keyId,
+})
+```
+
+---
+
+### React Hooks — Credential Records
+
+These hooks give real-time reactive access to credentials stored in the wallet. They update automatically when credentials are added, updated, or deleted.
+
+> Must be used inside `MobileSDK.AppProvider`.
+
+#### `useW3cCredentialRecords()`
+
+Subscribe to all W3C credential records.
+
+```tsx
+import { useW3cCredentialRecords } from '@credebl/ssi-mobile-core'
+
+const { w3cCredentialRecords, isLoading } = useW3cCredentialRecords()
+```
+
+#### `useW3cCredentialRecordById(id)`
+
+```tsx
+const record = useW3cCredentialRecordById('record-id')
+```
+
+---
+
+#### `useSdJwtVcRecords()`
+
+Subscribe to all SD-JWT credential records.
+
+```tsx
+import { useSdJwtVcRecords } from '@credebl/ssi-mobile-core'
+
+const { sdJwtVcRecords, isLoading } = useSdJwtVcRecords()
+```
+
+#### `useSdJwtVcRecordById(id)`
+
+```tsx
+const record = useSdJwtVcRecordById('record-id')
+```
+
+---
+
+#### `useMdocRecords()`
+
+Subscribe to all mDoc credential records.
+
+```tsx
+import { useMdocRecords } from '@credebl/ssi-mobile-core'
+
+const { mdocRecords, isLoading } = useMdocRecords()
+```
+
+#### `useMdocRecordById(id)`
+
+```tsx
+const record = useMdocRecordById('record-id')
+```
+
+---
+
+#### `useGenericRecords(options?)`
+
+Subscribe to generic records, with optional tag filtering.
+
+```tsx
+import { useGenericRecords } from '@credebl/ssi-mobile-core'
+
+const { genericRecords, isLoading } = useGenericRecords({
+  filterByTagKey: 'type',
+  filterByTags: { type: 'settings' },
+})
+```
+
+#### `useGenericRecordById(id)`
+
+```tsx
+const record = useGenericRecordById('record-id')
+```
+
+---
+
+### Wallet Utilities
+
+These are standalone functions — no hook or SDK instance needed.
+
+#### `isWalletPinCorrect(storeConfig)`
+
+Check if a wallet key is correct before opening. Useful for PIN verification screens.
+
+```tsx
+import { isWalletPinCorrect } from '@credebl/ssi-mobile-core'
+
+const isCorrect = await isWalletPinCorrect({
+  id: 'wallet-id',
+  key: 'entered-pin',
+})
+```
+
+---
+
+#### `isWalletImportable(storeConfig, importFromStore)`
+
+Check whether a wallet backup file can be imported before attempting the import.
+
+```tsx
+import { isWalletImportable } from '@credebl/ssi-mobile-core'
+
+const canImport = await isWalletImportable(
+  { id: 'new-wallet', key: 'new-wallet-key' },
+  { id: 'backup-wallet', key: 'backup-key', path: '/path/to/backup' }
+)
+```
+
+---
+
+#### `importWalletToStore(storeConfig, importFromStore)`
+
+Import a wallet from a backup file.
+
+```tsx
+import { importWalletToStore } from '@credebl/ssi-mobile-core'
+
+await importWalletToStore(
+  { id: 'new-wallet', key: 'new-wallet-key' },
+  { id: 'backup-wallet', key: 'backup-key', path: '/path/to/backup' }
+)
+```

package/package.json

@@ -4,7 +4,7 @@
     ".": "./build/index.mjs",
     "./package.json": "./package.json"
   },
-  "version": "2.0.3-alpha-20260410105148",
+  "version": "2.1.0",
   "files": [
     "build"
   ],