@obsidianlabs/writeback-worker

Cloudflare Worker backend for writeback-capable internal tools. Ships with D1 and MotherDuck storage adapters, Cloudflare Access and magic-link auth, optimistic concurrency, and audit logging.

Install

pnpm add @obsidianlabs/writeback-worker

Usage

// worker/src/index.ts
import { createWritebackApp, defineEntity } from "@obsidianlabs/writeback-worker";
import { z } from "zod";

const invoice = defineEntity({
  type: "invoice",
  primaryKey: "invoice_id",
  overlay: {
    fields: {
      status: z.enum(["open", "disputed", "paid"]).nullable(),
      notes: z.string().max(2000).nullable(),
    },
    precedence: {
      status: "sticky",
    },
  },
  audit: true,
});

export default createWritebackApp({
  entities: [invoice],
});

API Routes (auto-generated per entity)

| Method | Path | Description | |---|---|---| | GET | /api/:type | List with optional query filters | | GET | /api/:type/:id | Get single (merged pipeline + overlay) | | POST | /api/:type | Create overlay (requires Idempotency-Key header) | | PATCH | /api/:type/:id | Partial update (requires If-Match + Idempotency-Key) | | DELETE | /api/:type/:id | Delete overlay (requires If-Match) | | GET | /api/:type/:id/audit | Audit history | | GET | /api/health | Health check |

Environment Variables

Backend selection

| Var | Values | Default | |---|---|---| | WRITEBACK_BACKEND | d1, motherduck | d1 | | WRITEBACK_PIPELINE_SOURCE | none, d1, motherduck | none | | WRITEBACK_AUTH_PROVIDER | access, magic-link | magic-link |

D1 (Wrangler bindings)

| Binding | Required when | |---|---| | OVERLAY_DB | WRITEBACK_BACKEND=d1 | | PIPELINE_DB | WRITEBACK_PIPELINE_SOURCE=d1 |

MotherDuck

| Var | Required when | |---|---| | WRITEBACK_MD_HOST | backend or pipeline = motherduck | | WRITEBACK_MD_DATABASE | backend or pipeline = motherduck | | MD_RW_TOKEN | backend or pipeline = motherduck |

Cloudflare Access

| Var | Required when | |---|---| | WRITEBACK_ACCESS_TEAM_DOMAIN | WRITEBACK_AUTH_PROVIDER=access | | WRITEBACK_ACCESS_AUD | WRITEBACK_AUTH_PROVIDER=access |

Magic Link

| Var | Required when | |---|---| | WRITEBACK_JWT_SECRET | WRITEBACK_AUTH_PROVIDER=magic-link | | WRITEBACK_EMAIL_FROM | WRITEBACK_AUTH_PROVIDER=magic-link | | WRITEBACK_EMAIL_ALLOWLIST | WRITEBACK_AUTH_PROVIDER=magic-link | | RESEND_API_KEY | magic-link in production | | WRITEBACK_EMAIL_DEV_MODE | set to true to log links to console |

License

MIT