abloatai.com

## Identity You are integrating `@abloatai/ablo` — Ablo's state API for humans and agents working on the same data. Teach one path first: `Ablo({ schema, apiKey: process.env.ABLO_API_KEY })`, then `ablo.<model>.get({ id })` / `ablo.<model>.list({ where })` and `ablo.<model>.update({ id, data })`. Explain that `get`/`list` are the async server reads, while `local.get(id)`/`local.list({ where })`/`local.count({ where })` are synchronous local-graph reads for reactive selectors after the data is loaded. Lower-level server resources and commits are advanced protocol escape hatches. ## Discovery flow Before writing integration code, load context on demand: 1. **Unsure what the SDK covers?** Call `get_api_surface()` with no argument to list every subpath. Then `get_api_surface({ subpath: "react" })` (or "schema" / "testing") for the structured export list. 2. **Have a specific question?** Call `search_ablo_docs({ query })`. You get ranked matches with excerpts. Follow up with `get_recipe({ name })` on the top hit. 3. **Starting from zero?** Call `get_recipe({ name: "readme" })`, then `get_recipe({ name: "integration-guide" })`, `get_recipe({ name: "guarantees" })`, and `get_recipe({ name: "api" })`. 4. **Writing a schema?** Do this for the root SDK path. Call `validate_schema({ code })` before committing schema code. Don't dump every recipe into context unprompted — the SDK has ~20 docs and only 2-3 are relevant to any given integration task. ## Design principles - **Schema first.** Start with `defineSchema(...)` and `Ablo({ schema, apiKey })`. Typed model resources are the happy path. - **Keep schema simple first.** New users should see model fields and relations. Load strategies, local indexing, and offline-cache hints are advanced options. - **System fields are automatic.** Do not declare `id`, `createdAt`, `updatedAt`, `organizationId`, or `createdBy` inside `model({ ... })`; the SDK supplies them. - **Claimed reads are explicit.** Server reads default to `ifClaimed: "return"` (returns the row plus active claim metadata); pass `ifClaimed: "fail"` to throw `AbloClaimedError` on a claimed row. Reads never block — to wait for a row to free up, `claim({ id })` it (the claim queues fairly behind the holder). There is no `ifClaimed: "wait"`. - **Writes are protected.** Pass `readAt: stamp` and an `idempotencyKey`; local state changes optimistically, and awaiting the model write waits for authoritative confirmation. - **Claims are concrete.** Take `ablo.<model>.claim({ id })` before expensive work; bind with `await using` (or release in `finally`). - **Do not introduce parallel mutation APIs.** Normal writes use `ablo.<model>.update`; low-level batches use `commits.create` only when the user asks for custom protocol work. ## Common mistakes to avoid - Don't lead with capabilities, React hooks, sync groups, or mesh internals. - Don't use `commits.create` for the first example. - Don't call API keys "auth" in public docs. - Don't ship `ABLO_API_KEY` to a browser bundle. ## Hosted service Ablo's hosted service handles commit validation, claim coordination, receipts, and fan-out. Trusted runtimes pass `apiKey: process.env.ABLO_API_KEY`.