# Backfill Documentation

> The accounting platform built for ambitious startups. An event-driven ledger, a powerful scripting runtime, and a dashboard that's actually yours. Pair it with whatever AI tool you already use.

Site: https://backfill.io/
Last built: 2026-06-01

---

# File structure

URL: https://backfill.io/docs/sdk/extensions/file-structure/

> The anatomy of a Backfill integration and how the platform finds what each file does.


Every Backfill integration is a TypeScript project with a fixed layout. Hooks, jobs, API routes, custom entities, and fields are discovered by file path. UI pages are referenced from the manifest.

## Required files

| File | Purpose |
|---|---|
| `backfill.config.ts` | Manifest. `defineExtension({...})` (or `defineConnector({...})`) as the default export. |
| `package.json` | Declare `@backfill-io/sdk` as a devDependency plus any browser-compatible runtime packages your scripts import. |
| `tsconfig.json` | TypeScript config — `strict: true`, `noEmit: true`. |
| `.backfillrc` | Local dev credentials. Gitignored. |
| `src/` | All script source. |

## What lives in `src/`

```
src/
├── hooks/<entity-kebab>/        Hooks for a given entity
│   ├── before-save.ts
│   ├── after-save.ts
│   └── recalculate.ts
├── jobs/                         Scheduled jobs
│   └── <name>.ts
├── api/                          HTTP routes
│   └── <path>.ts
├── entities/                     Custom entity definitions
│   └── <Name>.ts
├── fields/                       Field declarations for host entities
│   └── <EntityName>.ts
├── pages/                        UI pages and action handlers
│   └── <page>.tsx
└── lib/                          Shared helpers
    └── <Name>.ts 
```

Shared helpers usually live under `src/lib`. They are not registered on their
own, but any hook, job, route, page, entity, tab, panel, or action can import
them. The CLI bundles each executable entrypoint independently, so shared helper
code is duplicated per entrypoint in v1.

## Where each thing goes

