@abloatai/ablo 0.3.0

package/examples/data-source/ablo-driver.ts

@@ -0,0 +1,89 @@
+/**
+ * Ablo-Cloud-side request driver.
+ *
+ * This file is what Ablo Cloud runs in production. Customers DON'T
+ * write it — they only see signed POSTs hit their endpoint. We
+ * publish it here so the example can show the full round-trip
+ * locally without standing up the cloud.
+ *
+ * In production:
+ *   - Ablo Cloud holds the signing secret in its config
+ *   - It signs each outbound POST with `signAbloSourceRequest`
+ *   - The customer's `dataSource(...)` handler verifies the signature
+ *   - The response feeds back into Ablo Cloud's hosted realtime layer
+ *
+ * Here we wire signer -> in-process handler with no network hop, so
+ * `npx tsx run.ts` works without ports, env, or cloud credentials.
+ */
+
+import {
+  signAbloSourceRequest,
+  type Ablo,
+} from '@ablo/sync-engine';
+
+export interface AbloDriverOptions {
+  /**
+   * In-process target. Production calls a URL; the example calls
+   * the handler directly so there's no http port to manage.
+   */
+  readonly handler: (request: Request) => Promise<Response>;
+  /** Same secret the customer's `dataSource(...)` is configured with. */
+  readonly signingSecret: string;
+}
+
+export class AbloDriver {
+  private messageCounter = 0;
+
+  constructor(private readonly options: AbloDriverOptions) {}
+
+  async load(model: string, id: string): Promise<unknown> {
+    return this.send({ type: 'load', model, id });
+  }
+
+  async list(model: string, query?: Ablo.Source.Operation['input']) {
+    return this.send({ type: 'list', model, query: query ?? {} });
+  }
+
+  async commit(operations: readonly Ablo.Source.Operation[], clientTxId?: string) {
+    return this.send({
+      type: 'commit',
+      operations,
+      ...(clientTxId ? { clientTxId } : {}),
+    });
+  }
+
+  async events(cursor?: string, limit?: number) {
+    return this.send({
+      type: 'events',
+      ...(cursor !== undefined ? { cursor } : {}),
+      ...(limit !== undefined ? { limit } : {}),
+    });
+  }
+
+  // Builds the exact signed Request shape the production Ablo Cloud
+  // would send. The customer's handler can't tell this apart from a
+  // real cloud-originated request.
+  private async send(payload: Record<string, unknown>): Promise<unknown> {
+    this.messageCounter += 1;
+    const body = JSON.stringify(payload);
+    const messageId = `msg_${Date.now()}_${this.messageCounter}`;
+    const signed = await signAbloSourceRequest({
+      secret: this.options.signingSecret,
+      body,
+      messageId,
+    });
+    const request = new Request('http://example.test/api/ablo/source', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...signed.headers },
+      body,
+    });
+    const response = await this.options.handler(request);
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(
+        `Data Source POST ${payload.type} failed: ${response.status} ${text}`,
+      );
+    }
+    return response.json();
+  }
+}

package/examples/data-source/customer-server.ts

