shipd 0.1.3 → 0.1.4

package/features/ai-chat/README.md

@@ -0,0 +1,258 @@
+# 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
+

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": []
+}
+

package/features/analytics/README.md

@@ -0,0 +1,308 @@
+# Analytics Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ✅ Yes (can work independently)
+
+---
+
+## Overview
+
+This module adds PostHog analytics integration for event tracking, user analytics, feature flags, session recording, and heatmaps.
+
+**Key Features:**
+- PostHog integration
+- Event tracking
+- User analytics
+- Feature flags
+- Session recording
+- Heatmaps
+- Automatic pageview tracking
+
+---
+
+## Files Added
+
+### Utilities/Libraries
+- `lib/posthog.ts` - PostHog provider and initialization
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `posthog-js@^1.248.1` - PostHog JavaScript SDK
+- `posthog-node@^4.18.0` - PostHog Node.js SDK
+
+### Required Modules
+- None - Analytics module is standalone
+
+### Optional Integration
+- **Auth Module** - For user identification and tracking
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# Analytics (PostHog)
+NEXT_PUBLIC_POSTHOG_KEY="phc_xxxxxxxxxxxxx"  # Your PostHog project API key
+NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"  # PostHog host (default: https://app.posthog.com)
+```
+
+**Required Variables:**
+- `NEXT_PUBLIC_POSTHOG_KEY` - Your PostHog project API key
+
+**Optional Variables:**
+- `NEXT_PUBLIC_POSTHOG_HOST` - PostHog host URL (defaults to `https://app.posthog.com`)
+
+**Where to get them:**
+- **PostHog**: [posthog.com](https://posthog.com) - Free tier available
+- Create account and project
+- Get API key from project settings
+- Use self-hosted PostHog instance if preferred
+
+---
+
+## 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 `NEXT_PUBLIC_POSTHOG_KEY` with your PostHog API key
+3. Optionally set `NEXT_PUBLIC_POSTHOG_HOST` if using self-hosted PostHog
+
+### Step 3: Integrate PostHog Provider
+
+Add the PostHog provider to your root layout (`app/layout.tsx`):
+
+```tsx
+import { PostHogProviderWrapper } from "@/lib/posthog";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <PostHogProviderWrapper>
+          {children}
+        </PostHogProviderWrapper>
+      </body>
+    </html>
+  );
+}
+```
+
+### Step 4: Verify Installation
+
+1. Check that `lib/posthog.ts` exists
+2. Add PostHog provider to your layout
+3. Start your dev server: `npm run dev`
+4. Visit your site and check PostHog dashboard for events
+
+---
+
+## Usage Examples
+
+### Tracking Custom Events
+
+```tsx
+'use client';
+
+import { usePostHog } from 'posthog-js/react';
+
+export function MyComponent() {
+  const posthog = usePostHog();
+
+  const handleButtonClick = () => {
+    posthog?.capture('button_clicked', {
+      button_name: 'signup',
+      location: 'homepage',
+    });
+  };
+
+  return <button onClick={handleButtonClick}>Sign Up</button>;
+}
+```
+
+### Identifying Users
+
+```tsx
+'use client';
+
+import { usePostHog } from 'posthog-js/react';
+import { useEffect } from 'react';
+
+export function UserTracker({ user }: { user: { id: string; email: string } }) {
+  const posthog = usePostHog();
+
+  useEffect(() => {
+    if (posthog && user) {
+      posthog.identify(user.id, {
+        email: user.email,
+        // Add more user properties
+      });
+    }
+  }, [posthog, user]);
+
+  return null;
+}
+```
+
+### Using Feature Flags
+
+```tsx
+'use client';
+
+import { usePostHog } from 'posthog-js/react';
+import { useEffect, useState } from 'react';
+
+export function FeatureFlagComponent() {
+  const posthog = usePostHog();
+  const [isEnabled, setIsEnabled] = useState(false);
+
+  useEffect(() => {
+    if (posthog) {
+      posthog.onFeatureFlags(() => {
+        const enabled = posthog.isFeatureEnabled('new-feature');
+        setIsEnabled(enabled || false);
+      });
+    }
+  }, [posthog]);
+
+  if (!isEnabled) {
+    return null;
+  }
+
+  return <div>New Feature Content</div>;
+}
+```
+
+### Server-Side Tracking
+
+```typescript
+import { PostHog } from 'posthog-node';
+
+const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
+  host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://app.posthog.com',
+});
+
+// Track server-side events
+export async function trackEvent(userId: string, eventName: string, properties?: Record<string, any>) {
+  posthog.capture({
+    distinctId: userId,
+    event: eventName,
+    properties,
+  });
+}
+```
+
+---
+
+## Customization
+
+### Configuration
+- PostHog initialization is in `lib/posthog.ts`
+- Customize person profiles setting
+- Add custom properties to all events
+
+### Features
+- Pageview tracking is automatic
+- Custom event tracking is available
+- Feature flags are supported
+- Session recording can be enabled in PostHog dashboard
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**app/layout.tsx**:
+- Wrap children with `PostHogProviderWrapper`
+- Add PostHog provider to root layout
+
+**Components**:
+- Use `usePostHog` hook for event tracking
+- Identify users when they sign in
+- Track custom events throughout your app
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "NEXT_PUBLIC_POSTHOG_KEY is not defined" error
+**Solution:**
+- Add `NEXT_PUBLIC_POSTHOG_KEY` to `.env.local`
+- Get API key from PostHog dashboard
+- Restart dev server after adding env var
+- Ensure variable name starts with `NEXT_PUBLIC_` for client-side access
+
+**Issue:** Events not showing in PostHog
+**Solution:**
+- Verify API key is correct
+- Check PostHog host is correct
+- Check browser console for errors
+- Verify PostHog provider is in root layout
+
+**Issue:** Feature flags not working
+**Solution:**
+- Ensure feature flags are enabled in PostHog dashboard
+- Check that user is identified before checking flags
+- Use `posthog.onFeatureFlags()` to wait for flags to load
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Get PostHog API key from [posthog.com](https://posthog.com)
+2. Add `NEXT_PUBLIC_POSTHOG_KEY` to `.env.local`
+3. Integrate PostHog provider in `app/layout.tsx`
+4. Test event tracking
+5. Set up feature flags in PostHog dashboard
+6. Identify users when they sign in
+7. Track custom events throughout your app
+
+---
+
+## Related Modules
+
+This module works well with:
+- **Auth Module** - For user identification and tracking
+
+**Note:** Analytics module is optional and standalone. No other modules are required.
+
+---
+
+## Module Status
+
+✅ **Standalone Package** - Can be installed independently  
+✅ **Event Tracking** - Automatic and custom events  
+✅ **Feature Flags** - Built-in feature flag support  
+✅ **User Analytics** - User identification and tracking  
+✅ **Well Documented** - Comprehensive integration guide
+