shipd 0.1.3 → 0.2.0

package/docs-template/README.md

@@ -253,3 +253,77 @@ This module works independently and doesn't require other modules. However, it c
 ✅ **Well Documented** - Comprehensive integration guide  
 ✅ **Smart Deduplication** - Won't overwrite existing components
 
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the Documentation Pages module into an existing Next.js application.
+
+```
+The Documentation Pages module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- @radix-ui/react-slot@^1.1.0 - UI component primitives
+- @radix-ui/react-dialog@^1.1.0 - Dialog component
+- class-variance-authority@^0.7.0 - Component variant utilities
+- clsx@^2.1.1 - Conditional class names
+- tailwind-merge@^2.5.4 - Tailwind class merging
+- lucide-react@^0.469.0 - Icon library
+- react-markdown@^10.1.0 - Markdown rendering
+- remark-gfm@^4.0.1 - GitHub Flavored Markdown support
+
+**Files Added:**
+- app/docs/page.tsx - Documentation home page
+- app/docs/layout.tsx - Documentation layout with sidebar
+- app/docs/[slug]/page.tsx - Category documentation pages
+- app/docs/[slug]/[subslug]/page.tsx - Subcategory documentation pages
+- app/docs/api/page.tsx - API documentation page
+- app/docs/documentation/page.tsx - General documentation page
+- components/docs/docs-sidebar.tsx - Documentation sidebar navigation
+- components/docs/docs-header.tsx - Documentation page header
+- components/docs/docs-toc.tsx - Table of contents component
+- components/docs/docs-category-page.tsx - Category page layout
+- components/docs/docs-code-card.tsx - Code example card component
+- components/docs/docs-nav.ts - Navigation data structure
+- components/ui/* - UI components (button, card, badge, sheet) if not exist
+- lib/utils.ts - Utility functions (cn helper) if not exist
+
+**Environment Variables Required:**
+- None (module is self-contained)
+
+**Integration Steps:**
+1. Verify app/docs/ directory exists with all page files
+2. Check that components/docs/ directory exists with all docs components
+3. Verify components/ui/ directory has required UI components (button, card, badge, sheet)
+4. Check that lib/utils.ts exists with cn() function
+5. Verify components/docs/docs-nav.ts has navigation structure
+6. Test docs pages: Visit /docs, /docs/api, /docs/[category], etc.
+7. Check sidebar navigation works and highlights current page
+
+**Key Integration Points:**
+- Navigation: components/docs/docs-nav.ts defines the documentation structure
+- Layout: app/docs/layout.tsx provides sidebar and page structure
+- Routing: Uses Next.js dynamic routes [slug] and [subslug] for nested pages
+- Markdown: Pages can use react-markdown for content rendering
+- Sidebar: components/docs/docs-sidebar.tsx reads from docs-nav.ts
+- TOC: components/docs/docs-toc.tsx generates table of contents from headings
+- Smart deduplication: UI components won't overwrite if they already exist
+
+**Dependencies:**
+- No dependencies on other Shipd modules
+- Can be installed standalone
+
+**Common Issues to Check:**
+- If docs pages show 404: Verify app/docs/ directory structure and page.tsx files exist
+- If UI components not found: Check components/ui/ directory, install missing dependencies
+- If navigation not showing: Verify docs-nav.ts structure and sidebar imports
+- If markdown not rendering: Ensure react-markdown and remark-gfm are installed
+
+**Next Steps After Integration:**
+- Customize navigation structure in components/docs/docs-nav.ts
+- Update documentation content in app/docs/ pages
+- Add your own documentation pages following the [slug]/[subslug] pattern
+- Customize sidebar styling in docs-sidebar.tsx
+- Update header content in docs-header.tsx
+- Add code examples using docs-code-card.tsx component
+```

package/features/ai-chat/README.md

