miragedev-sdk 0.3.0 → 0.4.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
 ```
 
@@ -389,6 +411,388 @@ OPENAI_API_KEY=sk-...
 **Supported Providers:**
 - ✅ OpenAI (GPT-4, GPT-3.5, embeddings)
 - 🔜 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

package/dist/ai/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AIConfig, C as ChatOptions, e as ChatResponse, S as StreamChunk, E as EmbeddingOptions, f as EmbeddingResponse } from '../ai-DTlWq4Xf.cjs';
-export { d as AIFunction, c as AIMessage, a as AIProvider, b as AIRole } from '../ai-DTlWq4Xf.cjs';
+import { A as AIConfig, C as ChatOptions, a as ChatResponse, S as StreamChunk, E as EmbeddingOptions, b as EmbeddingResponse } from '../ai-B4sdf-PH.cjs';
+export { f as AIFunction, e as AIMessage, c as AIProvider, d as AIRole } from '../ai-B4sdf-PH.cjs';
 
 declare function setAIConfig(config: Partial<AIConfig>): void;
 declare function getAIConfig(): AIConfig;

package/dist/ai/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AIConfig, C as ChatOptions, e as ChatResponse, S as StreamChunk, E as EmbeddingOptions, f as EmbeddingResponse } from '../ai-DTlWq4Xf.js';
-export { d as AIFunction, c as AIMessage, a as AIProvider, b as AIRole } from '../ai-DTlWq4Xf.js';
+import { A as AIConfig, C as ChatOptions, a as ChatResponse, S as StreamChunk, E as EmbeddingOptions, b as EmbeddingResponse } from '../ai-B4sdf-PH.js';
+export { f as AIFunction, e as AIMessage, c as AIProvider, d as AIRole } from '../ai-B4sdf-PH.js';
 
 declare function setAIConfig(config: Partial<AIConfig>): void;
 declare function getAIConfig(): AIConfig;

package/dist/{ai-DTlWq4Xf.d.cts → ai-B4sdf-PH.d.cts}

@@ -69,4 +69,4 @@ type EmbeddingResponse = {
     };
 };
 
-export type { AIConfig as A, ChatOptions as C, EmbeddingOptions as E, StreamChunk as S, AIProvider as a, AIRole as b, AIMessage as c, AIFunction as d, ChatResponse as e, EmbeddingResponse as f };
+export type { AIConfig as A, ChatOptions as C, EmbeddingOptions as E, StreamChunk as S, ChatResponse as a, EmbeddingResponse as b, AIProvider as c, AIRole as d, AIMessage as e, AIFunction as f };

package/dist/{ai-DTlWq4Xf.d.ts → ai-B4sdf-PH.d.ts}

@@ -69,4 +69,4 @@ type EmbeddingResponse = {
     };
 };
 
-export type { AIConfig as A, ChatOptions as C, EmbeddingOptions as E, StreamChunk as S, AIProvider as a, AIRole as b, AIMessage as c, AIFunction as d, ChatResponse as e, EmbeddingResponse as f };
+export type { AIConfig as A, ChatOptions as C, EmbeddingOptions as E, StreamChunk as S, ChatResponse as a, EmbeddingResponse as b, AIProvider as c, AIRole as d, AIMessage as e, AIFunction as f };

package/dist/analytics/client.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+require('../chunk-75ZPJI57.cjs');
+var react = require('react');
+
+function useAnalytics() {
+  const track = react.useCallback(
+    async (eventName, properties) => {
+      try {
+        await fetch("/api/analytics/track", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ eventName, properties })
+        });
+      } catch (error) {
+        console.error("Analytics tracking error:", error);
+      }
+    },
+    []
+  );
+  const identify = react.useCallback(
+    async (userId, properties) => {
+      try {
+        await fetch("/api/analytics/identify", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ userId, properties })
+        });
+      } catch (error) {
+        console.error("Analytics identify error:", error);
+      }
+    },
+    []
+  );
+  return { track, identify };
+}
+function useUsageLimits(metric) {
+  const [usage, setUsage] = react.useState(0);
+  const [limit, setLimit] = react.useState(void 0);
+  const [isLoading, setIsLoading] = react.useState(true);
+  const [error, setError] = react.useState(null);
+  react.useEffect(() => {
+    const fetchUsage = async () => {
+      try {
+        setIsLoading(true);
+        const response = await fetch(
+          `/api/analytics/usage?metric=${encodeURIComponent(metric)}`
+        );
+        if (!response.ok) {
+          throw new Error(`Failed to fetch usage: ${response.statusText}`);
+        }
+        const data = await response.json();
+        setUsage(data.usage || 0);
+        setLimit(data.limit);
+        setError(null);
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error("Unknown error"));
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    fetchUsage();
+  }, [metric]);
+  const percentage = limit ? Math.min(Math.round(usage / limit * 100), 100) : 0;
+  const isLimitReached = limit ? usage >= limit : false;
+  const remaining = limit ? Math.max(limit - usage, 0) : 0;
+  return {
+    usage,
+    limit,
+    percentage,
+    isLimitReached,
+    remaining,
+    isLoading,
+    error
+  };
+}
+function usePageTracking(additionalProperties) {
+  const { track } = useAnalytics();
+  react.useEffect(() => {
+    const trackPageView = async () => {
+      track("page_view", {
+        path: window.location.pathname,
+        search: window.location.search,
+        ...additionalProperties
+      });
+    };
+    trackPageView();
+  }, [track, additionalProperties]);
+}
+
+exports.useAnalytics = useAnalytics;
+exports.usePageTracking = usePageTracking;
+exports.useUsageLimits = useUsageLimits;

package/dist/analytics/client.d.cts

@@ -0,0 +1,19 @@
+import { E as EventProperties, U as UserProperties } from '../analytics-KVIUba3B.cjs';
+
+declare function useAnalytics(): {
+    track: (eventName: string, properties?: EventProperties) => Promise<void>;
+    identify: (userId: string, properties?: UserProperties) => Promise<void>;
+};
+interface UsageLimitsData {
+    usage: number;
+    limit?: number;
+    percentage: number;
+    isLimitReached: boolean;
+    remaining: number;
+    isLoading: boolean;
+    error: Error | null;
+}
+declare function useUsageLimits(metric: string): UsageLimitsData;
+declare function usePageTracking(additionalProperties?: EventProperties): void;
+
+export { type UsageLimitsData, useAnalytics, usePageTracking, useUsageLimits };

package/dist/analytics/client.d.ts

@@ -0,0 +1,19 @@
+import { E as EventProperties, U as UserProperties } from '../analytics-KVIUba3B.js';
+
+declare function useAnalytics(): {
+    track: (eventName: string, properties?: EventProperties) => Promise<void>;
+    identify: (userId: string, properties?: UserProperties) => Promise<void>;
+};
+interface UsageLimitsData {
+    usage: number;
+    limit?: number;
+    percentage: number;
+    isLimitReached: boolean;
+    remaining: number;
+    isLoading: boolean;
+    error: Error | null;
+}
+declare function useUsageLimits(metric: string): UsageLimitsData;
+declare function usePageTracking(additionalProperties?: EventProperties): void;
+
+export { type UsageLimitsData, useAnalytics, usePageTracking, useUsageLimits };

package/dist/analytics/client.js

@@ -0,0 +1,89 @@
+import '../chunk-MLKGABMK.js';
+import { useCallback, useState, useEffect } from 'react';
+
+function useAnalytics() {
+  const track = useCallback(
+    async (eventName, properties) => {
+      try {
+        await fetch("/api/analytics/track", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ eventName, properties })
+        });
+      } catch (error) {
+        console.error("Analytics tracking error:", error);
+      }
+    },
+    []
+  );
+  const identify = useCallback(
+    async (userId, properties) => {
+      try {
+        await fetch("/api/analytics/identify", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ userId, properties })
+        });
+      } catch (error) {
+        console.error("Analytics identify error:", error);
+      }
+    },
+    []
+  );
+  return { track, identify };
+}
+function useUsageLimits(metric) {
+  const [usage, setUsage] = useState(0);
+  const [limit, setLimit] = useState(void 0);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    const fetchUsage = async () => {
+      try {
+        setIsLoading(true);
+        const response = await fetch(
+          `/api/analytics/usage?metric=${encodeURIComponent(metric)}`
+        );
+        if (!response.ok) {
+          throw new Error(`Failed to fetch usage: ${response.statusText}`);
+        }
+        const data = await response.json();
+        setUsage(data.usage || 0);
+        setLimit(data.limit);
+        setError(null);
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error("Unknown error"));
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    fetchUsage();
+  }, [metric]);
+  const percentage = limit ? Math.min(Math.round(usage / limit * 100), 100) : 0;
+  const isLimitReached = limit ? usage >= limit : false;
+  const remaining = limit ? Math.max(limit - usage, 0) : 0;
+  return {
+    usage,
+    limit,
+    percentage,
+    isLimitReached,
+    remaining,
+    isLoading,
+    error
+  };
+}
+function usePageTracking(additionalProperties) {
+  const { track } = useAnalytics();
+  useEffect(() => {
+    const trackPageView = async () => {
+      track("page_view", {
+        path: window.location.pathname,
+        search: window.location.search,
+        ...additionalProperties
+      });
+    };
+    trackPageView();
+  }, [track, additionalProperties]);
+}
+
+export { useAnalytics, usePageTracking, useUsageLimits };