Integration Guide

import Ablo from '@abloatai/ablo';
import { defineSchema, model, z } from '@abloatai/ablo/schema';

schema -> ablo.<model>.list(...) -> ablo.<model>.update(...)

Add Ablo to this app for one model that humans and agents both edit.
Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
wait: 'confirmed' }), and add a smoke test for two concurrent writers.

// src/ablo/schema.ts
import { defineSchema, model, z } from '@abloatai/ablo/schema';

export const schema = defineSchema(
  {
    weatherReports: model({
      // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy)
      // are SDK-provided automatically — never declare them. Declare only your
      // own fields.
      projectId: z.string(),
      location: z.string(),
      status: z.enum(['pending', 'ready']),
      assigneeId: z.string().nullable(),
    }),
  },
  {
    // Identity-anchored sync-group roles. The server walks these to build each
    // participant's allowed subscription set from the resolved identity context.
    // `kind` is the group prefix; `source` is the identity field to read — both
    // consumer-controlled, no hardcoded `org:` / `user:` convention anywhere in
    // the engine. Pure data (no closures), so the schema stays JSON-serializable.
    // Omit `identityRoles` entirely if you don't need identity-derived scoping.
    identityRoles: [
      identityRole({ kind: 'org', source: 'organizationId' }),
      identityRole({ kind: 'user', source: 'userId' }),
    ],
  }
);

model(
  {
    /* fields */
  },
  /* relations */ {},
  {
    // Axis 1 — `policy`: who may READ a row (tenant isolation / RLS). A
    // row-local `organization_id` column is the default, so you omit this for
    // normal tables; set it only for the exceptions (parent-inherited / global).

    // Axis 2 — `groups`: which sync-group CHANNELS a row fans into.
    // Scope root: rows form the group `matter:<id>`. Children point at it with
    // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
    groups: { root: 'matter' },
  }
);

// src/ablo.ts
import Ablo from '@abloatai/ablo';
import { schema } from './ablo/schema';

export const ablo = Ablo({
  schema,
  apiKey: process.env.ABLO_API_KEY,
});

// src/ablo-client.ts
import Ablo from '@abloatai/ablo';
import { schema } from '@/ablo/schema';

// The browser never holds the API key. The client mints a short-lived token
// from your session route (see below) and refreshes it before expiry.
export const ablo = Ablo({
  schema,
  authEndpoint: '/api/ablo-session',
});

// app/providers.tsx
'use client';

import { AbloProvider } from '@abloatai/ablo/react';
import { ablo } from '@/ablo-client';

export function Providers({ children }: { children: React.ReactNode }) {
  return <AbloProvider client={ablo}>{children}</AbloProvider>;
}

// app/api/ablo-session/route.ts
import Ablo from '@abloatai/ablo';
import { schema } from '@/ablo/schema';
import { auth } from '@/auth';

export const runtime = 'nodejs';

const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });

export async function POST() {
  const session = await auth(); // your own auth — returns the signed-in user
  const { token } = await sync.sessions.create({ user: { id: session.userId } });
  return Response.json({ token });
}

                     trusted runtime              browser / agent
ABLO_API_KEY ─exchange─►  scoped token ────────► narrow scope, leased
(long-lived,             (short-lived,
 broad scope,             per-actor scope,
 server only)             revocable)

await ablo.ready();

const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
if (!report) throw new Error('report not found');

const report = ablo.weatherReports.get('report_stockholm');
const activeReports = ablo.weatherReports.getAll({
  where: { projectId: 'proj_123' },
  filter: (report) => report.status !== 'ready',
  orderBy: { updatedAt: 'desc' },
  limit: 50,
});

'use client';

import { useAblo } from '@abloatai/ablo/react';

export function ReportRow({
  report: serverReport,
}: {
  report: { id: string; location: string; status: string };
}) {
  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));

  return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
}

const ablo = useAblo();

await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });

const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });

await ablo.weatherReports.update({
  id: 'report_stockholm',
  data: { status: 'ready' },
  readAt: snap.stamp,
  onStale: 'reject',
  wait: 'confirmed',
});

human UI -> ablo.weatherReports.update(...)
agent    -> ablo.weatherReports.update(...)
server   -> ablo.weatherReports.update(...)

Button
  -> ablo.weatherReports.update(...)
  -> Ablo
  -> signed Data Source request
  -> existing backend service
  -> app database
  -> Ablo realtime fanout

// app/api/ablo/source/route.ts
import { dataSourceNext } from '@abloatai/ablo/source/next';
import { prismaDataSource } from '@abloatai/ablo/source';
import { schema } from '@/ablo/schema';
import { prisma } from '@/db';

export const runtime = 'nodejs';

export const { POST } = dataSourceNext({
  schema,
  apiKey: process.env.ABLO_API_KEY!,
  adapter: prismaDataSource(prisma, schema),
});

import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';

export const { POST } = dataSourceNext({
  schema,
  apiKey: process.env.ABLO_API_KEY!,
  adapter: drizzleDataSource(db, schema),
});

ABLO_API_KEY=sk_live_...

await using claim = await ablo.weatherReports.claim({
  id: reportId,
  reason: 'forecasting',
});
const claimed = claim.data;
if (!claimed) return;

await ablo.weatherReports.update({
  id: claimed.id,
  data: { status: 'ready', forecast: await getForecast(claimed) },
  wait: 'confirmed',
});

const completeReport = tool({
  description: 'Mark a weather report ready with a forecast',
  inputSchema: z.object({
    reportId: z.string(),
    forecast: z.string(),
  }),
  execute: async ({ reportId, forecast }) => {
    const snap = ablo.snapshot({ weatherReports: reportId });
    return ablo.weatherReports.update({
      id: reportId,
      data: { status: 'ready', forecast },
      readAt: snap.stamp,
      onStale: 'reject',
      wait: 'confirmed',
    });
  },
});