@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 CHANGED
@@ -329,10 +329,10 @@ const client = new DakotaClient({
329
329
 
330
330
  ## Idempotency Keys
331
331
 
332
- Dakota requires idempotency keys (UUID format) for all `POST`, `PUT`, and `PATCH` requests to ensure safe retries. By default, the SDK auto-generates keys for you, but you can provide your own for deterministic API calls:
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 for deterministic retries
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() } // or your own deterministic key
346
+ { idempotencyKey: uuid() }
348
347
  );
349
348
 
350
- // Use deterministic keys for replay safety
351
- const txKey = `invoice-${invoiceId}-payment`;
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 keys based on your business logic (e.g., `invoice-{id}-payment`)
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