| To do this… | Put a file at… | What it exports |
|---|---|---|
| React to an entity create / update | `src/hooks/<entity-kebab>/after-save.ts` | `export default async function (ctx) { ... }` |
| Modify or reject an entity write | `src/hooks/<entity-kebab>/before-save.ts` | `export default async function (ctx) { return { ... } }` |
| Contribute to draft calculation | `src/hooks/<entity-kebab>/recalculate.ts` | See [Hooks → Recalculate](../hooks/#recalculate) |
| Run on a schedule | `src/jobs/<name>.ts` | `export const schedule = "..."`, `export async function run() {...}` |
| Expose an HTTP endpoint | `src/api/<path>.ts` | `export const GET = async (ctx) => {...}` (or `POST`, `PUT`, `PATCH`, `DELETE`) |
| Define a custom entity | `src/entities/<PascalName>.ts` | `export default defineEntity({ name, fields })` |
| Define fields on a host entity | `src/fields/<EntityName>.ts` | `export const stripeCustomerId = defineEntityField({ key: "stripe_customer_id", ... })` or `defineLineField(...)` |
| Add a dashboard page | `src/pages/<name>.tsx` + entry in `pages[]` | A default-export render function |
| Add a tab / panel / action | A render `.tsx` + entry in `ui.{tabs,panels,actions}` | Same as a page render |

---

# Get started

URL: https://backfill.io/docs/sdk/get-started/

> Install the CLI, scaffold an extension, and ship your first hook.



---

# Install the CLI

URL: https://backfill.io/docs/sdk/get-started/install/

> Install @backfill-io/cli, point it at your workspace, ship.


The `@backfill-io/cli` package handles scaffolding, dev mode, and deploys. One install and you're set.

## Install

```sh
npm install -g @backfill-io/cli
```

Or with whatever package manager you prefer:

```sh
pnpm add -g @backfill-io/cli
yarn global add @backfill-io/cli
```

Verify:

```sh
backfill --version
```

## Point it at your workspace

The CLI reads its server URL and API token from a `.backfillrc` file. It walks **up** the directory tree to find one — so a single file at the root of your integrations monorepo covers every project under it.

```ini
# .backfillrc — DO NOT commit
server = https://api.backfill.io
token  = bf_...
```

Precedence (highest wins):

1. CLI flags: `--server`, `--token`
2. Env vars: `BACKFILL_SERVER`, `BACKFILL_TOKEN`
3. A `.backfillrc` in the project directory
4. A `.backfillrc` in any parent directory

Verify auth:

```sh
backfill auth
```

If something's off, the CLI exits non-zero and tells you exactly what.

## What you can do with it

| Command | What it does |
|---|---|
| `backfill init <name>` | Scaffold a new extension project. |
| `backfill build` | Validate the manifest and every script. No deploy, no network. |
| `backfill dev` | Watch your files. Auto-deploys a draft on save. |
| `backfill deploy` | Build, validate, upload, activate. `--observe` to dry-run against live traffic. |
| `backfill versions` | List deployed versions. |
| `backfill rollback --to <id>` | Roll back to a prior version. |
| `backfill logs [--follow]` | Stream extension logs. |
| `backfill trigger` | Manually fire a hook for testing. |
| `backfill promote` | Turn an `--observe` deployment into the live one. |
| `backfill job list` / `run <name>` | Inspect or kick off a scheduled job by hand. |
| `backfill auth` | Show or verify the active credentials. |

## Next

Five-minute first ship → [Quickstart](../quickstart/).


---

# Invoice

URL: https://backfill.io/docs/resources/invoice/



---

# Overview

URL: https://backfill.io/docs/sdk/connectors/overview/

> When to reach for defineConnector and what it gives you over a plain extension.


**Connectors** vs **extensions**:

- A **connector** (`defineConnector`) brings data in from an external provider — Stripe, Shopify, a bank, an OCR vendor. The platform handles streams, signed webhook ingestion, and canonical record emission.
- An **[extension](../extensions/)** (`defineExtension`) augments Backfill's behavior — computing tax, validating fields, adding dashboard pages, posting to Slack on status changes.

A connector is just an extension with extra connector-shaped manifest entries. Both share file layout, the standard library, and the deploy lifecycle.

## What changes

```typescript
import { defineConnector } from "@backfill-io/sdk";

export default defineConnector({
  key: "stripe",
  name: "Stripe",
  provider: "stripe",
  kind: "source",
  version: "0.2.0",
  permissions: { /* same shape as defineExtension */ },
  connection: {
    testConnection: { route: "/setup/test_connection", method: "POST" },
    setup: { webhookUrlTemplate: "...", instructions: "..." },
    settingsSchema: { /* JSON Schema */ },
  },
  webhooks: { endpoint: "/webhooks/stripe", auth: "stripe_signature" },
  streams: [
    { key: "events",    mode: "webhook" },
    { key: "customers", mode: "poll", schedule: "*/15 * * * *" },
    { key: "invoices",  mode: "poll", schedule: "*/15 * * * *" },
    /* ... */
  ],
});
```

## What you keep from `defineExtension`

- File/folder structure under `src/` — hooks, jobs, api routes, entities all live in the same places.
- The standard library globals: `Entity`, `Log`, `Http`, `Settings`, `Secrets`, `api`, and generated entity classes.
- Permissions, custom entities, UI pages, UI contributions.

## What's added

- **`connection`** — defines how a workspace admin sets the connector up (test connection route, setup instructions, settings schema).
- **`webhooks`** — declares a single signed webhook ingress endpoint with provider-specific signature verification.
- **`streams`** — the catalog of data streams this connector ingests (`poll` or `webhook` mode, with cron schedules for poll streams).
- **`provider`, `kind`** — identity. `kind: "source"` means data flows in; the platform plans for `"sink"` (outbound) and bidirectional kinds in future.

## What's added at runtime

Connector sync routes use a runtime global, **`ingest`**, that plain extensions don't get. It writes a normalized payload as a canonical entity, with idempotency keying and provenance:

```typescript
import { ingest } from "@backfill-io/sdk";

ingest.canonical("customer", customerCanonical(stripeCustomer), {
  stream: "customers",
  idempotencyKey: `stripe:customer:${stripeCustomer.id}`,
});
```

Detail in [Sync routes](../sync-routes/).

## When `defineExtension` is enough

If your integration only needs hooks and an admin settings UI, you don't need any of this. Plain extensions can call `Http`, write to entities, and run on schedules — they just don't get the connector-specific scaffolding for ingest, signed webhooks, or stream-level retries / checkpoints.


---

# Pages

URL: https://backfill.io/docs/sdk/extensions/ui/pages/

> Custom dashboard pages declared in backfill.config.ts and rendered with the SDK's JSX runtime.


UI pages are the only script type *not* discovered by filename — the platform needs metadata (id, title, route, kind, nav order) it can't read off the filesystem, so pages are declared in the manifest with a `render` path pointing at the `.tsx` source.

## Manifest declaration

```typescript
interface ExtensionPageConfig {
  id: string;
  title: string;
  path: string;
  render: string;
  kind?: 'page' | 'settings' | 'list' | 'dashboard' | 'detail';
  parentPage?: string;
  access?: { roles?: string[] };
  adminOnly?: boolean;
  nav?: { label: string; section?: string; order?: number };
}
```

A real example:

```typescript
pages: [
  {
    id: "nexus-addresses",
    title: "Nexus Addresses",
    path: "nexus-addresses",
    render: "src/pages/nexus-addresses.tsx",
    kind: "list",
    nav: { label: "Nexus Addresses", section: "Tax", order: 10 },
  },
  {
    id: "nexus-address-form",
    title: "Nexus Address",
    path: "nexus-address-form",
    render: "src/pages/nexus-address-form.tsx",
    kind: "detail",
    parentPage: "nexus-addresses",
  },
],
```

## Field reference

| Field | Effect |
|---|---|
| `id` | Unique within the extension. Used to reference the page from `ui.actions[].page`. |
| `title` | Browser title and page header. |
| `path` | URL segment under the extension's namespace. Cannot contain `..`. |
| `render` | Path to the `.tsx` render script. Discovery resolves it against compiled files. |
| `kind` | `"page"`, `"settings"`, `"list"`, `"dashboard"`, or `"detail"`. Affects layout and where the page surfaces. |
| `parentPage` | Required for `kind: "detail"`. References another page id in this extension, and Backfill renders the default back link. |
| `access.roles` | Restrict to users in specific roles. |
| `adminOnly` | Convenience: equivalent to `access: { roles: ["admin"] }`. Cannot combine with `access`. |
| `nav.label` | Sidebar label (defaults to no nav entry if omitted). |
| `nav.section` | Sidebar section grouping. Defaults to `"Extensions"`. |
| `nav.order` | Integer for sorting within the section. |

All fields are validated at deploy.

## Render script

Render scripts use the SDK's JSX runtime (`@backfill-io/sdk/jsx-runtime`) and component library (`@backfill-io/sdk/ui`):

```tsx
/** @jsxImportSource @backfill-io/sdk */
import { Page, Section, Card, Stat, Table } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default function NexusAddresses() {
  const rows = NexusAddress.query({ where: { active: true } });

  return (
    <Page title="Nexus Addresses">
      <Section>
        <Card>
          <Stat label="Active addresses" value={rows.length} />
        </Card>
      </Section>

      <Table
        rows={rows}
        columns={[
          { key: "nexusName", label: "Name" },
          { key: "state", label: "State" },
          { key: "city", label: "City" },
        ]}
      />
    </Page>
  );
}
```

## Available components

Full prop reference for every primitive: [Components](../components/).

Quick list — exported from `@backfill-io/sdk/ui`:

`Fragment`, `Page`, `Section`, `Stack`, `Grid`, `Card`, `Stat`, `Divider`, `Text`, `Badge`, `EmptyState`, `Toolbar`, `Button`, `Link`, `Table`, `Form`, `Field`, `HiddenInput`, `NumberInput`, `DateInput`, `DateTimeInput`, `TextInput`, `Textarea`, `Select`, `Checkbox`, `Toggle`, `SubmitButton`, `ResetButton`.

Each has a typed prop set. Passing an unsupported prop or a value of the wrong type throws at runtime.

## Render context

The platform invokes your render with a context object:

```typescript
interface ExtensionPageRenderContext {
  tenant: { id: string; slug?: string | null; name?: string | null };
  settings: Record<string, any>;
  page: {
    id: string;
    title: string;
    path: string;
    kind?: string | null;
    parentPageId?: string | null;
    params?: RouteParams;
  };
  routes?: ExtensionPageRoutesContext;
  actor?: { id?: string; email?: string; role?: string };
  extension?: { id?: string; versionId?: string; key?: string };
}
```

If your render takes no params, ignore it; otherwise:

```tsx
export default function NexusAddressForm(ctx: ExtensionPageRenderContext) {
  const id = ctx.page.params?.id;
  const existing = id ? NexusAddress.get(String(id)) : null;
  // ...
}
```

## Route helpers

Use `Routes.page(ctx, pageId, { query })` to link between pages in the same
extension. Use `Routes.entity(ctx, entityName, id)` to link to the canonical
Backfill detail page for a standard entity.

```tsx
import { Link, Routes } from "@backfill-io/sdk/ui";

<Link href={Routes.page(ctx, "nexus-address-form", { query: { id: row.id } })}>
  Edit
</Link>

<Link href={Routes.entity(ctx, "Invoice", invoiceId)}>
  Open invoice
</Link>
```

## Form actions

Forms post back to a separate handler script declared as a UI action — see [Contributions](../contributions/).

## What the render runs in

UI render scripts are not React components. The runtime walks the returned `BackfillElementNode` tree, validates props server-side, and produces the dashboard's UI. There's no `useState`, no client-side reactivity in the script — re-render happens by re-running the render with new params.


---

# Platform SDK

URL: https://backfill.io/docs/sdk/

> Build on Backfill in TypeScript. Two flavors — extensions for behavior, connectors for data ingest.


The SDK is split into two surfaces:

- **[Extensions](extensions/)** — `defineExtension(...)`. Hooks, jobs, API routes, custom entities, dashboard pages, UI tabs, action buttons. The default flavor; reach for it for anything that augments Backfill's existing behavior.
- **[Connectors](connectors/)** — `defineConnector(...)`. Third-party data integrations with first-class support for streams, signed webhooks, and the canonical ingest pipeline. Reach for it when your job is *bringing data in*.

Both share the same file/folder layout, the same standard-library globals, and the same deploy lifecycle. A connector is just an extension with extra connector-shaped manifest entries.

If you're new, start with [Get started](get-started/install/) and the [Quickstart](get-started/quickstart/), then read [Concepts](concepts/) end-to-end.



---

# Standard library

URL: https://backfill.io/docs/sdk/concepts/standard-library/

> The named exports from @backfill-io/sdk that every script imports.


Every script and declaration file uses the same small standard library, exported from `@backfill-io/sdk`.

| Export | What it does | Reference |
|---|---|---|
| `Entity` | Generic CRUD against any entity. | [Entities](../../extensions/entities/) |
| `Log` | Structured logging — `debug`, `info`, `warn`, `error`. | [Logging](../../extensions/logging/) |
| `Http` | Outbound HTTPS. URLs gated by `permissions.http`. | [Outbound HTTP](../../extensions/outbound-http/) |
| `Settings` | Read merged extension settings. | [Settings](../../extensions/settings/) |
| `Secrets` | Read/write encrypted secrets. | [Secrets](../../extensions/secrets/) |
| `api` | Helper for declaring API route handlers and building responses. | [API routes](../../extensions/api-routes/) |
| `OAuth` | Connector-only access to host-managed provider OAuth tokens and metadata. | [Connector OAuth](../../connectors/oauth/) |

```typescript
import { Entity, Log, Settings } from "@backfill-io/sdk";
```

The runtime also exposes these as globals — at deploy, `@backfill-io/sdk` imports are stripped and the same identifiers are injected onto `globalThis`. Either style runs identically; the docs use imports because they give you autocomplete, type-checking, and a clear edit-time signal of what each script depends on.

`@backfill-io/sdk` also exports declaration helpers — `defineExtension`, `defineConnector`, `defineEntity`, `defineEntityField`, `defineLineField` — used in the manifest and discovered declaration files. They return the declaration object for type-checking and build-time discovery; they are not runtime APIs. Each is documented alongside the file it belongs in: [configuration](../../extensions/configuration/), [connectors](../../connectors/overview/), [custom entities](../../extensions/custom-entities/), and [custom fields](../../extensions/custom-fields/).

## Entity classes

The SDK exports a typed class for each first-class entity, pre-bound to the type:

```
Invoice    Customer    Payment       Expense       SalesReceipt
Item       VendorBill  BillPayment   PurchaseOrder CreditMemo
Quote      SalesOrder  RefundReceipt VendorCredit  Account
Vendor     JournalEntry Deposit      BankTransfer
```

```typescript
import { Invoice } from "@backfill-io/sdk";
```

So instead of `Entity.query("Invoice", { ... })` you write `Invoice.query({ ... })`. Both work and read against the same data. Custom entities you declare via `defineEntity` get the same treatment — once the CLI regenerates types, they're importable by their PascalCase name.


---

# Build a tax extension

URL: https://backfill.io/docs/sdk/guides/build-a-tax-extension/

> A full extension that adds a sales-tax line to invoices and exposes a tax-summary endpoint and dashboard page.


A complete extension that exercises hooks, custom entities, jobs, API routes, and pages.

## Goal

- On invoice / sales-receipt save, compute and stamp a sales-tax line.
- Track each tax application as a `TaxRecord` custom entity.
- Track jurisdiction addresses as a `NexusAddress` custom entity, manageable from a UI page.
- Expose a `/tax-summary` API route for date-ranged reporting.
- Run a weekly job that summarizes the prior week.

## Manifest

```typescript
// backfill.config.ts
import { defineExtension } from "@backfill-io/sdk";

export default defineExtension({
  key: "backfill-extension-tax-calcs",
  name: "Tax Calculations",
  version: "1.1.0",
  permissions: {
    entities: {
      Invoice: ["read", "write"],
      SalesReceipt: ["read", "write"],
      NexusAddress: ["read", "write"],
    },
  },
  pages: [
    {
      id: "nexus-addresses",
      title: "Nexus Addresses",
      path: "nexus-addresses",
      render: "src/pages/nexus-addresses.tsx",
      kind: "list",
      nav: { label: "Nexus Addresses", section: "Tax", order: 10 },
    },
    {
      id: "nexus-address-form",
      title: "Nexus Address",
      path: "nexus-address-form",
      render: "src/pages/nexus-address-form.tsx",
      kind: "page",
    },
  ],
  ui: {
    actions: [
      {
        id: "save-nexus-address",
        label: "Save Nexus Address",
        page: "nexus-address-form",
        run: "src/pages/actions/save-nexus-address.ts",
      },
    ],
  },
  config: {
    taxRate: 8.25,
    taxLabel: "Sales Tax",
    enableTaxOnInvoices: true,
    enableTaxOnSalesReceipts: true,
  },
});
```

## Custom entities

```typescript
// src/entities/NexusAddress.ts
import { defineEntity } from "@backfill-io/sdk";

export default defineEntity({
  name: "NexusAddress",
  fields: {
    nexusName:  { type: "string", required: true },
    street:     { type: "string", required: true },
    city:       { type: "string", required: true },
    state:      { type: "string", required: true },
    postalCode: { type: "string", required: true },
    country:    { type: "string", default: "US" },
    active:     { type: "boolean", default: true },
  },
});
```

```typescript
// src/entities/TaxRecord.ts
import { defineEntity } from "@backfill-io/sdk";

export default defineEntity({
  name: "TaxRecord",
  fields: {
    entityType: { type: "string", required: true },
    entityId:   { type: "string", required: true },
    subtotal:   { type: "number", required: true },
    taxRate:    { type: "number", required: true },
    taxAmount:  { type: "number", required: true },
  },
});
```

## The before-save hook

```typescript
// src/hooks/invoice/before-save.ts
import { Settings, Log } from "@backfill-io/sdk";
import type { HookContext } from "@backfill-io/sdk";

export default async function (ctx: HookContext) {
  const settings = Settings.getAll();
  if (!settings.enableTaxOnInvoices) return null;

  const rate = settings.taxRate ?? 8.25;
  const label = settings.taxLabel ?? "Sales Tax";
  const lines: any[] = ctx.entity.line_items ?? [];

  const subtotal = lines
    .filter((li) => li.description !== label)
    .reduce((sum, li) => sum + (Number(li.amount) || 0), 0);
  if (subtotal <= 0) return null;

  const taxAmount = Math.round(subtotal * (rate / 100) * 100) / 100;
  const updatedLines = [
    ...lines.filter((li) => li.description !== label),
    { description: label, amount: taxAmount, quantity: 1 },
  ];
  const totalAmount = Math.round((subtotal + taxAmount) * 100) / 100;

  Log.info("Tax calculated for invoice", { subtotal, rate, taxAmount, totalAmount });

  return { line_items: updatedLines, total_amount: totalAmount };
}
```

A near-identical hook lives at `src/hooks/sales-receipt/before-save.ts`.

## The after-save hook

After save, persist a `TaxRecord` so we can summarize later:

```typescript
// src/hooks/invoice/after-save.ts
declare const TaxRecord: any;

import type { HookContext } from "@backfill-io/sdk";

export default async function (ctx: HookContext) {
  const lines: any[] = ctx.entity.line_items ?? [];
  const taxLine = lines.find((li) => li.description?.toLowerCase().includes("tax"));
  if (!taxLine) return;

  const subtotal = lines
    .filter((li) => li !== taxLine)
    .reduce((sum, li) => sum + (Number(li.amount) || 0), 0);

  TaxRecord.create({
    entityType: "Invoice",
    entityId: ctx.entity.id,
    subtotal,
    taxRate: 8.25,
    taxAmount: Number(taxLine.amount),
  });
}
```

## The summary API route

```typescript
// src/api/tax-summary.ts
declare const TaxRecord: any;

export const GET = async function (ctx: { searchParams: Record<string, string> }) {
  const { start, end } = ctx.searchParams;
  if (!start || !end) {
    return { __api_response: true, status: 400, body: { error: "Missing start/end" } };
  }
  const records = TaxRecord.query({
    where: { _created_at: { gte: start, lte: end } },
  });
  return { period: { start, end }, count: records.length };
};
```

## The weekly job

```typescript
// src/jobs/weekly-tax-report.ts
import { Log } from "@backfill-io/sdk";
declare const TaxRecord: any;

export const schedule = "0 8 * * 1";

export async function run() {
  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
  const startDate = weekAgo.toISOString().split("T")[0];
  const records: any[] = TaxRecord.query({
    where: { _created_at: { gte: startDate } },
  });
  const total = records.reduce((sum, r) => sum + r.taxAmount, 0);
  Log.info("Weekly tax report", { count: records.length, total });
}
```

## Nexus address pages

Three pieces wire up the admin UI: a list page, a form page, and an action handler that does the save.

### List page

```tsx
// src/pages/nexus-addresses.tsx
import {
  Page, Section, Stack, Card, Text, Badge,
  EmptyState, Toolbar, Link, Routes,
} from "@backfill-io/sdk/ui";
import type { ExtensionPageRenderContext } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default function render(ctx: ExtensionPageRenderContext) {
  const rows = NexusAddress.query({
    orderBy: [{ field: "nexusName", direction: "asc" }],
  });
  const newHref = Routes.page(ctx, "nexus-address-form");

  return (
    <Page
      title="Nexus Addresses"
      description="Jurisdictions where you have a tax nexus."
      toolbar={<Toolbar><Link href={newHref}>Add Nexus Address</Link></Toolbar>}
    >
      {rows.length === 0 ? (
        <Section>
          <EmptyState
            title="No nexus addresses yet"
            description="Add your first address to get started."
          />
        </Section>
      ) : (
        <Section>
          <Stack direction="column" gap="md">
            {rows.map((row: any) => (
              <Card key={row.id} title={row.nexusName}>
                <Stack direction="column" gap="sm">
                  <Text>{row.street}</Text>
                  <Text>{`${row.city}, ${row.state} ${row.postalCode}`}</Text>
                  <Text tone="muted">{row.country || "US"}</Text>
                  {row.active === false && <Badge tone="warning">Inactive</Badge>}
                  <Link href={Routes.page(ctx, "nexus-address-form", { query: { id: row.id } })}>
                    Edit
                  </Link>
                </Stack>
              </Card>
            ))}
          </Stack>
        </Section>
      )}
    </Page>
  );
}
```

`Routes.page(ctx, "<page-id>", { query })` builds a link to another page in this extension, with optional query params. That's how the list page hands a row id to the form page on edit.

### Form page

The same `nexus-address-form.tsx` file handles both create and edit — the difference is whether `?id=...` is in the URL. If it is, we load the existing record and pre-fill the fields.

```tsx
// src/pages/nexus-address-form.tsx
import {
  Page, Section, Stack, Grid, Form, Field,
  TextInput, Select, Checkbox, SubmitButton, Routes,
} from "@backfill-io/sdk/ui";
import type { ExtensionPageRenderContext, SelectOption } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

const COUNTRY_OPTIONS: SelectOption[] = [
  { value: "US", label: "United States" },
  { value: "CA", label: "Canada" },
  { value: "GB", label: "United Kingdom" },
  // …extend as needed
];

export default function render(ctx: ExtensionPageRenderContext) {
  const id = typeof ctx.page.params?.id === "string" ? ctx.page.params.id : undefined;
  const existing = id ? NexusAddress.get(id) : null;
  const isEdit = existing != null;
  const v = existing ?? {
    nexusName: "", street: "", city: "", state: "",
    postalCode: "", country: "US", active: true,
  };

  return (
    <Page title={isEdit ? "Edit Nexus Address" : "New Nexus Address"}>
      <Section>
        <Form action="save-nexus-address" cancelHref={Routes.page(ctx, "nexus-addresses")}>
          <Stack direction="column" gap="md">
            <Field name="nexusName" label="Nexus Name" required>
              <TextInput defaultValue={v.nexusName} placeholder="Company HQ" />
            </Field>
            <Field name="street" label="Street" required>
              <TextInput defaultValue={v.street} />
            </Field>
            <Grid columns={2} gap="md">
              <Field name="city" label="City" required>
                <TextInput defaultValue={v.city} />
              </Field>
              <Field name="state" label="State / Province" required>
                <TextInput defaultValue={v.state} />
              </Field>
              <Field name="postalCode" label="Postal Code" required>
                <TextInput defaultValue={v.postalCode} />
              </Field>
              <Field name="country" label="Country">
                <Select defaultValue={v.country ?? "US"} options={COUNTRY_OPTIONS} />
              </Field>
            </Grid>
            <Field name="active" label="Active">
              <Checkbox checked={v.active !== false} />
            </Field>
            <SubmitButton action="save-nexus-address">
              {isEdit ? "Save Changes" : "Create Nexus Address"}
            </SubmitButton>
          </Stack>
        </Form>
      </Section>
    </Page>
  );
}
```

`Form action="save-nexus-address"` references the action declared in `ui.actions` in the manifest. The runtime invokes the corresponding handler script with the form's values.

### Action handler

```typescript
// src/pages/actions/save-nexus-address.ts
import { redirect, validationError, Routes } from "@backfill-io/sdk/ui";
import type { ExtensionPageActionContext, UiActionFieldError } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default async function run(ctx: ExtensionPageActionContext) {
  const id = typeof ctx.page.params?.id === "string" ? ctx.page.params.id : undefined;
  const v = ctx.values ?? {};

  const attrs = {
    nexusName: String(v.nexusName ?? "").trim(),
    street: String(v.street ?? "").trim(),
    city: String(v.city ?? "").trim(),
    state: String(v.state ?? "").trim(),
    postalCode: String(v.postalCode ?? "").trim(),
    country: String(v.country ?? "").trim() || "US",
    // Checkbox may arrive as boolean true, "true", "on", or missing
    active: v.active === true || v.active === "true" || v.active === "on",
  };

  const errors: UiActionFieldError[] = [];
  if (!attrs.nexusName)  errors.push({ field: "nexusName",  message: "Nexus name is required." });
  if (!attrs.street)     errors.push({ field: "street",     message: "Street is required." });
  if (!attrs.city)       errors.push({ field: "city",       message: "City is required." });
  if (!attrs.state)      errors.push({ field: "state",      message: "State is required." });
  if (!attrs.postalCode) errors.push({ field: "postalCode", message: "Postal code is required." });

  if (errors.length > 0) {
    return validationError("Please correct the errors below.", errors);
  }

  if (id) {
    NexusAddress.update(id, attrs);
  } else {
    NexusAddress.create(attrs);
  }

  return redirect(
    Routes.page(ctx, "nexus-addresses"),
    id ? "Nexus address updated." : "Nexus address created.",
  );
}
```

Two things to note:

- `ctx.values` are strings (or arrays for multi-selects, or whatever the input emits). Coerce explicitly — checkboxes in particular can arrive as `true`, `"true"`, `"on"`, or missing.
- `validationError(message, fieldErrors)` re-renders the form with field-level error messages. `redirect(href, toast)` navigates and flashes a toast. Both come from `@backfill-io/sdk`.

## Deploy

```sh
pnpm tsc --noEmit
backfill build
backfill deploy
```

That's it.


---

# API Reference

URL: https://backfill.io/docs/api/

> Complete reference for the Backfill HTTP API. Generated from the live OpenAPI 3.1 spec.


The Backfill HTTP API. Every operation, request body, response shape, and example.


---

# Build a connector

URL: https://backfill.io/docs/sdk/guides/build-a-connector/

> A walkthrough using Stripe as the canonical example — manifest, settings schema, sync route, webhook handler.


Walk through the core files a real connector ships: manifest, field declarations, test-connection route, poll sync route, and webhook handler.

## 1. Manifest with `defineConnector`

```typescript
// backfill.config.ts
import { defineConnector } from "@backfill-io/sdk";

export default defineConnector({
  key: "stripe",
  name: "Stripe",
  provider: "stripe",
  kind: "source",
  version: "0.2.0",
  permissions: {
    http: ["https://api.stripe.com/*"],
    entities: {
      Customer: ["write"],
      Invoice: ["write"],
      Payment: ["write"],
      // ...the rest
    },
    secrets: {
      api_key: ["read"],
      webhook_secret: ["read"],
    },
  },
  connection: {
    testConnection: { route: "/setup/test_connection", method: "POST" },
    setup: {
      webhookUrlTemplate:
        "/api/v1/extensions/<tenant_id>/stripe/routes/webhooks/stripe?connection_id=<connection_id>",
      instructions:
        "Create a Stripe webhook endpoint forwarding accounting events to the generated URL, then paste the signing secret here.",
    },
    settingsSchema: {
      type: "object",
      required: ["api_key"],
      properties: {
        api_key: {
          type: "string", minLength: 1,
          title: "Secret API key",
          "x-secret": true,
          "x-placeholder": "sk_live_... or sk_test_...",
        },
        webhook_secret: {
          type: "string", minLength: 1,
          title: "Webhook signing secret",
          "x-secret": true,
          "x-placeholder": "whsec_...",
        },
      },
    },
  },
  webhooks: { endpoint: "/webhooks/stripe", auth: "stripe_signature" },
  streams: [
    { key: "events",    mode: "webhook" },
    { key: "customers", mode: "poll", schedule: "*/15 * * * *" },
    { key: "invoices",  mode: "poll", schedule: "*/15 * * * *" },
    { key: "payments",  mode: "poll", schedule: "*/15 * * * *" },
    { key: "payouts",   mode: "poll", schedule: "*/15 * * * *" },
  ],
  ui: {
    lineColumns: [
      {
        id: "stripe-tax-behavior",
        label: "Stripe tax",
        entity: "Invoice",
        lineCollection: "line_items",
        field: "stripe_tax_behavior",
        width: 140,
        order: 60,
        visibleWhen: { field: "source_system", equals: "stripe" },
      },
    ],
  },
});
```

See [Settings schema](../../connectors/settings-schema/), [Webhooks](../../connectors/webhooks/), [Streams](../../connectors/streams/), [Connection setup](../../connectors/connection-setup/) for the deeper dive on each block.

### API-key vs OAuth starter

Use one setup path in the first version of a connector:

```typescript
// API-key connector: declare the key in settingsSchema and read it with Secrets.get("api_key").
connection: {
  settingsSchema: {
    required: ["api_key"],
    properties: {
      api_key: { type: "string", "x-secret": true },
    },
  },
}
```

```typescript
// OAuth connector: declare connection.oauth and read provider tokens with OAuth.accessToken().
connection: {
  oauth: {
    type: "authorization_code",
    authorizationUrlTemplate: "https://provider.example.com/oauth/authorize",
    tokenUrlTemplate: "https://provider.example.com/oauth/token",
    scopes: ["orders.read"],
    client: { credentialKey: "provider_public_app" },
  },
  settingsSchema: { type: "object", required: [], properties: {} },
}
```

If the provider expects normal SaaS "Connect" behavior, use OAuth from day one. Do not ask admins to paste provider OAuth access tokens into secret fields. See [Build an OAuth connector](../build-an-oauth-connector/) for the OAuth-specific route and test pattern.

## 2. Field declarations

Stripe carries useful provider-specific IDs and classifications that should stay extension-owned. Declare those fields in `src/fields/Invoice.ts`; the CLI discovers the file and normalizes it into the deployment manifest.

```typescript
// src/fields/Invoice.ts
import { defineLineField } from "@backfill-io/sdk";

export const stripeBalanceTransactionId = defineLineField("line_items", {
  key: "stripe_balance_transaction_id",
  label: "Balance transaction",
  type: "string",
});

export const stripeTaxBehavior = defineLineField("line_items", {
  key: "stripe_tax_behavior",
  label: "Stripe tax behavior",
  type: "select",
  options: ["inclusive", "exclusive", "unspecified"],
});

export const stripeFeeAmount = defineLineField("line_items", {
  key: "stripe_fee_amount",
  label: "Stripe fee",
  type: "currency",
  currencyField: "currency",
});
```

The `ui.lineColumns[]` entry in `backfill.config.ts` references the field key `stripe_tax_behavior`.

## 3. The test-connection route

The dashboard calls this when an admin enters credentials.

```typescript
// src/api/setup/test_connection.ts
import { api, Http } from "@backfill-io/sdk";

export const config = { auth: "api_key" };

export const POST = api(async (request) => {
  const apiKey = request.body.api_key;
  const res = Http.get("https://api.stripe.com/v1/balance", {
    auth: { bearer: apiKey },
  });
  if (!res.ok) {
    return api.badRequest("Invalid API key", { status: res.status });
  }
  return api.json({ ok: true });
});
```

## 4. A poll sync route

```typescript
// src/api/sync/customers.ts
import { api, ingest } from "@backfill-io/sdk";

export const config = { auth: "api_key" };

export const POST = api(async (request) => {
  const stream = "customers";
  const apiKey = Secrets.get("api_key");
  if (!apiKey) return api.badRequest("Missing api_key");

  // Read cursor / page from request, fetch a page from Stripe,
  // and emit each customer:
  const res = Http.get("https://api.stripe.com/v1/customers?limit=100", {
    auth: { bearer: apiKey },
  });
  if (!res.ok) return api.error(`Stripe ${res.status}`, { status: 502 });

  const results = (res.body.data || []).map((c) =>
    ingest.canonical("customer", { customer_id: c.id, name: c.name }, {
      stream,
      idempotencyKey: `stripe:customer:${c.id}`,
    }),
  );
  return api.json({ stream, imported: results.length, hasMore: res.body.has_more });
});
```

The real connector uses `lib/stripe.ts` helpers for cursor management and pagination. See [Sync routes](../../connectors/sync-routes/) for the full pattern.

## 5. The webhook handler

```typescript
// src/api/webhooks/stripe.ts
import { api, ingest } from "@backfill-io/sdk";
// ...transforms imported from src/lib/transforms/webhooks.ts

export const config = { auth: "stripe_signature" };

export const POST = api(async (request) => {
  const event = request.body;
  // dispatch on event.type, transform to canonical, emit:
  ingest.canonical("payment", transformPayment(event), {
    stream: "payments",
    idempotencyKey: `stripe:event:${event.id}`,
  });
  return api.json({ ok: true }, { status: 202 });
});
```

The platform verifies the signature before invoking the handler — see [Webhooks](../../connectors/webhooks/).

## 6. Line annotations

Stripe invoice lines often carry provider-specific facts that are useful in the Backfill UI but should not become native accounting fields. Declare those with `defineLineField`, render them with read-only `ui.lineColumns[]`, and include declared line field keys directly in the canonical invoice payload.

```typescript
// src/api/sync/invoices.ts
import { api, ingest } from "@backfill-io/sdk";

export const config = { auth: "api_key" };

export const POST = api(async (request) => {
  const stripeInvoice = request.body;
  const payload = transformStripeInvoice(stripeInvoice);

  payload.line_items = (payload.line_items ?? []).map((line) => ({
    ...line,
    stripe_tax_behavior: line.metadata?.stripe_tax_behavior ?? "unspecified",
    stripe_balance_transaction_id: line.metadata?.balance_transaction_id,
    stripe_fee_amount: line.metadata?.stripe_fee_amount,
  }));

  const result = ingest.canonical("invoice", payload, {
    stream: "invoices",
    idempotencyKey: `stripe:invoice:${stripeInvoice.id}`,
  });

  return api.json(result);
});
```

Backfill splits the payload into native invoice fields, native line fields, and declared extension fields. The native document write and inline line field write are one logical operation: if a declared line field fails validation, the whole ingest fails. Line fields require stable `line_key` values on the canonical lines. Line fields are extension-owned and excluded from reports, exports, public API projections, MCP responses, and outbound sync payloads by default.

## 7. Route tests

Connector route modules can be tested locally with
`@backfill-io/sdk/testing`. The test runtime installs the SDK globals that
Backfill normally provides at runtime and captures provider HTTP, checkpoints,
logs, and canonical ingest calls.

```typescript
import assert from "node:assert/strict";
import test from "node:test";
import { connectorTestRuntime } from "@backfill-io/sdk/testing";

test("customers sync emits canonical customers", async () => {
  const runtime = connectorTestRuntime({
    secrets: { api_key: "sk_test_123" },
  });

  try {
    runtime.install();
    const { POST } = await import("../src/api/sync/customers");

    runtime.http.getOnce({
      status: 200,
      body: { data: [{ id: "cus_123", name: "Ada Lovelace" }] },
    });

    const response = await runtime.call(POST);

    assert.equal(response.status, 200);
    assert.equal(runtime.ingest.calls[0].documentType, "customer");
    assert.equal(runtime.ingest.calls[0].sourceId, "cus_123");
  } finally {
    runtime.restore();
  }
});
```

See [Connector testing](../../connectors/testing/) for mocked `Http`, `Secrets`,
`Settings`, `sync`, `ingest`, and partial failure examples.

## What's left as an exercise

- The transform layer (`src/lib/transforms/`) — provider-specific shape → canonical shape.
- Per-stream pagination state (the Stripe connector has `lib/stripe.ts` for cursor management).
- Per-event idempotency keying for events that explode into multiple emissions.

These are still moving targets. Read the Stripe connector source as the reference.


---

# Concepts

URL: https://backfill.io/docs/sdk/concepts/

> How extensions plug into Backfill — glossary, standard library, script types, events, and runtime.



---

# Configuration

URL: https://backfill.io/docs/sdk/extensions/configuration/

> Learn about backfill.config.ts permissions, settings defaults, page declarations, UI contributions.


The manifest is one file: `backfill.config.ts`. It's a TypeScript module whose default export is the result of `defineExtension({...})`. The platform reads and validates it before running any of your code.

Keep declarations that can grow large out of the manifest. Custom entities live in `src/entities/` and custom fields live in `src/fields/`. The CLI discovers those files and normalizes them into the deployment artifact.

## Minimum manifest

```typescript
import { defineExtension } from "@backfill-io/sdk";

export default defineExtension({
  key: "my-extension",
  name: "My Extension",
  version: "0.1.0",
  permissions: {
    entities: { Invoice: ["read", "write"] },
  },
});
```

`key` and `name` are required. `version` is recommended. Everything else is optional.

## All manifest fields

```typescript
defineExtension({
  key: string,            // unique extension key
  name: string,           // human display name
  version?: string,
  permissions?: {
    entities?: Record<EntityName, ("read" | "write")[]>,
    http?: string[],      // each must be an https URL with an explicit host
    secrets?: Record<SecretName, ("read" | "write")[]>,
  },
  config?: Record<string, any>,  // settings defaults — see Settings article
  pages?: ExtensionPageConfig[],
  ui?: {
    tabs?: UiTabConfig[],
    panels?: UiPanelConfig[],
    actions?: UiActionConfig[],
  },
});
```

## Permissions are enforced

If your code calls `Invoice.update(...)` and the manifest only granted `read`, the runtime rejects the write. Same for HTTP and secrets. There's no allow-by-default — anything not in the manifest is denied.

### entities

```typescript
permissions: {
  entities: {
    Invoice: ["read", "write"],
    Customer: ["read"],
    NexusAddress: ["read", "write"],   // also for custom entities you declare
  },
}
```

### http

```typescript
permissions: {
  http: ["https://api.stripe.com/*"],
}
```

- Must be `https://`. Plain HTTP is rejected.
- Must have an explicit host. `*` as the host is rejected.
- Path wildcards are fine.

### secrets

```typescript
permissions: {
  secrets: {
    stripe_api_key: ["read"],
    webhook_secret: ["read"],
  },
}
```

Names must match `^[a-z][a-z0-9_]{0,62}$`. See [Secrets](../secrets/).

## config

```typescript
config: {
  taxRate: 8.25,
  taxLabel: "Sales Tax",
  enableTaxOnInvoices: true,
}
```

`Settings.getAll()` at runtime returns the merged map of these defaults plus any overrides the workspace admin set in the dashboard.

## pages

Each entry registers an extension page. See [UI Pages](../ui/pages/).

```typescript
pages: [
  {
    id: "nexus-addresses",
    title: "Nexus Addresses",
    path: "nexus-addresses",
    render: "src/pages/nexus-addresses.tsx",
    kind: "list",
    nav: { label: "Nexus Addresses", section: "Tax", order: 10 },
  },
],
```

## ui: tabs, panels, actions

Contribute UI to existing entity pages. See [UI Contributions](../ui/contributions/).

```typescript
ui: {
  actions: [
    {
      id: "save-nexus-address",
      label: "Save Nexus Address",
      page: "nexus-address-form",
      run: "src/pages/actions/save-nexus-address.ts",
    },
  ],
}
```

---

# Contributions

URL: https://backfill.io/docs/sdk/extensions/ui/contributions/

> Tabs, panels, actions, and line columns added to existing entity or page surfaces.


`pages` adds full pages. `ui` contributes smaller surfaces: tabs and panels on existing entity pages, action buttons on entity headers and on your own pages, and read-only columns on host line tables.

## Contribution kinds

```typescript
interface UiConfig {
  tabs?: UiTabConfig[];          // adds a tab to an entity page
  panels?: UiPanelConfig[];      // adds a side panel to an entity page
  actions?: UiActionConfig[];    // adds a button (entity header or page toolbar)
  lineColumns?: UiLineColumnConfig[]; // adds a read-only host line-table column
}
```

## Tabs and panels

Tabs and panels share the same shape — they both render content inline on an entity page.

```typescript
interface UiRenderableConfig {
  id: string;
  label: string;
  entity: string;        // standard entity, or your custom entity name
  render: string;        // path to a .tsx render script
  icon?: string;
  order?: number;
  visibleWhen?: { field: string; equals?: any; in?: any[] };
}
```

Example:

```typescript
ui: {
  tabs: [
    {
      id: "stripe-charges",
      label: "Stripe charges",
      entity: "Invoice",
      render: "src/ui/invoice-stripe-charges.tsx",
      order: 50,
      visibleWhen: { field: "status", in: ["open", "paid"] },
    },
  ],
}
```

The render script receives a [`UiRenderContext`](../pages/#render-context) with an extra `record` field — the entity instance the tab is rendered for:

```tsx
import { Stack, Stat } from "@backfill-io/sdk/ui";

export default function StripeCharges({ record }) {
  const charges = StripeCharge.query({ where: { invoiceId: record.id } });
  return (
    <Stack>
      <Stat label="Charges" value={charges.length} />
      {/* table of charges */}
    </Stack>
  );
}
```

`visibleWhen` controls when the tab appears — equality (`equals`) or membership (`in`) on a field of the host entity.

## Line columns

Line columns render extension-owned line field values inside Backfill's host line table. The surface is deliberately narrow: every line-bearing canonical document (`Invoice`, `CreditMemo`, `SalesReceipt`, `RefundReceipt`, `VendorBill`, `Expense`, `PurchaseOrder`, `Quote`, `VendorCredit`, `SalesOrder`, and `Deposit`) on `line_items`, host-rendered read-only cells, and no arbitrary per-cell JSX.

Declare persisted fields in `src/fields/<EntityName>.ts`, then place them in the UI with `ui.lineColumns[]`:

```typescript
// src/fields/Invoice.ts
import { defineLineField } from "@backfill-io/sdk";

export const stripeTaxBehavior = defineLineField("line_items", {
  key: "stripe_tax_behavior",
  label: "Stripe tax behavior",
  type: "select",
  options: ["inclusive", "exclusive", "unspecified"],
});
```

```typescript
// backfill.config.ts
import { defineExtension } from "@backfill-io/sdk";

export default defineExtension({
  key: "stripe-reconciliation",
  name: "Stripe Reconciliation",
  version: "1.0.0",

  permissions: {
    entities: {
      Invoice: ["read", "write"],
    },
  },

  ui: {
    lineColumns: [
      {
        id: "stripe-tax-behavior",
        label: "Stripe tax",
        entity: "Invoice",
        lineCollection: "line_items",
        field: "stripe_tax_behavior",
        width: 140,
        align: "left",
        order: 60,
        visibleWhen: { field: "source_system", equals: "stripe" },
      },
    ],
  },
});
```

```typescript
interface UiLineColumnConfig {
  id: string;
  label: string;
  entity: "Invoice";
  lineCollection?: "line_items";
  field: string;        // references a defineLineField key
  width?: number;       // 64-320 px
  align?: "left" | "right" | "center";
  order?: number;
  visibleWhen?: {
    field: "source_system" | "source_id" | "document_type" | "document_number" | "customer_id" | "approval_status" | "payment_status" | "currency";
    equals?: string | number | boolean | null;
    notEquals?: string | number | boolean | null;
    in?: Array<string | number | boolean | null>;
    exists?: boolean;
  };
}
```

When you are already writing the invoice, include declared line field keys directly in the line payload:

```typescript
import { Invoice } from "@backfill-io/sdk";

Invoice.update(invoiceId, {
  line_items: [
    {
      line_key: "stripe:il_123",
      quantity: "2",
      stripe_tax_behavior: "exclusive",
    },
  ],
});
```

For field-only writes after the canonical document and stable line keys exist, use the generated line-collection namespace:

```typescript
import { Invoice } from "@backfill-io/sdk";

export default async function afterSave(ctx) {
  for (const line of ctx.entity.line_items ?? []) {
    if (!line.line_key) continue;

    Invoice.lineItems.fields.setAll(ctx.entity.id, line.line_key, {
      stripe_tax_behavior: line.metadata?.stripe_tax_behavior ?? "unspecified",
    });
  }
}
```

Do not write line fields from before-save hooks. Before-save runs before the canonical document version and persisted line rows exist, so Backfill cannot validate the target `line_key`.

Line fields are extension-owned. Backfill excludes them from core reports, company export, canonical API projections, MCP responses, and outbound connector sync payloads by default. Future API or export support must opt in explicitly and should expose values by immutable `extension_key`, not tenant-specific extension UUID.

## Actions

Actions are buttons that, when clicked, run a server-side handler and return a result (a redirect, a toast, validation errors).

```typescript
interface UiActionConfig {
  id: string;
  label: string;
  entity?: string;       // for entity-scoped actions (header buttons)
  page?: string;         // for page-scoped actions (form submits)
  run: string;           // path to a .ts handler
  icon?: string;
  order?: number;
  visibleWhen?: VisibilityCondition;
}
```

An action declares **either** `entity` (entity header action) **or** `page` (page-scoped action). Not both — deploy rejects mixing them.

### Page-scoped action (form submit)

The pattern:

```typescript
pages: [
  { id: "nexus-address-form", title: "Nexus Address", path: "nexus-address-form",
    render: "src/pages/nexus-address-form.tsx", kind: "page" },
],
ui: {
  actions: [
    {
      id: "save-nexus-address",
      label: "Save Nexus Address",
      page: "nexus-address-form",
      run: "src/pages/actions/save-nexus-address.ts",
    },
  ],
}
```

The form references the action by id; the handler runs server-side when submitted:

```typescript
// src/pages/actions/save-nexus-address.ts
import type { ExtensionPageActionContext } from "@backfill-io/sdk/ui";
import { redirect, validationError } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default async function (ctx: ExtensionPageActionContext) {
  const { values } = ctx;
  if (!values.nexusName) {
    return validationError("Name is required", [{ field: "nexusName", message: "Required" }]);
  }
  NexusAddress.create({ ...values });
  return redirect("/nexus-addresses", "Saved", "success");
}
```

For routed page actions, `ctx.page.params` contains the page route/query params,
`ctx.values` contains serialized form fields, and `ctx.action.params` contains
the params from the clicked `<Button>` or `<SubmitButton>`.

Helpers from `@backfill-io/sdk/ui`:

| Helper | Result shape |
|---|---|
| `ok(message?, opts)` | `{ ok: true, message?, level? }` |
| `message(text, level?)` | Toast at level `info`/`success`/`warning`/`error`. |
| `redirect(to, message?, level?)` | Navigate to `to` with optional toast. |
| `validationError(error, fieldErrors[])` | Per-field validation result. |

### Entity header action

```typescript
ui: {
  actions: [
    {
      id: "post-invoice",
      label: "Post invoice",
      entity: "Invoice",
      run: "src/ui/actions/post-invoice.ts",
      visibleWhen: { field: "status", equals: "open" },
    },
  ],
}
```

Entity actions appear in the entity's detail-page header. The handler receives a `UiActionContext` with the `record`.

## Slots

Discovery normalizes contributions into slots:

| Kind | Slot |
|---|---|
| Tab | `tabs` |
| Panel | `right_panels` |
| Action with `entity` | `header_actions` |
| Action with `page` | `page_actions` |
| Line column | `line_columns` |

These map onto where in the dashboard your contribution appears.

## Validation rules

- IDs must be non-empty and unique across all contributions in the extension.
- `entity` (when present) must be a known entity (standard or one you declared in `src/entities/`).
- `render` and `run` paths must resolve to a script the compiler picked up.
- `ui.lineColumns[].field` must reference a `defineLineField` key for the same entity and line collection.
- `ui.lineColumns[]` supports `line_items` on every line-bearing canonical document — `Invoice`, `CreditMemo`, `SalesReceipt`, `RefundReceipt`, `VendorBill`, `Expense`, `PurchaseOrder`, `Quote`, `VendorCredit`, `SalesOrder`, and `Deposit`.
- `order` must be an integer.
- `visibleWhen` must be an object (or omitted).

All enforced at deploy.


---

# Customer

URL: https://backfill.io/docs/resources/customer/



---

# Quickstart

URL: https://backfill.io/docs/sdk/get-started/quickstart/

> Scaffold an extension that auto-creates a Customer when an Invoice references one that doesn't exist. End-to-end in five minutes.


We'll build a real `before-save` hook that touches three entities — read a `Customer`, create one if missing, attach the resulting id to the `Invoice`. By the end you'll have used the SDK's `Entity` global for query, create, and update.

## 1. Scaffold

```sh
backfill init customer-autocreate
cd customer-autocreate
```

You get:

```
customer-autocreate/
├── backfill.config.ts
├── package.json
├── tsconfig.json
├── .backfillrc      # gitignored
└── src/
```

## 2. Manifest

```typescript
// backfill.config.ts
import { defineExtension } from "@backfill-io/sdk";

export default defineExtension({
  key: "customer-autocreate",
  name: "Customer Autocreate",
  version: "0.1.0",
  permissions: {
    entities: {
      Invoice:  ["read", "write"],
      Customer: ["read", "write"],
    },
  },
});
```

## 3. The hook

`src/hooks/invoice/before-save.ts`. The folder name maps to the entity (`invoice` → `Invoice`); the filename maps to the event (`before-save` → `before_save`). Default export, async function:

```typescript
// src/hooks/invoice/before-save.ts
import { Customer, Log } from "@backfill-io/sdk";
import type { HookContext } from "@backfill-io/sdk";

export default async function (ctx: HookContext) {
  const { customer_id, customer_name, billing_address } = ctx.entity;

  // Already linked to a real customer? Nothing to do.
  if (customer_id) return null;

  // Need at least a name to create one.
  if (!customer_name) return null;

  // Look for an existing customer by name.
  const matches = Customer.query({
    where: { name: customer_name },
    limit: 1,
  });

  if (matches.length > 0) {
    Log.info("Linked invoice to existing customer", {
      customerId: matches[0].id,
      customerName: customer_name,
    });
    return { customer_id: matches[0].id };
  }

  // Otherwise, create one.
  const created = Customer.create({
    name: customer_name,
    billing_address,
  });

  Log.info("Created customer for invoice", {
    customerId: created.id,
    customerName: customer_name,
  });

  return { customer_id: created.id };
}
```

What's happening:

- `Customer` is the typed entity class for the `Customer` entity — imported from `@backfill-io/sdk`, with the same shape as `Entity` but pre-bound so there's no first argument. `Invoice`, `Payment`, `Account`, etc. all work the same way.
- `query` returns an array. `create` returns the new record. Both are synchronous from your code's perspective.
- The handler returns the **changes** to merge into the invoice — here, just `customer_id`. Return `null` to leave the invoice alone.
- `Log.info` writes to `backfill logs --follow` and the dashboard's audit trail.

## 4. Type-check

```sh
npx tsc --noEmit
```

Catches typos in field names, wrong types, missing imports — everything before the platform sees your code.

## 5. Validate without deploying

```sh
backfill build
```

Runs the same discovery + validation the server runs. Common errors:

```
src/hooks/invoice/before-save.ts: unknown hook event 'beforesave'
src/hooks/invoiced/before-save.ts: unknown entity type 'Invoiced'
```

## 6. Develop with auto-redeploy

```sh
backfill dev
```

The CLI watches your files and pushes a draft on every save. Open `backfill logs --follow` in another terminal and create an invoice in the dashboard — your `Log.info` lines appear immediately.

## 7. Ship it

```sh
backfill deploy
```

Or, to dry-run against live traffic without committing writes:

```sh
backfill deploy --observe
backfill logs --follow
# happy?
backfill promote
```

## What's next

- [File structure](../../extensions/file-structure/) — the rest of the layout: jobs, routes, custom entities, pages.
- [Hooks](../../extensions/hooks/) — every event, every return contract, the recalculate hook.
- [Entities](../../extensions/entities/) — the full `Entity` API, including `update`, `delete`, `exists`, `count`, and `action`.


---

# Script types

URL: https://backfill.io/docs/sdk/concepts/script-types/

> Learn about hooks, jobs, API routes, entities, fields, pages and the file/folder rules the platform uses to find them.


Backfill extensions don't register handlers in code. The platform finds them by **filesystem convention**, similar to how Next.js finds pages. Every script's path determines its role.

| Type | Path | What registers it |
|---|---|---|
| **Hook** | `src/hooks/<entity-kebab>/<event>.ts` | Default export. Folder name → entity (kebab → PascalCase: `sales-receipt` → `SalesReceipt`). Filename → event. |
| **Job** | `src/jobs/<name>.ts` | Named exports `schedule` (cron string) and `run` (async function). |
| **API route** | `src/api/<path>.ts` | Named exports for HTTP verbs (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). URL = `/<path>`, including nested folders. |
| **Custom entity** | `src/entities/<Name>.ts` | Default export from `defineEntity({...})`. Name must be PascalCase. |
| **Fields** | `src/fields/<EntityName>.ts` | Named exports from `defineEntityField({...})` or `defineLineField(...)`. Filename supplies the host entity. |
| **UI page / contribution** | `src/ui` or any path you choose | Not auto-discovered — referenced explicitly from `backfill.config.ts` via `pages[].render` or `ui.{tabs,panels,actions}[].render`. |

Hooks, jobs, API routes, custom entities, and fields are auto-registered by their location. UI pages and contributions are declared in the manifest, because the platform needs metadata (id, title, route, kind, nav order) it can't read off the filesystem.

## What goes in the manifest vs. what's discovered

The manifest (`backfill.config.ts`) declares **metadata**: extension key, name, version, permissions, settings defaults, page list, UI contributions. It does **not** register hooks, jobs, routes, entities, or fields — those come from the file tree. Delete `src/hooks/invoice/before-save.ts` and the next deploy stops invoking that hook. There's no second place to clean up.

## Folder ↔ entity name mapping

Hook folder names convert kebab → PascalCase with no separator:

| Folder | Entity |
|---|---|
| `invoice/` | `Invoice` |
| `sales-receipt/` | `SalesReceipt` |
| `journal-entry/` | `JournalEntry` |

If the entity isn't a [standard one](/docs/sdk/concepts/standard-library/#entity-classes) and you haven't declared it via `defineEntity` in `src/entities/`, deploy fails:

```
src/hooks/foo/before-save.ts: unknown entity type 'Foo'
```

## Validation runs locally

`backfill build` and `backfill deploy` both run the same discovery checks before anything ships. You'll see errors like:

```
unknown hook event 'on-save'
route must export at least one HTTP method handler (e.g. export const POST = ...)
entity name 'invoice' must be PascalCase (e.g. RevenueSchedule)
```

Rename a file, re-run `backfill build`, see the verdict. There's no separate registration step — the file tree *is* the registration.


---

# Streams

URL: https://backfill.io/docs/sdk/connectors/streams/

> Declare what your connector ingests. Each stream has a key and a mode (poll or webhook).


A connector advertises its data streams up front. The platform uses the catalog to schedule polls, route webhooks, manage checkpoints, and surface stream health to operators.

## Declaring streams

```typescript
streams: [
  { key: "events",    mode: "webhook" },
  { key: "customers", mode: "poll", schedule: "*/15 * * * *" },
  { key: "invoices",  mode: "poll", schedule: "*/15 * * * *" },
  { key: "payouts",   mode: "poll", schedule: "*/15 * * * *" },
],
```

## Modes

| Mode | When the platform invokes you | Where the handler lives |
|---|---|---|
| `poll` | On the cron schedule. | `src/api/sync/<stream-key>.ts` (a route that reads `from` / `to` / cursor query params, fetches from the provider, and emits via `ingest.canonical`). |
| `webhook` | On every event posted to the configured webhook endpoint. | `src/api/webhooks/<provider>.ts` (a route that verifies the signature and emits via `ingest.canonical`). |

The `poll` and `backfill` mapping is enforced at build/deploy time. A stream
such as `{ key: "customers", mode: "poll" }` must have a matching
`POST src/api/sync/customers.ts` route. Webhook-mode streams do not need a sync
route, but `webhooks.endpoint` must point at an existing `POST` route with the
declared auth mode.

## Poll streams

Each `poll` stream has a `schedule` (cron). The platform invokes the corresponding sync route with paging metadata, and the handler is responsible for:

- Reading the saved cursor / page from the request.
- Calling the provider's API.
- Emitting each record via `ingest.canonical(...)`.
- Returning a response that includes the new cursor and a `hasMore` flag for pagination.

Stripe's customers sync is the canonical pattern — see [Sync routes](../sync-routes/).

## Webhook streams

A `webhook`-mode stream means the corresponding events arrive at the connector's webhook endpoint (declared in `webhooks: { endpoint, auth }`). The webhook handler dispatches to per-stream transforms; one webhook delivery may emit records into multiple streams.

```typescript
// after parsing event:
ingest.canonical(emission.canonicalType, emission.payload, {
  stream: emission.stream,                  // names the destination stream
  idempotencyKey: eventIdempotencyKey(/* ... */),
});
```

## Stream key conventions

- Lowercase + underscores: `customers`, `payout_reconciliation`, `balance_transactions`.
- One-to-one with the provider's logical resource name where possible.
- Webhooks for events that don't map to a single stream (e.g., a generic `events` topic) declare a stream named `events`.

## Why declare them at all

Operators need to see "this connector ingests these 12 things, on these cadences, with these last-success timestamps." The stream catalog makes that surfaceable in the dashboard without inferring from your route filenames.


---

# Build an OAuth connector

URL: https://backfill.io/docs/sdk/guides/build-an-oauth-connector/

> Create a connector that uses host-managed OAuth instead of API-key secrets.


This guide shows the minimum moving pieces for an OAuth connector:

- `connection.oauth` in `backfill.config.ts`
- a setup route that validates the connected provider account
- sync routes that read provider tokens through `OAuth.accessToken()`
- local tests that seed OAuth state with `connectorTestRuntime`

Use [Build a connector](../build-a-connector/) first if you have not built a connector before.

## 1. Choose API key or OAuth

Start with the provider's normal customer setup path:

```typescript
// API-key connector: keep credentials in connection.settingsSchema secrets.
permissions: {
  secrets: { api_key: ["read"] },
},
connection: {
  settingsSchema: {
    required: ["api_key"],
    properties: {
      api_key: { type: "string", "x-secret": true },
    },
  },
},
```

```typescript
// OAuth connector: declare connection.oauth and leave tokens to the host.
permissions: {
  secrets: { webhook_secret: ["read"] },
},
connection: {
  oauth: {
    type: "authorization_code",
    authorizationUrlTemplate: "https://provider.example.com/oauth/authorize",
    tokenUrlTemplate: "https://provider.example.com/oauth/token",
    scopes: ["orders.read"],
    client: { credentialKey: "provider_public_app" },
  },
  settingsSchema: {
    required: [],
    properties: {},
  },
},
```

Do not store OAuth access tokens, refresh tokens, or client secrets in connector-owned settings. The host stores tokens and OAuth app credentials separately.

## 2. Add the manifest

Shopify needs a tenant-specific authorization host, so the manifest uses a dynamic URL template and `hostValidation`.

```typescript
// backfill.config.ts
import { defineConnector } from "@backfill-io/sdk";

export default defineConnector({
  key: "shopify",
  name: "Shopify",
  provider: "shopify",
  kind: "source",
  version: "0.1.0",
  permissions: {
    http: ["https://*.myshopify.com/*"],
    entities: {
      Customer: ["write"],
      SalesReceipt: ["write"],
      RefundReceipt: ["write"],
    },
    secrets: {
      webhook_secret: ["read"],
    },
  },
  connection: {
    testConnection: { route: "/setup/test_connection", method: "POST" },
    oauth: {
      type: "authorization_code",
      authorizationUrlTemplate:
        "https://{settings.shop_domain}/admin/oauth/authorize",
      tokenUrlTemplate:
        "https://{settings.shop_domain}/admin/oauth/access_token",
      scopes: ["read_customers", "read_orders", "read_refunds"],
      accessType: "offline",
      pkce: false,
      requiredSettings: ["shop_domain"],
      client: {
        credentialKey: "shopify_public_app",
      },
      token: {
        accessTokenPath: "access_token",
        scopePath: "scope",
      },
      refresh: { enabled: false },
      postConnect: {
        route: "/setup/test_connection",
        method: "POST",
      },
      hostValidation: {
        shop_domain: {
          suffix: ".myshopify.com",
          normalize: "shopifyShopDomain",
        },
      },
    },
    settingsSchema: {
      type: "object",
      required: ["shop_domain"],
      properties: {
        shop_domain: {
          type: "string",
          title: "Shop domain",
          "x-placeholder": "acme.myshopify.com",
        },
        webhook_secret: {
          type: "string",
          title: "Webhook signing secret",
          "x-secret": true,
        },
      },
    },
  },
});
```

The host expands `{settings.shop_domain}` after validating and normalizing it. If the setting appears in the URL host, the manifest must include a `hostValidation` rule for that setting.

## 3. Validate the connection

`postConnect` should call a setup route that proves the token works and returns provider account metadata.

```typescript
// src/api/setup/test_connection.ts
import { OAuth, api, Http, Settings } from "@backfill-io/sdk";

export const config = { auth: "api_key" };

export const POST = api(async () => {
  const shopDomain = Settings.get("shop_domain");

  let accessToken: string;

  try {
    accessToken = OAuth.accessToken({ minTtlSeconds: 600 });
  } catch (error) {
    if (
      error &&
      typeof error === "object" &&
      (error as { code?: string }).code === "reauth_required"
    ) {
      return api.badRequest("Shopify OAuth connection is required");
    }

    throw error;
  }

  const response = Http.post(
    `https://${shopDomain}/admin/api/2026-04/graphql.json`,
    { query: "{ shop { id name myshopifyDomain } }" },
    {
      headers: {
        "X-Shopify-Access-Token": accessToken,
      },
    },
  );

  if (!response.ok) {
    return api.badRequest("Shopify rejected the OAuth token", {
      status: response.status,
    });
  }

  const shop = response.body.data.shop;

  return api.json({
    ok: true,
    providerAccountId: shop.id,
    providerAccountName: shop.name,
    providerAccountDomain: shop.myshopifyDomain,
  });
});
```

## 4. Use OAuth in sync routes

Keep token lookup in a small provider helper so every route handles reauth the same way.

```typescript
// src/lib/provider.ts
import { OAuth, api } from "@backfill-io/sdk";