@@ -0,0 +1,208 @@
+/**
+ * Customer-side Data Source endpoint.
+ *
+ * This file is what a customer running their own backend writes. It
+ * holds the canonical data — in production it's their Postgres,
+ * Mongo, or whatever — and exposes one handler that Ablo Cloud calls
+ * over HTTP for `load`, `list`, `commit`, and `events`.
+ *
+ * `dataSource(...)` returns `(req: Request) => Promise<Response>` —
+ * a Fetch-API handler. Drop it into Next.js (`export const POST`),
+ * Hono, Cloudflare Workers, or a thin `http.createServer` wrapper.
+ *
+ * This example uses an in-memory `Map` as the "database" so it runs
+ * with zero setup. A real customer swaps the Map calls for ORM calls
+ * inside a transaction. The shape of the handlers stays identical.
+ */
+
+import Ablo, { dataSource } from '@ablo/sync-engine';
+import { schema } from './schema';
+
+type TaskRow = {
+  id: string;
+  title: string;
+  status: 'todo' | 'doing' | 'done';
+  assignee?: string;
+};
+
+// Stand-in for the customer's real database. Map keyed by row id.
+const taskStore = new Map<string, TaskRow>();
+
+// Outbox table. In production this is a `tasks_outbox` Postgres table
+// populated by triggers or service code. Ablo polls `events` to fan
+// out changes that didn't originate from an Ablo commit.
+type OutboxRow = {
+  id: string;
+  entityId: string;
+  type: Ablo.Source.Operation['type'];
+  data: TaskRow | null;
+  clientTxId?: string;
+};
+const outbox: OutboxRow[] = [];
+let outboxSequence = 0;
+
+// Seed one row so the example's first `load` returns something.
+taskStore.set('task_seed', {
+  id: 'task_seed',
+  title: 'Seeded by customer database',
+  status: 'todo',
+});
+
+/**
+ * The full Data Source handler. One symbol exposes load/list/commit/
+ * events for every model the schema declares.
+ *
+ * In Next.js:
+ *
+ * ```ts
+ * // app/api/ablo/source/route.ts
+ * export const POST = handleAbloSource;
+ * ```
+ *
+ * In Hono / Cloudflare Workers:
+ *
+ * ```ts
+ * app.post('/api/ablo/source', (c) => handleAbloSource(c.req.raw));
+ * ```
+ */
+export const handleAbloSource = dataSource({
+  schema,
+
+  // The signing secret pairs with what Ablo Cloud is configured with.
+  // Wrong secret -> 401 with `source_signature_invalid`. Passing a
+  // function (instead of the env value directly) re-reads the secret
+  // on every request — convenient for rotation, and required by the
+  // example because `run.ts` configures the env after this module is
+  // imported.
+  signingSecret: () => {
+    const secret = process.env.ABLO_DATA_SOURCE_SIGNING_SECRET;
+    if (!secret) {
+      throw new Error(
+        'ABLO_DATA_SOURCE_SIGNING_SECRET is not set — refusing to accept unsigned requests',
+      );
+    }
+    return secret;
+  },
+
+  // `authorize` runs before any handler. Use it to map the signed
+  // request to your tenant/user context. The returned value lands on
+  // `context.auth` inside every model handler. This example just
+  // returns `{}` since the in-memory store is single-tenant.
+  authorize() {
+    return {};
+  },
+
+  tasks: {
+    load({ id }) {
+      return taskStore.get(id) ?? null;
+    },
+
+    list({ query }) {
+      const all = Array.from(taskStore.values());
+      const start = query.cursor ? Number(query.cursor) : 0;
+      const limit = query.limit ?? 50;
+      const page = all.slice(start, start + limit);
+      return {
+        rows: page,
+        nextCursor:
+          start + page.length < all.length
+            ? String(start + page.length)
+            : undefined,
+      };
+    },
+
+    // The commit handler applies every operation in the customer's
+    // own transaction. The example uses a synchronous in-memory
+    // update; the surrounding `apply` helper shows where you would
+    // open `db.transaction(async (tx) => { ... })`.
+    commit({ operations, clientTxId }) {
+      const rows: TaskRow[] = [];
+      for (const op of operations) {
+        const row = applyOperation(op, clientTxId);
+        if (row) rows.push(row);
+      }
+      return { rows };
+    },
+  },
+
+  // `events` lets Ablo learn about writes that bypassed Ablo —
+  // cron jobs, dashboards, batch imports. Each call drains a batch
+  // from the outbox and reports the cursor to resume from.
+  events({ cursor, limit }) {
+    const start = cursor ? Number(cursor) : 0;
+    const cap = limit ?? 100;
+    const slice = outbox.slice(start, start + cap);
+    const events = slice.map((row) => ({
+      id: row.id,
+      model: 'tasks',
+      entityId: row.entityId,
+      type: row.type,
+      data: row.data,
+      ...(row.clientTxId ? { clientTxId: row.clientTxId } : {}),
+    }));
+    const nextCursor =
+      start + slice.length < outbox.length
+        ? String(start + slice.length)
+        : undefined;
+    return { events, ...(nextCursor !== undefined ? { nextCursor } : {}) };
+  },
+});
+
+function applyOperation(
+  op: Ablo.Source.Operation,
+  clientTxId: string | undefined,
+): TaskRow | null {
+  if (op.model !== 'tasks') return null;
+  const id = op.id ?? `task_${Math.random().toString(36).slice(2, 10)}`;
+
+  if (op.type === 'CREATE') {
+    const row: TaskRow = {
+      id,
+      title: String(op.input?.title ?? ''),
+      status:
+        (op.input?.status as TaskRow['status'] | undefined) ?? 'todo',
+      ...(op.input?.assignee
+        ? { assignee: String(op.input.assignee) }
+        : {}),
+    };
+    taskStore.set(id, row);
+    appendOutbox({ entityId: id, type: 'CREATE', data: row, clientTxId });
+    return row;
+  }
+
+  if (op.type === 'UPDATE') {
+    const existing = taskStore.get(id);
+    if (!existing) return null;
+    const next: TaskRow = { ...existing, ...(op.input as Partial<TaskRow>) };
+    taskStore.set(id, next);
+    appendOutbox({ entityId: id, type: 'UPDATE', data: next, clientTxId });
+    return next;
+  }
+
+  if (op.type === 'DELETE') {
+    const existing = taskStore.get(id);
+    if (!existing) return null;
+    taskStore.delete(id);
+    appendOutbox({ entityId: id, type: 'DELETE', data: null, clientTxId });
+    return existing;
+  }
+
+  return null;
+}
+
+function appendOutbox(input: Omit<OutboxRow, 'id'>): void {
+  outboxSequence += 1;
+  outbox.push({ id: `evt_${outboxSequence}`, ...input });
+}
+
+// Exposed for the orchestrator's `run.ts`. A real customer doesn't
+// need this — it's a back door for the demo to verify state.
+export function _inspectStore(): {
+  rows: TaskRow[];
+  outboxSize: number;
+} {
+  return {
+    rows: Array.from(taskStore.values()),
+    outboxSize: outbox.length,
+  };
+}

