@ericminassian/plat 0.0.0-stage → 0.1.0

package/template/src/server.ts

@@ -0,0 +1,100 @@
+import { auth, db, events, metrics, app as platform, queue } from '@ericminassian/platform';
+import { Hono } from 'hono';
+import { validator } from 'hono/validator';
+import { z } from 'zod';
+import type { EmailJob, Todo, TodoCreated } from './types.ts';
+
+// One collection per entity. Partition by user so each user's todos are one query.
+// Sort keys are time-ordered ids, so `query` returns oldest first.
+const todos = db.collection<Todo>('todos', { partition: 'userId', sort: 'id' });
+
+const NewTodo = z.object({ title: z.string().trim().min(1).max(200) });
+const PatchTodo = z.object({
+  title: z.string().trim().min(1).max(200).optional(),
+  done: z.boolean().optional(),
+});
+
+/** Validates a JSON body with a zod schema; the parsed type flows to the typed web client. */
+const json = <T extends z.ZodType>(schema: T) =>
+  validator('json', (value, c) => {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) return c.json({ error: parsed.error.issues[0]?.message ?? 'invalid body' }, 400);
+    return parsed.data as z.infer<T>;
+  });
+
+/** Time-sortable id: 9 chars of base36 ms timestamp + 8 random chars. */
+function newId(): string {
+  return Date.now().toString(36).padStart(9, '0') + crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+}
+
+const api = new Hono()
+  .get('/health', (c) => c.json({ ok: true, app: platform.name, stage: platform.stage }))
+
+  .get('/me', async (c) => c.json({ user: await auth.getUser(c.req.raw) }))
+
+  .get('/todos', async (c) => {
+    const user = await auth.requireUser(c.req.raw);
+    const page = await todos.query({ userId: user.id });
+    return c.json({ todos: page.items });
+  })
+
+  .post('/todos', json(NewTodo), async (c) => {
+    const user = await auth.requireUser(c.req.raw);
+    const input = c.req.valid('json');
+
+    const todo: Todo = {
+      userId: user.id,
+      id: newId(),
+      title: input.title,
+      done: false,
+      createdAt: new Date().toISOString(),
+    };
+    await todos.put(todo, { ifNotExists: true });
+    await events.publish<TodoCreated>('todo.created', { userId: user.id, id: todo.id, title: todo.title });
+    if (user.email) {
+      await queue<EmailJob>('emails').send({ to: user.email, subject: 'New todo', body: todo.title });
+    }
+    metrics.count('todos.created');
+    return c.json({ todo }, 201);
+  })
+
+  .patch('/todos/:id', json(PatchTodo), async (c) => {
+    const user = await auth.requireUser(c.req.raw);
+    const key = { userId: user.id, id: c.req.param('id') };
+    if (!(await todos.get(key))) return c.json({ error: 'not found' }, 404);
+    const todo = await todos.update(key, c.req.valid('json'));
+    return c.json({ todo });
+  })
+
+  .delete('/todos/:id', async (c) => {
+    const user = await auth.requireUser(c.req.raw);
+    await todos.delete({ userId: user.id, id: c.req.param('id') });
+    return c.body(null, 204);
+  });
+
+const app = new Hono();
+
+// `auth.requireUser` throws a 401 Response when signed out: send it as-is.
+app.use(async (c, next) => {
+  try {
+    await next();
+  } catch (err) {
+    if (err instanceof Response) {
+      c.res = err;
+      return;
+    }
+    throw err;
+  }
+});
+app.route('/api', api);
+
+// Anything else is a bug: rethrow so the platform records it (error group, trace
+// id, stack) and answers 500, instead of Hono swallowing it.
+app.onError((err) => {
+  throw err;
+});
+
+/** Typed client for the frontend: `hc<ApiType>('/api')` from `hono/client`. */
+export type ApiType = typeof api;
+
+export default app;

package/template/src/types.ts

@@ -0,0 +1,21 @@
+/** Shared between the server, the worker and the web client. */
+
+export type Todo = {
+  userId: string;
+  id: string;
+  title: string;
+  done: boolean;
+  createdAt: string;
+};
+
+export type EmailJob = {
+  to: string;
+  subject: string;
+  body: string;
+};
+
+export type TodoCreated = {
+  userId: string;
+  id: string;
+  title: string;
+};

package/template/src/worker.ts

