@bhooai/nexus-examples 2.0.0

package/examples/ai-chat/README.md

@@ -0,0 +1,37 @@
+# AI chat example
+
+Streaming LLM chat. The backend proxies the OpenAI-compatible Nexus AI server
+with `nexus-ai-client` and re-emits token deltas as SSE; the frontend consumes
+the stream with `fetch` + `ReadableStream`.
+
+## What's here
+
+- `apps/backend/src/routes/chat.ts` — `POST /api/ai/chat` SSE endpoint backed by `AiClient.chatStream()`
+- `apps/frontend/src/main.tsx` — chat UI that appends streamed deltas to the last bubble
+
+## Flow
+
+1. Frontend posts `{ messages }` to `/api/ai/chat`.
+2. Backend calls `ai.chatStream({ model, messages })` against
+   `NEXUS_AI_URL` (default `http://localhost:8000/v1`).
+3. Each chunk's delta is written as `data: {"delta":"..."}` SSE events;
+   termination is `data: [DONE]`.
+4. The frontend's reader splits on `\n\n`, parses each event, and appends
+   deltas to the in-progress assistant message. *Stop* aborts the fetch.
+
+## Configuration
+
+| Env var          | Default                     | Purpose              |
+|------------------|-----------------------------|----------------------|
+| `NEXUS_AI_URL`   | `http://localhost:8000/v1`  | AI server base URL   |
+| `NEXUS_AI_MODEL` | `default`                   | Model name to use    |
+
+## Run
+
+```bash
+# Start the AI server first (or set NEXUS_AI_URL to a reachable one)
+npx nexus dev
+```
+
+If no AI server is reachable the endpoint returns an SSE error event and the
+UI shows it above the input box.

package/examples/ai-chat/apps/backend/src/routes/chat.ts

@@ -0,0 +1,40 @@
+import { defineRoutes } from '@bhooai/nexus-core';
+import { AiClient } from '@bhooai/nexus-ai-client';
+
+// Points at the local Nexus AI server (OpenAI-compatible FastAPI).
+const ai = new AiClient({ serverUrl: process.env.NEXUS_AI_URL ?? 'http://localhost:8000/v1' });
+
+interface ChatMessage { role: 'system' | 'user' | 'assistant'; content: string }
+
+export default defineRoutes([
+  {
+    // SSE proxy: pipes the AI server's streamed chat completion to the browser.
+    method: 'POST',
+    path: '/api/ai/chat',
+    handler: async (ctx) => {
+      const body = (ctx.body ?? {}) as { messages?: ChatMessage[] };
+      if (!Array.isArray(body.messages) || body.messages.length === 0) {
+        return ctx.json({ error: 'messages[] is required' }, 422);
+      }
+      ctx.setHeader('content-type', 'text/event-stream');
+      ctx.setHeader('cache-control', 'no-cache');
+      ctx.setHeader('connection', 'keep-alive');
+      ctx.res.write(': connected\n\n');
+      try {
+        const stream = ai.chatStream({
+          model: process.env.NEXUS_AI_MODEL ?? 'default',
+          messages: body.messages,
+        });
+        for await (const chunk of stream) {
+          const delta = chunk?.choices?.[0]?.delta?.content ?? '';
+          if (delta) ctx.res.write(`data: ${JSON.stringify({ delta })}\n\n`);
+        }
+        ctx.res.write('data: [DONE]\n\n');
+      } catch (err) {
+        ctx.res.write(`data: ${JSON.stringify({ error: (err as Error).message })}\n\n`);
+      } finally {
+        ctx.res.end();
+      }
+    },
+  },
+]);

package/examples/ai-chat/apps/frontend/src/main.tsx