package/examples/data-source/run.ts

@@ -0,0 +1,101 @@
+/**
+ * End-to-end Data Source demo.
+ *
+ * Run:
+ *
+ *   cd packages/sync-engine/examples
+ *   npx tsx data-source/run.ts
+ *
+ * What this proves:
+ *
+ *   1. Ablo Cloud's signer + the customer's verifier interop. A wrong
+ *      secret produces `source_signature_invalid`.
+ *   2. `load`, `list`, `commit`, and `events` all flow through the
+ *      same Fetch-API handler.
+ *   3. The customer's "database" (here a Map) holds canonical rows.
+ *      Ablo never sees them directly — only via the contract.
+ *   4. Writes that touch the customer DB show up on the next `events`
+ *      poll so Ablo Cloud can fan them out to other clients.
+ */
+
+import { handleAbloSource, _inspectStore } from './customer-server';
+import { AbloDriver } from './ablo-driver';
+
+const SIGNING_SECRET =
+  process.env.ABLO_DATA_SOURCE_SIGNING_SECRET ?? 'whsec_example_secret_do_not_use_in_prod';
+
+// `dataSource()` reads `options.signingSecret` at construction; we
+// re-export the same value to the driver so signer and verifier agree.
+// In production this is one secret shared between Ablo Cloud config
+// and the customer's environment.
+process.env.ABLO_DATA_SOURCE_SIGNING_SECRET = SIGNING_SECRET;
+
+async function main() {
+  const driver = new AbloDriver({
+    handler: handleAbloSource,
+    signingSecret: SIGNING_SECRET,
+  });
+
+  log('--- 1. load (existing seeded row) ---');
+  const seeded = await driver.load('tasks', 'task_seed');
+  log('loaded:', seeded);
+
+  log('\n--- 2. commit (CREATE + UPDATE in one batch) ---');
+  const committed = await driver.commit(
+    [
+      {
+        type: 'CREATE',
+        model: 'tasks',
+        id: 'task_new',
+        input: { title: 'Wire the data source', status: 'todo' },
+      },
+      {
+        type: 'UPDATE',
+        model: 'tasks',
+        id: 'task_seed',
+        input: { status: 'doing', assignee: 'alice' },
+      },
+    ],
+    'cltx_demo_1',
+  );
+  log('committed rows:', committed);
+
+  log('\n--- 3. list (all tasks after commit) ---');
+  const listed = await driver.list('tasks');
+  log('listed:', listed);
+
+  log('\n--- 4. events (outbox feed for cross-channel writes) ---');
+  const events = await driver.events();
+  log('events:', events);
+
+  log('\n--- 5. signature failure (wrong secret) ---');
+  const badDriver = new AbloDriver({
+    handler: handleAbloSource,
+    signingSecret: 'whsec_wrong_secret',
+  });
+  try {
+    await badDriver.load('tasks', 'task_seed');
+    throw new Error('expected signature failure');
+  } catch (err) {
+    log('rejected as expected:', (err as Error).message);
+  }
+
+  log('\n--- final customer DB state ---');
+  log(_inspectStore());
+}
+
+function log(...args: unknown[]) {
+  // Pretty-print objects so the demo output reads cleanly.
+  console.log(
+    ...args.map((arg) =>
+      typeof arg === 'object' && arg !== null
+        ? JSON.stringify(arg, null, 2)
+        : arg,
+    ),
+  );
+}
+
+main().catch((err) => {
+  console.error('data-source example failed:', err);
+  process.exit(1);
+});

