@hsafa/ui-sdk 0.3.3 → 0.4.1

package/docs/handbook/08-Server-Integration.md

@@ -0,0 +1,84 @@
+# 08 — Server Integration
+
+This document explains the server contract expected by the SDK and how the provided server module implements it.
+
+## Endpoints
+
+- `POST /api/run/:agentId`
+  - Consumes Vercel AI SDK v5 UI messages from the client.
+  - Streams NDJSON events back to the client.
+- `POST /api/uploads`
+  - Receives file uploads and returns JSON: `{ id, name, url, mimeType, size }`.
+
+## Request/response contract
+
+- Client uses `DefaultChatTransport` via `createHsafaTransport(baseUrl, agentId, chatId)` and posts:
+  ```json
+  {
+    "messages": [ /* UIMessage[] (AI SDK v5) */ ],
+    "chatId": "chat_...", // injected by the SDK
+    "...extra": {}
+  }
+  ```
+- Server streams NDJSON produced from `toUIMessageStream()` and wraps it using `createUIMessageStreamResponse()`.
+
+## Reference implementation
+
+File: `server/src/modules/agents/run-agent-handler.ts`
+
+Key steps:
+1) Parse body; extract `uiMessages` (AI SDK v5 messages).
+2) Load agent definition from Prisma (`agent`, `flowNodes`, `flowEdges`).
+3) Resolve nodes: model, system prompt(s), prompt(s), temperature, MCP, tool nodes.
+4) Build model factory; gather tool model factories from node API keys.
+5) `convertToModelMessages(uiMessages)` → model messages.
+6) `streamText({ model, tools, messages, ... })` using Vercel AI SDK.
+7) Convert to UI stream: `toUIMessageStream({ originalMessages: uiMessages })`.
+8) Send `createUIMessageStreamResponse({ stream, originalMessages: uiMessages })`.
+9) Cleanup MCP clients after stream consumption.
+
+```ts
+// Example usage in a Next.js route
+export const runtime = 'edge';
+export async function POST(req: NextRequest, ctx: { params: { id: string } }) {
+  return handleRunAgentRequest(req, ctx);
+}
+```
+
+### Tools on the server
+
+- Tool nodes are collected from the agent graph (`run-core/tools.ts`, `run-core/tools/*`).
+- MCP (Model Context Protocol) tools are created in `run-core/mcp.ts` from `custom_mcp` or legacy `mcp_*` nodes.
+- The final `tools` map merges MCP tools and regular tools, namespaced to avoid collisions.
+
+### Model providers
+
+- The server supports multiple providers via `run-core/models.ts`.
+- The agent’s model node selects provider, model name, and API key.
+
+### System prompt
+
+- Built from nodes in `run-core/prompts.ts` (also merges available tool info and MCP configuration).
+
+### Error handling
+
+- All stream errors are emitted as `{ type: 'error', errorText }` events to the client.
+- Handler returns `500` with JSON for pre-stream errors.
+
+## Security and performance
+
+- Use Edge runtime for lower latency streaming (`export const runtime = 'edge'`).
+- Validate API keys and user access when loading agents.
+- Consider rate-limiting and auth for `/api/run/:agentId`.
+
+## Customizing the server
+
+- Add new tools in `run-core/tools/` and wire them in `run-core/tools.ts`.
+- Extend prompts and templates in `run-core/prompts.ts`.
+- Add model providers or tweak options in `run-core/models.ts`.
+
+## Relationship to the client
+
+- Client `HsafaChat`/`useHsafaAgent` expects standard AI SDK v5 semantics.
+- Frontend-only tools and UI components are resolved on the client side (`onToolCall`).
+- Server tools must be declared and available in the `tools` map.

package/docs/handbook/09-Agent-Studio-Client.md

