@abloatai/ablo 0.3.0

package/docs/data-sources.md

@@ -0,0 +1,214 @@
+# Connect Your Database
+
+Every schema model has a backing store.
+
+By default, Ablo stores the rows for the models you declare. That makes Ablo the
+managed state store for those resources, the same way Stripe stores `Customer`
+and `PaymentIntent` objects that you create through Stripe's API.
+
+If you already have application tables and want those tables to remain
+canonical, attach a Data Source. Then Ablo coordinates the write and calls your
+app to commit it.
+
+Use the SDK with an API key:
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { schema } from './ablo.schema';
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
+Do not pass a database URL to `Ablo(...)`.
+
+## Backing Modes
+
+| Mode | Where rows live | What `create/update/delete` does | Use when |
+|---|---|---|---|
+| Ablo-managed | Ablo | Writes directly to Ablo's managed state store, then returns the confirmed row and fans out realtime deltas. | New collaborative/agent state that can live in Ablo. |
+| Data Source | Your app database | Sends a signed commit request to your route; your app writes its DB and returns canonical rows. | Existing app tables, regulated data, or teams that need their DB to stay canonical. |
+
+The SDK call is the same in both modes:
+
+```ts
+await ablo.tasks.create({ title: 'Draft launch plan', status: 'todo' });
+await ablo.tasks.update('task_123', { status: 'done' });
+const task = ablo.tasks.retrieve('task_123');
+```
+
+Only the backing store changes.
+
+Multiplayer behavior is the same in both modes. Writes made through
+`ablo.<model>.create/update/delete` are coordinated by Ablo, then confirmed rows
+fan out to subscribers. Direct database writes outside Ablo need Data Source
+events so connected humans and agents see the change.
+
+## When To Use A Data Source
+
+Use a Data Source only when your existing application database remains the
+source of truth and Ablo should coordinate writes against it.
+
+If you are migrating an app where every button already calls a backend endpoint,
+read [Integration Guide](./integration-guide.md) first, then
+[Existing Python Backend](./examples/existing-python-backend.md) for a concrete
+service-owned database example.
+
+## What Ablo Gives You
+
+When you add a Data Source in Ablo, you get:
+
+| Field | Purpose |
+|---|---|
+| Data Source URL | The public HTTPS route in your app that Ablo will call. |
+| Signing secret | Stored in your app as `ABLO_DATA_SOURCE_SIGNING_SECRET`; used to verify Ablo calls. |
+| Push events URL | Ablo endpoint your app can call when rows change outside Ablo. |
+| Status | Last successful request, last error, and delivery attempts. |
+
+The shape is the same as a production webhook integration:
+
+1. Add a Data Source URL in Ablo.
+2. Store the signing secret in your app.
+3. Expose one signed HTTP route from your app.
+4. Keep your database credentials in your app.
+
+```bash
+ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+```
+
+## Route
+
+```ts
+// app/api/ablo/source/route.ts
+import { dataSource } from '@ablo/sync-engine';
+import { schema } from '@/ablo.schema';
+import { db } from '@/db';
+
+export const POST = dataSource({
+  schema,
+  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+
+  authorize() {
+    return { db };
+  },
+
+  async commit({ operations, clientTxId, context }) {
+    const rows = await context.auth.db.transaction(async (tx) => {
+      await tx.idempotency.upsert({ key: clientTxId, operations });
+      return applyOperations(tx, operations);
+    });
+
+    return { rows };
+  },
+
+  tasks: {
+    async load({ id, context }) {
+      return context.auth.db.task.findUnique({ where: { id } });
+    },
+
+    async list({ query, context }) {
+      return context.auth.db.task.findMany({
+        take: query.limit ?? 100,
+      });
+    },
+  },
+});
+```
+
+Your app code still writes through the normal model API:
+
+```ts
+await ablo.tasks.update(
+  'task_123',
+  { status: 'done' },
+  { wait: 'confirmed', readAt: snap.stamp, onStale: 'reject' },
+);
+```
+
+## Commit Request
+
+When Ablo calls your Data Source, it sends a signed JSON request:
+
+```ts
+{
+  type: 'commit',
+  clientTxId: 'tx_...',
+  operations: [
+    {
+      type: 'UPDATE',
+      model: 'tasks',
+      id: 'task_123',
+      input: { status: 'done' },
+      readAt: 1042,
+      onStale: 'reject',
+    },
+  ],
+  scope: {
+    participantId: 'agent:triage',
+    participantKind: 'agent',
+    organizationId: 'org_123',
+    requiredSyncGroups: ['org:org_123'],
+    mode: 'live',
+  },
+}
+```
+
+Return canonical rows:
+
+```ts
+{
+  rows: [
+    { id: 'task_123', title: 'Fix docs', status: 'done' },
+  ],
+}
+```
+
+Use explicit `deltas` only when your source already computes canonical change
+events.
+
+## External Writes
+
+If your app changes data outside Ablo, return those changes from an `events`
+handler so connected humans and agents stay current:
+
+```ts
+export const POST = dataSource({
+  schema,
+  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+
+  async events({ cursor, limit, context }) {
+    const page = await context.auth.db.outbox.after(cursor, { limit });
+
+    return {
+      events: page.rows.map((row) => ({
+        id: row.id,
+        model: row.model,
+        entityId: row.entityId,
+        type: row.type,
+        data: row.data,
+        organizationId: row.organizationId,
+        clientTxId: row.clientTxId,
+        occurredAt: row.createdAt.getTime(),
+      })),
+      nextCursor: page.nextCursor,
+    };
+  },
+});
+```
+
+`clientTxId` lets Ablo drop SDK echoes that already produced a realtime update.
+Events without `clientTxId` are treated as external writes.
+
+## Security
+
+- Verify requests with `ABLO_DATA_SOURCE_SIGNING_SECRET`.
+- Keep database credentials in your app.
+- Dedupe commits by `clientTxId`.
+- Dedupe external events by event `id`.
+- Use HTTPS in production.
+
+The signing secret is not a database credential and does not give Ablo access to
+your database. It only lets your route verify that the request came from Ablo
+and was not modified in transit.

