@zerohash-sdk/fund-js 1.12.5 → 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 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
- | `onError` | `({ errorCode, reason }) => void` | No | - | Callback for error events |
129
- | `onClose` | `() => void` | No | - | Callback when the widget is closed |
130
- | `onEvent` | `({ type, data }) => void` | No | - | Callback for general events |
131
- | `onLoaded` | `() => void` | No | - | Callback when the widget is loaded and ready |
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
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zerohash-sdk/fund-js",
3
- "version": "1.12.5",
3
+ "version": "1.14.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",