@parsrun/server 0.1.27 → 0.1.29

package/dist/quota-enforcement-CN3z5bfc.d.ts

@@ -0,0 +1,744 @@
+import { HonoContext, HonoNext, CorsConfig, ApiResponse } from './context.js';
+import * as hono from 'hono';
+import * as hono_utils_types from 'hono/utils/types';
+import { ErrorTransport } from '@parsrun/core/transports';
+
+/**
+ * @parsrun/server - Auth Middleware
+ * JWT authentication middleware
+ */
+
+/**
+ * JWT payload structure
+ */
+interface JwtPayload {
+    sub: string;
+    email?: string;
+    tenantId?: string;
+    role?: string;
+    permissions?: string[];
+    iat?: number;
+    exp?: number;
+    jti?: string;
+}
+/**
+ * JWT verification function type
+ */
+type JwtVerifier = (token: string) => Promise<JwtPayload | null>;
+/**
+ * Auth middleware options
+ */
+interface AuthMiddlewareOptions {
+    /** JWT verification function */
+    verify: JwtVerifier;
+    /** Header name for token (default: Authorization) */
+    header?: string;
+    /** Token prefix (default: Bearer) */
+    prefix?: string;
+    /** Cookie name for token (alternative to header) */
+    cookie?: string;
+    /** Skip auth for certain requests */
+    skip?: (c: HonoContext) => boolean;
+    /** Custom error message */
+    message?: string;
+}
+/**
+ * Auth middleware - requires valid JWT
+ *
+ * @example
+ * ```typescript
+ * import { verifyJwt } from '@parsrun/auth';
+ *
+ * const authMiddleware = auth({
+ *   verify: (token) => verifyJwt(token, secret),
+ *   cookie: 'auth_token',
+ * });
+ *
+ * app.use('/api/*', authMiddleware);
+ *
+ * // Access user in handlers
+ * app.get('/api/me', (c) => {
+ *   const user = c.get('user');
+ *   return c.json({ user });
+ * });
+ * ```
+ */
+declare function auth(options: AuthMiddlewareOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+/**
+ * Optional auth middleware - sets user if token present, but doesn't require it
+ *
+ * @example
+ * ```typescript
+ * app.use('/api/public/*', optionalAuth({
+ *   verify: (token) => verifyJwt(token, secret),
+ * }));
+ *
+ * // User may or may not be present
+ * app.get('/api/public/items', (c) => {
+ *   const user = c.get('user'); // may be undefined
+ *   // Return different data based on auth status
+ * });
+ * ```
+ */
+declare function optionalAuth(options: Omit<AuthMiddlewareOptions, "message">): (c: HonoContext, next: HonoNext) => Promise<void>;
+/**
+ * Create auth middleware from verifier function
+ *
+ * @example
+ * ```typescript
+ * const { auth, optionalAuth } = createAuthMiddleware({
+ *   verify: async (token) => {
+ *     return verifyJwt(token, process.env.JWT_SECRET);
+ *   },
+ *   cookie: 'session',
+ * });
+ *
+ * app.use('/api/*', auth);
+ * app.use('/public/*', optionalAuth);
+ * ```
+ */
+declare function createAuthMiddleware(baseOptions: Omit<AuthMiddlewareOptions, "skip" | "message">): {
+    auth: (options?: Partial<AuthMiddlewareOptions>) => (c: HonoContext, next: HonoNext) => Promise<void>;
+    optionalAuth: (options?: Partial<Omit<AuthMiddlewareOptions, "message">>) => (c: HonoContext, next: HonoNext) => Promise<void>;
+};
+
+/**
+ * @parsrun/server - CORS Middleware
+ * Cross-Origin Resource Sharing configuration
+ */
+
+/**
+ * CORS middleware
+ *
+ * @example
+ * ```typescript
+ * app.use('*', cors({
+ *   origin: ['https://example.com', 'https://app.example.com'],
+ *   credentials: true,
+ * }));
+ * ```
+ */
+declare function cors(config?: Partial<CorsConfig>): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+
+/**
+ * @parsrun/server - CSRF Middleware
+ * Cross-Site Request Forgery protection
+ */
+
+/**
+ * CSRF options
+ */
+interface CsrfOptions {
+    /** Cookie name for CSRF token */
+    cookieName?: string;
+    /** Header name for CSRF token */
+    headerName?: string;
+    /** Methods that require CSRF validation */
+    methods?: string[];
+    /** Paths to exclude from CSRF protection */
+    excludePaths?: string[];
+    /** Skip CSRF for certain requests */
+    skip?: (c: HonoContext) => boolean;
+    /** Token generator */
+    generateToken?: () => string;
+    /** Cookie options */
+    cookie?: {
+        secure?: boolean;
+        httpOnly?: boolean;
+        sameSite?: "strict" | "lax" | "none";
+        path?: string;
+        maxAge?: number;
+    };
+}
+/**
+ * CSRF protection middleware
+ *
+ * @example
+ * ```typescript
+ * app.use('*', csrf({
+ *   cookieName: '_csrf',
+ *   headerName: 'X-CSRF-Token',
+ *   methods: ['POST', 'PUT', 'PATCH', 'DELETE'],
+ *   cookie: {
+ *     secure: true,
+ *     sameSite: 'strict',
+ *   },
+ * }));
+ *
+ * // Get token in handler
+ * app.get('/csrf-token', (c) => {
+ *   return c.json({ token: c.get('csrfToken') });
+ * });
+ * ```
+ */
+declare function csrf(options?: CsrfOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+/**
+ * Double Submit Cookie pattern
+ * Generates a token and validates it matches between cookie and header
+ */
+declare function doubleSubmitCookie(options?: CsrfOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+
+/**
+ * Base API error class
+ */
+declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown> | undefined);
+    toResponse(): ApiResponse<never>;
+}
+/**
+ * 400 Bad Request
+ */
+declare class BadRequestError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 401 Unauthorized
+ */
+declare class UnauthorizedError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 403 Forbidden
+ */
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 404 Not Found
+ */
+declare class NotFoundError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 409 Conflict
+ */
+declare class ConflictError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 422 Unprocessable Entity (Validation Error)
+ */
+declare class ValidationError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 429 Too Many Requests
+ */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * 500 Internal Server Error
+ */
+declare class InternalError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * 503 Service Unavailable
+ */
+declare class ServiceUnavailableError extends ApiError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Error handler options
+ */
+interface ErrorHandlerOptions {
+    /** Include stack trace in development */
+    includeStack?: boolean;
+    /** Custom error logger */
+    onError?: (error: Error, c: HonoContext) => void;
+    /**
+     * Error transport for external error tracking (e.g., Sentry)
+     * Automatically captures exceptions with request context
+     */
+    errorTransport?: ErrorTransport;
+    /**
+     * Capture all errors including 4xx client errors
+     * By default, only 5xx server errors are captured
+     * @default false
+     */
+    captureAllErrors?: boolean;
+    /**
+     * Custom function to determine if an error should be captured
+     * Overrides the default captureAllErrors behavior
+     */
+    shouldCapture?: (error: Error, statusCode: number) => boolean;
+}
+/**
+ * Global error handler middleware
+ *
+ * @example Basic usage
+ * ```typescript
+ * app.use('*', errorHandler({
+ *   includeStack: process.env.NODE_ENV === 'development',
+ *   onError: (error, c) => {
+ *     console.error(`[${c.get('requestId')}]`, error);
+ *   },
+ * }));
+ * ```
+ *
+ * @example With Sentry error tracking
+ * ```typescript
+ * import { SentryTransport } from '@parsrun/core/transports';
+ *
+ * const sentry = new SentryTransport({
+ *   dsn: process.env.SENTRY_DSN!,
+ *   environment: process.env.NODE_ENV,
+ * });
+ *
+ * app.use('*', errorHandler({
+ *   errorTransport: sentry,
+ *   captureAllErrors: false, // Only capture 5xx errors
+ * }));
+ * ```
+ */
+declare function errorHandler(options?: ErrorHandlerOptions): (c: HonoContext, next: HonoNext) => Promise<(Response & hono.TypedResponse<{
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        details?: {
+            [x: string]: hono_utils_types.JSONValue;
+        } | undefined;
+    } | undefined;
+    meta?: {
+        page?: number | undefined | undefined;
+        limit?: number | undefined | undefined;
+        total?: number | undefined | undefined;
+        requestId?: string | undefined | undefined;
+    } | undefined;
+}, 400, "json">) | (Response & hono.TypedResponse<{
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        details?: {
+            [x: string]: hono_utils_types.JSONValue;
+        } | undefined;
+    } | undefined;
+    meta?: {
+        page?: number | undefined | undefined;
+        limit?: number | undefined | undefined;
+        total?: number | undefined | undefined;
+        requestId?: string | undefined | undefined;
+    } | undefined;
+}, 500, "json">) | undefined>;
+/**
+ * Not found handler
+ *
+ * @example
+ * ```typescript
+ * app.notFound(notFoundHandler);
+ * ```
+ */
+declare function notFoundHandler(c: HonoContext): Response & hono.TypedResponse<{
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        details?: {
+            [x: string]: hono_utils_types.JSONValue;
+        } | undefined;
+    } | undefined;
+    meta?: {
+        page?: number | undefined | undefined;
+        limit?: number | undefined | undefined;
+        total?: number | undefined | undefined;
+        requestId?: string | undefined | undefined;
+    } | undefined;
+}, 404, "json">;
+
+/**
+ * @parsrun/server - Rate Limit Middleware
+ * Request throttling with multiple storage backends
+ */
+
+/**
+ * Rate limit storage interface
+ */
+interface RateLimitStorage {
+    /** Get current count for key */
+    get(key: string): Promise<number>;
+    /** Increment count and set expiry */
+    increment(key: string, windowMs: number): Promise<number>;
+    /** Reset count for key */
+    reset(key: string): Promise<void>;
+}
+/**
+ * In-memory rate limit storage
+ * For single-instance deployments or development
+ */
+declare class MemoryRateLimitStorage implements RateLimitStorage {
+    private store;
+    get(key: string): Promise<number>;
+    increment(key: string, windowMs: number): Promise<number>;
+    reset(key: string): Promise<void>;
+    /** Clean up expired entries */
+    cleanup(): void;
+}
+/**
+ * Rate limit options
+ */
+interface RateLimitOptions {
+    /** Time window in milliseconds */
+    windowMs?: number;
+    /** Maximum requests per window */
+    max?: number;
+    /** Generate key from request (default: IP address) */
+    keyGenerator?: (c: HonoContext) => string;
+    /** Skip rate limiting for certain requests */
+    skip?: (c: HonoContext) => boolean;
+    /** Custom storage backend */
+    storage?: RateLimitStorage;
+    /** Error message */
+    message?: string;
+    /** Include rate limit headers */
+    headers?: boolean;
+    /** Handler when limit is exceeded */
+    onLimitReached?: (c: HonoContext, key: string) => void;
+}
+/**
+ * Rate limit middleware
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - 100 requests per minute
+ * app.use('/api/*', rateLimit({
+ *   windowMs: 60 * 1000,
+ *   max: 100,
+ * }));
+ *
+ * // Per-user rate limiting
+ * app.use('/api/*', rateLimit({
+ *   keyGenerator: (c) => c.get('user')?.id ?? getIP(c),
+ *   max: 1000,
+ * }));
+ *
+ * // Strict limit for auth endpoints
+ * app.use('/api/auth/*', rateLimit({
+ *   windowMs: 15 * 60 * 1000, // 15 minutes
+ *   max: 5,
+ *   message: 'Too many login attempts',
+ * }));
+ * ```
+ */
+declare function rateLimit(options?: RateLimitOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+/**
+ * Create rate limiter for specific routes
+ *
+ * @example
+ * ```typescript
+ * const apiLimiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   max: 100,
+ * });
+ *
+ * app.use('/api/*', apiLimiter.middleware);
+ *
+ * // Reset limit for a user after successful auth
+ * await apiLimiter.reset('user:123');
+ * ```
+ */
+declare function createRateLimiter(options?: RateLimitOptions): {
+    middleware: (c: HonoContext, next: HonoNext) => Promise<void>;
+    storage: RateLimitStorage;
+    reset: (key: string) => Promise<void>;
+    get: (key: string) => Promise<number>;
+};
+
+/**
+ * @parsrun/server - Request Logger Middleware
+ * HTTP request/response logging
+ */
+
+/**
+ * Request logger options
+ */
+interface RequestLoggerOptions {
+    /** Skip logging for certain paths */
+    skip?: (c: HonoContext) => boolean;
+    /** Custom log format */
+    format?: "json" | "combined" | "short";
+    /** Include request body in logs */
+    includeBody?: boolean;
+    /** Include response body in logs (be careful with large responses) */
+    includeResponseBody?: boolean;
+    /** Maximum body length to log */
+    maxBodyLength?: number;
+}
+/**
+ * Request logger middleware
+ *
+ * @example
+ * ```typescript
+ * app.use('*', requestLogger({
+ *   skip: (c) => c.req.path === '/health',
+ *   format: 'json',
+ * }));
+ * ```
+ */
+declare function requestLogger(options?: RequestLoggerOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+
+/**
+ * @parsrun/server - Usage Tracking Middleware
+ * Automatically track API usage per request
+ */
+
+/**
+ * Usage service interface (from @parsrun/payments)
+ * Defined here to avoid circular dependency
+ */
+interface UsageServiceLike {
+    trackUsage(options: {
+        tenantId: string;
+        customerId: string;
+        subscriptionId?: string;
+        featureKey: string;
+        quantity?: number;
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+}
+/**
+ * Usage tracking middleware options
+ */
+interface UsageTrackingOptions {
+    /**
+     * Usage service instance
+     */
+    usageService: UsageServiceLike;
+    /**
+     * Feature key to track
+     * Can be a static string or a function that extracts it from context
+     * @default "api_calls"
+     */
+    featureKey?: string | ((c: HonoContext) => string);
+    /**
+     * Quantity to track
+     * Can be a static number or a function that calculates it from context
+     * @default 1
+     */
+    quantity?: number | ((c: HonoContext) => number);
+    /**
+     * Skip tracking for certain requests
+     */
+    skip?: (c: HonoContext) => boolean;
+    /**
+     * When to track: before or after the request
+     * @default "response"
+     */
+    trackOn?: "request" | "response";
+    /**
+     * Only track successful responses (2xx)
+     * @default true
+     */
+    successOnly?: boolean;
+    /**
+     * Custom customer ID extractor
+     * @default Uses c.get("user")?.id
+     */
+    getCustomerId?: (c: HonoContext) => string | undefined;
+    /**
+     * Custom tenant ID extractor
+     * @default Uses c.get("tenant")?.id or c.get("user")?.tenantId
+     */
+    getTenantId?: (c: HonoContext) => string | undefined;
+    /**
+     * Custom subscription ID extractor
+     */
+    getSubscriptionId?: (c: HonoContext) => string | undefined;
+    /**
+     * Include request metadata
+     * @default true
+     */
+    includeMetadata?: boolean;
+    /**
+     * Generate idempotency key to prevent duplicates
+     */
+    getIdempotencyKey?: (c: HonoContext) => string | undefined;
+}
+/**
+ * Usage tracking middleware
+ *
+ * Automatically tracks API usage for authenticated requests.
+ *
+ * @example
+ * ```typescript
+ * import { usageTracking } from "@parsrun/server";
+ * import { createUsageService, createMemoryUsageStorage } from "@parsrun/payments";
+ *
+ * const usageService = createUsageService({
+ *   storage: createMemoryUsageStorage(),
+ * });
+ *
+ * // Track all API calls
+ * app.use("/api/*", usageTracking({
+ *   usageService,
+ *   featureKey: "api_calls",
+ * }));
+ *
+ * // Track with custom feature key based on route
+ * app.use("/api/ai/*", usageTracking({
+ *   usageService,
+ *   featureKey: "ai_requests",
+ *   quantity: (c) => {
+ *     // Track tokens used from response
+ *     return c.get("tokensUsed") ?? 1;
+ *   },
+ * }));
+ *
+ * // Skip certain routes
+ * app.use("/api/*", usageTracking({
+ *   usageService,
+ *   skip: (c) => c.req.path.startsWith("/api/health"),
+ * }));
+ * ```
+ */
+declare function usageTracking(options: UsageTrackingOptions): (c: HonoContext, next: HonoNext) => Promise<void>;
+/**
+ * Create usage tracking middleware with pre-configured options
+ */
+declare function createUsageTracking(baseOptions: UsageTrackingOptions): (overrides?: Partial<UsageTrackingOptions>) => (c: HonoContext, next: HonoNext) => Promise<void>;
+
+/**
+ * @parsrun/server - Quota Enforcement Middleware
+ * Enforce usage quotas before processing requests
+ */
+
+/**
+ * Quota check result interface (from @parsrun/payments)
+ */
+interface QuotaCheckResult {
+    allowed: boolean;
+    currentUsage: number;
+    limit: number | null;
+    remaining: number | null;
+    wouldExceed: boolean;
+    percentAfter: number | null;
+}
+/**
+ * Quota manager interface (from @parsrun/payments)
+ * Defined here to avoid circular dependency
+ */
+interface QuotaManagerLike {
+    checkQuota(customerId: string, featureKey: string, quantity?: number): Promise<QuotaCheckResult>;
+    enforceQuota(customerId: string, featureKey: string, quantity?: number): Promise<void>;
+}
+/**
+ * Quota exceeded error class
+ */
+declare class QuotaExceededError extends Error {
+    readonly featureKey: string;
+    readonly limit: number | null;
+    readonly currentUsage: number;
+    readonly requestedQuantity: number;
+    readonly statusCode = 429;
+    readonly code = "QUOTA_EXCEEDED";
+    constructor(featureKey: string, limit: number | null, currentUsage: number, requestedQuantity?: number);
+}
+/**
+ * Quota enforcement middleware options
+ */
+interface QuotaEnforcementOptions {
+    /**
+     * Quota manager instance
+     */
+    quotaManager: QuotaManagerLike;
+    /**
+     * Feature key to check
+     * Can be a static string or a function that extracts it from context
+     */
+    featureKey: string | ((c: HonoContext) => string);
+    /**
+     * Quantity to check (default: 1)
+     */
+    quantity?: number | ((c: HonoContext) => number);
+    /**
+     * Skip quota check for certain requests
+     */
+    skip?: (c: HonoContext) => boolean;
+    /**
+     * Custom customer ID extractor
+     * @default Uses c.get("user")?.id
+     */
+    getCustomerId?: (c: HonoContext) => string | undefined;
+    /**
+     * Include quota headers in response
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Custom error handler
+     */
+    onQuotaExceeded?: (c: HonoContext, result: QuotaCheckResult, featureKey: string) => Response | void;
+    /**
+     * Soft limit mode - warn but don't block
+     * @default false
+     */
+    softLimit?: boolean;
+    /**
+     * Callback when quota is close to limit (>80%)
+     */
+    onQuotaWarning?: (c: HonoContext, result: QuotaCheckResult, featureKey: string) => void;
+}
+/**
+ * Quota enforcement middleware
+ *
+ * Checks and enforces usage quotas before processing requests.
+ *
+ * @example
+ * ```typescript
+ * import { quotaEnforcement } from "@parsrun/server";
+ * import { createQuotaManager, createMemoryUsageStorage } from "@parsrun/payments";
+ *
+ * const quotaManager = createQuotaManager({
+ *   storage: createMemoryUsageStorage(),
+ * });
+ *
+ * // Enforce API call quota
+ * app.use("/api/*", quotaEnforcement({
+ *   quotaManager,
+ *   featureKey: "api_calls",
+ * }));
+ *
+ * // Enforce with dynamic feature key
+ * app.use("/api/*", quotaEnforcement({
+ *   quotaManager,
+ *   featureKey: (c) => {
+ *     if (c.req.path.startsWith("/api/ai")) return "ai_requests";
+ *     return "api_calls";
+ *   },
+ * }));
+ *
+ * // Soft limit mode (warn but allow)
+ * app.use("/api/*", quotaEnforcement({
+ *   quotaManager,
+ *   featureKey: "api_calls",
+ *   softLimit: true,
+ *   onQuotaWarning: (c, result) => {
+ *     console.warn("Quota warning:", result);
+ *   },
+ * }));
+ * ```
+ */
+declare function quotaEnforcement(options: QuotaEnforcementOptions): (c: HonoContext, next: HonoNext) => Promise<void | Response>;
+/**
+ * Create quota enforcement middleware with pre-configured options
+ */
+declare function createQuotaEnforcement(baseOptions: Omit<QuotaEnforcementOptions, "featureKey">): (featureKey: string | ((c: HonoContext) => string)) => (c: HonoContext, next: HonoNext) => Promise<void | Response>;
+/**
+ * Multiple quota enforcement
+ * Check multiple features at once
+ */
+declare function multiQuotaEnforcement(options: Omit<QuotaEnforcementOptions, "featureKey"> & {
+    features: Array<{
+        featureKey: string;
+        quantity?: number | ((c: HonoContext) => number);
+    }>;
+}): (c: HonoContext, next: HonoNext) => Promise<void | Response>;
+
+export { type AuthMiddlewareOptions as A, BadRequestError as B, type CsrfOptions as C, type QuotaCheckResult as D, type ErrorHandlerOptions as E, ForbiddenError as F, InternalError as I, type JwtPayload as J, MemoryRateLimitStorage as M, NotFoundError as N, QuotaExceededError as Q, RateLimitError as R, ServiceUnavailableError as S, UnauthorizedError as U, ValidationError as V, auth as a, type JwtVerifier as b, createAuthMiddleware as c, cors as d, csrf as e, doubleSubmitCookie as f, errorHandler as g, ApiError as h, ConflictError as i, createRateLimiter as j, type RateLimitOptions as k, type RateLimitStorage as l, requestLogger as m, notFoundHandler as n, optionalAuth as o, type RequestLoggerOptions as p, createUsageTracking as q, rateLimit as r, type UsageTrackingOptions as s, type UsageServiceLike as t, usageTracking as u, quotaEnforcement as v, createQuotaEnforcement as w, multiQuotaEnforcement as x, type QuotaEnforcementOptions as y, type QuotaManagerLike as z };