package/docs/examples/agent-human.md

@@ -0,0 +1,84 @@
+# Agent + Human
+
+A task-writing agent that yields when a human is editing the same task.
+
+## Scenario
+
+A product queue has tasks that humans and agents both update. They must not
+collide:
+
+- If the user is editing, the agent waits or yields.
+- If the agent is updating, the UI can show who is active.
+- If the task changes mid-run, the commit rejects instead of overwriting newer
+  state.
+
+## Schema-Backed Worker
+
+Use the same schema client the app uses. The worker loads the task, checks active
+intents, and writes through `ablo.tasks.update(...)`.
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+export async function markDone(taskId: string) {
+  await ablo.ready();
+
+  const [task] = await ablo.tasks.load({ where: { id: taskId } });
+  if (!task) return { status: 'not_found' };
+
+  const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
+  if (busy.length > 0) return { status: 'busy', intents: busy };
+
+  const snap = ablo.snapshot({ tasks: taskId });
+  const updated = await ablo.tasks.update(
+    taskId,
+    { status: 'done' },
+    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  );
+
+  return { status: 'done', task: updated };
+}
+```
+
+Advanced schema-less workers can use `Ablo({ apiKey }).agent(...)`, but that is
+not the first integration path.
+
+## UI
+
+```tsx
+'use client';
+
+import { useAblo } from '@ablo/sync-engine/react';
+
+export function TaskRow({ task: serverTask }: Props) {
+  const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
+  const intents = useAblo((ablo) =>
+    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
+  ) ?? [];
+  const agentActive = intents.some((i) => i.participantKind === 'agent');
+
+  return (
+    <div>
+      <span>{data.title}</span>
+      {agentActive ? <span>Agent is updating...</span> : null}
+    </div>
+  );
+}
+```
+
+## Why It Works
+
+- Intents are visible on read and over the live stream.
+- `ifBusy: 'wait'` lets agents wait for active work instead of racing.
+- `readAt` plus `onStale: 'reject'` turns mid-flight changes into typed errors.
+- Audit rows tie each accepted write back to the run that caused it.

package/docs/examples/ai-sdk-tool.md

@@ -0,0 +1,92 @@
+# AI SDK Tool
+
+Use AI SDK for the loop and Ablo for the state boundary inside the tool.
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z as schemaZ } from '@ablo/sync-engine/schema';
+import { streamText, tool } from 'ai';
+import { z } from 'zod';
+
+const schema = defineSchema({
+  tasks: model({
+    title: schemaZ.string(),
+    status: schemaZ.enum(['todo', 'doing', 'done']),
+    summary: schemaZ.string().optional(),
+  }),
+});
+
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+
+const updateTask = tool({
+  description: 'Update a task in the product database.',
+  inputSchema: z.object({
+    taskId: z.string(),
+    status: z.enum(['todo', 'doing', 'done']).optional(),
+    summary: z.string().optional(),
+  }),
+  execute: async ({ taskId, status, summary }) => {
+    await ablo.ready();
+
+    const [task] = await ablo.tasks.load({ where: { id: taskId } });
+    if (!task) return { ok: false, reason: 'not_found' };
+
+    const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
+    if (busy.length > 0) {
+      await ablo.intents.waitFor(
+        { resource: 'tasks', id: taskId },
+        { timeout: 30_000 },
+      );
+    }
+
+    const snap = ablo.snapshot({ tasks: taskId });
+    const intent = await ablo.intents.create({
+      target: { resource: 'tasks', id: taskId, field: 'status' },
+      action: 'update',
+    });
+
+    try {
+      const updated = await ablo.tasks.update(
+        taskId,
+        {
+          status: status ?? task.status,
+          summary: summary ?? task.summary,
+        },
+        {
+          intent,
+          readAt: snap.stamp,
+          onStale: 'reject',
+          wait: 'confirmed',
+        },
+      );
+
+      return { ok: true, task: updated };
+    } finally {
+      await intent.release();
+    }
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages, model } = await req.json();
+
+  return streamText({
+    model,
+    messages,
+    tools: { updateTask },
+  }).toUIMessageStreamResponse();
+}
+```
+
+The important part is not the model provider. The important part is that the
+tool:
+
+- loads the latest task,
+- checks active intent,
+- writes with `readAt`,
+- rejects stale state,
+- waits for server confirmation.
+

