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:

app.ts
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:

app.ts
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

app.ts
const may = await sluurp.permissions();
may.can("orders", "update");        // for some rows at least
may.certainly("orders", "delete");  // for every row

This 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) and leave(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:

app.js
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.ai from plugin:ai (AI)
  • sluurp.pages from plugin:pages (Pages)
  • sluurp.billing from plugin:billing, and sluurp.social from plugin:social
  • sluurp.conversation(id) and sluurp.conversations from plugin:conversations
  • sluurp.payments from plugin:payments (Payments)

To call any endpoint with the sign-in and app headers attached, use sluurp.send(path, { method, body, query }).

View as Markdown