@dakota-xyz/ts-sdk 1.0.16 → 1.1.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 +12 -8
- package/dist/index.d.mts +605 -91
- package/dist/index.d.ts +605 -91
- package/dist/index.js +506 -83
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +506 -84
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -329,10 +329,10 @@ const client = new DakotaClient({
|
|
|
329
329
|
|
|
330
330
|
## Idempotency Keys
|
|
331
331
|
|
|
332
|
-
Dakota requires idempotency keys (
|
|
332
|
+
Dakota requires idempotency keys (**must be valid UUIDs**) for all `POST`, `PUT`, and `PATCH` requests to ensure safe retries. By default, the SDK auto-generates UUID keys for you, but you can provide your own for deterministic API calls:
|
|
333
333
|
|
|
334
334
|
```typescript
|
|
335
|
-
import { v4 as uuid } from 'uuid';
|
|
335
|
+
import { v4 as uuid, v5 as uuidv5 } from 'uuid';
|
|
336
336
|
|
|
337
337
|
// Auto-generated idempotency key (default behavior)
|
|
338
338
|
const customer = await client.customers.create({
|
|
@@ -340,15 +340,17 @@ const customer = await client.customers.create({
|
|
|
340
340
|
customer_type: 'business',
|
|
341
341
|
});
|
|
342
342
|
|
|
343
|
-
// Custom idempotency key
|
|
344
|
-
const customerId = 'acme-corp-123';
|
|
343
|
+
// Custom UUID idempotency key
|
|
345
344
|
const customer = await client.customers.create(
|
|
346
345
|
{ name: 'Acme Corp', customer_type: 'business' },
|
|
347
|
-
{ idempotencyKey: uuid() }
|
|
346
|
+
{ idempotencyKey: uuid() }
|
|
348
347
|
);
|
|
349
348
|
|
|
350
|
-
//
|
|
351
|
-
const
|
|
349
|
+
// Deterministic UUID from business key (recommended for replay safety)
|
|
350
|
+
const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // Your app's namespace
|
|
351
|
+
const invoiceId = 'INV-12345';
|
|
352
|
+
const txKey = uuidv5(`invoice-${invoiceId}-payment`, NAMESPACE); // Always same UUID for same invoice
|
|
353
|
+
|
|
352
354
|
const tx = await client.transactions.create(
|
|
353
355
|
{
|
|
354
356
|
customer_id: customerId,
|
|
@@ -371,10 +373,12 @@ const txRetry = await client.transactions.create(
|
|
|
371
373
|
|
|
372
374
|
### When to Use Custom Idempotency Keys
|
|
373
375
|
|
|
374
|
-
- **Retry safety**: Use deterministic
|
|
376
|
+
- **Retry safety**: Use deterministic UUIDs derived from business keys (e.g., `uuidv5('invoice-123', NAMESPACE)`)
|
|
375
377
|
- **Distributed systems**: When requests may be retried across different processes
|
|
376
378
|
- **Exactly-once semantics**: When you need to guarantee no duplicate side effects
|
|
377
379
|
|
|
380
|
+
> **Note**: Idempotency keys must be valid UUIDs. Use `uuid` v5 to generate deterministic UUIDs from your business identifiers.
|
|
381
|
+
|
|
378
382
|
### Disable Auto-Generated Keys
|
|
379
383
|
|
|
380
384
|
```typescript
|