@scalemule/nextjs 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleMule Inc.
+
+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,297 @@
+# @scalemule/nextjs
+
+ScaleMule SDK for Next.js applications.
+
+Server-side authentication with HTTP-only cookies, CSRF protection, webhook handling, secrets management, and client-side hooks.
+
+## Install
+
+```bash
+npm install @scalemule/nextjs
+```
+
+## Auth in 6 Lines
+
+```ts
+// app/api/auth/[...scalemule]/route.ts
+import { createAuthRoutes } from '@scalemule/nextjs/server'
+
+export const { GET, POST, DELETE, PATCH } = createAuthRoutes()
+```
+
+This creates all auth endpoints automatically:
+- `POST /api/auth/register` — register + set HTTP-only cookie
+- `POST /api/auth/login` — login + set HTTP-only cookie
+- `POST /api/auth/logout` — logout + clear cookie
+- `GET /api/auth/me` — get current user
+- `POST /api/auth/forgot-password` — request password reset
+- `POST /api/auth/reset-password` — reset password
+- `POST /api/auth/verify-email` — verify email
+- `POST /api/auth/resend-verification` — resend verification (session or email-only)
+- `POST /api/auth/refresh` — refresh session
+- `PATCH /api/auth/me` — update profile
+- `DELETE /api/auth/me` — delete account
+
+API keys never reach the browser. Session tokens are HTTP-only cookies.
+
+## Environment Variables
+
+```bash
+# .env.local
+SCALEMULE_API_KEY=sk_prod_xxx    # server-only, no NEXT_PUBLIC_ prefix
+SCALEMULE_ENV=prod               # 'dev' | 'prod'
+SCALEMULE_COOKIE_DOMAIN=.yourdomain.com  # optional, for subdomain sharing
+```
+
+## Auth Route Options
+
+```ts
+export const { GET, POST, DELETE, PATCH } = createAuthRoutes({
+  // CSRF validation (recommended for production)
+  csrf: true,
+
+  // Cookie configuration
+  cookies: {
+    domain: '.yourdomain.com',    // share across subdomains
+    maxAge: 30 * 24 * 60 * 60,    // 30 days
+  },
+
+  // Lifecycle hooks
+  onRegister: async (user) => { /* post-registration logic */ },
+  onLogin: async (user) => { /* post-login logic */ },
+  onLogout: async () => { /* cleanup */ },
+})
+```
+
+## Webhooks in 10 Lines
+
+```ts
+// app/api/webhooks/scalemule/route.ts
+import { createWebhookHandler } from '@scalemule/nextjs/server/webhooks'
+
+export const POST = createWebhookHandler({
+  secret: process.env.SCALEMULE_WEBHOOK_SECRET,
+  onEvent: {
+    'storage.file.uploaded': async (event) => {
+      console.log('File uploaded:', event.data.file_id)
+    },
+    'video.transcoding.completed': async (event) => {
+      console.log('Video ready:', event.data.video_id)
+    },
+  },
+})
+```
+
+HMAC-SHA256 signature verification and 5-minute replay protection included.
+
+## 1-Line Auth Export
+
+For zero-config auth (reads from env vars):
+
+```ts
+// app/api/auth/[...scalemule]/route.ts
+export { GET, POST, DELETE, PATCH } from '@scalemule/nextjs/server/auth'
+```
+
+## Client-Side Provider
+
+```tsx
+// app/layout.tsx
+import { ScaleMuleProvider } from '@scalemule/nextjs'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <ScaleMuleProvider
+          apiKey={process.env.NEXT_PUBLIC_SCALEMULE_API_KEY!}
+          environment={process.env.NEXT_PUBLIC_SCALEMULE_ENV as 'dev' | 'prod'}
+        >
+          {children}
+        </ScaleMuleProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+## Client-Side Hooks
+
+### `useAuth()`
+
+```tsx
+'use client'
+import { useAuth } from '@scalemule/nextjs'
+
+function LoginPage() {
+  const { login, register, logout, user, loading, isAuthenticated, error } = useAuth()
+
+  const handleLogin = async () => {
+    await login({ email, password })
+  }
+}
+```
+
+### `useContent()`
+
+```tsx
+import { useContent } from '@scalemule/nextjs'
+
+function Gallery() {
+  const { files, upload, loading, uploadProgress, refresh, remove } = useContent({ autoFetch: true })
+
+  const handleUpload = async (file: File) => {
+    await upload(file, {
+      onProgress: (pct) => console.log(`${pct}%`),
+    })
+  }
+}
+```
+
+### `useUser()`
+
+```tsx
+import { useUser } from '@scalemule/nextjs'
+
+function Settings() {
+  const { profile, update, changePassword, changeEmail, deleteAccount, exportData } = useUser()
+}
+```
+
+### `useRealtime()`
+
+```tsx
+import { useRealtime } from '@scalemule/nextjs'
+
+function LiveUpdates() {
+  const { status, subscribe } = useRealtime({ autoConnect: true })
+
+  useEffect(() => {
+    const unsub = subscribe('notifications', (data) => {
+      console.log('New notification:', data)
+    })
+    return () => unsub()
+  }, [subscribe])
+}
+```
+
+## Server Client
+
+For server-side operations beyond auth (API routes, server components, server actions):
+
+```ts
+import { createServerClient } from '@scalemule/nextjs/server'
+
+const sm = createServerClient()
+
+// Storage
+const { data } = await sm.storage.getViewUrl(fileId)
+
+// Auth (with session token)
+const { data: user } = await sm.auth.me(sessionToken)
+
+// Secrets
+const secret = await sm.secrets.get('STRIPE_KEY')
+
+// Vault bundles
+const db = await sm.bundles.get('database/primary')
+```
+
+## CSRF Protection
+
+### Middleware Setup
+
+```ts
+// middleware.ts
+import { generateCSRFToken, CSRF_COOKIE_NAME } from '@scalemule/nextjs/server'
+import { NextResponse } from 'next/server'
+
+export function middleware(request) {
+  const response = NextResponse.next()
+
+  if (!request.cookies.get(CSRF_COOKIE_NAME)) {
+    const token = generateCSRFToken()
+    response.cookies.set(CSRF_COOKIE_NAME, token, {
+      httpOnly: false,  // must be readable by JS
+      sameSite: 'strict',
+      secure: process.env.NODE_ENV === 'production',
+      path: '/',
+    })
+  }
+
+  return response
+}
+```
+
+### Enable in Auth Routes
+
+```ts
+export const { GET, POST, DELETE, PATCH } = createAuthRoutes({
+  csrf: true,  // validates x-csrf-token header against cookie
+})
+```
+
+### Client-Side
+
+```ts
+// Read CSRF token from cookie and include in requests
+const csrfToken = document.cookie.match(/csrf_token=([^;]+)/)?.[1]
+
+fetch('/api/auth/login', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'x-csrf-token': csrfToken,
+  },
+  body: JSON.stringify({ email, password }),
+})
+```
+
+## Secrets & Vault
+
+```ts
+import {
+  getAppSecret,
+  requireAppSecret,
+  getMySqlBundle,
+  getRedisBundle,
+  getS3Bundle,
+  getOAuthBundle,
+  getBundle,
+} from '@scalemule/nextjs/server'
+
+// Simple secrets
+const apiKey = await getAppSecret('STRIPE_API_KEY')
+const required = await requireAppSecret('WEBHOOK_SECRET')  // throws if missing
+
+// Typed bundles
+const db = await getMySqlBundle('database/primary')     // { host, port, user, password, database, connectionUrl }
+const redis = await getRedisBundle('cache/main')        // { host, port, password, connectionUrl }
+const s3 = await getS3Bundle('storage/uploads')         // { bucket, region, access_key_id, secret_access_key }
+const oauth = await getOAuthBundle('google')            // { client_id, client_secret, redirect_uri }
+
+// Generic bundle
+const stripe = await getBundle<{ api_key: string; webhook_secret: string }>('external/stripe')
+```
+
+Secrets are cached for 5 minutes. Configure with `configureSecrets({ cacheTtlMs, noCache })`.
+
+## Testing
+
+```tsx
+import { MockScaleMuleProvider, createMockUser, createMockFile } from '@scalemule/nextjs/testing'
+import { render, screen } from '@testing-library/react'
+
+test('shows user name', () => {
+  render(
+    <MockScaleMuleProvider user={createMockUser({ full_name: 'Jane' })}>
+      <ProfilePage />
+    </MockScaleMuleProvider>
+  )
+  expect(screen.getByText('Jane')).toBeInTheDocument()
+})
+```
+
+## License
+
+MIT - ScaleMule Inc.

package/dist/client.d.mts

@@ -0,0 +1,163 @@
+import { i as StorageAdapter, j as ApiResponse } from './index-BkacIKdu.mjs';
+
+/**
+ * ScaleMule API Client
+ *
+ * Core HTTP client that handles:
+ * - Automatic x-api-key header injection
+ * - Automatic Authorization: Bearer header injection when authenticated
+ * - Session token management
+ * - Error handling and response parsing
+ */
+
+type ScaleMuleEnvironment = 'dev' | 'prod';
+interface ClientConfig {
+    /** Your ScaleMule API key */
+    apiKey: string;
+    /** Your ScaleMule Application ID (required for realtime features) */
+    applicationId?: string;
+    /** Environment: 'dev' or 'prod' - automatically sets gateway URL */
+    environment?: ScaleMuleEnvironment;
+    /** Custom gateway URL (overrides environment preset) */
+    gatewayUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom storage adapter */
+    storage?: StorageAdapter;
+    /** Enable rate limit queue (automatically queues requests when rate limited) */
+    enableRateLimitQueue?: boolean;
+    /** Enable offline queue (queues requests when offline, syncs when back online) */
+    enableOfflineQueue?: boolean;
+}
+interface RequestOptions extends RequestInit {
+    /** Skip adding auth headers (for public endpoints) */
+    skipAuth?: boolean;
+    /** Custom timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts for transient failures (default: 2) */
+    retries?: number;
+    /** Skip retries */
+    skipRetry?: boolean;
+}
+/**
+ * ScaleMule API Client
+ *
+ * Handles all HTTP communication with the ScaleMule gateway.
+ */
+declare class ScaleMuleClient {
+    private apiKey;
+    private applicationId;
+    private gatewayUrl;
+    private debug;
+    private storage;
+    private sessionToken;
+    private userId;
+    private rateLimitQueue;
+    private offlineQueue;
+    private enableRateLimitQueue;
+    private enableOfflineQueue;
+    constructor(config: ClientConfig);
+    /**
+     * Sync offline queue when coming back online
+     */
+    private syncOfflineQueue;
+    /**
+     * Check if client is online
+     */
+    isOnline(): boolean;
+    /**
+     * Get number of pending offline requests
+     */
+    getOfflineQueueLength(): number;
+    /**
+     * Get number of pending rate-limited requests
+     */
+    getRateLimitQueueLength(): number;
+    /**
+     * Check if currently rate limited
+     */
+    isRateLimited(): boolean;
+    /**
+     * Get the gateway URL
+     */
+    getGatewayUrl(): string;
+    /**
+     * Get the application ID (required for realtime features)
+     */
+    getApplicationId(): string | null;
+    /**
+     * Initialize client by loading persisted session
+     */
+    initialize(): Promise<void>;
+    /**
+     * Set session after login
+     */
+    setSession(token: string, userId: string): Promise<void>;
+    /**
+     * Clear session on logout
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Get current session token
+     */
+    getSessionToken(): string | null;
+    /**
+     * Get current user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Check if client has an active session
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Build headers for a request
+     */
+    private buildHeaders;
+    /**
+     * Make an HTTP request to the ScaleMule API
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * GET request
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * POST request with JSON body
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PUT request with JSON body
+     */
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PATCH request with JSON body
+     */
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Upload a file using multipart/form-data
+     *
+     * Automatically includes Authorization: Bearer header for user identity.
+     * Supports progress callback via XMLHttpRequest when onProgress is provided.
+     */
+    upload<T>(path: string, file: File, additionalFields?: Record<string, string>, options?: RequestOptions & {
+        onProgress?: (progress: number) => void;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * Upload with progress using XMLHttpRequest (with retry)
+     */
+    private uploadWithProgress;
+    /**
+     * Single upload attempt with progress using XMLHttpRequest
+     */
+    private singleUploadWithProgress;
+}
+/**
+ * Create a new ScaleMule client instance
+ */
+declare function createClient(config: ClientConfig): ScaleMuleClient;
+
+export { type ClientConfig, type RequestOptions, ScaleMuleClient, type ScaleMuleEnvironment, createClient };

package/dist/client.d.ts

@@ -0,0 +1,163 @@
+import { i as StorageAdapter, j as ApiResponse } from './index-BkacIKdu.js';
+
+/**
+ * ScaleMule API Client
+ *
+ * Core HTTP client that handles:
+ * - Automatic x-api-key header injection
+ * - Automatic Authorization: Bearer header injection when authenticated
+ * - Session token management
+ * - Error handling and response parsing
+ */
+
+type ScaleMuleEnvironment = 'dev' | 'prod';
+interface ClientConfig {
+    /** Your ScaleMule API key */
+    apiKey: string;
+    /** Your ScaleMule Application ID (required for realtime features) */
+    applicationId?: string;
+    /** Environment: 'dev' or 'prod' - automatically sets gateway URL */
+    environment?: ScaleMuleEnvironment;
+    /** Custom gateway URL (overrides environment preset) */
+    gatewayUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom storage adapter */
+    storage?: StorageAdapter;
+    /** Enable rate limit queue (automatically queues requests when rate limited) */
+    enableRateLimitQueue?: boolean;
+    /** Enable offline queue (queues requests when offline, syncs when back online) */
+    enableOfflineQueue?: boolean;
+}
+interface RequestOptions extends RequestInit {
+    /** Skip adding auth headers (for public endpoints) */
+    skipAuth?: boolean;
+    /** Custom timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts for transient failures (default: 2) */
+    retries?: number;
+    /** Skip retries */
+    skipRetry?: boolean;
+}
+/**
+ * ScaleMule API Client
+ *
+ * Handles all HTTP communication with the ScaleMule gateway.
+ */
+declare class ScaleMuleClient {
+    private apiKey;
+    private applicationId;
+    private gatewayUrl;
+    private debug;
+    private storage;
+    private sessionToken;
+    private userId;
+    private rateLimitQueue;
+    private offlineQueue;
+    private enableRateLimitQueue;
+    private enableOfflineQueue;
+    constructor(config: ClientConfig);
+    /**
+     * Sync offline queue when coming back online
+     */
+    private syncOfflineQueue;
+    /**
+     * Check if client is online
+     */
+    isOnline(): boolean;
+    /**
+     * Get number of pending offline requests
+     */
+    getOfflineQueueLength(): number;
+    /**
+     * Get number of pending rate-limited requests
+     */
+    getRateLimitQueueLength(): number;
+    /**
+     * Check if currently rate limited
+     */
+    isRateLimited(): boolean;
+    /**
+     * Get the gateway URL
+     */
+    getGatewayUrl(): string;
+    /**
+     * Get the application ID (required for realtime features)
+     */
+    getApplicationId(): string | null;
+    /**
+     * Initialize client by loading persisted session
+     */
+    initialize(): Promise<void>;
+    /**
+     * Set session after login
+     */
+    setSession(token: string, userId: string): Promise<void>;
+    /**
+     * Clear session on logout
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Get current session token
+     */
+    getSessionToken(): string | null;
+    /**
+     * Get current user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Check if client has an active session
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Build headers for a request
+     */
+    private buildHeaders;
+    /**
+     * Make an HTTP request to the ScaleMule API
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * GET request
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * POST request with JSON body
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PUT request with JSON body
+     */
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PATCH request with JSON body
+     */
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Upload a file using multipart/form-data
+     *
+     * Automatically includes Authorization: Bearer header for user identity.
+     * Supports progress callback via XMLHttpRequest when onProgress is provided.
+     */
+    upload<T>(path: string, file: File, additionalFields?: Record<string, string>, options?: RequestOptions & {
+        onProgress?: (progress: number) => void;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * Upload with progress using XMLHttpRequest (with retry)
+     */
+    private uploadWithProgress;
+    /**
+     * Single upload attempt with progress using XMLHttpRequest
+     */
+    private singleUploadWithProgress;
+}
+/**
+ * Create a new ScaleMule client instance
+ */
+declare function createClient(config: ClientConfig): ScaleMuleClient;
+
+export { type ClientConfig, type RequestOptions, ScaleMuleClient, type ScaleMuleEnvironment, createClient };