@n-dream/builders-sdk
v1.5.0
Published
Builders SDK for app code: app information, sign-in of app users and app data.
Readme
@n-dream/builders-sdk
The SDK for apps on Builders (design 4.5). Apps import it from npm.
import * as builders from "@n-dream/builders-sdk";
const info = await builders.appInfo(); // { appId, slug, environment, version }
const user = await builders.auth.user(); // { id, name, developer } or null
builders.auth.onChange((u) => render(u)); // now and at each change
await builders.auth.signIn(); // leaves the page; comes back signed in
await builders.auth.signOut();
builders.auth.accountPage(); // the Builders page: download or delete my dataappInfo()reads/_api/app.jsonon the app's own host.environmentislive,previeworversion.versionis null on the preview. Without the platform,appInfo()throws aBuildersError.auth(docs/login-and-data.md 4.1, 8.1): sign-in with Google, on the app's own host.user.idis this app's id of the user (another app has another id). The app gets the name, never the email.signIn()goes to the Builders sign-in page and back to the page (or toreturnTo, a path of the app). Previews and versions sign in only developers.- Who can sign in is set by the app's owner in the portal (anyone, listed domains, or listed emails).
BuildersErrorhascode(for examplesign-in-required,offline,app-stopped) andstatus(the HTTP status, 0 when no answer came).
Data
Each collection is declared in builders.data.json in the app folder
(docs/login-and-data.md 6.1): "mine" (each user's own, sign-in needed)
or "public" (everyone reads; each signed-in user adds and changes only
their own items; developers can remove any).
const notes = builders.db.collection<{ text: string; folder: string }>("notes");
const n = await notes.add({ text: "Hi", folder: "work" });
await notes.update(n.id, { text: "Hello" });
const page = await notes.list({ where: { folder: "work" }, limit: 20 });
const stop = notes.watch({ where: { folder: "work" } }, (items) => render(items));get,set,update,removetake an id. A short id (no dot) is always the caller's own item. Apublicitem has the id<user id>.<id>.listandcountfilter only by equality on the declaredfilterfields and sort bycreatedAt,updatedAtor the declaredsortfield.watchgives the whole current list at once and after each change.- Errors are
BuildersErrorwith a plain message that says what to do (8.3). There are no transactions, joins or counters; calls such asdb.transactionthrow a message with the way to do it. db.usage(): the bytes of the signed-in user's items and files, and their limits.- The user guard: each request names the user that the page believes is
signed in. When the session has another user (a sign-in in another
tab), Builders refuses it with
user-changed: nothing is read or saved,auth.onChangegets the new user, and watches start again.
Files
A file set is declared in builders.data.json as "files": { "photos":
"mine" } (docs/login-and-data.md 7). Only the user who uploads a file
can open it, and only when signed in.
const photos = builders.db.files("photos");
const f = await photos.upload(input.files[0]); // a File or a Blob
img.src = f.url; // "/_api/files/photos/<id>": only this user can open it
const { files, next } = await photos.list({ limit: 20 }); // newest first
await photos.remove(f.id);- Types: JPEG, PNG, WebP, GIF, AVIF, HEIC; MP3, M4A, OGG, WAV, WebM
audio; MP4, MOV (iPhone), WebM video; PDF. The platform reads the
first bytes of the file: the content must be the type of the file. No
SVG, HTML or scripts. A
.movis served asvideo/mp4(Chrome on Android plays it only so); itstypestaysvideo/quicktime. - At most 10 MB a file, 1,000 files and 200 MB per user. Make photos smaller in the browser before the upload (at most 2,048 pixels, JPEG or WebP).
Local mode
On localhost, 127.0.0.1 and [::1] (vite dev, test:headless) the
SDK keeps everything in memory (docs/login-and-data.md 8.4), with the
same rules and limits as the platform (the same engine runs there):
auth.signIn() signs in "Test user 1" at once. The tabs of one browser
share the data. A file's url is a blob: URL there (there is no
/_api/files on localhost); <img src> and <audio src> work the same. The Vite plugin puts builders.data.json into the build:
// vite.config.ts
import { builders } from "@n-dream/builders-sdk/vite";
export default defineConfig({ plugins: [builders(), react()] });Headless tests use:
import { signInAs, signOut, reset, seed, setLoginMode } from "@n-dream/builders-sdk/testing";
signInAs("Ann"); // the same name gives the same user id
signInAs("Dev", { developer: true });
await seed("posts", [{ data: { text: "Hi" } }], { as: "Bob" });
setLoginMode("emails", ["[email protected]"]); // then signInAs takes the email
signOut();
reset(); // no users, no dataThe SDK never uses the local mode on other hosts.
Release: the owner publishes with the next dist-tag (Q29). npm pack
builds dist/ first.
