@nextsparkjs/core 0.1.0-beta.75 → 0.1.0-beta.77

package/dist/lib/api/permission-middleware.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Permission Middleware for API Endpoints
+ *
+ * Helper functions to integrate permission checks into API routes.
+ * Maps HTTP methods to entity actions and validates permissions.
+ */
+import type { Permission } from '../permissions/types';
+import { NextResponse } from 'next/server';
+/**
+ * Special mapping for list operations (GET on collection)
+ */
+export declare const LIST_ACTION = "list";
+/**
+ * Get the permission string for an entity action
+ *
+ * @param entitySlug - Entity slug (e.g., 'customers', 'tasks')
+ * @param action - Action being performed (e.g., 'create', 'read', 'list')
+ * @returns Permission string (e.g., 'customers.create')
+ *
+ * @example
+ * ```typescript
+ * const permission = getEntityPermission('customers', 'create')
+ * // => 'customers.create'
+ * ```
+ */
+export declare function getEntityPermission(entitySlug: string, action: string): Permission;
+/**
+ * Get entity action from HTTP method and context
+ *
+ * @param method - HTTP method (GET, POST, PATCH, DELETE)
+ * @param isCollection - Whether this is a collection endpoint (true) or single entity (false)
+ * @returns Action string (e.g., 'list', 'read', 'create', 'update', 'delete')
+ *
+ * @example
+ * ```typescript
+ * // GET /api/v1/customers (list)
+ * const action = getActionFromMethod('GET', true)
+ * // => 'list'
+ *
+ * // GET /api/v1/customers/123 (read single)
+ * const action = getActionFromMethod('GET', false)
+ * // => 'read'
+ * ```
+ */
+export declare function getActionFromMethod(method: string, isCollection: boolean): string;
+/**
+ * Check if user has permission for entity action
+ *
+ * This is the main permission check function for API endpoints.
+ * Returns either success indicator or error Response.
+ *
+ * @param userId - User ID
+ * @param teamId - Team ID
+ * @param entitySlug - Entity slug (e.g., 'customers')
+ * @param action - Action being performed (e.g., 'create', 'read', 'list')
+ * @returns Success indicator or error Response
+ *
+ * @example
+ * ```typescript
+ * // In API route handler
+ * const permCheck = await checkEntityPermission(userId, teamId, 'customers', 'create')
+ * if (!permCheck.allowed) {
+ *   return permCheck.error
+ * }
+ * // Continue with operation...
+ * ```
+ */
+export declare function checkEntityPermission(userId: string, teamId: string, entitySlug: string, action: string): Promise<{
+    allowed: true;
+} | {
+    allowed: false;
+    error: NextResponse;
+}>;
+/**
+ * Helper for common API pattern: check permission and return early if denied
+ *
+ * @param userId - User ID
+ * @param teamId - Team ID
+ * @param entitySlug - Entity slug
+ * @param method - HTTP method
+ * @param isCollection - Whether this is a collection endpoint
+ * @returns null if allowed, error Response if denied
+ *
+ * @example
+ * ```typescript
+ * // Simplified usage in API routes
+ * const error = await checkEntityPermissionOrFail(userId, teamId, 'customers', 'POST', true)
+ * if (error) return error
+ *
+ * // Continue with operation...
+ * ```
+ */
+export declare function checkEntityPermissionOrFail(userId: string, teamId: string, entitySlug: string, method: string, isCollection: boolean): Promise<NextResponse | null>;
+//# sourceMappingURL=permission-middleware.d.ts.map

package/dist/lib/api/permission-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-middleware.d.ts","sourceRoot":"","sources":["../../../src/lib/api/permission-middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAa1C;;GAEG;AACH,eAAO,MAAM,WAAW,SAAS,CAAA;AAEjC;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAElF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAOjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC,CAkCtE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAK9B"}

package/dist/lib/api/rate-limit.d.ts

