feat: use api-client and rework flow

Author: Yukaii

examples/ai-conference-assistant/README.md

@@ -9,7 +9,7 @@ A web-based AI assistant that helps you create book-mode collaborative note syst
 - **Reference Note Fetching**: Point the AI to an existing HackMD note (e.g., last year's conference) and it will analyze the format
 - **Markdown Preview**: Preview the generated homepage and all session pages before creating
 - **Rate-Limit-Aware Creation**: Batch note creation with configurable delay and real-time progress tracking via SSE
-- **Frontend API Key Entry**: No server-side secrets needed — provide your HackMD and OpenAI API keys from the browser
+- **Server-side LLM credentials**: `AI_GATEWAY_API_KEY` is read only on the server (never sent from the browser); you still enter your HackMD token in the UI
 
 ## Architecture
 
@@ -19,7 +19,7 @@ A web-based AI assistant that helps you create book-mode collaborative note syst
 │                                                  │
 │  ┌──────────────┐  ┌──────────┐  ┌───────────┐  │
 │  │  Setup Panel  │  │  Chat UI │  │  Preview   │  │
-│  │  (API keys)   │  │  (useChat)│  │  (Markdown)│  │
+│  │  (HackMD)     │  │  (useChat)│  │  (Markdown)│  │
 │  └──────┬───────┘  └────┬─────┘  └───────────┘  │
 │         │               │                        │
 └─────────┼───────────────┼────────────────────────┘
@@ -44,7 +44,7 @@ A web-based AI assistant that helps you create book-mode collaborative note syst
 
 - Node.js 18+
 - A [HackMD API token](https://hackmd.io/settings/api)
-- An [OpenAI API key](https://platform.openai.com/api-keys)
+- A [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) API key (or another OpenAI-compatible key) set as **`AI_GATEWAY_API_KEY` in the server environment** — for example in `.env.local` when developing, or in your host’s env for production
 
 ### Setup
 
@@ -55,6 +55,11 @@ cd examples/ai-conference-assistant
 # Install dependencies
 npm install
 
+# Required: LLM key for the API route (not committed — use .env.local)
+echo 'AI_GATEWAY_API_KEY=your_key_here' >> .env.local
+# Optional: custom OpenAI-compatible base URL (e.g. Vercel AI Gateway)
+# echo 'AI_GATEWAY_BASE_URL=https://ai-gateway.vercel.sh/v1' >> .env.local
+
 # Start the development server
 npm run dev
 ```
@@ -63,7 +68,7 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
 
 ### Usage
 
-1. **Enter your credentials** — HackMD API key, OpenAI API key, and team path
+1. **Enter your HackMD credentials** — API key and team path (LLM access uses `AI_GATEWAY_API_KEY` on the server only)
 2. **Upload session data** — Click the 📁 button to upload your `sessions.json`
 3. **Chat with the AI** — Tell it about your conference, reference notes, customizations
 4. **Preview** — The AI generates pages; preview them in the right panel

examples/ai-conference-assistant/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /** Pre-bundle issues with the linked file:../../nodejs package under Turbopack; webpack resolves it reliably. */
+  serverExternalPackages: ["@hackmd/api", "axios"],
+};
+
+export default nextConfig;

examples/ai-conference-assistant/next.config.ts

@@ -3,12 +3,13 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
-    "build": "next build",
+    "dev": "next dev --webpack",
+    "build": "next build --webpack",
     "start": "next start",
     "lint": "eslint"
   },
   "dependencies": {
+    "@hackmd/api": "file:../../nodejs",
     "@ai-sdk/openai": "^3.0.48",
     "@ai-sdk/react": "^3.0.140",
     "ai": "^6.0.138",

examples/ai-conference-assistant/package-lock.json

@@ -61,7 +61,6 @@ export async function POST(req: Request) {
       apiKey: string
       apiEndpoint: string
       teamPath: string
-      openaiApiKey: string
     }
   }
 
@@ -72,16 +71,25 @@ export async function POST(req: Request) {
     })
   }
 
-  if (!config?.openaiApiKey) {
-    return new Response(JSON.stringify({ error: 'OpenAI API key is required' }), {
-      status: 400,
-      headers: { 'Content-Type': 'application/json' },
-    })
+  const aiGatewayApiKey = process.env.AI_GATEWAY_API_KEY
+  if (!aiGatewayApiKey) {
+    return new Response(
+      JSON.stringify({
+        error: 'Server misconfiguration: AI_GATEWAY_API_KEY is not set',
+      }),
+      {
+        status: 503,
+        headers: { 'Content-Type': 'application/json' },
+      },
+    )
   }
 
   const tools = createTools(config.apiKey, config.apiEndpoint)
 
-  const openai = createOpenAI({ apiKey: config.openaiApiKey })
+  const openai = createOpenAI({
+    apiKey: aiGatewayApiKey,
+    ...(process.env.AI_GATEWAY_BASE_URL && { baseURL: process.env.AI_GATEWAY_BASE_URL }),
+  })
 
   const result = streamText({
     model: openai('gpt-4o'),

examples/ai-conference-assistant/package.json

@@ -5,7 +5,17 @@
  * and progress streaming via Server-Sent Events.
  */
 
-import { HackMDClient } from '@/lib/hackmd-client'
+import { NotePermissionRole } from '@hackmd/api'
+import { createHackMDApi } from '@/lib/create-hackmd-api'
+
+function isRateLimitError(err: unknown): boolean {
+  if (typeof err === 'object' && err !== null) {
+    const e = err as { code?: number; response?: { status?: number } }
+    if (e.code === 429 || e.response?.status === 429) return true
+  }
+  const msg = err instanceof Error ? err.message : String(err)
+  return msg.includes('429') || msg.toLowerCase().includes('too many requests')
+}
 
 export const maxDuration = 300
 
@@ -40,10 +50,7 @@ export async function POST(req: Request) {
     })
   }
 
-  const client = new HackMDClient({
-    accessToken: config.apiKey,
-    apiEndpoint: config.apiEndpoint,
-  })
+  const client = createHackMDApi(config.apiKey, config.apiEndpoint)
 
   const webDomain = config.webDomain || 'https://hackmd.io'
   const delayMs = Math.max(0, Math.min(config.delayMs || 300, 5000))
@@ -81,8 +88,8 @@ export async function POST(req: Request) {
           const note = await client.createTeamNote(config.teamPath, {
             title: page.title,
             content: page.content,
-            readPermission: 'guest',
-            writePermission: 'signed_in',
+            readPermission: NotePermissionRole.GUEST,
+            writePermission: NotePermissionRole.SIGNED_IN,
           })
 
           createdNotes[page.sessionId] = note.shortId
@@ -119,7 +126,7 @@ export async function POST(req: Request) {
           })
 
           // If it's a rate limit error, wait longer
-          if (message.includes('429')) {
+          if (isRateLimitError(err)) {
             await new Promise(resolve => setTimeout(resolve, 10000))
           } else if (delayMs > 0) {
             await new Promise(resolve => setTimeout(resolve, delayMs))
@@ -150,8 +157,8 @@ export async function POST(req: Request) {
         const mainNote = await client.createTeamNote(config.teamPath, {
           title: homepage.title,
           content: homepageContent,
-          readPermission: 'guest',
-          writePermission: 'signed_in',
+          readPermission: NotePermissionRole.GUEST,
+          writePermission: NotePermissionRole.SIGNED_IN,
         })
 
         completed++

examples/ai-conference-assistant/src/app/api/chat/route.ts

@@ -0,0 +1,63 @@
+/**
+ * Verifies HackMD credentials server-side. The HackMD API does not allow
+ * browser origins (CORS), so /me must be called from the backend.
+ */
+
+import { createHackMDApi } from '@/lib/create-hackmd-api'
+
+function httpStatusFromError(err: unknown): number | undefined {
+  if (typeof err !== 'object' || err === null) return undefined
+  const e = err as { response?: { status?: number }; code?: number }
+  if (e.response?.status != null) return e.response.status
+  if (typeof e.code === 'number') return e.code
+  return undefined
+}
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const { apiKey, apiEndpoint, teamPath } = body as {
+    apiKey?: string
+    apiEndpoint?: string
+    teamPath?: string
+  }
+
+  if (!apiKey?.trim()) {
+    return Response.json({ error: 'HackMD API key is required' }, { status: 400 })
+  }
+
+  const client = createHackMDApi(apiKey, apiEndpoint)
+
+  let user: { teams?: Array<{ path: string }> }
+  try {
+    user = await client.getMe()
+  } catch (err) {
+    const status = httpStatusFromError(err)
+    if (status === undefined) {
+      return Response.json(
+        { error: 'Failed to reach HackMD API. Check the API endpoint URL.' },
+        { status: 502 },
+      )
+    }
+    return Response.json(
+      { error: `HackMD API returned ${status}` },
+      { status: status === 401 ? 401 : 502 },
+    )
+  }
+
+  const teams = user.teams || []
+  const trimmedTeam = teamPath?.trim()
+
+  if (trimmedTeam && !teams.some((t) => t.path === trimmedTeam)) {
+    const teamNames = teams.map((t) => t.path).join(', ')
+    return Response.json(
+      {
+        error: `Team "${trimmedTeam}" not found. Available teams: ${teamNames || 'none'}`,
+      },
+      { status: 400 },
+    )
+  }
+
+  return Response.json({
+    teamPath: trimmedTeam || teams[0]?.path || '',
+  })
+}