@@ -0,0 +1,40 @@
+# 09 — Agent Studio (Client)
+
+This SDK is designed to consume agents authored in the Agent Studio UI (the flow builder). This document explains how the Studio relates to the runtime and the SDK.
+
+## Location
+
+- Studio root: `client/src/features/agent/`
+  - Page: `AgentPage.tsx`
+  - Canvas & flow: `components/AgentFlow.tsx`, `components/AgentFlowCanvas.tsx`
+  - Nodes: `components/nodes/*`
+  - Hooks: `hooks/useAgentFlow.ts`, `hooks/useStreamingPersistence.ts`
+  - Lib: `lib/*`
+
+## What the Studio produces
+
+- A graph of nodes/edges persisted to the backend (Prisma `agent`, `flowNodes`, `flowEdges`).
+- Node types include model selection, system/prompt nodes, temperature, tool nodes, and MCP nodes.
+- Tool nodes may carry provider-specific API keys used by the server to build model factories.
+
+## Server consumption
+
+- File: `server/src/modules/agents/run-agent-handler.ts`
+  - Loads the saved agent by id.
+  - Filters/expands nodes and edges.
+  - Renders node data (with templating) into a runtime configuration.
+  - Builds model/tools/MCP stacks before streaming.
+
+## SDK relationship
+
+- The SDK is agnostic of how the agent was authored; it only expects the server to implement the `/api/run/:agentId` contract.
+- Dynamic pages and UI components can be leveraged by the agent if the Studio emits the proper tool calls during execution.
+
+## Extending the Studio
+
+- Add/modify nodes under `client/src/features/agent/components/nodes/*`.
+- Persist new node data fields; ensure `run-core` interprets them accordingly.
+- For new tools, implement:
+  - Studio node for configuration (client),
+  - Tool implementation in `server/src/modules/agents/run-core/tools/` (server),
+  - Optional frontend tool/UI in the SDK if needed.

package/docs/handbook/10-Examples-and-Recipes.md

