@volter/twin-upstash 0.1.0

package/dist/api/src/screens/teams.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// UPSTASH CONSOLE: ACCOUNT > TEAMS, and the invitation's acceptance link (docs/contributing/architecture.md, "Screens").
+// https://upstash.com/docs/common/account/teams: "we will send an invitation email to that address. The user joins the team
+// by clicking the acceptance link in the email ... Until the invitation is accepted, the user appears as a **pending
+// member** and does not have access to the team yet. You can revoke a pending invitation (**Revoke Invite**) or remove an
+// existing member from the same page." No API operation accepts an invitation, and none says a member is pending: both
+// are here. Built from @volter/world-ui's settings layout (Portal) under Upstash's skin; nothing of Upstash's page is
+// copied. Its controls are the ones a life needs: a member's Pending mark, Revoke Invite, and the invitation's Accept.
+//
+// The person on a page is who signed in at /login (session.tsx). Where the documentation stops and the twin decides: the
+// page is at /account/teams and lists every team the person has joined, each with its members; the acceptance link is
+// /invite/<token> and asks the invited person to accept (a person signed in as anyone else is told the invitation is not
+// theirs, 403); a revoked or accepted invitation's link answers 404. The invitation email itself is the World's record,
+// read at GET /_twin/mail?to=<email> → {to, mails: [{at, subject, text}]} (standing in for the person's inbox).
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import { MAIL, membersOf, removeMember, roleOf, teamOf } from "../semantics/teams.js";
+import { signedIn, toSignIn } from "./session.js";
+const PATH = '/account/teams';
+const SKIN = `
+body { background: #ffffff; color: #1c1917; }
+.portal-side { background: #fafaf9; border-right: 1px solid #e7e5e4; }
+.portal-section h2 { border-color: #e7e5e4; color: #57534e; }
+.portal-notice { background: #ecfdf5; border: 1px solid #a7f3d0; }
+.portal-button { background: #ffffff; border: 1px solid #d6d3d1; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #00c98d; border-color: #00c98d; color: #0c0a09; }
+.portal-danger { border-color: #fecaca; color: #b91c1c; }
+`;
+const ROLE_LABEL = { owner: 'Owner', admin: 'Admin', dev: 'Dev', finance: 'Finance' };
+function teamsPage(ctx, email, notice) {
+    const joined = ctx.rowsRaw('TeamMember').filter((m) => m.member_email === email && !m._removed_at && m._pending !== true && teamOf(ctx, String(m.team_id)));
+    return flowPage({
+        title: 'Teams · Account · Upstash Console',
+        css: [PORTAL_CSS, SKIN],
+        body: (_jsx(Portal, { merchant: `${email} · Account`, back: { href: '/', label: 'Back to console' }, ...(notice ? { notice } : {}), sections: joined.length === 0 ? [{ heading: 'Teams', items: [], empty: 'You are not a member of any team.' }] : joined.map((j) => {
+                const team = String(j.team_id);
+                const manager = ['owner', 'admin'].includes(String(j.member_role));
+                return {
+                    heading: String(j.team_name),
+                    items: membersOf(ctx, team).map((m) => ({
+                        title: String(m.member_email),
+                        detail: ROLE_LABEL[String(m.member_role)] ?? String(m.member_role),
+                        ...(m._pending === true ? { badge: 'Pending', note: 'Invitation sent, not yet accepted' } : typeof m._joined_at === 'string' ? { note: `Joined ${m._joined_at.slice(0, 10)}` } : {}),
+                        actions: m._pending === true && manager ? [{ label: 'Revoke Invite', action: `${PATH}/revoke`, tone: 'danger', fields: { team_id: team, member_email: String(m.member_email) } }] : [],
+                    })),
+                };
+            }) })),
+    });
+}
+function invitePage(team, role, token, notice, status = 200) {
+    return flowPage({
+        title: 'Team invitation · Upstash Console',
+        css: [PORTAL_CSS, SKIN],
+        status,
+        body: (_jsx(Portal, { merchant: "Team invitation", ...(notice ? { notice } : {}), sections: [{ heading: `Join ${team}`, items: [{ title: team, detail: `as ${ROLE_LABEL[role] ?? role}`, actions: notice ? [] : [{ label: 'Accept invitation', action: `/invite/${token}`, tone: 'primary' }] }] }] })),
+    });
+}
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+/** The Teams page, the invitation's link and the World's mail door, or undefined for any other request. */
+export async function teamsPages(request, contextFor) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, '');
+    if (path === '/_twin/mail' && request.method === 'GET') {
+        const to = (url.searchParams.get('to') ?? '').toLowerCase();
+        const mails = (await contextFor(new Request(request.url))).rowsRaw(MAIL).filter((m) => m.to === to).map((m) => ({ at: m.at, subject: m.subject, text: m.text }));
+        return Response.json({ to, mails });
+    }
+    const invite = /^\/invite\/([0-9a-f]+)$/.exec(path);
+    if (path !== PATH && path !== `${PATH}/revoke` && !invite)
+        return undefined;
+    const ctx = await contextFor(new Request(request.url));
+    const person = signedIn(ctx, request);
+    if (!person)
+        return toSignIn(request);
+    if (invite) {
+        const member = ctx.rowsRaw('TeamMember').find((m) => m._invite === invite[1] && m._pending === true && !m._removed_at);
+        if (!member)
+            return new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+        const [team, role] = [String(member.team_name), String(member.member_role)];
+        if (member.member_email !== person.email)
+            return invitePage(team, role, invite[1], `This invitation is for ${String(member.member_email)}. Log in as that user to accept it.`, 403);
+        if (request.method !== 'POST')
+            return invitePage(team, role, invite[1]);
+        await ctx.write('TeamMember', `${String(member.team_id)}:${person.email}`, { ...ctx.own(member), _pending: false, _joined_at: ctx.occurredAt }, 'team.accept-invite');
+        return teamsPage(await contextFor(new Request(request.url)), person.email, `You joined ${team}.`);
+    }
+    return path === PATH ? teamsPage(ctx, person.email) : revokeInvite(ctx, person.email, request, contextFor);
+}
+/** Revoke Invite: a pending member goes, by the team's Owner or an Admin. */
+async function revokeInvite(ctx, email, request, contextFor) {
+    const form = await formOf(request);
+    const team = String(form.team_id ?? '');
+    const pending = membersOf(ctx, team).find((m) => m.member_email === form.member_email && m._pending === true);
+    if (!pending || !['owner', 'admin'].includes(roleOf(ctx, team, email) ?? ''))
+        return teamsPage(ctx, email, 'There is no pending invitation you can revoke.');
+    await removeMember(ctx, team, String(pending.member_email), 'team.revoke-invite');
+    return teamsPage(await contextFor(new Request(request.url)), email, `The invitation to ${String(pending.member_email)} was revoked.`);
+}

