@volter/twin-turbopuffer 0.1.0

package/dist/src/screens/dashboard.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// TURBOPUFFER'S DASHBOARD — the pages an organization's person signs in to and makes its API keys on
+// (docs/contributing/architecture.md, "Screens" and "Who is on a screen"). No API operation makes or expires a key: "All
+// API calls require authenticating with your API key. You can create and expire tokens in the dashboard"
+// (https://turbopuffer.com/docs/auth), so every key a customer uses comes from here. Built from @volter/world-ui's
+// sign-in and settings pieces under turbopuffer's skin; nothing of turbopuffer's page is copied.
+//
+// - turbopuffer.com/login: the sign-in (turbopuffer's page asks for an Email and has Continue). A dashboard page asked for
+//   by nobody signed in sends its visitor here, and the sign-in returns them there.
+// - turbopuffer.com/dashboard/api-keys: the organization's API keys. Create API key with its Name and its permissions,
+//   shown once in the page's notice; each live key's Expire. The permissions are the ones turbopuffer's pages name:
+//   "API Key read/write permissions" (https://turbopuffer.com/docs/roadmap, March 2024), "New API key permission to
+//   `list` namespaces" (the same, May 2026), and admin ("available to API keys with list or admin permissions",
+//   https://turbopuffer.com/docs/namespaces). A key is named ("Named API Keys", the same changelog) and marked expired
+//   (the audit log's `api-key-marked-as-expired`, https://turbopuffer.com/docs/audit-logs).
+// - POST /_twin/users/:email/password {password, organization, plan}: stands in for turbopuffer's sign-up
+//   (turbopuffer.com/join: Email, a plan, Continue), as upstash's and planetscale's doors of the same path do. The World
+//   keeps the password's hash, never the password.
+//
+// Where turbopuffer's documentation stops and the twin decides: a person signs in with an email and the password the
+// World gave them (turbopuffer's own sign-in continues by email or GitHub or Google, which the twin does not model); the
+// session cookie is named `tpuf_session`; the keys page is at /dashboard/api-keys; a key's permissions are four
+// checkboxes (Read, Write, List, Admin; turbopuffer does not document the control) and a key needs at least one; a key
+// is `tpuf_` and 32 letters and digits (the length is the twin's; the prefix is the docs' own placeholder for a key,
+// `"source_api_key": "tpuf_A1..."` in https://turbopuffer.com/docs/write's copy example); a refused sign-in shows the form again with
+// "Incorrect email or password." (200); a name already used by a live key, or none, answers the page with a notice (422).
+import { createHash } from 'node:crypto';
+import { cookieOf, flowPage, Portal, PORTAL_CSS, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+export const DASHBOARD_HOST = 'turbopuffer.com';
+const COOKIE = 'tpuf_session';
+const KEYS = '/dashboard/api-keys';
+export const GRANTS = ['read', 'write', 'list', 'admin'];
+const LABEL = { read: 'Read', write: 'Write', list: 'List', admin: 'Admin' };
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email, password) => hex(`password:${email.toLowerCase()}:${password}`);
+const ALNUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+// turbopuffer's skin: its warm off-white page and near-black ink and buttons
+const SKIN = `
+body { background: #faf8f5; color: #111111; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.sign-in-mark { background: #111111; }
+.sign-in-box { background: #ffffff; border-color: #e5e1da; }
+.sign-in-error { background: #fff4f2; border-color: #f3c7bf; color: #111111; }
+.sign-in-submit { background: #111111; border-color: #111111; color: #ffffff; }
+.portal-side { background: #f3f0ea; border-right: 1px solid #e5e1da; }
+.portal-section h2 { border-color: #e5e1da; color: #57534e; }
+.portal-notice { background: #f3f0ea; border: 1px solid #e5e1da; word-break: break-all; }
+.portal-button { background: #ffffff; border: 1px solid #d6d1c8; border-radius: 4px; padding: 6px 12px; }
+.portal-primary { background: #111111; border-color: #111111; color: #ffffff; }
+`;
+/** A return_to the dashboard follows: a path on turbopuffer.com, never another site. */
+const returnTo = (raw) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : KEYS);
+function signInPage(back, email, error) {
+    return flowPage({
+        title: 'Log in · turbopuffer',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(SignIn, { heading: "Log in", action: "/login", fields: { return_to: back }, account: { name: 'email', label: 'Email', ...(email ? { value: email } : {}) }, password: { name: 'password', label: 'Password' }, submit: "Continue", ...(error ? { error } : {}) })),
+    });
+}
+/** The person the request's session cookie names, with their organization, or undefined. */
+function signedIn(ctx, request) {
+    const token = cookieOf(request, COOKIE);
+    const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+    return session ? ctx.rowsRaw('_person').find((p) => p.email === session.email) : undefined;
+}
+/** The organization's live and expired keys, oldest first. */
+export function keysOf(ctx, organization) {
+    return ctx.rowsRaw('_api_key').filter((k) => k.organization === organization);
+}
+function keysPage(ctx, person, notice, status = 200) {
+    const organization = String(person.organization);
+    const keys = keysOf(ctx, organization);
+    const grantsOf = (k) => (Array.isArray(k.grants) ? k.grants.map((g) => LABEL[g]).join(', ') : '');
+    return flowPage({
+        title: 'API keys · turbopuffer',
+        css: [PORTAL_CSS, SKIN],
+        status,
+        body: (_jsx(Portal, { merchant: `${organization} · ${String(person.email)}`, back: { href: '/dashboard', label: 'Dashboard' }, ...(notice ? { notice } : {}), sections: [{
+                    heading: 'API keys',
+                    empty: 'No API keys yet.',
+                    items: keys.map((k) => ({
+                        title: String(k.name),
+                        detail: grantsOf(k),
+                        note: k.expired_at ? `Expired ${String(k.expired_at).slice(0, 10)}` : `Created ${String(k.created_at).slice(0, 10)} · ends ${String(k.suffix)}`,
+                        ...(k.expired_at ? { badge: 'Expired' } : { actions: [{ label: 'Expire', action: `${KEYS}/expire`, tone: 'danger', fields: { name: String(k.name) } }] }),
+                    })),
+                }], forms: [{
+                    heading: 'Create API key',
+                    action: KEYS,
+                    fields: [
+                        { id: 'name', label: 'Name' },
+                        ...GRANTS.map((g) => ({ id: g, label: LABEL[g], type: 'checkbox' })),
+                    ],
+                    submit: { label: 'Create API key' },
+                }] })),
+    });
+}
+/** A key's value: `tpuf_` and 32 letters and digits, derived from the organization, the name and the moment. */
+function keyValue(organization, name, at, n) {
+    const digest = createHash('sha256').update(`apikey:${organization}:${name}:${at}:${n}`).digest();
+    return `tpuf_${Array.from(digest.subarray(0, 32), (b) => ALNUM[b % ALNUM.length]).join('')}`;
+}
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+async function createKey(ctx, person, form) {
+    const organization = String(person.organization);
+    const name = (form.name ?? '').trim();
+    const grants = GRANTS.filter((g) => form[g] !== undefined);
+    if (!name)
+        return keysPage(ctx, person, 'An API key needs a name.', 422);
+    if (keysOf(ctx, organization).some((k) => k.name === name && !k.expired_at))
+        return keysPage(ctx, person, `There is already an API key named ${name}.`, 422);
+    if (!grants.length)
+        return keysPage(ctx, person, 'Choose at least one permission.', 422);
+    const n = ctx.rowsRaw('_api_key').length + 1;
+    const key = keyValue(organization, name, ctx.occurredAt, n);
+    await ctx.record('_api_key', {
+        organization, name, grants, created_at: ctx.occurredAt, created_by: person.email, expired_at: null,
+        suffix: key.slice(-4), key_sha256: hex(key),
+    }, `apikey:${organization}:${n}`);
+    return keysPage(ctx, person, `API key ${name} created: ${key} — copy it now, it will not be shown again.`);
+}
+/** Expire: the key stops working at once (key-gate.ts admits no expired key). */
+async function expireKey(ctx, person, name) {
+    const organization = String(person.organization);
+    const key = keysOf(ctx, organization).find((k) => k.name === name && !k.expired_at);
+    if (!key)
+        return keysPage(ctx, person, `There is no live API key named ${name}.`, 422);
+    await ctx.record('_api_key', { ...ctx.own(key), expired_at: ctx.occurredAt, expired_by: person.email }, String(key.id));
+    return keysPage(ctx, person, `API key ${name} expired.`);
+}
+/** turbopuffer.com's pages and the World's sign-up door, or undefined for any other path. `contextFor` gives the
+ *  pack's semantics context for a request. */
+export async function dashboard(request, contextFor) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    const ctx = await contextFor(new Request(request.url));
+    if (path === '/login' && request.method === 'GET')
+        return signInPage(returnTo(url.searchParams.get('return_to')));
+    if (path === '/login' && request.method === 'POST') {
+        const f = await formOf(request);
+        const email = (f.email ?? '').trim().toLowerCase();
+        const back = returnTo(f.return_to);
+        const person = ctx.rowsRaw('_person').find((p) => p.email === email);
+        if (!email || !person || person.hash !== passwordHash(email, f.password ?? ''))
+            return signInPage(back, email, 'Incorrect email or password.');
+        const token = hex(`session:${email}:${ctx.occurredAt}:${ctx.rowsRaw('_web_session').length + 1}`).slice(0, 48);
+        await ctx.record('_web_session', { token, email, created_at: ctx.occurredAt }, `websession:${token}`);
+        const headers = new Headers({ location: back });
+        headers.append('set-cookie', `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`);
+        return new Response(null, { status: 302, headers });
+    }
+    const door = /^\/_twin\/users\/([^/]+)\/password$/.exec(path);
+    if (door && request.method === 'POST')
+        return signUpDoor(ctx, decodeURIComponent(door[1]).toLowerCase(), request);
+    // a path the host's pages do not have is the caller's (its 404)
+    return path === '/dashboard' || path === KEYS || path === `${KEYS}/expire` ? keysPages(ctx, request, url, path) : undefined;
+}
+/** /dashboard (to the keys page), the keys page, its Create API key and its Expire, for the person signed in. */
+async function keysPages(ctx, request, url, path) {
+    const person = signedIn(ctx, request);
+    if (!person)
+        return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(url.pathname + url.search)}` } });
+    if (request.method === 'GET')
+        return path === '/dashboard' ? new Response(null, { status: 302, headers: { location: KEYS } }) : keysPage(ctx, person);
+    if (request.method !== 'POST' || path === '/dashboard')
+        return undefined;
+    const form = await formOf(request);
+    return path === KEYS ? createKey(ctx, person, form) : expireKey(ctx, person, (form.name ?? '').trim());
+}
+/** The sign-up door's refusal of a call missing what it needs. */
+function badSignUp() {
+    return Response.json({ status: 'error', error: 'an email, a password of at least 8 characters, an organization and a plan (launch or scale) are required' }, { status: 400 });
+}
+/** POST /_twin/users/:email/password {password, organization, plan}: the person, their organization and its plan, as
+ *  turbopuffer's sign-up makes them (turbopuffer.com/join: "Select plan launch ($16/mo minimum) … scale ($256/mo
+ *  minimum)"); 204. */
+async function signUpDoor(ctx, email, request) {
+    let body = {};
+    try {
+        body = JSON.parse(await request.text());
+    }
+    catch { /* refused below */ }
+    const password = typeof body.password === 'string' ? body.password : '';
+    const organization = typeof body.organization === 'string' ? body.organization.trim() : '';
+    const plan = body.plan === undefined ? 'launch' : body.plan;
+    if (!/^[^@\s]+@[^@\s]+$/.test(email) || password.length < 8 || !organization || (plan !== 'launch' && plan !== 'scale'))
+        return badSignUp();
+    await ctx.record('_person', { email, hash: passwordHash(email, password), organization, plan, set_at: ctx.occurredAt }, `person:${email}`);
+    return new Response(null, { status: 204 });
+}

package/dist/src/semantics/namespaces.d.ts

@@ -0,0 +1,5 @@
+import type { DerivedHandler } from '@volter/world-core';
+/** The operations served here, every one the twin serves. */
+export declare const HANDLED: readonly ["get_v1_namespaces", "get_v2_namespaces_namespace_metadata", "get_v1_namespaces_namespace_metadata", "get_v1_namespaces_namespace_hint_cache_warm", "delete_v2_namespaces_namespace", "get_v1_namespaces_namespace_operations_token", "get_v1_namespaces_namespace_schema", "post_v1_namespaces_namespace_schema", "post_v2_namespaces_namespace", "post_v2_namespaces_namespace_query"];
+/** A handler per operation above, answering through `answer` (the pack's request handler as a fetch). */
+export declare function turbopufferHandlers(answer: (request: Request) => Promise<Response>): Record<string, DerivedHandler>;

package/dist/src/semantics/namespaces.js

@@ -0,0 +1,17 @@
+/** The operations served here, every one the twin serves. */
+export const HANDLED = [
+    // namespaces
+    'get_v1_namespaces', 'get_v2_namespaces_namespace_metadata', 'get_v1_namespaces_namespace_metadata', 'get_v1_namespaces_namespace_hint_cache_warm',
+    'delete_v2_namespaces_namespace',
+    // an asynchronous copy's operation, polled (the API overview's Asynchronous requests)
+    'get_v1_namespaces_namespace_operations_token',
+    // a namespace's schema
+    'get_v1_namespaces_namespace_schema', 'post_v1_namespaces_namespace_schema',
+    // documents: the write (upserts, patches and deletes, by id or by filter) and the query (one query, or several)
+    'post_v2_namespaces_namespace', 'post_v2_namespaces_namespace_query',
+];
+/** A handler per operation above, answering through `answer` (the pack's request handler as a fetch). */
+export function turbopufferHandlers(answer) {
+    const serve = ({ request }) => answer(request);
+    return Object.fromEntries(HANDLED.map((id) => [id, serve]));
+}

package/dist/src/turbopuffer-capabilities.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const TURBOPUFFER_CAPABILITIES: CapabilitySpec[];
+/** Committed area census: the SDK's surface groups (write, query, filters, full-text, vectors,
+ *  schema options, namespace management) plus the protocol and connector areas. */
+export declare const TURBOPUFFER_AREAS: readonly ["auth", "conformance", "connector", "errors", "filters", "fts", "legacy", "namespaces", "query", "schema", "vectors", "wire", "write"];
+export declare function turbopufferCapabilities(): Promise<CapabilityReport>;