@payez/next-mvp 3.0.0

package/dist/lib/api-handler.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Unified API Handler for PayEz Next.js Applications
+ *
+ * Provides a single, comprehensive API handler with:
+ * - Coordinated token refresh with Redis locks
+ * - Role-based access control
+ * - Middleware queue support
+ * - Timeout handling
+ * - Standardized PayEz API response format
+ * - Client slug validation (security)
+ *
+ * @version 1.0.0
+ * @since Consolidated from website-membership simple-api-handler + MVP auth-handler
+ */
+import { NextRequest, NextResponse } from 'next/server';
+export interface ApiHandlerConfig {
+    /** Whether authentication is required (default: true) */
+    requireAuth?: boolean;
+    /** Roles required to access this endpoint */
+    requiredRoles?: string[];
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Validate client_slug in token matches expected (default: true) */
+    validateClientSlug?: boolean;
+}
+export interface ApiRequestContext {
+    requestId: string;
+    startTime: number;
+    endpoint: string;
+    method: string;
+    userId?: string;
+    sessionId?: string;
+    userAgent?: string;
+    ipAddress?: string;
+    params?: Record<string, string>;
+}
+export interface ApiAuthContext {
+    accessToken: string | null;
+    userId?: string;
+    roles: string[];
+    sessionId?: string;
+    tokenType: string;
+    refreshToken: string | null;
+}
+export interface ApiMiddleware {
+    name: string;
+    execute: (context: ApiRequestContext, config: ApiHandlerConfig) => Promise<void>;
+}
+export type ApiHandlerFunction<T = any> = (req: NextRequest, ctx: ApiRequestContext, auth: ApiAuthContext, responseBuilder: any) => Promise<T>;
+export declare class ApiResponseBuilder {
+    private context;
+    constructor(context: ApiRequestContext);
+    success<T>(data: T, meta?: {
+        operation?: string;
+        version?: string;
+        [key: string]: any;
+    }): {
+        success: true;
+        data: T;
+        message: string;
+        operation_code: string;
+        meta: any;
+        timestamp: string;
+        request_id: string;
+    };
+    error(code: string, message?: string, details?: Record<string, any>): {
+        success: false;
+        error: any;
+        meta: any;
+        timestamp: string;
+        request_id: string;
+    };
+}
+export declare class ApiHandler {
+    private config;
+    private middlewareQueue;
+    constructor(config?: ApiHandlerConfig);
+    /**
+     * Add middleware to the handler chain
+     */
+    use(middleware: ApiMiddleware): this;
+    /**
+     * Create the route handler
+     */
+    handle<T = any>(handler: ApiHandlerFunction<T>): (req: NextRequest) => Promise<NextResponse>;
+    private handleAuthentication;
+    private validateClientSlug;
+    private handleNoSessionToken;
+    private handleCoordinatedRefresh;
+    private waitForRefresh;
+    private createEmptyAuth;
+    private executeWithTimeout;
+    private successResponse;
+    private errorResponse;
+    private getStatusFromError;
+    private getErrorCode;
+}
+/**
+ * Create an API handler with the specified configuration
+ *
+ * @example
+ * ```typescript
+ * export const GET = createApiHandler({ requireAuth: true })
+ *   .handle(async (req, ctx, auth) => {
+ *     return { data: 'hello' };
+ *   });
+ * ```
+ */
+export declare function createApiHandler(config?: ApiHandlerConfig): ApiHandler;
+/**
+ * Pre-configured API handler presets for common use cases
+ */
+export declare const API_PRESETS: {
+    /** Public endpoint - no authentication required */
+    readonly PUBLIC: () => ApiHandler;
+    /** Authenticated endpoint - any logged-in user */
+    readonly AUTHENTICATED: () => ApiHandler;
+    /** User endpoint - requires payez_user or payez_admin role */
+    readonly USER: () => ApiHandler;
+    /** Admin endpoint - requires payez_admin role */
+    readonly ADMIN: () => ApiHandler;
+};
+export default createApiHandler;

package/dist/lib/api-handler.js

