@zerohash-sdk/fund-js 1.12.4 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -11
- package/dist/index.d.ts +7 -2
- package/dist/index.js +5 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -60,6 +60,12 @@ const fund = new Fund({
|
|
|
60
60
|
onCompleted: ({ assetSymbol, amount, network, depositAddress }) => {
|
|
61
61
|
console.log('Fund completed:', amount, assetSymbol, network, depositAddress);
|
|
62
62
|
},
|
|
63
|
+
onFailed: ({ transactionId, amount, assetSymbol }) => {
|
|
64
|
+
console.log('Deposit failed:', transactionId, amount, assetSymbol);
|
|
65
|
+
},
|
|
66
|
+
onDeposit: ({ data }) => {
|
|
67
|
+
console.log('External-source deposit:', data.depositId, data.status.value);
|
|
68
|
+
},
|
|
63
69
|
onError: ({ errorCode, reason }) => {
|
|
64
70
|
console.error('Fund error:', errorCode, 'Reason:', reason);
|
|
65
71
|
},
|
|
@@ -118,17 +124,19 @@ await fund.render(document.getElementById('fund-container')!);
|
|
|
118
124
|
|
|
119
125
|
### Configuration
|
|
120
126
|
|
|
121
|
-
| Prop | Type | Required | Default | Description
|
|
122
|
-
| ------------- | ------------------------------------------------------------ | -------- | -------- |
|
|
123
|
-
| `jwt` | `string` | Yes | - | JWT token for authentication with Connect
|
|
124
|
-
| `env` | `"prod" \| "cert" \| "dev" \| "local"` | No | `"prod"` | Target environment
|
|
125
|
-
| `theme` | `"auto" \| "light" \| "dark"` | No | `"auto"` | Theme mode for the interface
|
|
126
|
-
| `isPay` | `boolean` | No | `false` | Run the SDK in Pay mode (see notes below)
|
|
127
|
-
| `onCompleted` | `({ assetSymbol, amount, network, depositAddress }) => void` | No | - | Callback when the fund flow completes successfully
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
127
|
+
| Prop | Type | Required | Default | Description |
|
|
128
|
+
| ------------- | ------------------------------------------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
|
|
129
|
+
| `jwt` | `string` | Yes | - | JWT token for authentication with Connect |
|
|
130
|
+
| `env` | `"prod" \| "cert" \| "dev" \| "local"` | No | `"prod"` | Target environment |
|
|
131
|
+
| `theme` | `"auto" \| "light" \| "dark"` | No | `"auto"` | Theme mode for the interface |
|
|
132
|
+
| `isPay` | `boolean` | No | `false` | Run the SDK in Pay mode (see notes below) |
|
|
133
|
+
| `onCompleted` | `({ assetSymbol, amount, network, depositAddress }) => void` | No | - | Callback when the fund flow completes successfully |
|
|
134
|
+
| `onFailed` | `({ assetSymbol, amount, network, depositAddress }) => void` | No | - | Callback when a deposit ends in a failed state |
|
|
135
|
+
| `onDeposit` | `(deposit) => void` | No | - | Deposit-status updates for the external-source ("connect an account") path; may fire more than once per deposit |
|
|
136
|
+
| `onError` | `({ errorCode, reason }) => void` | No | - | Callback for error events |
|
|
137
|
+
| `onClose` | `() => void` | No | - | Callback when the widget is closed |
|
|
138
|
+
| `onEvent` | `({ type, data }) => void` | No | - | Callback for general events |
|
|
139
|
+
| `onLoaded` | `() => void` | No | - | Callback when the widget is loaded and ready |
|
|
132
140
|
|
|
133
141
|
### Pay mode (`isPay`)
|
|
134
142
|
|
|
@@ -208,6 +216,47 @@ onCompleted: ({ assetSymbol, amount, network, depositAddress }) => {
|
|
|
208
216
|
};
|
|
209
217
|
```
|
|
210
218
|
|
|
219
|
+
### onFailed
|
|
220
|
+
|
|
221
|
+
Called when a deposit transaction reaches a terminal **failed** state. This is a
|
|
222
|
+
flow outcome, not an SDK error, so `onError` is not called for it — handle both
|
|
223
|
+
if you need to cover every unsuccessful path.
|
|
224
|
+
|
|
225
|
+
```javascript
|
|
226
|
+
onFailed: ({ assetSymbol, amount, network, depositAddress, transactionId }) => {
|
|
227
|
+
// Same shape as onCompleted — the details of the deposit that failed.
|
|
228
|
+
};
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### onDeposit
|
|
232
|
+
|
|
233
|
+
Called when a deposit funded from an **external source** (the "connect an
|
|
234
|
+
account" path) changes status. That flow reports here rather than through
|
|
235
|
+
`onCompleted`/`onFailed`, which cover the manual-deposit and Pay paths, so handle
|
|
236
|
+
this too if you offer external funding sources.
|
|
237
|
+
|
|
238
|
+
This is a status notification, **not** a single terminal event: it can fire more
|
|
239
|
+
than once for the same deposit, including while account matching is still
|
|
240
|
+
verifying. Which outcome it is lives in the payload — there is no separate
|
|
241
|
+
failure callback:
|
|
242
|
+
|
|
243
|
+
```javascript
|
|
244
|
+
onDeposit: ({ data }) => {
|
|
245
|
+
data.depositId; // deposit this status belongs to
|
|
246
|
+
data.status.value; // 'PROCESSED' = funded, 'FAILED' = not
|
|
247
|
+
data.status.details; // why, when it failed
|
|
248
|
+
data.accountMatchingValidation?.status; // 'PENDING' = still verifying
|
|
249
|
+
data.assetId;
|
|
250
|
+
data.networkId;
|
|
251
|
+
data.amount;
|
|
252
|
+
};
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Treat it as finished only when `status.value` is `PROCESSED` (funded) or the
|
|
256
|
+
deposit has failed — either `status.value === 'FAILED'` or
|
|
257
|
+
`accountMatchingValidation.status` is `INVALID` or `ERROR`. Any other
|
|
258
|
+
combination, `PENDING` account matching in particular, is still in flight.
|
|
259
|
+
|
|
211
260
|
### onError
|
|
212
261
|
|
|
213
262
|
Called when an error occurs in the Fund widget.
|
|
@@ -257,6 +306,23 @@ onLoaded: () => {
|
|
|
257
306
|
- Safari 14+
|
|
258
307
|
- All modern browsers with Web Components support
|
|
259
308
|
|
|
309
|
+
### The two deposit paths report different fields
|
|
310
|
+
|
|
311
|
+
`onCompleted` / `onFailed` and `onDeposit` do not carry the same shape, so read
|
|
312
|
+
whichever the path you support actually delivers:
|
|
313
|
+
|
|
314
|
+
| | `onCompleted` / `onFailed` (manual, Pay) | `onDeposit` (external source) |
|
|
315
|
+
| ---------- | ---------------------------------------- | ----------------------------------------------------- |
|
|
316
|
+
| identifier | `transactionId`, `fundId` | `depositId` |
|
|
317
|
+
| asset | `assetSymbol` (e.g. `BTC.BITCOIN`) | `assetId` (asset key, e.g. `usdc`) |
|
|
318
|
+
| network | `network` | `networkId` |
|
|
319
|
+
| amount | `amount`, `notionalAmount` | `amount` |
|
|
320
|
+
| outcome | which callback fired | `status.value` (+ `accountMatchingValidation.status`) |
|
|
321
|
+
|
|
322
|
+
There is no `transactionId` on an `onDeposit` payload — an external-source deposit is
|
|
323
|
+
identified by `depositId`. If you need one code path for both, key off the identifier
|
|
324
|
+
each provides rather than assuming a shared field name.
|
|
325
|
+
|
|
260
326
|
## More Information & Support
|
|
261
327
|
|
|
262
328
|
For comprehensive documentation or support about Connect, visit our [Documentation Page](https://docs.zerohash.com/).
|
package/dist/index.d.ts
CHANGED
|
@@ -24,7 +24,8 @@ declare type AppEvent<TType extends string = string, TData = Record<string, unkn
|
|
|
24
24
|
*/
|
|
25
25
|
declare interface BaseConfig<TEvent = AppEvent> extends CommonCallbacks<TEvent> {
|
|
26
26
|
/**
|
|
27
|
-
* JWT token used for authentication
|
|
27
|
+
* JWT token used for authentication. Provide/update it via `setJWT`
|
|
28
|
+
* (`updateConfig({ jwt })`).
|
|
28
29
|
*/
|
|
29
30
|
jwt: string;
|
|
30
31
|
|
|
@@ -119,7 +120,11 @@ declare abstract class BaseJsSdk<Config extends BaseConfig<never> = BaseConfig>
|
|
|
119
120
|
}
|
|
120
121
|
|
|
121
122
|
/**
|
|
122
|
-
* Update the configuration of the widget
|
|
123
|
+
* Update the configuration of the widget (e.g. `theme`, or the `jwt`).
|
|
124
|
+
*
|
|
125
|
+
* Passing a `jwt` is the JS-SDK equivalent of `setJWT` — it provides the JWT
|
|
126
|
+
* used to authenticate.
|
|
127
|
+
*
|
|
123
128
|
* @param config - Partial configuration to update
|
|
124
129
|
* @returns void
|
|
125
130
|
*/
|
package/dist/index.js
CHANGED
|
@@ -169,7 +169,11 @@ class j {
|
|
|
169
169
|
}
|
|
170
170
|
}
|
|
171
171
|
/**
|
|
172
|
-
* Update the configuration of the widget
|
|
172
|
+
* Update the configuration of the widget (e.g. `theme`, or the `jwt`).
|
|
173
|
+
*
|
|
174
|
+
* Passing a `jwt` is the JS-SDK equivalent of `setJWT` — it provides the JWT
|
|
175
|
+
* used to authenticate.
|
|
176
|
+
*
|
|
173
177
|
* @param config - Partial configuration to update
|
|
174
178
|
* @returns void
|
|
175
179
|
*/
|