miragedev-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MirageDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,393 @@
+# MirageDev SDK
+
+AI-first SDK for building SAAS applications with Next.js. Build production-ready SAAS apps in minutes, not weeks.
+
+[![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
+
+## Quick Start (5 minutes)
+
+### 1. Installation
+
+```bash
+npm install miragedev-sdk
+# or
+pnpm add miragedev-sdk
+```
+
+### 2. Initialize with CLI
+
+```bash
+npx miragedev init
+```
+
+The CLI will guide you through selecting providers and generating configuration files.
+
+**What gets created:**
+- `miragedev.config.ts` - SDK configuration
+- `.env.local.example` - Environment variables template
+- `miragedev.init.ts` - Initialization file
+- `AGENTS.md` - Instructions for AI assistants (Copilot, Cursor, etc.)
+
+### 3. Configure Environment
+
+Create `.env.local`:
+
+```env
+# Auth
+AUTH_SECRET=your-secret-key-here
+
+# Billing (Stripe)
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# Email (Resend)
+RESEND_API_KEY=re_xxx
+EMAIL_FROM=noreply@yourapp.com
+```
+
+### 4. Initialize SDK
+
+Create `lib/miragedev.ts`:
+
+```typescript
+import { initMirageDev } from 'miragedev-sdk'
+
+initMirageDev({
+  auth: {
+    provider: 'nextauth',
+    sessionSecret: process.env.AUTH_SECRET!,
+  },
+  billing: {
+    provider: 'stripe',
+    stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
+    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+  },
+  email: {
+    provider: 'resend',
+    apiKey: process.env.RESEND_API_KEY!,
+    from: process.env.EMAIL_FROM!,
+  },
+})
+```
+
+Import this in your root layout (`app/layout.tsx`).
+
+### 5. Start Building
+
+```typescript
+// Server Component - Protected Page
+import { requireAuth } from 'miragedev-sdk/auth'
+
+export default async function DashboardPage() {
+  const session = await requireAuth() // Throws if not authenticated
+  return <div>Welcome {session.user.name}!</div>
+}
+```
+
+```typescript
+// Client Component - Subscription Button
+'use client'
+import { useSubscription } from 'miragedev-sdk/billing/client'
+
+export function UpgradeButton() {
+  const { subscription, isLoading } = useSubscription()
+  
+  if (subscription?.status === 'active') {
+    return <button>Manage Subscription</button>
+  }
+  
+  return <button>Upgrade to Pro</button>
+}
+```
+
+## Configuration
+
+### Auth Module
+
+```typescript
+import { requireAuth, getSession } from 'miragedev-sdk/auth'
+import { authMiddleware } from 'miragedev-sdk/auth/middleware'
+import { useSession, signIn, signOut } from 'miragedev-sdk/auth/client'
+import { enableBiometric, signInWithBiometric } from 'miragedev-sdk/auth/biometric'
+```
+
+**Server-Side:**
+- `requireAuth()` - Require authentication, throws error if not authenticated
+- `getSession()` - Get current session or null
+
+**Client-Side:**
+- `useSession()` - React hook for session state
+- `signIn(provider?)` - Sign in with optional provider
+- `signOut()` - Sign out current user
+
+**Middleware:**
+```typescript
+// middleware.ts
+export default authMiddleware({
+  publicRoutes: ['/', '/pricing'],
+  redirectTo: '/login'
+})
+```
+
+**Biometric:**
+```typescript
+await enableBiometric() // Enable for current user
+const session = await signInWithBiometric() // Sign in with biometric
+```
+
+### Billing Module
+
+```typescript
+import { 
+  createCheckout, 
+  createPortal, 
+  getSubscription, 
+  cancelSubscription 
+} from 'miragedev-sdk/billing'
+import { useSubscription, openBillingPortal } from 'miragedev-sdk/billing/client'
+import { createMobileCheckout, createPaymentIntent } from 'miragedev-sdk/billing/mobile'
+import { handleWebhook } from 'miragedev-sdk/billing/webhook'
+```
+
+**Checkout:**
+```typescript
+const { url } = await createCheckout({
+  priceId: 'price_xxx',
+  userId: session.user.id,
+  successUrl: 'https://yourapp.com/success',
+  cancelUrl: 'https://yourapp.com/cancel',
+})
+redirect(url)
+```
+
+**Webhooks:**
+```typescript
+// app/api/webhooks/stripe/route.ts
+export async function POST(req: Request) {
+  return handleWebhook(req, {
+    onSubscriptionCreated: async (data) => {
+      await db.user.update({ 
+        where: { id: data.userId }, 
+        data: { isPro: true }
+      })
+    },
+    onSubscriptionCanceled: async (data) => {
+      // Handle cancellation
+    }
+  })
+}
+```
+
+**Mobile:**
+```typescript
+// For mobile PWA checkout
+const { clientSecret } = await createMobileCheckout({
+  priceId: 'price_xxx',
+  userId: user.id,
+  successUrl: 'myapp://success',
+  cancelUrl: 'myapp://cancel',
+})
+```
+
+### Email Module
+
+```typescript
+import { sendEmail, sendTemplateEmail } from 'miragedev-sdk/email'
+```
+
+**Basic Email:**
+```typescript
+await sendEmail({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<p>Hello World</p>',
+})
+```
+
+**Template Email:**
+```typescript
+await sendTemplateEmail({
+  to: 'user@example.com',
+  template: 'welcome',
+  data: {
+    userName: 'John',
+    actionUrl: 'https://app.com/onboarding'
+  }
+})
+```
+
+**Available Templates:**
+- `welcome` - Welcome new users
+- `reset-password` - Password reset
+- `subscription-created` - Subscription confirmation
+- `subscription-canceled` - Cancellation notice
+- `invoice` - Invoice notification
+
+### PWA Module
+
+```typescript
+import { configurePWA } from 'miragedev-sdk/pwa'
+```
+
+```typescript
+export const pwaConfig = configurePWA({
+  name: 'My SaaS App',
+  shortName: 'MySaaS',
+  theme: '#000000',
+  backgroundColor: '#ffffff',
+  offline: { 
+    enabled: true, 
+    pages: ['/', '/dashboard'] 
+  }
+})
+
+// Use pwaConfig.manifest in Next.js metadata
+// Write pwaConfig.serviceWorker to public/sw.js
+```
+
+### Mobile Module
+
+```typescript
+import { 
+  useNetworkStatus, 
+  useInstallPrompt, 
+  useNotifications, 
+  usePullToRefresh 
+} from 'miragedev-sdk/mobile'
+```
+
+```typescript
+function MyComponent() {
+  const isOnline = useNetworkStatus()
+  const { canInstall, promptInstall } = useInstallPrompt()
+  const { permission, requestPermission } = useNotifications()
+  const { isRefreshing } = usePullToRefresh(async () => {
+    await fetchData()
+  })
+  
+  // Your component logic
+}
+```
+
+## API Reference
+
+Full API documentation with examples for every function is available in the code via JSDoc. Your AI assistant can read these to help you build faster.
+
+## Examples
+
+Check out the `examples/` directory for complete working applications:
+
+- `examples/basic-saas` - Minimal SAAS with auth + billing
+- `examples/with-biometric` - Biometric authentication example
+- `examples/stripe-advanced` - Advanced billing with multiple tiers
+
+## Troubleshooting
+
+### "SDK not initialized" error
+
+Make sure you call `initMirageDev()` before using any SDK functions. Import the initialization in your root layout.
+
+### Webhooks not working
+
+1. Verify your webhook secret is correct in `.env.local`
+2. Make sure your webhook endpoint is publicly accessible
+3. Check Stripe dashboard for webhook delivery logs
+
+### TypeScript errors
+
+The SDK is fully typed. If you see type errors, make sure you're using TypeScript 5.0+ and have `strict: true` in your tsconfig.json.
+
+## Publishing the SDK
+
+### For Maintainers: Automated Publishing
+
+This SDK uses **automated versioning and publishing** via GitHub Actions.
+
+#### How It Works
+
+When a PR is merged to `main`:
+1. ✅ Tests run automatically
+2. ✅ Version is bumped based on commit messages:
+   - `feat:` → minor version (0.1.0 → 0.2.0)
+   - `fix:` → patch version (0.1.0 → 0.1.1)
+   - `feat!:` or `BREAKING CHANGE` → major version (0.1.0 → 1.0.0)
+3. ✅ package.json is updated and committed
+4. ✅ Git tag is created automatically
+5. ✅ Package is published to NPM
+6. ✅ GitHub Release is created
+
+#### Setup (One Time)
+
+1. Add `NPM_TOKEN` to GitHub repository secrets:
+   - Go to npmjs.com → Access Tokens → Generate New Token (Automation)
+   - Copy token
+   - Go to GitHub repo → Settings → Secrets → New secret
+   - Name: `NPM_TOKEN`, Value: (paste token)
+
+2. That's it! Now every merge to main auto-publishes.
+
+#### Publishing Process
+
+**Simple workflow:**
+```bash
+# 1. Create feature branch
+git checkout -b feat/new-feature
+
+# 2. Make changes with conventional commits
+git commit -m "feat: add new awesome feature"
+
+# 3. Push and create PR
+git push origin feat/new-feature
+
+# 4. Merge PR to main
+# → GitHub Actions automatically:
+#    - Runs tests
+#    - Bumps version (0.1.0 → 0.2.0)
+#    - Publishes to NPM
+#    - Creates release
+```
+
+**No manual `npm version` or `npm publish` needed!**
+
+#### Manual Publishing (Emergency Only)
+
+If you need to publish manually:
+```bash
+npm version patch  # or minor/major
+npm run prepublishOnly  # Runs type-check, tests, build
+npm publish --access public
+git push && git push --tags
+```
+
+#### After Publishing
+
+Users can install the latest version:
+```bash
+npm install miragedev-sdk@latest
+```
+
+## License
+
+MIT © MirageDev
+
+## Support
+
+- 📖 [Documentation](https://github.com/miragedev/miragedev-sdk)
+- 🐛 [Issue Tracker](https://github.com/miragedev/miragedev-sdk/issues)
+- 💬 [Discussions](https://github.com/miragedev/miragedev-sdk/discussions)
+
+---
+
+Built with ❤️ for the Next.js community

package/dist/auth/biometric.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+var chunkBW4BLEIM_cjs = require('../chunk-BW4BLEIM.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+// src/auth/biometric.ts
+function isBiometricSupported() {
+  return typeof window !== "undefined" && window.PublicKeyCredential !== void 0 && typeof window.PublicKeyCredential === "function";
+}
+async function enableBiometric() {
+  if (!isBiometricSupported()) {
+    throw new chunkBW4BLEIM_cjs.MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      "Biometric authentication is not supported in this browser"
+    );
+  }
+  try {
+    const optionsResponse = await fetch("/api/auth/biometric/register", {
+      method: "POST"
+    });
+    if (!optionsResponse.ok) {
+      throw new Error("Failed to get registration options");
+    }
+    const options = await optionsResponse.json();
+    const credential = await navigator.credentials.create({
+      publicKey: options
+    });
+    if (!credential) {
+      throw new Error("Failed to create credentials");
+    }
+    const registerResponse = await fetch("/api/auth/biometric/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credential)
+    });
+    if (!registerResponse.ok) {
+      throw new Error("Failed to register biometric");
+    }
+  } catch (error) {
+    throw new chunkBW4BLEIM_cjs.MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      `Failed to enable biometric authentication: ${error.message}`
+    );
+  }
+}
+async function signInWithBiometric() {
+  if (!isBiometricSupported()) {
+    throw new chunkBW4BLEIM_cjs.MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      "Biometric authentication is not supported in this browser"
+    );
+  }
+  try {
+    const optionsResponse = await fetch("/api/auth/biometric/authenticate");
+    if (!optionsResponse.ok) {
+      throw new Error("Failed to get authentication options");
+    }
+    const options = await optionsResponse.json();
+    const credential = await navigator.credentials.get({
+      publicKey: options
+    });
+    if (!credential) {
+      throw new Error("Failed to get credentials");
+    }
+    const verifyResponse = await fetch("/api/auth/biometric/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credential)
+    });
+    if (!verifyResponse.ok) {
+      throw new Error("Failed to verify biometric");
+    }
+    const session = await verifyResponse.json();
+    return session;
+  } catch (error) {
+    throw new chunkBW4BLEIM_cjs.MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      `Biometric authentication failed: ${error.message}`
+    );
+  }
+}
+
+exports.enableBiometric = enableBiometric;
+exports.isBiometricSupported = isBiometricSupported;
+exports.signInWithBiometric = signInWithBiometric;

