@bhooai/nexus-examples 2.0.0

package/examples/file-storage/README.md

@@ -0,0 +1,48 @@
+# File storage example
+
+Uploads to two disks: a public `uploads` disk (plain URLs) and a `private`
+disk (signed URLs only). All through `storage.disk(...)` from
+`@bhooai/nexus-core`.
+
+## What's here
+
+- `apps/backend/src/routes/files.ts`
+  - `POST /api/files` — accept multipart upload onto the `uploads` disk
+  - `POST /api/files/private` — accept multipart upload onto the `private` disk
+  - `GET /api/files/:id/signed` — mint an HMAC-signed URL (5 min TTL) for any file
+  - `GET /api/files`, `DELETE /api/files/:id` — list + delete
+- `apps/frontend/src/main.tsx` — file input, list, inline preview for public images
+
+## Multipart parsing
+
+The Nexus body parser collects `multipart/form-data` file parts into
+`ctx.state.files`; `uploadedFiles(ctx)` is the typed accessor. No multer, no
+busboy dependency.
+
+## Switching to S3
+
+Disks are driver-based. Point a disk at S3 via env vars (the local driver is
+the default):
+
+```env
+NEXUS_STORAGE_DEFAULT=uploads
+NEXUS_STORAGE_DISKS_UPLOADS_DRIVER=s3
+NEXUS_STORAGE_DISKS_UPLOADS_BUCKET=my-bucket
+NEXUS_STORAGE_DISKS_UPLOADS_REGION=ap-south-1
+# optional for S3-compatible (MinIO, R2):
+NEXUS_STORAGE_DISKS_UPLOADS_ENDPOINT=https://...
+NEXUS_STORAGE_DISKS_UPLOADS_CDN_URL=https://cdn.example.com
+```
+
+`signedUrl()` automatically switches to S3 presigned URLs
+(`@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` are optional peer
+deps — install them when you enable the S3 driver).
+
+## Run
+
+```bash
+npx nexus dev
+```
+
+Upload a public image and a private file, then mint a signed URL for the
+private one.

package/examples/file-storage/apps/backend/src/routes/files.ts

@@ -0,0 +1,86 @@
+import { defineRoutes, storage, uploadedFiles } from '@bhooai/nexus-core';
+import { ValidationError, NotFoundError } from '@bhooai/nexus-core';
+
+/** Kept in-memory so the demo is self-contained; back with a model in real apps. */
+export interface FileEntry {
+  id: string;
+  disk: 'uploads' | 'private';
+  path: string;
+  url: string;
+  originalName: string;
+  mime: string;
+  size: number;
+}
+export const files = new Map<string, FileEntry>();
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/files',
+    handler: async (ctx) => {
+      ctx.json({ files: [...files.values()] });
+    },
+  },
+  {
+    // Public upload — goes to the 'uploads' disk and gets a plain public URL.
+    method: 'POST',
+    path: '/api/files',
+    handler: async (ctx) => {
+      const [file] = uploadedFiles(ctx);
+      if (!file) throw new ValidationError('a file is required');
+      const stored = await storage.disk('uploads').put('media', {
+        buffer: file.data,
+        originalName: file.filename,
+        mime: file.contentType,
+      });
+      const entry: FileEntry = {
+        id: stored.id, disk: 'uploads', path: stored.path, url: stored.url,
+        originalName: stored.originalName, mime: stored.mime, size: stored.size,
+      };
+      files.set(entry.id, entry);
+      ctx.json({ file: entry }, 201);
+    },
+  },
+  {
+    // Private upload — no public URL; access goes through signed URLs.
+    method: 'POST',
+    path: '/api/files/private',
+    handler: async (ctx) => {
+      const [file] = uploadedFiles(ctx);
+      if (!file) throw new ValidationError('a file is required');
+      const stored = await storage.disk('private').put('secure', {
+        buffer: file.data,
+        originalName: file.filename,
+        mime: file.contentType,
+      });
+      const entry: FileEntry = {
+        id: stored.id, disk: 'private', path: stored.path, url: '',
+        originalName: stored.originalName, mime: stored.mime, size: stored.size,
+      };
+      files.set(entry.id, entry);
+      ctx.json({ file: entry }, 201);
+    },
+  },
+  {
+    // Mint a signed URL (default TTL 5 minutes) for a file on any disk.
+    method: 'GET',
+    path: '/api/files/:id/signed',
+    handler: async (ctx) => {
+      const entry = files.get(ctx.params.id);
+      if (!entry) throw new NotFoundError('file not found');
+      const url = await storage.disk(entry.disk).signedUrl(entry.path, { ttl: 300 });
+      ctx.json({ url, expiresIn: 300 });
+    },
+  },
+  {
+    method: 'DELETE',
+    path: '/api/files/:id',
+    handler: async (ctx) => {
+      const entry = files.get(ctx.params.id);
+      if (!entry) throw new NotFoundError('file not found');
+      await storage.disk(entry.disk).delete(entry.path);
+      files.delete(entry.id);
+      ctx.json({ ok: true });
+    },
+  },
+]);