package/examples/data-source/schema.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared schema for the Data Source example.
+ *
+ * The schema is the contract between three sides:
+ *
+ *   1. The application UI — `ablo.tasks.update(...)`.
+ *   2. The Ablo Cloud — translates writes into signed POSTs.
+ *   3. The customer's Data Source endpoint — applies them to its own
+ *      database.
+ *
+ * All three import the SAME schema file. Adding a column on either
+ * side without the other is a compile error.
+ */
+
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+export const schema = defineSchema({
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+    assignee: z.string().optional(),
+  }),
+});
+
+export type Schema = typeof schema;

package/examples/quickstart.ts

@@ -0,0 +1,54 @@
+/**
+ * Quickstart — schema-backed state coordination.
+ *
+ * Run:
+ *
+ *   ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+ */
+
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+  }),
+});
+
+async function getWeather(location: string): Promise<string> {
+  return `Light rain in ${location}, 13C`;
+}
+
+async function main() {
+  const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+  const location = process.env.WEATHER_LOCATION ?? 'Stockholm';
+
+  try {
+    await ablo.ready();
+
+    const created = await ablo.weatherReports.create({
+      location,
+      status: 'pending',
+    });
+
+    const updated = await ablo.weatherReports.update(created.id, {
+      status: 'ready',
+      forecast: await getWeather(created.location),
+    });
+
+    console.log('updated', {
+      id: updated.id,
+      status: updated.status,
+      forecast: updated.forecast,
+    });
+  } finally {
+    await ablo.dispose();
+  }
+}
+
+main().catch((err) => {
+  console.error('quickstart failed:', err);
+  process.exit(1);
+});

package/examples/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/llms.txt

