@organizze/api-client

Typed TypeScript client for the Organizze REST API v2. Handles HTTP Basic auth, the mandatory User-Agent, Link-header pagination, error normalization, and retries. Types are generated from the OpenAPI spec in this repo.

Usage

import { OrganizzeClient } from "@organizze/api-client";

const organizze = new OrganizzeClient({
  email: "[email protected]",
  apiKey: process.env.ORGANIZZE_API_KEY!,
  userAgent: "my-app/1.0 ([email protected])",
});

// List a page
const accounts = await organizze.accounts.list();

// Auto-paginate
for await (const tx of organizze.transactions.iterate({ startDate: "2026-01-01" })) {
  console.log(tx.description, tx.amount_cents);
}

// Create (write)
await organizze.transactions.create({
  description: "Mercado",
  date: "2026-01-02",
  amount_cents: -5000,
  account_id: accounts[0]!.id,
});

Errors

All errors extend OrganizzeError:

| Class | When | |---|---| | AuthError | 401 (bad credentials / missing User-Agent / inactive license) | | ReadOnlyKeyError (⊂ AuthError) | 403 (read-only API key on a write) | | NotFoundError | 404 | | ValidationError | 422 (and 400); exposes .errors field map | | RateLimitError | 429; exposes .retryAfter | | ApiError | other non-2xx (e.g. 5xx) | | NetworkError | request never reached the server |

429 and 5xx (and network failures) are retried automatically with exponential backoff (maxRetries, default 2).

Resources

accounts, creditCards (+ creditCards.invoices), transactions (+ iterate, occurrences), transfers, categories, budgets, balances, accountConnections, institutions, users, entities, status.