package/examples/file-storage/apps/frontend/src/main.tsx

@@ -0,0 +1,111 @@
+import React, { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+interface FileEntry {
+  id: string;
+  disk: 'uploads' | 'private';
+  path: string;
+  url: string;
+  originalName: string;
+  mime: string;
+  size: number;
+}
+
+const fmtSize = (n: number) => (n > 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(n / 1024)} KB`);
+
+function App() {
+  const [files, setFiles] = useState<FileEntry[]>([]);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState('');
+  const [signed, setSigned] = useState<Record<string, string>>({});
+  const [previews, setPreviews] = useState<Record<string, string>>({});
+
+  const load = async () => {
+    try {
+      const res = await fetch('/api/files');
+      setFiles((await res.json()).files ?? []);
+    } catch { setError('backend unreachable'); }
+  };
+  useEffect(() => { load(); }, []);
+
+  const upload = async (input: HTMLInputElement, priv: boolean) => {
+    const file = input.files?.[0];
+    if (!file) return;
+    setPending(true);
+    setError('');
+    try {
+      const fd = new FormData();
+      fd.append('file', file);
+      const res = await fetch(priv ? '/api/files/private' : '/api/files', { method: 'POST', body: fd });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+      if (file.type.startsWith('image/') && !priv) {
+        setPreviews((p) => ({ ...p, [data.file.id]: URL.createObjectURL(file) }));
+      }
+      await load();
+    } catch (err) {
+      setError((err as Error).message);
+    } finally {
+      setPending(false);
+      input.value = '';
+    }
+  };
+
+  const signUrl = async (id: string) => {
+    try {
+      const res = await fetch(`/api/files/${id}/signed`);
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+      setSigned((s) => ({ ...s, [id]: data.url }));
+    } catch (err) { setError((err as Error).message); }
+  };
+
+  const remove = async (id: string) => {
+    await fetch(`/api/files/${id}`, { method: 'DELETE' }).catch(() => {});
+    setSigned((s) => { const c = { ...s }; delete c[id]; return c; });
+    load();
+  };
+
+  return (
+    <main style={{ fontFamily: 'system-ui', maxWidth: 720, margin: '2rem auto', padding: '0 1rem' }}>
+      <h1>File storage</h1>
+
+      <div style={{ display: 'flex', gap: '1rem', marginBottom: '1rem', flexWrap: 'wrap' }}>
+        <label style={{ border: '1px solid #ccc', borderRadius: 8, padding: '0.5rem 1rem', cursor: 'pointer' }}>
+          Upload public
+          <input type="file" hidden disabled={pending} onChange={(e) => upload(e.currentTarget, false)} />
+        </label>
+        <label style={{ border: '1px solid #ccc', borderRadius: 8, padding: '0.5rem 1rem', cursor: 'pointer' }}>
+          Upload private
+          <input type="file" hidden disabled={pending} onChange={(e) => upload(e.currentTarget, true)} />
+        </label>
+        {pending && <span style={{ color: '#666' }}>uploading...</span>}
+      </div>
+      {error && <p style={{ color: '#c00' }}>{error}</p>}
+
+      {files.length === 0 && <p style={{ color: '#666' }}>No files yet.</p>}
+      {files.map((f) => (
+        <div key={f.id} style={{ display: 'flex', gap: '0.75rem', alignItems: 'center', border: '1px solid #e4e4e4', borderRadius: 8, padding: '0.5rem 0.75rem', marginBottom: '0.5rem' }}>
+          {previews[f.id] && <img src={previews[f.id]} alt={f.originalName} style={{ width: 48, height: 48, objectFit: 'cover', borderRadius: 4 }} />}
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <div style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+              <strong>{f.originalName}</strong>{' '}
+              <span style={{ color: '#666', fontSize: '0.8rem' }}>{fmtSize(f.size)} — {f.disk}</span>
+            </div>
+            {f.disk === 'uploads' && f.url && (
+              <a href={f.url} target="_blank" rel="noreferrer" style={{ fontSize: '0.8rem' }}>{f.url}</a>
+            )}
+            {signed[f.id] && (
+              <div style={{ fontSize: '0.75rem', color: '#060', wordBreak: 'break-all' }}>signed: {signed[f.id]}</div>
+            )}
+          </div>
+          <button onClick={() => signUrl(f.id)}>Signed URL</button>
+          <button onClick={() => remove(f.id)}>Delete</button>
+        </div>
+      ))}
+    </main>
+  );
+}
+
+const el = document.getElementById('root');
+if (el) createRoot(el).render(<App />);

package/examples/livestream/README.md

@@ -0,0 +1,34 @@
+# Livestream example
+
+One broadcaster, many viewers. Simplified transport: instead of mediasoup, the
+broadcaster draws camera frames to a canvas and ships JPEG data URLs over the
+WS room; the server fans each frame out to viewers.
+
+## What's here
+
+- `apps/backend/src/ws/stream.room.ts` — `broadcaster` / `viewer` roles, frame fan-out, stream registry
+- `apps/backend/src/routes/list.ts` — `GET /api/streams` lists active streams
+- `apps/frontend/src/main.tsx` — two tabs: **Broadcast** (camera + go live) and **Watch** (list + view)
+
+## Flow
+
+1. Broadcaster opens the Broadcast tab, names the stream, presses *Go live*.
+   Camera frames are captured at ~5 fps, JPEG-encoded, and sent as `frame`
+   messages.
+2. A viewer opens the Watch tab and sees the stream in `GET /api/streams`.
+3. Clicking *Watch* joins the WS room as a viewer; incoming `frame` messages
+   are drawn into an `<img>`.
+4. When the broadcaster stops (or disconnects), a `stopped` message closes
+   every viewer panel.
+
+For production you'd swap the canvas-over-WS fan-out for a mediasoup SFU
+(`config.webrtc` is already in the Nexus config schema) and keep this room for
+chat/roster side-channel traffic.
+
+## Run
+
+```bash
+npx nexus dev
+```
+
+Open two browser windows: Broadcast in one, Watch in the other.

package/examples/livestream/apps/backend/src/routes/list.ts

@@ -0,0 +1,21 @@
+import { defineRoutes } from '@bhooai/nexus-core';
+import { listStreams } from '../ws/stream.room.js';
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/streams',
+    handler: async (ctx) => {
+      ctx.json({ streams: listStreams() });
+    },
+  },
+  {
+    method: 'GET',
+    path: '/api/streams/:streamId',
+    handler: async (ctx) => {
+      const stream = listStreams().find((s) => s.id === ctx.params.streamId);
+      if (!stream) return ctx.json({ error: 'stream not found' }, 404);
+      ctx.json({ stream });
+    },
+  },
+]);

package/examples/livestream/apps/backend/src/ws/stream.room.ts

@@ -0,0 +1,53 @@
+/**
+ * Livestream room. One broadcaster captures frames; the server fans them out
+ * to every viewer of the stream. Simplified: frames are JPEG data URLs sent
+ * over WS — no mediasoup wiring in this example.
+ *
+ * Client protocol:
+ *   -> start   { streamId, title }   (become the broadcaster of streamId)
+ *   -> watch   { streamId }          (join as a viewer)
+ *   <- started { streamId, title }   (broadcast to everyone; used by stream list)
+ *   -> frame   { streamId, data }    (broadcaster -> server)
+ *   <- frame   { data }              (server -> viewers)
+ *   <- stopped { streamId }          (when the broadcaster leaves)
+ */
+const streams = new Map<string, { title: string; broadcaster: string }>();
+
+export function listStreams() {
+  return [...streams.entries()].map(([id, s]) => ({ id, title: s.title }));
+}
+
+export default {
+  name: 'stream',
+
+  async onJoin(socket: any, payload: { streamId: string; role?: string }) {
+    socket.data.streamId = payload.streamId;
+    socket.data.role = payload.role === 'broadcaster' ? 'broadcaster' : 'viewer';
+    socket.join(`stream:${payload.streamId}`);
+  },
+
+  async onLeave(socket: any, payload: { streamId: string }) {
+    if (socket.data?.role === 'broadcaster') {
+      streams.delete(payload.streamId);
+      socket.to(`stream:${payload.streamId}`).emit('stopped', { streamId: payload.streamId });
+    }
+  },
+
+  onMessage: {
+    'start': async (socket: any, payload: { streamId: string; title: string }, ctx: any) => {
+      streams.set(payload.streamId, { title: payload.title ?? 'Untitled', broadcaster: socket.id });
+      socket.data.role = 'broadcaster';
+      ctx.server.emit('started', { streamId: payload.streamId, title: payload.title });
+    },
+    'frame': (socket: any, payload: { streamId: string; data: string }, _ctx: any) => {
+      if (socket.data?.role !== 'broadcaster') return;
+      // Fan the frame out to viewers only (not back to the broadcaster).
+      socket.to(`stream:${payload.streamId}`).emit('frame', { data: payload.data });
+    },
+    'stop': (socket: any, payload: { streamId: string }, _ctx: any) => {
+      if (socket.data?.role !== 'broadcaster') return;
+      streams.delete(payload.streamId);
+      socket.to(`stream:${payload.streamId}`).emit('stopped', { streamId: payload.streamId });
+    },
+  },
+};

package/examples/livestream/apps/frontend/src/main.tsx

@@ -0,0 +1,148 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+interface StreamInfo { id: string; title: string }
+
+function wsUrl(): string {
+  const host = (import.meta as any).env?.VITE_BACKEND_HOST ?? 'localhost';
+  const port = (import.meta as any).env?.VITE_BACKEND_PORT ?? '4000';
+  return `ws://${host}:${port}/ws`;
+}
+
+function Broadcast() {
+  const [streamId, setStreamId] = useState('my-stream');
+  const [title, setTitle] = useState('My live stream');
+  const [live, setLive] = useState(false);
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const timerRef = useRef<number | null>(null);
+
+  const start = async () => {
+    const media = await navigator.mediaDevices.getUserMedia({ video: true });
+    if (videoRef.current) videoRef.current.srcObject = media;
+
+    const ws = new WebSocket(wsUrl());
+    wsRef.current = ws;
+    ws.onopen = () => {
+      ws.send(JSON.stringify({ type: 'join', streamId, role: 'broadcaster' }));
+      ws.send(JSON.stringify({ type: 'start', streamId, title }));
+      setLive(true);
+
+      // Draw camera frames to a canvas and ship JPEG data URLs over WS (~5 fps).
+      const canvas = document.createElement('canvas');
+      canvas.width = 320; canvas.height = 240;
+      const g = canvas.getContext('2d')!;
+      timerRef.current = window.setInterval(() => {
+        const v = videoRef.current;
+        if (!v || ws.readyState !== WebSocket.OPEN) return;
+        g.drawImage(v, 0, 0, canvas.width, canvas.height);
+        ws.send(JSON.stringify({ type: 'frame', streamId, data: canvas.toDataURL('image/jpeg', 0.6) }));
+      }, 200);
+    };
+  };
+
+  const stop = () => {
+    if (timerRef.current) window.clearInterval(timerRef.current);
+    wsRef.current?.send(JSON.stringify({ type: 'stop', streamId }));
+    wsRef.current?.close();
+    wsRef.current = null;
+    (videoRef.current?.srcObject as MediaStream | null)?.getTracks().forEach((t) => t.stop());
+    setLive(false);
+  };
+
+  useEffect(() => () => stop(), []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: '0.5rem', marginBottom: '1rem', flexWrap: 'wrap' }}>
+        <input value={streamId} onChange={(e) => setStreamId(e.target.value)} placeholder="stream id" disabled={live} />
+        <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="title" disabled={live} />
+        {!live ? <button onClick={start}>Go live</button> : <button onClick={stop}>Stop</button>}
+      </div>
+      <video ref={videoRef} autoPlay muted playsInline style={{ width: 480, maxWidth: '100%', background: '#000', borderRadius: 8 }} />
+      {live && <p style={{ color: '#c00', fontWeight: 600 }}>LIVE — {streamId}</p>}
+    </div>
+  );
+}
+
+function Watch() {
+  const [streams, setStreams] = useState<StreamInfo[]>([]);
+  const [watching, setWatching] = useState<string | null>(null);
+  const imgRef = useRef<HTMLImageElement>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+
+  const refresh = () => {
+    fetch('/api/streams').then((r) => r.json()).then((d) => setStreams(d.streams ?? [])).catch(() => {});
+  };
+  useEffect(refresh, []);
+
+  const watch = (id: string) => {
+    leave();
+    const ws = new WebSocket(wsUrl());
+    wsRef.current = ws;
+    ws.onopen = () => ws.send(JSON.stringify({ type: 'join', streamId: id }));
+    ws.onmessage = (ev) => {
+      try {
+        const data = JSON.parse(ev.data);
+        if (data.type === 'frame' && imgRef.current) imgRef.current.src = data.payload.data;
+        if (data.type === 'stopped') leave();
+      } catch { /* ignore */ }
+    };
+    setWatching(id);
+  };
+
+  const leave = () => {
+    wsRef.current?.close();
+    wsRef.current = null;
+    setWatching(null);
+    if (imgRef.current) imgRef.current.removeAttribute('src');
+  };
+
+  useEffect(() => () => leave(), []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <div>
+      <button onClick={refresh} style={{ marginBottom: '0.75rem' }}>Refresh list</button>
+      {streams.length === 0 && <p style={{ color: '#666' }}>No live streams right now.</p>}
+      <ul>
+        {streams.map((s) => (
+          <li key={s.id} style={{ marginBottom: '0.25rem' }}>
+            <button onClick={() => watch(s.id)} disabled={watching === s.id}>Watch</button>{' '}
+            <strong>{s.title}</strong> <span style={{ color: '#666' }}>({s.id})</span>
+          </li>
+        ))}
+      </ul>
+      {watching && (
+        <div>
+          <p>Watching <strong>{watching}</strong> — <button onClick={leave}>Leave</button></p>
+          <img ref={imgRef} alt="live stream" style={{ width: 480, maxWidth: '100%', background: '#000', borderRadius: 8 }} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function App() {
+  const [tab, setTab] = useState<'broadcast' | 'watch'>('watch');
+  const tabBtn = (t: 'broadcast' | 'watch') => ({
+    padding: '0.5rem 1rem',
+    border: '1px solid #ccc',
+    borderBottom: tab === t ? 'none' : '1px solid #ccc',
+    background: tab === t ? '#fff' : '#f0f0f0',
+    cursor: 'pointer',
+  } as const);
+
+  return (
+    <main style={{ fontFamily: 'system-ui', maxWidth: 720, margin: '2rem auto', padding: '0 1rem' }}>
+      <h1>Livestream</h1>
+      <div style={{ display: 'flex', marginBottom: '1rem' }}>
+        <button style={tabBtn('broadcast')} onClick={() => setTab('broadcast')}>Broadcast</button>
+        <button style={tabBtn('watch')} onClick={() => setTab('watch')}>Watch</button>
+      </div>
+      {tab === 'broadcast' ? <Broadcast /> : <Watch />}
+    </main>
+  );
+}
+
+const el = document.getElementById('root');
+if (el) createRoot(el).render(<App />);

package/examples/multi-app/README.md

@@ -0,0 +1,51 @@
+# Multi-app example
+
+Nexus as a platform: two backends (`shop` + `api`) and two frontends (`web` +
+`shop`) in one project, with one admin covering all of them.
+
+## Why there's almost nothing in this overlay
+
+Multi-app projects are created by `nexus add` — each call scaffolds a new
+`apps/<name>` with its own config, ports, and discovery roots. So this overlay
+ships only a README plus two small route files to look at; the apps themselves
+appear when you run the commands below.
+
+## Set up after `nexus init --example multi-app`
+
+```bash
+npx nexus add backend shop
+npx nexus add backend api
+npx nexus add frontend shop --for backend-shop
+npx nexus add frontend web --for backend
+npx nexus dev
+```
+
+## What you end up with
+
+```
+apps/
+  backend/          # the default backend from init (keep or repurpose)
+  backend-shop/     # storefront API   -> routes/products.ts (in this overlay)
+  backend-api/      # shared API      -> routes/users.ts    (in this overlay)
+  frontend/         # default frontend from init
+  frontend-shop/    # storefront UI, proxies to backend-shop
+  frontend-web/     # marketing/web UI, proxies to backend
+```
+
+## Conventions
+
+- Each `apps/backend-*` has its own `src/routes`, `src/ws`, `src/models`, etc.,
+  auto-discovered independently by `createNexusApp()`.
+- Backends get distinct ports; `nexus dev` prints the port map.
+- Frontends created with `--for <backend>` have their `VITE_BACKEND_*` env
+  pre-wired to that backend.
+- The admin (single instance) aggregates health/metrics across all backends.
+
+## Files in this overlay
+
+- `apps/backend-shop/src/routes/products.ts` — sample storefront routes
+- `apps/backend-api/src/routes/users.ts` — sample identity routes
+
+Drop them in after `nexus add backend ...` scaffolds the apps, then `npx nexus
+dev` and hit `GET /api/products` on the shop backend and `GET /api/users` on
+the api backend.

package/examples/multi-app/apps/backend-api/src/routes/users.ts

@@ -0,0 +1,26 @@
+import { defineRoutes } from '@bhooai/nexus-core';
+
+// Mounted on the "api" backend (apps/backend-api) — shared identity/service API.
+const USERS = [
+  { id: 'u-1', name: 'Ada Lovelace', email: 'ada@example.com' },
+  { id: 'u-2', name: 'Grace Hopper', email: 'grace@example.com' },
+];
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/users',
+    handler: async (ctx) => {
+      ctx.json({ users: USERS });
+    },
+  },
+  {
+    method: 'GET',
+    path: '/api/users/:id',
+    handler: async (ctx) => {
+      const user = USERS.find((u) => u.id === ctx.params.id);
+      if (!user) return ctx.json({ error: 'user not found' }, 404);
+      ctx.json({ user });
+    },
+  },
+]);

package/examples/multi-app/apps/backend-shop/src/routes/products.ts

@@ -0,0 +1,27 @@
+import { defineRoutes } from '@bhooai/nexus-core';
+
+// Mounted on the "shop" backend (apps/backend-shop) — the storefront API.
+const PRODUCTS = [
+  { id: 'sku-1', name: 'Nexus mug', priceCents: 49900 },
+  { id: 'sku-2', name: 'Nexus tee', priceCents: 89900 },
+  { id: 'sku-3', name: 'Sticker pack', priceCents: 14900 },
+];
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/products',
+    handler: async (ctx) => {
+      ctx.json({ products: PRODUCTS });
+    },
+  },
+  {
+    method: 'GET',
+    path: '/api/products/:id',
+    handler: async (ctx) => {
+      const product = PRODUCTS.find((p) => p.id === ctx.params.id);
+      if (!product) return ctx.json({ error: 'product not found' }, 404);
+      ctx.json({ product });
+    },
+  },
+]);

