From 550a75a3237d58d4d37f7a8d5fcdb8afce293903 Mon Sep 17 00:00:00 2001 From: "Valentin D. Pinkman" Date: Thu, 23 Jan 2025 17:42:38 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20(transports):=20Add=20missing=20?= =?UTF-8?q?readme.md=20to=20transport=20packages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 12 +++- danger/helpers.ts | 22 +++---- packages/device-management-kit/README.md | 58 +++++++++--------- packages/transport/web-ble/README.md | 77 ++++++++++++++++++++++++ packages/transport/web-hid/README.md | 77 ++++++++++++++++++++++++ 5 files changed, 201 insertions(+), 45 deletions(-) create mode 100644 packages/transport/web-ble/README.md create mode 100644 packages/transport/web-hid/README.md diff --git a/README.md b/README.md index 30bdad3d2..3c29854a2 100644 --- a/README.md +++ b/README.md @@ -189,12 +189,12 @@ Device Management Kit main module. pnpm dmk build ``` -### Signer +### Signers Transaction and message signer module. ```bash -pnpm signer build +pnpm signer-eth build ``` ### Trusted Apps @@ -221,6 +221,12 @@ Sample application module. pnpm sample build ``` +#### Documentation + +```bash +pnpm doc build +``` + # Processes & usage ## Continuous integration @@ -295,7 +301,7 @@ It includes background information about the project and how to setup, run and b ## Reference API -Please refer to the core package [**readme**](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/core/README.md). +Please refer to the core package [**readme**](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/README.md). # Contributing diff --git a/danger/helpers.ts b/danger/helpers.ts index c6e8ee868..430ab51b2 100644 --- a/danger/helpers.ts +++ b/danger/helpers.ts @@ -11,7 +11,7 @@ import { execSync } from "child_process"; type FailFn = (message: MarkdownString, file?: string, line?: number) => void; type MessageFn = ( message: MarkdownString, - opts?: { file?: string; line?: number; icon?: MarkdownString }, + opts?: { file?: string; line?: number; icon?: MarkdownString } ) => void; export const BRANCH_PREFIX = [ @@ -44,13 +44,13 @@ export const isFork = (pr: GitHubPRDSL) => pr?.head?.repo?.fork ?? false; const Branch = ( danger: DangerDSLType, fail: FailFn, - isFork: boolean = false, + isFork: boolean = false ) => ({ regex: isFork ? new RegExp(`^(${BRANCH_PREFIX.join("|")})\/.+`, "i") : new RegExp( `^(${BRANCH_PREFIX.join("|")})\/((dsdk)-[0-9]+|no-issue|issue-[0-9]+)\-.+`, - "i", + "i" ), getBranch: () => { @@ -99,7 +99,7 @@ Please fix the PR branch name to match the convention, see [CONTRIBUTING.md](htt export const checkBranches = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Branch(danger, fail, fork); const currentBranch = config.getBranch(); @@ -115,7 +115,7 @@ export const checkBranches = ( const Commits = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => ({ regex: /^.+\(([a-z]+\-?){1,}\): [A-Z].*/, @@ -146,7 +146,7 @@ Example: \`💚 (scope): My feature\`\ const currentBranch = Branch(danger, fail, fork).getBranch(); return execSync( - `git log origin/develop..${currentBranch} --pretty=format:%s`, + `git log origin/develop..${currentBranch} --pretty=format:%s` ) .toString() .split("\n"); @@ -156,14 +156,14 @@ Example: \`💚 (scope): My feature\`\ export const checkCommits = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Commits(danger, fail, fork); const branchCommits = config.getCommits(); console.log("Branch commits:", branchCommits); const wrongCommits = branchCommits.filter( - (commit) => !config.regex.test(commit), + (commit) => !config.regex.test(commit) ); if (wrongCommits.length > 0) { @@ -225,7 +225,7 @@ Please fix the PR title to match the convention, see [CONTRIBUTING.md](https://g export const checkTitle = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Title(danger, fail, fork); if (!config.regex.test(danger.github.pr.title)) { @@ -240,10 +240,10 @@ export const checkChangesets = (danger: DangerDSLType, message: MessageFn) => { const changesetFiles = danger.git.fileMatch("**/.changeset/*.md"); if (changesetFiles.edited === false) { message( - `\ No changeset file found in the PR. Please add a changeset file.`, + `\ No changeset file found. Please make sure this is intended or add a changeset file.`, { icon: "⚠ī¸", - }, + } ); return false; } diff --git a/packages/device-management-kit/README.md b/packages/device-management-kit/README.md index e0cad35d9..8b791355a 100644 --- a/packages/device-management-kit/README.md +++ b/packages/device-management-kit/README.md @@ -8,7 +8,6 @@ - [Installation](#installation) - [Usage](#usage) - [Compatibility](#compatibility) - - [Pre-requisites](#pre-requisites) - [Main Features](#main-features) - [Setting up the SDK](#setting-up-the-sdk) - [Connecting to a Device](#connecting-to-a-device) @@ -37,13 +36,9 @@ npm install @ledgerhq/device-management-kit ## Usage -### Compatibility - -This library works in [any browser supporting the WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility). - ### Pre-requisites -Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure you are familiar with the basics of the Observer pattern and RxJS before using this SDK. You can refer to [RxJS documentation](https://rxjs.dev/guide/overview) for more information. +Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure you are familiar with the basics of the Observer pattern and RxJS before using this dmk. You can refer to [RxJS documentation](https://rxjs.dev/guide/overview) for more information. ### Main Features @@ -60,27 +55,28 @@ Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure y > [!NOTE] > At the moment we do not provide the possibility to distinguish two devices of the same model, via USB and to avoid connection to the same device twice. -### Setting up the SDK +### Setting up the DMK -The core package exposes an SDK builder `DeviceSdkBuilder` which will be used to initialise the SDK with your configuration. +The core package exposes a DMK builder `DeviceManagementKitBuilder` which will be used to initialise the DMK with your configuration. For now it allows you to add one or more custom loggers. -In the following example, we add a console logger (`.addLogger(new ConsoleLogger())`). Then we build the SDK with `.build()`. +In the following example, we add a console logger (`.addLogger(new ConsoleLogger())`) and a WebHID transport. Then we build the DMK with `.build()`. -**The returned object will be the entrypoint for all your interactions with the SDK.** +**The returned object will be the entrypoint for all your interactions with the DMK.** -The SDK should be built only once in your application runtime so keep a reference of this object somewhere. +The DMK should be built only once in your application runtime so keep a reference of this object somewhere. ```ts import { ConsoleLogger, - DeviceSdk, - DeviceSdkBuilder, + DeviceManagementKitBuilder, } from "@ledgerhq/device-management-kit"; +import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid"; -export const sdk = new DeviceSdkBuilder() +export const sdk = new DeviceManagementKitBuilder() .addLogger(new ConsoleLogger()) + .addTransport(webHidTransportFactory) .build(); ``` @@ -88,20 +84,20 @@ export const sdk = new DeviceSdkBuilder() There are two steps to connecting to a device: -- **Discovery**: `sdk.startDiscovering()` +- **Discovery**: `dmk.startDiscovering()` - Returns an observable which will emit a new `DiscoveredDevice` for every scanned device. - The `DiscoveredDevice` objects contain information about the device model. - Use one of these values to connect to a given discovered device. -- **Connection**: `sdk.connect({ deviceId: device.id })` +- **Connection**: `dmk.connect({ deviceId: device.id })` - Returns a Promise resolving in a device session identifier `DeviceSessionId`. - **Keep this device session identifier to further interact with the device.** - - Then, `sdk.getConnectedDevice({ sessionId })` returns the `ConnectedDevice`, which contains information about the device model and its name. + - Then, `dmk.getConnectedDevice({ sessionId })` returns the `ConnectedDevice`, which contains information about the device model and its name. ```ts -sdk.startDiscovering().subscribe({ +dmk.startDiscovering().subscribe({ next: (device) => { - sdk.connect({ deviceId: device.id }).then((sessionId) => { - const connectedDevice = sdk.getConnectedDevice({ sessionId }); + dmk.connect({ deviceId: device.id }).then((sessionId) => { + const connectedDevice = dmk.getConnectedDevice({ sessionId }); }); }, error: (error) => { @@ -112,8 +108,8 @@ sdk.startDiscovering().subscribe({ Then once a device is connected: -- **Disconnection**: `sdk.disconnect({ sessionId })` -- **Observe the device session state**: `sdk.getDeviceSessionState({ sessionId })` +- **Disconnection**: `dmk.disconnect({ sessionId })` +- **Observe the device session state**: `dmk.getDeviceSessionState({ sessionId })` - This will return an `Observable` to listen to the known information about the device: - device status: - ready to process a command @@ -154,7 +150,7 @@ const apdu = new ApduBuilder(openAppApduArgs) // ### 2. Sending the APDU -const apduResponse = await sdk.sendApdu({ sessionId, apdu }); +const apduResponse = await dmk.sendApdu({ sessionId, apdu }); // ### 3. Parsing the result @@ -178,7 +174,7 @@ The `sendCommand` method will take care of building the APDU, sending it to the > ### ❗ī¸ Error Responses > > Most of the commands will reject with an error if the device is locked. -> Ensure that the device is unlocked before sending commands. You can check the device session state (`sdk.getDeviceSessionState`) to know if the device is locked. +> Ensure that the device is unlocked before sending commands. You can check the device session state (`dmk.getDeviceSessionState`) to know if the device is locked. > > Most of the commands will reject with an error if the response status word is not `0x9000` (success response from the device). @@ -191,7 +187,7 @@ import { OpenAppCommand } from "@ledgerhq/device-management-kit"; const command = new OpenAppCommand("Bitcoin"); // Open the Bitcoin app -await sdk.sendCommand({ sessionId, command }); +await dmk.sendCommand({ sessionId, command }); ``` #### Close App @@ -203,14 +199,14 @@ import { CloseAppCommand } from "@ledgerhq/device-management-kit"; const command = new CloseAppCommand(); -await sdk.sendCommand({ sessionId, command }); +await dmk.sendCommand({ sessionId, command }); ``` #### Get OS Version This command will return information about the currently installed OS on the device. -> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `sdk.getDeviceSessionState({ sessionId })`. +> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `dmk.getDeviceSessionState({ sessionId })`. ```ts import { GetOsVersionCommand } from "@ledgerhq/device-management-kit"; @@ -218,21 +214,21 @@ import { GetOsVersionCommand } from "@ledgerhq/device-management-kit"; const command = new GetOsVersionCommand(); const { seVersion, mcuSephVersion, mcuBootloaderVersion } = - await sdk.sendCommand({ sessionId, command }); + await dmk.sendCommand({ sessionId, command }); ``` #### Get App and Version This command will return the name and version of the currently running app on the device. -> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `sdk.getDeviceSessionState({ sessionId })`. +> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `dmk.getDeviceSessionState({ sessionId })`. ```ts import { GetAppAndVersionCommand } from "@ledgerhq/device-management-kit"; const command = new GetAppAndVersionCommand(); -const { name, version } = await sdk.sendCommand({ sessionId, command }); +const { name, version } = await dmk.sendCommand({ sessionId, command }); ``` ### Building a Custom Command @@ -264,7 +260,7 @@ import { const openAppDeviceAction = new OpenAppDeviceAction({ appName: "Bitcoin" }); -const { observable, cancel } = await sdk.executeDeviceAction({ +const { observable, cancel } = await dmk.executeDeviceAction({ deviceAction: openAppDeviceAction, command, }); diff --git a/packages/transport/web-ble/README.md b/packages/transport/web-ble/README.md new file mode 100644 index 000000000..a702c49b3 --- /dev/null +++ b/packages/transport/web-ble/README.md @@ -0,0 +1,77 @@ +# Transport Device Kit Web BLE + +> [!CAUTION] +> This is still under development and we are free to make new interfaces which may lead to breaking changes. + +- [Transport Device Kit Web HID Documentation](#transport-device-kit-web-ble) + - [Description](#description) + - [Installation](#installation) + - [Usage](#usage) + - [Compatibility](#compatibility) + - [Pre-requisites](#pre-requisites) + - [Main Features](#main-features) + - [How To](#how-to) + +## Description + +This transport is used to interact with a Ledger device through the Web BLE (Bluetooth) implementation. + +## Installation + +To install the core package, run the following command: + +```sh +npm install @ledgerhq/device-transport-kit-web-ble +``` + +## Usage + +### Compatibility + +This library works in [any browser supporting the Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API#browser_compatibility). + +### Pre-requisites + +To use this transport, you need to have the DMK installed on your project as well. + +### Main Features + +- Exposing a transport factory to be injected into the DeviceManagementKit +- Exposing the transport directly for a custom configuration + +### How To + +To use the transport, you need to inject it in the DeviceManagementKitBuilder before the build. This will allow the DMK to find and interact with devices on the Web BLE protocol. + +```typescript +import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit" +import { webBleTransportFactory, WebBleTransport } from "@ledgerhq/device-transport-kit-web-ble" + +// Easy setup with the factory +const dmk = new DeviceManagementKitBuilder() + .addTransport(webBleTransportFactory) + .build(); + + +// With custom config +const dmk = new DeviceManagementKitBuilder() + .addTransport(({ + deviceModelDataSource: DeviceModelDataSource; + loggerServiceFactory: (tag: string) => LoggerPublisherService; + config: DmkConfig; + apduSenderServiceFactory: ApduSenderServiceFactory; + apduReceiverServiceFactory: ApduReceiverServiceFactory; + }) => { + // custom code + return new WebBleTransport( + deviceModelDataSource, + loggerServiceFactory, + config, + apduSenderServiceFactory, + apduReceiverServiceFactory, + ); + }) + .build(); + + // Youn can then make use of the DMK +``` diff --git a/packages/transport/web-hid/README.md b/packages/transport/web-hid/README.md new file mode 100644 index 000000000..462384cde --- /dev/null +++ b/packages/transport/web-hid/README.md @@ -0,0 +1,77 @@ +# Transport Device Kit Web HID + +> [!CAUTION] +> This is still under development and we are free to make new interfaces which may lead to breaking changes. + +- [Transport Device Kit Web HID Documentation](#transport-device-kit-web-hid) + - [Description](#description) + - [Installation](#installation) + - [Usage](#usage) + - [Compatibility](#compatibility) + - [Pre-requisites](#pre-requisites) + - [Main Features](#main-features) + - [How To](#how-to) + +## Description + +This transport is used to interact with a Ledger device through the Web HID (usb) implementation. + +## Installation + +To install the core package, run the following command: + +```sh +npm install @ledgerhq/device-transport-kit-web-hid +``` + +## Usage + +### Compatibility + +This library works in [any browser supporting the WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility). + +### Pre-requisites + +To use this transport, you need to have the DMK installed on your project as well. + +### Main Features + +- Exposing a transport factory to be injected into the DeviceManagementKit +- Exposing the transport directly for a custom configuration + +### How To + +To use the transport, you need to inject it in the DeviceManagementKitBuilder before the build. This will allow the DMK to find and interact with devices on the Web HID protocol. + +```typescript +import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit" +import { webHidTransportFactory, WebHidTransport } from "@ledgerhq/device-transport-kit-web-hid" + +// Easy setup with the factory +const dmk = new DeviceManagementKitBuilder() + .addTransport(webHidTransportFactory) + .build(); + + +// With custom config +const dmk = new DeviceManagementKitBuilder() + .addTransport(({ + deviceModelDataSource: DeviceModelDataSource; + loggerServiceFactory: (tag: string) => LoggerPublisherService; + config: DmkConfig; + apduSenderServiceFactory: ApduSenderServiceFactory; + apduReceiverServiceFactory: ApduReceiverServiceFactory; + }) => { + // custom code + return new WebHidTransport( + deviceModelDataSource, + loggerServiceFactory, + config, + apduSenderServiceFactory, + apduReceiverServiceFactory, + ); + }) + .build(); + + // Youn can then make use of the DMK +```