@payez/next-mvp 4.0.1 → 4.0.2

package/dist/lib/token-lifecycle.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * Token Lifecycle Management for @payez/next-mvp
+ *
+ * Ensures tokens are fresh before making API calls.
+ * Checks expiration and triggers refresh if needed.
+ *
+ * Pattern: Check first, refresh if needed, fail gracefully if refresh fails.
+ *
+ * HANDLES CONCURRENT REFRESH: When multiple API calls arrive simultaneously
+ * with expired tokens, only one will actually perform the refresh. Others
+ * receive 409 (conflict) and wait for the refresh to complete, then use
+ * the freshly refreshed tokens.
+ *
+ * REQUIRED: Your app must expose the refresh route:
+ * ```typescript
+ * // app/api/auth/refresh/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/refresh';
+ * ```
+ *
+ * @version 2.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureFreshToken = ensureFreshToken;
+exports.getFreshAuthHeader = getFreshAuthHeader;
+const session_store_1 = require("./session-store");
+const auth_1 = require("../server/auth");
+// 5 minute threshold for "needs refresh" - matches refresh handler pattern
+const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+// Concurrent refresh handling configuration
+const CONCURRENT_REFRESH_POLL_INTERVAL_MS = 200; // How often to poll session during concurrent refresh
+const CONCURRENT_REFRESH_MAX_WAIT_MS = 8000; // Max time to wait for concurrent refresh to complete
+const REFRESH_RETRY_DELAY_MS = 500; // Delay before retrying after failed concurrent refresh
+const KEY_PROPAGATION_DELAY_MS = 150; // Delay after refresh to allow JWKS cache updates in downstream services
+/**
+ * Check if token needs refresh based on expiration time
+ */
+function needsRefresh(accessTokenExpires) {
+    if (!accessTokenExpires)
+        return true;
+    const timeUntilExpiry = accessTokenExpires - Date.now();
+    return timeUntilExpiry <= REFRESH_THRESHOLD_MS;
+}
+/**
+ * Helper to delay execution
+ */
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Wait for a concurrent refresh to complete by polling the session.
+ * Returns true if session becomes fresh, false if timeout reached.
+ */
+async function waitForConcurrentRefresh(sessionToken, maxWaitMs = CONCURRENT_REFRESH_MAX_WAIT_MS) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWaitMs) {
+        await delay(CONCURRENT_REFRESH_POLL_INTERVAL_MS);
+        const sessionData = await (0, session_store_1.getSession)(sessionToken);
+        if (!sessionData) {
+            return { success: false };
+        }
+        // Check if token is now fresh
+        if (!needsRefresh(sessionData.idpAccessTokenExpires)) {
+            return { success: true, sessionData };
+        }
+        // Check if session has a new access token (even if still within threshold)
+        if (sessionData.idpAccessToken && sessionData.idpAccessTokenExpires &&
+            sessionData.idpAccessTokenExpires > Date.now()) {
+            return { success: true, sessionData };
+        }
+    }
+    return { success: false };
+}
+/**
+ * Get the internal API URL for making internal service calls.
+ * INTERNAL_API_URL is REQUIRED - no fallbacks.
+ */
+function getInternalApiUrl(request) {
+    const internalUrl = process.env.INTERNAL_API_URL;
+    if (!internalUrl) {
+        throw new Error('[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED. ' +
+            'Set it to this app\'s internal K8s service URL (e.g., http://myapp.namespace.svc.cluster.local:80) ' +
+            'or http://localhost:3000 for local development.');
+    }
+    return internalUrl;
+}
+/**
+ * Trigger a token refresh via the refresh API endpoint.
+ *
+ * HANDLES CONCURRENT REFRESH (409):
+ * When another request is already refreshing the token, this function
+ * waits for that refresh to complete instead of failing immediately.
+ * This prevents race conditions where multiple parallel API calls
+ * could cause unnecessary refresh failures.
+ *
+ * TERMINAL STATES:
+ * Returns { success: false, terminal: true } when the session cannot be
+ * recovered (e.g., no refresh token). Callers should redirect to login.
+ */
+async function triggerRefresh(request, sessionToken, retryCount = 0) {
+    const maxRetries = 2;
+    try {
+        const baseUrl = getInternalApiUrl(request);
+        const requestId = `refresh_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const response = await fetch(`${baseUrl}/api/auth/refresh`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Cookie': request.headers.get('cookie') || '',
+                'X-Session-Token': sessionToken,
+                'X-Request-Id': requestId,
+            },
+        });
+        // Handle 409 Conflict - another refresh is in progress
+        if (response.status === 409) {
+            // Wait for the concurrent refresh to complete
+            const waitResult = await waitForConcurrentRefresh(sessionToken);
+            if (waitResult.success) {
+                return { success: true };
+            }
+            // Concurrent refresh didn't produce a fresh token - try again if we have retries left
+            if (retryCount < maxRetries) {
+                await delay(REFRESH_RETRY_DELAY_MS);
+                return triggerRefresh(request, sessionToken, retryCount + 1);
+            }
+            return { success: false };
+        }
+        // Handle other non-OK responses
+        if (!response.ok) {
+            // Parse response body to check for terminal errors
+            let responseData = {};
+            try {
+                responseData = await response.json();
+            }
+            catch {
+                // Ignore parse errors
+            }
+            // Log the failure for debugging
+            console.warn('[TOKEN_LIFECYCLE] Refresh request failed:', {
+                status: response.status,
+                statusText: response.statusText,
+                baseUrl,
+                retryCount,
+                code: responseData.code,
+                terminal: responseData.terminal
+            });
+            // CHECK FOR TERMINAL STATE: No refresh token = session is dead
+            // Don't retry - user must re-authenticate
+            if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
+                console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
+                return { success: false, terminal: true, code: responseData.code };
+            }
+            // For other 401s, check if maybe session was refreshed by another request
+            if (response.status === 401 && retryCount < maxRetries) {
+                await delay(REFRESH_RETRY_DELAY_MS);
+                const sessionData = await (0, session_store_1.getSession)(sessionToken);
+                if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
+                    return { success: true };
+                }
+            }
+            return { success: false, code: responseData.code };
+        }
+        const result = await response.json();
+        const success = result.refreshed === true || result.reason === 'already_fresh';
+        return { success };
+    }
+    catch (error) {
+        // Log network errors for debugging
+        console.error('[TOKEN_LIFECYCLE] Refresh network error:', {
+            error: error instanceof Error ? error.message : String(error),
+            retryCount
+        });
+        // On network error, check if maybe another request refreshed the token
+        if (retryCount < maxRetries) {
+            await delay(REFRESH_RETRY_DELAY_MS);
+            const sessionData = await (0, session_store_1.getSession)(sessionToken);
+            if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
+                return { success: true };
+            }
+        }
+        return { success: false };
+    }
+}
+/**
+ * Ensures we have a fresh access token before making API calls.
+ *
+ * This utility checks token expiration and triggers a refresh if needed,
+ * preventing 401 errors from expired tokens being sent to downstream APIs.
+ *
+ * @param request - The incoming NextRequest
+ * @returns TokenResult with accessToken and sessionData, or TokenError
+ *
+ * @example
+ * ```typescript
+ * import { ensureFreshToken } from '@payez/next-mvp/lib/token-lifecycle';
+ *
+ * export async function GET(request: NextRequest) {
+ *   const tokenResult = await ensureFreshToken(request);
+ *   if (!tokenResult.success) {
+ *     return NextResponse.json({ error: tokenResult.error }, { status: 401 });
+ *   }
+ *
+ *   // Use tokenResult.accessToken for downstream API calls
+ *   const response = await fetch('https://api.example.com/data', {
+ *     headers: { 'Authorization': `Bearer ${tokenResult.accessToken}` }
+ *   });
+ * }
+ * ```
+ */
+async function ensureFreshToken(request) {
+    try {
+        // 1. Get Better Auth session to extract sessionToken
+        const betterAuthSession = await (0, auth_1.getSession)(request);
+        if (!betterAuthSession?.session?.token) {
+            console.warn('[TOKEN_LIFECYCLE] NO_SESSION - Better Auth session not found');
+            return {
+                success: false,
+                error: 'NO_SESSION',
+                message: 'No session available',
+            };
+        }
+        const sessionToken = betterAuthSession.session.token;
+        // 2. Get session data from Redis
+        let sessionData = await (0, session_store_1.getSession)(sessionToken);
+        if (!sessionData) {
+            return {
+                success: false,
+                error: 'NO_SESSION',
+                message: 'Session expired or not found',
+            };
+        }
+        // DEBUG: Log session data before refresh check
+        const tokenExpiresStr = sessionData.idpAccessTokenExpires
+            ? new Date(sessionData.idpAccessTokenExpires).toISOString()
+            : 'undefined';
+        let needsRefreshNow = needsRefresh(sessionData.idpAccessTokenExpires);
+        // VALIDATION: Check if the actual JWT token's exp matches what Redis claims
+        // This catches cases where accessTokenExpires was updated but accessToken wasn't
+        let tokenMismatch = false;
+        if (sessionData.idpAccessToken && !needsRefreshNow) {
+            try {
+                const tokenParts = sessionData.idpAccessToken.split('.');
+                if (tokenParts.length === 3) {
+                    const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64url').toString());
+                    const jwtExpMs = (payload.exp || 0) * 1000;
+                    const now = Date.now();
+                    // If the JWT is actually expired, force a refresh regardless of what Redis says
+                    if (jwtExpMs < now) {
+                        console.warn('[TOKEN_LIFECYCLE] Token mismatch detected! JWT expired but Redis claims valid', {
+                            jwtExp: new Date(jwtExpMs).toISOString(),
+                            redisAccessTokenExpires: tokenExpiresStr,
+                            now: new Date(now).toISOString(),
+                            mismatchMs: sessionData.idpAccessTokenExpires ? sessionData.idpAccessTokenExpires - jwtExpMs : 'N/A'
+                        });
+                        needsRefreshNow = true;
+                        tokenMismatch = true;
+                    }
+                }
+            }
+            catch (e) {
+                // If we can't decode, proceed with normal logic
+                console.warn('[TOKEN_LIFECYCLE] Could not validate JWT exp claim:', e);
+            }
+        }
+        console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
+            sessionToken: sessionToken.substring(0, 8) + '...',
+            accessTokenExpires: tokenExpiresStr,
+            now: new Date().toISOString(),
+            needsRefresh: needsRefreshNow,
+            tokenMismatch,
+            hasRefreshToken: !!sessionData.idpRefreshToken
+        });
+        // 3. Check if token needs refresh
+        if (needsRefreshNow) {
+            // 4. Trigger refresh
+            console.log('[TOKEN_LIFECYCLE] Triggering refresh...');
+            const refreshResult = await triggerRefresh(request, sessionToken);
+            if (!refreshResult.success) {
+                // Check for terminal state - session cannot be recovered
+                if (refreshResult.terminal) {
+                    console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired with no refresh token - redirect to login');
+                    return {
+                        success: false,
+                        error: 'SESSION_EXPIRED_NO_REFRESH',
+                        message: 'Session expired. Please sign in again.',
+                        terminal: true,
+                    };
+                }
+                console.warn('[TOKEN_LIFECYCLE] Refresh failed');
+                return {
+                    success: false,
+                    error: 'REFRESH_FAILED',
+                    message: 'Token refresh failed',
+                };
+            }
+            // 5. Re-fetch session data after refresh
+            sessionData = await (0, session_store_1.getSession)(sessionToken);
+            console.log('[TOKEN_LIFECYCLE] After refresh:', {
+                hasAccessToken: !!sessionData?.idpAccessToken,
+                newAccessTokenExpires: sessionData?.idpAccessTokenExpires
+                    ? new Date(sessionData.idpAccessTokenExpires).toISOString()
+                    : 'undefined'
+            });
+            if (!sessionData?.idpAccessToken) {
+                return {
+                    success: false,
+                    error: 'REFRESH_FAILED',
+                    message: 'No access token after refresh',
+                };
+            }
+            // 5.5. Key propagation delay - allow downstream services (like Vibe) to cache new JWKS
+            // This is critical when IDP rotates signing keys - the new token's kid may not be
+            // immediately available in Vibe's JWKS cache
+            await delay(KEY_PROPAGATION_DELAY_MS);
+        }
+        // 6. Validate we have a token
+        if (!sessionData.idpAccessToken) {
+            return {
+                success: false,
+                error: 'NO_TOKEN',
+                message: 'No access token available',
+            };
+        }
+        return {
+            success: true,
+            accessToken: sessionData.idpAccessToken,
+            sessionData,
+        };
+    }
+    catch (error) {
+        console.error('[TOKEN_LIFECYCLE] Error:', error);
+        return {
+            success: false,
+            error: 'NO_SESSION',
+            message: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Get authorization header from fresh token.
+ * Convenience wrapper for API routes.
+ *
+ * @param request - The incoming NextRequest
+ * @returns Authorization header string or null if token unavailable
+ *
+ * @example
+ * ```typescript
+ * const authHeader = await getFreshAuthHeader(request);
+ * if (!authHeader) {
+ *   return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+ * }
+ * ```
+ */
+async function getFreshAuthHeader(request) {
+    const result = await ensureFreshToken(request);
+    if (!result.success) {
+        return null;
+    }
+    return `Bearer ${result.accessToken}`;
+}

package/dist/lib/types/api-responses.d.ts

@@ -0,0 +1,128 @@
+/**
+ * BASE STANDARDIZED RESPONSE FORMAT
+ * This is THE ONLY acceptable response format from our APIs
+ */
+export interface StandardizedApiResponse<TData = unknown> {
+    /** REQUIRED: Operation success status */
+    success: true;
+    /** REQUIRED: The actual data payload */
+    data: TData;
+    /** REQUIRED: Human-readable success message */
+    message: string;
+    /** REQUIRED: Unique operation code for tracking */
+    operation_code: string;
+    /** Optional: Server timestamp */
+    timestamp?: string;
+    /** Optional: Request ID for tracing */
+    request_id?: string;
+}
+/**
+ * STANDARDIZED ERROR RESPONSE FORMAT
+ * This is THE ONLY acceptable error format from our APIs
+ */
+export interface StandardizedErrorResponse {
+    /** REQUIRED: Always false for errors */
+    success: false;
+    /** REQUIRED: Standard error code */
+    error_code: string;
+    /** REQUIRED: Human-readable error message */
+    message: string;
+    /** REQUIRED: Operation that failed */
+    operation: string;
+    /** Optional: Additional error details - can be any structure from IDP */
+    details?: unknown;
+    /** Optional: Validation errors */
+    validation_errors?: Record<string, string[]>;
+    /** Optional: Server timestamp */
+    timestamp?: string;
+    /** Optional: Request ID for tracing */
+    request_id?: string;
+}
+/**
+ * STANDARDIZED PAGINATED RESPONSE FORMAT
+ * For endpoints that return paged data
+ */
+export interface StandardizedPagedResponse<TData = unknown> {
+    /** REQUIRED: Always true for success */
+    success: true;
+    /** REQUIRED: Array of data items */
+    data: TData[];
+    /** REQUIRED: Human-readable success message */
+    message: string;
+    /** REQUIRED: Unique operation code */
+    operation_code: string;
+    /** REQUIRED: Pagination metadata */
+    pagination: {
+        /** Current page number (1-based) */
+        current_page: number;
+        /** Total number of pages */
+        total_pages: number;
+        /** Number of items per page */
+        page_size: number;
+        /** Total number of items across all pages */
+        total_items: number;
+        /** True if there are more pages after current */
+        has_next_page: boolean;
+        /** True if there are pages before current */
+        has_previous_page: boolean;
+    };
+    /** Optional: Server timestamp */
+    timestamp?: string;
+    /** Optional: Request ID for tracing */
+    request_id?: string;
+}
+/**
+ * VALIDATION ERROR RESPONSE FORMAT
+ * For input validation failures
+ */
+export interface StandardizedValidationResponse {
+    /** REQUIRED: Always false for validation errors */
+    success: false;
+    /** REQUIRED: Always 'VALIDATION_ERROR' */
+    error_code: 'VALIDATION_ERROR';
+    /** REQUIRED: Summary message */
+    message: string;
+    /** REQUIRED: Operation that failed */
+    operation: string;
+    /** REQUIRED: Field-specific validation errors */
+    payload: {
+        /** Field name mapped to array of error messages */
+        validation_errors: Record<string, string[]>;
+        /** The invalid value that caused the error */
+        invalid_value?: unknown;
+        /** The field that caused the primary error */
+        primary_field?: string;
+    };
+}
+/** ALL POSSIBLE STANDARDIZED RESPONSES */
+export type StandardizedResponse<TData = unknown> = StandardizedApiResponse<TData> | StandardizedPagedResponse<TData> | StandardizedErrorResponse | StandardizedValidationResponse;
+/**
+ * Type guard to check if response is a success response
+ * THROWS if response doesn't match standardized format
+ */
+export declare function isSuccessResponse<TData = unknown>(response: unknown): response is StandardizedApiResponse<TData>;
+/**
+ * Type guard to check if response is a paged success response
+ * THROWS if response doesn't match standardized format
+ */
+export declare function isPagedResponse<TData = unknown>(response: unknown): response is StandardizedPagedResponse<TData>;
+/**
+ * Type guard to check if response is an error response
+ * THROWS if response doesn't match standardized format
+ */
+export declare function isErrorResponse(response: unknown): response is StandardizedErrorResponse;
+/**
+ * Type guard to check if response is a validation error
+ * THROWS if response doesn't match standardized format
+ */
+export declare function isValidationErrorResponse(response: unknown): response is StandardizedValidationResponse;
+/**
+ * VALIDATES AND NORMALIZES API RESPONSES
+ * This function BREAKS THE BUILD if responses don't match our standard
+ * NO EXCEPTIONS - ZERO TOLERANCE FOR BAD RESPONSES
+ */
+export declare function validateStandardizedResponse<TData = unknown>(response: unknown, endpoint?: string): StandardizedResponse<TData>;
+/** Extract the data type from a standardized response */
+export type ExtractResponseData<T> = T extends StandardizedApiResponse<infer U> ? U : T extends StandardizedPagedResponse<infer U> ? U[] : never;
+/** Extract the error code from an error response */
+export type ExtractErrorCode<T> = T extends StandardizedErrorResponse ? T['error_code'] : T extends StandardizedValidationResponse ? T['error_code'] : never;

package/dist/lib/types/api-responses.js

@@ -0,0 +1,171 @@
+"use strict";
+// ========================================================================================
+// BULLETPROOF API RESPONSE TYPES - ENFORCES STANDARDIZED FORMAT
+// ========================================================================================
+// These types ENFORCE the standardized response format from our Identity API
+// If the API doesn't return this exact structure, TypeScript will break the build
+// NO MORE data.data.data.data NONSENSE - EVER!
+// ========================================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSuccessResponse = isSuccessResponse;
+exports.isPagedResponse = isPagedResponse;
+exports.isErrorResponse = isErrorResponse;
+exports.isValidationErrorResponse = isValidationErrorResponse;
+exports.validateStandardizedResponse = validateStandardizedResponse;
+// ========================================================================================
+// TYPE GUARDS FOR RUNTIME VALIDATION
+// ========================================================================================
+/**
+ * Type guard to check if response is a success response
+ * THROWS if response doesn't match standardized format
+ */
+function isSuccessResponse(response) {
+    if (!response || typeof response !== 'object') {
+        throw new Error('INVALID_API_RESPONSE: Response is not an object');
+    }
+    const r = response;
+    if (r.success !== true) {
+        return false; // This is an error response, not invalid format
+    }
+    // SUCCESS RESPONSE VALIDATION - BE STRICT!
+    if (!('data' in r)) {
+        throw new Error('INVALID_API_RESPONSE: Success response missing required "data" field');
+    }
+    if (!('message' in r) || typeof r.message !== 'string') {
+        throw new Error('INVALID_API_RESPONSE: Success response missing required "message" field');
+    }
+    if (!('operation_code' in r) || typeof r.operation_code !== 'string') {
+        throw new Error('INVALID_API_RESPONSE: Success response missing required "operation_code" field');
+    }
+    return true;
+}
+/**
+ * Type guard to check if response is a paged success response
+ * THROWS if response doesn't match standardized format
+ */
+function isPagedResponse(response) {
+    if (!isSuccessResponse(response)) {
+        return false;
+    }
+    const r = response;
+    // Check if it has pagination metadata
+    if (!('pagination' in r) || typeof r.pagination !== 'object') {
+        return false;
+    }
+    const pagination = r.pagination;
+    const requiredPaginationFields = [
+        'current_page', 'total_pages', 'page_size', 'total_items',
+        'has_next_page', 'has_previous_page'
+    ];
+    for (const field of requiredPaginationFields) {
+        if (!(field in pagination)) {
+            throw new Error(`INVALID_API_RESPONSE: Paged response missing required pagination.${field}`);
+        }
+    }
+    // Ensure data is an array for paged responses
+    if (!Array.isArray(r.data)) {
+        throw new Error('INVALID_API_RESPONSE: Paged response data must be an array');
+    }
+    return true;
+}
+/**
+ * Type guard to check if response is an error response
+ * THROWS if response doesn't match standardized format
+ */
+function isErrorResponse(response) {
+    if (!response || typeof response !== 'object') {
+        throw new Error('INVALID_API_RESPONSE: Response is not an object');
+    }
+    const r = response;
+    if (r.success !== false) {
+        return false; // This is a success response, not invalid format
+    }
+    // ERROR RESPONSE VALIDATION - BE STRICT!
+    if (!('error_code' in r) || typeof r.error_code !== 'string') {
+        throw new Error('INVALID_API_RESPONSE: Error response missing required "error_code" field');
+    }
+    if (!('message' in r) || typeof r.message !== 'string') {
+        throw new Error('INVALID_API_RESPONSE: Error response missing required "message" field');
+    }
+    if (!('operation' in r) || typeof r.operation !== 'string') {
+        throw new Error('INVALID_API_RESPONSE: Error response missing required "operation" field');
+    }
+    return true;
+}
+/**
+ * Type guard to check if response is a validation error
+ * THROWS if response doesn't match standardized format
+ */
+function isValidationErrorResponse(response) {
+    if (!isErrorResponse(response)) {
+        return false;
+    }
+    const r = response;
+    if (r.error_code !== 'VALIDATION_ERROR') {
+        return false;
+    }
+    // VALIDATION ERROR RESPONSE VALIDATION - BE STRICT!
+    if (!('payload' in r) || typeof r.payload !== 'object') {
+        throw new Error('INVALID_API_RESPONSE: Validation error missing required "payload" field');
+    }
+    if (!('validation_errors' in r.payload) || typeof r.payload.validation_errors !== 'object') {
+        throw new Error('INVALID_API_RESPONSE: Validation error missing required "payload.validation_errors" field');
+    }
+    return true;
+}
+// ========================================================================================
+// RESPONSE VALIDATOR - ENFORCES COMPLIANCE AT RUNTIME
+// ========================================================================================
+/**
+ * VALIDATES AND NORMALIZES API RESPONSES
+ * This function BREAKS THE BUILD if responses don't match our standard
+ * NO EXCEPTIONS - ZERO TOLERANCE FOR BAD RESPONSES
+ */
+function validateStandardizedResponse(response, endpoint) {
+    const context = endpoint ? ` for endpoint: ${endpoint}` : '';
+    try {
+        // First, basic object validation
+        if (!response || typeof response !== 'object') {
+            throw new Error(`CRITICAL_API_ERROR: Invalid response object${context}`);
+        }
+        const r = response;
+        // Check for success field (REQUIRED)
+        if (!('success' in r) || typeof r.success !== 'boolean') {
+            throw new Error(`CRITICAL_API_ERROR: Response missing required boolean "success" field${context}`);
+        }
+        // Route to appropriate validator based on success status
+        if (r.success === true) {
+            // Check if it's a paged response
+            if ('pagination' in r) {
+                if (isPagedResponse(response)) {
+                    return response;
+                }
+            }
+            else {
+                if (isSuccessResponse(response)) {
+                    return response;
+                }
+            }
+        }
+        else if (r.success === false) {
+            // Check if it's a validation error
+            if (r.error_code === 'VALIDATION_ERROR') {
+                if (isValidationErrorResponse(response)) {
+                    return response;
+                }
+            }
+            else {
+                if (isErrorResponse(response)) {
+                    return response;
+                }
+            }
+        }
+        // If we reach here, the response format is invalid
+        throw new Error(`CRITICAL_API_ERROR: Response format validation failed${context}. Response: ${JSON.stringify(response, null, 2)}`);
+    }
+    catch (error) {
+        // Re-throw validation errors with context
+        const errorMessage = error instanceof Error ? error.message : 'Unknown validation error';
+        throw new Error(`${errorMessage}${context}`);
+    }
+}