@@ -0,0 +1,32 @@
+import { log, metrics } from '@ericminassian/platform';
+import { defineWorker, type PlatformEvent, type QueueMessage } from '@ericminassian/platform/worker';
+import type { EmailJob, TodoCreated } from './types.ts';
+
+// Every key here must match platform.json: `queues`, `events` and `crons`.
+// Throwing retries the job (queues: up to maxReceiveCount, then the dead-letter queue).
+export default defineWorker({
+  queues: {
+    emails: async (message: QueueMessage<EmailJob>) => {
+      // Swap in a real email provider here (store its API key with `plat secrets set`).
+      log.info('would send email', {
+        to: message.body.to,
+        subject: message.body.subject,
+        attempt: message.attempt,
+      });
+      metrics.count('emails.sent');
+    },
+  },
+
+  events: {
+    'todo.created': async (event: PlatformEvent<TodoCreated>) => {
+      log.info('todo created', { id: event.detail.id, userId: event.detail.userId });
+    },
+  },
+
+  crons: {
+    cleanup: async () => {
+      log.info('nightly cleanup ran');
+      metrics.count('cleanup.runs');
+    },
+  },
+});

package/template/test/server.test.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Unit tests replace the platform SDK with in-memory fakes, so they run with no
+// emulator and no AWS. Integration tests (`*.integration.test.ts`, `plat test`)
+// use the real SDK against the AWS Emulator.
+const store = new Map<string, Record<string, unknown>>();
+const published: Array<{ type: string; detail: unknown }> = [];
+const sent: unknown[] = [];
+
+vi.mock('@ericminassian/platform', () => {
+  const userFrom = (req: Request) => {
+    const id = req.headers.get('x-test-user');
+    return id ? { id, email: `${id}@example.com`, groups: [] } : null;
+  };
+  return {
+    app: {
+      name: 'template-app',
+      stage: 'test',
+      host: 'localhost',
+      url: 'http://localhost',
+      revision: 'd0',
+      isLocal: true,
+    },
+    auth: {
+      getUser: async (req: Request) => userFrom(req),
+      requireUser: async (req: Request) => {
+        const u = userFrom(req);
+        if (!u) throw new Response('unauthorized', { status: 401 });
+        return u;
+      },
+    },
+    db: {
+      collection: (name: string) => {
+        const k = (key: Record<string, unknown>) => `${name}#${key.userId}#${key.id}`;
+        return {
+          get: async (key: Record<string, unknown>) => store.get(k(key)),
+          put: async (item: Record<string, unknown>) => {
+            store.set(k(item), item);
+            return item;
+          },
+          update: async (key: Record<string, unknown>, patch: Record<string, unknown>) => {
+            const next = { ...store.get(k(key)), ...patch };
+            store.set(k(key), next);
+            return next;
+          },
+          delete: async (key: Record<string, unknown>) => void store.delete(k(key)),
+          query: async (part: Record<string, unknown>) => ({
+            items: [...store.entries()]
+              .filter(([key]) => key.startsWith(`${name}#${part.userId}#`))
+              .map(([, v]) => v),
+          }),
+        };
+      },
+    },
+    events: { publish: async (type: string, detail: unknown) => void published.push({ type, detail }) },
+    queue: () => ({ send: async (body: unknown) => void sent.push(body), sendBatch: async () => {} }),
+    metrics: { count: () => {}, value: () => {} },
+    log: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+  };
+});
+
+const { default: app } = await import('../src/server.ts');
+
+const as = (user: string) => ({ 'x-test-user': user, 'content-type': 'application/json' });
+
+describe('api', () => {
+  beforeEach(() => {
+    store.clear();
+    published.length = 0;
+    sent.length = 0;
+  });
+
+  it('reports health', async () => {
+    const res = await app.request('/api/health');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ ok: true, app: 'template-app' });
+  });
+
+  it('requires sign-in for todos', async () => {
+    const res = await app.request('/api/todos');
+    expect(res.status).toBe(401);
+  });
+
+  it('creates, lists, toggles and deletes todos', async () => {
+    const created = await app.request('/api/todos', {
+      method: 'POST',
+      headers: as('u1'),
+      body: JSON.stringify({ title: 'Buy milk' }),
+    });
+    expect(created.status).toBe(201);
+    const { todo } = (await created.json()) as { todo: { id: string; done: boolean } };
+    expect(published).toEqual([{ type: 'todo.created', detail: expect.objectContaining({ id: todo.id }) }]);
+    expect(sent).toHaveLength(1);
+
+    const list = await app.request('/api/todos', { headers: as('u1') });
+    expect(((await list.json()) as { todos: unknown[] }).todos).toHaveLength(1);
+    const other = await app.request('/api/todos', { headers: as('u2') });
+    expect(((await other.json()) as { todos: unknown[] }).todos).toHaveLength(0);
+
+    const patched = await app.request(`/api/todos/${todo.id}`, {
+      method: 'PATCH',
+      headers: as('u1'),
+      body: JSON.stringify({ done: true }),
+    });
+    expect(((await patched.json()) as { todo: { done: boolean } }).todo.done).toBe(true);
+
+    const deleted = await app.request(`/api/todos/${todo.id}`, { method: 'DELETE', headers: as('u1') });
+    expect(deleted.status).toBe(204);
+    expect(store.size).toBe(0);
+  });
+
+  it('validates input', async () => {
+    const res = await app.request('/api/todos', {
+      method: 'POST',
+      headers: as('u1'),
+      body: JSON.stringify({ title: '' }),
+    });
+    expect(res.status).toBe(400);
+  });
+});

