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+