export function providerAccessToken() {
  try {
    return OAuth.accessToken({ minTtlSeconds: 600 });
  } catch (error) {
    if (
      error &&
      typeof error === "object" &&
      (error as { code?: string }).code === "reauth_required"
    ) {
      return null;
    }

    throw error;
  }
}

export function missingProviderAccessResponse() {
  return api.error("OAuth connection is not authorized", { status: 401 });
}
```

```typescript
// src/api/sync/orders.ts
import { api, ingest } from "@backfill-io/sdk";
import {
  missingProviderAccessResponse,
  providerAccessToken,
} from "../../lib/provider";

export const config = { auth: "api_key" };

export const POST = api(async () => {
  const accessToken = providerAccessToken();

  if (!accessToken) {
    return missingProviderAccessResponse();
  }

  // Fetch one page, transform records, and emit canonical payloads.
  const payloads = [
    {
      receipt_id: "provider-order-123",
      customer_id: "provider-customer-123",
      total: "42.00",
      currency: "USD",
    },
  ];

  const result = ingest.batch("sales_receipt", payloads, {
    stream: "orders",
    continueOnError: true,
    idempotencyKey: (_payload, index) => `provider:order:${index}`,
  });

  return api.json(result);
});
```

For fixed-host providers that accept bearer tokens, the route can use the `auth.oauth` HTTP option:

```typescript
const response = Http.get("https://api.example.com/v1/orders", {
  auth: { oauth: { minTtlSeconds: 300 } },
});
```

## 5. Fixed-host provider example

OAuth connectors do not need dynamic hosts when the provider has one authorization domain. A Square-style manifest can use fixed URLs and refresh enabled:

```typescript
oauth: {
  type: "authorization_code",
  authorizationUrlTemplate: "https://connect.squareup.com/oauth2/authorize",
  tokenUrlTemplate: "https://connect.squareup.com/oauth2/token",
  scopes: ["PAYMENTS_READ", "ORDERS_READ", "CUSTOMERS_READ"],
  client: {
    credentialKey: "square_public_app",
  },
  refresh: { enabled: true },
  token: {
    accessTokenPath: "access_token",
    refreshTokenPath: "refresh_token",
    expiresInPath: "expires_in",
    scopePath: "scope",
  },
}
```

Because the URLs do not include `{settings.<name>}` in the host, this shape does not need `hostValidation`.

## 6. Test OAuth routes

Seed OAuth state in the test runtime. No live provider or browser flow is required for route tests.

```typescript
import assert from "node:assert/strict";
import test from "node:test";
import { connectorTestRuntime } from "@backfill-io/sdk/testing";