package/template/test/todos.integration.test.ts

@@ -0,0 +1,30 @@
+import { db } from '@ericminassian/platform';
+import { createPlatformFetch } from '@ericminassian/platform/server';
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.ts';
+import type { Todo } from '../src/types.ts';
+
+// Runs under `plat test`: real SDK, real (emulated) DynamoDB/SQS/EventBridge.
+const fetchApp = createPlatformFetch(app);
+
+describe('integration', () => {
+  it('serves health through the platform wrapper', async () => {
+    const res = await fetchApp(new Request('http://localhost/api/health'));
+    expect(res.status).toBe(200);
+  });
+
+  it('round-trips a todo through the database', async () => {
+    const todos = db.collection<Todo>('todos', { partition: 'userId', sort: 'id' });
+    const todo: Todo = {
+      userId: 'it-user',
+      id: `t-${Date.now()}`,
+      title: 'from a test',
+      done: false,
+      createdAt: new Date().toISOString(),
+    };
+    await todos.put(todo);
+    expect(await todos.get({ userId: todo.userId, id: todo.id })).toMatchObject({ title: 'from a test' });
+    const page = await todos.query({ userId: todo.userId });
+    expect(page.items.map((t) => t.id)).toContain(todo.id);
+  });
+});

package/template/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "test", "vitest.config.ts", "vitest.integration.config.ts"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,9 @@
+import { configDefaults, defineConfig } from 'vitest/config';
+
+// Unit tests: fast, no emulator. `*.integration.test.ts` runs under `plat test`.
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    exclude: [...configDefaults.exclude, '**/*.integration.test.ts'],
+  },
+});

package/template/vitest.integration.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+// Integration tests: `plat test` starts the AWS Emulator, provisions this app
+// (stage `test`) and runs these with the same environment deployed code gets.
+export default defineConfig({
+  test: {
+    include: ['test/**/*.integration.test.ts'],
+    testTimeout: 30_000,
+  },
+});

package/template/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>template-app</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/web/src/App.tsx

@@ -0,0 +1,102 @@
+import { type FormEvent, useCallback, useEffect, useState } from 'react';
+import type { Todo } from '../../src/types.ts';
+import { api, signInUrl, signOutUrl } from './api.ts';
+
+type User = { id: string; email?: string; name?: string };
+
+export function App() {
+  const [user, setUser] = useState<User | null | undefined>(undefined);
+  const [todos, setTodos] = useState<Todo[]>([]);
+  const [title, setTitle] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    const res = await api.todos.$get();
+    if (res.ok) setTodos((await res.json()).todos);
+  }, []);
+
+  useEffect(() => {
+    void (async () => {
+      const res = await api.me.$get();
+      const me = res.ok ? (await res.json()).user : null;
+      setUser(me);
+      if (me) await load();
+    })();
+  }, [load]);
+
+  async function add(e: FormEvent) {
+    e.preventDefault();
+    setError(null);
+    const res = await api.todos.$post({ json: { title } });
+    if (!res.ok) {
+      setError('Could not add that todo.');
+      return;
+    }
+    setTitle('');
+    await load();
+  }
+
+  async function toggle(todo: Todo) {
+    await api.todos[':id'].$patch({ param: { id: todo.id }, json: { done: !todo.done } });
+    await load();
+  }
+
+  async function remove(todo: Todo) {
+    await api.todos[':id'].$delete({ param: { id: todo.id } });
+    await load();
+  }
+
+  if (user === undefined) return <main className="card">Loading…</main>;
+
+  if (!user) {
+    return (
+      <main className="card">
+        <h1>template-app</h1>
+        <p>Sign in to keep a todo list.</p>
+        <a className="button" href={signInUrl()}>
+          Sign in
+        </a>
+      </main>
+    );
+  }
+
+  return (
+    <main className="card">
+      <header>
+        <h1>Todos</h1>
+        <span>
+          {user.email ?? user.name ?? user.id} · <a href={signOutUrl()}>Sign out</a>
+        </span>
+      </header>
+      <form onSubmit={add}>
+        <input
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="What needs doing?"
+          required
+        />
+        <button type="submit">Add</button>
+      </form>
+      {error && <p className="error">{error}</p>}
+      <ul>
+        {todos.map((t) => (
+          <li key={t.id}>
+            <label>
+              <input type="checkbox" checked={t.done} onChange={() => void toggle(t)} />
+              <span className={t.done ? 'done' : undefined}>{t.title}</span>
+            </label>
+            <button
+              type="button"
+              className="link"
+              onClick={() => void remove(t)}
+              aria-label={`Delete ${t.title}`}
+            >
+              ✕
+            </button>
+          </li>
+        ))}
+        {todos.length === 0 && <li className="empty">Nothing yet.</li>}
+      </ul>
+    </main>
+  );
+}