@@ -0,0 +1,154 @@
+# 10 — Examples & Recipes
+
+Practical snippets for common tasks using the SDK.
+
+## Minimal chat page
+
+```tsx
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+
+export default function Page() {
+  return (
+    <HsafaProvider baseUrl="">
+      <HsafaChat agentId="my-agent" theme="dark" />
+    </HsafaProvider>
+  );
+}
+```
+
+## Custom tool and UI component
+
+```tsx
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+
+const tools = {
+  add: async ({ a, b }: any) => ({ sum: a + b })
+};
+
+function ProductCard({ name, price }: { name: string; price: number }) {
+  return <div>{name}: ${price}</div>;
+}
+
+export default function Page() {
+  return (
+    <HsafaProvider baseUrl="">
+      <HsafaChat agentId="my-agent" HsafaTools={tools} HsafaUI={{ ProductCard }} />
+    </HsafaProvider>
+  );
+}
+```
+
+## Headless custom UI
+
+```tsx
+import { useHsafaAgent } from '@hsafa/ui-sdk';
+
+export function MyChat() {
+  const agent = useHsafaAgent({ agentId: 'my-agent', baseUrl: '' });
+
+  return (
+    <div>
+      <div style={{ height: 320, overflow: 'auto' }}>
+        {agent.messages.map((m) => (
+          <pre key={m.id}>{JSON.stringify(m, null, 2)}</pre>
+        ))}
+      </div>
+      <input
+        value={agent.input}
+        onChange={(e) => agent.setInput(e.target.value)}
+        onKeyDown={(e) => e.key === 'Enter' && agent.sendMessage()}
+      />
+      <button disabled={agent.isLoading} onClick={() => agent.sendMessage()}>
+        Send
+      </button>
+      <button onClick={() => agent.stop()}>Stop</button>
+    </div>
+  );
+}
+```
+
+## Chat history with `useChatStorage`
+
+```tsx
+import { useChatStorage, useHsafaAgent } from '@hsafa/ui-sdk';
+
+export function ChatWithHistory() {
+  const agent = useHsafaAgent({ agentId: 'my-agent', baseUrl: '' });
+  const storage = useChatStorage({
+    agentId: 'my-agent',
+    chatId: agent.chatId,
+    messages: agent.messages,
+    isLoading: agent.isLoading,
+  });
+
+  return (
+    <div style={{ display: 'flex', gap: 16 }}>
+      <aside>
+        {storage.chatList.map((c) => (
+          <div key={c.id}>
+            <button onClick={() => storage.switchToChat(c.id, agent.setMessages)}>{c.title}</button>
+          </div>
+        ))}
+      </aside>
+      <main style={{ flex: 1 }}>
+        {/* ... render your UI, inputs, etc. ... */}
+      </main>
+    </div>
+  );
+}
+```
+
+## Dynamic page tools enabled
+
+```tsx
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+import type { DynamicPageTypeConfig } from '@hsafa/ui-sdk';
+
+const types: DynamicPageTypeConfig[] = [
+  // your type configs here
+];
+
+export default function Page() {
+  return (
+    <HsafaProvider baseUrl="">
+      <HsafaChat agentId="dp-agent" dynamicPageTypes={types} />
+    </HsafaProvider>
+  );
+}
+```
+
+## File uploads
+
+```tsx
+import { useFileUploadHook } from '@hsafa/ui-sdk';
+
+function Uploader() {
+  const { attachments, uploading, fileInputRef, handleFileSelection, handleRemoveAttachment } = useFileUploadHook('');
+  return (
+    <div>
+      <input ref={fileInputRef} type="file" multiple onChange={(e) => handleFileSelection(e.target.files, () => {})} />
+      {uploading ? 'Uploading...' : null}
+      <ul>
+        {attachments.map((a) => (
+          <li key={a.id}>
+            {a.name} <button onClick={() => handleRemoveAttachment(a.id)}>x</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Server route (Next.js edge)
+
+```ts
+// app/api/run/[id]/route.ts
+import { NextRequest } from 'next/server';
+import { handleRunAgentRequest } from '@/server/src/modules/agents/run-agent-handler';
+
+export const runtime = 'edge';
+export async function POST(req: NextRequest, { params }: { params: { id: string } }) {
+  return handleRunAgentRequest(req as any, { params } as any);
+}
+```

package/docs/handbook/11-API-Reference-Map.md

@@ -0,0 +1,48 @@
+# 11 — API Reference Map
+
+Use this as a directory to the TypeDoc API and key source files.
+
+## TypeDoc (generated)
+
+- `sdk/docs/api/README.md` (entry)
+- Common pages:
+  - `sdk/docs/api/functions/HsafaChat.md`
+  - `sdk/docs/api/functions/HsafaProvider.md`
+  - `sdk/docs/api/functions/useHsafaAgent.md`
+  - `sdk/docs/api/functions/useChatStorage.md`
+  - `sdk/docs/api/functions/useFileUploadHook.md`
+
+## Source references
+
+- Provider: `sdk/src/providers/HsafaProvider.tsx`
+- Chat component: `sdk/src/components/HsafaChat.tsx`
+- Hooks:
+  - `sdk/src/hooks/useHsafaAgent.ts`
+  - `sdk/src/hooks/useChatStorage.ts`
+  - `sdk/src/hooks/useFileUploadHook.ts`
+  - `sdk/src/hooks/useMessageEditor.ts`
+  - `sdk/src/hooks/useAutoScroll.ts`
+- Tools & UI:
+  - `sdk/src/components/hsafa-chat/utils/transport.ts`
+  - `sdk/src/components/hsafa-chat/utils/builtInTools.ts`
+  - `sdk/src/components/hsafa-chat/utils/builtInUI.tsx`
+  - `sdk/src/components/hsafa-chat/utils/renderUserForm.ts`
+  - `sdk/src/components/hsafa-chat/hooks/useStreamingToolInput.ts`
+- Dynamic pages:
+  - `sdk/src/components/dynamic-page/DynamicPage.tsx`
+  - `sdk/src/components/dynamic-page/useDynamicPage.ts`
+  - `sdk/src/components/dynamic-page/tools.ts`
+  - `sdk/src/components/dynamic-page/operations.ts`
+  - `sdk/src/components/dynamic-page/storage.ts`
+  - `sdk/src/components/dynamic-page/types.ts`
+- Types:
+  - `sdk/src/types/chat.ts`
+  - `sdk/src/types/messages.ts`
+
+## Related server code
+
+- Server entry: `server/src/modules/agents/run-agent-handler.ts`
+- Server core: `server/src/modules/agents/run-core/*`
+- Agent CRUD: `server/src/modules/agents/agent-service.ts`
+
+See also the high-level guide: `sdk/docs/README.md`.

package/docs/handbook/README.md

@@ -0,0 +1,24 @@
+# Hsafa UI SDK Handbook
+
+This handbook consolidates everything you need to use, extend, and integrate the Hsafa UI SDK across the client and server.
+
+- Audience: Frontend engineers, full‑stack engineers, and integrators
+- Scope: SDK architecture, APIs, hooks, tools, dynamic pages, persistence, transport, server contract, and examples
+- Related: `sdk/docs/README.md` (Advanced Guide), `sdk/docs/api/` (TypeDoc)
+
+## Contents
+
+- 00-Overview.md — high-level architecture and repository map
+- 01-Quickstart.md — install and minimal setup (UI and headless)
+- 02-Architecture.md — layers, flows, and data contracts
+- 03-Components-and-Hooks.md — exported components/types/hooks with usage
+- 04-Streaming-and-Transport.md — Vercel AI SDK v5, tool calls, UI stream
+- 05-Tools-and-UI.md — built-in tools and registering custom UI/actions
+- 06-Storage-and-History.md — local persistence and history management
+- 07-Dynamic-Pages.md — dynamic page system, tools, and storage
+- 08-Server-Integration.md — `/api/run/:agentId`, run-core, and MCP/tools
+- 09-Agent-Studio-Client.md — client Agent Studio overview and relation
+- 10-Examples-and-Recipes.md — common tasks and full snippets
+- 11-API-Reference-Map.md — pointers to TypeDoc and source files
+
+If something is missing, open an issue or PR with suggested additions.