@@ -0,0 +1,478 @@
+"use strict";
+/**
+ * Unified API Handler for PayEz Next.js Applications
+ *
+ * Provides a single, comprehensive API handler with:
+ * - Coordinated token refresh with Redis locks
+ * - Role-based access control
+ * - Middleware queue support
+ * - Timeout handling
+ * - Standardized PayEz API response format
+ * - Client slug validation (security)
+ *
+ * @version 1.0.0
+ * @since Consolidated from website-membership simple-api-handler + MVP auth-handler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_PRESETS = exports.ApiHandler = exports.ApiResponseBuilder = void 0;
+exports.createApiHandler = createApiHandler;
+const server_1 = require("next/server");
+const nanoid_1 = require("nanoid");
+const session_store_1 = require("./session-store");
+const test_aware_get_token_1 = require("./test-aware-get-token");
+const internal_api_1 = require("./internal-api");
+// ============================================================================
+// API Response Builder (for backward compatibility)
+// ============================================================================
+class ApiResponseBuilder {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    success(data, meta) {
+        return {
+            success: true,
+            data,
+            message: meta?.operation ? `${meta.operation.replace(/-/g, ' ')} completed successfully` : 'Operation completed successfully',
+            operation_code: meta?.operation || 'unknown-operation',
+            meta: {
+                version: '1.0',
+                responseTime: Date.now() - this.context.startTime,
+                ...meta
+            },
+            timestamp: new Date().toISOString(),
+            request_id: this.context.requestId
+        };
+    }
+    error(code, message, details) {
+        return {
+            success: false,
+            error: {
+                code,
+                message: message || code,
+                details
+            },
+            meta: {
+                version: '1.0',
+                responseTime: Date.now() - this.context.startTime
+            },
+            timestamp: new Date().toISOString(),
+            request_id: this.context.requestId
+        };
+    }
+}
+exports.ApiResponseBuilder = ApiResponseBuilder;
+// ============================================================================
+// API Handler Class
+// ============================================================================
+class ApiHandler {
+    config;
+    middlewareQueue = [];
+    constructor(config = {}) {
+        this.config = {
+            requireAuth: config.requireAuth ?? true,
+            requiredRoles: config.requiredRoles ?? [],
+            timeout: config.timeout ?? 30000,
+            validateClientSlug: config.validateClientSlug ?? true,
+        };
+    }
+    /**
+     * Add middleware to the handler chain
+     */
+    use(middleware) {
+        this.middlewareQueue.push(middleware);
+        return this;
+    }
+    /**
+     * Create the route handler
+     */
+    handle(handler) {
+        return async (req) => {
+            const startTime = Date.now();
+            const requestId = (0, nanoid_1.nanoid)();
+            const ctx = {
+                requestId,
+                startTime,
+                endpoint: req.nextUrl.pathname,
+                method: req.method,
+                userAgent: req.headers.get('user-agent') || undefined,
+                ipAddress: req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip') || undefined,
+            };
+            try {
+                // Execute middleware chain
+                for (const middleware of this.middlewareQueue) {
+                    await middleware.execute(ctx, this.config);
+                }
+                // Handle authentication
+                const authResult = await this.handleAuthentication(req, ctx);
+                if (!authResult.success) {
+                    if (authResult.reason === 'REFRESH_IN_PROGRESS') {
+                        const response = this.errorResponse('SERVICE_UNAVAILABLE', 'Token refresh in progress', 503, requestId);
+                        response.headers.set('Retry-After', '1');
+                        return response;
+                    }
+                    if (this.config.requireAuth) {
+                        return this.errorResponse('UNAUTHORIZED', 'Authentication required', 401, requestId);
+                    }
+                }
+                const auth = authResult.auth || this.createEmptyAuth();
+                // Attach auth context to request for downstream use
+                if (auth.accessToken) {
+                    req.__authContext = { accessToken: auth.accessToken };
+                }
+                // Check roles
+                if (this.config.requiredRoles.length > 0 && auth) {
+                    const hasRequiredRole = this.config.requiredRoles.some(role => auth.roles.includes(role));
+                    if (!hasRequiredRole) {
+                        return this.errorResponse('FORBIDDEN', 'Insufficient permissions', 403, requestId);
+                    }
+                }
+                // Create response builder for backward compatibility
+                const responseBuilder = new ApiResponseBuilder(ctx);
+                // Execute handler with timeout
+                const result = await this.executeWithTimeout(handler(req, ctx, auth, responseBuilder), this.config.timeout);
+                return this.successResponse(result, requestId, ctx);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'Request timeout') {
+                    return this.errorResponse('TIMEOUT', 'Request timeout', 408, requestId);
+                }
+                const statusCode = error instanceof Error ? this.getStatusFromError(error) : 500;
+                const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+                return this.errorResponse(this.getErrorCode(statusCode), message, statusCode, requestId);
+            }
+        };
+    }
+    // ==========================================================================
+    // Authentication
+    // ==========================================================================
+    async handleAuthentication(req, ctx) {
+        try {
+            const token = await (0, test_aware_get_token_1.getTokenTestAware)(req);
+            if (!token) {
+                if (this.config.requireAuth) {
+                    return { success: false, reason: 'NO_TOKEN' };
+                }
+                return { success: true, auth: this.createEmptyAuth() };
+            }
+            // Client slug validation (security feature from auth-handler)
+            if (this.config.validateClientSlug) {
+                const validationResult = this.validateClientSlug(token);
+                if (!validationResult.valid) {
+                    return { success: false, reason: validationResult.reason };
+                }
+            }
+            // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+            const sessionToken = token.sessionToken || token.redisSessionId;
+            if (!sessionToken) {
+                return this.handleNoSessionToken(token, ctx);
+            }
+            // Get session with version for coordinated refresh
+            const sessionWithVersion = await (0, session_store_1.getSessionWithVersion)(sessionToken);
+            if (!sessionWithVersion) {
+                return { success: false, reason: 'SESSION_EXPIRED' };
+            }
+            const { session: sessionData } = sessionWithVersion;
+            let accessToken = sessionData.idpAccessToken || null;
+            let userRoles = Array.isArray(sessionData.roles) ? sessionData.roles : [];
+            // Merge roles from JWT token
+            try {
+                const tokenRoles = Array.isArray(token.roles) ? token.roles : [];
+                if (tokenRoles.length > 0) {
+                    userRoles = Array.from(new Set([...userRoles, ...tokenRoles]));
+                }
+            }
+            catch { /* ignore */ }
+            // Check if token needs refresh
+            const thresholdMs = 5 * 60 * 1000;
+            const expires = sessionData.idpAccessTokenExpires || 0;
+            const needsRefresh = !accessToken || (expires - Date.now()) <= thresholdMs;
+            if (needsRefresh) {
+                const refreshResult = await this.handleCoordinatedRefresh(req, token, sessionData, ctx);
+                if (refreshResult.blocked) {
+                    return { success: false, reason: 'REFRESH_IN_PROGRESS' };
+                }
+                if (refreshResult.accessToken) {
+                    accessToken = refreshResult.accessToken;
+                    if (refreshResult.roles) {
+                        userRoles = Array.from(new Set([...userRoles, ...refreshResult.roles]));
+                    }
+                }
+            }
+            if (!accessToken) {
+                return { success: false, reason: 'NO_ACCESS_TOKEN' };
+            }
+            ctx.userId = token.sub;
+            ctx.sessionId = sessionToken;
+            return {
+                success: true,
+                auth: {
+                    accessToken,
+                    userId: token.sub,
+                    roles: userRoles,
+                    sessionId: sessionToken,
+                    tokenType: 'bearer',
+                    refreshToken: sessionData?.refreshToken || null,
+                }
+            };
+        }
+        catch (error) {
+            return { success: false, reason: 'AUTH_ERROR' };
+        }
+    }
+    validateClientSlug(token) {
+        const expectedClientSlug = process.env.NEXT_PUBLIC_EXPECTED_CLIENT_SLUG;
+        // If not configured, skip validation (backward compat)
+        if (!expectedClientSlug) {
+            return { valid: true, reason: '' };
+        }
+        const tokenClientSlug = token.client_slug || token.clientSlug;
+        if (!tokenClientSlug) {
+            return { valid: false, reason: 'TOKEN_MISSING_CLIENT_SLUG' };
+        }
+        if (tokenClientSlug.toLowerCase() !== expectedClientSlug.toLowerCase()) {
+            return { valid: false, reason: 'TOKEN_CLIENT_MISMATCH' };
+        }
+        return { valid: true, reason: '' };
+    }
+    handleNoSessionToken(token, ctx) {
+        const allowTestFallback = process.env.TEST_MODE === 'true' || process.env.NODE_ENV === 'test';
+        if (allowTestFallback && token.accessToken) {
+            return {
+                success: true,
+                auth: {
+                    accessToken: token.accessToken,
+                    userId: token.sub,
+                    roles: token.roles || [],
+                    sessionId: undefined,
+                    tokenType: 'bearer',
+                    refreshToken: null,
+                }
+            };
+        }
+        if (this.config.requireAuth) {
+            return { success: false, reason: 'NO_SESSION_TOKEN' };
+        }
+        return { success: true, auth: this.createEmptyAuth() };
+    }
+    // ==========================================================================
+    // Coordinated Refresh
+    // ==========================================================================
+    async handleCoordinatedRefresh(req, token, sessionData, ctx) {
+        // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+        const sessionToken = token.sessionToken || token.redisSessionId;
+        const existingLock = await (0, session_store_1.checkRefreshLock)(sessionToken);
+        if (existingLock) {
+            // Wait for existing refresh to complete
+            const waitResult = await this.waitForRefresh(sessionToken, 10000);
+            if (waitResult.success) {
+                const refreshed = await (0, session_store_1.getSession)(sessionToken);
+                if (refreshed?.accessToken) {
+                    return {
+                        accessToken: refreshed.accessToken,
+                        roles: Array.isArray(refreshed.roles) ? refreshed.roles : [],
+                    };
+                }
+            }
+            return { blocked: true };
+        }
+        // Try to acquire lock
+        const lockResult = await (0, session_store_1.acquireRefreshLock)(sessionToken, ctx.requestId, 5000);
+        if (!lockResult.acquired || !lockResult.lockInfo) {
+            const waitResult = await this.waitForRefresh(sessionToken, 10000);
+            if (waitResult.success) {
+                const refreshed = await (0, session_store_1.getSession)(sessionToken);
+                if (refreshed?.accessToken) {
+                    return {
+                        accessToken: refreshed.accessToken,
+                        roles: Array.isArray(refreshed.roles) ? refreshed.roles : [],
+                    };
+                }
+            }
+            return { blocked: true };
+        }
+        try {
+            // Double-check if still needs refresh
+            const latest = await (0, session_store_1.getSession)(sessionToken);
+            const thresholdMs = 5 * 60 * 1000;
+            const stillNeeds = !latest?.accessToken || ((latest?.accessTokenExpires || 0) - Date.now()) <= thresholdMs;
+            if (!stillNeeds && latest?.accessToken) {
+                return {
+                    accessToken: latest.accessToken,
+                    roles: Array.isArray(latest.roles) ? latest.roles : [],
+                };
+            }
+            // Use centralized internal API helper for server-to-server refresh calls
+            const refreshResponse = await (0, internal_api_1.internalRefresh)(req.headers.get('cookie') || '', sessionToken, sessionData.idpRefreshToken, ctx.requestId);
+            if (!refreshResponse.ok) {
+                return {};
+            }
+            const refreshed = await (0, session_store_1.getSession)(sessionToken);
+            if (refreshed?.accessToken) {
+                return {
+                    accessToken: refreshed.accessToken,
+                    roles: Array.isArray(refreshed.roles) ? refreshed.roles : [],
+                };
+            }
+            return {};
+        }
+        finally {
+            await (0, session_store_1.releaseRefreshLock)(sessionToken, ctx.requestId, lockResult.lockInfo.lockVersion);
+        }
+    }
+    async waitForRefresh(sessionToken, maxWaitMs) {
+        const startTime = Date.now();
+        const pollInterval = 100;
+        while (Date.now() - startTime < maxWaitMs) {
+            const lockExists = await (0, session_store_1.checkRefreshLock)(sessionToken);
+            if (!lockExists) {
+                const session = await (0, session_store_1.getSession)(sessionToken);
+                if (session?.accessToken) {
+                    const expires = session.accessTokenExpires || 0;
+                    if ((expires - Date.now()) > (5 * 60 * 1000)) {
+                        return { success: true };
+                    }
+                }
+                return { success: false };
+            }
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+        return { success: false };
+    }
+    // ==========================================================================
+    // Response Helpers
+    // ==========================================================================
+    createEmptyAuth() {
+        return {
+            accessToken: null,
+            roles: [],
+            tokenType: 'bearer',
+            refreshToken: null,
+        };
+    }
+    async executeWithTimeout(promise, timeoutMs) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('Request timeout')), timeoutMs);
+        });
+        return Promise.race([promise, timeoutPromise]);
+    }
+    successResponse(data, requestId, ctx) {
+        // Pass through Response objects unchanged
+        if (data instanceof Response) {
+            return data;
+        }
+        // Handle nested success/error flags
+        if (data && typeof data === 'object') {
+            if (Object.prototype.hasOwnProperty.call(data, 'success')) {
+                if (data.success === false) {
+                    const msg = data.error?.message || data.message || 'Upstream service error';
+                    const code = data.error?.code || 'UPSTREAM_SERVICE_ERROR';
+                    return this.errorResponse(code, msg, 400, requestId);
+                }
+            }
+        }
+        return server_1.NextResponse.json({
+            success: true,
+            data,
+            message: 'Operation completed successfully',
+            operation_code: 'api_handler_operation',
+            timestamp: new Date().toISOString(),
+            request_id: requestId,
+            meta: {
+                version: '1.0',
+                responseTime: Date.now() - ctx.startTime,
+            }
+        }, { status: 200 });
+    }
+    errorResponse(code, message, status, requestId) {
+        const now = new Date().toISOString();
+        return server_1.NextResponse.json({
+            success: false,
+            message,
+            operation_code: 'api_handler_error',
+            timestamp: now,
+            request_id: requestId,
+            error: {
+                code,
+                message,
+                support: { request_id: requestId, timestamp: now }
+            },
+            meta: { version: '1.0' }
+        }, { status });
+    }
+    getStatusFromError(error) {
+        const msg = error.message.toLowerCase();
+        if (msg.includes('unauthorized'))
+            return 401;
+        if (msg.includes('forbidden') || msg.includes('insufficient permissions'))
+            return 403;
+        if (msg.includes('not found'))
+            return 404;
+        if (msg.includes('timeout'))
+            return 408;
+        if (msg.includes('rate limit'))
+            return 429;
+        if (msg.includes('bad gateway') || msg.includes('upstream'))
+            return 502;
+        if (msg.includes('service unavailable'))
+            return 503;
+        return 500;
+    }
+    getErrorCode(status) {
+        switch (status) {
+            case 400: return 'BAD_REQUEST';
+            case 401: return 'UNAUTHORIZED';
+            case 403: return 'FORBIDDEN';
+            case 404: return 'NOT_FOUND';
+            case 408: return 'TIMEOUT';
+            case 429: return 'RATE_LIMIT_EXCEEDED';
+            case 502: return 'BAD_GATEWAY';
+            case 503: return 'SERVICE_UNAVAILABLE';
+            default: return 'INTERNAL_SERVER_ERROR';
+        }
+    }
+}
+exports.ApiHandler = ApiHandler;
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create an API handler with the specified configuration
+ *
+ * @example
+ * ```typescript
+ * export const GET = createApiHandler({ requireAuth: true })
+ *   .handle(async (req, ctx, auth) => {
+ *     return { data: 'hello' };
+ *   });
+ * ```
+ */
+function createApiHandler(config = {}) {
+    return new ApiHandler(config);
+}
+// ============================================================================
+// Pre-configured Presets
+// ============================================================================
+/**
+ * Pre-configured API handler presets for common use cases
+ */
+exports.API_PRESETS = {
+    /** Public endpoint - no authentication required */
+    PUBLIC: () => createApiHandler({ requireAuth: false, validateClientSlug: false }),
+    /** Authenticated endpoint - any logged-in user */
+    AUTHENTICATED: () => createApiHandler({ requireAuth: true }),
+    /** User endpoint - requires payez_user or payez_admin role */
+    USER: () => createApiHandler({
+        requireAuth: true,
+        requiredRoles: ['payez_user', 'payez_admin'],
+    }),
+    /** Admin endpoint - requires payez_admin role */
+    ADMIN: () => createApiHandler({
+        requireAuth: true,
+        requiredRoles: ['payez_admin'],
+    }),
+};
+// ============================================================================
+// Default Export
+// ============================================================================
+exports.default = createApiHandler;

