@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 { webhookSignatureVerify } from '@frihet/sdk';

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

Node-only, synchronous. Accepts the canonical Frihet header (timestamp=<unix>, signature=<hex64>) plus sha256=<hex64> and raw hex for compatibility. Validates timestamp freshness (default 300 s) and uses crypto.timingSafeEqual over hex-sanitized buffers — see functions/src/webhookVerification.ts for the equivalent server impl.

For non-Node runtimes use the async Webhooks.verifySignature static helper instead.

HR (leaves + attendance + payroll)

import {
  createLeaveRequest,
  approveLeave,
  rejectLeave,
  type LeaveType,
  type LeaveEntitlement,
  type AttendanceEntry,
  type PayrollProfile,
  type PayrollExportFormat,
} from '@frihet/sdk';

// helpers expect a transport — pass the same client your Frihet instance uses
const req = await createLeaveRequest(client, {
  employeeId: 'emp_123',
  type: 'vacation',
  startDate: '2026-07-01',
  endDate: '2026-07-15',
});

await approveLeave(client, req.id, 'Cobertura confirmada');
// or: await rejectLeave(client, req.id, 'Coincide con cierre fiscal');

Banking (exceptions + rules)

import {
  bankRuleSimulate,
  type BankException,
  type BankExceptionStatus,
  type BankRule,
  type CreateBankRuleParams,
} from '@frihet/sdk';

const draft: CreateBankRuleParams = {
  name: 'AWS hosting',
  priority: 100,
  isActive: true,
  conditions: [{ field: 'counterparty', operator: 'contains', value: 'AMAZON WEB' }],
  action: 'categorize_expense',
  actionConfig: { category: 'hosting' },
};
const { matched, sample } = await bankRuleSimulate(client, draft);

Period close

import { periodCloseStatus, type PeriodClose } from '@frihet/sdk';

const current = await periodCloseStatus(client);          // most recent close
const march = await periodCloseStatus(client, '2026-03'); // specific period

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, {
  // Optional: POST requests generate a UUID v4 automatically when omitted.
  // Supply your own to coordinate retries across separate process calls.
  idempotencyKey: 'unique-key-123',
  timeout: 60000,
});

Every POST receives one cryptographically strong Idempotency-Key per logical SDK call. The same key is reused across network, 429, and retryable 5xx attempts; separate calls receive separate keys. Blank explicit keys are treated as absent and replaced safely. PATCH and DELETE are not retried after a network error or 5xx, because the API does not currently protect those methods with an idempotency contract.

429 remains retryable for every method because Frihet applies rate limiting before route handlers execute, so a rate-limited request has produced no business side effect.

Features

• Full TypeScript types with autocompletion
• Automatic retry on rate limits (429), GET failures, and idempotency-protected POST failures
• Exponential backoff with configurable retries
• Automatic cryptographic idempotency keys for safe POST 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