test("setup uses OAuth token", async () => {
  const runtime = connectorTestRuntime({
    settings: { shop_domain: "demo.myshopify.com" },
    connector: { key: "shopify", provider: "shopify" },
    oauth: {
      accessToken: "test_access_token",
      scopes: ["read_orders"],
      requiredScopes: ["read_orders"],
      provider: "shopify",
    },
  });

  try {
    runtime.install();
    const { POST } = await import("../src/api/setup/test_connection");

    runtime.http.postOnce({
      status: 200,
      body: {
        data: {
          shop: {
            id: "gid://shopify/Shop/1",
            name: "Demo Shop",
            myshopifyDomain: "demo.myshopify.com",
          },
        },
      },
    });

    const response = await runtime.call(POST);

    assert.equal(response.status, 200);
    assert.equal(
      runtime.http.calls[0].opts?.headers?.["X-Shopify-Access-Token"],
      "test_access_token",
    );
  } finally {
    runtime.restore();
  }
});
```

Add failure tests for missing tokens and missing scopes:

```typescript
const runtime = connectorTestRuntime({
  oauth: {
    accessToken: null,
    scopes: [],
    requiredScopes: ["read_orders"],
  },
});
```

## Release checklist

Before shipping an OAuth connector:

- the manifest validates with `connection.oauth`
- required settings are present before OAuth start
- dynamic URL hosts have `hostValidation`
- the Backfill host has a company OAuth app credential setup path, and the credential exists for `client.credentialKey`
- `postConnect` verifies provider account identity
- route tests cover connected, missing-token, missing-scope, provider-auth-failure, and refresh-failure cases
- logs and errors do not include access tokens, refresh tokens, or client secrets


---

# Resources

URL: https://backfill.io/docs/resources/

> Every canonical record in Backfill — fields, types, and SDK examples.


Backfill normalizes every connector's data into a small set of **canonical resources** — the same record shapes whether the source is QuickBooks, Stripe, a CSV upload, or a custom connector you wrote. This browser is the single source of truth for those shapes.

For each resource you'll find:

- **Attributes** — every field with its type, whether it's required, enum values, and nested object structure.
- **TypeScript SDK** — copy-paste examples for `create`, `get`, `query`, `update`, and `delete` using the [`@backfill-io/sdk`](../sdk/) entity classes.

Generated from the canonical contract definitions — when an attribute is added, removed, or renamed, this section regenerates.


---

# Components

URL: https://backfill.io/docs/sdk/extensions/ui/components/

> Props, types, and one quick example per component.


```tsx
import {
  Page, Section, Stack, Grid, Card, Toolbar, Fragment,
  Text, Stat, Divider, Badge, EmptyState, Table,
  Button, SubmitButton, ResetButton, Link,
  Form, Field, HiddenInput, NumberInput, DateInput, DateTimeInput,
  TextInput, Textarea, Select, Checkbox, Toggle,
} from "@backfill-io/sdk/ui";
```

Props are validated server-side. Passing an unknown prop, the wrong type, or omitting a required prop throws at render time.

## Layout

### `<Page>`

Top-level container for every render script. Renders title, optional description, optional host-header toolbar, and a children slot.

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | Required. Browser title and page header. |
| `description` | `string` | Subtitle below the page header. |
| `toolbar` | node | Slot for a `<Toolbar>` of header actions. |
| `children` | node | Page body. |

```tsx
<Page title="Reconciliation" description="Match Stripe charges to invoices.">
  <Section>...</Section>
</Page>
```

### `<Section>`

Visual grouping with optional title and description. Use multiple sections to break a page into named regions.

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | Optional section heading. |
| `description` | `string` | Subtitle below the heading. |
| `children` | node | Section body. |

```tsx
<Section title="Open invoices" description="Last 30 days.">
  <Table ... />
</Section>
```

### `<Stack>`

Flex container. Use for stacking children with consistent gaps.

| Prop | Type | Default |
|---|---|---|
| `direction` | `"row"` \| `"column"` | `"column"` |
| `gap` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` | `"md"` |
| `span` | `1` - `12` | Optional grid column span on medium screens and up. |
| `align` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` | Optional cross-axis alignment. |
| `justify` | `"start"` \| `"center"` \| `"end"` \| `"between"` | Optional main-axis distribution. |
| `self` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` | Optional alignment of this stack inside a parent grid. |
| `wrap` | `boolean` | Allow row children to wrap. |
| `children` | node | — |

```tsx
<Stack direction="row" gap="sm">
  <Badge tone="success">Live</Badge>
  <Text tone="muted">Synced 2 minutes ago</Text>
</Stack>
```

Use `justify="end"` and `self="center"` for row action groups in dense grids:

```tsx
<Stack direction="row" span={3} justify="end" self="center" gap="xs">
  <Button action="bump-hours">+.25</Button>
  <Button action="delete-entry" variant="dangerLink">Delete</Button>
</Stack>
```

### `<Grid>`

Fixed-column responsive grid.

| Prop | Type | Default |
|---|---|---|
| `columns` | `1` - `12` | `1` |
| `gap` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` | `"md"` |
| `children` | node | — |

```tsx
<Grid columns={3} gap="md">
  <Card><Stat label="Pending" value={pendingCount} /></Card>
  <Card><Stat label="Reconciled" value={doneCount} /></Card>
  <Card><Stat label="Errors" value={errorCount} /></Card>
</Grid>
```

### `<Card>`

Bordered container with optional title.

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | Card header. |
| `href` | `string` | Optional same-origin destination; makes the card container clickable. |
| `tone` | `"default"` \| `"subtle"` | Optional background/border treatment. |
| `density` | `"default"` \| `"compact"` | Optional tighter padding. |
| `children` | node | Card body. |

```tsx
<Card title="This month">
  <Stat label="Revenue" value="$12,400" />
</Card>
```

Use `href` when a repeated card should open a detail page. Nested buttons still
invoke their own actions.

```tsx
<Card href={Routes.page(ctx, "work-week-detail", { query: { id: week.id } })}>
  <Text>{week.customerName}</Text>
  <Button action="delete-week" variant="dangerLink" params={{ workWeekId: week.id }}>
    Delete Week
  </Button>
</Card>
```

Use `tone="subtle"` for lightweight form grouping without adding custom CSS:

```tsx
<Card tone="subtle" density="compact">
  <Form action="save-line">...</Form>
</Card>
```

### `<Toolbar>`

Container for action buttons, typically passed to `<Page toolbar={...}>`.

| Prop | Type |
|---|---|
| `children` | node |

```tsx
<Page
  title="Vendors"
  toolbar={<Toolbar><Link href="/vendors/new">New vendor</Link></Toolbar>}
>
  ...
</Page>
```

### `<Fragment>`

Render multiple children without a wrapping element. Returned implicitly when you write `<>...</>`.

```tsx
<Fragment>
  <Text>First line</Text>
  <Text>Second line</Text>
</Fragment>
```

## Display

### `<Text>`

Plain text with optional tone.

| Prop | Type | Default |
|---|---|---|
| `tone` | `"default"` \| `"muted"` | `"default"` |
| `children` | node | — |

```tsx
<Text tone="muted">No matches found.</Text>
```

### `<Stat>`

Big-number display. Both `label` and `value` accept strings, numbers, or booleans.

| Prop | Type | Notes |
|---|---|---|
| `label` | string \| number \| boolean | Required. |
| `value` | string \| number \| boolean | Required. |
| `tone` | `"default"` \| `"good"` \| `"bad"` \| `"warning"` \| `"neutral"` | Optional value color. |
| `children` | node | Optional caption beneath the value. |

```tsx
<Stat label="Outstanding AR" value="$48,210" tone="warning">
  <Text tone="muted">across 12 invoices</Text>
</Stat>
```

### `<Divider>`

Section separator with an optional centered label.

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | Optional. |

```tsx
<Divider label="Open tasks" />
```

### `<Badge>`

Small colored chip.

| Prop | Type | Default |
|---|---|---|
| `tone` | `"info"` \| `"success"` \| `"warning"` \| `"error"` \| `"neutral"` | `"neutral"` |
| `children` | node | — |

```tsx
<Badge tone="warning">Needs review</Badge>
```

### `<EmptyState>`

Placeholder for empty result sets.

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | Required. |
| `description` | `string` | Optional supporting copy. |

```tsx
{rows.length === 0
  ? <EmptyState title="No invoices yet" description="They'll show up once Stripe sends the first webhook." />
  : <Table rows={rows} columns={cols} />}
```

### `<Table>`

Tabular data. Pass an array of plain-object rows and a column descriptor.

| Prop | Type | Notes |
|---|---|---|
| `columns` | `TableColumn[]` | Required. |
| `rows` | `Record<string, unknown>[]` | Required. |

```typescript
type TableColumn = {
  key: string;                                // matches a key on each row
  label: string;
  align?: "start" | "center" | "end";
  cell?:
    | { kind: "badge"; tone?: BadgeTone }
    | { kind: "link"; hrefKey: string; labelKey?: string }
    | { kind: "action"; action: string; label?: string; labelKey?: string; params?: Record<string, string | number | boolean>; paramsKey?: string }
    | { kind: "money"; currency?: string; currencyKey?: string }
    | { kind: "date" };
};
```

```tsx
import { Customer } from "@backfill-io/sdk";

<Table
  rows={Customer.query({ limit: 50 })}
  columns={[
    { key: "name",   label: "Customer" },
    { key: "status", label: "Status", cell: { kind: "badge" } },
    { key: "balance", label: "Balance", align: "end", cell: { kind: "money", currency: "USD" } },
    { key: "href", label: "Open", cell: { kind: "link", hrefKey: "href", labelKey: "name" } },
    { key: "deleteLabel", label: "Actions", cell: { kind: "action", action: "delete-customer", params: { customerId: "id" } } },
  ]}
/>
```

## Interaction

### `<Button>`

Triggers a UI action declared in `ui.actions[]`. The `action` prop is the action's `id`.

| Prop | Type | Notes |
|---|---|---|
| `action` | `string` | Required. The action id. |
| `variant` | `"button"` \| `"link"` \| `"dangerLink"` | Optional visual treatment. Defaults to `"button"`. |
| `params` | `Record<string, string \| number \| boolean>` | Optional action-specific params, exposed as `ctx.action.params`. |
| `children` | node | Button label. |

```tsx
<Button action="delete-entry" variant="dangerLink" params={{ entryId: entry.id }}>Delete</Button>
```

For navigation, use [`<Link>`](#link). `<Button>` is for invoking server-side action handlers.

### `<SubmitButton>`

Submits the surrounding `<Form>`. Optionally invokes a different action than the form's default.

| Prop | Type | Notes |
|---|---|---|
| `action` | `string` | Optional override of the form's action id. |
| `params` | `Record<string, string \| number \| boolean>` | Optional action-specific params, exposed as `ctx.action.params`. |
| `children` | node | Button label. |

```tsx
<Form action="save-customer">
  <Field name="name" label="Name"><TextInput name="name" /></Field>
  <SubmitButton params={{ customerId: existing.id }}>Save</SubmitButton>
</Form>
```

### `<ResetButton>`

Resets the surrounding form to its initial values. No props beyond children.

```tsx
<ResetButton>Reset</ResetButton>
```

### `<Link>`

Navigation link to another URL — extension page, dashboard route, or external.

| Prop | Type | Notes |
|---|---|---|
| `href` | `string` | Required. |
| `variant` | `"link"` \| `"button"` \| `"primary"` | Optional visual treatment. |
| `mode` | `"link"` \| `"navigate"` \| `"patch"` | Optional navigation behavior. Defaults to plain browser navigation. |
| `children` | node | Link text. |

```tsx
<Link href="/nexus-addresses">Back to nexus addresses</Link>
```

Use `mode="patch"` for same-page query-param changes like tabs and filters. The
host renders this as a LiveView patch, so the URL and page content update without
a full browser reload.

```tsx
<Link
  href={Routes.page(ctx, "work-weeks", { query: { status: "closed" } })}
  mode="patch"
  variant="button"
>
  Closed
</Link>
```

Use `mode="navigate"` for same-origin page-to-page navigation when you want
LiveView navigation semantics. LiveView modes require a same-origin `href`;
external links must use the default `"link"` mode.

## Forms

### `<Form>`

Wraps form fields and binds them to a UI action handler.

| Prop | Type | Notes |
|---|---|---|
| `action` | `string` | Required. The action id to invoke on submit. |
| `cancelAction` | `string` | Optional cancel-action id. |
| `cancelHref` | `string` | Optional cancel link. |
| `autoSubmit` | `"input"` \| `"change"` | Optional. Invoke the form action automatically when a field emits that event. |
| `debounceMs` | `number` | Optional debounce for autosubmit. Defaults to `500` for `"input"` and `0` for `"change"`. |
| `children` | node | Field rows + submit button. |

```tsx
<Form action="save-vendor" cancelHref="/vendors">
  <Field name="name" label="Vendor name" required>
    <TextInput name="name" />
  </Field>
  <SubmitButton>Create</SubmitButton>
</Form>
```

Form fields are serialized into `ctx.values`. Button-specific `params` are not
merged into `ctx.values`; they are available at `ctx.action.params`, which keeps
route params, clicked-button params, and editable form values from colliding.

Use `autoSubmit="change"` for inline edit rows where a visible Save button would
be noise. The action can return `refresh()` to re-render the current page without
navigating.

```tsx
<Form action="update-time-entry" autoSubmit="change">
  <HiddenInput name="entryId" value={entry.id} />
  <Field name="hours" label="Hours">
    <NumberInput defaultValue={entry.hours} min={0} step={0.25} />
  </Field>
</Form>
```

### `<Field>`

Wraps a single input with a label, help text, and validation rules.

| Prop | Type | Notes |
|---|---|---|
| `name` | `string` | Required. Form field name (key in `ctx.values`). |
| `label` | `string` | Required. |
| `helpText` | `string` | Subtitle under the field. |
| `required` | `boolean` | Validate non-empty before invoking the action. |
| `minLength` | `number` | String length validation. |
| `maxLength` | `number` | String length validation. |
| `pattern` | `string` | Regex string the value must match. |
| `span` | `1` - `12` | Optional grid column span on medium screens and up. |
| `labelHidden` | `boolean` | Visually hide the label while keeping it available to assistive tech. |
| `children` | node | The input — `HiddenInput`, `NumberInput`, `DateInput`, `DateTimeInput`, `TextInput`, `Textarea`, `Select`, `Checkbox`, or `Toggle`. |

```tsx
<Field name="email" label="Email" required pattern="^[^@]+@[^@]+$" helpText="Used for invoices.">
  <TextInput name="email" type="email" />
</Field>
```

### `<HiddenInput>`

Hidden form value. Use this for form-scoped IDs that should submit without
rendering an editable field.

| Prop | Type | Notes |
|---|---|---|
| `name` | `string` | Required. Key in `ctx.values`. |
| `value` | string \| number \| boolean | Required. |

```tsx
<Form action="save-hours">
  <HiddenInput name="entryId" value={entry.id} />
  <SubmitButton>Save</SubmitButton>
</Form>
```

### `<NumberInput>`

Numeric input with browser number affordances.

| Prop | Type | Default |
|---|---|---|
| `defaultValue` | string \| number \| boolean | — |
| `min` | number | — |
| `max` | number | — |
| `step` | number | — |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<NumberInput defaultValue={1.25} min={0} step={0.25} />
```

### `<DateInput>`

Date input that submits ISO `YYYY-MM-DD` strings.

| Prop | Type | Default |
|---|---|---|
| `defaultValue` | `string` | — |
| `min` | `string` | — |
| `max` | `string` | — |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<DateInput defaultValue={weekStart} min={weekStart} max={weekEnd} />
```

### `<DateTimeInput>`

Datetime input that submits browser `datetime-local` strings.

| Prop | Type | Default |
|---|---|---|
| `defaultValue` | `string` | — |
| `min` | `string` | — |
| `max` | `string` | — |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<DateTimeInput defaultValue="2026-05-11T09:00" />
```

### `<TextInput>`

Single-line text input.

| Prop | Type | Default |
|---|---|---|
| `defaultValue` | string \| number \| boolean | — |
| `placeholder` | `string` | — |
| `type` | `"text"` \| `"number"` \| `"email"` \| `"url"` \| `"password"` | `"text"` |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<TextInput name="taxId" placeholder="GB123456789" />
```

### `<Textarea>`

Multi-line text input.

| Prop | Type | Default |
|---|---|---|
| `defaultValue` | `string` | — |
| `placeholder` | `string` | — |
| `rows` | `number` | platform default |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<Textarea name="notes" rows={4} placeholder="Internal notes…" />
```

### `<Select>`

Dropdown.

| Prop | Type | Notes |
|---|---|---|
| `defaultValue` | `string` | — |
| `options` | `SelectOption[]` | Required. `{ value, label }`. |
| `disabled` | `boolean` | `false` |

```tsx
<Select
  defaultValue="USD"
  options={[
    { value: "USD", label: "US Dollar" },
    { value: "EUR", label: "Euro" },
    { value: "GBP", label: "British Pound" },
  ]}
/>
```

### `<Checkbox>`

Boolean checkbox. Submitted as `"true"` / `"false"` in `ctx.values`.

| Prop | Type | Default |
|---|---|---|
| `checked` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<Field name="active" label="Active">
  <Checkbox checked={existing.active} />
</Field>
```

### `<Toggle>`

Switch-style boolean. Same submit shape as `<Checkbox>`.

| Prop | Type | Default |
|---|---|---|
| `checked` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |

```tsx
<Toggle checked={settings.notifications} />
```

## Action result helpers

Imported from the same module, used inside action handlers (not render scripts):

```typescript
import { ok, message, redirect, refresh, validationError } from "@backfill-io/sdk/ui";
```

| Helper | Returns |
|---|---|
| `ok(message?, opts?)` | Action succeeded. Optional toast. |
| `message(text, level?)` | Toast at level `"info"` / `"success"` / `"warning"` / `"error"`. |
| `redirect(href, message?, level?)` | Navigate to `href` with optional toast. |
| `refresh(message?, level?)` | Re-render the current extension page with optional toast. |
| `validationError(error, fieldErrors[])` | Per-field validation result. Each entry: `{ field, message }`. |

```typescript
import { Vendor } from "@backfill-io/sdk";
import { redirect, validationError } from "@backfill-io/sdk/ui";

export default async function saveVendor(ctx) {
  if (!ctx.values.name) {
    return validationError("Please fix the errors", [
      { field: "name", message: "Required" },
    ]);
  }
  Vendor.create({ name: ctx.values.name });
  return redirect("/vendors", "Vendor created", "success");
}
```

## Shared types

```typescript
type ScalarValue = string | number | boolean;

type TableColumn = {
  key: string;
  label: string;
  align?: "start" | "center" | "end";
  cell?:
    | { kind: "badge"; tone?: "info" | "success" | "warning" | "error" | "neutral" }
    | { kind: "link"; hrefKey: string; labelKey?: string }
    | { kind: "action"; action: string; label?: string; labelKey?: string; params?: Record<string, ScalarValue>; paramsKey?: string }
    | { kind: "money"; currency?: string; currencyKey?: string }
    | { kind: "date" };
};

type SelectOption = { value: string; label: string };
```


---

# Events

URL: https://backfill.io/docs/sdk/concepts/events/

> System hook events, what triggers them, and what your handler is expected to return.


Filenames use kebab case (`before-save.ts`); the underlying event name uses underscores (`before_save`). They're equivalent.

| Event | File | Triggered by | Return value |
|---|---|---|---|
| `before_save` | `before-save.ts` | Entity create / update, before commit. | An object of fields to change, merged into the entity. `null` to skip. Throw to reject the write. |
| `after_save` | `after-save.ts` | Entity create / update, after commit. | Ignored — side-effect only. |
| `before_post` | `before-post.ts` | The "post" workflow transition (e.g., posting an invoice to the ledger), before commit. | Throw to abort. |
| `after_post` | `after-post.ts` | Same workflow, after commit. | Ignored. |
| `before_delete` | `before-delete.ts` | Entity destroy, before commit. | Throw to abort. |
| `after_delete` | `after-delete.ts` | Entity destroy, after commit. | Ignored. |
| `before_approve` | `before-approve.ts` | Approval transition, before commit. | Throw to abort. |
| `after_approve` | `after-approve.ts` | Approval transition, after commit. | Ignored. |
| `recalculate` | `recalculate.ts` | Draft recalculation while a user edits — fires synchronously on changes. | Calculation components and warnings. See [Hooks → Recalculate](../../extensions/hooks/#recalculate). |

`before_post`, `before_approve`, and the matching `after_*` events only fire on entities whose workflow includes a post or approve transition (Invoice, Bill, JournalEntry, etc. — not all entities have these). If your hook isn't firing, that's the first thing to check.

## Hook context

Save hooks receive a `HookContext`:

```typescript
interface HookContext<T = any> {
  entity: T;             // entity AFTER the change (or proposed entity, in before-*)
  entityType: string;
  operation: 'create' | 'update' | 'delete';
  previous: T | null;    // entity before; null on create
  changes: string[];     // names of fields actually modified
}
```

`previous` is `null` on create. `changes` lists field names — useful for short-circuiting in `after_save`:

```typescript
if (!ctx.changes.includes("status")) return;
```

The recalculate hook's context is different — see [Hooks → Recalculate](../../extensions/hooks/#recalculate).


---

# Extensions

URL: https://backfill.io/docs/sdk/extensions/

> Anatomy of an extension — the manifest, file layout, and one article per global and script type.



---

# Hooks

URL: https://backfill.io/docs/sdk/extensions/hooks/

> React to entity lifecycle events with side effects, mutations, or rejected writes.


## File location

Hooks live at `src/hooks/<entity-kebab>/<event>.ts` and use a default export — drop the file in place and it's registered on the next deploy. The folder name converts kebab → PascalCase (`invoice/` → `Invoice`, `sales-receipt/` → `SalesReceipt`); the filename must be one of the nine valid [events](../../concepts/events/).

```typescript
// ✅
export default async function (ctx) { ... }

