stoop-platform

The stoop platform SDK

What a stoop site can do at runtime without any backend code of its own. This is the same surface however the site was published — from a folder with the stoop CLI, or over HTTP with an API key.

Loading it

Every page that needs data or identity loads the SDK. It is served by the platform on the site's own origin — do not bundle, vendor, or CDN it:

<script src="/__platform/sdk.js"></script>

It installs window.platform.

Database — platform.db.collection(name)

Schemaless JSON documents, shared by all visitors of the site, with realtime updates:

const votes = platform.db.collection("votes");
await votes.create({ spot: "Taco Cart" }); // → doc; the server assigns doc.id
await votes.list();                        // → doc[] (newest first)
await votes.get(id);                       // → doc
await votes.update(id, { count: 2 });      // → doc (shallow merge)
await votes.delete(id);                    // → null
const stop = votes.subscribe({             // realtime; returns unsubscribe fn
  onCreate: (doc) => {},
  onUpdate: (doc) => {},
  onDelete: (id) => {},
});

// Queries: equality filters, one sort field (- prefix = descending;
// _created / _updated sort by timestamp), and a page-size limit.
await votes.list({ where: { spot: "Taco Cart" }, sort: "-_created", limit: 50 });
// Pagination for big collections: cursor is null on the last page.
const { docs, cursor } = await votes.page({ limit: 100 });
const rest = await votes.page({ limit: 100, cursor });

// Access rules — make a collection read-only or invisible to visitors.
// Only site members may call this ("public"/"public" is the default).
await votes.setRules({ read: "public", write: "members" });

• Subscribe events fire for every client's writes, including this page's own: render from list() + subscribe events and don't also apply local writes to the UI, or they will show up twice.
• list() returns newest first — reverse it when appending rows in chronological order, so live onCreate appends continue the same order.
• list() returns at most one page (1000 docs); use page() and follow cursor when a collection can grow past that.
• where is exact equality on top-level fields only (no ranges, no substring match) — filter client-side for anything richer.
• No transactions or atomic increments: concurrent update()s to the same key are last-write-wins, so a shared counter can drop clicks. When every event must count (votes, tallies), create() one document per event and count them client-side.
• Documents may carry a platform-stamped _by author ({ id, name }). Client-sent values are ignored, and anonymous visitors cannot edit or delete documents authored by someone else.
• setRules({ read, write }) with "public" | "members" persists per collection. Use write: "members" for owner-curated content (menus, announcements) that visitors read but must not change; visitor sites calling it get a 403, so gate it on user action, not page load.