DocsAPI & clients
Browser client
The client every page can import, for collections, sign-in, files and live data.
The client is @sluurp/client. It wraps the REST API and handles sign-in. In React, @sluurp/react adds hooks such as useLive. Both come with Sluurp: there’s nothing to install, and the client your pages get is always the one your server speaks. To use it, import it:
import { Sluurp } from "@sluurp/client";
const sluurp = new Sluurp();
const todos = sluurp.collection("todos");
const { items } = await todos.list({ filter: "done = false", sort: "-created_at" });
const todo = await todos.create({ title: "Milk" });
await todos.update(todo.id, { done: true }, { reason: "bought" });new Sluurp() talks to the page’s own server. To talk to another, pass its origin: new Sluurp("https://app.example.com"). For a project other than the default, pass { project }.
The client isn’t published as a package, because it changes with the server it talks to. A frontend hosted elsewhere can be served by Sluurp instead (see several apps on one server), or it can call the REST API directly.
Collections
sluurp.collection(name) has:
list({ page, perPage, sort, filter, asOf }) | One page: { items, page, perPage, totalItems, totalPages } |
listAll(options) | Every page as one array (answered from sync after the first call) |
getOne(id), getFirst(filter) | A single record |
create(data), update(id, data), delete(id) | Writes. Each takes { reason }, kept with the change |
history(id), version(id, seq), restore(id, seq) | Past versions, if history is on |
changes(since) | Every change after a sequence number, in order |
Files
upload(id, field, file) | Upload a File or Blob to a field |
createWithFile(data, field, file) | Make the record and upload in one step |
fileUrl(id, field, { w, h, fit, format }) | A URL for an <img>, resized |
srcset(id, field, [400, 800, 1200]) | A srcset at those widths |
fileObjectUrl(id, field), fileText(id, field) | Fetch a private file, signed in |
Sign in
On the sign-in collection, usually users:
const users = sluurp.collection("users");
await users.authWithPassword(email, password);
sluurp.authStore.isValid; // signed in?
sluurp.authStore.record; // the user
sluurp.logout();The collection also has signUp, requestPasswordReset, requestSigninLink (a sign-in link), verifyTwoFactor, authRefresh, and oauthUrl("google"), with captureOAuthToken(sluurp) on the page people come back to.
The session is kept in localStorage and shared by the site’s pages. sluurp.onAuthFailure fires when the server refuses the token.
Check permissions
const may = await sluurp.permissions();
may.can("orders", "update"); // for some rows at least
may.certainly("orders", "delete"); // for every rowThis evaluates the collections’ rules in advance, so you can show only the buttons that will work.
Errors
A failed call throws a SluurpError, with status, message (from the server), body, and the helpers isAuthError (401) and isForbidden (403).
Live changes
sluurp.socket({ subscribe: ["messages"] }) opens a WebSocket that streams every change to those collections, filtered by your rules.
on(type, listener)subscribes.join(topic)andleave(topic)handle presence.emit(topic, event, data)broadcasts without storing anything.
For lists that stay current on their own, use Sync.
Show the last data at once
kept shows the last answer cached in this browser at once, then updates from the server’s answer if it differs:
sluurp.kept("todos", () => sluurp.collection("todos").list(), (r) => todos.set(r.items));A reload then shows the whole screen in the first frame, instead of filling in piece by piece. The cache is per user and per browser, and logout() clears it.
Plugins and the rest
Plugins add their own parts to the client once you import them:
sluurp.aifromplugin:ai(AI)sluurp.pagesfromplugin:pages(Pages)sluurp.billingfromplugin:billing, andsluurp.socialfromplugin:socialsluurp.conversation(id)andsluurp.conversationsfromplugin:conversationssluurp.paymentsfromplugin:payments(Payments)
To call any endpoint with the sign-in and app headers attached, use sluurp.send(path, { method, body, query }).