// ❌ won't be picked up — runtime looks for a default export, not a named one
export async function handler(ctx) { ... }
```

## Anatomy

```typescript
// src/hooks/invoice/before-save.ts
import { Settings, Log } from "@backfill-io/sdk";
import type { HookContext } from "@backfill-io/sdk";

export default async function (ctx: HookContext) {
  const settings = Settings.getAll();
  if (!settings.enableTaxOnInvoices) return null;

  const total = computeTax(ctx.entity);
  Log.info("Tax calculated", { total });

  return { line_items: updatedItems, total_amount: total };
}
```

## Hook context

```typescript
interface HookContext<T = any> {
  entity: T;             // entity AFTER the change (or proposed entity, in before-*)
  entityType: string;
  operation: 'create' | 'update' | 'delete';
  previous: T | null;    // entity before; null on create
  changes: string[];     // names of fields modified
}
```

Use `ctx.changes` to bail early when an `after_save` only cares about specific fields:

```typescript
if (!ctx.changes.includes("status")) return;
```

## Return contract by event

| Event | Return | Effect |
|---|---|---|
| `before-save` | An object of fields to change, or `null`. | Object is merged into the entity before commit. `null` means no changes. Throw to reject the write. |
| `after-save`, `after-post`, `after-delete`, `after-approve` | Anything (ignored). | Side-effect only. |
| `before-post`, `before-delete`, `before-approve` | Throw to abort the transition. | Returning normally lets it proceed. |
| `recalculate` | A `RecalculateResult`. | See below. |

## Folder name → entity

Folder name converts kebab → PascalCase:

| Folder | Entity |
|---|---|
| `invoice/` | `Invoice` |
| `sales-receipt/` | `SalesReceipt` |
| `journal-entry/` | `JournalEntry` |

If the entity isn't a [standard entity](../../concepts/standard-library/#entity-classes) and isn't declared via `defineEntity` in `src/entities/`, deploy fails with `unknown entity type 'X'`.

## Recalculate

Recalculate is different. Instead of returning changes or being side-effect-only, the hook returns *components* that the platform composes into the draft total:

```typescript
// src/hooks/invoice/recalculate.ts
import type { RecalculateContext, RecalculateResult } from "@backfill-io/sdk";

export default async function (ctx: RecalculateContext): Promise<RecalculateResult> {
  return {
    components: [
      {
        key: "tax",
        type: "tax",
        label: "Sales tax",
        amount: computeTax(ctx.calculation).toFixed(2),
        provider: "my-tax-engine",
      },
    ],
  };
}
```

## Shared helpers

Hook files can import extension-local helpers and browser-compatible npm packages. The CLI bundles each hook entrypoint before deploy, leaving `@backfill-io/sdk` external for the Backfill runtime and inlining relative modules such as `../../lib/tax` plus pure JavaScript packages such as `zod`, `dayjs`, or `lodash`.

Unsupported imports fail at build time: CSS, SVG, images, Node builtins such as `fs`/`net`/`tls`, native addons, dynamic `require`, dynamic `import`, and packages that require Node process-level globals. Shared helpers are bundled per hook in v1, so a helper used by multiple hooks is duplicated in each deployed hook bundle.


---

# Manage extensions and connectors

URL: https://backfill.io/docs/sdk/get-started/management/

> Install, configure, version, and monitor extensions and connectors from the Backfill dashboard.


The SDK is for building extensions. This article is for everything that comes after: installing them in a workspace, wiring up connections, granting permissions, rolling versions forward and back, and watching them run.

Most of what's below applies equally to extensions (`defineExtension`) and connectors (`defineConnector`). The differences are called out where they matter.

## Where this lives in the dashboard

Open your workspace and head to **Settings → Extensions**. You'll see two surfaces:

- **Installed** — the extensions and connectors active in this workspace, with their current version, recent activity, and a per-installation settings page.
- **Catalog** — anything available to install. First-party connectors (Stripe, Shopify, etc.) live here alongside any private extensions you've built and pushed to the workspace.

A workspace admin role is required for all install / uninstall / settings actions. Roles can be reviewed under **Settings → Members**.

## Installing an extension

1. From the catalog, click into the extension and review its **manifest summary**: the permissions it requests (entities, HTTP hosts, secrets), the pages it adds, the UI contributions it makes, and the version about to install.
2. Click **Install**. For an extension with no required settings, that's it — the new version is live.
3. For anything with required settings, the install drops you into a configuration form (see [Configuring](#configuring-an-extension-or-connector) below) before activation.

You can install the same extension key into multiple workspaces independently. Each install carries its own settings, secrets, version, and logs.

## Installing a connector

Connectors follow the same path with extra setup. After clicking **Install**:

1. **Fill in connection settings.** The dashboard renders a form from the connector's `connection.settingsSchema`. Required fields are marked; secret fields render as password inputs and route into the encrypted secret store automatically.
2. **Connect OAuth if required.** OAuth connectors show a **Connect** action after required pre-OAuth settings are present. Backfill handles the provider redirect, callback, token storage, refresh, and reauth state.
3. **Test the connection.** Click **Test connection**. The dashboard hits the connector's `testConnection` route with the credentials or host-managed OAuth connection. If it fails, the credentials don't save until you fix them.
4. **Wire up webhooks (if applicable).** For connectors with a `webhooks.endpoint`, the dashboard generates a per-installation URL — copy it into the provider's webhook configuration, paste their signing secret back into the form. Both halves are required for verified webhook delivery.
5. **Activate.** The connector starts polling its declared streams on schedule and accepts webhook deliveries immediately.

You can have multiple connections of the same connector running side by side — for example, a Stripe connector pointed at production and another pointed at a test account. Each connection is a separate row under **Installed**.

## Configuring an extension or connector

Each install has a **Settings** page with three tabs:

- **Settings** — the user-configurable knobs your extension exposed via `config` (or via `connection.settingsSchema` for connectors). Edit and save; changes take effect immediately, no redeploy.
- **Secrets** — encrypted credentials. Set, rotate, or revoke. Values are write-only — the dashboard never displays an existing secret's plaintext.
- **Permissions** — read-only summary of what the manifest requests. Permissions are baked into the manifest, so changing them requires a new version.

For connectors, the **Connection** tab adds: which streams are syncing, last successful poll per stream, webhook ingress health, and a re-test button.

## Versions and rollback

Every deploy of an extension produces an immutable version. From the install's **Versions** tab:

- **Active** — the version currently running.
- **History** — every version that has ever been deployed for this extension key, with timestamp and the developer who shipped it.
- **Roll back** — pick any prior version and make it active. The cutover is atomic; in-flight invocations finish on the previous version.

Two version states beyond plain "active":

- **Observation** — a version deployed with `backfill deploy --observe`. Hooks fire, logs flow, but writes are intercepted. Use this to validate a candidate against live traffic; you'll see all the work it *would* have done in the **Logs** tab. Promote it to live with **Promote** in the dashboard or `backfill promote` from the CLI.
- **Draft** — what `backfill dev` deploys behind the scenes. Auto-replaced on every save; not promoted to active. Drafts only fire for the developer's session.

## Permissions

The permissions an extension runs with are exactly what its manifest declares — no allow-by-default. The dashboard surfaces them at install time and on the **Permissions** tab post-install:

- **Entities** — which entity types the extension can read or write.
- **HTTP** — which `https://` hosts it can reach.
- **Secrets** — which secret names it can read or write.

A workspace admin can review these any time but cannot widen them — to grant additional access, the developer ships a new version with an updated manifest. The dashboard will surface the diff at upgrade time.

## Logs and monitoring

The **Logs** tab streams `Log.debug / info / warn / error` calls from every script in the extension. Filter by:

- Time range
- Log level
- Script type (hook / job / route / page action)
- Specific entity, event, route path, or job name

For connectors, the **Connections** tab shows per-stream sync status: last successful run, records ingested, current cursor, error counts, and webhook delivery rate. A stream stuck on its cursor or accumulating errors is the first signal something's wrong upstream.

Errors thrown from `before_save` and other transactional hooks surface to the *user* who triggered the originating write — they see the validation message immediately. Errors from async paths (jobs, webhook handlers, sync routes) only surface in **Logs**; build alerting on top by querying the API at `/v1/extensions/<key>/logs` or wiring up your own webhook destination.

## Disabling and uninstalling

Two ways to turn an extension off:

- **Disable** — the extension stays installed and configured, but stops firing hooks, jobs, and routes. Useful while debugging or when temporarily silencing a misbehaving connector. Re-enable to resume.
- **Uninstall** — removes the extension from the workspace entirely. Settings and secrets are deleted; custom entities the extension defined are *not* deleted (their data persists), but no new writes can target them until something is reinstalled with a matching `defineEntity`.

Disabling is reversible. Uninstalling drops the configuration; you'll need to re-enter settings if you reinstall later.


---

# Payment

URL: https://backfill.io/docs/resources/payment/



---

# Build a UI page

URL: https://backfill.io/docs/sdk/guides/build-a-ui-page/

> Add a custom page to the dashboard with form submission via a UI action.


Pages are declared in the manifest with a `render` script path; form submissions are handled by a separate UI action declared under `ui.actions`. This guide walks through the pattern using `basic-tax-calcs`'s nexus address form as the reference.

## 1. Declare in the manifest

```typescript
pages: [
  {
    id: "nexus-addresses",
    title: "Nexus Addresses",
    path: "nexus-addresses",
    render: "src/pages/nexus-addresses.tsx",
    kind: "list",
    nav: { label: "Nexus Addresses", section: "Tax", order: 10 },
  },
  {
    id: "nexus-address-form",
    title: "Nexus Address",
    path: "nexus-address-form",
    render: "src/pages/nexus-address-form.tsx",
    kind: "page",
  },
],
ui: {
  actions: [
    {
      id: "save-nexus-address",
      label: "Save",
      page: "nexus-address-form",
      run: "src/pages/actions/save-nexus-address.ts",
    },
  ],
},
```

## 2. The list page

```tsx
// src/pages/nexus-addresses.tsx
/** @jsxImportSource @backfill-io/sdk */
import { Page, Section, Toolbar, Link, Table, EmptyState } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default function NexusAddresses() {
  const rows = NexusAddress.query({ where: { active: true } });

  return (
    <Page title="Nexus Addresses" toolbar={<Toolbar><Link href="/nexus-address-form">Add</Link></Toolbar>}>
      

      {rows.length === 0 ? (
        <EmptyState title="No addresses yet" />
      ) : (
        <Table
          rows={rows}
          columns={[
            { key: "nexusName", label: "Name" },
            { key: "state", label: "State" },
            { key: "city", label: "City" },
            { key: "postalCode", label: "Postal code" },
          ]}
        />
      )}
    </Page>
  );
}
```

## 3. The form page

```tsx
// src/pages/nexus-address-form.tsx
/** @jsxImportSource @backfill-io/sdk */
import { Page, Form, Field, TextInput, SubmitButton } from "@backfill-io/sdk/ui";

export default function NexusAddressForm() {
  return (
    <Page title="New Nexus Address">
      <Form action="save-nexus-address">
        <Field name="nexusName" label="Name" required>
          <TextInput name="nexusName" />
        </Field>
        <Field name="street" label="Street" required>
          <TextInput name="street" />
        </Field>
        <Field name="city" label="City" required>
          <TextInput name="city" />
        </Field>
        <Field name="state" label="State" required>
          <TextInput name="state" />
        </Field>
        <Field name="postalCode" label="Postal code" required>
          <TextInput name="postalCode" />
        </Field>
        <SubmitButton>Save</SubmitButton>
      </Form>
    </Page>
  );
}
```

`Form action="save-nexus-address"` references the action by its id.

## 4. The action handler

```typescript
// src/pages/actions/save-nexus-address.ts
import type { ExtensionPageActionContext } from "@backfill-io/sdk/ui";
import { redirect, validationError } from "@backfill-io/sdk/ui";

declare const NexusAddress: any;

export default async function (ctx: ExtensionPageActionContext) {
  const v = ctx.values;
  const errs: { field: string; message: string }[] = [];
  if (!v.nexusName) errs.push({ field: "nexusName", message: "Name is required" });
  if (!v.street)   errs.push({ field: "street",   message: "Street is required" });
  if (errs.length) return validationError("Please fix the errors below", errs);

  NexusAddress.create({
    nexusName: v.nexusName,
    street: v.street,
    city: v.city,
    state: v.state,
    postalCode: v.postalCode,
  });

  return redirect("/nexus-addresses", "Saved", "success");
}
```

Helpers (`redirect`, `validationError`, `ok`, `message`) are in `@backfill-io/sdk/ui`.

## How submission flows

1. Admin clicks Submit. The dashboard collects form values.
2. The dashboard invokes the page's bound action handler server-side, passing values in `ctx.values`.
3. The handler returns one of: `validationError(...)` (re-render the form with errors), `redirect(...)` (navigate elsewhere with an optional toast), `ok(...)` / `message(...)` (toast in place), or `null`/`undefined` (no-op).

## Available components

Full prop reference: [Components](../../extensions/ui/components/). The render script must use only these primitives — passing unknown props or mismatched types throws at runtime.


---

# Webhooks

URL: https://backfill.io/docs/sdk/connectors/webhooks/

> Declare a signed webhook endpoint and verify it in the route handler.


Connectors that receive provider-emitted events declare a single webhook endpoint in the manifest. The platform mounts the endpoint, generates a per-installation URL the admin pastes into the provider's webhook config, and routes deliveries to your handler.

## Declaring the endpoint

```typescript
webhooks: {
  endpoint: "/webhooks/stripe",
  auth: "stripe_signature",
},
```

| Field | Effect |
|---|---|
| `endpoint` | URL path under the connector's namespace. Must correspond to a route file (`src/api/webhooks/stripe.ts` for the example). |
| `auth` | Signature scheme. Provider-specific (e.g. `"stripe_signature"`). |

> The set of supported signature schemes is provider-by-provider. Plain extensions are restricted to `auth: "api_key"` or `"public"`; webhook signature schemes are gated to connectors. Consult the platform team for what's wired up.

## The handler

```typescript
// src/api/webhooks/stripe.ts
import { api, ingest } from "@backfill-io/sdk";
import {
  STRIPE_EVENT_CATALOG,
  KNOWN_IGNORED_EVENT_TYPES,
  eventIdempotencyKey,
} from "../../lib/transforms/webhooks";

export const config = { auth: "stripe_signature" };

export const POST = api(async (request) => {
  const event = request.body || {};
  const object = event.data?.object || {};
  const catalogEntry = STRIPE_EVENT_CATALOG[event.type];

  if (!catalogEntry) {
    return api.json({
      ignored: true,
      known: KNOWN_IGNORED_EVENT_TYPES.includes(event.type),
      eventId: event.id || null,
      eventType: event.type || null,
    }, { status: 202 });
  }

  const emissions = catalogEntry.transform(event, object);
  const results = emissions.map((em, i) =>
    ingest.canonical(em.canonicalType, em.payload, {
      stream: em.stream,
      idempotencyKey: eventIdempotencyKey(event, em, i, emissions.length),
    }),
  );

  return api.json({ ok: true, eventId: event.id, results }, { status: 202 });
});
```

`import { ingest } from "@backfill-io/sdk"` is the connector pattern — `ingest` is provided to connector scripts at runtime.

## Signature verification

When `config.auth` is a signature scheme, the platform verifies the signature *before* invoking your handler. By the time `POST(request)` runs, the signature has been validated against the secret stored in the connection's settings (e.g., `webhook_secret`). If verification fails, the platform rejects the delivery with 401 and your handler never runs.

This is different from a plain extension's `auth: "public"` route, where verification is your responsibility entirely.

## Idempotency

Providers re-deliver. Your handler will see duplicates. Always pass an `idempotencyKey` to `ingest.canonical` derived from the provider's event ID (and emission index, if a single event splits into multiple records). The platform deduplicates based on the key.

```typescript
idempotencyKey: `stripe:event:${event.id}:${emissionIndex}`
```

## Status codes