@@ -0,0 +1,105 @@
+import React, { useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+interface Msg { role: 'user' | 'assistant'; content: string }
+
+function App() {
+  const [messages, setMessages] = useState<Msg[]>([]);
+  const [draft, setDraft] = useState('');
+  const [streaming, setStreaming] = useState(false);
+  const [error, setError] = useState('');
+  const abortRef = useRef<AbortController | null>(null);
+
+  const send = async () => {
+    const text = draft.trim();
+    if (!text || streaming) return;
+    setDraft('');
+    setError('');
+
+    const history = [...messages, { role: 'user', content: text } as Msg];
+    setMessages([...history, { role: 'assistant', content: '' }]);
+    setStreaming(true);
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    try {
+      const res = await fetch('/api/ai/chat', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ messages: history }),
+        signal: controller.signal,
+      });
+      if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+
+      // Consume the SSE stream manually with ReadableStream.
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const events = buffer.split('\n\n');
+        buffer = events.pop() ?? '';
+        for (const raw of events) {
+          const line = raw.replace(/^data: /, '').trim();
+          if (!line || line.startsWith(':')) continue;
+          if (line === '[DONE]') break;
+          const data = JSON.parse(line) as { delta?: string; error?: string };
+          if (data.error) setError(data.error);
+          if (data.delta) {
+            setMessages((m) => {
+              const copy = [...m];
+              const last = copy[copy.length - 1];
+              copy[copy.length - 1] = { ...last, content: last.content + data.delta };
+              return copy;
+            });
+          }
+        }
+      }
+    } catch (err) {
+      if ((err as Error).name !== 'AbortError') setError((err as Error).message);
+    } finally {
+      setStreaming(false);
+      abortRef.current = null;
+    }
+  };
+
+  const stop = () => abortRef.current?.abort();
+
+  return (
+    <main style={{ fontFamily: 'system-ui', maxWidth: 720, margin: '2rem auto', padding: '0 1rem' }}>
+      <h1>AI chat</h1>
+
+      <div style={{ border: '1px solid #ccc', borderRadius: 8, padding: '1rem', minHeight: 300, maxHeight: 440, overflow: 'auto', background: '#fafafa', marginBottom: '1rem' }}>
+        {messages.length === 0 && <p style={{ color: '#666' }}>Ask anything — responses stream token-by-token.</p>}
+        {messages.map((m, i) => (
+          <div key={i} style={{ marginBottom: '0.75rem' }}>
+            <strong style={{ color: m.role === 'user' ? '#06c' : '#060' }}>
+              {m.role === 'user' ? 'You' : 'AI'}
+            </strong>
+            <div style={{ whiteSpace: 'pre-wrap' }}>{m.content || (streaming && i === messages.length - 1 ? '...' : '')}</div>
+          </div>
+        ))}
+      </div>
+
+      {error && <p style={{ color: '#c00' }}>{error}</p>}
+
+      <div style={{ display: 'flex', gap: '0.5rem' }}>
+        <input
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          onKeyDown={(e) => e.key === 'Enter' && send()}
+          placeholder="Type a message..."
+          style={{ flex: 1, padding: '0.5rem' }}
+          disabled={streaming}
+        />
+        {streaming ? <button onClick={stop}>Stop</button> : <button onClick={send}>Send</button>}
+      </div>
+    </main>
+  );
+}
+
+const el = document.getElementById('root');
+if (el) createRoot(el).render(<App />);

package/examples/blog-crud/README.md

@@ -0,0 +1,45 @@
+# Blog CRUD example
+
+Posts + authors + comments with a REST API and an equivalent GraphQL subgraph.
+Best starting point for the `nexus-data` ODM.
+
+## What's here
+
+- `models/Post.ts`, `models/Author.ts`, `models/Comment.ts` — ODM documents
+- `routes/posts.ts` — full REST CRUD (`GET/POST /api/posts`, `GET/PUT/DELETE /api/posts/:id`, `POST /api/posts/:id/comments`)
+- `graphql/post.graph.ts` — federation subgraph: `typeDefs` + resolvers for posts, nested author + comments, and a `publishPost` mutation
+- `apps/frontend/src/main.tsx` — post list + create form (REST)
+
+## Conventions shown
+
+- `model()` + `Schema` from `@bhooai/nexus-data`, with `index: true` fields and
+  `default: () => new Date()` timestamps.
+- Slug generation and find-or-create author on post creation.
+- Deleting a post cascades to its comments.
+
+## GraphQL
+
+The subgraph is auto-discovered from `graphql/*.graph.ts` and serves when the
+GraphQL gateway is enabled in config. Try:
+
+```graphql
+query {
+  posts(publishedOnly: true) {
+    id
+    title
+    author { name }
+    comments { name text }
+  }
+}
+
+mutation { publishPost(id: "<id>") { id published } }
+```
+
+## Run
+
+```bash
+npx nexus dev
+```
+
+Create a post, toggle publish, delete — all through the UI or directly against
+`/api/posts`.

