codat-sdk

Production-grade TypeScript SDK for the Codat API — financial data connectivity for accounting, banking, and commerce platforms.

Installation

npm install codat-sdk zod

Quick Start

import { CodatClient } from "codat-sdk";

const client = new CodatClient({
  apiKey: process.env.CODAT_API_KEY!,
});

// List companies
const { results, totalResults } = await client.platform.companies.list();

// Stream all invoices (lazy pagination via AsyncGenerator)
for await (const invoice of client.accounting.invoices.iterate(companyId)) {
  console.log(invoice.status, invoice.amountDue);
}

// Create an invoice and poll for completion
const pushOp = await client.accounting.invoices.create(companyId, connectionId, {
  status: "Draft",
  issueDate: "2024-01-01",
  lineItems: [{ description: "Consulting", unitAmount: 1000, quantity: 1 }],
});

const completed = await client.platform.pushOperations.pollUntilDone(
  companyId,
  pushOp.pushOperationKey,
  { onPoll: (op) => console.log(op.status) },
);

API Namespaces

| Namespace | Description | | ------------------- | ---------------------------------------------------------------------------------------------- | | client.platform | Companies, connections, push operations, API keys, webhooks, data status, files | | client.accounting | Invoices, bills, customers, suppliers, accounts, bank accounts, payments, financial statements | | client.bankFeeds | Bank feed source accounts and transactions | | client.lending | Accounts receivable/payable, banking, financial statements, data integrity | | client.expenses | Expense sync, transactions, mapping options | | client.billPay | Bills, suppliers, and bill payments |

Webhooks

import { WebhookHandler, EventTypes, verifyOrThrow } from "codat-sdk/webhooks";

const handler = new WebhookHandler({ secret: process.env.CODAT_WEBHOOK_SECRET! });

handler.on(EventTypes.invoices.writeSuccessful, async (payload) => {
  await syncInvoice(payload.companyId!, payload.data);
});

handler.on(/^expenses\.sync\./, async (payload) => {
  await handleExpenseSync(payload);
});

// Next.js App Router
export const POST = createFetchHandler(handler);

// Express
app.post("/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
  await handler.handle(req.body.toString(), req.headers as Record<string, string>);
  res.sendStatus(200);
});

Configuration

const client = new CodatClient({
  apiKey: "your-api-key", // or CODAT_API_KEY env var
  baseUrl: "https://api.codat.io", // default
  maxRetries: 3, // default
  timeoutMs: 30_000, // default
  fetch: customFetch, // custom fetch implementation
});

Query Builder

import { QueryBuilder } from "codat-sdk";

const query = new QueryBuilder()
  .where("status", "=", "Open")
  .and("amountDue", ">", 0)
  .and("customerRef.companyName", "~", "Acme")
  .toString();
// => "status=Open&&amountDue>0&&customerRef.companyName~Acme"

const invoices = await client.accounting.invoices.list(companyId, { query });

Requirements

• Node.js 18+ (uses native fetch and Web Crypto API)
• TypeScript 5.0+