@@ -0,0 +1,316 @@
+# AI Chat Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ✅ Yes (can work independently)
+
+---
+
+## Overview
+
+This module adds AI-powered chat functionality using OpenAI's GPT-4o model. It includes a full chat interface with streaming responses, markdown rendering, and web search capabilities.
+
+**Key Features:**
+- OpenAI GPT-4o integration
+- Streaming chat responses
+- Markdown rendering with syntax highlighting
+- Web search preview tool
+- Full chat UI with message history
+- Chatbot component for dashboard integration
+
+---
+
+## Files Added
+
+### Pages/Routes
+- `app/dashboard/chat/page.tsx` - Full chat interface page
+- `app/api/chat/route.ts` - Chat API endpoint with streaming
+
+### Components
+- `app/dashboard/_components/chatbot.tsx` - Chatbot widget component (optional dashboard integration)
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `@ai-sdk/openai@^1.3.22` - OpenAI SDK for AI SDK
+- `ai@^4.3.16` - Vercel AI SDK
+- `@ai-sdk/react@^1.0.0` - React hooks for AI SDK
+
+**Note:** This module uses `react-markdown` and `remark-gfm` which may already be installed by the docs module. If not, they will be added automatically.
+
+### Required Modules
+- None - AI Chat module is standalone
+
+### Optional Integration
+- **Auth Module** - For protected chat routes (works without it, but chat should be protected)
+- **Docs Module** - May share `react-markdown` dependency
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# AI Chat (OpenAI)
+OPENAI_API_KEY="sk-xxxxxxxxxxxxx"  # Your OpenAI API key
+```
+
+**Required Variables:**
+- `OPENAI_API_KEY` - Your OpenAI API key (get from [platform.openai.com](https://platform.openai.com))
+
+**Where to get them:**
+- **OpenAI**: [platform.openai.com](https://platform.openai.com) - Create account and generate API key
+- Free tier available with limited credits
+- Pay-as-you-go pricing for production use
+
+---
+
+## Manual Integration Steps
+
+If you're appending this module to an existing project, follow these steps:
+
+### Step 1: Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+The append command automatically adds missing dependencies to `package.json`, but you need to install them.
+
+### Step 2: Add Environment Variables
+
+1. Copy `.env.example` to `.env.local` (if not exists)
+2. Add `OPENAI_API_KEY` with your OpenAI API key
+3. Get your API key from [platform.openai.com](https://platform.openai.com)
+
+### Step 3: Verify Installation
+
+1. Check that `app/api/chat/route.ts` exists
+2. Check that `app/dashboard/chat/page.tsx` exists
+3. Start your dev server: `npm run dev`
+4. Visit `http://localhost:3000/dashboard/chat` to test the chat interface
+
+### Step 4: Protect Chat Route (Optional)
+
+If you have the auth module installed, the chat route should already be protected. If not, consider adding authentication to protect the chat API endpoint.
+
+---
+
+## Usage Examples
+
+### Using the Chat Page
+
+1. Navigate to `/dashboard/chat`
+2. Start typing messages
+3. Receive streaming AI responses
+4. Messages support markdown formatting
+
+### Integrating Chatbot Component
+
+The chatbot component can be added to any dashboard page:
+
+```tsx
+import Chatbot from "@/app/dashboard/_components/chatbot";
+
+export default function DashboardPage() {
+  return (
+    <div>
+      {/* Your dashboard content */}
+      <Chatbot />
+    </div>
+  );
+}
+```
+
+### Customizing the Chat Model
+
+Edit `app/api/chat/route.ts` to change the model:
+
+```typescript
+const result = streamText({
+  model: openai("gpt-3.5-turbo"), // Change model here
+  messages,
+  tools: {
+    web_search_preview: openai.tools.webSearchPreview(),
+  },
+});
+```
+
+### Adding Custom Tools
+
+You can add custom tools to the chat:
+
+```typescript
+const result = streamText({
+  model: openai("gpt-4o"),
+  messages,
+  tools: {
+    web_search_preview: openai.tools.webSearchPreview(),
+    // Add your custom tools here
+  },
+});
+```
+
+---
+
+## Customization
+
+### Styling
+- Chat UI uses Tailwind CSS classes
+- Customize colors in `tailwind.config.ts`
+- Modify chat bubble styles in `app/dashboard/chat/page.tsx`
+
+### Configuration
+- Model selection in `app/api/chat/route.ts`
+- Max steps configuration in `useChat` hook
+- Customize chatbot component in `app/dashboard/_components/chatbot.tsx`
+
+### Features
+- Web search is enabled by default
+- Streaming responses are automatic
+- Markdown rendering is built-in
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**app/dashboard/layout.tsx** (if you want chatbot in all dashboard pages):
+- Import and add `<Chatbot />` component
+- Position it as needed (bottom-right corner by default)
+
+**Middleware** (if auth module installed):
+- Chat routes should be protected
+- Add `/dashboard/chat` to protected routes if needed
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "OPENAI_API_KEY is not defined" error
+**Solution:**
+- Add `OPENAI_API_KEY` to `.env.local`
+- Get API key from [platform.openai.com](https://platform.openai.com)
+- Restart dev server after adding env var
+
+**Issue:** Chat not responding
+**Solution:**
+- Check OpenAI API key is valid
+- Verify API key has credits/quota
+- Check browser console for errors
+- Verify API route is accessible
+
+**Issue:** Streaming not working
+**Solution:**
+- Ensure `ai` package is installed
+- Check network tab for streaming responses
+- Verify API route returns `toDataStreamResponse()`
+
+**Issue:** Markdown not rendering
+**Solution:**
+- Ensure `react-markdown` and `remark-gfm` are installed
+- Check that markdown is wrapped in proper components
+- Verify Tailwind prose classes are configured
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Get OpenAI API key from [platform.openai.com](https://platform.openai.com)
+2. Add `OPENAI_API_KEY` to `.env.local`
+3. Test chat interface at `/dashboard/chat`
+4. Customize chat model and tools as needed
+5. Integrate chatbot component into dashboard if desired
+6. Set up rate limiting for production use
+
+---
+
+## Related Modules
+
+This module works well with:
+- **Auth Module** - For protecting chat routes
+- **Docs Module** - May share markdown dependencies
+
+**Note:** AI Chat module is optional and standalone. No other modules are required.
+
+---
+
+## Module Status
+
+✅ **Standalone Package** - Can be installed independently  
+✅ **Streaming Support** - Real-time streaming responses  
+✅ **Markdown Rendering** - Built-in markdown support  
+✅ **Web Search** - Includes web search preview tool  
+✅ **Well Documented** - Comprehensive integration guide
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the AI Chat module into an existing Next.js application.
+
+```
+The AI Chat module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- ai@^4.3.16 - Vercel AI SDK for streaming responses
+- @ai-sdk/openai@^1.3.22 - OpenAI provider for AI SDK
+- react-markdown@^10.1.0 - Markdown rendering for chat messages
+- remark-gfm@^4.0.1 - GitHub Flavored Markdown support
+
+**Files Added:**
+- app/api/chat/route.ts - API route for streaming chat responses (POST handler)
+- app/dashboard/chat/page.tsx - Full chat interface page with message history
+- app/dashboard/_components/chatbot.tsx - Reusable chatbot widget component
+
+**Environment Variables Required:**
+- OPENAI_API_KEY - OpenAI API key (get from platform.openai.com)
+
+**Integration Steps:**
+1. Verify app/api/chat/route.ts exists and exports POST handler
+2. Check that chat page exists: app/dashboard/chat/page.tsx
+3. Verify chatbot component exists: app/dashboard/_components/chatbot.tsx
+4. Ensure OPENAI_API_KEY is set in .env.local
+5. Test chat API: POST to /api/chat with messages array
+6. Test chat page: Visit /dashboard/chat
+7. If auth module installed: Verify chat routes are protected
+
+**Key Integration Points:**
+- API route: app/api/chat/route.ts uses streamText from ai SDK with OpenAI provider
+- Streaming: Responses use toDataStreamResponse() for real-time streaming
+- Chat UI: Uses useChat hook from ai/react for message management
+- Markdown: Chat messages are rendered with react-markdown and remark-gfm
+- Web search: Includes openai.tools.webSearchPreview() by default
+- Model: Uses gpt-4o by default (configurable in route.ts)
+
+**Dependencies:**
+- OPTIONAL: Auth module (for protecting chat routes)
+- No hard dependencies on other Shipd modules
+
+**Common Issues to Check:**
+- If "OPENAI_API_KEY is not defined": Add API key to .env.local
+- If streaming not working: Check API route returns toDataStreamResponse()
+- If markdown not rendering: Ensure react-markdown and remark-gfm are installed
+- If chat not responding: Verify OpenAI API key is valid and has credits
+
+**Next Steps After Integration:**
+- Get OpenAI API key from platform.openai.com
+- Add OPENAI_API_KEY to .env.local
+- Test chat interface at /dashboard/chat
+- Customize model in app/api/chat/route.ts (default: gpt-4o)
+- Add chatbot widget to other pages if desired
+- Configure rate limiting for production
+```

package/features/ai-chat/app/api/chat/route.ts

@@ -0,0 +1,16 @@
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai.responses("gpt-4o"),
+    messages,
+    tools: {
+      web_search_preview: openai.tools.webSearchPreview(),
+    },
+  });
+
+  return result.toDataStreamResponse();
+}

