diff --git a/README.md b/README.md index b9d1f65..ef53f97 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,9 @@ --- +> Refer to [docs](./docs) for some more in-depth documentation in the newer, and easier to use, API. +> The [example](./example) application shows how this can be used. + ## Introduction This package can be used as a transport for [DIDComm](https://didcomm.org) messages over Bluetooth Low Energy (BLE). diff --git a/docs/request.md b/docs/request.md new file mode 100644 index 0000000..4232972 --- /dev/null +++ b/docs/request.md @@ -0,0 +1,104 @@ +# BLE Request Proof Function Documentation + +## Overview + +The `bleRequestProof` function is designed to facilitate a proof request over Bluetooth Low Energy (BLE). + +## Function Signature + +```typescript +export const bleRequestProof = async (options: BleRequestProofOptions) => Promise +``` + +## Parameters + +The function takes a single object parameter of type `BleRequestProofOptions` with the following properties: + +- `agent: Agent` - An instance of the Agent class from the Credo framework. +- `peripheral: Peripheral` - A Peripheral object representing the BLE device. + - This can be retrieved with the `usePeripheral` hook as shown in the example. +- `serviceUuid: string` - The UUID of the BLE service to use. + - This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code. +- `presentationTemplate: PresentationTemplate` - An object containing the proof request details. +- `onFailure: () => Promise | void` - A callback function to be called if the proof request fails. +- `onConnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is established. +- `onDisconnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is disconnected. + +## Return Value + +Proof record id + +## Usage Example + +```typescript +import { Agent } from '@credo-ts/core'; +import { bleRequestProof, PresentationTemplate, usePeripheral } from '@animo-id/react-native-ble-didcomm'; +import { YourPeripheralImplementation } from './your-peripheral-implementation'; + +const agent = new Agent(/* agent configuration */); +const peripheral = usePeripheral(); + +const presentationTemplate: PresentationTemplate = { + id: 'template-id', + name: 'Proof Request Template', + requestMessage: { + anoncreds: { + name: 'anon-request', + version: '2.0', + requested_attributes: { nameGroup: { name: 'name' } }, + requested_predicates: { + ageGroup: { name: 'age', p_value: 20, p_type: '>' }, + }, + }, + }, +}; + +const serviceUuid = 'your-service-uuid'; + +try { + const proofRecordId = await bleRequestProof({ + agent, + peripheral, + serviceUuid, + presentationTemplate, + onFailure: () => console.error('Proof request failed'), + onConnected: () => console.log('BLE connected'), + onDisconnected: () => console.log('BLE disconnected') + }); + + console.log(`Proof record created with ID: ${proofRecordId}`); +} catch (error) { + console.error('Error in bleRequestProof:', error); +} +``` + +## Function Flow + +1. Starts the BLE transport for the agent. +2. Sets up the indication, message and service UUID as characteristics +3. Sets up a disconnection notifier. +4. Sends the proof request message when connected. +5. Starts a message receiver for incoming messages. +6. Waits for the proof to be received and processes it. +7. Returns the proof record ID upon successful completion. + +## Error Handling + +If an error occurs during the execution of the function, it will: + +1. Log the error using the agent's logger. +2. Call the `onFailure` callback. +3. Throw the error for the caller to handle. + +## Peer Dependencies + +- `@credo-ts/core` +- `@credo-ts/anoncreds` +- `react` +- `react-native` + +## Notes + +- The function uses credo-ts for presentation exchange. +- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations. +- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange. diff --git a/docs/share.md b/docs/share.md new file mode 100644 index 0000000..d544642 --- /dev/null +++ b/docs/share.md @@ -0,0 +1,88 @@ +# BLE Share Proof Function Documentation + +## Overview + +The `bleShareProof` function is designed to facilitate a response to a proof request over Bluetooth Low Energy (BLE). + +## Function Signature + +```typescript +export const bleShareProof = async (options: BleShareProofOptions): Promise +``` + +## Parameters + +The function takes a single object parameter of type `BleShareProofOptions` with the following properties: + +- `agent: Agent` - An instance of the Agent class from the Credo framework. +- `central: Central` - A Central object representing the BLE central device. + - This can be retrieved with the `useCentral` hook as shown in the example. +- `serviceUuid: string` - The UUID of the BLE service to use. + - This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code. +- `onFailure: () => Promise | void` - A callback function to be called if the proof sharing fails. +- `onConnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is established. +- `onDisconnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is disconnected. + +## Return Value + +The function returns a Promise that resolves to `void` when the proof sharing process is complete. + +## Usage Example + +```typescript +import { Agent } from '@credo-ts/core'; +import { bleShareProof, useCentral } from '@animo-id/react-native-ble-didcomm'; + +const agent = new Agent(/* agent configuration */); +const central = useCentral(); + +const serviceUuid = 'your-service-uuid'; + +try { + await bleShareProof({ + agent, + central, + serviceUuid, + onFailure: () => console.error('Proof sharing failed'), + onConnected: () => console.log('BLE connected'), + onDisconnected: () => console.log('BLE disconnected') + }); + + console.log('Proof sharing completed successfully'); +} catch (error) { + console.error('Error in bleShareProof:', error); +} +``` + +## Function Flow + +1. Starts the BLE transport for the agent (both inbound and outbound). +2. Initializes the central device and starts scanning for peripherals. +3. Sets up a disconnection notifier. +4. Discovers and connects to a peripheral device. +5. Notifies when connected. +6. Shares the proof by: + a. Receiving an out-of-band invitation. + b. Automatically responding to the proof request. +7. Handles the acknowledgment of the shared proof. + +## Error Handling + +If an error occurs during the execution of the function, it will: + +1. Log the error using the agent's logger. +2. Call the `onFailure` callback. +3. Throw the error for the caller to handle. + +## Peer Dependencies + +- `@credo-ts/core` +- `@credo-ts/anoncreds` +- `react` +- `react-native` + +## Notes + +- The function uses credo-ts for presentation exchange. +- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations. +- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange. diff --git a/library/src/bleShareProof.ts b/library/src/bleShareProof.ts index 43f3f25..4b76e95 100644 --- a/library/src/bleShareProof.ts +++ b/library/src/bleShareProof.ts @@ -44,6 +44,7 @@ export const bleShareProof = async ({ const proofRecord = await shareProof(agent, central, serviceUuid) await handleAck(agent, central, proofRecord) + return proofRecord.id } catch (e) { if (e instanceof Error) { agent.config.logger.error(e.message, { cause: e })