miragedev-sdk 0.3.0 → 0.5.0

package/README.md

@@ -5,16 +5,27 @@ AI-first SDK for building SAAS applications with Next.js. Build production-ready
 [![npm version](https://badge.fury.io/js/miragedev-sdk.svg)](https://www.npmjs.com/package/miragedev-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Features
-
-- 🔐 **Authentication** - NextAuth.js, Clerk, Supabase support with biometric auth
-- 💳 **Billing** - Stripe integration with mobile-optimized checkout
-- 📧 **Email** - Beautiful React Email templates with Resend/SendGrid
-- 📱 **PWA** - Progressive Web App with offline support
-- 🎯 **Mobile-First** - Optimized hooks for mobile experiences
-- 🤖 **AI-Friendly** - Comprehensive JSDoc for AI code generation
-- 📦 **Modular** - Import only what you need
-- 🔒 **Type-Safe** - Full TypeScript support with Zod validation
+## ✨ Features
+
+### Core Modules
+- 🔐 **Authentication**: Supabase (email, magic link, OAuth)
+- 📧 **Email**: Resend (transactional emails, templates)
+- 🤖 **AI**: OpenAI, Anthropic, Replicate (LLMs, image generation)
+- 💳 **Payments**: Stripe (subscriptions, one-time payments)
+- 📦 **Storage**: Cloudflare R2 (file upload, CDN integration)
+- 📊 **Analytics**: PostHog (event tracking, usage limits)
+- 🚦 **Limits**: Upstash Redis (rate limiting, circuit breaker)
+- ⚙️ **Jobs**: Trigger.dev (background jobs, scheduling)
+
+### Developer Experience
+- 🎯 **Type-safe**: Full TypeScript support
+- 🔧 **Zero-config**: Sensible defaults, minimal setup
+- 🧩 **Modular**: Use only what you need
+- 📚 **Well-documented**: Comprehensive guides and examples
+- 🚀 **Production-ready**: Battle-tested patterns
+- 📱 **PWA**: Progressive Web App with offline support
+- 🎯 **Mobile-First**: Optimized hooks for mobile experiences
+- 🤖 **AI-Friendly**: Comprehensive JSDoc for AI code generation
 
 ## Quick Start (2 minutes)
 
@@ -40,6 +51,17 @@ That's it! You now have a full-featured SAAS with:
 ```bash
 # In your existing Next.js project
 npm install miragedev-sdk
+
+# Peer dependencies (install only what you need)
+npm install @supabase/supabase-js        # For authentication
+npm install resend                        # For email
+npm install openai @anthropic-ai/sdk replicate  # For AI
+npm install stripe                        # For payments
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner sharp  # For storage
+npm install posthog-node                  # For analytics
+npm install @upstash/redis                # For limits
+npm install @trigger.dev/sdk              # For jobs
+
 npx miragedev init
 ```
 
@@ -380,15 +402,476 @@ const response = await createEmbeddings({
 console.log(response.embeddings[0]) // [0.123, -0.456, ...]
 ```
 
+**Image Generation:**
+
+```typescript
+import { generateImage } from 'miragedev-sdk/ai'
+
+const result = await generateImage({
+  prompt: 'A serene mountain landscape at sunset',
+  model: 'dall-e-3',
+  size: '1024x1024',
+  quality: 'standard'
+})
+
+console.log(result.images[0].url) // https://oaidalleapiprodscus.blob...
+```
+
+**Client-Side Hook:**
+
+```typescript
+'use client'
+import { useImageGeneration } from 'miragedev-sdk/ai'
+
+export function ImageGenerator() {
+  const { generate, isLoading, result } = useImageGeneration()
+  
+  return (
+    <div>
+      <button onClick={() => generate('A sunset')}>
+        {isLoading ? 'Generating...' : 'Generate'}
+      </button>
+      {result && <img src={result.images[0].url} alt="Generated" />}
+    </div>
+  )
+}
+```
+
+**With Rate Limiting:**
+
+```typescript
+import { generateImage } from 'miragedev-sdk/ai'
+import { checkRateLimit } from 'miragedev-sdk/limits'
+
+const limit = await checkRateLimit({
+  key: `images:${userId}`,
+  limit: 10,
+  window: 3600
+})
+
+if (!limit.allowed) {
+  throw new Error('Rate limit exceeded')
+}
+
+const result = await generateImage({ prompt: 'A sunset' })
+```
+
+**Save to Permanent Storage:**
+
+```typescript
+import { generateImage } from 'miragedev-sdk/ai'
+import { uploadFile } from 'miragedev-sdk/storage'
+
+const result = await generateImage({ prompt: 'A sunset' })
+
+// Download and upload to R2
+const response = await fetch(result.images[0].url)
+const buffer = await response.arrayBuffer()
+
+await uploadFile({
+  file: Buffer.from(buffer),
+  key: `images/${userId}/${Date.now()}.png`,
+  contentType: 'image/png'
+})
+```
+
+**Cost Warning:** DALL-E 3 costs $0.04-$0.12 per image. Always implement rate limiting.
+
 **Environment Variables:**
 
 ```env
 OPENAI_API_KEY=sk-...
 ```
 
+**Supported Models:**
+- ✅ DALL-E 2 (256x256, 512x512, 1024x1024)
+- ✅ DALL-E 3 (1024x1024, 1792x1024, 1024x1792, HD quality)
+
 **Supported Providers:**
-- ✅ OpenAI (GPT-4, GPT-3.5, embeddings)
+- ✅ OpenAI (GPT-4, GPT-3.5, embeddings, DALL-E)
 - 🔜 Anthropic (Claude) - Coming soon
+
+### 📦 Storage Module
+
+Upload and manage files with CDN integration.
+
+**Features:**
+- File upload with automatic optimization (resize, compress)
+- CDN integration (Cloudflare R2)
+- Pre-signed upload URLs for client-side uploads
+- Public URL generation
+- File metadata tracking
+
+**Quick Start:**
+
+```typescript
+import { uploadFile, getPublicUrl } from 'miragedev-sdk/storage'
+
+// Upload a file
+const result = await uploadFile({
+  file: imageBuffer,
+  key: 'avatars/user-123.jpg',
+  contentType: 'image/jpeg',
+  resize: { width: 800, height: 800, fit: 'cover' }
+})
+
+// Get public CDN URL
+const url = await getPublicUrl(result.key)
+console.log(url) // https://cdn.example.com/avatars/user-123.jpg
+```
+
+**Configuration:**
+
+```typescript
+import { initMirageDev } from 'miragedev-sdk'
+
+initMirageDev({
+  storage: {
+    provider: 'cloudflare-r2',
+    cloudflareR2: {
+      accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+      accessKeyId: process.env.CLOUDFLARE_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.CLOUDFLARE_SECRET_ACCESS_KEY!,
+      bucketName: process.env.CLOUDFLARE_BUCKET_NAME!,
+      cdnUrl: 'https://cdn.example.com', // Optional
+    }
+  }
+})
+```
+
+**Environment Variables:**
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_ACCESS_KEY_ID`
+- `CLOUDFLARE_SECRET_ACCESS_KEY`
+- `CLOUDFLARE_BUCKET_NAME`
+
+### 📊 Analytics Module
+
+Track events, identify users, and monitor usage limits.
+
+**Features:**
+- Event tracking with properties
+- User identification and properties
+- Usage tracking with Redis storage
+- Automatic integration with Limits module
+
+**Quick Start:**
+
+```typescript
+import { trackEvent, identifyUser, incrementUsage, getUsage } from 'miragedev-sdk/analytics'
+
+// Track events
+await trackEvent('image_generated', {
+  userId: 'user-123',
+  model: 'dalle-3',
+  credits: 10
+})
+
+// Identify users
+await identifyUser('user-123', {
+  email: 'user@example.com',
+  plan: 'pro',
+  signupDate: '2026-01-01'
+})
+
+// Track usage limits
+await incrementUsage('user-123', 'api_calls', 1)
+const usage = await getUsage('user-123', 'api_calls')
+console.log(`API calls: ${usage}`)
+```
+
+**React Hooks:**
+
+```typescript
+'use client'
+import { useAnalytics, useUsageLimits, usePageTracking } from 'miragedev-sdk/analytics/client'
+
+function Dashboard() {
+  const { trackEvent } = useAnalytics()
+  const { usage, increment, reset } = useUsageLimits('user-123', 'api_calls')
+  
+  usePageTracking() // Auto-track page views
+  
+  return <div>API Calls: {usage}</div>
+}
+```
+
+**Configuration:**
+
+```typescript
+initMirageDev({
+  analytics: {
+    provider: 'posthog',
+    posthog: {
+      apiKey: process.env.POSTHOG_API_KEY!,
+      host: process.env.POSTHOG_HOST || 'https://app.posthog.com',
+    }
+  },
+  limits: { // Required for usage tracking
+    provider: 'upstash',
+    upstash: {
+      url: process.env.UPSTASH_REDIS_URL!,
+      token: process.env.UPSTASH_REDIS_TOKEN!,
+    }
+  }
+})
+```
+
+**Environment Variables:**
+- `POSTHOG_API_KEY`
+- `POSTHOG_HOST` (optional)
+
+### 🚦 Limits Module
+
+Rate limiting and circuit breaker for cost control.
+
+**Features:**
+- Sliding window rate limiting
+- Multi-tier rate limits
+- Circuit breaker pattern
+- Cost protection for AI APIs
+- Redis-backed counters
+
+**Quick Start:**
+
+```typescript
+import { checkRateLimit, checkCircuitBreaker, checkMultipleRateLimits } from 'miragedev-sdk/limits'
+
+// Rate limiting
+const result = await checkRateLimit({
+  key: 'api:user:123',
+  limit: 100,
+  window: 3600 // 1 hour
+})
+
+if (!result.allowed) {
+  throw new Error(`Rate limit exceeded. Try again in ${result.resetIn}s`)
+}
+
+// Multi-tier rate limits
+const [ipLimit, userLimit] = await checkMultipleRateLimits([
+  { key: 'api:ip:1.2.3.4', limit: 1000, window: 3600 },
+  { key: 'api:user:123', limit: 100, window: 3600 },
+])
+
+if (!ipLimit.allowed || !userLimit.allowed) {
+  throw new Error('Rate limit exceeded')
+}
+
+// Circuit breaker for AI costs
+const breaker = await checkCircuitBreaker({
+  key: 'ai:openai',
+  threshold: 1000, // $10 limit
+  window: 3600,
+  cooldown: 300
+})
+
+if (!breaker.allowed) {
+  throw new Error('AI spending limit reached')
+}
+
+// After successful AI call
+await breaker.increment(5) // $0.05 spent
+```
+
+**Configuration:**
+
+```typescript
+initMirageDev({
+  limits: {
+    provider: 'upstash',
+    upstash: {
+      url: process.env.UPSTASH_REDIS_URL!,
+      token: process.env.UPSTASH_REDIS_TOKEN!,
+    }
+  }
+})
+```
+
+**Environment Variables:**
+- `UPSTASH_REDIS_URL`
+- `UPSTASH_REDIS_TOKEN`
+
+### ⚙️ Jobs Module
+
+Background jobs and scheduled tasks.
+
+**Features:**
+- Background job processing
+- Cron scheduling
+- Job status tracking
+- Type-safe job definitions
+- Automatic retries
+
+**Quick Start:**
+
+```typescript
+import { enqueueJob, getJobStatus, scheduleJob } from 'miragedev-sdk/jobs'
+import { defineJob, registerJobs } from 'miragedev-sdk/jobs/define'
+
+// Define job handlers
+const generateImageJob = defineJob(
+  'generate-image',
+  async (payload: { userId: string; prompt: string }, context) => {
+    const image = await generateImage(payload.prompt)
+    await uploadFile({ file: image, key: `images/${context.job.id}.png` })
+    await trackEvent('image_generated', { userId: payload.userId })
+    return { success: true }
+  }
+)
+
+// Register jobs (in your server startup)
+registerJobs([generateImageJob])
+
+// Enqueue jobs
+const job = await enqueueJob('generate-image', {
+  userId: 'user-123',
+  prompt: 'A beautiful sunset'
+})
+
+// Check job status
+const status = await getJobStatus(job.id)
+console.log(status) // 'queued', 'running', 'success', 'failed'
+
+// Schedule jobs
+await scheduleJob('generate-image', '0 0 * * *', {
+  userId: 'system',
+  prompt: 'Daily digest image'
+})
+```
+
+**React Hooks:**
+
+```typescript
+'use client'
+import { useJobStatus, useUserJobs } from 'miragedev-sdk/jobs/client'
+
+function JobTracker({ jobId }: { jobId: string }) {
+  const { status, result, error, isLoading } = useJobStatus(jobId)
+  
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  
+  return <div>Job Status: {status}</div>
+}
+
+function UserJobs({ userId }: { userId: string }) {
+  const { jobs, isLoading } = useUserJobs(userId, { limit: 10 })
+  
+  return (
+    <ul>
+      {jobs.map(job => (
+        <li key={job.id}>{job.name}: {job.status}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+**Configuration:**
+
+```typescript
+initMirageDev({
+  jobs: {
+    provider: 'trigger',
+    trigger: {
+      apiKey: process.env.TRIGGER_API_KEY!,
+      apiUrl: process.env.TRIGGER_API_URL || 'https://api.trigger.dev',
+    }
+  }
+})
+```
+
+**Environment Variables:**
+- `TRIGGER_API_KEY`
+- `TRIGGER_API_URL` (optional)
+
+### 🔗 Module Integration
+
+Combine modules for powerful SaaS workflows.
+
+**Example: AI Image Generation SaaS**
+
+```typescript
+import { checkRateLimit, checkCircuitBreaker } from 'miragedev-sdk/limits'
+import { enqueueJob } from 'miragedev-sdk/jobs'
+import { uploadFile } from 'miragedev-sdk/storage'
+import { trackEvent, incrementUsage } from 'miragedev-sdk/analytics'
+
+export async function POST(req: Request) {
+  const { userId, prompt } = await req.json()
+  
+  // Step 1: Check rate limits
+  const userLimit = await checkRateLimit({
+    key: `generate:${userId}`,
+    limit: 10,
+    window: 3600 // 10 images per hour
+  })
+  
+  if (!userLimit.allowed) {
+    return Response.json({ error: 'Rate limit exceeded' }, { status: 429 })
+  }
+  
+  // Step 2: Check AI cost circuit breaker
+  const aiBreaker = await checkCircuitBreaker({
+    key: 'ai:dalle',
+    threshold: 10000, // $100/hour limit
+    window: 3600,
+    cooldown: 300
+  })
+  
+  if (!aiBreaker.allowed) {
+    return Response.json({ error: 'AI service temporarily unavailable' }, { status: 503 })
+  }
+  
+  // Step 3: Enqueue background job
+  const job = await enqueueJob('generate-image', { userId, prompt })
+  
+  // Step 4: Track analytics
+  await trackEvent('image_requested', { userId, prompt })
+  await incrementUsage(userId, 'images_generated', 1)
+  
+  // Step 5: Increment AI costs (after successful generation)
+  await aiBreaker.increment(40) // $0.40 per image
+  
+  return Response.json({ jobId: job.id, status: 'queued' })
+}
+```
+
+**Job Handler:**
+
+```typescript
+const generateImageJob = defineJob(
+  'generate-image',
+  async (payload: { userId: string; prompt: string }) => {
+    // Generate image
+    const image = await callDalleAPI(payload.prompt)
+    
+    // Upload to CDN
+    const result = await uploadFile({
+      file: image,
+      key: `images/${payload.userId}/${Date.now()}.png`,
+      contentType: 'image/png',
+      resize: { width: 1024, height: 1024 }
+    })
+    
+    // Track success
+    await trackEvent('image_generated', {
+      userId: payload.userId,
+      url: result.url
+    })
+    
+    return { url: result.url }
+  }
+)
+```
+
+This workflow demonstrates:
+- ✅ Rate limiting per user
+- ✅ Circuit breaker for cost control
+- ✅ Background job processing
+- ✅ CDN file storage
+- ✅ Analytics tracking
 ```
 
 ## API Reference