package/features/ai-chat/app/dashboard/_components/chatbot.tsx

@@ -0,0 +1,39 @@
+"use client";
+import { Input } from "@/components/ui/input";
+import { Bot, X } from "lucide-react";
+import { useState } from "react";
+
+export default function Chatbot() {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="absolute bottom-4 right-4 z-[99]">
+      <div
+        className="rounded-full bg-black/10 cursor-pointer border p-3"
+        onClick={() => setOpen(!open)}
+      >
+        <Bot className="w-4 h-4 transition-transform hover:scale-125 hover:rotate-12 duration-300 ease-in-out" />
+      </div>
+      {open && (
+        <div className="absolute bottom-12 right-4 w-80 z-[99] dark:bg-black bg-white">
+          <div className="flex flex-col items-start justify-between gap-3 rounded-lg border h-96 shadow-lg p-4">
+            <div className="w-full">
+              <div className="flex items-center justify-between">
+                <h3 className="text-lg font-semibold">Nextjs Starter Kit</h3>
+                <X
+                  className="w-4 h-4 hover:cursor-pointer"
+                  onClick={() => setOpen(false)}
+                />
+              </div>
+              <p className="text-sm text-muted-foreground mt-1 mb-4">
+                Ask me anything about Nextjs Starter Kit
+              </p>
+            </div>
+            <div className="flex  items-end justify-center gap-2 w-full">
+              <Input className="w-full" placeholder="Ask me anything" />
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/features/ai-chat/app/dashboard/chat/page.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { useChat } from "@ai-sdk/react";
+import Markdown from "react-markdown";
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    maxSteps: 10,
+  });
+
+  return (
+    <div className="flex flex-col w-full py-24 justify-center items-center">
+      <div className="w-full max-w-xl space-y-4 mb-20">
+        {messages.map((message, i) => (
+          <div
+            key={message.id}
+            className={cn(
+              "flex",
+              message.role === "user" ? "justify-end" : "justify-start",
+            )}
+          >
+            <div
+              className={cn(
+                "max-w-[65%] px-3 py-1.5 text-sm shadow-sm",
+                message.role === "user"
+                  ? "bg-[#0B93F6] text-white rounded-2xl rounded-br-sm"
+                  : "bg-[#E9E9EB] text-black rounded-2xl rounded-bl-sm",
+              )}
+            >
+              {message.parts.map((part) => {
+                switch (part.type) {
+                  case "text":
+                    return (
+                      <div
+                        key={`${message.id}-${i}`}
+                        className="prose-sm prose-p:my-0.5 prose-li:my-0.5 prose-ul:my-1 prose-ol:my-1"
+                      >
+                        <Markdown>{part.text}</Markdown>
+                      </div>
+                    );
+                  default:
+                    return null;
+                }
+              })}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <form
+        className="flex gap-2 justify-center w-full items-center fixed bottom-0"
+        onSubmit={handleSubmit}
+      >
+        <div className="flex flex-col gap-2 justify-center items-start mb-8 max-w-xl w-full border p-2 rounded-lg bg-white ">
+          <Input
+            className="w-full border-0 shadow-none !ring-transparent "
+            value={input}
+            placeholder="Say something..."
+            onChange={handleInputChange}
+          />
+          <div className="flex justify-end gap-3 items-center w-full">
+            <Button size="sm" className="text-xs">
+              Send
+            </Button>
+          </div>
+        </div>
+      </form>
+    </div>
+  );
+}

package/features/ai-chat/feature.config.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-chat",
+  "version": "1.0.0",
+  "description": "OpenAI chat integration with streaming responses and markdown rendering",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.22",
+    "ai": "^4.3.16",
+    "@ai-sdk/react": "^1.0.0"
+  },
+  "devDependencies": {},
+  "envVars": [
+    "OPENAI_API_KEY"
+  ],
+  "files": [
+    "app/api/chat/**/*",
+    "app/dashboard/chat/**/*",
+    "app/dashboard/_components/chatbot.tsx"
+  ],
+  "requires": [],
+  "conflicts": []
+}
+