@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

npm install @tormentalabs/floyd-sdk

Quick Start

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

// 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

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

Assets

// 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');

Wallets

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 });

History

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);
}

Blockchain

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

Error Handling

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

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