@tormentalabs/floyd-sdk


Official Node.js SDK for the Floyd Blockchain API.

Features

- Full API coverage - Assets, Wallets, History, Blockchain status
- Auto-retry - Exponential backoff for transient failures
- Rate limit handling - Automatic queuing on 429 responses
- Pagination helpers - Async iterators for seamless pagination
- Idempotency - Auto-generated keys for safe retries
- Response caching - LRU cache for GET requests
- TypeScript - Full type definitions included
- Validators - Built-in CPF/CNPJ validation

Installation

``bash
npm install @tormentalabs/floyd-sdk
`

Quick Start

`typescript
import { Floyd } from '@tormentalabs/floyd-sdk';

const floyd = new Floyd({
apiKey: process.env.FLOYD_API_KEY,
});

// Create an asset
const asset = await floyd.assets.create({
name: 'My Bike',
legalEntity: 'PF',
document: '12345678901',
chassisNumber: 'ABC123',
serialNumber: 'SN-001',
invoiceDate: '2025-01-15',
mileage: 0,
});

// Wait for blockchain confirmation
const confirmed = await floyd.assets.waitForConfirmation(asset.id, {
timeout: 120000,
onProgress: (status) => console.log(Status: ${status}),
});

console.log(Confirmed with tx: ${confirmed.blockchain.transactionHash});
`

Pagination

`typescript
// Auto-pagination with async iterator
for await (const asset of floyd.assets.listAll({ limit: 100 })) {
console.log(asset.name);
}

// Collect all into array
const allAssets = await floyd.assets.listAll().toArray();

// With progress tracking
const assets = await floyd.assets.listAll({
onProgress: ({ fetched, hasMore }) => {
console.log(Fetched ${fetched} assets, more: ${hasMore});
}
}).toArray();
`

Configuration

`typescript
const floyd = new Floyd({
apiKey: 'your-api-key',
baseUrl: 'https://api.floyd.example.com', // optional

// Retry configuration
retry: {
maxAttempts: 3,
backoff: 'exponential', // 'exponential' | 'linear' | 'fixed'
initialDelay: 1000,
maxDelay: 30000,
},

// Timeouts
timeout: {
request: 30000,
},

// Caching (GET requests only)
cache: {
enabled: true,
ttl: 60000,
maxSize: 100,
},

// Auto-generate idempotency keys
idempotency: {
autoGenerate: true,
keyPrefix: 'floyd_',
},

// Debug logging
debug: true,
});
`

Resources

$3

`typescript
// CRUD
await floyd.assets.create({ ... });
await floyd.assets.get('asset-id');
await floyd.assets.list({ legalEntity: 'PF', limit: 50 });
await floyd.assets.update('asset-id', { mileage: 1000 });
await floyd.assets.delete('asset-id');

// Transfers
await floyd.assets.transfer('asset-id', {
name: 'New Owner',
legalEntity: 'PJ',
document: '12345678000199',
});

// Blockchain
await floyd.assets.verify('asset-id');
await floyd.assets.waitForConfirmation('asset-id');

// Accessories
await floyd.assets.attachAccessory('asset-id', 'acc-id', { name: 'GPS Tracker' });
await floyd.assets.detachAccessory('asset-id', 'acc-id');
`

$3

`typescript
await floyd.wallets.create({ userId: 'user-uuid' });
await floyd.wallets.get('user-id');
await floyd.wallets.getBalance('user-id');
await floyd.wallets.signMessage('user-id', { message: 'Hello' });
await floyd.wallets.signTypedData('user-id', { domain, types, value });
`

$3

`typescript
await floyd.history.search({
assetId: 'asset-id',
eventType: 'TRANSFER',
fromDate: '2025-01-01',
});

// Auto-pagination
for await (const event of floyd.history.searchAll({ assetId: 'id' })) {
console.log(event.eventType);
}
`

$3

`typescript
const status = await floyd.blockchain.status();
console.log(Connected: ${status.connected}, Block: ${status.latestBlock});
`

Error Handling

`typescript
import {
FloydError,
ValidationError,
NotFoundError,
RateLimitError
} from '@tormentalabs/floyd-sdk';

try {
await floyd.assets.get('invalid-id');
} catch (error) {
if (error instanceof NotFoundError) {
console.log('Asset not found');
} else if (error instanceof ValidationError) {
console.log('Validation errors:', error.details);
} else if (error instanceof RateLimitError) {
console.log(Rate limited, retry after ${error.retryAfter}s);
}
}
`

Testing

`typescript
import { createMockClient, createMockAsset } from '@tormentalabs/floyd-sdk/testing';

const mockFloyd = createMockClient({
assets: {
get: async () => createMockAsset({ name: 'Test Bike' }),
},
});

const asset = await mockFloyd.assets.get('id');
// asset.name === 'Test Bike'
``

Related Packages

- @tormentalabs/floyd-webhooks - Webhook handling
- @tormentalabs/floyd-types - TypeScript definitions
- @tormentalabs/floyd-validators - Document validators

License

MIT