package/dist/lib/app-slug.d.ts

@@ -0,0 +1,95 @@
+/**
+ * App Slug Utility for `@payez/next-mvp`
+ *
+ * Provides app-specific namespacing for Redis keys and cookies to prevent
+ * collisions when multiple MVP-based apps run on the same host (e.g., localhost).
+ *
+ * The slug is derived from:
+ * 1. APP_SLUG environment variable (preferred)
+ * 2. CLIENT_ID environment variable (fallback)
+ * 3. 'payez' (default fallback)
+ */
+/**
+ * Gets the app slug for namespacing.
+ * Caches the result for performance.
+ */
+export declare function getAppSlug(): string;
+/**
+ * Clears the cached slug (useful for testing).
+ */
+export declare function clearSlugCache(): void;
+/**
+ * Gets the prefix for session keys.
+ * Format: {slug}:sess:
+ */
+export declare function getSessionPrefix(): string;
+/**
+ * Gets the prefix for anonymous session keys.
+ * Format: {slug}:anon:
+ */
+export declare function getAnonPrefix(): string;
+/**
+ * Gets the prefix for refresh lock keys.
+ * Format: {slug}:refresh_lock:
+ */
+export declare function getRefreshLockPrefix(): string;
+/**
+ * THE session cookie name - SINGLE SOURCE OF TRUTH.
+ *
+ * This is used by:
+ * - auth-options.ts (cookies.sessionToken.name)
+ * - getToken() calls (cookieName parameter)
+ * - getJwtCookieName() (alias for consistency)
+ *
+ * Format: {slug}.session-token
+ */
+export declare function getSessionCookieName(): string;
+/**
+ * Gets the JWT cookie name for getToken() calls.
+ *
+ * CRITICAL: This MUST match what auth-options.ts configures:
+ * - Production: __Secure-{slug}.session-token
+ * - Development: {slug}.session-token
+ *
+ * This is the cookie name that getToken() should use to READ the JWT.
+ */
+export declare function getJwtCookieName(): string;
+/**
+ * Validates that cookie names are consistent with auth-options.ts.
+ * Call this at startup to catch mismatches early.
+ */
+export declare function validateCookieNameConsistency(): void;
+/**
+ * Gets the __Secure- prefixed cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getSessionCookieName().
+ * NextAuth does NOT automatically use this prefix.
+ *
+ * Format: __Secure-{slug}.session-token
+ */
+export declare function getSecureSessionCookieName(): string;
+/**
+ * Gets the anonymous session cookie name.
+ * Format: {slug}_anon_id
+ */
+export declare function getAnonCookieName(): string;
+/**
+ * Gets the CSRF token cookie name.
+ * Format: {slug}.csrf-token
+ */
+export declare function getCsrfCookieName(): string;
+/**
+ * Gets the __Host- prefixed CSRF cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getCsrfCookieName().
+ *
+ * Format: __Host-{slug}.csrf-token
+ */
+export declare function getSecureCsrfCookieName(): string;
+/**
+ * Gets the callback URL cookie name.
+ * Format: {slug}.callback-url
+ */
+export declare function getCallbackUrlCookieName(): string;