package/dist/api/src/screens/teams.tsx

@@ -0,0 +1,114 @@
+// UPSTASH CONSOLE: ACCOUNT > TEAMS, and the invitation's acceptance link (docs/contributing/architecture.md, "Screens").
+// https://upstash.com/docs/common/account/teams: "we will send an invitation email to that address. The user joins the team
+// by clicking the acceptance link in the email ... Until the invitation is accepted, the user appears as a **pending
+// member** and does not have access to the team yet. You can revoke a pending invitation (**Revoke Invite**) or remove an
+// existing member from the same page." No API operation accepts an invitation, and none says a member is pending: both
+// are here. Built from @volter/world-ui's settings layout (Portal) under Upstash's skin; nothing of Upstash's page is
+// copied. Its controls are the ones a life needs: a member's Pending mark, Revoke Invite, and the invitation's Accept.
+//
+// The person on a page is who signed in at /login (session.tsx). Where the documentation stops and the twin decides: the
+// page is at /account/teams and lists every team the person has joined, each with its members; the acceptance link is
+// /invite/<token> and asks the invited person to accept (a person signed in as anyone else is told the invitation is not
+// theirs, 403); a revoked or accepted invitation's link answers 404. The invitation email itself is the World's record,
+// read at GET /_twin/mail?to=<email> → {to, mails: [{at, subject, text}]} (standing in for the person's inbox).
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { MAIL, membersOf, removeMember, roleOf, teamOf } from '../semantics/teams.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+const PATH = '/account/teams';
+
+const SKIN = `
+body { background: #ffffff; color: #1c1917; }
+.portal-side { background: #fafaf9; border-right: 1px solid #e7e5e4; }
+.portal-section h2 { border-color: #e7e5e4; color: #57534e; }
+.portal-notice { background: #ecfdf5; border: 1px solid #a7f3d0; }
+.portal-button { background: #ffffff; border: 1px solid #d6d3d1; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #00c98d; border-color: #00c98d; color: #0c0a09; }
+.portal-danger { border-color: #fecaca; color: #b91c1c; }
+`;
+
+const ROLE_LABEL: Record<string, string> = { owner: 'Owner', admin: 'Admin', dev: 'Dev', finance: 'Finance' };
+
+function teamsPage(ctx: SemanticsContext, email: string, notice?: string): Response {
+  const joined = ctx.rowsRaw('TeamMember').filter((m) => m.member_email === email && !m._removed_at && m._pending !== true && teamOf(ctx, String(m.team_id)));
+  return flowPage({
+    title: 'Teams · Account · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    body: (
+      <Portal
+        merchant={`${email} · Account`}
+        back={{ href: '/', label: 'Back to console' }}
+        {...(notice ? { notice } : {})}
+        sections={joined.length === 0 ? [{ heading: 'Teams', items: [], empty: 'You are not a member of any team.' }] : joined.map((j) => {
+          const team = String(j.team_id);
+          const manager = ['owner', 'admin'].includes(String(j.member_role));
+          return {
+            heading: String(j.team_name),
+            items: membersOf(ctx, team).map((m) => ({
+              title: String(m.member_email),
+              detail: ROLE_LABEL[String(m.member_role)] ?? String(m.member_role),
+              ...(m._pending === true ? { badge: 'Pending', note: 'Invitation sent, not yet accepted' } : typeof m._joined_at === 'string' ? { note: `Joined ${m._joined_at.slice(0, 10)}` } : {}),
+              actions: m._pending === true && manager ? [{ label: 'Revoke Invite', action: `${PATH}/revoke`, tone: 'danger' as const, fields: { team_id: team, member_email: String(m.member_email) } }] : [],
+            })),
+          };
+        })}
+      />
+    ),
+  });
+}
+
+function invitePage(team: string, role: string, token: string, notice?: string, status = 200): Response {
+  return flowPage({
+    title: 'Team invitation · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant="Team invitation"
+        {...(notice ? { notice } : {})}
+        sections={[{ heading: `Join ${team}`, items: [{ title: team, detail: `as ${ROLE_LABEL[role] ?? role}`, actions: notice ? [] : [{ label: 'Accept invitation', action: `/invite/${token}`, tone: 'primary' as const }] }] }]}
+      />
+    ),
+  });
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The Teams page, the invitation's link and the World's mail door, or undefined for any other request. */
+export async function teamsPages(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path === '/_twin/mail' && request.method === 'GET') {
+    const to = (url.searchParams.get('to') ?? '').toLowerCase();
+    const mails = (await contextFor(new Request(request.url))).rowsRaw(MAIL).filter((m) => m.to === to).map((m) => ({ at: m.at, subject: m.subject, text: m.text }));
+    return Response.json({ to, mails });
+  }
+  const invite = /^\/invite\/([0-9a-f]+)$/.exec(path);
+  if (path !== PATH && path !== `${PATH}/revoke` && !invite) return undefined;
+  const ctx = await contextFor(new Request(request.url));
+  const person = signedIn(ctx, request);
+  if (!person) return toSignIn(request);
+  if (invite) {
+    const member = ctx.rowsRaw('TeamMember').find((m) => m._invite === invite[1] && m._pending === true && !m._removed_at);
+    if (!member) return new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    const [team, role] = [String(member.team_name), String(member.member_role)];
+    if (member.member_email !== person.email) return invitePage(team, role, invite[1]!, `This invitation is for ${String(member.member_email)}. Log in as that user to accept it.`, 403);
+    if (request.method !== 'POST') return invitePage(team, role, invite[1]!);
+    await ctx.write('TeamMember', `${String(member.team_id)}:${person.email}`, { ...ctx.own(member), _pending: false, _joined_at: ctx.occurredAt }, 'team.accept-invite');
+    return teamsPage(await contextFor(new Request(request.url)), person.email, `You joined ${team}.`);
+  }
+  return path === PATH ? teamsPage(ctx, person.email) : revokeInvite(ctx, person.email, request, contextFor);
+}
+
+/** Revoke Invite: a pending member goes, by the team's Owner or an Admin. */
+async function revokeInvite(ctx: SemanticsContext, email: string, request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response> {
+  const form = await formOf(request);
+  const team = String(form.team_id ?? '');
+  const pending = membersOf(ctx, team).find((m) => m.member_email === form.member_email && m._pending === true);
+  if (!pending || !['owner', 'admin'].includes(roleOf(ctx, team, email) ?? '')) return teamsPage(ctx, email, 'There is no pending invitation you can revoke.');
+  await removeMember(ctx, team, String(pending.member_email), 'team.revoke-invite');
+  return teamsPage(await contextFor(new Request(request.url)), email, `The invitation to ${String(pending.member_email)} was revoked.`);
+}

package/dist/api/src/semantics/backups.d.ts

@@ -0,0 +1,7 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+export declare const COMPLETE_AFTER_MS: number;
+export declare const DAILY_KEPT_MS = 86400000;
+/** Make a backup of a database as it stands at `ctx.occurredAt`, `pending` until it completes. */
+export declare function makeBackup(ctx: SemanticsContext, db: Row, name: string, daily: boolean): Promise<Row>;
+export declare const backupSemantics: Record<string, Semantics>;

package/dist/api/src/semantics/backups.js

@@ -0,0 +1,75 @@
+import { keyspaceImage, restoreKeyspace } from "../../../src/upstash-store.js";
+import { backingUp, badRequest, body, live, ownFields, uuidOf } from "./shared.js";
+export const COMPLETE_AFTER_MS = 2 * 60_000;
+export const DAILY_KEPT_MS = 86_400_000;
+const scope = (ctx, database) => ({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, database });
+/** Make a backup of a database as it stands at `ctx.occurredAt`, `pending` until it completes. */
+export async function makeBackup(ctx, db, name, daily) {
+    const database = String(db.database_id);
+    const image = keyspaceImage(scope(ctx, database));
+    const id = uuidOf(`backup:${database}:${ctx.occurredAt}:${name}:${ctx.rowsRaw('Backup', { withDeleted: true }).length + 1}`);
+    const fields = {
+        database_id: database, customer_id: db.customer_id, name, backup_id: id, creation_time: Math.floor(Date.parse(ctx.occurredAt) / 1000),
+        state: 'pending', backup_size: Buffer.byteLength(JSON.stringify(image)), daily_backup: String(daily), hourly_backup: 'false', internal_backup_tag: '',
+        _image: image, _owner: db._owner, _created_at: ctx.occurredAt,
+    };
+    await ctx.write('Backup', id, fields, daily ? 'backup.daily' : 'backup.create');
+    return fields;
+}
+/** The live backups of a database, oldest first. */
+const backupsOf = (ctx, database) => ctx.rowsRaw('Backup').filter((k) => k.database_id === database && !k._deleted_at).sort((a, b) => Number(a.creation_time) - Number(b.creation_time));
+/** createBackup {name}: a backup of the database now, answered "OK" (its 200 schema). */
+const createBackup = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const db = live(ctx, id);
+    if (!db)
+        return ctx.notFound('Database', id, 'id');
+    const name = typeof body(ctx).name === 'string' ? String(body(ctx).name).trim() : '';
+    if (!name)
+        return badRequest(ctx, 'name is required');
+    const busy = backingUp(ctx, id);
+    if (busy)
+        return busy;
+    await makeBackup(ctx, db, name, false);
+    return ctx.reply('OK', 200);
+};
+/** listBackup: the database's backups, as the Backup schema answers each. */
+const listBackup = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    if (!live(ctx, id))
+        return ctx.notFound('Database', id, 'id');
+    return ctx.reply(backupsOf(ctx, id).map((k) => ownFields(ctx.own(k))));
+};
+/** deleteBackup: the backup goes, answered "OK". */
+const deleteBackup = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    if (!live(ctx, id))
+        return ctx.notFound('Database', id, 'id');
+    const backup = backupsOf(ctx, id).find((k) => k.backup_id === ctx.call.params.backup_id);
+    if (!backup)
+        return ctx.notFound('Backup', String(ctx.call.params.backup_id), 'backup_id');
+    await ctx.write('Backup', String(backup.backup_id), { ...ctx.own(backup), _deleted_at: ctx.occurredAt }, 'backup.delete');
+    return ctx.reply('OK', 200);
+};
+/** restoreBackup {backup_id}: the database's keys are replaced by the backup's, answered "OK". */
+const restoreBackup = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    if (!live(ctx, id))
+        return ctx.notFound('Database', id, 'id');
+    const wanted = String(body(ctx).backup_id ?? '');
+    const backup = ctx.rowsRaw('Backup').find((k) => k.backup_id === wanted && !k._deleted_at && k.state === 'completed' && live(ctx, String(k.database_id)));
+    if (!backup)
+        return badRequest(ctx, `backup ${wanted} is not a completed backup of a database in your account`);
+    await restoreKeyspace(backup._image, scope(ctx, id));
+    return ctx.reply('OK', 200);
+};
+/** enableDailyBackup: from now the database is backed up every day (semantics/time.ts), answered "OK". */
+const enableDailyBackup = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const db = live(ctx, id);
+    if (!db)
+        return ctx.notFound('Database', id, 'id');
+    await ctx.write('Database', id, { ...ctx.own(db), daily_backup_enabled: true, _daily_since: ctx.occurredAt }, 'database.enable-dailybackup');
+    return ctx.reply('OK', 200);
+};
+export const backupSemantics = { createBackup, listBackup, deleteBackup, restoreBackup, enableDailyBackup };