@@ -0,0 +1,143 @@
+# Ablo
+
+Ablo is the state coordination layer for apps where humans and agents edit the same data.
+
+Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
+
+## Use this API
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  tasks: model({
+    id: z.string(),
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+    summary: z.string().optional(),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
+if (!task) throw new Error('Task not found');
+
+const intents = ablo.intents.list({ resource: 'tasks', id: 'task_123' });
+if (intents.length > 0) {
+  await ablo.intents.waitFor({ resource: 'tasks', id: 'task_123' }, { timeout: 30_000 });
+}
+
+const snap = ablo.snapshot({ tasks: 'task_123' });
+const updated = await ablo.tasks.update(
+  'task_123',
+  { status: 'done', summary: await summarize(task) },
+  {
+    readAt: snap.stamp,
+    onStale: 'reject',
+    wait: 'confirmed',
+  },
+);
+```
+
+That is the normal app path: declare models in a schema, then use `ablo.<model>.load(...)`, `ablo.<model>.retrieve(...)`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`.
+
+For full integrations, use `integration-guide` as the canonical doc. It covers
+the same model API across Ablo-managed state, Data Source-backed app databases,
+React selectors, multiplayer, and future agent workers.
+
+`ablo.<model>.list(...)` and `count(...)` are synchronous local reads. They
+accept `where`, `filter`, `orderBy`, `limit`, `offset`, and `scope`; scope
+defaults to `'live'`, with `'archived'` and `'all'` for lifecycle-aware reads.
+
+Advanced schema-less agents exist for workers that cannot import the app schema,
+but do not teach that path first.
+
+React reads should use selector `useAblo`: `useAblo((ablo) => ablo.tasks.retrieve(id))`.
+Use zero-argument `useAblo()` only when a component needs the client for an
+event handler or effect. Treat `useQuery`, `useOne`, `useReader`, and
+`useMutate` as compatibility hooks for older string-keyed integrations, not the
+first integration path.
+
+## Multiplayer
+
+Multiplayer is not a separate mode. When human UI, server actions, and agents use
+the same schema client and write through `ablo.<model>`, Ablo coordinates the
+shared resource stream: confirmed deltas fan out to subscribers, active intents
+are visible, and stale writes can be rejected with `readAt`.
+
+If an app writes directly to its own database outside Ablo, that write bypasses
+coordination until the app reports it through Data Source events.
+
+## Nouns
+
+- `Model resource` is the typed `ablo.<model>` object generated from schema.
+- `Intent` declares active work on a resource so humans and agents can coordinate.
+- `Commit` is the durable protocol write behind `ablo.<model>.update(...)`.
+- `Receipt` confirms the commit.
+- `Capability` scopes what an agent may do. `agent.run(...)` handles the common case.
+- `Task` is one agent run, with audit and cost attribution.
+
+## Busy Behavior
+
+Reads never silently block. Pass `ifBusy: 'return'` to receive active intents, `ifBusy: 'fail'` to throw `AbloBusyError`, or `ifBusy: 'wait'` to wait until the active intent clears.
+
+Schema clients wait from the realtime intent stream. Schema-less HTTP callers must provide an explicit `busyPollInterval` when using `ifBusy: 'wait'`; Ablo does not hide a hard-coded polling loop.
+
+Use `busyTimeout` only as a maximum wait, not as the coordination mechanism.
+
+## Guarantees
+
+`wait: 'confirmed'` means the server accepted the write. Schema model writes are optimistic by default; server rejection rolls back local state. Use `snapshot(...)` plus `readAt` and `onStale: 'reject'` to prevent lost updates.
+
+Intents are coordination signals, not database locks. Capabilities and tasks are real protocol primitives, but most users let the SDK manage them through schema-backed writes or advanced `agent.run(...)`.
+
+All SDK errors extend `AbloError`. Important classes: `AbloBusyError`, `AbloStaleContextError`, `AbloAuthenticationError`, `AbloPermissionError`, `AbloRateLimitError`, `AbloIdempotencyError`, `AbloConnectionError`, `AbloValidationError`, and `AbloServerError`.
+
+## Schema Scope
+
+Teach schema as model fields and relations first. Advanced schema helpers such as `mutable`, `readOnly`, `field`, `indexed`, queries, and load strategies exist for offline/cache/indexing-heavy apps, but they should not be the first concept a new integration sees.
+
+## Storage Boundary
+
+Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_API_KEY`.
+
+Every schema model has a backing store. By default, Ablo stores rows for declared models, so `ablo.<model>.create/update/delete` write to Ablo-managed state. If the customer database is canonical, add a Data Source URL in Ablo, store `ABLO_DATA_SOURCE_SIGNING_SECRET` in the app, then expose a signed `dataSource({ schema, signingSecret, load, list, commit, events })` route from the customer app. Customer-owned app database credentials stay private.
+
+Use `dataSource` from the root import:
+
+```ts
+import { dataSource } from '@ablo/sync-engine';
+```
+
+## Sandboxes
+
+Public `/sandbox` is a deterministic visual demo. It should teach shared state,
+intents, stale-write rejection, receipts, and deltas, but it does not use a real
+API key. It also exposes a Claude Code / Codex handoff prompt. Prefer that shape
+when an agent is asked to "make Ablo work" in an existing app.
+
+Authenticated org sandboxes are real test environments. Treat the default
+sandbox like Stripe test mode: it has an isolated sync group prefix and mints
+`sk_test_*` keys. Extra sandboxes can start blank or copy live configuration.
+Resetting a sandbox creates a clean future stream without touching live data.
+Use `sk_live_*` only for production.
+
+For coding agents, the sandbox success path is: pick one shared resource,
+declare schema, create the Ablo client, replace one direct mutation with a typed
+`ablo.<model>.update(...)`, use selector `useAblo` for live reads, and add a
+two-writer stale/intent smoke test.
+
+## Public Surface
+
+Import from these public paths only:
+
+- `@ablo/sync-engine` — `Ablo`, errors, typed model resources, intents, `dataSource`, and advanced protocol resources.
+- `@ablo/sync-engine/schema` — schema DSL.
+- `@ablo/sync-engine/react` — React provider and hooks.
+- `@ablo/sync-engine/testing` — test harnesses and mocks.
+
+Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, `/source`, or internal subpaths.
+
+Canonical docs to read before integrating: `quickstart`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`.