Return `202 Accepted` for valid events you've processed (or chosen to ignore). Reserve `4xx` for deliveries you can't process at all (malformed payload, event types you've never heard of). The platform's webhook ingress retries on `5xx`.

## What you don't have to do

- Tenant resolution. The platform resolves tenant from the per-installation URL and binds your handler accordingly.
- Replay storage. Verified raw bodies are persisted by the platform for replay tooling.
- Retries from the ingest side — that's `ingest.canonical`'s job, with the idempotency key.


---

# Connection setup

URL: https://backfill.io/docs/sdk/connectors/connection-setup/

> testConnection, setup instructions, and webhook URL templates — the install flow for a connector.


A connector needs to tell the platform how to:

1. **Test** that an admin's credentials work.
2. **Walk** the admin through any provider-side setup (creating a webhook endpoint, generating an API key, etc.).
3. **Generate** a per-installation webhook URL the admin can paste into the provider.

These all live in the manifest's `connection` block.

For providers that expect OAuth, add `connection.oauth` and let the host manage redirects, callback state, token exchange, encrypted token storage, refresh, disconnect, and reauth status. See [OAuth](../oauth/) for the full contract.

## Shape

```typescript
connection: {
  testConnection: {
    route: "/setup/test_connection",
    method: "POST",
  },
  setup: {
    webhookUrlTemplate:
      "/api/v1/extensions/<tenant_id>/stripe/routes/webhooks/stripe?connection_id=<connection_id>",
    instructions:
      "Create a Stripe webhook endpoint that forwards must-have accounting events to the generated Backfill URL, then paste the Stripe webhook signing secret here.",
  },
  settingsSchema: { /* JSON Schema — see Settings schema */ },
},
```

## `testConnection`

Points at a route in your `src/api/` tree. The dashboard's setup screen calls this route after the admin enters credentials and clicks "Test connection". Return `200` if the credentials work, an explicit error response otherwise.

```typescript
// src/api/setup/test_connection.ts
import { api, Http } from "@backfill-io/sdk";

export const config = { auth: "api_key" };

export const POST = api(async (request) => {
  const apiKey = request.body.api_key;
  const res = Http.get("https://api.stripe.com/v1/balance", {
    auth: { bearer: apiKey },
  });
  if (!res.ok) {
    return api.badRequest("Invalid Stripe API key", { status: res.status });
  }
  return api.json({ ok: true, account: res.body.account_id });
});
```

The route is a normal API route — exactly the pattern in [API routes](../../extensions/api-routes/). The only thing special is that it's referenced from the connection block, which causes the dashboard to surface it during setup.

For OAuth connectors, the same route usually becomes the `postConnect` route. It should call `OAuth.accessToken()`, verify the provider account, and return stable provider metadata:

```typescript
connection: {
  testConnection: { route: "/setup/test_connection", method: "POST" },
  oauth: {
    type: "authorization_code",
    authorizationUrlTemplate: "https://provider.example.com/oauth/authorize",
    tokenUrlTemplate: "https://provider.example.com/oauth/token",
    scopes: ["orders.read"],
    client: { credentialKey: "provider_public_app" },
    postConnect: { route: "/setup/test_connection", method: "POST" },
  },
}
```

## `setup.webhookUrlTemplate`

A URL pattern with placeholder tokens that the platform expands at install time. The admin sees the *expanded* URL in the dashboard and pastes it into the provider's webhook configuration.

| Token | Replaced with |
|---|---|
| `<tenant_id>` | The installing workspace's tenant ID. |
| `<connection_id>` | The newly-created connection's ID. |

The expanded URL hits your connector's webhook endpoint — see [Webhooks](../webhooks/).

## `setup.instructions`

Free-form admin-facing copy explaining what they need to do on the provider side. Markdown is supported in the dashboard renderer (consult the platform team for the exact subset).

## Setup flow, end to end

1. Admin clicks "Install Stripe" in the connectors gallery.
2. Dashboard renders a form from `connection.settingsSchema` (see [Settings schema](../settings-schema/)).
3. Admin enters credentials. Clicks "Test connection". Dashboard POSTs to `connection.testConnection.route`.
4. On success: admin sees the expanded `setup.webhookUrlTemplate` plus `setup.instructions`. Pastes URL into provider, copies signing secret back into the form.
5. Dashboard saves the connection. Subsequent webhook deliveries are routed to the connector's webhook handler.

There's no secondary configuration step — once the connection exists, the connector is live.

## OAuth setup flow, end to end

1. Admin clicks "Install Shopify" in the connectors gallery.
2. Dashboard renders required pre-OAuth settings from `connection.settingsSchema`, such as `shop_domain`.
3. Admin clicks "Connect". The host starts OAuth using `connection.oauth`, creates one-time state, resolves the OAuth client credential, validates dynamic hosts, and redirects to the provider.
4. Provider redirects to Backfill's global connector OAuth callback.
5. The host verifies state, exchanges the code, stores tokens encrypted, and runs `connection.oauth.postConnect` if configured.
6. Dashboard shows connected provider account metadata, scopes, expiry, and reconnect/disconnect actions.
7. Sync routes use `OAuth.accessToken()` or `Http` with `auth: { oauth: true }`.

Do not ask users to paste OAuth access tokens into `settingsSchema`. Manual token fields are acceptable for local dogfood and route tests only.


---

# Connectors

URL: https://backfill.io/docs/sdk/connectors/

> Build third-party data integrations with defineConnector — streams, webhooks, and connection setup.


A connector is a special kind of extension whose primary job is pulling data from an external system (Stripe, Shopify, your bank's API) and emitting it as canonical Backfill entities. Connectors share the file/folder conventions of plain extensions but use a different manifest entry point — `defineConnector` — and a connector-specific runtime helper, `ingest`.

Read in order:

1. [Overview](overview/) — when to use `defineConnector` vs `defineExtension`.
2. [Streams](streams/) — `poll` vs `webhook` modes, scheduling, checkpoints.
3. [Webhooks](webhooks/) — receiving events from the source system.
4. [Connection setup](connection-setup/) — `testConnection`, setup instructions, webhook URL templates.
5. [OAuth](oauth/) — host-managed authorization-code flows, runtime tokens, and OAuth test fixtures.
6. [Settings schema](settings-schema/) — JSON-Schema-driven connection configuration with secret fields.
7. [Sync routes](sync-routes/) — the `src/api/sync/<stream>.ts` contract and `ingest.canonical`.
8. [Testing](testing/) — local route tests with `@backfill-io/sdk/testing`.


---

# Entities

URL: https://backfill.io/docs/sdk/extensions/entities/

> CRUD against the platform's entities — Invoice, Customer, Payment, and the rest.


The generic `Entity` class plus per-entity classes (`Invoice`, `Customer`, `Payment`, …) are how scripts read and write data. All are exported from `@backfill-io/sdk`. Both shapes hit the same data — the per-entity version is shorter and type-aware.

```typescript
import { Entity, Invoice, Customer } from "@backfill-io/sdk";
```

The examples below assume these imports.

## The interface

```typescript
interface EntityClass<TRecord, TCreateInput, TUpdateInput> {
  get(id: string, opts?: { include?: string[] }): TRecord | null;
  query(opts?: EntityQueryOptions<TRecord>): TRecord[];
  create(attrs: TCreateInput): TRecord;
  update(id: string, attrs: TUpdateInput): TRecord;
  delete(id: string): boolean;
  exists(where?: Record<string, any>): boolean;
  count(where?: Record<string, any>): number;
  action(id: string, actionName: string, params?: Record<string, any>): any;
}

interface EntityQueryOptions<TRecord> {
  where?: Partial<TRecord> | Record<string, any>;
  orderBy?: Array<{ field: string; direction: "asc" | "desc" }>;
  limit?: number;
  offset?: number;
  include?: string[];
}
```

## Generic vs. shortcut

```typescript
// generic
const inv = Entity.get("Invoice", "inv_123");
const recents = Entity.query("Invoice", { where: { status: "open" }, limit: 50 });

// per-entity — same data, less typing
const inv2 = Invoice.get("inv_123");
const recents2 = Invoice.query({ where: { status: "open" }, limit: 50 });
```

Custom entities you declare via [`defineEntity`](../custom-entities/) get the same treatment — once the CLI regenerates types, they're importable by their PascalCase name.

## Reads

### `get`

```typescript
const inv = Invoice.get("inv_123");
// → InvoiceRecord | null

const withCustomer = Invoice.get("inv_123", { include: ["customer"] });
```

### `query`

```typescript
const open = Invoice.query({
  where: { status: "open" },
  orderBy: [{ field: "issued_at", direction: "desc" }],
  limit: 50,
});
```

`where` accepts simple equality. Range filters use system fields with operators:

```typescript
const recent = TaxRecord.query({
  where: { _created_at: { gte: "2026-04-01" } },
});
```

### `exists`, `count`

```typescript
if (!Customer.exists({ email: input.email })) {
  Customer.create({ email: input.email, name: input.name });
}
const total = Invoice.count({ status: "open" });
```

## Writes

### `create`

```typescript
const inv = Invoice.create({
  customer_id: "cus_123",
  currency: "USD",
  lines: [
    { description: "Consulting", amount: "1000.00", line_type: "service" },
  ],
});
```

Required fields differ per entity — your editor's TypeScript inference will tell you what `create` accepts. For custom entities, the `required: true` flags in `defineEntity` apply.

### `update`

```typescript
Invoice.update("inv_123", { status: "paid" });
```

### `delete`

```typescript
Invoice.delete("inv_123");
// → true if it existed
```

## Actions

`action` invokes an entity-specific operation that's not a plain CRUD verb — for example, posting an invoice to the ledger.

```typescript
Invoice.action("inv_123", "post", { effective_date: "2026-05-01" });
```

The set of actions varies by entity.

## Permissions

Every `Entity.*` call checks the manifest's `permissions.entities`. With:

```typescript
permissions: { entities: { Invoice: ["read"] } }
```

`Invoice.query(...)` works. `Invoice.update(...)` throws. Add `"write"` to permit writes.


---

# Expense

URL: https://backfill.io/docs/resources/expense/



---

# Sandbox & runtime

URL: https://backfill.io/docs/sdk/concepts/sandbox-and-runtime/

> Learn how extension code executes including what's allowed, what's stripped, and what's enforced by the sandbox.


Extension scripts run in a JavaScript sandbox. Each invocation gets a fresh evaluation context with the standard library injected and the manifest's permissions enforced.

## What's allowed

- Plain JS/TS — async/await, classes, generators, regex, etc.
- The standard library: `Entity`, `Log`, `Http`, `Settings`, `Secrets`, `api`, plus per-entity classes (`Invoice`, `Customer`, etc) and any custom entities you declare. All exported from `@backfill-io/sdk`, and also exposed as globals at runtime.
- SDK imports from `@backfill-io/sdk` and subpaths like `@backfill-io/sdk/ui`.
- Relative helpers and browser-compatible npm packages that can be bundled at build time.

## What's stripped at deploy

The CLI bundles each executable entrypoint before upload. Relative helpers and pure JavaScript package dependencies are inlined into that entrypoint bundle. `@backfill-io/sdk` imports are left external, then stripped by the server before execution. At runtime, the SDK identifiers live as globals, not as imports.

```typescript
import { Log } from "@backfill-io/sdk";   // edit-time only
Log.info("hello");                     // runtime: Log is a global
```

## What's rejected

Imports that cannot be bundled or cannot run in the sandbox fail during `backfill build`:

```
src/hooks/invoice/after-save.ts: Unsupported import "../../assets/logo.svg" —
v1 extension bundles support .ts, .tsx, .js, and .json modules only
```

So no CSS, SVG, images, `node:fs`, `node:crypto`, native addons, dynamic `require`, dynamic `import`, or packages that depend on Node process-level globals.

## What's gated by permissions

`backfill.config.ts` declares three permission categories. Calls that exceed them are blocked at runtime.

```typescript
permissions: {
  entities: { Invoice: ["read", "write"], Customer: ["read"] },
  http: ["https://api.stripe.com/*"],
  secrets: { stripe_api_key: ["read"] },
}
```

- **Entities**: `"read"` and `"write"`. Other verbs rejected at deploy.
- **HTTP**: each entry must be `https://` with an explicit host. Path wildcards yes; host wildcards no.
- **Secrets**: names match `^[a-z][a-z0-9_]{0,62}$`.

## Observation mode

```sh
backfill deploy --observe
```

Deploys a version that runs against live traffic *without committing writes*. Hooks fire. `Log` calls flow normally. `Entity.create` and `Entity.update` are intercepted and recorded but not persisted. Use this to validate a new version before you cut over:

```sh
backfill deploy --observe
backfill logs --follow
# Satisfied? Promote it
backfill promote
```

## Local validation

`backfill build` runs the same manifest extraction, file-type discovery, hook event whitelist, route auth check, entity field-type check, and import validator the server runs. You see all the same errors locally before anything goes near the network.


---

# OAuth

URL: https://backfill.io/docs/sdk/connectors/oauth/

> Declare connector OAuth, use host-managed tokens at runtime, and test OAuth routes locally.


Use `connection.oauth` when the provider expects an authorization-code flow. Backfill owns state, callback handling, token exchange, encrypted token storage, refresh, disconnect, and reauth status. Connector code declares what it needs and receives a runtime token API.

API-key connectors should keep using `connection.settingsSchema` secrets and `Secrets.get(...)`. Do not build a custom OAuth redirect route inside a connector.

## Manifest

```typescript
// backfill.config.ts
import { defineConnector } from "@backfill-io/sdk";

export default defineConnector({
  key: "shopify",
  name: "Shopify",
  provider: "shopify",
  kind: "source",
  permissions: {
    http: ["https://*.myshopify.com/*"],
    entities: {
      Customer: ["write"],
      Item: ["write"],
      SalesReceipt: ["write"],
      RefundReceipt: ["write"],
    },
    secrets: {
      webhook_secret: ["read"],
    },
  },
  connection: {
    testConnection: { route: "/setup/test_connection", method: "POST" },
    oauth: {
      type: "authorization_code",
      authorizationUrlTemplate:
        "https://{settings.shop_domain}/admin/oauth/authorize",
      tokenUrlTemplate:
        "https://{settings.shop_domain}/admin/oauth/access_token",
      scopes: [
        "read_customers",
        "read_products",
        "read_orders",
        "read_refunds",
      ],
      accessType: "offline",
      pkce: false,
      requiredSettings: ["shop_domain"],
      client: {
        credentialKey: "shopify_public_app",
      },
      token: {
        accessTokenPath: "access_token",
        scopePath: "scope",
      },
      refresh: { enabled: false },
      postConnect: {
        route: "/setup/test_connection",
        method: "POST",
      },
      hostValidation: {
        shop_domain: {
          suffix: ".myshopify.com",
          normalize: "shopifyShopDomain",
        },
      },
    },
    setup: {
      instructions:
        "Connect Shopify with OAuth, then configure the generated webhook URL in Shopify.",
    },
    settingsSchema: {
      type: "object",
      required: ["shop_domain"],
      properties: {
        shop_domain: {
          type: "string",
          title: "Shop domain",
          "x-placeholder": "acme.myshopify.com",
        },
        webhook_secret: {
          type: "string",
          title: "Webhook signing secret",
          "x-secret": true,
        },
      },
    },
  },
});
```

## Manifest fields

| Field | Use |
|---|---|
| `type` | Currently `authorization_code`. |
| `authorizationUrlTemplate` | Provider authorization URL. Supports `{settings.<name>}` placeholders. |
| `tokenUrlTemplate` | Provider token exchange and refresh URL. Supports `{settings.<name>}` placeholders. |
| `scopes` | Required provider scopes. The host blocks OAuth starts if the selected client credential does not allow every requested scope. |
| `scopeSeparator` | Optional scope joiner. Defaults to provider/runtime behavior. Use `" "` or `","` when the provider requires it. |
| `accessType` | Optional provider hint such as `"offline"` or `"online"`. |
| `pkce` | Set true for providers that require PKCE. |
| `requiredSettings` | Settings that must exist before the Connect button can start OAuth. |
| `additionalAuthorizeParams` | Static provider parameters added to the authorization request. |
| `additionalTokenParams` | Static provider parameters added to token exchange and refresh requests. |
| `client` | Host-owned OAuth app credential handle. |
| `token` | Paths for reading token response fields. |
| `refresh` | Whether the host should refresh tokens. |
| `postConnect` | Connector route called after token storage to validate the connection and capture provider metadata. |
| `hostValidation` | Rules that validate dynamic OAuth hosts before a redirect or token request is made. |

## OAuth app credentials

`connection.oauth.client` tells the host which company-managed OAuth app credentials to use. Connector runtime code never sees the client secret.

```typescript
client: {
  credentialKey: "shopify_public_app",
}
```

Backfill currently documents only company-managed OAuth clients: a company admin creates or brings an OAuth app in the provider, enters the app's client id and client secret in Backfill, and then each connector connection completes its own provider authorization. Publisher-managed OAuth apps need a separate publishing model and are intentionally not part of this public contract yet.

Client secrets are write-only. Admin forms accept a secret during create/rotate, but read APIs and connector runtime APIs only expose non-secret metadata such as `client_id`, `credentialKey`, status, scopes, and rotation timestamps.

## Company credential registration

The connector declares the credential handle:

```typescript
client: {
  credentialKey: "private_app",
}
```

Backfill must have a company OAuth app credential registered for that handle before OAuth start can succeed. The self-serve admin form for managing these credentials is still pending; until it ships, credentials need to be provisioned by a Backfill operator or internal setup path.

The admin-only credential form should collect:

- client id
- client secret
- allowed scopes
- redirect URI, when the provider requires a pre-registered callback
- label or metadata that helps the admin recognize the app

The client secret field is write-only. After save, the UI should show only non-secret metadata, credential status, allowed scopes, last rotation time, and revoke/rotate actions. Starting OAuth fails if the credential is missing, revoked, provider-mismatched, connector-mismatched, or if the connector requests scopes outside `allowed_scopes`.

Company OAuth app credentials are not reusable across companies. Each connector connection still completes a separate provider authorization and stores separate access/refresh tokens.

## Dynamic OAuth URLs

Use dynamic URLs only when the provider requires tenant-specific hosts. Shopify is the common case because every shop has its own `*.myshopify.com` host.

```typescript
authorizationUrlTemplate:
  "https://{settings.shop_domain}/admin/oauth/authorize",
tokenUrlTemplate:
  "https://{settings.shop_domain}/admin/oauth/access_token",
hostValidation: {
  shop_domain: {
    suffix: ".myshopify.com",
    normalize: "shopifyShopDomain",
  },
},
```

`hostValidation` is required for any setting that appears in the URL host. A rule must declare `suffix` or `exact`. The optional `normalize` value can canonicalize user input before validation.

`normalize: "shopifyShopDomain"`:

- trims whitespace
- lowercases the value
- removes `http://` or `https://`
- drops any path
- appends `.myshopify.com` when the user entered only the shop slug

For fixed-host providers, do not use dynamic host placeholders:

```typescript
oauth: {
  type: "authorization_code",
  authorizationUrlTemplate: "https://connect.squareup.com/oauth2/authorize",
  tokenUrlTemplate: "https://connect.squareup.com/oauth2/token",
  scopes: ["PAYMENTS_READ", "ORDERS_READ", "CUSTOMERS_READ"],
  pkce: false,
  client: {
    credentialKey: "square_public_app",
  },
  refresh: { enabled: true },
  token: {
    accessTokenPath: "access_token",
    refreshTokenPath: "refresh_token",
    expiresInPath: "expires_in",
    scopePath: "scope",
  },
}
```

## Runtime API

Use `OAuth.accessToken()` inside setup, sync, and webhook routes that call the provider.

```typescript
import { OAuth, api } from "@backfill-io/sdk";

export const POST = api(async () => {
  try {
    const accessToken = OAuth.accessToken({ minTtlSeconds: 600 });
    return api.json({ ok: true, hasToken: Boolean(accessToken) });
  } catch (error) {
    if (
      error &&
      typeof error === "object" &&
      (error as { code?: string }).code === "reauth_required"
    ) {
      return api.badRequest("Reconnect this connector");
    }

    throw error;
  }
});
```

`OAuth.connected()` returns whether the current route has a usable token and all required scopes.

`OAuth.tokenInfo()` returns non-secret metadata:

```typescript
const info = OAuth.tokenInfo();
// {
//   provider: "shopify",
//   connected: true,
//   scopes: ["read_orders"],
//   expiresAt: null,
//   providerAccountId: "gid://shopify/Shop/1",
//   providerAccountName: "Demo Shop",
// }
```

If the provider accepts bearer tokens, use the HTTP convenience auth helper:

```typescript
const response = Http.get("https://api.example.com/v1/orders", {
  auth: { oauth: { minTtlSeconds: 300 } },
});
```

For providers like Shopify that require a provider-specific header, read the token and set that header yourself:

```typescript
const response = Http.post(
  `https://${shopDomain}/admin/api/2026-04/graphql.json`,
  { query },
  {
    headers: {
      "X-Shopify-Access-Token": OAuth.accessToken({ minTtlSeconds: 600 }),
    },
  },
);
```

Do not log access tokens or refresh tokens. The host redacts known token values from runtime logs and route errors, but connector code should still treat token material as sensitive.

## Testing

`@backfill-io/sdk/testing` can seed OAuth state without a live provider:

```typescript
import { connectorTestRuntime } from "@backfill-io/sdk/testing";

const runtime = connectorTestRuntime({
  settings: { shop_domain: "demo.myshopify.com" },
  connector: { key: "shopify", provider: "shopify" },
  oauth: {
    accessToken: "test_access_token",
    scopes: ["read_orders", "read_customers"],
    requiredScopes: ["read_orders"],
    provider: "shopify",
    providerAccountId: "gid://shopify/Shop/1",
    providerAccountName: "Demo Shop",
  },
});
```

Useful OAuth fixture cases:

- connected token with required scopes
- missing token: `oauth: { accessToken: null }`
- scope mismatch: set `requiredScopes` to include a scope not present in `scopes`
- expired refreshable token: set `expiresAt` in the past and provide `refresh`
- permanent refresh failure: set `refreshError`
- bearer helper: call `Http.get(..., { auth: { oauth: true } })` and assert the request shape


---

# Custom entities

URL: https://backfill.io/docs/sdk/extensions/custom-entities/

> Declare your own entity types with defineEntity.


When you need to track something the platform doesn't provide out-of-the-box, you can create a custom entity. Each custom entity gets its own importable entity class, JSONB-backed storage with deploy-time validation, and the same `Entity` API as native entities in Backfill.

For the distinction between entities, records, resources, documents, and lines, see the [SDK glossary](../../concepts/glossary/).

## File location

Create one file per entity, at `src/entities/<PascalName>.ts`. It's auto-registered on deploy. The filename must match the entity name (`MyEntity` → `MyEntity.ts`), and the file's default export is `defineEntity({ ... })`:

```typescript
// src/entities/NexusAddress.ts
import { defineEntity } from "@backfill-io/sdk";

export default defineEntity({
  name: "NexusAddress",
  fields: {
    nexusName:  { type: "string", required: true },
    street:     { type: "string", required: true },
    city:       { type: "string", required: true },
    state:      { type: "string", required: true },
    postalCode: { type: "string", required: true },
    country:    { type: "string", default: "US" },
    active:     { type: "boolean", default: true },
    startsOn:   { type: "date" },
    status:     { type: "enum", values: ["draft", "active", "archived"], default: "draft" },
    customerId: { type: "reference", entity: "Customer", index: true },
    rate:       { type: "decimal" },
  },
});
```

## Field types

We currently support the field types below:

| Type | Use for |
|---|---|
| `string` | IDs, names, dates as ISO strings, free text. |
| `number` | Amounts, counts, percentages. |
| `boolean` | Flags. |
| `json` | Nested objects, arrays, anything you want as opaque structured data. |
| `date` | ISO `YYYY-MM-DD` date strings. |
| `datetime` | ISO datetimes or browser `datetime-local` strings. |
| `enum` | One string from a declared `values` list. |
| `reference` | A string id pointing at a standard entity or another custom entity in the same extension. |
| `decimal` | Exact decimal strings or numbers for rates, hours, quantities, and money-like values. |

Each field can declare:

- `required?: boolean` — fail to create if missing.
- `default?: any` — applied at create when the field isn't supplied.
- `index?: boolean` — add `index: true` when you expect to filter by equality on this field often. Backfill can use the index instead of scanning custom entity data. `reference` fields are indexed for equality automatically.

`enum` fields must declare `values: string[]`. `reference` fields must declare
`entity: string`; this can be a Backfill standard entity such as `Invoice` or a
custom entity declared by the same extension.

## Naming rules

- Entity name must be **PascalCase** (e.g., `RevenueSchedule`, `NexusAddress`).
- Cannot collide with a standard entity name (you can't define one called `Invoice`).
- Filename must match the name: `MyEntity` lives at `src/entities/MyEntity.ts`.

Errors look like:

```
src/entities/foo.ts: entity name 'foo' must be PascalCase (e.g. RevenueSchedule)
src/entities/Invoice.ts: entity name 'Invoice' conflicts with a standard entity
```

## Permission grants

Custom entities go through the same permission system. Grant access in the manifest:

```typescript
permissions: {
  entities: { NexusAddress: ["read", "write"] },
}
```

Without explicit permissions, your own scripts can't access the entity you just defined.

## displayOn — surface on parent entities

`displayOn` adds a panel to a parent entity's detail page in the dashboard.

```typescript
defineEntity({
  name: "StripeReconciliation",
  fields: {
    chargeId:   { type: "string", required: true },
    invoiceId:  { type: "reference", entity: "Invoice", index: true },
    matchedAt:  { type: "datetime" },
    confidence: { type: "number" },
  },
  displayOn: [
    { entity: "Invoice", foreignKey: "invoiceId" },
  ],
});
```

The parent entity must be a standard entity and the `foreignKey` must be either
a `string` field or a `reference` field that points at that parent entity.

## Hooks against custom entities

Hooks work the same as for standard entities. Drop a file at `src/hooks/<custom-entity-kebab>/<event>.ts`. The entity name converts to kebab using the standard rule (so `NexusAddress` → `nexus-address`).

```
src/hooks/nexus-address/before-save.ts
src/hooks/stripe-reconciliation/after-save.ts
```

## Reading and writing

Review [entities](../entities/) to see all `Entity` methods available for custom entities. Example below:

```typescript
import { NexusAddress } from "@backfill-io/sdk";

const records = NexusAddress.query({ where: { active: true } });

NexusAddress.create({
  nexusName: "California",
  street: "...",
  city: "...",
  state: "CA",
  postalCode: "94000",
});
```


---

# Guides

URL: https://backfill.io/docs/sdk/guides/

> End-to-end walkthroughs for the most common extension shapes.


Each guide is a complete working example. Clone, adapt, ship.


---

# SalesReceipt

URL: https://backfill.io/docs/resources/sales-receipt/



---

# Settings schema

URL: https://backfill.io/docs/sdk/connectors/settings-schema/

> JSON Schema describing per-installation connection settings — including encrypted secret fields.


Connectors use a JSON Schema document to describe the form an admin fills in to install a connection. The schema lives at `connection.settingsSchema` in the manifest. Plain extensions don't have this — they use the simpler `config` defaults map (see [Settings](../../extensions/settings/)).

## Real example

A real connector's schema:

```typescript
settingsSchema: {
  type: "object",
  required: ["api_key"],
  properties: {
    api_key: {
      type: "string",
      minLength: 1,
      title: "Secret API key",
      description:
        "Stripe restricted or secret API key used for poll and reconciliation routes.",
      "x-secret": true,
      "x-placeholder": "sk_live_... or sk_test_...",
    },
    webhook_secret: {
      type: "string",
      minLength: 1,
      title: "Webhook signing secret",
      description:
        "Stripe endpoint signing secret used by the verified webhook route.",
      "x-secret": true,
      "x-placeholder": "whsec_...",
    },
    account_id: {
      type: "string",
      title: "Connected account ID",
      description: "Optional Stripe Connect account ID...",
      "x-placeholder": "acct_...",
    },
    extract_tax_details: {
      type: "boolean",
      title: "Extract tax details",
      default: true,
    },
    settlement_currency: {
      type: "string",
      title: "Expected settlement currency",
      enum: ["auto", "USD", "EUR", "GBP", "CAD", "AUD", "JPY"],
      default: "auto",
    },
  },
},
```

## Standard JSON Schema bits

- `type: "object"` and a `properties` map — required.
- `required: [...]` — fields that must be present.
- Per-property: `type` (`string` | `number` | `boolean` | `object` | `array`), `title`, `description`, `default`.
- Standard validators: `minLength`, `maximum`, `enum`, `pattern`, etc.

## Backfill-specific extensions

| Key | Effect |
|---|---|
| `x-secret: true` | The dashboard renders the field as a password input and stores the value in the encrypted secret store. The schema field name becomes the secret name (so `api_key` ends up readable as `Secrets.get("api_key")`). |
| `x-placeholder: "..."` | Placeholder text in the dashboard input. |

`x-secret` is the bridge between the connector schema and the [Secrets](../../extensions/secrets/) system. You don't need to also list these names under `permissions.secrets` — by being declared in the connector's `settingsSchema`, they're owned by the connector.

## Reading the values

Non-secret fields come back from `Settings.getAll()` exactly like a plain extension's `config`:

```typescript
const acctId = Settings.get("account_id");
const extractTax = Settings.get("extract_tax_details");
```

Secret fields are read with `Secrets.get(...)`:

```typescript
const apiKey = Secrets.get("api_key");
const webhookSecret = Secrets.get("webhook_secret");
```

## What happens at install

The dashboard renders the form from the schema, validates the admin's inputs against the schema, splits secret-marked values into the secret store, and persists the rest as the connection's settings. From that point on, your runtime calls to `Settings.get` and `Secrets.get` see the values.


---

# Custom fields

URL: https://backfill.io/docs/sdk/extensions/custom-fields/

> Store custom field values from your extension on entity records and lines.


Custom fields are extension-owned values attached to Backfill entity records and lines. Use entity fields for values that belong to a whole record, such as a customer or invoice. Use line fields for provider-specific values that belong to one line on a line-bearing document.

## File location

Declare fields in one file per parent entity:

```text
src/fields/
├── Customer.ts
└── Invoice.ts
```

The filename is the canonical entity name. Field keys live inside the declaration config, so exported constants can follow normal TypeScript naming conventions.

```typescript
// src/fields/Customer.ts
import { defineEntityField } from "@backfill-io/sdk";

export const stripeCustomerId = defineEntityField({
  key: "stripe_customer_id",
  label: "Stripe customer",
  type: "string",
});
```

```typescript
// src/fields/Invoice.ts
import { defineEntityField, defineLineField } from "@backfill-io/sdk";

export const stripeInvoiceId = defineEntityField({
  key: "stripe_invoice_id",
  label: "Stripe invoice",
  type: "string",
});

export const stripeTaxBehavior = defineLineField("line_items", {
  key: "stripe_tax_behavior",
  label: "Stripe tax behavior",
  type: "select",
  options: ["inclusive", "exclusive", "unspecified"],
});
```

`line_items` is the only supported line collection today, on every line-bearing canonical document (`Invoice`, `CreditMemo`, `SalesReceipt`, `RefundReceipt`, `VendorBill`, `Expense`, `PurchaseOrder`, `Quote`, `VendorCredit`, `SalesOrder`, and `Deposit`). Additional line collections will be added as new line-bearing entities ship. Field keys must be lower snake case.

The equivalent normalized deployment manifest is generated by the CLI. You do not write this block by hand:

```typescript
fields: {
  entity: {
    Customer: {
      stripe_customer_id: {
        label: "Stripe customer",
        type: "string",
      },
    },
    Invoice: {
      stripe_invoice_id: {
        label: "Stripe invoice",
        type: "string",
      },
    },
  },
  line: {
    Invoice: {
      line_items: {
        stripe_tax_behavior: {
          label: "Stripe tax behavior",
          type: "select",
          options: ["inclusive", "exclusive", "unspecified"],
        },
      },
    },
  },
}
```

`src/fields/<EntityName>.ts` declarations apply to Backfill standard entities. Use `defineEntity.fields` for the schema of extension-owned [custom entities](../custom-entities/).

## Field types

```typescript
type FieldType =
  | "string"
  | "number"
  | "boolean"
  | "date"
  | "datetime"
  | "select"
  | "multi_select"
  | "currency"
  | "json";

type FieldOption = string | { label: string; value: string };

interface FieldConfig {
  key: string;
  label: string;
  type: FieldType;
  nullable?: boolean;
  options?: FieldOption[];
  currency?: string;
  currencyField?: string;
}

defineEntityField(config: FieldConfig);
defineLineField(lineCollection: "line_items", config: FieldConfig);
```

`string`, `number`, `boolean`, `date`, and `datetime` use their standard JSON-shaped values. `select`, `multi_select`, `currency`, and `json` have extra rules covered below.

### Select and multi-select

`select` and `multi_select` fields must declare a non-empty `options` list. Options can be plain strings, or `{ label, value }` objects when you want a friendlier UI label without changing the stored value:

```typescript
export const stripeTaxBehavior = defineLineField("line_items", {
  key: "stripe_tax_behavior",
  label: "Stripe tax behavior",
  type: "select",
  options: [
    { label: "Inclusive", value: "inclusive" },
    { label: "Exclusive", value: "exclusive" },
    { label: "Unspecified", value: "unspecified" },
  ],
});
```

`multi_select` stores an array of declared option values:

```typescript
export const fulfillmentFlags = defineLineField("line_items", {
  key: "fulfillment_flags",
  label: "Fulfillment flags",
  type: "multi_select",
  options: ["backordered", "split_shipment", "manual_review"],
});
```

### Currency

Currency fields are amount-shaped values for financial extension data. Use decimal strings for values — never JavaScript floating-point numbers — to avoid rounding errors.

A currency field must declare either a static ISO 4217 `currency` code, or a `currencyField` that names another field on the same record where the currency code lives:

```typescript
// Static currency: every value is in USD.
export const stripeFeeUsd = defineEntityField({
  key: "stripe_fee_usd",
  label: "Stripe fee (USD)",
  type: "currency",
  currency: "USD",
});

// Dynamic currency: read the code from a sibling field on the same line.
export const stripeFeeAmount = defineLineField("line_items", {
  key: "stripe_fee_amount",
  label: "Stripe fee",
  type: "currency",
  currencyField: "currency",
});
```

### JSON

`json` stores arbitrary JSON-shaped values. Use it sparingly for structured payloads that don't fit the other types:

```typescript
export const stripeMetadata = defineEntityField({
  key: "stripe_metadata",
  label: "Stripe metadata",
  type: "json",
});
```

## Reserved keys

Custom field keys cannot collide with native attributes on the parent entity or line. The platform validates these reserved keys at deploy time against a parity-tested list, and a colliding key fails the deploy with a validation error pointing at the declaration.

For entity fields, reserved keys include native attributes such as `email` on `Customer` or `status` on `Invoice`.

For line fields, reserved native line keys include `amount`, `quantity`, `tax_amount`, `account_id`, `account_code`, `item_id`, `line_key`, and `line_number`.

## Runtime reads and writes

Reads require entity `read` permission, writes require entity `write`. Values are scoped to the calling extension — reads only see fields your extension declared.

### Entity fields

After declaring fields with `defineEntityField`, read and write values through the same entity APIs you use for native fields. Declared field keys sit at the top level next to native fields; unknown keys fail validation.

```typescript
import { Customer } from "@backfill-io/sdk";

Customer.create({
  name: "Acme, Inc.",
  email: "billing@acme.example",
  stripe_customer_id: "cus_123",
});

Customer.update(customerId, {
  name: "Acme, Inc.",
  stripe_customer_id: "cus_123",
});

const customer = Customer.get(customerId);
const stripeCustomerId = customer?.stripe_customer_id;
```

For field-only writes, use the generated entity field namespace:

```typescript
Customer.fields.set(customerId, "stripe_customer_id", "cus_123");

Customer.fields.setAll(customerId, {
  stripe_customer_id: "cus_123",
  revenue_schedule_id: "rs_abc123",
});

const all = Customer.fields.getAll(customerId);
// => { stripe_customer_id: "cus_123", revenue_schedule_id: "rs_abc123" }

Customer.fields.delete(customerId, "stripe_customer_id");
```

Generic code can use `Entity`:

```typescript
import { Entity } from "@backfill-io/sdk";

Entity.update("Invoice", invoiceId, {
  stripe_invoice_id: "in_123",
  revenue_schedule_id: "rs_abc123",
});
```

### Line fields

Line fields target a document ID and a `line_key`. When you are already creating or updating an invoice, include declared line field keys directly inside `line_items` next to native line attributes:

```typescript
import { Invoice } from "@backfill-io/sdk";

Invoice.update(invoiceId, {
  status: "sent",
  stripe_invoice_id: "in_123",
  line_items: [
    {
      line_key: "line_1",
      quantity: 2,
      stripe_tax_behavior: "exclusive",
      stripe_balance_transaction_id: "txn_123",
    },
  ],
});
```

For field-only writes, use the line-collection `fields` namespace. Get `line_key` from the hook context (`ctx.entity.line_items[i].line_key`) or from the invoice you just read or wrote. The generated SDK accessor is camelCase: `Invoice.lineItems`.

```typescript
Invoice.lineItems.fields.set(
  invoiceId,
  lineKey,
  "stripe_tax_behavior",
  "exclusive",
);

Invoice.lineItems.fields.setAll(invoiceId, lineKey, {
  stripe_tax_behavior: "exclusive",
  stripe_balance_transaction_id: "txn_123",
});

Invoice.lineItems.fields.setMany(invoiceId, {
  "stripe:il_123": {
    stripe_tax_behavior: "exclusive",
    stripe_fee_amount: "1.23",
  },
  "stripe:il_124": {
    stripe_tax_behavior: "inclusive",
    stripe_fee_amount: "0.42",
  },
});

Invoice.lineItems.fields.delete(invoiceId, lineKey, "stripe_tax_behavior");

const value = Invoice.lineItems.fields.get(
  invoiceId,
  lineKey,
  "stripe_tax_behavior",
);

const valuesByLine = Invoice.lineItems.fields.getAll(invoiceId);
// => { [lineKey]: { stripe_tax_behavior: "exclusive" } }
```

### Merge, null, and delete

Writes merge declared keys instead of replacing the whole field set. `setAll` — for both entity and line fields — only touches the keys you pass, leaving unset keys at their existing values.

To clear a field, use `delete`. `set(..., null)` stores JSON `null`, which is a real value, not a delete. Fields are nullable by default; if a declaration sets `nullable: false`, writes with `null` are rejected.

### Transactions and hook timing

Inline line field writes and the native document update are one logical transaction. If any line field fails validation — wrong type, oversized value, unknown `line_key` — the whole write fails and nothing is persisted.

Before-save hooks cannot write line fields, because new line keys do not exist yet at that point. Either include the line field values in the create/update call itself, or write them from an after-save hook once line keys are stable.

### Generated types

Generated SDK reads are typed from discovered field declarations, so `Customer.get(...)` returns the right shape for the fields you declared. Generic `Entity` calls may still return `unknown` when the entity type or field key is not statically known.

## API responses

SDK reads are scoped to the calling extension. Backfill UI surfaces can combine active values from every enabled extension for a rendered document.

Backfill REST API responses exclude extension fields by default and accept a single `include` query parameter to opt in:

- `extension_fields.entity` — surface entity-level extension fields on the parent record under `extensionFields`.
- `extension_fields.line` — surface line-level extension fields on each projected line under an `extensionFields` key on the line.

Both tokens may be combined (`?include=extension_fields.entity,extension_fields.line`); unknown tokens return `400 invalid_include`.

```http
GET /api/v1/invoices/:id?include=extension_fields.entity,extension_fields.line
```

```json
{
  "data": {
    "id": "...",
    "documentNumber": "INV-1",
    "extensionFields": {
      "stripe": { "stripe_invoice_id": "in_123" }
    },
    "lines": [
      {
        "lineKey": "line_1",
        "amount": "100.00",
        "extensionFields": {
          "stripe": { "stripe_tax_behavior": "exclusive" }
        }
      }
    ]
  }
}
```

Keys are always immutable `extension_key` → `field_key`; internal `extension_id` UUIDs never appear in responses. Only enabled extensions contribute values, and only field keys declared in the extension's active manifest are projected. The opt-in is supported on every line-bearing canonical document REST endpoint: `Invoice`, `CreditMemo`, `SalesReceipt`, `RefundReceipt`, `VendorBill`, `Expense`, `PurchaseOrder`, `Quote`, `VendorCredit`, `SalesOrder`, and `Deposit`.

## Custom fields vs. entities

Fields and custom entities both use file-based declarations. Choose based on the lifecycle of the data:

| Use fields when | Use custom entities when |
|---|---|
| Data lives 1:1 on an existing entity or document line. | Data has its own lifecycle, often many records per parent. |
| You want it to disappear with the parent. | You want to query, sort, filter, or permission it independently. |
| You need declared field validation without a new resource. | You need a first-class extension-owned entity type. |

For 1:N data attached to an invoice, such as reconciliation matches, use a [custom entity](../custom-entities/) with [`displayOn`](../custom-entities/#displayon--surface-on-parent-entities) instead.


---

# Item

URL: https://backfill.io/docs/resources/item/



---

# Logging

URL: https://backfill.io/docs/sdk/extensions/logging/

> How to use Log.debug, info, warn, error for structured logging that surfaces in the Backfill dashboard and `backfill logs`.


`Log` is the only way to emit observability data from a script. Four levels, each takes a message and an optional structured-data object.

```typescript
import { Log } from "@backfill-io/sdk";

Log.debug(message: string, data?: Record<string, any>): void;
Log.info(message: string, data?: Record<string, any>): void;
Log.warn(message: string, data?: Record<string, any>): void;
Log.error(message: string, data?: Record<string, any>): void;
```

## Usage

```typescript
Log.info("Tax calculated", {
  invoiceId: ctx.entity.id,
  subtotal,
  taxAmount,
  taxRate: rate,
});
```

The data object renders structurally in the dashboard and in `backfill logs --follow`. Keep keys short and stable — searches across log lines key off them.

## What about `console.log`?

Works in the sandbox, but it isn't the right channel. Only `Log.*` calls flow into the platform's audit trail and the CLI's log stream. Use `Log` for anything you want to inspect later.

## Levels

| Level | Use for |
|---|---|
| `debug` | Verbose detail useful while iterating. Filtered by default in the log view. |
| `info` | Notable but expected events: a sync completed, a hook fired, a counter incremented. |
| `warn` | Recoverable surprises: missing optional config, unknown enum values, retries kicking in. |
| `error` | Things that failed and you'd want to chase. Always include enough context to reproduce. |

## Constraints

- No log levels below `debug`. There's no `trace`.
- Data must be JSON-serializable — no functions, symbols, or circular references.
- One call = one log line. No streaming.


---

# Sync routes

URL: https://backfill.io/docs/sdk/connectors/sync-routes/

> Per-stream poll handlers that fetch from the provider and emit canonical records.


For every poll-mode stream you declare, write a sync route. The platform invokes it on schedule, hands you the saved page/cursor, and expects you to fetch from the provider and emit canonical records via `ingest.canonical`.

## File location

Sync routes live at `src/api/sync/<stream-key>.ts` — auto-registered as the `POST` handler for the matching `streams[]` entry in poll or backfill mode. This is an enforced build/deploy contract: every `poll` or `backfill` stream must have a matching `POST` sync route. They follow the same conventions as plain [API routes](../../extensions/api-routes/).

## Real example

A real sync route — Stripe customers:

```typescript
import { api, ingest } from "@backfill-io/sdk";
import { stripePollMetadata } from "../../lib/metadata";
import {
  commitStripeListPage,
  missingStripeApiKeyResponse,
  stripeApiKey,
  stripeDateFilterParams,
  stripeGet,
  stripeListPage,
  stripeListResponse,
  stripeListUrl,
  stripeSyncResponse,
} from "../../lib/stripe";

export const config = { auth: "api_key" };

export const POST = api(async (request) => {
  const stream = "customers";
  const apiKey = stripeApiKey();
  if (!apiKey) return missingStripeApiKeyResponse();

  const page = stripeListPage(request, stream);
  const response = stripeGet(
    stripeListUrl("/customers", page, stripeDateFilterParams(request)),
    apiKey,
  );
  if (!response.ok) {
    return api.providerError("Stripe customers sync failed", response);
  }

  const list = stripeListResponse(response);
  const payloads = list.records.map((customer) => customerCanonical(customer));
  const batch = ingest.batch("customer", payloads, {
    stream,
    continueOnError: true,
    sourceId: (payload) => payload.customer_id,
    idempotencyKey: (payload) => `stripe:customer:${payload.customer_id}`,
  });

  const checkpoint = commitStripeListPage(stream, list.records, list.hasMore);

  return stripeSyncResponse({
    stream,
    imported: batch.imported,
    failed: batch.failed,
    hasMore: list.hasMore,
    checkpoint,
    results: batch.results,
    failedRecords: batch.failedRecords,
  });
});
```

## The contract

A sync route is just an API route with `POST`. The platform invokes it as part of the schedule for the matching stream.

| Concern | Where it lives |
|---|---|
| Scheduling | The `streams[]` entry in the manifest (`schedule: "*/15 * * * *"`). |
| Auth into the provider | `Secrets.get("api_key")` (or whatever your `settingsSchema` declared). |
| Cursor / page | Read from `request` (e.g., `searchParams`) and persisted between runs by the platform / lib helpers. |
| Outbound HTTP | `Http` (with the provider's host on `permissions.http`). |
| Emit | `ingest.batch(canonicalType, payloads, { stream, continueOnError: true, sourceId, idempotencyKey })` for pages, or `ingest.canonical(...)` for one record. |
| Telemetry | `Log.info("...", { ... })`. |
| Response | A status object the platform reads to know how the run went. |

## `ingest.canonical`

The connector-specific runtime helper. Signature observed from usage:

```typescript
ingest.canonical(
  canonicalType: string,                // canonical entity name (lowercase or platform-mapped)
  payload: Record<string, any>,         // shaped to canonical schema
  opts: { stream: string; idempotencyKey: string }
): IngestResult;
```

| Argument | Notes |
|---|---|
| `canonicalType` | The canonical entity to write to (e.g., `"customer"`, `"invoice"`). The platform routes this to the right concrete entity for the connection. |
| `payload` | Shape it as the canonical schema expects, not the provider's raw shape. Most connectors maintain `lib/transforms/*.ts` to normalize. |
| `stream` | The stream key from `streams[]`. Used for telemetry + checkpoint accounting. |
| `idempotencyKey` | A stable string derived from the provider's record. Re-emissions with the same key dedupe. |

## `ingest.batch`

For sync pages, prefer `ingest.batch(..., { continueOnError: true })` so one bad
record does not abort the whole page:

```typescript
const batch = ingest.batch("customer", payloads, {
  stream: "customers",
  continueOnError: true,
  sourceId: (payload) => payload.customer_id,
  idempotencyKey: (payload) => `stripe:customer:${payload.customer_id}`,
});
```

The result includes:

| Field | Notes |
|---|---|
| `imported` | Successful records. |
| `failed` | Failed records. |
| `results` | Successful canonical ingest results. |
| `failedRecords` | Structured failures with `documentType`, `stream`, `sourceId`, `idempotencyKey`, `reason`, `message`, `retryable`, and `index`. |

## Pagination & checkpoints

The platform's lib helpers (`stripeListPage`, `commitStripeListPage`, etc.) abstract a "read the saved cursor → fetch one page → save the new cursor → return `hasMore`" loop. Until the connector SDK formalizes this, treat the existing connector's helpers as the reference and copy patterns.

## Errors

If the provider call fails, return early with a structured response (e.g., `api.providerError(...)`). Don't throw — `ingest.canonical` is not aware of mid-pagination throws and you may end up with partial state.

If a single record fails to ingest, log the failure and continue the page; the platform records ingest results per record so partial success is observable.

## Testing sync routes

Use `@backfill-io/sdk/testing` to run sync routes locally with mocked provider
HTTP, settings, secrets, checkpoints, and ingest calls:

```typescript
import assert from "node:assert/strict";
import test from "node:test";
import { connectorTestRuntime } from "@backfill-io/sdk/testing";

test("customers sync emits canonical customers", async () => {
  const runtime = connectorTestRuntime({
    secrets: { api_key: "sk_test_123" },
  });

  try {
    runtime.install();
    const { POST } = await import("../src/api/sync/customers");

    runtime.http.getOnce({
      status: 200,
      body: { data: [{ id: "cus_123", name: "Ada Lovelace" }] },
    });

    const response = await runtime.call(POST);

    assert.equal(response.status, 200);
    assert.equal(runtime.ingest.calls[0].documentType, "customer");
    assert.equal(runtime.ingest.calls[0].sourceId, "cus_123");
  } finally {
    runtime.restore();
  }
});
```

See [Testing](../testing/) for the full route-test harness, including partial
ingest failures and pagination assertions.


---

# Outbound HTTP

URL: https://backfill.io/docs/sdk/extensions/outbound-http/

> Learn about Http.get / post / put / patch / delete to reach external services.


`Http` is the SDK's HTTP client. Every outbound call must match an entry in `permissions.http` within `backfill.config.ts` (see [configuration](../configuration/)) or it's blocked.

## Signatures

```typescript
interface RequestOpts {
  headers?: Record<string, string>;
  body?: any;
  auth?: {
    bearer?: string;
    basic?: { user: string; pass: string };
    oauth?: boolean | { minTtlSeconds?: number };
  };
  timeout?: number;
}

interface HttpResponse {
  status: number;
  headers: Record<string, string>;
  body: any;       // parsed JSON if the response is JSON; raw string otherwise
  ok: boolean;     // true if 2xx
}

Http.get(url, opts?)
Http.post(url, body?, opts?)
Http.put(url, body?, opts?)
Http.patch(url, body?, opts?)
Http.delete(url, opts?)
```

## Permissions

Each entry in `permissions.http` is an `https://` URL with an explicit host. Path wildcards are allowed; host wildcards are not.

```typescript
permissions: {
  http: ["https://api.stripe.com/*"],
}
```

A request to a host not on the allowlist throws at runtime.

## Making a request

```typescript
const res = Http.get("https://api.stripe.com/v1/customers", {
  auth: { bearer: Secrets.get("stripe_api_key")! },
  timeout: 10_000,
});

if (!res.ok) {
  Log.error("Stripe call failed", { status: res.status, body: res.body });
  throw new Error("Stripe call failed");
}

const customers = res.body.data;
```

## Authentication

Built-ins:

```typescript
auth: { bearer: "sk_live_..." }                    // Authorization: Bearer ...
auth: { basic: { user: "key", pass: "secret" } }   // Authorization: Basic ...
auth: { oauth: true }                              // Connector OAuth bearer token
auth: { oauth: { minTtlSeconds: 300 } }            // Refresh first if needed
```

`auth.oauth` is available to connector routes whose manifest declares
`connection.oauth`. See [Connector OAuth](../../connectors/oauth/).

For anything else, set the header directly:

```typescript
Http.post(url, body, {
  headers: {
    "Authorization": "Bearer " + token,
    "X-Idempotency-Key": myKey,
  },
});
```

## Bodies

`body` is auto-serialized:

- A plain object → JSON, with `Content-Type: application/json`.
- A string → sent as-is. Set `Content-Type` yourself.

The response `body` is parsed back to JSON when the server responds with a JSON content type, otherwise it's a string.

## Timeouts

`timeout` is in milliseconds. Default is platform-decided. For chatty external APIs, set it explicitly so a hung peer doesn't block your hook.

## Retries

`Http` does *not* retry. If you need retry-on-503 / retry-on-network-error semantics, write a small loop. For sync routes in connectors, retry behavior is yours.


---

# Testing

URL: https://backfill.io/docs/sdk/connectors/testing/

> Unit-test connector routes locally with the SDK testing runtime.


Connector routes run inside Backfill with runtime globals like `api`, `Http`,
`Secrets`, `Settings`, `sync`, and `ingest`. In local Node tests, those globals
do not exist unless you install a test runtime first.

Use `@backfill-io/sdk/testing` to run route modules against mocked provider
HTTP, mocked connection settings, mocked secrets, in-memory checkpoints, and
captured ingest calls.

## Install

Add a test runner and run tests through TypeScript:

```bash
pnpm add -D tsx
```

```json
{
  "scripts": {
    "test": "node --test --import tsx test/*.test.ts"
  }
}
```

## Basic route test

Install the runtime before importing a route module that imports SDK globals.
The safest pattern is a dynamic import inside the test after `runtime.install()`.

```typescript
import assert from "node:assert/strict";
import test from "node:test";
import { connectorTestRuntime } from "@backfill-io/sdk/testing";

test("customers sync imports one page", async () => {
  const runtime = connectorTestRuntime({
    settings: { shop_domain: "demo.myshopify.com" },
    connector: { key: "shopify", provider: "shopify" },
    connection: {
      id: "conn_123",
      connectionId: "conn_123",
      connectorKey: "shopify",
      provider: "shopify",
    },
    oauth: {
      accessToken: "test_access_token",
      scopes: ["read_customers"],
      requiredScopes: ["read_customers"],
      provider: "shopify",
    },
  });

  try {
    runtime.install();

    const { POST } = await import("../src/api/sync/customers");

    runtime.http.postJsonOnce({
      status: 200,
      body: {
        data: {
          customers: {
            nodes: [
              {
                id: "gid://shopify/Customer/123",
                displayName: "Ada Lovelace",
              },
            ],
            pageInfo: { hasNextPage: false, endCursor: "cursor_1" },
          },
        },
      },
    });

    const response = await runtime.call(POST, {
      searchParams: { limit: "50" },
    });

    assert.equal(response.status, 200);
    assert.equal(runtime.http.calls.length, 1);
    assert.equal(runtime.ingest.calls.length, 1);
    assert.equal(runtime.ingest.calls[0].documentType, "customer");
    assert.equal(
      runtime.ingest.calls[0].idempotencyKey,
      "shopify:customer:gid://shopify/Customer/123",
    );
  } finally {
    runtime.restore();
  }
});
```

Always call `runtime.restore()` in a `finally` block. The runtime installs
globals on `globalThis`; restoring prevents one test from leaking SDK state into
the next.

## Runtime setup

```typescript
const runtime = connectorTestRuntime({
  settings: { shop_domain: "demo.myshopify.com" },
  tenantId: "tenant_123",
  extensionKey: "shopify",
  connector: { key: "shopify", provider: "shopify" },
  connection: {
    id: "conn_123",
    connectionId: "conn_123",
    connectorKey: "shopify",
    provider: "shopify",
    settings: { shop_domain: "demo.myshopify.com" },
  },
  oauth: {
    accessToken: "test_access_token",
    scopes: ["read_customers"],
    requiredScopes: ["read_customers"],
    provider: "shopify",
  },
});
```

The runtime installs mocks for:

| SDK surface | What the test runtime provides |
|---|---|
| `api` | `api(...)`, `api.json(...)`, `api.badRequest(...)`, `api.error(...)`, and `api.providerError(...)` responses. |
| `Http` | Queue-based `get`, `post`, `postJson`, `put`, `patch`, and `delete` responses plus captured calls. |
| `Settings` | Values from `settings`, with runtime mutation through `runtime.settings.set(...)`. |
| `Secrets` | Values from `secrets`, with runtime mutation through `runtime.secrets.set(...)`. |
| `sync` | In-memory `listPage(...)`, `checkpoint(...)`, and `setCheckpoint(...)` helpers. |
| `ingest` | Captured `canonical(...)` and `batch(...)` calls with optional failure injection. |
| `Log` | Captured `debug`, `info`, `warn`, and `error` entries. |
| `Connector` / `connector` | Current connector, connection, and status metadata. |
| `OAuth` | Connected, missing-token, missing-scope, expired, refreshable, and refresh-failed OAuth states. |
| `Entity` | In-memory entity reads and writes for route code that imports it. |

## Mock provider calls

Queue provider responses before the route makes outbound calls:

```typescript
runtime.http.getOnce({
  status: 200,
  body: { data: [{ id: "cus_123", name: "Ada Lovelace" }] },
});

runtime.http.respondOnce({
  method: "POST",
  url: /graphql\.json$/,
  status: 200,
  body: { data: { shop: { id: "gid://shopify/Shop/1" } } },
});
```

Assert the provider request shape through `runtime.http.calls`:

```typescript
assert.equal(runtime.http.calls[0].method, "POST");
assert.match(runtime.http.calls[0].url, /admin\/api\/.*\/graphql\.json$/);
assert.equal(
  runtime.http.calls[0].opts?.headers?.["X-Shopify-Access-Token"],
  "test_access_token",
);
```

If a route calls `Http` without a queued response, the runtime throws. This
usually means the test missed an upstream page or the route made an unexpected
provider call.

## Assert ingest behavior

For single-record routes, assert `runtime.ingest.calls`:

```typescript
assert.deepEqual(runtime.ingest.calls[0].payload, {
  customer_id: "cus_123",
  display_name: "Ada Lovelace",
});
assert.equal(runtime.ingest.calls[0].stream, "customers");
assert.equal(runtime.ingest.calls[0].sourceId, "cus_123");
```

For page-based sync routes that use `ingest.batch(...)`, assert both the batch
call and the expanded per-record calls:

```typescript
assert.equal(runtime.ingest.batchCalls.length, 1);
assert.equal(runtime.ingest.batchCalls[0].documentType, "customer");
assert.equal(runtime.ingest.calls.length, 100);
```

## Test partial failures

Use failure injection to verify safe-ingest behavior. With
`continueOnError: true`, `ingest.batch(...)` returns imported and failed counts
instead of throwing on the first bad record.

```typescript
runtime.ingest.failWhere((call) => call.sourceId === "bad", {
  reason: "fixture_rejected",
  message: "Fixture rejected",
  retryable: true,
});

const response = await runtime.call(POST);

assert.equal(response.body.imported, 1);
assert.equal(response.body.failed, 1);
assert.equal(response.body.failedRecords[0].sourceId, "bad");
assert.equal(response.body.failedRecords[0].retryable, true);
```

Use `runtime.ingest.failNext(...)` when the next canonical write should fail
regardless of record contents.

## Test checkpoints and pagination

Pass request query params through `runtime.call(...)` and assert the checkpoint
written by the route:

```typescript
const response = await runtime.call(POST, {
  searchParams: { limit: "25", cursor: "cursor_0" },
});

assert.equal(response.body.hasMore, true);
assert.deepEqual(runtime.sync.checkpoints.customers, {
  endCursor: "cursor_1",
});
```

This keeps pagination tests focused on connector code: request parsing,
provider query construction, checkpoint writes, and response shape.

## Test OAuth routes

Seed OAuth state with the `oauth` option. This lets setup and sync routes call
`OAuth.accessToken()`, `OAuth.connected()`, `OAuth.tokenInfo()`, or `Http` with
`auth: { oauth: true }` without a live provider.

```typescript
const runtime = connectorTestRuntime({
  settings: { shop_domain: "demo.myshopify.com" },
  connector: { key: "shopify", provider: "shopify" },
  connection: {
    connectorKey: "shopify",
    provider: "shopify",
  },
  oauth: {
    accessToken: "test_access_token",
    scopes: ["read_orders", "read_customers"],
    requiredScopes: ["read_orders"],
    provider: "shopify",
    providerAccountId: "gid://shopify/Shop/1",
    providerAccountName: "Demo Shop",
  },
});
```

Useful OAuth cases:

- Missing token: `oauth: { accessToken: null }`.
- Missing scope: set `requiredScopes` to include a scope not present in `scopes`.
- Expired and refreshable: set `expiresAt` in the past and provide `refresh`.
- Permanent refresh failure: set `refreshError`.
- Explicit reauth: call `runtime.oauth.needsReauth("invalid_grant")`.

For providers that accept bearer auth, assert the `Http` OAuth helper was used:

```typescript
Http.get("https://api.example.com/v1/orders", {
  auth: { oauth: true },
});

assert.equal(
  runtime.http.calls[0].opts?.headers?.authorization,
  "Bearer [REDACTED_OAUTH_TOKEN]",
);
```

The test runtime redacts OAuth bearer auth in captured HTTP calls. If your
provider needs a custom token header, assert that header directly from the
connector code.

## What this is not

The testing runtime is a route-level unit test harness. It does not boot
Backfill, run Ash resources, verify tenant permissions, execute the canonical
reactor pipeline, or validate a deployed manifest. Use platform integration
tests for those behaviors.

Use connector route tests for:

- provider request construction
- credentials and setting lookup
- transform output
- `ingest.canonical(...)` and `ingest.batch(...)` arguments
- partial failure handling
- pagination and checkpoint response shape
- log messages that operators depend on


---

# VendorBill

URL: https://backfill.io/docs/resources/vendor-bill/



---

# BillPayment

URL: https://backfill.io/docs/resources/bill-payment/



---

# Company settings

URL: https://backfill.io/docs/sdk/extensions/settings/

> Learn about Settings.get / getAll for company-configurable settings in your extension.


Settings are the company-configurable knobs your extension exposes to company admins. Declare defaults in the manifest's `config` field; the company admin can override them in the Backfill dashboard.

## Signatures

```typescript
Settings.get(key: string): any;
Settings.getAll(): Record<string, any>;
```

## Declaring defaults

```typescript
// backfill.config.ts
export default defineExtension({
  key: "tax-calcs",
  name: "Tax Calculations",
  config: {
    taxRate: 8.25,
    taxLabel: "Sales Tax",
    enableTaxOnInvoices: true,
    enableTaxOnSalesReceipts: true,
  },
});
```

## Reading

```typescript
import { Settings } from "@backfill-io/sdk";

const all = Settings.getAll();
if (!all.enableTaxOnInvoices) return null;

const rate = Settings.get("taxRate") ?? 8.25;
```

`Settings.getAll()` returns the merged map: manifest defaults overridden by per-installation values the admin set. `Settings.get(key)` is shorthand for `Settings.getAll()[key]`.

## `config` vs. `secrets`

| Goes in `config` | Goes in `secrets` |
|---|---|
| Knobs visible to the admin in the Backfill dashboard. | Encrypted credentials. |
| Plain JSON values: numbers, strings, booleans, arrays. | Strings, written via CLI or settings UI. |
| Returned by `Settings.getAll()` | Read with `Secrets.get(name)`; never returned to the dashboard read API. |

If a value is sensitive (an API key, a webhook signing secret), put it in [Secrets](../secrets/), not `config`.

## Settings schema for connectors

Connectors use a richer `connection.settingsSchema` (JSON Schema) instead of `config`. See [Connectors → Settings schema](../../connectors/settings-schema/). Plain extensions stick with `config`.

## When changes take effect

`config` defaults are part of the `backfill.config.ts` manifest. Changing them requires a redeploy. Admin overrides take effect immediately.


---

# Company secrets

URL: https://backfill.io/docs/sdk/extensions/secrets/

> Learn about encrypted credentials for companies, scoped per extension, accessed via Secrets.get / set / delete.


Use secrets for anything a company admin shouldn't see in plaintext: API keys, webhook signing secrets, OAuth tokens. Secrets are encrypted at rest and never returned to the Backfill read APIs.

## Signatures

```typescript
Secrets.get(name: string): string | null;
Secrets.set(name: string, value: string): void;
Secrets.delete(name: string): boolean;
Secrets.has(name: string): boolean;
Secrets.list(): string[];
```

## Declaring access

```typescript
permissions: {
  secrets: {
    stripe_api_key: ["read"],
    webhook_secret: ["read"],
  },
}
```

The verb model matches entities: `"read"` and `"write"`. A hook with only `"read"` cannot call `Secrets.set(...)`.

Secret names must match `^[a-z][a-z0-9_]{0,62}$` — lowercase, starts with a letter, underscores allowed.

## Reading

```typescript
const apiKey = Secrets.get("stripe_api_key");
if (!apiKey) {
  throw new Error("stripe_api_key is not configured");
}
```

`Secrets.get` returns `null` if the secret hasn't been set. Never log the value.

## Setting from inside the extension

If your extension grants `"write"` on a secret, you can rotate it from a hook, job, or route:

```typescript
Secrets.set("oauth_refresh_token", newToken);
```

Most extensions only need `"read"`. The dashboard / CLI is the canonical place to set secrets.

## Secrets via connector settings schema

For connectors, the JSON Schema in `connection.settingsSchema` can mark fields as `x-secret: true`:

```typescript
api_key: {
  type: "string",
  title: "Secret API key",
  "x-secret": true,
  "x-placeholder": "sk_live_...",
}
```

The dashboard renders the field as a password input and stores the value in the secret store keyed by the field name.

## Constraints

- No environment variables. There is no `process.env`.
- No remote secret stores (Vault, AWS Secrets Manager). The platform's secret store is the only one.
- Reads are synchronous and idempotent within a script.


---

# PurchaseOrder

URL: https://backfill.io/docs/resources/purchase-order/



---

# CreditMemo

URL: https://backfill.io/docs/resources/credit-memo/



---

# Glossary

URL: https://backfill.io/docs/sdk/concepts/glossary/

> Shared SDK terms for entities, records, documents, lines, and resources.


These terms apply across extension manifests, declaration files, runtime APIs, and platform docs:

| Term | Meaning |
|---|---|
| Entity | A canonical object type in Backfill, such as `Customer`, `Invoice`, or `Payment`. Extension manifests and declaration files use entity names because they declare against a type. |
| Record | One stored instance of an entity. Runtime APIs take an entity name plus an id to select the specific record. |
| Line | One stable row inside a line-bearing entity, such as one `Invoice.line_items` entry identified by `line_key`. |
| Document | A canonical business document with versioned payloads and lines. Line fields are supported on every line-bearing document — `Invoice`, `CreditMemo`, `SalesReceipt`, `RefundReceipt`, `VendorBill`, `Expense`, `PurchaseOrder`, `Quote`, `VendorCredit`, `SalesOrder`, and `Deposit`. |
| Resource | The server-side persistence/API implementation behind an entity. Extension authors generally interact with entities, not resources. |



---

# API routes

URL: https://backfill.io/docs/sdk/extensions/api-routes/

> Learn about HTTP endpoints under your extension's namespace.


API routes let external services (or your own UI) talk to your extension.

## File location

Files at `src/api/<path>.ts` auto-register as HTTP handlers at `/<path>` — mounted under your extension's namespace. The HTTP verb is the export name (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`).

| File | URL |
|---|---|
| `src/api/tax-summary.ts` | `/tax-summary` |
| `src/api/sync/customers.ts` | `/sync/customers` |
| `src/api/webhooks/stripe.ts` | `/webhooks/stripe` |

## A minimal route

```typescript
// src/api/tax-summary.ts
declare const TaxRecord: any;

export const GET = async function (ctx: {
  searchParams: Record<string, string>;
}) {
  const { start, end } = ctx.searchParams;

  if (!start || !end) {
    return {
      __api_response: true,
      status: 400,
      body: { error: "Missing required query parameters: start, end (YYYY-MM-DD)" },
    };
  }

  const records = TaxRecord.query({
    where: { _created_at: { gte: start, lte: end } },
  });

  return { period: { start, end }, records };
};
```

## The handler signature

The runtime injects a context with the parsed request:

```typescript
{
  searchParams: Record<string, string | string[]>;
  params: Record<string, string | string[]>;   // path parameters where supported
  body: any;
  rawBody: string;
  headers: Record<string, string>;
  context: { tenant: { id: string }, extension: { key: string } };
}
```

## Returning responses

### Plain object → 200 JSON

```typescript
return { ok: true, count: 42 };
```

### Explicit response object

```typescript
return {
  __api_response: true,
  status: 400,
  body: { error: "Missing param" },
};
```

## The `api` helper

The same shape, written more naturally:

```typescript
import { api } from "@backfill-io/sdk";

export const POST = api(async (request) => {
  if (!request.body?.email) {
    return api.badRequest("Email required");
  }
  return api.json({ ok: true });
});
```

`api` exposes:

```typescript
api(handler)                                // wraps a handler with type inference
api.json(data, { status })                  // 200 (or status) JSON
api.badRequest(message, data?)              // 400
api.notFound(message)                       // 404
api.forbidden(message)                      // 403
api.unauthorized(message)                   // 401
api.error(message, { status })              // generic
```

## Auth modes

Routes declare an auth mode via an exported `config`:

```typescript
export const config = { auth: "api_key" };
```

For plain extensions, two modes are accepted:

| Mode | Effect |
|---|---|
| `api_key` | Default. The platform requires a workspace API token in `Authorization: Bearer <token>`. |
| `public` | No auth. The handler is responsible for any verification (use sparingly). |

A third mode (`stripe_signature`, etc.) is used by [connector webhook routes](../../connectors/webhooks/), gated to connectors.

## Method exports

A single route file can declare multiple verbs:

```typescript
export const config = { auth: "api_key" };

export const GET = async (ctx) => { ... };
export const POST = api(async (req) => { ... });
```

At least one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE` must be exported, or deploy fails:

```
route must export at least one HTTP method handler (e.g. export const POST = api(...))
```


---

# Quote

URL: https://backfill.io/docs/resources/quote/



---

# SalesOrder

URL: https://backfill.io/docs/resources/sales-order/



---

# Scheduled jobs

URL: https://backfill.io/docs/sdk/extensions/jobs/

> Learn about scheduled work that runs on a cron expression.


Jobs run on a schedule. Each file is a separate job, with its own cron expression.

## File location

Files at `src/jobs/<name>.ts` auto-register on the next deploy. The filename (without `.ts`) is the job name — lowercase, kebab-friendly. Each file exports a cron `schedule` string and an async `run()` function.

| File | Job name |
|---|---|
| `src/jobs/weekly-tax-report.ts` | `weekly-tax-report` |
| `src/jobs/sync-balances.ts` | `sync-balances` |

## Required exports

```typescript
// src/jobs/weekly-tax-report.ts
import { Log } from "@backfill-io/sdk";

export const schedule = "0 8 * * 1";

export async function run() {
  // your work here
}
```

| Export | Type | Required |
|---|---|---|
| `schedule` | `string` (cron expression) | yes |
| `run` | `async function` | yes |
| `timezone` | `string` (IANA tz, default `"UTC"`) | no |
| `retry` | `number` (attempts, default `1`) | no |
| `timeout_ms` | `number` (default `30_000`) | no |

## Cron syntax

Standard 5-field cron (minute, hour, day-of-month, month, day-of-week). Invalid expressions fail at deploy:

```
src/jobs/weekly-tax-report.ts: invalid cron expression '0 8 ?'
```

Examples:

| Expression | Meaning |
|---|---|
| `0 * * * *` | Top of every hour. |
| `*/15 * * * *` | Every 15 minutes. |
| `0 8 * * 1` | 8am every Monday. |
| `0 0 1 * *` | Midnight on the 1st of every month. |

## Timezone

```typescript
export const schedule = "0 9 * * 1-5";
export const timezone = "America/New_York";
```

Unknown zones are rejected at deploy. `"UTC"` and `"Etc/UTC"` are pre-accepted; everything else must be a recognized IANA name.

## What the job can do

`run()` runs in a fresh sandbox context with the standard library: `Entity` queries, `Http` calls (against permitted hosts), `Log`, `Settings`, `Secrets`, and generated entity classes. Permissions are the manifest's.

## Manual trigger

```sh
backfill job run weekly-tax-report
```

For listing jobs:

```sh
backfill job list
```

## Idempotency

A job that fails partway is not rolled back — anything you wrote to entities stays written. If your job is non-idempotent, structure it so a retry is safe (cursor-based pagination, idempotency keys on outbound calls, dedupe checks before creates).


---

# Extension UI

URL: https://backfill.io/docs/sdk/extensions/ui/

> Build dashboard surfaces — full pages, contributions to existing entity pages, and the JSX component library that renders them.



---

# RefundReceipt

URL: https://backfill.io/docs/resources/refund-receipt/



---

# VendorCredit

URL: https://backfill.io/docs/resources/vendor-credit/



---

# Account

URL: https://backfill.io/docs/resources/account/



---

# Vendor

URL: https://backfill.io/docs/resources/vendor/



---

# JournalEntry

URL: https://backfill.io/docs/resources/journal-entry/



---

# Deposit

URL: https://backfill.io/docs/resources/deposit/



---

# BankTransfer

URL: https://backfill.io/docs/resources/bank-transfer/



---