@bloque/sdk 0.0.25 → 0.0.27
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 +24 -662
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -6,708 +6,70 @@ The official TypeScript/JavaScript SDK for integrating [Bloque](https://www.bloq
|
|
|
6
6
|
>
|
|
7
7
|
> This SDK is currently under active development. Breaking changes may occur between versions.
|
|
8
8
|
> We strongly recommend pinning to a specific version in your `package.json` to avoid unexpected issues.
|
|
9
|
-
>
|
|
10
|
-
> ```json
|
|
11
|
-
> {
|
|
12
|
-
> "dependencies": {
|
|
13
|
-
> "@bloque/sdk": "x.x.x"
|
|
14
|
-
> }
|
|
15
|
-
> }
|
|
16
|
-
> ```
|
|
17
|
-
>
|
|
18
|
-
> Replace with the latest version from [npm](https://www.npmjs.com/package/@bloque/sdk).
|
|
19
9
|
|
|
20
10
|
## Platform Support
|
|
21
11
|
|
|
22
|
-
This SDK is compatible with multiple JavaScript runtimes:
|
|
23
|
-
|
|
24
12
|
- **Node.js** 22.x or higher
|
|
25
13
|
- **Bun** 1.x or higher
|
|
26
14
|
- **Deno** Latest version
|
|
27
15
|
- **Web/Browsers** Modern browsers with ES2020+ support
|
|
28
16
|
- **React Native** Latest version
|
|
29
17
|
|
|
30
|
-
## Features
|
|
31
|
-
|
|
32
|
-
- **TypeScript First**: Built with TypeScript for complete type safety
|
|
33
|
-
- **Modular Architecture**: Import only what you need - accounts, identity, compliance, or organizations
|
|
34
|
-
- **Multi-Runtime**: Works seamlessly across Node.js, Bun, Deno, browsers, and React Native
|
|
35
|
-
- **Account Management**: Create and manage virtual cards, virtual accounts, Polygon wallets, and Bancolombia accounts
|
|
36
|
-
- **Identity System**: Register individual users (KYC) and businesses (KYB) with multi-method authentication
|
|
37
|
-
- **Compliance Ready**: Built-in KYC/KYB verification workflows
|
|
38
|
-
- **Transfer System**: Transfer funds between accounts with multiple asset support
|
|
39
|
-
- **Production Ready**:
|
|
40
|
-
- ✅ Automatic retry with exponential backoff
|
|
41
|
-
- ✅ Configurable timeouts (default: 30s)
|
|
42
|
-
- ✅ Specific error types for better error handling
|
|
43
|
-
- ✅ Request ID tracking for debugging
|
|
44
|
-
- ✅ Security warnings for insecure practices
|
|
45
|
-
- **Lightweight**: Minimal dependencies for optimal bundle size
|
|
46
|
-
- **Fully Async**: Promise-based API for modern JavaScript workflows
|
|
47
|
-
|
|
48
18
|
## Installation
|
|
49
19
|
|
|
50
20
|
```bash
|
|
51
|
-
|
|
52
|
-
npm install @bloque/sdk
|
|
53
|
-
|
|
54
|
-
# bun
|
|
55
|
-
bun add @bloque/sdk
|
|
56
|
-
|
|
57
|
-
# pnpm
|
|
58
|
-
pnpm add @bloque/sdk
|
|
59
|
-
|
|
60
|
-
# yarn
|
|
61
|
-
yarn add @bloque/sdk
|
|
21
|
+
pnpm install @bloque/sdk
|
|
62
22
|
```
|
|
63
23
|
|
|
64
24
|
## Quick Start
|
|
65
25
|
|
|
66
|
-
### Backend (Node.js, Bun, Deno)
|
|
67
|
-
|
|
68
26
|
```typescript
|
|
69
27
|
import { SDK } from '@bloque/sdk';
|
|
70
28
|
|
|
71
|
-
// Initialize
|
|
29
|
+
// Initialize SDK
|
|
30
|
+
const bloque = await SDK.connect({
|
|
31
|
+
apiKey: process.env.BLOQUE_API_KEY!,
|
|
32
|
+
platform: 'node',
|
|
33
|
+
});
|
|
72
34
|
const bloque = new SDK({
|
|
73
|
-
origin: '
|
|
35
|
+
origin: 'bloque',
|
|
74
36
|
auth: {
|
|
75
37
|
type: 'apiKey',
|
|
76
|
-
apiKey:
|
|
38
|
+
apiKey: 'sk_live_862f110...',
|
|
77
39
|
},
|
|
78
40
|
mode: 'production', // or 'sandbox' for testing
|
|
79
|
-
platform: 'node',
|
|
80
|
-
timeout: 30000, // optional: request timeout in ms
|
|
81
|
-
retry: { // optional: retry configuration
|
|
82
|
-
enabled: true,
|
|
83
|
-
maxRetries: 3,
|
|
84
|
-
initialDelay: 1000,
|
|
85
|
-
},
|
|
41
|
+
platform: 'node',
|
|
86
42
|
});
|
|
87
43
|
|
|
88
|
-
// Connect to user session
|
|
89
|
-
const session = await bloque.connect('did:bloque:your-origin:user-alias');
|
|
90
|
-
|
|
91
44
|
// Create a virtual card
|
|
92
|
-
const card = await
|
|
45
|
+
const card = await bloque.accounts.card.create({
|
|
93
46
|
name: 'My Virtual Card',
|
|
94
47
|
});
|
|
95
48
|
|
|
96
49
|
console.log('Card created:', card.urn);
|
|
97
|
-
console.log('Last four digits:', card.lastFour);
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
### Frontend (Browser, React Native)
|
|
101
|
-
|
|
102
|
-
```typescript
|
|
103
|
-
import { SDK } from '@bloque/sdk';
|
|
104
|
-
|
|
105
|
-
// Initialize the SDK with JWT authentication
|
|
106
|
-
const bloque = new SDK({
|
|
107
|
-
origin: 'your-origin-name',
|
|
108
|
-
auth: { type: 'jwt' },
|
|
109
|
-
mode: 'production',
|
|
110
|
-
platform: 'browser', // or 'react-native'
|
|
111
|
-
// For browser: uses localStorage by default (with security warning)
|
|
112
|
-
// For react-native: provide custom tokenStorage
|
|
113
|
-
tokenStorage: {
|
|
114
|
-
get: () => {
|
|
115
|
-
// Your secure storage implementation
|
|
116
|
-
return AsyncStorage.getItem('bloque_token');
|
|
117
|
-
},
|
|
118
|
-
set: (token) => {
|
|
119
|
-
AsyncStorage.setItem('bloque_token', token);
|
|
120
|
-
},
|
|
121
|
-
clear: () => {
|
|
122
|
-
AsyncStorage.removeItem('bloque_token');
|
|
123
|
-
},
|
|
124
|
-
},
|
|
125
|
-
});
|
|
126
|
-
|
|
127
|
-
// Register a new user
|
|
128
|
-
const result = await bloque.identity.origins.register(
|
|
129
|
-
'did:bloque:your-origin:ethereum-mainnet',
|
|
130
|
-
{
|
|
131
|
-
assertionResult: { /* signing challenge result */ },
|
|
132
|
-
type: 'individual',
|
|
133
|
-
profile: {
|
|
134
|
-
firstName: 'John',
|
|
135
|
-
lastName: 'Doe',
|
|
136
|
-
email: 'john@example.com',
|
|
137
|
-
},
|
|
138
|
-
}
|
|
139
|
-
);
|
|
140
|
-
|
|
141
|
-
// The JWT is automatically stored and used for subsequent requests
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
## Configuration
|
|
145
|
-
|
|
146
|
-
### Full Configuration Options
|
|
147
|
-
|
|
148
|
-
```typescript
|
|
149
|
-
interface BloqueSDKConfig {
|
|
150
|
-
// Required
|
|
151
|
-
origin: string; // Your origin identifier
|
|
152
|
-
auth: AuthStrategy; // Authentication strategy
|
|
153
|
-
|
|
154
|
-
// Optional
|
|
155
|
-
platform?: Platform; // Runtime platform (default: 'node')
|
|
156
|
-
mode?: Mode; // Environment mode (default: 'production')
|
|
157
|
-
timeout?: number; // Request timeout in ms (default: 30000)
|
|
158
|
-
tokenStorage?: TokenStorage; // JWT storage (required for react-native)
|
|
159
|
-
retry?: RetryConfig; // Retry configuration
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
// Authentication strategies
|
|
163
|
-
type AuthStrategy =
|
|
164
|
-
| { type: 'apiKey'; apiKey: string } // Backend only
|
|
165
|
-
| { type: 'jwt' }; // Frontend (browser/react-native)
|
|
166
|
-
|
|
167
|
-
// Platforms
|
|
168
|
-
type Platform = 'node' | 'bun' | 'deno' | 'browser' | 'react-native';
|
|
169
|
-
|
|
170
|
-
// Modes
|
|
171
|
-
type Mode = 'production' | 'sandbox';
|
|
172
|
-
|
|
173
|
-
// Retry configuration
|
|
174
|
-
interface RetryConfig {
|
|
175
|
-
enabled?: boolean; // default: true
|
|
176
|
-
maxRetries?: number; // default: 3
|
|
177
|
-
initialDelay?: number; // default: 1000ms
|
|
178
|
-
maxDelay?: number; // default: 30000ms
|
|
179
|
-
}
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
## SDK Structure
|
|
183
|
-
|
|
184
|
-
After connecting to a user session, you have access to these clients:
|
|
185
|
-
|
|
186
|
-
```typescript
|
|
187
|
-
const session = await bloque.connect('did:bloque:your-origin:user-alias');
|
|
188
|
-
|
|
189
|
-
// Available clients
|
|
190
|
-
session.accounts // Account management
|
|
191
|
-
session.identity // Identity and aliases
|
|
192
|
-
session.compliance // KYC/KYB verification
|
|
193
|
-
session.orgs // Organization management
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
## Accounts Client
|
|
197
|
-
|
|
198
|
-
The accounts client provides access to multiple account types:
|
|
199
|
-
|
|
200
|
-
### Virtual Cards
|
|
201
|
-
|
|
202
|
-
```typescript
|
|
203
|
-
// Create a virtual card
|
|
204
|
-
const card = await session.accounts.card.create({
|
|
205
|
-
name: 'My Card',
|
|
206
|
-
webhookUrl: 'https://your-app.com/webhooks/card',
|
|
207
|
-
});
|
|
208
|
-
|
|
209
|
-
// List cards
|
|
210
|
-
const cards = await session.accounts.card.list();
|
|
211
|
-
|
|
212
|
-
// Check balance
|
|
213
|
-
const balance = await session.accounts.card.balance({
|
|
214
|
-
urn: card.urn,
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
// Get movements/transactions
|
|
218
|
-
const movements = await session.accounts.card.movements({
|
|
219
|
-
urn: card.urn,
|
|
220
|
-
asset: 'DUSD/6',
|
|
221
|
-
limit: 50,
|
|
222
|
-
direction: 'in', // 'in' | 'out'
|
|
223
|
-
});
|
|
224
|
-
|
|
225
|
-
// Update card
|
|
226
|
-
const updated = await session.accounts.card.updateMetadata({
|
|
227
|
-
urn: card.urn,
|
|
228
|
-
metadata: { name: 'Updated Name' },
|
|
229
|
-
});
|
|
230
|
-
|
|
231
|
-
// Manage card state
|
|
232
|
-
await session.accounts.card.activate(card.urn);
|
|
233
|
-
await session.accounts.card.freeze(card.urn);
|
|
234
|
-
await session.accounts.card.disable(card.urn);
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
### Virtual Accounts
|
|
238
|
-
|
|
239
|
-
Virtual accounts are simple testing accounts requiring only basic personal information:
|
|
240
|
-
|
|
241
|
-
```typescript
|
|
242
|
-
// Create a virtual account
|
|
243
|
-
const account = await session.accounts.virtual.create({
|
|
244
|
-
firstName: 'John',
|
|
245
|
-
lastName: 'Doe',
|
|
246
|
-
metadata: {
|
|
247
|
-
environment: 'testing',
|
|
248
|
-
purpose: 'integration-test',
|
|
249
|
-
},
|
|
250
|
-
});
|
|
251
|
-
|
|
252
|
-
// Update metadata
|
|
253
|
-
await session.accounts.virtual.updateMetadata({
|
|
254
|
-
urn: account.urn,
|
|
255
|
-
metadata: { updated_by: 'admin' },
|
|
256
|
-
});
|
|
257
|
-
|
|
258
|
-
// Manage account state
|
|
259
|
-
await session.accounts.virtual.activate(account.urn);
|
|
260
|
-
await session.accounts.virtual.freeze(account.urn);
|
|
261
|
-
await session.accounts.virtual.disable(account.urn);
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
### Polygon Wallets
|
|
265
|
-
|
|
266
|
-
Cryptocurrency wallets on the Polygon network for Web3 transactions:
|
|
267
|
-
|
|
268
|
-
```typescript
|
|
269
|
-
// Create a Polygon wallet (no additional input required)
|
|
270
|
-
const wallet = await session.accounts.polygon.create({
|
|
271
|
-
metadata: {
|
|
272
|
-
purpose: 'web3-transactions',
|
|
273
|
-
project: 'my-dapp',
|
|
274
|
-
},
|
|
275
|
-
});
|
|
276
|
-
|
|
277
|
-
console.log('Wallet address:', wallet.address);
|
|
278
|
-
console.log('Network:', wallet.network); // "polygon"
|
|
279
|
-
|
|
280
|
-
// Update metadata
|
|
281
|
-
await session.accounts.polygon.updateMetadata({
|
|
282
|
-
urn: wallet.urn,
|
|
283
|
-
metadata: { environment: 'production' },
|
|
284
|
-
});
|
|
285
|
-
|
|
286
|
-
// Manage account state
|
|
287
|
-
await session.accounts.polygon.activate(wallet.urn);
|
|
288
|
-
await session.accounts.polygon.freeze(wallet.urn);
|
|
289
|
-
await session.accounts.polygon.disable(wallet.urn);
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
### Bancolombia Accounts
|
|
293
|
-
|
|
294
|
-
Colombian virtual accounts with unique reference code system:
|
|
295
|
-
|
|
296
|
-
```typescript
|
|
297
|
-
// Create a Bancolombia account
|
|
298
|
-
const account = await session.accounts.bancolombia.create({
|
|
299
|
-
name: 'Main Account',
|
|
300
|
-
webhookUrl: 'https://your-app.com/webhooks/bancolombia',
|
|
301
|
-
});
|
|
302
|
-
|
|
303
|
-
console.log('Reference code:', account.referenceCode);
|
|
304
|
-
|
|
305
|
-
// Update metadata or name
|
|
306
|
-
await session.accounts.bancolombia.updateMetadata({
|
|
307
|
-
urn: account.urn,
|
|
308
|
-
metadata: { category: 'savings' },
|
|
309
|
-
});
|
|
310
|
-
|
|
311
|
-
await session.accounts.bancolombia.updateName(account.urn, 'Savings Account');
|
|
312
|
-
|
|
313
|
-
// Manage account state
|
|
314
|
-
await session.accounts.bancolombia.activate(account.urn);
|
|
315
|
-
await session.accounts.bancolombia.freeze(account.urn);
|
|
316
|
-
await session.accounts.bancolombia.disable(account.urn);
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
### Transfers
|
|
320
|
-
|
|
321
|
-
Transfer funds between any account types:
|
|
322
|
-
|
|
323
|
-
```typescript
|
|
324
|
-
const result = await session.accounts.transfer({
|
|
325
|
-
sourceUrn: 'did:bloque:account:card:usr-123:crd-456',
|
|
326
|
-
destinationUrn: 'did:bloque:account:virtual:acc-789',
|
|
327
|
-
amount: '1000000', // Amount in smallest unit
|
|
328
|
-
asset: 'DUSD/6', // 'DUSD/6' | 'KSM/12'
|
|
329
|
-
metadata: {
|
|
330
|
-
description: 'Payment for services',
|
|
331
|
-
},
|
|
332
|
-
});
|
|
333
|
-
|
|
334
|
-
console.log('Transfer queued:', result.queueId);
|
|
335
|
-
console.log('Status:', result.status); // 'queued' | 'processing' | 'completed' | 'failed'
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
## Identity Client
|
|
339
|
-
|
|
340
|
-
Manage user identities and authentication:
|
|
341
|
-
|
|
342
|
-
```typescript
|
|
343
|
-
// Get alias information
|
|
344
|
-
const alias = await session.identity.aliases.get('user@example.com');
|
|
345
|
-
|
|
346
|
-
// List available origins
|
|
347
|
-
const origins = await session.identity.origins.list();
|
|
348
|
-
|
|
349
|
-
// Register a new identity (individual)
|
|
350
|
-
const result = await bloque.identity.origins.register(
|
|
351
|
-
'did:bloque:your-origin:ethereum-mainnet',
|
|
352
|
-
{
|
|
353
|
-
assertionResult: {
|
|
354
|
-
alias: '0x742d35Cc...',
|
|
355
|
-
challengeType: 'SIGNING_CHALLENGE',
|
|
356
|
-
value: {
|
|
357
|
-
signature: '0x...',
|
|
358
|
-
alias: '0x742d35Cc...',
|
|
359
|
-
},
|
|
360
|
-
},
|
|
361
|
-
type: 'individual',
|
|
362
|
-
profile: {
|
|
363
|
-
firstName: 'John',
|
|
364
|
-
lastName: 'Doe',
|
|
365
|
-
email: 'john@example.com',
|
|
366
|
-
birthdate: '1990-01-15',
|
|
367
|
-
countryOfResidenceCode: 'US',
|
|
368
|
-
},
|
|
369
|
-
}
|
|
370
|
-
);
|
|
371
|
-
|
|
372
|
-
// Register a business
|
|
373
|
-
const businessResult = await bloque.identity.origins.register(
|
|
374
|
-
'did:bloque:your-origin:ethereum-mainnet',
|
|
375
|
-
{
|
|
376
|
-
assertionResult: { /* ... */ },
|
|
377
|
-
type: 'business',
|
|
378
|
-
profile: {
|
|
379
|
-
legalName: 'Acme Corporation',
|
|
380
|
-
taxId: '123456789',
|
|
381
|
-
incorporationDate: '2020-01-01',
|
|
382
|
-
type: 'llc',
|
|
383
|
-
addressLine1: '123 Main St',
|
|
384
|
-
city: 'San Francisco',
|
|
385
|
-
state: 'CA',
|
|
386
|
-
country: 'US',
|
|
387
|
-
postalCode: '12345',
|
|
388
|
-
// ... other required fields
|
|
389
|
-
},
|
|
390
|
-
}
|
|
391
|
-
);
|
|
392
|
-
|
|
393
|
-
// OTP-based authentication
|
|
394
|
-
const otpEmail = await bloque.identity.origins.email.assert('user@example.com');
|
|
395
|
-
const otpWhatsApp = await bloque.identity.origins.whatsapp.assert('+1234567890');
|
|
396
|
-
const otpCustom = await bloque.identity.origins.custom('my-origin').assert('user-id');
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
## Compliance Client
|
|
400
|
-
|
|
401
|
-
KYC/KYB verification workflows:
|
|
402
|
-
|
|
403
|
-
```typescript
|
|
404
|
-
// Start KYC verification
|
|
405
|
-
const verification = await session.compliance.kyc.startVerification({
|
|
406
|
-
urn: 'did:bloque:user:123e4567',
|
|
407
|
-
webhookUrl: 'https://your-app.com/webhooks/kyc',
|
|
408
|
-
});
|
|
409
|
-
|
|
410
|
-
console.log('Verification URL:', verification.url);
|
|
411
|
-
console.log('Status:', verification.status);
|
|
412
|
-
|
|
413
|
-
// Get verification status
|
|
414
|
-
const status = await session.compliance.kyc.getVerification({
|
|
415
|
-
urn: 'did:bloque:user:123e4567',
|
|
416
|
-
});
|
|
417
|
-
|
|
418
|
-
console.log('Status:', status.status);
|
|
419
|
-
console.log('Completed at:', status.completedAt);
|
|
420
|
-
```
|
|
421
|
-
|
|
422
|
-
## Organizations Client
|
|
423
|
-
|
|
424
|
-
Create and manage organizations:
|
|
425
|
-
|
|
426
|
-
```typescript
|
|
427
|
-
const org = await session.orgs.create({
|
|
428
|
-
org_type: 'business',
|
|
429
|
-
profile: {
|
|
430
|
-
legal_name: 'Acme Corporation',
|
|
431
|
-
tax_id: '123456789',
|
|
432
|
-
incorporation_date: '2020-01-01',
|
|
433
|
-
business_type: 'llc',
|
|
434
|
-
incorporation_country_code: 'US',
|
|
435
|
-
incorporation_state: 'CA',
|
|
436
|
-
address_line1: '123 Main St',
|
|
437
|
-
address_line2: 'Suite 100',
|
|
438
|
-
postal_code: '12345',
|
|
439
|
-
city: 'San Francisco',
|
|
440
|
-
},
|
|
441
|
-
metadata: {
|
|
442
|
-
industry: 'technology',
|
|
443
|
-
},
|
|
444
|
-
});
|
|
445
|
-
|
|
446
|
-
console.log('Organization created:', org.urn);
|
|
447
|
-
console.log('Status:', org.status);
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
## Error Handling
|
|
451
|
-
|
|
452
|
-
The SDK provides specific error types for better error handling:
|
|
453
|
-
|
|
454
|
-
```typescript
|
|
455
|
-
import {
|
|
456
|
-
BloqueRateLimitError,
|
|
457
|
-
BloqueAuthenticationError,
|
|
458
|
-
BloqueValidationError,
|
|
459
|
-
BloqueNotFoundError,
|
|
460
|
-
BloqueInsufficientFundsError,
|
|
461
|
-
BloqueNetworkError,
|
|
462
|
-
BloqueTimeoutError,
|
|
463
|
-
} from '@bloque/sdk';
|
|
464
|
-
|
|
465
|
-
try {
|
|
466
|
-
const card = await session.accounts.card.create({ name: 'My Card' });
|
|
467
|
-
} catch (error) {
|
|
468
|
-
if (error instanceof BloqueRateLimitError) {
|
|
469
|
-
console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
|
|
470
|
-
console.log(`Request ID: ${error.requestId}`);
|
|
471
|
-
} else if (error instanceof BloqueValidationError) {
|
|
472
|
-
console.log('Validation errors:', error.validationErrors);
|
|
473
|
-
} else if (error instanceof BloqueAuthenticationError) {
|
|
474
|
-
console.log('Authentication failed. Check your API key.');
|
|
475
|
-
} else if (error instanceof BloqueNotFoundError) {
|
|
476
|
-
console.log(`Resource not found: ${error.resourceType}`);
|
|
477
|
-
} else if (error instanceof BloqueInsufficientFundsError) {
|
|
478
|
-
console.log(`Insufficient funds: ${error.requestedAmount} ${error.currency}`);
|
|
479
|
-
console.log(`Available: ${error.availableBalance} ${error.currency}`);
|
|
480
|
-
} else if (error instanceof BloqueTimeoutError) {
|
|
481
|
-
console.log(`Request timed out after ${error.timeoutMs}ms`);
|
|
482
|
-
} else if (error instanceof BloqueNetworkError) {
|
|
483
|
-
console.log('Network error:', error.message);
|
|
484
|
-
}
|
|
485
|
-
|
|
486
|
-
// All errors have these fields
|
|
487
|
-
console.log('Error details:', error.toJSON());
|
|
488
|
-
}
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
### Error Metadata
|
|
492
|
-
|
|
493
|
-
All errors include rich metadata for debugging:
|
|
494
|
-
|
|
495
|
-
- `message`: Human-readable error message
|
|
496
|
-
- `status`: HTTP status code (if applicable)
|
|
497
|
-
- `code`: Error code from the API
|
|
498
|
-
- `requestId`: Unique request ID for tracing
|
|
499
|
-
- `timestamp`: When the error occurred
|
|
500
|
-
- `response`: Original response body (for debugging)
|
|
501
|
-
- `cause`: Original error (for error chaining)
|
|
502
|
-
|
|
503
|
-
## Retry Logic
|
|
504
|
-
|
|
505
|
-
The SDK automatically retries failed requests with exponential backoff:
|
|
506
|
-
|
|
507
|
-
- **Retried scenarios**: 429 (Rate Limit), 503 (Service Unavailable), network errors, timeouts
|
|
508
|
-
- **Exponential backoff**: Delay increases exponentially (1s → 2s → 4s)
|
|
509
|
-
- **Jitter**: ±25% random jitter to prevent thundering herd
|
|
510
|
-
- **Respects Retry-After**: Honors the `Retry-After` header when present
|
|
511
|
-
|
|
512
|
-
```typescript
|
|
513
|
-
const bloque = new SDK({
|
|
514
|
-
origin: 'your-origin',
|
|
515
|
-
auth: { type: 'apiKey', apiKey: 'key' },
|
|
516
|
-
retry: {
|
|
517
|
-
enabled: true, // default: true
|
|
518
|
-
maxRetries: 3, // default: 3
|
|
519
|
-
initialDelay: 1000, // default: 1000ms
|
|
520
|
-
maxDelay: 30000, // default: 30000ms
|
|
521
|
-
},
|
|
522
|
-
});
|
|
523
|
-
```
|
|
524
|
-
|
|
525
|
-
## Timeout Configuration
|
|
526
|
-
|
|
527
|
-
Configure request timeouts globally or per-request:
|
|
528
|
-
|
|
529
|
-
```typescript
|
|
530
|
-
// Global timeout
|
|
531
|
-
const bloque = new SDK({
|
|
532
|
-
origin: 'your-origin',
|
|
533
|
-
auth: { type: 'apiKey', apiKey: 'key' },
|
|
534
|
-
timeout: 15000, // 15 seconds
|
|
535
|
-
});
|
|
536
|
-
|
|
537
|
-
// Per-request timeout (override global)
|
|
538
|
-
const card = await session.accounts.card.create(
|
|
539
|
-
{ name: 'My Card' },
|
|
540
|
-
{ timeout: 5000 } // 5 seconds for this request
|
|
541
|
-
);
|
|
542
|
-
```
|
|
543
|
-
|
|
544
|
-
## Security Best Practices
|
|
545
|
-
|
|
546
|
-
### API Keys
|
|
547
|
-
|
|
548
|
-
- ✅ Store API keys in environment variables
|
|
549
|
-
- ✅ Use different keys for development and production
|
|
550
|
-
- ✅ Never commit API keys to version control
|
|
551
|
-
- ✅ Rotate API keys regularly
|
|
552
|
-
- ❌ Never expose API keys in client-side code
|
|
553
|
-
|
|
554
|
-
### Token Storage (Frontend)
|
|
555
|
-
|
|
556
|
-
The SDK warns when using insecure storage:
|
|
557
|
-
|
|
558
|
-
```typescript
|
|
559
|
-
// Browser: localStorage (⚠️ vulnerable to XSS)
|
|
560
|
-
const bloque = new SDK({
|
|
561
|
-
auth: { type: 'jwt' },
|
|
562
|
-
platform: 'browser',
|
|
563
|
-
// Uses localStorage by default with security warning
|
|
564
|
-
});
|
|
565
|
-
|
|
566
|
-
// Recommended: httpOnly cookies (immune to XSS)
|
|
567
|
-
const cookieStorage: TokenStorage = {
|
|
568
|
-
get: () => null, // Token sent automatically in cookie
|
|
569
|
-
set: async (token) => {
|
|
570
|
-
await fetch('/api/auth/set-token', {
|
|
571
|
-
method: 'POST',
|
|
572
|
-
body: JSON.stringify({ token }),
|
|
573
|
-
});
|
|
574
|
-
},
|
|
575
|
-
clear: async () => {
|
|
576
|
-
await fetch('/api/auth/logout', { method: 'POST' });
|
|
577
|
-
},
|
|
578
|
-
};
|
|
579
|
-
|
|
580
|
-
const bloque = new SDK({
|
|
581
|
-
auth: { type: 'jwt' },
|
|
582
|
-
platform: 'browser',
|
|
583
|
-
tokenStorage: cookieStorage,
|
|
584
|
-
});
|
|
585
|
-
```
|
|
586
|
-
|
|
587
|
-
## TypeScript Support
|
|
588
|
-
|
|
589
|
-
The SDK is built with TypeScript and provides full type safety:
|
|
590
|
-
|
|
591
|
-
```typescript
|
|
592
|
-
import type {
|
|
593
|
-
BloqueSDKConfig,
|
|
594
|
-
CardAccount,
|
|
595
|
-
CreateCardParams,
|
|
596
|
-
VirtualAccount,
|
|
597
|
-
CreateVirtualAccountParams,
|
|
598
|
-
PolygonAccount,
|
|
599
|
-
CreatePolygonAccountParams,
|
|
600
|
-
TransferParams,
|
|
601
|
-
TransferResult,
|
|
602
|
-
} from '@bloque/sdk';
|
|
603
|
-
|
|
604
|
-
// Type-safe configuration
|
|
605
|
-
const config: BloqueSDKConfig = {
|
|
606
|
-
origin: 'your-origin',
|
|
607
|
-
auth: { type: 'apiKey', apiKey: 'key' },
|
|
608
|
-
mode: 'production',
|
|
609
|
-
};
|
|
610
|
-
|
|
611
|
-
// Type-safe parameters
|
|
612
|
-
const params: CreateCardParams = {
|
|
613
|
-
name: 'My Card',
|
|
614
|
-
};
|
|
615
|
-
|
|
616
|
-
// Type-safe responses
|
|
617
|
-
const card: CardAccount = await session.accounts.card.create(params);
|
|
618
|
-
```
|
|
619
|
-
|
|
620
|
-
## Package Exports
|
|
621
|
-
|
|
622
|
-
The SDK supports modular imports:
|
|
623
|
-
|
|
624
|
-
```typescript
|
|
625
|
-
// Main SDK
|
|
626
|
-
import { SDK } from '@bloque/sdk';
|
|
627
|
-
|
|
628
|
-
// Initialization helper
|
|
629
|
-
import { init } from '@bloque/sdk/init';
|
|
630
|
-
|
|
631
|
-
// Modular clients (tree-shakeable)
|
|
632
|
-
import { AccountsClient } from '@bloque/sdk/accounts';
|
|
633
|
-
import { IdentityClient } from '@bloque/sdk/identity';
|
|
634
|
-
import { ComplianceClient } from '@bloque/sdk/compliance';
|
|
635
|
-
import { OrgsClient } from '@bloque/sdk/orgs';
|
|
636
|
-
|
|
637
|
-
// Types
|
|
638
|
-
import type {
|
|
639
|
-
BloqueSDKConfig,
|
|
640
|
-
CardAccount,
|
|
641
|
-
VirtualAccount,
|
|
642
|
-
PolygonAccount,
|
|
643
|
-
BancolombiaAccount,
|
|
644
|
-
} from '@bloque/sdk';
|
|
645
|
-
```
|
|
646
|
-
|
|
647
|
-
## Advanced Usage
|
|
648
|
-
|
|
649
|
-
### Custom HTTP Client
|
|
650
|
-
|
|
651
|
-
For advanced use cases, access the HTTP client directly:
|
|
652
|
-
|
|
653
|
-
```typescript
|
|
654
|
-
const session = await bloque.connect('did:bloque:your-origin:user-alias');
|
|
655
|
-
|
|
656
|
-
// Access the HTTP client
|
|
657
|
-
const httpClient = session.accounts.card['httpClient'];
|
|
658
|
-
|
|
659
|
-
// Make custom requests
|
|
660
|
-
const response = await httpClient.request({
|
|
661
|
-
method: 'GET',
|
|
662
|
-
path: '/api/custom-endpoint',
|
|
663
|
-
timeout: 10000,
|
|
664
|
-
});
|
|
665
|
-
```
|
|
666
|
-
|
|
667
|
-
### Environment-Specific Configuration
|
|
668
|
-
|
|
669
|
-
```typescript
|
|
670
|
-
const config: BloqueSDKConfig = {
|
|
671
|
-
origin: process.env.BLOQUE_ORIGIN!,
|
|
672
|
-
auth: {
|
|
673
|
-
type: 'apiKey',
|
|
674
|
-
apiKey: process.env.BLOQUE_API_KEY!,
|
|
675
|
-
},
|
|
676
|
-
mode: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
|
|
677
|
-
platform: 'node',
|
|
678
|
-
timeout: Number.parseInt(process.env.BLOQUE_TIMEOUT || '30000', 10),
|
|
679
|
-
retry: {
|
|
680
|
-
enabled: process.env.BLOQUE_RETRY_ENABLED !== 'false',
|
|
681
|
-
maxRetries: Number.parseInt(process.env.BLOQUE_MAX_RETRIES || '3', 10),
|
|
682
|
-
},
|
|
683
|
-
};
|
|
684
|
-
|
|
685
|
-
const bloque = new SDK(config);
|
|
686
50
|
```
|
|
687
51
|
|
|
688
|
-
##
|
|
52
|
+
## Documentation
|
|
689
53
|
|
|
690
|
-
|
|
54
|
+
For complete documentation, examples, and guides, visit:
|
|
691
55
|
|
|
692
|
-
|
|
693
|
-
- `virtual-cards.ts` - Virtual card management
|
|
694
|
-
- `virtual-accounts.ts` - Virtual account management
|
|
695
|
-
- `transfers.ts` - Account transfers
|
|
696
|
-
- `identity-registration.ts` - User registration
|
|
697
|
-
- `kyc-verification.ts` - KYC workflows
|
|
698
|
-
- `error-handling.ts` - Advanced error handling
|
|
56
|
+
**[https://docs.bloque.app/sdk](https://docs.bloque.app/sdk)**
|
|
699
57
|
|
|
700
|
-
|
|
58
|
+
The documentation includes:
|
|
701
59
|
|
|
702
|
-
|
|
60
|
+
- Getting started guides
|
|
61
|
+
- Account management (Virtual Cards, US Accounts, Polygon, Bancolombia)
|
|
62
|
+
- Identity and authentication
|
|
63
|
+
- Transfers and transactions
|
|
64
|
+
- Error handling
|
|
65
|
+
- TypeScript support
|
|
66
|
+
- Advanced configuration
|
|
703
67
|
|
|
704
68
|
## Support
|
|
705
69
|
|
|
706
|
-
-
|
|
707
|
-
-
|
|
708
|
-
- 📖 Docs: [docs.bloque.app](https://docs.bloque.app)
|
|
709
|
-
- 🐛 Issues: [GitHub Issues](https://github.com/bloque/sdk/issues)
|
|
70
|
+
- **Documentation**: [docs.bloque.app/sdk](https://docs.bloque.app/sdk)
|
|
71
|
+
- **GitHub Issues**: [github.com/bloque/sdk/issues](https://github.com/bloque/sdk/issues)
|
|
710
72
|
|
|
711
73
|
## License
|
|
712
74
|
|
|
713
|
-
MIT © [Bloque](https://www.bloque.app)
|
|
75
|
+
[MIT](../../LICENSE) © [Bloque](https://www.bloque.app)
|
package/dist/index.cjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,t)=>{for(var i in t)__webpack_require__.o(t,i)&&!__webpack_require__.o(e,i)&&Object.defineProperty(e,i,{enumerable:!0,get:t[i]})},__webpack_require__.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{SDK:()=>SDK});const sdk_accounts_namespaceObject=require("@bloque/sdk-accounts"),sdk_compliance_namespaceObject=require("@bloque/sdk-compliance"),sdk_core_namespaceObject=require("@bloque/sdk-core"),sdk_identity_namespaceObject=require("@bloque/sdk-identity"),sdk_orgs_namespaceObject=require("@bloque/sdk-orgs");class SDK{httpClient;identity;constructor(e){this.httpClient=new sdk_core_namespaceObject.HttpClient(e),this.identity=new sdk_identity_namespaceObject.IdentityClient(this.httpClient)}buildClients(){return{accounts:new sdk_accounts_namespaceObject.AccountsClient(this.httpClient),compliance:new sdk_compliance_namespaceObject.ComplianceClient(this.httpClient),identity:this.identity,orgs:new sdk_orgs_namespaceObject.OrgsClient(this.httpClient)}}getApiKey(){let{auth:e}=this.httpClient;return"apiKey"===e.type?e.apiKey:""}buildUrn(e){let t=this.httpClient.origin;if(!t)throw Error("Origin is required to build a urn");return`did:bloque:${t}:${e}`}async register(e,t){t.extraContext||(t.extraContext={});let i=this.buildUrn(e),r=this.httpClient.origin,_=await this.identity.origins.register(
|
|
1
|
+
"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,t)=>{for(var i in t)__webpack_require__.o(t,i)&&!__webpack_require__.o(e,i)&&Object.defineProperty(e,i,{enumerable:!0,get:t[i]})},__webpack_require__.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{SDK:()=>SDK});const sdk_accounts_namespaceObject=require("@bloque/sdk-accounts"),sdk_compliance_namespaceObject=require("@bloque/sdk-compliance"),sdk_core_namespaceObject=require("@bloque/sdk-core"),sdk_identity_namespaceObject=require("@bloque/sdk-identity"),sdk_orgs_namespaceObject=require("@bloque/sdk-orgs");class SDK{httpClient;identity;constructor(e){this.httpClient=new sdk_core_namespaceObject.HttpClient(e),this.identity=new sdk_identity_namespaceObject.IdentityClient(this.httpClient)}buildClients(){return{accounts:new sdk_accounts_namespaceObject.AccountsClient(this.httpClient),compliance:new sdk_compliance_namespaceObject.ComplianceClient(this.httpClient),identity:this.identity,orgs:new sdk_orgs_namespaceObject.OrgsClient(this.httpClient)}}getApiKey(){let{auth:e}=this.httpClient;return"apiKey"===e.type?e.apiKey:""}buildUrn(e){let t=this.httpClient.origin;if(!t)throw Error("Origin is required to build a urn");return`did:bloque:${t}:${e}`}async register(e,t){t.extraContext||(t.extraContext={});let i=this.buildUrn(e),r=this.httpClient.origin,_=await this.identity.origins.register(e,r,{assertionResult:{alias:e,challengeType:"API_KEY",value:{apiKey:this.getApiKey(),alias:e}},...t});return this.httpClient.setAccessToken(_.accessToken),this.httpClient.setUrn(i),this.buildClients()}async connect(e){let t=this.buildUrn(e),i=this.httpClient.origin,r=await this.httpClient.request({path:`/api/origins/${i}/connect`,method:"POST",body:{assertion_result:{challengeType:"API_KEY",value:{api_key:this.getApiKey(),alias:e}},extra_context:{}}});return this.httpClient.setAccessToken(r.result.access_token),this.httpClient.setUrn(t),this.buildClients()}}for(var __rspack_i in exports.SDK=__webpack_exports__.SDK,__webpack_exports__)-1===["SDK"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{AccountsClient as t}from"@bloque/sdk-accounts";import{ComplianceClient as e}from"@bloque/sdk-compliance";import{HttpClient as i}from"@bloque/sdk-core";import{IdentityClient as n}from"@bloque/sdk-identity";import{OrgsClient as s}from"@bloque/sdk-orgs";class r{httpClient;identity;constructor(t){this.httpClient=new i(t),this.identity=new n(this.httpClient)}buildClients(){return{accounts:new t(this.httpClient),compliance:new e(this.httpClient),identity:this.identity,orgs:new s(this.httpClient)}}getApiKey(){let{auth:t}=this.httpClient;return"apiKey"===t.type?t.apiKey:""}buildUrn(t){let e=this.httpClient.origin;if(!e)throw Error("Origin is required to build a urn");return`did:bloque:${e}:${t}`}async register(t,e){e.extraContext||(e.extraContext={});let i=this.buildUrn(t),n=this.httpClient.origin,s=await this.identity.origins.register(
|
|
1
|
+
import{AccountsClient as t}from"@bloque/sdk-accounts";import{ComplianceClient as e}from"@bloque/sdk-compliance";import{HttpClient as i}from"@bloque/sdk-core";import{IdentityClient as n}from"@bloque/sdk-identity";import{OrgsClient as s}from"@bloque/sdk-orgs";class r{httpClient;identity;constructor(t){this.httpClient=new i(t),this.identity=new n(this.httpClient)}buildClients(){return{accounts:new t(this.httpClient),compliance:new e(this.httpClient),identity:this.identity,orgs:new s(this.httpClient)}}getApiKey(){let{auth:t}=this.httpClient;return"apiKey"===t.type?t.apiKey:""}buildUrn(t){let e=this.httpClient.origin;if(!e)throw Error("Origin is required to build a urn");return`did:bloque:${e}:${t}`}async register(t,e){e.extraContext||(e.extraContext={});let i=this.buildUrn(t),n=this.httpClient.origin,s=await this.identity.origins.register(t,n,{assertionResult:{alias:t,challengeType:"API_KEY",value:{apiKey:this.getApiKey(),alias:t}},...e});return this.httpClient.setAccessToken(s.accessToken),this.httpClient.setUrn(i),this.buildClients()}async connect(t){let e=this.buildUrn(t),i=this.httpClient.origin,n=await this.httpClient.request({path:`/api/origins/${i}/connect`,method:"POST",body:{assertion_result:{challengeType:"API_KEY",value:{api_key:this.getApiKey(),alias:t}},extra_context:{}}});return this.httpClient.setAccessToken(n.result.access_token),this.httpClient.setUrn(e),this.buildClients()}}export{r as SDK};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bloque/sdk",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.27",
|
|
4
4
|
"description": "Official Bloque SDK",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"access": "public",
|
|
14
14
|
"provenance": true
|
|
15
15
|
},
|
|
16
|
-
"homepage": "
|
|
16
|
+
"homepage": "https://docs.bloque.app/sdk",
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|
|
19
19
|
"url": "git+https://github.com/bloque-app/sdk.git",
|
|
@@ -63,10 +63,10 @@
|
|
|
63
63
|
"node": ">=22"
|
|
64
64
|
},
|
|
65
65
|
"dependencies": {
|
|
66
|
-
"@bloque/sdk-accounts": "0.0.
|
|
67
|
-
"@bloque/sdk-compliance": "0.0.
|
|
68
|
-
"@bloque/sdk-core": "0.0.
|
|
69
|
-
"@bloque/sdk-identity": "0.0.
|
|
70
|
-
"@bloque/sdk-orgs": "0.0.
|
|
66
|
+
"@bloque/sdk-accounts": "0.0.27",
|
|
67
|
+
"@bloque/sdk-compliance": "0.0.27",
|
|
68
|
+
"@bloque/sdk-core": "0.0.27",
|
|
69
|
+
"@bloque/sdk-identity": "0.0.27",
|
|
70
|
+
"@bloque/sdk-orgs": "0.0.27"
|
|
71
71
|
}
|
|
72
72
|
}
|