package/examples/blog-crud/apps/backend/src/graphql/post.graph.ts

@@ -0,0 +1,99 @@
+/**
+ * GraphQL subgraph for the blog. Auto-discovered from graphql/*.graph.ts and
+ * composed into the gateway when `config.graphql` is enabled.
+ */
+import { defineSubgraph } from '@bhooai/nexus-graphql';
+import { Post } from '../models/Post.js';
+import { Author } from '../models/Author.js';
+import { Comment } from '../models/Comment.js';
+
+export const typeDefs = /* GraphQL */ `
+  type Author @key(fields: "id") {
+    id: ID!
+    name: String!
+    email: String!
+  }
+
+  type Comment {
+    id: ID!
+    name: String!
+    text: String!
+    createdAt: String!
+  }
+
+  type Post @key(fields: "id") {
+    id: ID!
+    title: String!
+    slug: String!
+    body: String!
+    published: Boolean!
+    author: Author
+    comments: [Comment!]!
+    createdAt: String!
+  }
+
+  type Query {
+    posts(publishedOnly: Boolean): [Post!]!
+    post(id: ID!): Post
+  }
+
+  type Mutation {
+    publishPost(id: ID!): Post
+  }
+`;
+
+const toPost = (p: Record<string, any>) => ({
+  id: String(p._id),
+  title: p.title,
+  slug: p.slug,
+  body: p.body,
+  published: !!p.published,
+  authorId: p.authorId,
+  createdAt: p.createdAt instanceof Date ? p.createdAt.toISOString() : String(p.createdAt),
+});
+
+export default defineSubgraph({
+  name: 'blog',
+  typeDefs,
+  resolvers: {
+    Query: {
+      posts: async (_parent, args) => {
+        const filter = args.publishedOnly ? { published: true } : {};
+        return (await Post.find(filter, { sort: { createdAt: -1 } })).map(toPost);
+      },
+      post: async (_parent, args) => {
+        const post = await Post.findById(args.id);
+        return post ? toPost(post) : null;
+      },
+    },
+    Mutation: {
+      publishPost: async (_parent, args) => {
+        const post = await Post.findOneAndUpdate(
+          { _id: args.id },
+          { $set: { published: true, updatedAt: new Date() } },
+        );
+        return post ? toPost(post) : null;
+      },
+    },
+    Post: {
+      author: async (parent) => {
+        const author = await Author.findById(parent.authorId);
+        if (!author) return null;
+        const a = author as unknown as { _id: unknown; name: string; email: string };
+        return { id: String(a._id), name: a.name, email: a.email };
+      },
+      comments: async (parent) => {
+        const comments = await Comment.find({ postId: parent.id }, { sort: { createdAt: 1 } });
+        return comments.map((c) => {
+          const d = c as unknown as { _id: unknown; name: string; text: string; createdAt: Date | string };
+          return {
+            id: String(d._id),
+            name: d.name,
+            text: d.text,
+            createdAt: d.createdAt instanceof Date ? d.createdAt.toISOString() : String(d.createdAt),
+          };
+        });
+      },
+    },
+  },
+});

package/examples/blog-crud/apps/backend/src/models/Author.ts