package/examples/saas-starter/README.md

@@ -0,0 +1,37 @@
+# SaaS starter example
+
+Teams + projects + members: the skeleton of a multi-tenant SaaS. Auth is
+deliberately stubbed (header-based find-or-create) — swap in `nexus-auth`
+providers for real OAuth.
+
+## What's here
+
+| File | Purpose |
+|------|---------|
+| `models/User.ts`, `models/Team.ts`, `models/Membership.ts` | Multi-tenant data model; membership carries the role |
+| `routes/teams.ts` | Sign-in (demo), team CRUD, member list/invite/delete |
+| `routes/projects.ts` | Project CRUD scoped to a team (in-memory for brevity) |
+| `policies/TeamPolicy.ts` | `owner` / `member` / `viewer` abilities |
+| `middleware/auth.ts` | `requireAuth` — trusts `x-user-id` (demo only) |
+| `events/UserRegistered.ts`, `events/TeamCreated.ts` | Domain events |
+| `listeners/OnUserRegistered.ts`, `listeners/OnTeamCreated.ts` | Auto-wired listeners (convention: `On<Foo>` -> `<Foo>`) |
+| `apps/frontend/src/main.tsx` | Sign-in stub + team list/create UI |
+
+## Role abilities
+
+| Ability | viewer | member | owner |
+|---------|:------:|:------:|:-----:|
+| view    |   x    |   x    |   x   |
+| update  |        |   x    |   x   |
+| invite  |        |   x    |   x   |
+| delete  |        |        |   x   |
+
+## Run
+
+```bash
+npx nexus dev
+```
+
+Sign in with any email (a user is created on first use), create a team, then
+sign in with a second email in a private window and try inviting that user via
+`POST /api/teams/:teamId/members` with an `x-user-id` header.

package/examples/saas-starter/apps/backend/src/events/TeamCreated.ts

@@ -0,0 +1,11 @@
+import { DomainEvent } from '@bhooai/nexus-core';
+
+export default class TeamCreated extends DomainEvent {
+  constructor(
+    public readonly teamId: string,
+    public readonly ownerId: string,
+    public readonly name: string,
+  ) {
+    super();
+  }
+}

package/examples/saas-starter/apps/backend/src/events/UserRegistered.ts

@@ -0,0 +1,10 @@
+import { DomainEvent } from '@bhooai/nexus-core';
+
+export default class UserRegistered extends DomainEvent {
+  constructor(
+    public readonly userId: string,
+    public readonly email: string,
+  ) {
+    super();
+  }
+}