@thesmallfield/web
v0.0.3
Published
Small Field for browser code: who is signed in, and files.
Maintainers
Readme
@thesmallfield/web
npm i @thesmallfield/webSmall Field for browser code, any framework. It asks the app's own gate for a short-lived token
(GET /.sf/token, same origin) and refreshes it by itself. It holds no keys and can never send email.
import { can, createClient, hasRole } from '@thesmallfield/web';
const sf = createClient();
const me = await sf.identity.me(); // { id, email, name, role, roles, scopes } or null when nobody is signed in
if (!me) sf.signIn(); // goes to /.sf/login and comes back here
if (hasRole(me, 'reports')) showReports();
if (can(me, 'reports:export')) showExportButton(); // scopes come bundled in the person's rolesFiles, as the signed-in person, through files.<apps>:
const up = sf.files.upload(input.files[0], {
tags: ['site-walk'],
onProgress: (sent, total) => (bar.value = sent / total),
});
const file = await up; // or up.promise; up.pause(), up.resume(), up.abort() while it runs
video.src = (await sf.files.link(file.id)).url; // 5-minute link for <video>, <img>, <a>; seeking works
const { files, nextBefore } = await sf.files.search({ kind: 'video', q: 'walk' }); // or search('walk')
await sf.files.get(file.id);
await sf.files.update(file.id, { fileName: 'walk.mp4', tags: ['q3'], meta: { room: '4b' } });
await sf.files.remove(file.id);Uploads are resumable (tus, 50 MiB chunks): a dropped connection is retried for about 90 seconds and continues
where it stopped; the token is refreshed on each request, so a long upload outlives the 5-minute token. There is no
download helper: use link(). Visibility (audience, sharing) and person-to-person sharing
(share(id, { userId } | { role }), shares(id), unshare(id, shareId)) work only when the app turns them on
under Capabilities → Files; otherwise the server answers with a SmallFieldError saying so.
Call another app that shared something with yours, as the signed-in person, straight from the page:
const orders = await sf.apps('rooms').fetch('/api/orders'); // JSON parsed
await sf
.apps('rooms', { scope: 'orders.write' })
.fetch('/api/orders', { method: 'POST', body: { item: 'desk' } });
const run = await sf.apps('rooms').jobs.run('report'); // { runId, job }
const done = await sf.apps('rooms').jobs.wait(run); // { status, exitCode, log, ... }
await sf.apps('rooms').jobs.run('report', { input: { from: '2026-10-01' } }); // the job reads SF_JOB_INPUTThe token comes from /.sf/token?for=rooms and is sent only to that app, as a bearer with no cookies. Pass scope
when your app uses more than one scope of the same app. A refusal is a SmallFieldError with the server's text.
Size budget: 40 KB gzipped, checked by pnpm --filter web size (20.0 KB with tus-js-client).