package/dist/api/src/semantics/backups.ts

@@ -0,0 +1,90 @@
+// A Redis database's backups (https://upstash.com/docs/redis/features/backup; the spec's create-backup, list-backup,
+// delete-backup, restore-backup and enable-dailybackup). A backup holds the database's keys as they stood when it was
+// made (the pack root's store, `keyspaceImage`), and a restore empties its target and writes them back: "All existing data
+// in the target database will be deleted before the restore operation begins". "You can restore your database from any
+// backup in your account or team": a backup of any database the caller reaches restores into any other it reaches.
+//
+// Where the pages stop and the twin decides: a backup is `pending` for two minutes and then `completed` (semantics/time.ts);
+// a manual backup is kept until it is deleted; a daily backup is made at 00:00 UTC each day after daily backup is enabled,
+// named `daily-backup-<date>`, and kept one day after it completes (the console offers "1 or 3 days", the API's
+// enable-dailybackup takes none, and the production checklist gives "Backup retention up to 3 days with Prod Pack",
+// https://upstash.com/docs/redis/help/production-checklist); a backup's size is the bytes of the keys it holds; an unknown
+// backup, or one not yet completed, answers 400 to a restore and 404 to a delete.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { keyspaceImage, restoreKeyspace, type KeyImage } from '../../../src/upstash-store.ts';
+import { backingUp, badRequest, body, live, ownFields, uuidOf, type Row } from './shared.ts';
+
+export const COMPLETE_AFTER_MS = 2 * 60_000;
+export const DAILY_KEPT_MS = 86_400_000;
+
+const scope = (ctx: SemanticsContext, database: string) => ({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, database });
+
+/** Make a backup of a database as it stands at `ctx.occurredAt`, `pending` until it completes. */
+export async function makeBackup(ctx: SemanticsContext, db: Row, name: string, daily: boolean): Promise<Row> {
+  const database = String(db.database_id);
+  const image = keyspaceImage(scope(ctx, database));
+  const id = uuidOf(`backup:${database}:${ctx.occurredAt}:${name}:${ctx.rowsRaw('Backup', { withDeleted: true }).length + 1}`);
+  const fields: Row = {
+    database_id: database, customer_id: db.customer_id, name, backup_id: id, creation_time: Math.floor(Date.parse(ctx.occurredAt) / 1000),
+    state: 'pending', backup_size: Buffer.byteLength(JSON.stringify(image)), daily_backup: String(daily), hourly_backup: 'false', internal_backup_tag: '',
+    _image: image, _owner: db._owner, _created_at: ctx.occurredAt,
+  };
+  await ctx.write('Backup', id, fields, daily ? 'backup.daily' : 'backup.create');
+  return fields;
+}
+
+/** The live backups of a database, oldest first. */
+const backupsOf = (ctx: SemanticsContext, database: string): Row[] =>
+  ctx.rowsRaw('Backup').filter((k) => k.database_id === database && !k._deleted_at).sort((a, b) => Number(a.creation_time) - Number(b.creation_time));
+
+/** createBackup {name}: a backup of the database now, answered "OK" (its 200 schema). */
+const createBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const db = live(ctx, id);
+  if (!db) return ctx.notFound('Database', id, 'id');
+  const name = typeof body(ctx).name === 'string' ? String(body(ctx).name).trim() : '';
+  if (!name) return badRequest(ctx, 'name is required');
+  const busy = backingUp(ctx, id);
+  if (busy) return busy;
+  await makeBackup(ctx, db, name, false);
+  return ctx.reply('OK', 200);
+};
+
+/** listBackup: the database's backups, as the Backup schema answers each. */
+const listBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  return ctx.reply(backupsOf(ctx, id).map((k) => ownFields(ctx.own(k))));
+};
+
+/** deleteBackup: the backup goes, answered "OK". */
+const deleteBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  const backup = backupsOf(ctx, id).find((k) => k.backup_id === ctx.call.params.backup_id);
+  if (!backup) return ctx.notFound('Backup', String(ctx.call.params.backup_id), 'backup_id');
+  await ctx.write('Backup', String(backup.backup_id), { ...ctx.own(backup), _deleted_at: ctx.occurredAt }, 'backup.delete');
+  return ctx.reply('OK', 200);
+};
+
+/** restoreBackup {backup_id}: the database's keys are replaced by the backup's, answered "OK". */
+const restoreBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  const wanted = String(body(ctx).backup_id ?? '');
+  const backup = ctx.rowsRaw('Backup').find((k) => k.backup_id === wanted && !k._deleted_at && k.state === 'completed' && live(ctx, String(k.database_id)));
+  if (!backup) return badRequest(ctx, `backup ${wanted} is not a completed backup of a database in your account`);
+  await restoreKeyspace(backup._image as KeyImage[], scope(ctx, id));
+  return ctx.reply('OK', 200);
+};
+
+/** enableDailyBackup: from now the database is backed up every day (semantics/time.ts), answered "OK". */
+const enableDailyBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const db = live(ctx, id);
+  if (!db) return ctx.notFound('Database', id, 'id');
+  await ctx.write('Database', id, { ...ctx.own(db), daily_backup_enabled: true, _daily_since: ctx.occurredAt }, 'database.enable-dailybackup');
+  return ctx.reply('OK', 200);
+};
+
+export const backupSemantics: Record<string, Semantics> = { createBackup, listBackup, deleteBackup, restoreBackup, enableDailyBackup };

