1 | <img src="https://user-images.githubusercontent.com/211411/34776833-6f1ef4da-f618-11e7-8b13-f0697901d6a8.png" height="100" />
|
2 |
|
3 | [Github](https://github.com/LedgerHQ/ledgerjs/),
|
4 | [Ledger Devs Slack](https://ledger-dev.slack.com/)
|
5 |
|
6 | ## @ledgerhq/hw-transport
|
7 |
|
8 | `@ledgerhq/hw-transport` implements the generic interface of a Ledger Hardware Wallet transport.
|
9 |
|
10 | ## API
|
11 |
|
12 |
|
13 |
|
14 | #### Table of Contents
|
15 |
|
16 | * [Subscription](#subscription)
|
17 | * [Properties](#properties)
|
18 | * [Device](#device)
|
19 | * [DescriptorEvent](#descriptorevent)
|
20 | * [Observer](#observer)
|
21 | * [Transport](#transport)
|
22 | * [exchange](#exchange)
|
23 | * [Parameters](#parameters)
|
24 | * [setScrambleKey](#setscramblekey)
|
25 | * [Parameters](#parameters-1)
|
26 | * [close](#close)
|
27 | * [on](#on)
|
28 | * [Parameters](#parameters-2)
|
29 | * [off](#off)
|
30 | * [Parameters](#parameters-3)
|
31 | * [setDebugMode](#setdebugmode)
|
32 | * [setExchangeTimeout](#setexchangetimeout)
|
33 | * [Parameters](#parameters-4)
|
34 | * [setExchangeUnresponsiveTimeout](#setexchangeunresponsivetimeout)
|
35 | * [Parameters](#parameters-5)
|
36 | * [send](#send)
|
37 | * [Parameters](#parameters-6)
|
38 | * [isSupported](#issupported)
|
39 | * [list](#list)
|
40 | * [Examples](#examples)
|
41 | * [listen](#listen)
|
42 | * [Parameters](#parameters-7)
|
43 | * [Examples](#examples-1)
|
44 | * [open](#open)
|
45 | * [Parameters](#parameters-8)
|
46 | * [Examples](#examples-2)
|
47 | * [create](#create)
|
48 | * [Parameters](#parameters-9)
|
49 | * [Examples](#examples-3)
|
50 |
|
51 | ### Subscription
|
52 |
|
53 | Type: {unsubscribe: function (): void}
|
54 |
|
55 | #### Properties
|
56 |
|
57 | * `unsubscribe` **function (): void**
|
58 |
|
59 | ### Device
|
60 |
|
61 | Type: any
|
62 |
|
63 | ### DescriptorEvent
|
64 |
|
65 | type: add or remove event
|
66 | descriptor: a parameter that can be passed to open(descriptor)
|
67 | deviceModel: device info on the model (is it a nano s, nano x, ...)
|
68 | device: transport specific device info
|
69 |
|
70 | ### Observer
|
71 |
|
72 | Type: Readonly<{next: function (event: Ev): any, error: function (e: any): any, complete: function (): any}>
|
73 |
|
74 | ### Transport
|
75 |
|
76 | Transport defines the generic interface to share between node/u2f impl
|
77 | A **Descriptor** is a parametric type that is up to be determined for the implementation.
|
78 | it can be for instance an ID, an file path, a URL,...
|
79 |
|
80 | #### exchange
|
81 |
|
82 | low level api to communicate with the device
|
83 | This method is for implementations to implement but should not be directly called.
|
84 | Instead, the recommanded way is to use send() method
|
85 |
|
86 | ##### Parameters
|
87 |
|
88 | * `_apdu` **[Buffer](https://nodejs.org/api/buffer.html)**
|
89 | * `apdu` the data to send
|
90 |
|
91 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Buffer](https://nodejs.org/api/buffer.html)>** a Promise of response data
|
92 |
|
93 | #### setScrambleKey
|
94 |
|
95 | set the "scramble key" for the next exchanges with the device.
|
96 | Each App can have a different scramble key and they internally will set it at instanciation.
|
97 |
|
98 | ##### Parameters
|
99 |
|
100 | * `_key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
|
101 | * `key` the scramble key
|
102 |
|
103 | #### close
|
104 |
|
105 | close the exchange with the device.
|
106 |
|
107 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<void>** a Promise that ends when the transport is closed.
|
108 |
|
109 | #### on
|
110 |
|
111 | Listen to an event on an instance of transport.
|
112 | Transport implementation can have specific events. Here is the common events:
|
113 |
|
114 | * `"disconnect"` : triggered if Transport is disconnected
|
115 |
|
116 | ##### Parameters
|
117 |
|
118 | * `eventName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
|
119 | * `cb` **function (...args: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<any>): any**
|
120 |
|
121 | Returns **void**
|
122 |
|
123 | #### off
|
124 |
|
125 | Stop listening to an event on an instance of transport.
|
126 |
|
127 | ##### Parameters
|
128 |
|
129 | * `eventName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
|
130 | * `cb` **function (...args: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<any>): any**
|
131 |
|
132 | Returns **void**
|
133 |
|
134 | #### setDebugMode
|
135 |
|
136 | Enable or not logs of the binary exchange
|
137 |
|
138 | #### setExchangeTimeout
|
139 |
|
140 | Set a timeout (in milliseconds) for the exchange call. Only some transport might implement it. (e.g. U2F)
|
141 |
|
142 | ##### Parameters
|
143 |
|
144 | * `exchangeTimeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
145 |
|
146 | Returns **void**
|
147 |
|
148 | #### setExchangeUnresponsiveTimeout
|
149 |
|
150 | Define the delay before emitting "unresponsive" on an exchange that does not respond
|
151 |
|
152 | ##### Parameters
|
153 |
|
154 | * `unresponsiveTimeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
155 |
|
156 | Returns **void**
|
157 |
|
158 | #### send
|
159 |
|
160 | wrapper on top of exchange to simplify work of the implementation.
|
161 |
|
162 | ##### Parameters
|
163 |
|
164 | * `cla` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
165 | * `ins` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
166 | * `p1` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
167 | * `p2` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
168 | * `data` **[Buffer](https://nodejs.org/api/buffer.html)** (optional, default `Buffer.alloc(0)`)
|
169 | * `statusList` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>** is a list of accepted status code (shorts). \[0x9000] by default (optional, default `[StatusCodes.OK]`)
|
170 |
|
171 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Buffer](https://nodejs.org/api/buffer.html)>** a Promise of response buffer
|
172 |
|
173 | #### isSupported
|
174 |
|
175 | Statically check if a transport is supported on the user's platform/browser.
|
176 |
|
177 | Type: function (): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>
|
178 |
|
179 | #### list
|
180 |
|
181 | List once all available descriptors. For a better granularity, checkout `listen()`.
|
182 |
|
183 | Type: function (): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<any>>
|
184 |
|
185 | ##### Examples
|
186 |
|
187 | ```javascript
|
188 | TransportFoo.list().then(descriptors => ...)
|
189 | ```
|
190 |
|
191 | Returns **any** a promise of descriptors
|
192 |
|
193 | #### listen
|
194 |
|
195 | Listen all device events for a given Transport. The method takes an Obverver of DescriptorEvent and returns a Subscription (according to Observable paradigm <https://github.com/tc39/proposal-observable> )
|
196 | a DescriptorEvent is a `{ descriptor, type }` object. type can be `"add"` or `"remove"` and descriptor is a value you can pass to `open(descriptor)`.
|
197 | each listen() call will first emit all potential device already connected and then will emit events can come over times,
|
198 | for instance if you plug a USB device after listen() or a bluetooth device become discoverable.
|
199 |
|
200 | Type: function (observer: [Observer](#observer)<[DescriptorEvent](#descriptorevent)\<any>>): [Subscription](#subscription)
|
201 |
|
202 | ##### Parameters
|
203 |
|
204 | * `observer` is an object with a next, error and complete function (compatible with observer pattern)
|
205 |
|
206 | ##### Examples
|
207 |
|
208 | ```javascript
|
209 | const sub = TransportFoo.listen({
|
210 | next: e => {
|
211 | if (e.type==="add") {
|
212 | sub.unsubscribe();
|
213 | const transport = await TransportFoo.open(e.descriptor);
|
214 | ...
|
215 | }
|
216 | },
|
217 | error: error => {},
|
218 | complete: () => {}
|
219 | })
|
220 | ```
|
221 |
|
222 | Returns **any** a Subscription object on which you can `.unsubscribe()` to stop listening descriptors.
|
223 |
|
224 | #### open
|
225 |
|
226 | attempt to create a Transport instance with potentially a descriptor.
|
227 |
|
228 | Type: function (descriptor: any, timeout: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Transport](#transport)>
|
229 |
|
230 | ##### Parameters
|
231 |
|
232 | * `descriptor` : the descriptor to open the transport with.
|
233 | * `timeout` : an optional timeout
|
234 |
|
235 | ##### Examples
|
236 |
|
237 | ```javascript
|
238 | TransportFoo.open(descriptor).then(transport => ...)
|
239 | ```
|
240 |
|
241 | Returns **any** a Promise of Transport instance
|
242 |
|
243 | #### create
|
244 |
|
245 | create() allows to open the first descriptor available or
|
246 | throw if there is none or if timeout is reached.
|
247 | This is a light helper, alternative to using listen() and open() (that you may need for any more advanced usecase)
|
248 |
|
249 | ##### Parameters
|
250 |
|
251 | * `openTimeout` (optional, default `3000`)
|
252 | * `listenTimeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?**
|
253 |
|
254 | ##### Examples
|
255 |
|
256 | ```javascript
|
257 | TransportFoo.create().then(transport => ...)
|
258 | ```
|
259 |
|
260 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Transport](#transport)>**
|