@@ -0,0 +1,10 @@
+import { model, Schema } from '@bhooai/nexus-data';
+
+const authorSchema = new Schema({
+  name:      { type: String, required: true },
+  email:     { type: String, required: true, index: true },
+  bio:       { type: String },
+  createdAt: { type: Date, default: () => new Date() },
+});
+
+export const Author = model('authors', authorSchema);

package/examples/blog-crud/apps/backend/src/models/Comment.ts

@@ -0,0 +1,10 @@
+import { model, Schema } from '@bhooai/nexus-data';
+
+const commentSchema = new Schema({
+  postId:    { type: String, required: true, index: true },
+  name:      { type: String, required: true },
+  text:      { type: String, required: true },
+  createdAt: { type: Date, default: () => new Date() },
+});
+
+export const Comment = model('comments', commentSchema);

package/examples/blog-crud/apps/backend/src/models/Post.ts

@@ -0,0 +1,13 @@
+import { model, Schema } from '@bhooai/nexus-data';
+
+const postSchema = new Schema({
+  title:      { type: String, required: true },
+  slug:       { type: String, required: true, index: true },
+  body:       { type: String, required: true },
+  authorId:   { type: String, required: true, index: true },
+  published:  { type: Boolean, default: false },
+  createdAt:  { type: Date, default: () => new Date(), index: true },
+  updatedAt:  { type: Date, default: () => new Date() },
+});
+
+export const Post = model('posts', postSchema);

package/examples/blog-crud/apps/backend/src/routes/posts.ts

@@ -0,0 +1,119 @@
+import { defineRoutes, NotFoundError } from '@bhooai/nexus-core';
+import { Post } from '../models/Post.js';
+import { Author } from '../models/Author.js';
+import { Comment } from '../models/Comment.js';
+
+const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+/** Raw shape of a hydrated Post document (property access proxies to _doc). */
+interface PostDoc {
+  _id: unknown;
+  title: string;
+  slug: string;
+  body: string;
+  authorId: string;
+  published: boolean;
+  createdAt: Date;
+}
+
+/** Serialize a Post document for JSON responses. */
+function toJson(p: unknown) {
+  const d = p as PostDoc;
+  return {
+    id: String(d._id),
+    title: d.title,
+    slug: d.slug,
+    body: d.body,
+    authorId: d.authorId,
+    published: d.published,
+    createdAt: d.createdAt,
+  };
+}
+
+function defined(obj: Record<string, unknown>) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/posts',
+    handler: async (ctx) => {
+      const posts = await Post.find({}, { sort: { createdAt: -1 } });
+      ctx.json({ posts: posts.map(toJson) });
+    },
+  },
+  {
+    method: 'POST',
+    path: '/api/posts',
+    handler: async (ctx) => {
+      const body = (ctx.body ?? {}) as { title?: string; body?: string; authorName?: string; authorEmail?: string; published?: boolean };
+      if (!body.title?.trim() || !body.body?.trim()) {
+        return ctx.json({ error: 'title and body are required' }, 422);
+      }
+      // Find-or-create the author (demo convenience; real apps use auth).
+      const email = body.authorEmail ?? 'anon@example.com';
+      let author = await Author.findOne({ email });
+      if (!author) {
+        [author] = await Author.create({ email, name: body.authorName ?? email.split('@')[0] });
+      }
+      const authorId = String((author as unknown as { _id: unknown })._id);
+      const [post] = await Post.create({
+        title: body.title.trim(),
+        slug: `${slugify(body.title)}-${Date.now().toString(36)}`,
+        body: body.body,
+        authorId,
+        published: !!body.published,
+        updatedAt: new Date(),
+      });
+      ctx.json({ post: toJson(post) }, 201);
+    },
+  },
+  {
+    method: 'GET',
+    path: '/api/posts/:id',
+    handler: async (ctx) => {
+      const post = await Post.findById(ctx.params.id);
+      if (!post) throw new NotFoundError('post not found');
+      const comments = await Comment.find({ postId: ctx.params.id }, { sort: { createdAt: 1 } });
+      ctx.json({ post: toJson(post), comments: comments.map((c) => (c as unknown as { toObject(): Record<string, unknown> }).toObject?.() ?? c) });
+    },
+  },
+  {
+    method: 'PUT',
+    path: '/api/posts/:id',
+    handler: async (ctx) => {
+      const body = (ctx.body ?? {}) as { title?: string; body?: string; published?: boolean };
+      const updated = await Post.findOneAndUpdate(
+        { _id: ctx.params.id },
+        { $set: { ...defined({ title: body.title, body: body.body, published: body.published }), updatedAt: new Date() } },
+      );
+      if (!updated) throw new NotFoundError('post not found');
+      ctx.json({ post: toJson(updated) });
+    },
+  },
+  {
+    method: 'DELETE',
+    path: '/api/posts/:id',
+    handler: async (ctx) => {
+      const deleted = await Post.findOneAndDelete({ _id: ctx.params.id });
+      if (!deleted) throw new NotFoundError('post not found');
+      await Comment.deleteMany({ postId: ctx.params.id });
+      ctx.json({ ok: true });
+    },
+  },
+  {
+    method: 'POST',
+    path: '/api/posts/:id/comments',
+    handler: async (ctx) => {
+      const body = (ctx.body ?? {}) as { name?: string; text?: string };
+      if (!body.name?.trim() || !body.text?.trim()) {
+        return ctx.json({ error: 'name and text are required' }, 422);
+      }
+      const post = await Post.findById(ctx.params.id);
+      if (!post) throw new NotFoundError('post not found');
+      const [comment] = await Comment.create({ postId: ctx.params.id, name: body.name, text: body.text });
+      ctx.json({ comment: (comment as unknown as { toObject(): Record<string, unknown> }).toObject() }, 201);
+    },
+  },
+]);

