@frihet/sdk

Official TypeScript SDK for the Frihet API. AI-native business management.

Install

npm install @frihet/sdk

Quick start

import Frihet from '@frihet/sdk';

const frihet = new Frihet({ apiKey: 'fri_...' });

// Create an invoice
const invoice = await frihet.invoices.create({
  clientName: 'Acme Corp',
  items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
});

// List overdue invoices
const overdue = await frihet.invoices.list({ status: 'overdue' });

// Mark as paid
await frihet.invoices.markPaid(invoice.id);

// Send by email
await frihet.invoices.send(invoice.id, { recipientEmail: '[email protected]' });

// Download PDF
const pdf = await frihet.invoices.pdf(invoice.id);

Resources

| Resource | Methods | |----------|---------| | frihet.invoices | list, retrieve, create, update, del, search, markPaid, send, pdf, createBatch | | frihet.expenses | list, retrieve, create, update, del, search, createBatch | | frihet.clients | list, retrieve, create, update, del, search | | frihet.vendors | list, retrieve, create, update, del, search | | frihet.products | list, retrieve, create, update, del, search | | frihet.quotes | list, retrieve, create, update, del, search, send, pdf | | frihet.webhooks | list, retrieve, create, update, del | | frihet.intelligence | context, summary, monthly, quarterly |

Intelligence

// Full business context (one call for AI agents)
const ctx = await frihet.intelligence.context();

// Monthly P&L with tax liability
const march = await frihet.intelligence.monthly('2026-03');

// Quarterly tax prep (Modelo 303/130)
const q1 = await frihet.intelligence.quarterly('2026-Q1');

// Financial summary with date range
const ytd = await frihet.intelligence.summary({ from: '2026-01-01', to: '2026-12-31' });

Error handling

import Frihet, { RateLimitError, NotFoundError, ValidationError } from '@frihet/sdk';

try {
  await frihet.invoices.retrieve('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Invoice not found');
  } else if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter}s`);
  } else if (err instanceof ValidationError) {
    console.log('Validation:', err.details);
  }
}

Webhook verification

import { Webhooks } from '@frihet/sdk';

const isValid = Webhooks.verifySignature(
  rawBody,
  req.headers['x-frihet-signature'],
  webhookSecret,
);

Configuration

const frihet = new Frihet({
  apiKey: 'fri_...',
  baseUrl: 'https://api.frihet.io/v1', // default
  timeout: 30000, // 30s default
});

// Per-request options
await frihet.invoices.create(data, {
  idempotencyKey: 'unique-key-123',
  timeout: 60000,
});

Features

• Full TypeScript types with autocompletion
• Automatic retry on rate limits (429) and server errors (5xx)
• Exponential backoff with configurable retries
• Idempotency key support for safe retries
• Dual CJS/ESM output
• Zero runtime dependencies
• Request ID tracking on errors
• HMAC webhook signature verification

Links

• API Documentation
• MCP Server
• CLI

License

MIT