package/dist/api/src/semantics/index.d.ts

@@ -0,0 +1,10 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** A database's own fields (never the kernel's), as the Database schema answers it; `credentials=hide` leaves out its
+ *  password and REST tokens. */
+export declare function view(record: Row, hide: boolean): Row;
+/** A new API key for `email`: its name, permission and expiry, the key shown once and kept as its SHA-256. */
+export declare function makeApiKey(ctx: SemanticsContext, email: string, name: string, permission: 'read_write' | 'read_only', expiresAt: string | null): Promise<{
+    key: string;
+}>;
+export declare const apiSemantics: Record<string, Semantics>;

package/dist/api/src/semantics/index.js

@@ -0,0 +1,191 @@
+// The Developer API lane's handlers, by operationId. Where Upstash's reference stops and the twin decides, the comment
+// beside the rule says so.
+import { createHash } from 'node:crypto';
+import { execRedisRun } from "../../../src/upstash-store.js";
+import { backupSemantics } from "./backups.js";
+import { teamSemantics } from "./teams.js";
+import { backingUp, badRequest, body, emailOf, hex, live, ownFields, uuidOf } from "./shared.js";
+// the CreateDatabaseRequest schema's enums
+const PLATFORMS = ['aws', 'gcp'];
+const REGIONS = ['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', 'ca-central-1', 'eu-central-1', 'eu-west-1', 'eu-west-2', 'sa-east-1', 'ap-south-1',
+    'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2', 'af-south-1', 'us-central1', 'us-east4', 'europe-west1', 'asia-northeast1'];
+const PLANS = ['free', 'payg', 'fixed_250mb', 'fixed_1gb', 'fixed_5gb', 'fixed_10gb', 'fixed_50gb', 'fixed_100gb', 'fixed_500gb'];
+// an endpoint slug in the shape the Database schema's example has ("beloved-stallion-58500"); the words are the twin's
+const ADJECTIVES = ['beloved', 'brave', 'calm', 'clever', 'eager', 'gentle', 'happy', 'lucky', 'merry', 'proud', 'quiet', 'striking'];
+const ANIMALS = ['stallion', 'osprey', 'cat', 'heron', 'otter', 'lynx', 'badger', 'falcon', 'marten', 'wren', 'bison', 'gecko'];
+const MB = 1024 * 1024;
+const GB = 1024 * MB;
+/** The pay-as-you-go and fixed plans' "Unlimited" monthly commands: no page says how the API writes it, so the twin
+ *  answers the Database schema's example `db_request_limit` (8024278031528737000), a paid database's. */
+const UNLIMITED = 8024278031528737000;
+/** A plan's limits as https://upstash.com/pricing/redis tables them: the plans table ("Max data size", "Monthly Commands",
+ *  "Max commands per second", "Max request size", "Max record size": Free 256 MB, 500K, 10,000, 10 MB, 100 MB; Pay as You
+ *  Go 100 GB, Unlimited, 10,000, 10 MB, 100 MB) and "Fixed plans — all tiers" ("Max data", "Max commands/sec", "Max
+ *  request size", "Max record size" per tier; their Monthly Commands "Unlimited"). */
+const limits = (disk, requests, perSecond, request, entry) => ({ db_disk_threshold: disk, db_request_limit: requests, db_max_commands_per_second: perSecond, db_max_request_size: request, db_max_entry_size: entry });
+const PLAN_LIMITS = {
+    free: limits(256 * MB, 500000, 10000, 10 * MB, 100 * MB),
+    payg: limits(100 * GB, UNLIMITED, 10000, 10 * MB, 100 * MB),
+    fixed_250mb: limits(250 * MB, UNLIMITED, 10000, 10 * MB, 100 * MB),
+    fixed_1gb: limits(1 * GB, UNLIMITED, 10000, 10 * MB, 200 * MB),
+    fixed_5gb: limits(5 * GB, UNLIMITED, 10000, 20 * MB, 300 * MB),
+    fixed_10gb: limits(10 * GB, UNLIMITED, 10000, 30 * MB, 400 * MB),
+    fixed_50gb: limits(50 * GB, UNLIMITED, 10000, 50 * MB, 500 * MB),
+    fixed_100gb: limits(100 * GB, UNLIMITED, 16000, 75 * MB, 1 * GB),
+    fixed_500gb: limits(500 * GB, UNLIMITED, 16000, 100 * MB, 5 * GB),
+};
+const FREE_REGIONS = 'Free usage is limited with max one read region';
+/** The free plan's refusals, each 400 (the twin's reading of the HTTP status codes page's "Your request is invalid"): "Max
+ *  Databases 1" (https://upstash.com/pricing/redis) and "Free usage is limited with max one read region"
+ *  (https://upstash.com/docs/redis/features/globaldatabase). */
+function freePlanRefusal(ctx, owner, readRegions) {
+    if (readRegions.length > 1)
+        return badRequest(ctx, FREE_REGIONS);
+    if (ctx.rowsRaw('Database').some((d) => d._owner === owner && ctx.own(d).type === 'free' && !d._deleted_at))
+        return badRequest(ctx, 'The free plan allows 1 database');
+    return undefined;
+}
+/** A database's id from the World's instant, the name and the count, so a World mints the same id every run. */
+const mintUuid = (ctx, seed) => uuidOf(`database:${ctx.occurredAt}:${seed}:${ctx.rowsRaw('Database', { withDeleted: true }).length + 1}`);
+/** A database's own fields (never the kernel's), as the Database schema answers it; `credentials=hide` leaves out its
+ *  password and REST tokens. */
+export function view(record, hide) {
+    const out = ownFields(record);
+    if (hide) {
+        delete out.password;
+        delete out.rest_token;
+        delete out.read_only_rest_token;
+    }
+    return out;
+}
+/** A database's password and REST tokens, new for every instant they are made at and every reset (`generation`). */
+function credentials(ctx, id, generation = 0) {
+    const secret = (what, length) => createHash('sha256').update(`${what}:${id}:${ctx.occurredAt}:${generation}`).digest('base64url').slice(0, length);
+    // the Standard and Read Only REST tokens (the spec patch, from Upstash's Terraform provider): the twin's tokens are
+    // opaque strings in the shape Upstash's have, an `A` then base64url
+    return { password: secret('password', 32), rest_token: `A${secret('rest', 59)}`, read_only_rest_token: `Ag${secret('readonly', 58)}` };
+}
+/** createDatabase. `database_name` and `primary_region` are required (CreateDatabaseRequest, whose `platform` the spec
+ *  patch makes optional: Upstash's own CLI sends none, spec/patches.json), each enum as the schema lists it; a database
+ *  made without a platform is on aws (the twin's decision). `region` is `global`, the one value the CLI sends. Where the reference stops and the twin decides: a missing or unlisted field, and a name the
+ *  account already has, answer 400 naming it; the database is `active` at once (the getDatabase example's state), on the
+ *  plan asked for or `free` ("If omitted, the database defaults to either the pay-as-you-go or free plan, based on the
+ *  account type": an account is free unless the World made it pay-as-you-go, screens/session.tsx's door); its limits are its plan's (PLAN_LIMITS, from
+ *  https://upstash.com/pricing/redis), with the schema's example values for the rest (manifest.ts names them). Its
+ *  REST endpoint is `https://<endpoint>.upstash.io`, which answers its two REST tokens (the pack root's auth). */
+const createDatabase = async (ctx) => {
+    const b = body(ctx);
+    const name = typeof b.database_name === 'string' ? b.database_name.trim() : '';
+    if (!name)
+        return badRequest(ctx, 'database_name is required');
+    if (b.platform !== undefined && !PLATFORMS.includes(String(b.platform)))
+        return badRequest(ctx, `platform must be one of ${PLATFORMS.join(', ')}`);
+    if (typeof b.primary_region !== 'string' || !REGIONS.includes(b.primary_region))
+        return badRequest(ctx, `primary_region must be one of ${REGIONS.join(', ')}`);
+    const owner = emailOf(ctx);
+    const plan = b.plan === undefined ? String(ctx.rowsRaw('_person').find((p) => p.email === owner)?.plan ?? 'free') : String(b.plan);
+    if (!PLANS.includes(plan))
+        return badRequest(ctx, `plan must be one of ${PLANS.join(', ')}`);
+    const readRegions = Array.isArray(b.read_regions) ? b.read_regions.map(String) : [];
+    const freeRefusal = plan === 'free' ? freePlanRefusal(ctx, owner, readRegions) : undefined;
+    if (freeRefusal)
+        return freeRefusal;
+    if (ctx.rowsRaw('Database').some((d) => d.database_name === name && d._owner === owner && !d._deleted_at))
+        return badRequest(ctx, `database ${name} already exists`);
+    const id = mintUuid(ctx, name);
+    const h = hex(`endpoint:${id}`);
+    const endpoint = `${ADJECTIVES[parseInt(h.slice(0, 2), 16) % ADJECTIVES.length]}-${ANIMALS[parseInt(h.slice(2, 4), 16) % ANIMALS.length]}-${10000 + (parseInt(h.slice(4, 10), 16) % 90000)}`;
+    const fields = {
+        database_id: id, database_name: name, region: 'global', port: 6379, creation_time: Math.floor(Date.parse(ctx.occurredAt) / 1000),
+        state: 'active', ...credentials(ctx, id), endpoint, tls: b.tls !== false, type: plan === 'free' ? 'free' : plan === 'payg' ? 'payg' : 'paid',
+        budget: typeof b.budget === 'number' ? b.budget : 0, primary_region: b.primary_region, primary_members: [b.primary_region],
+        all_members: [b.primary_region, ...readRegions], read_regions: readRegions, eviction: b.eviction === true, auto_upgrade: false, consistent: false,
+        modifying_state: '', db_max_clients: 10000, ...PLAN_LIMITS[plan],
+        db_memory_threshold: 268435456, db_resource_size: 'S', db_type: 'pebble',
+        // the Database schema's example values (the reference page's rendered answer) for the limits no page states per plan
+        // (manifest.ts records them as the twin's choice)
+        db_conn_idle_timeout: 21600000000000, db_lua_timeout: 250000000, db_lua_credits_per_min: 10000000000, db_store_max_idle: 900000000000,
+        db_max_loads_per_sec: 1000000, replicas: 5,
+        securityAddons: { ipWhitelisting: false, vpcPeering: false, privateLink: false, tlsMutualAuth: false, encryptionAtRest: false },
+        db_acl_enabled: 'false', db_acl_default_user_status: 'true', db_eviction: b.eviction === true, last_plan_upgrade_time: 0,
+        customer_id: owner, daily_backup_enabled: false, prometheus_enabled: 'false', prod_pack_enabled: false,
+        _owner: owner,
+    };
+    await ctx.write('Database', id, fields, 'database.create');
+    return ctx.reply(view(fields, false), 200);
+};
+/** getDatabase. `credentials=hide` "remove[s] credentials from the response". A database the account deleted, or never
+ *  had, answers 404 (the twin's decision; the reference declares no error response). */
+const getDatabase = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const record = live(ctx, id);
+    if (!record)
+        return ctx.notFound('Database', id, 'id');
+    return ctx.reply(view(ctx.own(record), new URL(ctx.call.request.url).searchParams.get('credentials') === 'hide'));
+};
+/** deleteDatabase answers "OK" (its 200 schema). A deleted database's data goes with it and its REST tokens answer the
+ *  REST API's 401 from then on (the pack root's auth): the twin empties its keyspace with FLUSHALL on its own database. */
+const deleteDatabase = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const record = live(ctx, id);
+    if (!record)
+        return ctx.notFound('Database', id, 'id');
+    await execRedisRun([['FLUSHALL']], { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, database: id });
+    await ctx.write('Database', id, { ...ctx.own(record), _deleted_at: ctx.occurredAt }, 'database.delete');
+    return ctx.reply('OK', 200);
+};
+// ── API keys (made on the console's Developer API tab, screens/developer-api.tsx) ─────────────
+/** A new API key for `email`: its name, permission and expiry, the key shown once and kept as its SHA-256. */
+export async function makeApiKey(ctx, email, name, permission, expiresAt) {
+    const n = ctx.rowsRaw('_api_key').length + 1;
+    const key = hex(`apikey:${email}:${name}:${ctx.occurredAt}:${n}`).slice(0, 36);
+    await ctx.record('_api_key', { email, name, permission, expires_at: expiresAt, created_at: ctx.occurredAt, deleted: false, key_sha256: hex(key) }, `apikey:${email}:${name}`);
+    return { key };
+}
+/** resetPassword "updates the password of a database" (the spec), and "You can revoke both _Standard_ and _Read Only_
+ *  tokens by resetting password of your database" (https://upstash.com/docs/redis/features/restapi): the old tokens
+ *  answer the REST API's 401 from then on (the pack root's auth reads them from this record). Its answer is the
+ *  `Database` with the new credentials (the twin's reading of its 200 schema; the page does not say). */
+const resetPassword = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const record = live(ctx, id);
+    if (!record)
+        return ctx.notFound('Database', id, 'id');
+    const own = ctx.own(record);
+    const revoked = [...(Array.isArray(own._revoked_tokens) ? own._revoked_tokens : []), own.rest_token, own.read_only_rest_token];
+    const fields = { ...own, ...credentials(ctx, id, revoked.length), _revoked_tokens: revoked };
+    await ctx.write('Database', id, fields, 'database.reset-password');
+    return ctx.reply(view(fields, false), 200);
+};
+// the read regions update-regions takes (its request schema's enum)
+const READ_REGIONS = ['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', 'ca-central-1', 'eu-central-1', 'eu-west-1', 'eu-west-2', 'sa-east-1', 'ap-south-1', 'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2'];
+/** updateRegions sets a database's read regions ("You can add or remove regions on a running Redis database",
+ *  https://upstash.com/docs/redis/features/globaldatabase) and answers "OK". Where the reference stops and the twin
+ *  decides: a region outside the schema's enum, or no array, answers 400; writes still go to the primary region. */
+const updateRegions = async (ctx) => {
+    const id = String(ctx.call.params.id);
+    const record = live(ctx, id);
+    if (!record)
+        return ctx.notFound('Database', id, 'id');
+    const asked = body(ctx).read_regions;
+    const regions = Array.isArray(asked) ? asked.map(String) : ['none'];
+    if (regions.some((r) => !READ_REGIONS.includes(r)))
+        return badRequest(ctx, `read_regions must be an array of ${READ_REGIONS.join(', ')}`);
+    if (ctx.own(record).type === 'free' && regions.length > 1)
+        return badRequest(ctx, FREE_REGIONS);
+    const busy = backingUp(ctx, id);
+    if (busy)
+        return busy;
+    const own = ctx.own(record);
+    await ctx.write('Database', id, { ...own, read_regions: regions, all_members: [own.primary_region, ...regions] }, 'database.update-regions');
+    return ctx.reply('OK', 200);
+};
+export const apiSemantics = {
+    createDatabase,
+    getDatabase,
+    deleteDatabase,
+    resetPassword,
+    updateRegions,
+    ...backupSemantics,
+    ...teamSemantics,
+};