wallaby-cash 3.6.0 → 3.8.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
@@ -13,9 +13,8 @@ The SDK currently supports the following blockchains:
13
13
  - Aptos
14
14
  - Avalanche
15
15
  - Base
16
- - Binance chain
17
16
  - Bitcoin
18
- - Bsc
17
+ - BSC
19
18
  - Canton
20
19
  - Ethereum
21
20
  - Hedera
@@ -32,6 +31,10 @@ The SDK currently supports the following blockchains:
32
31
  npm install wallaby-cash@latest
33
32
  ```
34
33
 
34
+ ## Concepts guide
35
+
36
+ New to the SDK? Read [GUIDE.md](./GUIDE.md) — the mental model, auth modes, key custody, multi-device handoff, errors, and gotchas in one page. Method signatures live in the TypeDoc output; runnable code lives in [`examples/`](./examples/).
37
+
35
38
  ## React Native migration plan (updated for v2.2.7)
36
39
 
37
40
  This plan reflects the current SDK package layout and native passkey support.
@@ -127,21 +130,61 @@ const config = {
127
130
  const wallaby = new Wallaby(config)
128
131
 
129
132
  /**
130
- * This will return all domains supported by wallaby (i.e auth, wallets, merchants, ...)
131
- * Then it can be called like the example below
132
- */
133
+ * Every feature hangs off the client's domain properties:
134
+ * auth, wallet, walletData, transactions, swap, system, utils
135
+ */
133
136
 
134
- wallaby.auth.refreshAccessToken()
135
- wallaby.wallets.getTokenBalance()
136
- wallaby.transactions.transfer()
137
+ wallaby.auth.refreshAuthTokens()
138
+ wallaby.walletData.getTokenBalance(/* … */)
139
+ wallaby.transactions.transfer(/* … */)
137
140
  wallaby.system.getSupportedBlockchains()
138
141
  ```
139
142
 
143
+ ### Establishing a session without a prompt
144
+
145
+ Since **v3.5.0**, `auth.exchangeClientToken()` exchanges the configured client JWT for a Wallaby
146
+ access + refresh token pair (`POST /auth/issue-jwt-token`) with **no password/passkey prompt** —
147
+ use it on wallet open before calling guarded read endpoints. Operations that touch key material
148
+ still require `auth.signUp()` / `auth.signIn()`, which unlock the device signing key.
149
+
150
+ ```javascript
151
+ const { accessToken, refreshToken } = await wallaby.auth.exchangeClientToken();
152
+ // Tokens are stored and rotated automatically by the SDK.
153
+ ```
154
+
155
+ ## Runtime validation
156
+
157
+ The SDK validates request bodies before send and API responses before return against schemas
158
+ generated from the OpenAPI spec, controlled by `options.runtimeValidation`:
159
+
160
+ ```javascript
161
+ const wallaby = new Wallaby({
162
+ ...config,
163
+ options: { runtimeValidation: 'throw' }, // 'throw' | 'warn' | 'off' — default 'throw'
164
+ });
165
+ ```
166
+
167
+ - **`'throw'`** (default): mismatches raise a `WallabyError` with `kind: 'validation'` — responses use
168
+ `errorCode: 'sdk_invalid_response'`, request bodies use `errorCode: 'sdk_invalid_parameter'`
169
+ (the request is not sent).
170
+ - **`'warn'`**: mismatches are logged via the SDK logger and the call proceeds anyway.
171
+ - **`'off'`**: validation is skipped entirely.
172
+
173
+ Validation is structural (missing or wrong-typed fields); unknown extra fields always pass, so
174
+ additive API changes don't break older SDK versions. `WallabyError` also carries a `kind`
175
+ discriminant (`'api' | 'network' | 'validation' | 'sdk'`) and a `toJSON()` for logging.
176
+
177
+ > **Note:** constructing the re-exported `WallabyApiClient`/`WallabyHttpClient` directly bypasses
178
+ > the SDK's chokepoints — those calls are not validated.
179
+
180
+ See [RUNTIME_VALIDATION.md](./RUNTIME_VALIDATION.md) for how it works, what's covered, and what's
181
+ still in progress.
182
+
140
183
  ## Generated API
141
184
 
142
185
  The `wallaby-sdk-js` includes automatically generated TypeScript types from the API Swagger specification:
143
186
 
144
- - **Types are generated automatically** during build process from `https://staging-testnet.wallaby.cash/swagger-json`
187
+ - **Types are generated automatically** during build process from `https://dev-testnet.wallaby.cash/swagger-json`
145
188
  - **Generated files location**: `src/generated/`
146
189
  - **Error codes included**: All API error codes are available as TypeScript enums
147
190
  - **Local development**: Use `npm run generate:types:local` to generate from local `swagger.json`
package/dist/base.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { AuthType, WallabyConfig, RequestOptions, RequestRoute, WallabyConfigOptions } from './types';
1
+ import { AuthType, WallabyConfig, RequestOptions, RequestRoute, WallabyConfigOptions, WallabyError, WallabyErrorPayload } from './types';
2
2
  import { StorageService } from './lib/utils/storage.service';
3
3
  import { LocalStorage } from './types/storage';
4
4
  import { LockManagerService } from './helpers/lock-manager.service';
@@ -30,6 +30,7 @@ export declare abstract class Base {
30
30
  * }
31
31
  */
32
32
  get deviceLocalStorage(): LocalStorage;
33
+ private get validationMode();
33
34
  /**
34
35
  * @private
35
36
  */
@@ -43,16 +44,29 @@ export declare abstract class Base {
43
44
  * All concurrent callers share the same in-flight promise via the module-level
44
45
  * `refreshDedupeManager` so only one network request is issued per user/environment scope.
45
46
  */
46
- protected _performTokenRefresh(): Promise<void>;
47
+ protected _performTokenRefresh(opts?: {
48
+ silent?: boolean;
49
+ }): Promise<void>;
50
+ /**
51
+ * Single chokepoint for surfacing transport failures. Every WallabyError raised
52
+ * by a transport path is built here so `options.onError` fires exactly once per
53
+ * logical failure. Retry paths must decide to retry BEFORE calling this so a
54
+ * retried request does not double-fire.
55
+ */
56
+ protected toWallabyError(payload: WallabyErrorPayload): WallabyError;
47
57
  /**
48
58
  * Main request method for making API calls to the Wallaby API.
49
59
  * @param route - Route configuration object containing the endpoint path and HTTP method
50
60
  * @param options - Optional request options including payload and query parameters
51
61
  * @param retried - Internal flag; set to true when retrying after a 401 to prevent loops
62
+ * @param silent - Internal flag; when true the resulting WallabyError does NOT fire
63
+ * `options.onError`. Used for best-effort refreshes whose failure is
64
+ * swallowed by the caller (e.g. proactive refresh in securityWorker),
65
+ * so an internal request never surfaces a consumer-facing error.
52
66
  * @returns Promise resolving to the typed response data
53
67
  * @throws Error if the API returns an error response or network failure occurs
54
68
  */
55
- protected request<T>(route: RequestRoute, options?: RequestOptions, retried?: boolean): Promise<T>;
69
+ protected request<T>(route: RequestRoute, options?: RequestOptions, retried?: boolean, silent?: boolean): Promise<T>;
56
70
  private _getRequestHeaders;
57
71
  protected securityWorker(securityData: any): Promise<any>;
58
72
  }