@@ -0,0 +1,82 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type RateLimitTier } from '../rate-limit-redis';
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetTime: number;
+    limit: number;
+}
+/**
+ * Verifica el rate limit para un identificador específico
+ */
+export declare function checkRateLimit(identifier: string, limit?: number, windowMs?: number): RateLimitResult;
+/**
+ * Rate limit types for distributed rate limiting
+ * Re-export from rate-limit-redis for convenience
+ */
+export type { RateLimitTier };
+/**
+ * Check rate limit using Redis (distributed) when configured,
+ * falls back to in-memory rate limiting otherwise.
+ *
+ * @param identifier - Unique identifier (IP, user ID, or combination)
+ * @param type - Rate limit tier: 'auth' (5/15min), 'api' (100/1min), 'strict' (10/1hr), 'read' (200/1min), 'write' (50/1min)
+ * @returns Promise with rate limit result
+ */
+export declare function checkDistributedRateLimit(identifier: string, type?: RateLimitTier): Promise<RateLimitResult & {
+    retryAfter?: number;
+}>;
+/**
+ * Create a 429 rate limit response
+ */
+export declare function createRateLimitErrorResponse(result: RateLimitResult & {
+    retryAfter?: number;
+}): NextResponse;
+/**
+ * Check if Redis-based distributed rate limiting might be available
+ * (based on environment variables)
+ */
+export declare function isDistributedRateLimitAvailable(): boolean;
+/**
+ * Aplica rate limiting a una request API
+ */
+export declare function applyRateLimit(request: NextRequest, keyId: string, scopes: string[]): NextResponse | null;
+/**
+ * Agrega headers de rate limiting a una respuesta
+ */
+export declare function addRateLimitHeaders(response: NextResponse, keyId: string, scopes: string[]): NextResponse;
+/**
+ * Middleware helper para aplicar rate limiting automáticamente
+ */
+export declare function withRateLimit<T extends unknown[]>(handler: (request: NextRequest, ...args: T) => Promise<NextResponse>): (request: NextRequest, ...args: T) => Promise<NextResponse>;
+/**
+ * Obtiene estadísticas de rate limiting para un keyId
+ */
+export declare function getRateLimitStats(keyId: string): {
+    currentUsage: number;
+    resetTime: number;
+    isNearLimit: boolean;
+} | null;
+/**
+ * Limpia manualmente el rate limit para un keyId (útil para testing)
+ */
+export declare function clearRateLimit(keyId: string): void;
+/**
+ * Obtiene todas las estadísticas de rate limiting (útil para monitoring)
+ */
+export declare function getAllRateLimitStats(): Array<{
+    keyId: string;
+    count: number;
+    resetTime: number;
+}>;
+/**
+ * Obtiene estadísticas del cache de rate limiting
+ */
+export declare function getRateLimitCacheStats(): {
+    total: number;
+    active: number;
+    expired: number;
+    maxSize: number;
+};
+export declare function withRateLimitTier<T extends unknown[]>(handler: (request: NextRequest, ...args: T) => Promise<NextResponse>, tier?: RateLimitTier): (request: NextRequest, ...args: T) => Promise<NextResponse>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/lib/api/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/lib/api/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAa,EACpB,QAAQ,GAAE,MAAc,GACvB,eAAe,CAyCjB;AAED;;;GAGG;AACH,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,aAAqB,GAC1B,OAAO,CAAC,eAAe,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsCpD;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,eAAe,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAwB5G;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EAAE,GACf,YAAY,GAAG,IAAI,CAkCrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EAAE,GACf,YAAY,CASd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,EAC/C,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,IAEtD,SAAS,WAAW,EAAE,GAAG,MAAM,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC,CAsCvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,IAAI,CAaP;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,KAAK,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CASD;AAED;;GAEG;AACH,wBAAgB,sBAAsB;;;;;EAErC;AAmGD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,EACnD,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,EACpE,IAAI,GAAE,aAAqB,IAEb,SAAS,WAAW,EAAE,GAAG,MAAM,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC,CAkCvE"}