package/examples/blog-crud/apps/frontend/src/main.tsx

@@ -0,0 +1,102 @@
+import React, { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+interface Post {
+  id: string;
+  title: string;
+  slug: string;
+  body: string;
+  published: boolean;
+  createdAt: string;
+}
+
+function App() {
+  const [posts, setPosts] = useState<Post[]>([]);
+  const [title, setTitle] = useState('');
+  const [body, setBody] = useState('');
+  const [authorName, setAuthorName] = useState('anonymous');
+  const [published, setPublished] = useState(false);
+  const [error, setError] = useState('');
+
+  const load = async () => {
+    try {
+      const res = await fetch('/api/posts');
+      const data = await res.json();
+      setPosts(data.posts ?? []);
+    } catch (err) { setError((err as Error).message); }
+  };
+  useEffect(() => { load(); }, []);
+
+  const create = async () => {
+    setError('');
+    if (!title.trim() || !body.trim()) { setError('title and body are required'); return; }
+    try {
+      const res = await fetch('/api/posts', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ title, body, authorName, published }),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+      setTitle(''); setBody(''); setPublished(false);
+      load();
+    } catch (err) { setError((err as Error).message); }
+  };
+
+  const remove = async (id: string) => {
+    await fetch(`/api/posts/${id}`, { method: 'DELETE' }).catch(() => {});
+    load();
+  };
+
+  const togglePublish = async (p: Post) => {
+    await fetch(`/api/posts/${p.id}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ published: !p.published }),
+    }).catch(() => {});
+    load();
+  };
+
+  return (
+    <main style={{ fontFamily: 'system-ui', maxWidth: 720, margin: '2rem auto', padding: '0 1rem' }}>
+      <h1>Blog CRUD</h1>
+
+      <section style={{ border: '1px solid #ccc', borderRadius: 8, padding: '1rem', marginBottom: '1.5rem', background: '#fafafa' }}>
+        <h2 style={{ fontSize: '1rem', marginTop: 0 }}>New post</h2>
+        <div style={{ display: 'flex', gap: '0.5rem', marginBottom: '0.5rem' }}>
+          <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" style={{ flex: 2, padding: '0.5rem' }} />
+          <input value={authorName} onChange={(e) => setAuthorName(e.target.value)} placeholder="Author" style={{ flex: 1, padding: '0.5rem' }} />
+        </div>
+        <textarea value={body} onChange={(e) => setBody(e.target.value)} placeholder="Write something..." rows={4} style={{ width: '100%', padding: '0.5rem', boxSizing: 'border-box' }} />
+        <div style={{ display: 'flex', gap: '0.75rem', alignItems: 'center', marginTop: '0.5rem' }}>
+          <label style={{ fontSize: '0.9rem' }}>
+            <input type="checkbox" checked={published} onChange={(e) => setPublished(e.target.checked)} /> publish
+          </label>
+          <button onClick={create}>Create post</button>
+        </div>
+        {error && <p style={{ color: '#c00', marginBottom: 0 }}>{error}</p>}
+      </section>
+
+      {posts.length === 0 && <p style={{ color: '#666' }}>No posts yet.</p>}
+      {posts.map((p) => (
+        <article key={p.id} style={{ borderBottom: '1px solid #e4e4e4', paddingBottom: '1rem', marginBottom: '1rem' }}>
+          <h2 style={{ fontSize: '1.1rem', margin: '0 0 0.25rem' }}>
+            {p.title}{' '}
+            <span style={{ fontSize: '0.75rem', color: p.published ? '#060' : '#a60', fontWeight: 400 }}>
+              {p.published ? 'published' : 'draft'}
+            </span>
+          </h2>
+          <p style={{ margin: '0.25rem 0', whiteSpace: 'pre-wrap' }}>{p.body}</p>
+          <div style={{ fontSize: '0.8rem', color: '#666', display: 'flex', gap: '0.75rem' }}>
+            <span>{new Date(p.createdAt).toLocaleString()}</span>
+            <button onClick={() => togglePublish(p)}>{p.published ? 'Unpublish' : 'Publish'}</button>
+            <button onClick={() => remove(p.id)}>Delete</button>
+          </div>
+        </article>
+      ))}
+    </main>
+  );
+}
+
+const el = document.getElementById('root');
+if (el) createRoot(el).render(<App />);

package/examples/chat/README.md

@@ -0,0 +1,20 @@
+# Chat example
+
+Realtime chat rooms demoing `nexus-realtime` + WS auto-discovery.
+
+## What's here
+
+- `apps/backend/src/ws/chat.room.ts` — WS room with presence + typing indicators
+- `apps/backend/src/routes/chat.ts` — REST history endpoint
+- `apps/backend/src/models/Message.ts` — ODM model for messages
+- `apps/frontend/src/main.tsx` — browser chat UI (replaces the default hello-world)
+
+## Run
+
+```bash
+npx nexus dev
+# Frontend: http://localhost:3000
+# Backend : http://localhost:4000
+```
+
+Open two browser windows side-by-side, pick a room + username, and chat.

package/examples/chat/apps/backend/src/models/Message.ts

@@ -0,0 +1,11 @@
+import { model, Schema } from '@bhooai/nexus-data';
+
+const messageSchema = new Schema({
+  roomId:    { type: String, required: true, index: true },
+  userId:    { type: String, required: true },
+  username:  { type: String, required: true },
+  text:      { type: String, required: true },
+  createdAt: { type: Date, default: () => new Date(), index: true },
+});
+
+export const Message = model('messages', messageSchema);

package/examples/chat/apps/backend/src/routes/chat.ts

@@ -0,0 +1,17 @@
+import { defineRoutes } from '@bhooai/nexus-core';
+import { Message } from '../models/Message.js';
+
+export default defineRoutes([
+  {
+    method: 'GET',
+    path: '/api/chat/rooms/:roomId/messages',
+    handler: async (ctx) => {
+      const limit = Math.min(parseInt((ctx.query.limit as string) ?? '50', 10), 200);
+      const messages = await Message.find(
+        { roomId: ctx.params.roomId },
+        { sort: { createdAt: -1 }, limit },
+      );
+      ctx.json({ messages: messages.reverse() });
+    },
+  },
+]);