package/docs/examples/existing-python-backend.md

@@ -0,0 +1,249 @@
+# Existing Python Backend
+
+Use this path when a product already has a Python API server and every button
+currently calls an application endpoint.
+
+The goal is not to replace the backend. Keep the Python service layer and
+database as the source of truth. Add Ablo as the shared write path for records
+that need multiplayer now and agent-safe writes later.
+
+This also applies to any API-backed app, not only Python. A product like a YC
+company's existing dashboard can keep its current endpoint/service/database
+shape and migrate one coordinated resource at a time.
+
+```txt
+Browser UI
+  -> Ablo model write
+  -> Python Data Source endpoint
+  -> existing Python service layer
+  -> app database
+  -> Ablo realtime fanout
+  -> browser UI and agents
+```
+
+## 1. Declare The Shared Models
+
+Create a schema for the records that need realtime coordination.
+
+```ts
+// web/ablo.schema.ts
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+export const schema = defineSchema({
+  tasks: model({
+    id: z.string(),
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+    updatedAt: z.string(),
+  }),
+});
+```
+
+```ts
+// web/ablo.ts
+import Ablo from '@ablo/sync-engine';
+import { schema } from './ablo.schema';
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
+Mount the React provider near the app root so client components can subscribe to
+model resources without importing server credentials.
+
+```tsx
+// web/app/providers.tsx
+'use client';
+
+import { AbloProvider } from '@ablo/sync-engine/react';
+import { schema } from '@/ablo.schema';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <AbloProvider schema={schema}>{children}</AbloProvider>;
+}
+```
+
+## 2. Add Live Reads In The UI
+
+Keep the first render backed by the existing Python endpoint. After that,
+subscribe to the same model resource Ablo writes through.
+
+```tsx
+'use client';
+
+import { useAblo } from '@ablo/sync-engine/react';
+
+export function TaskRow({ task: serverTask }: { task: Task }) {
+  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
+  const intents = useAblo((ablo) =>
+    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
+  ) ?? [];
+  const busy = intents.length > 0;
+
+  return (
+    <button disabled={busy || task.status === 'done'}>
+      {busy ? 'Someone is editing' : task.title}
+    </button>
+  );
+}
+```
+
+No string model key is needed in the first example. The selector reads from
+`ablo.tasks`, so React uses the same model resource as writes and agents.
+
+## 3. Add One Python Data Source Endpoint
+
+In Ablo, configure the Data Source URL:
+
+```txt
+https://api.example.com/api/ablo/source
+```
+
+Store the signing secret in the Python server:
+
+```bash
+ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+```
+
+Then expose one route that verifies the signed request and calls the existing
+service functions.
+
+```py
+# app/ablo_source.py
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+from fastapi import APIRouter, HTTPException, Request
+
+from app.services.tasks import get_task, list_tasks, apply_task_operations
+
+router = APIRouter()
+
+
+def verify_ablo_signature(request: Request, raw_body: bytes) -> None:
+    secret = os.environ["ABLO_DATA_SOURCE_SIGNING_SECRET"].encode()
+    message_id = request.headers.get("webhook-id")
+    timestamp = request.headers.get("webhook-timestamp")
+    signature_header = request.headers.get("webhook-signature", "")
+
+    if not message_id or not timestamp or not signature_header:
+        raise HTTPException(status_code=401, detail="missing signature")
+
+    signed_at = int(timestamp)
+    if abs(int(time.time() * 1000) - signed_at) > 5 * 60 * 1000:
+        raise HTTPException(status_code=401, detail="expired signature")
+
+    payload = message_id.encode() + b"." + timestamp.encode() + b"." + raw_body
+    expected = base64.b64encode(
+        hmac.new(secret, payload, hashlib.sha256).digest()
+    ).decode()
+
+    presented = [
+        part.removeprefix("v1,")
+        for part in signature_header.split()
+        if part.startswith("v1,")
+    ]
+
+    if not any(hmac.compare_digest(expected, value) for value in presented):
+        raise HTTPException(status_code=401, detail="invalid signature")
+
+
+@router.post("/api/ablo/source")
+async def ablo_source(request: Request):
+    raw_body = await request.body()
+    verify_ablo_signature(request, raw_body)
+    body = json.loads(raw_body)
+
+    if body["type"] == "load":
+        if body["model"] == "tasks":
+            return {"row": await get_task(body["id"])}
+
+    if body["type"] == "list":
+        if body["model"] == "tasks":
+            return {"rows": await list_tasks(body.get("query", {}))}
+
+    if body["type"] == "commit":
+        rows = await apply_task_operations(
+            operations=body["operations"],
+            client_tx_id=body.get("clientTxId"),
+            scope=body.get("scope", {}),
+        )
+        return {"rows": rows}
+
+    raise HTTPException(status_code=400, detail="unsupported request")
+```
+
+`apply_task_operations` should reuse the same transaction and validation logic
+the existing Python endpoints already use. Dedupe by `clientTxId` so retries are
+safe.
+
+## 4. Move Buttons Gradually
+
+Existing button path:
+
+```txt
+Button -> Python endpoint -> service -> database
+```
+
+Target button path:
+
+```txt
+Button -> ablo.tasks.update(...)
+Ablo -> Python Data Source endpoint
+Python service -> database
+Ablo -> realtime fanout and receipt
+```
+
+The app does not need a flag-day rewrite. Move one resource at a time.
+
+```ts
+const snap = ablo.snapshot({ tasks: taskId });
+
+await ablo.tasks.update(
+  taskId,
+  { status: 'done' },
+  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+);
+```
+
+Use `readAt` and `onStale: 'reject'` for actions that depend on state the user
+or agent already saw.
+
+## 5. Report Direct Database Writes
+
+Some writes will still happen through old Python endpoints, cron jobs, admin
+tools, or imports. Those bypass Ablo until the backend reports them.
+
+Add an outbox table in Python and expose it through Data Source `events`:
+
+```txt
+old Python endpoint -> service -> database -> outbox row
+Ablo polls events -> realtime fanout
+```
+
+Each event needs a stable event id, model name, entity id, event type, row data,
+and timestamp. If the change originated from an Ablo commit, include the same
+`clientTxId` so Ablo can ignore its own echo.
+
+## 6. Add Agents Later
+
+Agents use the same model API as the UI:
+
+```ts
+const [task] = await ablo.tasks.load({ where: { id: taskId } });
+const snap = ablo.snapshot({ tasks: taskId });
+
+await ablo.tasks.update(
+  taskId,
+  { status: 'done' },
+  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+);
+```
+
+That is the point of the migration: humans and agents share one write contract,
+while the Python backend remains the canonical business logic and database owner.