Options

Every option accepted by the default `Ablo({ ... })` client.

Import Ablo from @abloatai/ablo. Only schema is required. A server can usually rely on ABLO_API_KEY and keep the constructor small:

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

export const ablo = Ablo({ schema });

These options configure the package-root coordination client. API-key clients use HTTP; session clients use one multiplexed WebSocket by default. For a live human interface with a local graph, use the React guide. See Transports for the lifecycle and selection rules.

schema

The schema created with defineSchema(). It gives each declared model a typed ablo.<model> client. This is the only required option.

apiKey

A server API key, or an async function that resolves a credential at request time. When omitted, Ablo reads ABLO_API_KEY.

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

Use a resolver for credentials that rotate. Return null when the login has ended; throw when credential resolution failed temporarily. Do not combine it with another credential option.

session

A scoped session returned by the server-only Sessions(...).create() issuer. Pass the resource directly for bounded work, or pass a provider that re-mints the same logical actor for a long-running client:

import Sessions from '@abloatai/ablo/sessions';

const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
const session = await sessions.create({
  agent: { id: workerId },
  can: { records: ['read', 'update'] },
});

const worker = Ablo({ schema, session });

Do not extract session.token into apiKey; the session is the public handoff. A provider is cached until its returned session approaches expiresAt, so HTTP bootstrap and WebSocket connection setup do not mint duplicate credentials.

In a browser, name the application-owned route that mints the signed-in user’s session. Endpoint tuning belongs inside the same option:

const ablo = Ablo({
  schema,
  session: {
    endpoint: '/api/ablo-session',
    timeoutMs: 10_000,
    // allowCrossOrigin: true,
  },
});

The client sends a cookie-bearing POST, validates the response, and renews before expiry. Cross-origin minting is off by default and should be enabled only after configuring CORS and CSRF protection.

authToken

A bearer token the caller already holds. This is mainly for self-hosted or custom authentication layers. Hosted applications normally use apiKey or session.

baseURL

Overrides the Ablo API URL. Leave it unset for hosted Ablo. Use it for a private deployment, local development proxy, or test server.

const ablo = Ablo({ schema, baseURL: 'https://ablo.internal.example' });

Because credentials are sent to this URL, Ablo rejects URLs containing embedded credentials, query parameters, or fragments. Plain HTTP is accepted only for local hosts.

dangerouslyAllowBrowser

Allows a credential-bearing client to run in a browser. Defaults to false.

Private API keys must not ship to browsers. Prefer session.endpoint; enable this option only when the browser receives a narrowly scoped session credential or all traffic passes through a controlled server proxy.

fetch

A custom fetch implementation for tests, proxies, or runtimes without the standard global implementation.

bootstrapBaseUrl

Overrides the URL used for credential exchange and bootstrap. Most applications should leave this unset and use baseURL for a private or test deployment.

defaultHeaders

Headers included with every Ablo HTTP request. A null value removes a default header.

const ablo = Ablo({
  schema,
  defaultHeaders: { 'x-deployment': 'worker-eu' },
});

Do not use this option to duplicate the credential header; authentication is owned by session, apiKey, or authToken.

defaultQuery

Query parameters included with every Ablo HTTP request. This is primarily for proxies and controlled test deployments.

observability

A sink for claim lifecycle and rejected-write events. It implements captureClaim(event) and captureConflict(event). Use it to connect Ablo’s coordination outcomes to the application’s existing telemetry.

const ablo = Ablo({
  schema,
  observability: {
    captureClaim: (event) => telemetry.capture('ablo.claim', event),
    captureConflict: (event) => telemetry.capture('ablo.conflict', event),
  },
});

durableWrites

Persists an outbound write before dispatch so a worker can recover an unacknowledged create, update, or delete after a crash.

const ablo = Ablo({
  schema,
  durableWrites: { store, namespace: 'invoice-worker' },
});

The store must implement seal(), list(), and remove(). namespace separates deployments or workflow lanes sharing the same authenticated actor. Most clients do not need durable writes.

commitOutbox

Deprecated compatibility name for the durable write store. Use durableWrites: { store }. Passing both forms is an error.

commitOutboxScope

Deprecated compatibility scope for commitOutbox. Authentication now resolves actor identity. Use durableWrites.namespace when shared storage needs separate workflow or deployment lanes.

transport

Transport follows the configured identity. apiKey and authToken clients use request/response HTTP. session clients use one reconnecting WebSocket. Pass transport: 'http' only when bounded work needs a scoped session identity but must not hold a socket. The model, commit, claim, and context API stays unchanged.

Local materialized state and reactive reads still belong to the human client described in the React guide; selecting WebSocket here adds a carrier, not the human materializer.

timeoutMs

The deadline in milliseconds for an Ablo HTTP request. Defaults to 30000. Pass 0 only when the surrounding runtime already enforces a deadline.

groups

The initial groups observed by a WebSocket client. This can narrow what the connection follows, but it cannot widen the authority granted by sessions.create({ groups }).

collaborationEvents

Legacy store-level WebSocket event names accepted by subscribe(). New React and reactive-client code should prefer the record-scoped ablo.<model>.events.send(...) and .subscribe(...) surface. A collaboration-event handler receives the application’s unchanged payload first and optional server-authenticated context second:

store.subscribe('document:cursor', (cursor, context) => {
  context?.sender.presenceSessionId;
  context?.sender.participant; // { id, kind }
  context?.sentAt;
});

The context is optional while connecting to a server version that predates authenticated collaboration-event attribution. Never put caller-authored user identity in the application payload.