package/dist/auth/biometric.d.cts

@@ -0,0 +1,7 @@
+import { S as Session } from '../auth-BC8JI28z.cjs';
+
+declare function isBiometricSupported(): boolean;
+declare function enableBiometric(): Promise<void>;
+declare function signInWithBiometric(): Promise<Session>;
+
+export { enableBiometric, isBiometricSupported, signInWithBiometric };

package/dist/auth/biometric.d.ts

@@ -0,0 +1,7 @@
+import { S as Session } from '../auth-BC8JI28z.js';
+
+declare function isBiometricSupported(): boolean;
+declare function enableBiometric(): Promise<void>;
+declare function signInWithBiometric(): Promise<Session>;
+
+export { enableBiometric, isBiometricSupported, signInWithBiometric };

package/dist/auth/biometric.js

@@ -0,0 +1,81 @@
+import { MirageDevError } from '../chunk-JUTTFY3W.js';
+import '../chunk-MLKGABMK.js';
+
+// src/auth/biometric.ts
+function isBiometricSupported() {
+  return typeof window !== "undefined" && window.PublicKeyCredential !== void 0 && typeof window.PublicKeyCredential === "function";
+}
+async function enableBiometric() {
+  if (!isBiometricSupported()) {
+    throw new MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      "Biometric authentication is not supported in this browser"
+    );
+  }
+  try {
+    const optionsResponse = await fetch("/api/auth/biometric/register", {
+      method: "POST"
+    });
+    if (!optionsResponse.ok) {
+      throw new Error("Failed to get registration options");
+    }
+    const options = await optionsResponse.json();
+    const credential = await navigator.credentials.create({
+      publicKey: options
+    });
+    if (!credential) {
+      throw new Error("Failed to create credentials");
+    }
+    const registerResponse = await fetch("/api/auth/biometric/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credential)
+    });
+    if (!registerResponse.ok) {
+      throw new Error("Failed to register biometric");
+    }
+  } catch (error) {
+    throw new MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      `Failed to enable biometric authentication: ${error.message}`
+    );
+  }
+}
+async function signInWithBiometric() {
+  if (!isBiometricSupported()) {
+    throw new MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      "Biometric authentication is not supported in this browser"
+    );
+  }
+  try {
+    const optionsResponse = await fetch("/api/auth/biometric/authenticate");
+    if (!optionsResponse.ok) {
+      throw new Error("Failed to get authentication options");
+    }
+    const options = await optionsResponse.json();
+    const credential = await navigator.credentials.get({
+      publicKey: options
+    });
+    if (!credential) {
+      throw new Error("Failed to get credentials");
+    }
+    const verifyResponse = await fetch("/api/auth/biometric/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credential)
+    });
+    if (!verifyResponse.ok) {
+      throw new Error("Failed to verify biometric");
+    }
+    const session = await verifyResponse.json();
+    return session;
+  } catch (error) {
+    throw new MirageDevError(
+      "AUTH_INVALID_CREDENTIALS",
+      `Biometric authentication failed: ${error.message}`
+    );
+  }
+}
+
+export { enableBiometric, isBiometricSupported, signInWithBiometric };

