@samuraios/api-client

Lightweight Node.js SDK for the SamuRAI OS B2B API. Zero dependencies (uses native fetch), automatic retry on 429, and transparent rate-limit header parsing.

Requirements

• Node.js 24+ (native fetch)
• Active B2B API subscription

Installation

This package is distributed exclusively to paying B2B API subscribers. To install, use your API key to obtain a download URL:

# Get the download URL (requires your API key)
curl -H "x-api-key: sk_live_your_key" https://api.0xsamuraios.com/api/v1/sdk/download

# Install directly from the returned URL
npm install "https://presigned-s3-url-from-response..."

Or in one step (requires jq):

URL=$(curl -s -H "x-api-key: sk_live_your_key" \
  https://api.0xsamuraios.com/api/v1/sdk/download | jq -r '.data.downloadUrl')
npm install "$URL"

The download URL expires after 15 minutes. Generate a new one anytime with your API key.

Quick Start

import { createClient } from '@samuraios/api-client';

const samurai = createClient({ apiKey: 'sk_live_...' });

// Check RFC against SAT blacklists
const { data } = await samurai.compliance.searchSAT({ rfc: 'ABC123456789' });
console.log(data.found, data.matches);

// Check remaining rate limit after any call
console.log(samurai.rateLimit);
// { limit: 10, remaining: 9, reset: 1719936000 }

Configuration

const samurai = createClient({
  apiKey: 'sk_live_...',          // Required
  baseUrl: 'https://api-dev.0xsamuraios.com', // Optional (default: production)
  maxRetries: 3,                  // Optional: retries on 429 (default: 3)
  timeout: 30000,                 // Optional: request timeout ms (default: 30000)
  fetch: customFetch,             // Optional: custom fetch implementation
});

Verticals

Identity

await samurai.identity.lookup({ cedula: '1229587' });
await samurai.identity.verifyRICS({ memberNumber: '123456' });
await samurai.identity.searchAI({ lastName: 'Smith', designation: 'MAI' });
await samurai.identity.searchASA({ lastName: 'Garcia' });
await samurai.identity.listCredentials();
await samurai.identity.getCredential('cred_id');

Compliance

await samurai.compliance.searchSAT({ rfc: 'ABC123456789', articles: ['69b'] });
await samurai.compliance.getManifest();
await samurai.compliance.crossReference();
await samurai.compliance.searchOFAC({ name: 'John Doe' });
await samurai.compliance.searchONU({ name: 'Entity Name' });
await samurai.compliance.searchDOF({ name: 'Persona' });
await samurai.compliance.listMonitor();
await samurai.compliance.addMonitor({ rfc: 'ABC123456789', razonSocial: 'Empresa SA' });
await samurai.compliance.removeMonitor('monitor_id');
await samurai.compliance.getAlerts();
await samurai.compliance.bulkImport({ csv: 'RFC123456789,Empresa\nRFC987654321,Otra' });

Fiscal (CFDI)

await samurai.fiscal.uploadCredentials({ rfc, cerBase64, keyBase64, password });
await samurai.fiscal.listConnections();
await samurai.fiscal.getConnection('conn_id');
await samurai.fiscal.deleteConnection('conn_id');
await samurai.fiscal.createRequest({ connectionId, dateFrom: '2025-01-01', dateTo: '2025-06-30' });
await samurai.fiscal.listRequests();
await samurai.fiscal.getRequest('req_id');
await samurai.fiscal.cancelRequest('req_id');
await samurai.fiscal.retryRequest('req_id');
await samurai.fiscal.listCfdis({ connectionId, tipo: 'I', page: 1, limit: 50 });
await samurai.fiscal.getCfdi('uuid');
await samurai.fiscal.getAnalyticsSummary();
await samurai.fiscal.getAnalyticsConcentration();
await samurai.fiscal.getAnalyticsAnomalies();
await samurai.fiscal.getAnalyticsRunway();
await samurai.fiscal.getAnalyticsTaxReconciliation();
await samurai.fiscal.listCounterparties();
await samurai.fiscal.getRiskFlagged();

Trust (Notarization)

// Upload file first
const { data: upload } = await samurai.trust.getUploadUrl({ filename: 'contract.pdf' });
// PUT file to upload.data.uploadUrl, then:

await samurai.trust.notarize({ mode: 'storage', fileKey: upload.data.fileKey });
await samurai.trust.notarize({ mode: 'client_hash', hash: '0xabc...' });
await samurai.trust.verify({ hash: '0xabc...' });
await samurai.trust.getStatus('0xtxhash...');
await samurai.trust.certify({ fileKey: 'key', credentialId: 'cred_for_gold' });
await samurai.trust.getDownloadUrl({ fileKey: 'key' });

Data

await samurai.data.searchDENUE({ query: 'restaurantes', entidad: '09' });

Platform

await samurai.platform.createWebhook({ url: 'https://...', events: ['notarization.completed'] });
await samurai.platform.listWebhooks();
await samurai.platform.removeWebhook('wh_id');
await samurai.platform.getUsage({ period: '30d' });

Sandbox

await samurai.sandbox.notarize({ hash: '0x...', fileName: 'test.pdf' });
await samurai.sandbox.verify({ hash: '0x...' });

LegalOps (Contract Lifecycle Management)

await samurai.legalops.analyzeContract({ contractPdfKey: 'key' });
await samurai.legalops.getJob('job_id');
await samurai.legalops.listJobs();
await samurai.legalops.mitigateClause('job_id', { deviationId: 'dev_1' });
await samurai.legalops.getNegotiationUploadUrl({ fileName: 'contract.docx' });
await samurai.legalops.processNegotiation({ contractId: 'ctr_id' });
await samurai.legalops.listTemplates({ domain: 'commercial' });
await samurai.legalops.clonePlaybook('commercial', 'nda-standard');
await samurai.legalops.draftClause({ draftText: 'Limitation of liability...' });

CreditOps (Credit Origination for SOFOMes)

// Stateless underwriting engine
await samurai.creditops.underwrite({ borrower, sat_cfdi_summary_12m, collateral, loan_request });

// Tenant configuration
await samurai.creditops.getConfig();
await samurai.creditops.updateConfig({ referenceRates: { tiie28: 0.11 } });

// Application lifecycle
await samurai.creditops.createApplication({ borrower: { rfc: 'ABC010203XYZ' } });
// -> { applicationId, folio, applicantType, sessionToken, applyUrl }
await samurai.creditops.listApplications({ status: 'APPROVED' });
await samurai.creditops.getApplication('app_id');
await samurai.creditops.updateApplication('app_id', { loanRequest: { requestedAmount: 2000000 } });
await samurai.creditops.simulate('app_id', { requestedAmount: 2000000, tenorMonths: 24 });
await samurai.creditops.captureBuro('app_id', 700);
await samurai.creditops.dispatchUnderwriting('app_id');
await samurai.creditops.generateRecommendation('app_id');
await samurai.creditops.screen('app_id');
await samurai.creditops.invite('app_id', { email: '[email protected]' });

Error Handling

import { SamuraiApiError, RateLimitError } from '@samuraios/api-client';

try {
  await samurai.compliance.searchSAT({ rfc: 'bad' });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof SamuraiApiError) {
    console.log(err.status, err.code, err.message);
  }
}

Rate Limit Info

Every response includes rate limit data:

const { data, rateLimit } = await samurai.compliance.searchSAT({ rfc: '...' });
console.log(rateLimit);
// { limit: 10, remaining: 8, reset: 1719936000 }

// Also accessible globally (last call's info):
console.log(samurai.rateLimit);

License

MIT