import { NextRequest, NextResponse } from 'next/server';
import { ApiKeyAuth } from './auth';
interface SessionAuth {
    userId: string;
    scopes: string[];
    flags: import('../entities/types').UserFlag[];
    isSession: true;
}
type Auth = ApiKeyAuth | SessionAuth;
/**
 * Validates authentication using session or API key
 * Prefers session auth if available, falls back to API key
 */
export declare function validateAndAuthenticateRequest(request: NextRequest): Promise<{
    auth: Auth;
    rateLimitResponse?: NextResponse;
}>;
/**
 * Valida la API key y aplica rate limiting
 * Esta función debe ser llamada al inicio de cada endpoint API v1
 */
export declare function validateAndAuthenticateApiRequest(request: NextRequest): Promise<{
    auth: ApiKeyAuth;
    rateLimitResponse?: NextResponse;
}>;
/**
 * Extrae la información de autenticación API de los headers de la request
 * @deprecated Use validateAndAuthenticateApiRequest instead
 */
export declare function getApiAuth(request: NextRequest): ApiKeyAuth;
/**
 * Verifica que la autenticación tenga el scope requerido
 * Retorna un NextResponse de error si no tiene permisos, null si está autorizado
 */
export declare function checkScope(auth: Auth, requiredScope: string): NextResponse | null;
/**
 * Crea una respuesta exitosa estandarizada para la API
 */
export declare function createApiResponse<T>(data: T, responseMeta?: Record<string, unknown>, status?: number): NextResponse<{
    success: boolean;
    data: T;
    info: {
        timestamp: string;
    };
}>;
/**
 * Crea una respuesta de error estandarizada para la API
 */
export declare function createApiError(message: string, status?: number, details?: unknown, code?: string): NextResponse<{
    success: boolean;
    error: string;
    code: string;
    details: unknown;
    info: {
        timestamp: string;
    };
}>;
/**
 * Parsea y valida parámetros de paginación
 */
export declare function parsePaginationParams(request: NextRequest): {
    page: number;
    limit: number;
    offset: number;
};
/**
 * Crea metadatos de paginación para respuestas
 */
export declare function createPaginationMeta(page: number, limit: number, total: number): {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPrevPage: boolean;
};
/**
 * Registra el uso de la API para auditoría
 */
export declare function logApiUsage(auth: ApiKeyAuth, request: NextRequest, statusCode: number, responseTime?: number, requestBody?: unknown): Promise<void>;
/**
 * Wrapper para endpoints que agrega logging automático
 */
export declare function withApiLogging<T extends unknown[]>(handler: (request: NextRequest, ...args: T) => Promise<NextResponse>): (request: NextRequest, ...args: T) => Promise<NextResponse>;
/**
 * Valida que un UUID tenga formato válido
 */
export declare function isValidUUID(uuid: string): boolean;
/**
 * Sanitiza parámetros de búsqueda para prevenir inyección SQL
 */
export declare function sanitizeSearchQuery(query: string): string;
/**
 * Parsea filtros de query parameters
 *
 * Note: Replaces hardcoded allowedFilters array with registry-based configuration.
 * Previously violated anti-hardcoding policies with static filter list.
 */
export declare function parseFilters(request: NextRequest): Record<string, string>;
/**
 * Agrega headers de CORS para API externa
 * Uses unified getCorsOrigins() for single source of truth
 */
export declare function addCorsHeaders(response: NextResponse, request?: NextRequest): Promise<NextResponse>;
/**
 * Maneja requests OPTIONS para CORS preflight
 */
export declare function handleCorsPreflightRequest(request?: NextRequest): Promise<NextResponse>;
/**
 * Wraps an auth handler response with CORS headers
 *
 * Better Auth handles OPTIONS preflight but doesn't add CORS headers to actual responses.
 * This utility wraps responses to add proper CORS headers for cross-origin requests.
 *
 * @param handler - The original handler function (GET, POST, etc.)
 * @param request - The incoming request
 * @returns Response with CORS headers added
 *
 * @example
 * ```ts
 * // In your auth route:
 * import { wrapAuthHandlerWithCors } from '@nextsparkjs/core/lib/api/helpers'
 *
 * export async function POST(req: NextRequest) {
 *   return wrapAuthHandlerWithCors(() => handlers.POST(req), req)
 * }
 * ```
 */
export declare function wrapAuthHandlerWithCors(handler: () => Promise<Response>, request: NextRequest): Promise<Response>;
/**
 * Parsea los parámetros de metadata de una request
 * Soporta: metas=all, metas=key1,key2,key3, o sin parámetro
 */
export interface MetaParams {
    includeMetadata: boolean;
    specificKeys?: string[];
    includeAll: boolean;
}
export declare function parseMetaParams(request: NextRequest): MetaParams;
/**
 * Child entity parameters for request parsing
 */
export interface ChildParams {
    includeChildren: boolean;
    includeAll: boolean;
    specificChildren?: string[];
}
/**
 * Parse child entities parameters from request URL
 * Supports: child=all, child=audiences, child=audiences,products
 */
export declare function parseChildParams(request: NextRequest): ChildParams;
/**
 * Helper para incluir metadata en entidades según parámetros de request
 * Uso: await includeEntityMetadata('user', users, metaParams, userId)
 */
export declare function includeEntityMetadata<T extends {
    id: string;
}>(entityType: string, entities: T[], metaParams: MetaParams, userId: string): Promise<(T & {
    metas?: Record<string, unknown>;
})[]>;
/**
 * Helper para incluir child entities en entidades según parámetros de request
 * Uso: await includeEntityChildren('client', clients, childParams, userId, entityConfig)
 */
export declare function includeEntityChildren<T extends {
    id: string;
}>(entityName: string, entities: T[], childParams: ChildParams, userId: string, entityConfig?: unknown): Promise<(T & {
    child?: Record<string, unknown[]>;
})[]>;
/**
 * Helper para incluir metadata en una entidad individual según parámetros de request
 * Uso: await includeEntityMetadataForSingle('user', user, metaParams, userId)
 */
export declare function includeEntityMetadataForSingle<T extends {
    id: string;
}>(entityType: string, entity: T, metaParams: MetaParams, userId: string): Promise<T & {
    metas?: Record<string, unknown>;
}>;
/**
 * Helper para manejar metadata en CREATE/UPDATE: responder con metadata solo si se envió en el payload
 * Uso: await handleEntityMetadataInResponse('user', entity, metaWasProvided, userId)
 */
export declare function handleEntityMetadataInResponse<T extends {
    id: string;
}>(entityType: string, entity: T, metaWasProvided: boolean, userId: string): Promise<T & {
    metas?: Record<string, unknown>;
}>;
/**
 * Helper para procesar metadata en CREATE/UPDATE
 * Uso: await processEntityMetadata('user', entityId, meta, userId)
 *
 * NOTE: Metas tables do NOT have teamId - security is inherited from parent entity via RLS.
 */
export declare function processEntityMetadata(entityType: string, entityId: string, meta: unknown, userId: string): Promise<{
    success: boolean;
    errors: string[];
}>;
export {};
//# sourceMappingURL=helpers.d.ts.map