package/dist/lib/api/routes/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Route Handler Factories
+ *
+ * Compiled route handlers that can be imported from npm package.
+ * Use these factories instead of copying template files.
+ */
+export { createPatternUsagesHandlers } from './patterns-usages';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/api/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/lib/api/routes/patterns-usages.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pattern Usages Route Handlers Factory
+ *
+ * Creates compiled route handlers for pattern usages API.
+ * Use this factory in your app's route file:
+ *
+ * @example
+ * // app/api/v1/patterns/[id]/usages/route.ts
+ * import { createPatternUsagesHandlers } from '@nextsparkjs/core/lib/api/routes'
+ * export const { GET, OPTIONS } = createPatternUsagesHandlers()
+ */
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Creates GET and OPTIONS handlers for pattern usages endpoint
+ *
+ * GET /api/v1/patterns/[id]/usages - Get detailed usage information for a pattern
+ *
+ * Query Parameters:
+ * - entityType: Filter by entity type (e.g., 'pages', 'posts')
+ * - limit: Number of results per page (default: 50)
+ * - page: Page number (default: 1)
+ *
+ * Response includes:
+ * - usages: Array of usage records with entity info
+ * - counts: Array of counts by entity type
+ * - total: Total number of usages
+ */
+export declare function createPatternUsagesHandlers(): {
+    GET: (request: NextRequest, args_0: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse>;
+    OPTIONS: () => Promise<NextResponse<unknown>>;
+};
+//# sourceMappingURL=patterns-usages.d.ts.map

package/dist/lib/api/routes/patterns-usages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns-usages.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/routes/patterns-usages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAavD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B;;gBAQQ,OAAO,CAAC;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;;;EAkFzE"}

package/dist/lib/auth/api-keys.d.ts

@@ -0,0 +1,75 @@
+/**
+ * API Key Authentication System
+ *
+ * Handles API key validation, scopes, and permissions for external APIs.
+ */
+export interface APIKeyValidation {
+    valid: boolean;
+    apiKeyId?: string;
+    clientId?: string;
+    userId?: string;
+    scopes?: string[];
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface APIKeyValidationOptions {
+    requiredScopes?: string[];
+    entityName?: string;
+    allowInactive?: boolean;
+}
+interface APIKeyData {
+    id: string;
+    clientId: string;
+    userId?: string;
+    scopes: string[];
+    active: boolean;
+    name: string;
+    lastUsed?: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Validate API key and check permissions
+ */
+export declare function validateAPIKey(apiKey: string, options?: APIKeyValidationOptions): Promise<APIKeyValidation>;
+/**
+ * Generate scope name for entity and action
+ */
+export declare function generateScope(entityName: string, action: 'read' | 'create' | 'update' | 'delete'): string;
+/**
+ * Check if API key has specific scope
+ */
+export declare function hasScope(scopes: string[], requiredScope: string): boolean;
+/**
+ * Create API key (mock implementation)
+ */
+export declare function createAPIKey(data: {
+    clientId: string;
+    userId?: string;
+    scopes: string[];
+    name: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<{
+    apiKey: string;
+    keyData: APIKeyData;
+}>;
+/**
+ * Revoke API key
+ */
+export declare function revokeAPIKey(apiKey: string): Promise<boolean>;
+/**
+ * List API keys for a client
+ */
+export declare function listAPIKeys(clientId: string): Promise<APIKeyData[]>;
+/**
+ * Get API key analytics
+ */
+export declare function getAPIKeyAnalytics(apiKey: string): Promise<{
+    requests: number;
+    lastUsed?: string;
+    scopes: string[];
+    active: boolean;
+} | null>;
+export {};
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/lib/auth/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/api-keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AA0CD;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAwE3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAEzG;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAIzE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC,CAYnD;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEzE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,IAAI,CAAC,CAYR"}