package/template/web/src/api.ts

@@ -0,0 +1,11 @@
+import { hc } from 'hono/client';
+import type { ApiType } from '../../src/server.ts';
+
+/** Typed API client: routes, params and JSON bodies come from src/server.ts. */
+export const api = hc<ApiType>('/api');
+
+/** Platform-provided sign-in/out routes (same origin, cookie session). */
+export const signInUrl = (redirect = window.location.pathname) =>
+  `/__platform/auth/login?redirect=${encodeURIComponent(redirect)}`;
+export const signOutUrl = (redirect = '/') =>
+  `/__platform/auth/logout?redirect=${encodeURIComponent(redirect)}`;

package/template/web/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App.tsx';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/template/web/src/styles.css

@@ -0,0 +1,102 @@
+:root {
+  --bg: #f6f6f4;
+  --fg: #1a1a1a;
+  --muted: #6b6b6b;
+  --card: #fff;
+  --border: #e3e3e0;
+  --accent: #1a1a1a;
+  --accent-fg: #fff;
+  color-scheme: light dark;
+  font:
+    16px / 1.5 system-ui,
+    sans-serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #121212;
+    --fg: #ececec;
+    --muted: #9a9a9a;
+    --card: #1c1c1c;
+    --border: #2e2e2e;
+    --accent: #ececec;
+    --accent-fg: #121212;
+  }
+}
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+}
+.card {
+  max-width: 520px;
+  margin: 10vh auto;
+  padding: 24px;
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+}
+header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 12px;
+  color: var(--muted);
+}
+header h1 {
+  color: var(--fg);
+}
+form {
+  display: flex;
+  gap: 8px;
+}
+input:not([type="checkbox"]) {
+  flex: 1;
+  padding: 8px 10px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+}
+button,
+.button {
+  padding: 8px 14px;
+  border: 0;
+  border-radius: 8px;
+  background: var(--accent);
+  color: var(--accent-fg);
+  font: inherit;
+  cursor: pointer;
+  text-decoration: none;
+  display: inline-block;
+}
+button.link {
+  background: none;
+  color: var(--muted);
+  padding: 4px 8px;
+}
+ul {
+  list-style: none;
+  padding: 0;
+}
+li {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 0;
+  border-bottom: 1px solid var(--border);
+}
+.done {
+  text-decoration: line-through;
+  color: var(--muted);
+}
+.empty,
+.error {
+  color: var(--muted);
+}
+.error {
+  color: #c33;
+}
+a {
+  color: inherit;
+}

package/template/web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/web/vite.config.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// `plat dev` serves everything on its local router (default :3000) and proxies
+// frontend requests here; opening this dev server directly also works because
+// API and platform routes are proxied back to the router.
+const router = process.env.PLATFORM_DEV_ROUTER ?? 'http://localhost:3000';
+
+export default defineConfig({
+  root: fileURLToPath(new URL('.', import.meta.url)),
+  plugins: [react()],
+  build: { outDir: 'dist', emptyOutDir: true },
+  server: {
+    port: 5173,
+    strictPort: true,
+    proxy: { '/api': router, '/__platform': router },
+  },
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.