package/dist/auth/client.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+require('../chunk-75ZPJI57.cjs');
+var react = require('react');
+
+function useSession() {
+  const [session, setSession] = react.useState(null);
+  const [status, setStatus] = react.useState("loading");
+  react.useEffect(() => {
+    fetch("/api/auth/session").then((res) => res.json()).then((data) => {
+      if (data && data.user) {
+        setSession(data);
+        setStatus("authenticated");
+      } else {
+        setSession(null);
+        setStatus("unauthenticated");
+      }
+    }).catch(() => {
+      setSession(null);
+      setStatus("unauthenticated");
+    });
+  }, []);
+  return { session, status };
+}
+async function signIn(provider) {
+  const url = provider ? `/api/auth/signin/${provider}` : "/api/auth/signin";
+  if (typeof window !== "undefined") {
+    window.location.href = url;
+  }
+}
+async function signOut() {
+  try {
+    await fetch("/api/auth/signout", { method: "POST" });
+    if (typeof window !== "undefined") {
+      window.location.href = "/";
+    }
+  } catch (error) {
+    console.error("Sign out failed:", error);
+  }
+}
+
+exports.signIn = signIn;
+exports.signOut = signOut;
+exports.useSession = useSession;

package/dist/auth/client.d.cts

@@ -0,0 +1,12 @@
+import { S as Session } from '../auth-BC8JI28z.cjs';
+
+type SessionStatus = 'authenticated' | 'unauthenticated' | 'loading';
+interface UseSessionReturn {
+    session: Session | null;
+    status: SessionStatus;
+}
+declare function useSession(): UseSessionReturn;
+declare function signIn(provider?: string): Promise<void>;
+declare function signOut(): Promise<void>;
+
+export { type SessionStatus, type UseSessionReturn, signIn, signOut, useSession };

package/dist/auth/client.d.ts

@@ -0,0 +1,12 @@
+import { S as Session } from '../auth-BC8JI28z.js';
+
+type SessionStatus = 'authenticated' | 'unauthenticated' | 'loading';
+interface UseSessionReturn {
+    session: Session | null;
+    status: SessionStatus;
+}
+declare function useSession(): UseSessionReturn;
+declare function signIn(provider?: string): Promise<void>;
+declare function signOut(): Promise<void>;
+
+export { type SessionStatus, type UseSessionReturn, signIn, signOut, useSession };