@fitzzero/quickdraw-core 0.1.0 → 1.1.0

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, S as ServiceRegistryInstance, B as BaseServiceInstance, c as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-OhRxDBID.js';
+import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, A as AdminListPayload, c as AdminListResponse, d as AdminSetACLPayload, e as AdminSubscribersResponse, S as ServiceRegistryInstance, B as BaseServiceInstance, f as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-D7oHWh4O.js';
+import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
-import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition } from '../shared/index.js';
-import { Server } from 'socket.io';
+import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
 import 'http';
 
 /**
@@ -52,20 +52,33 @@ declare abstract class BaseService<TEntity extends {
     protected readonly logger: Logger;
     protected readonly subscribers: Map<string, Set<QuickdrawSocket>>;
     protected delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput> | undefined;
+    protected io: Server | null;
     private readonly publicMethods;
+    private adminMeta;
     constructor(options: BaseServiceOptions);
     /**
      * Set the Prisma delegate for this service.
      * Must be called in the constructor of derived classes.
      */
     protected setDelegate(delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput>): void;
+    /**
+     * Set the Socket.io server instance for room-based broadcasts.
+     * Called automatically by ServiceRegistry during registration.
+     */
+    setIo(io: Server): void;
     /**
      * Get the delegate, throwing if not set.
      */
     protected getDelegate(): PrismaDelegate<TEntity, TCreateInput, TUpdateInput>;
+    /**
+     * Get the Socket.io room name for an entry.
+     * Used for room-based broadcasting across services.
+     */
+    getRoomName(entryId: string): string;
     /**
      * Subscribe a socket to an entity's updates.
      * Returns the current entity data if access is granted, null otherwise.
+     * Also joins the socket to the entity's Socket.io room for cross-service events.
      */
     subscribe(entryId: string, socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<TEntity | null>;
     /**
@@ -76,8 +89,33 @@ declare abstract class BaseService<TEntity extends {
      * Remove a socket from all subscriptions (called on disconnect).
      */
     unsubscribeSocket(socket: QuickdrawSocket): void;
+    /**
+     * Emit a custom event to all subscribers of an entry via Socket.io rooms.
+     * This is useful for cross-service events (e.g., message service notifying chat subscribers).
+     *
+     * @param roomName - The Socket.io room name (use getRoomName for service rooms)
+     * @param eventName - The event name to emit
+     * @param data - The data to emit
+     *
+     * @example
+     * ```typescript
+     * // In MessageService, notify chat subscribers of a new message
+     * this.emitToRoom(
+     *   `chatService:${message.chatId}`,
+     *   'chat:message',
+     *   messageDTO
+     * );
+     * ```
+     */
+    protected emitToRoom(roomName: string, eventName: string, data: unknown): void;
+    /**
+     * Get any active socket for room-based operations.
+     */
+    private getAnySubscriberSocket;
     /**
      * Emit an update to all subscribers of an entity.
+     * Uses tier-based pre-filtering: computes filtered versions once,
+     * then selects the appropriate version per subscriber.
      */
     protected emitUpdate(entryId: string, data: Partial<TEntity>): void;
     /**
@@ -107,6 +145,56 @@ declare abstract class BaseService<TEntity extends {
      * Throws if access is denied.
      */
     ensureAccessForMethod(requiredLevel: AccessLevel, socket: QuickdrawSocket, entryId?: string): Promise<void>;
+    /**
+     * Get the list of fields that should be stripped for non-elevated subscribers.
+     * Override in derived classes to customize which fields are protected.
+     *
+     * @example
+     * ```typescript
+     * protected override getProtectedFields(): (keyof User)[] {
+     *   return ['email', 'serviceAccess', 'discordId'];
+     * }
+     * ```
+     */
+    protected getProtectedFields(): (keyof TEntity)[];
+    /**
+     * Check if a socket has elevated access to an entity (receives full data).
+     * Default: owner (socket.userId === entryId) or service-level Admin.
+     * Override in derived classes for custom logic.
+     *
+     * @example
+     * ```typescript
+     * protected override hasElevatedAccess(socket: QuickdrawSocket, entryId: string): boolean {
+     *   // Friends can see more data
+     *   return super.hasElevatedAccess(socket, entryId) ||
+     *          this.isFriend(socket.userId, entryId);
+     * }
+     * ```
+     */
+    protected hasElevatedAccess(socket: QuickdrawSocket, entryId: string): boolean;
+    /**
+     * Strip protected fields from an entity.
+     * Used internally by filterEntityForSubscriber.
+     */
+    protected stripProtectedFields<T extends Partial<TEntity>>(entity: T): T;
+    /**
+     * Filter entity data based on subscriber's access level.
+     * Override for complex filtering logic (e.g., multiple tiers).
+     *
+     * @example
+     * ```typescript
+     * protected override filterEntityForSubscriber(
+     *   entity: Partial<TEntity>,
+     *   socket: QuickdrawSocket,
+     *   entryId: string
+     * ): Partial<TEntity> {
+     *   if (this.hasElevatedAccess(socket, entryId)) return entity;
+     *   if (this.isFriend(socket.userId, entryId)) return this.stripForFriends(entity);
+     *   return this.stripProtectedFields(entity);
+     * }
+     * ```
+     */
+    protected filterEntityForSubscriber(entity: Partial<TEntity>, socket: QuickdrawSocket, entryId: string): Partial<TEntity>;
     /**
      * Find an entity by ID.
      */
@@ -139,8 +227,84 @@ declare abstract class BaseService<TEntity extends {
     /**
      * Install standard admin CRUD methods.
      * Call this in derived class constructor to expose admin endpoints.
+     *
+     * @example
+     * ```typescript
+     * this.installAdminMethods({
+     *   expose: { list: true, get: true, create: true, update: true, delete: true },
+     *   access: {
+     *     list: "Admin",
+     *     get: "Admin",
+     *     create: "Admin",
+     *     update: "Admin",
+     *     delete: "Admin",
+     *     setEntryACL: "Admin",
+     *     getSubscribers: "Admin",
+     *     reemit: "Admin",
+     *     unsubscribeAll: "Admin",
+     *   },
+     *   schema: createEntitySchema,
+     *   displayName: "Entities",
+     * });
+     * ```
+     */
+    protected installAdminMethods(options: InstallAdminMethodsOptions): void;
+    /**
+     * Convert service name to display name.
+     * e.g., "chatService" -> "Chats", "userService" -> "Users"
+     */
+    private toDisplayName;
+    /**
+     * Get admin metadata for this service.
+     * Returns the configured metadata or throws if not configured.
+     */
+    getAdminMeta(): AdminServiceMeta;
+    /**
+     * Admin method: List entities with pagination and filters.
      */
-    protected installAdminMethods(_options: InstallAdminMethodsOptions): void;
+    protected adminList(payload: AdminListPayload): Promise<AdminListResponse<TEntity>>;
+    /**
+     * Admin method: Get a single entity by ID.
+     */
+    protected adminGet(id: string): Promise<TEntity | null>;
+    /**
+     * Admin method: Create an entity.
+     */
+    protected adminCreate(data: TCreateInput): Promise<TEntity>;
+    /**
+     * Admin method: Update an entity.
+     */
+    protected adminUpdate(id: string, data: TUpdateInput): Promise<TEntity | null>;
+    /**
+     * Admin method: Delete an entity.
+     */
+    protected adminDelete(id: string): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    /**
+     * Admin method: Set entry-level ACL.
+     */
+    protected adminSetEntryACL(payload: AdminSetACLPayload): Promise<TEntity | null>;
+    /**
+     * Admin method: Get active subscribers for an entity.
+     */
+    protected adminGetSubscribers(entryId: string): AdminSubscribersResponse;
+    /**
+     * Admin method: Re-emit current entity state to all subscribers.
+     * Useful when you've made direct DB changes or need to force-refresh clients.
+     */
+    protected adminReemit(entryId: string): Promise<{
+        success: boolean;
+        subscriberCount: number;
+    }>;
+    /**
+     * Admin method: Unsubscribe all sockets from an entity.
+     */
+    protected adminUnsubscribeAll(entryId: string): {
+        success: boolean;
+        unsubscribedCount: number;
+    };
     /**
      * Fields that should never be exposed or editable via admin methods.
      */
@@ -155,6 +319,7 @@ declare abstract class BaseService<TEntity extends {
  * - Wires methods to Socket.io events with standardized naming
  * - Handles subscription lifecycle
  * - Provides consistent error handling and logging
+ * - Uses a single connection handler for all services (memory efficient)
  *
  * @example
  * ```typescript
@@ -163,19 +328,43 @@ declare abstract class BaseService<TEntity extends {
  * registry.registerService('userService', userService);
  * ```
  */
+interface ServiceRegistryOptions {
+    logger?: Logger;
+    /**
+     * Automatic method logging configuration.
+     * @default { enabled: true, logPayloads: false, logResponses: false }
+     */
+    methodLogging?: {
+        enabled?: boolean;
+        logPayloads?: boolean;
+        logResponses?: boolean;
+    };
+}
 declare class ServiceRegistry implements ServiceRegistryInstance {
     private readonly io;
     private readonly services;
     private readonly logger;
-    constructor(io: Server, options?: {
-        logger?: Logger;
-    });
+    private readonly methodLoggingEnabled;
+    private readonly logPayloads;
+    private readonly logResponses;
+    private connectionHandlerInstalled;
+    private readonly methodRegistry;
+    constructor(io: Server, options?: ServiceRegistryOptions);
+    /**
+     * Install the single connection handler that wires all registered services.
+     * This is called lazily on first service registration.
+     */
+    private installConnectionHandler;
+    /**
+     * Set up all event listeners for a newly connected socket.
+     */
+    private setupSocketListeners;
     /**
      * Register a service and auto-discover its public methods.
      */
     registerService(serviceName: string, service: BaseServiceInstance): void;
     /**
-     * Discover and register all public methods from a service.
+     * Discover and store all public methods from a service.
      */
     private discoverServiceMethods;
     /**
@@ -227,6 +416,255 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
  */
 declare function createQuickdrawServer(options: QuickdrawServerOptions): QuickdrawServerResult;
 
+/**
+ * Redis adapter utilities for horizontal scaling.
+ *
+ * This module provides optional Redis integration for Socket.io
+ * to enable running multiple server instances.
+ *
+ * @example
+ * ```typescript
+ * import { createQuickdrawServer } from '@fitzzero/quickdraw-core/server';
+ * import { setupRedisAdapter } from '@fitzzero/quickdraw-core/server';
+ *
+ * const { io } = createQuickdrawServer({ ... });
+ *
+ * // Enable Redis for horizontal scaling
+ * await setupRedisAdapter(io, {
+ *   host: process.env.REDIS_HOST ?? 'localhost',
+ *   port: parseInt(process.env.REDIS_PORT ?? '6379'),
+ * });
+ * ```
+ */
+
+/**
+ * Redis adapter configuration options.
+ */
+interface RedisAdapterOptions {
+    /**
+     * Redis host (default: 'localhost')
+     */
+    host?: string;
+    /**
+     * Redis port (default: 6379)
+     */
+    port?: number;
+    /**
+     * Redis password (optional)
+     */
+    password?: string;
+    /**
+     * Redis database number (default: 0)
+     */
+    db?: number;
+    /**
+     * Key prefix for Socket.io adapter (default: 'socket.io')
+     */
+    keyPrefix?: string;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+}
+/**
+ * Result of Redis adapter setup.
+ */
+interface RedisAdapterResult {
+    /**
+     * Whether the adapter was successfully set up.
+     */
+    success: boolean;
+    /**
+     * Cleanup function to disconnect from Redis.
+     */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Set up Redis adapter for Socket.io horizontal scaling.
+ *
+ * This function dynamically imports the @socket.io/redis-adapter package
+ * to avoid requiring it as a hard dependency.
+ *
+ * @param io - Socket.io server instance
+ * @param options - Redis configuration options
+ * @returns Promise resolving to setup result
+ *
+ * @example
+ * ```typescript
+ * const { io } = createQuickdrawServer({ ... });
+ *
+ * const { success, cleanup } = await setupRedisAdapter(io, {
+ *   host: 'redis.example.com',
+ *   port: 6379,
+ *   password: process.env.REDIS_PASSWORD,
+ * });
+ *
+ * if (success) {
+ *   console.log('Redis adapter enabled - horizontal scaling ready');
+ * }
+ *
+ * // On shutdown:
+ * await cleanup();
+ * ```
+ */
+declare function setupRedisAdapter(io: Server, options?: RedisAdapterOptions): Promise<RedisAdapterResult>;
+/**
+ * Check if Redis adapter packages are available.
+ *
+ * @returns Promise resolving to true if packages are installed
+ */
+declare function isRedisAdapterAvailable(): Promise<boolean>;
+
+/**
+ * Rate limiting middleware for Socket.io events.
+ *
+ * Provides per-socket rate limiting to prevent abuse and ensure
+ * fair resource usage across clients.
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter, applyRateLimitMiddleware } from '@fitzzero/quickdraw-core/server';
+ *
+ * // Create a rate limiter
+ * const rateLimiter = createRateLimiter({
+ *   windowMs: 60000, // 1 minute window
+ *   maxRequests: 100, // 100 requests per window
+ * });
+ *
+ * // Apply to Socket.io server
+ * applyRateLimitMiddleware(io, rateLimiter);
+ * ```
+ */
+
+/**
+ * Rate limiter configuration options.
+ */
+interface RateLimitOptions {
+    /**
+     * Time window in milliseconds (default: 60000 = 1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Maximum number of requests per window (default: 100)
+     */
+    maxRequests?: number;
+    /**
+     * Events to exclude from rate limiting (e.g., ['ping', 'pong'])
+     */
+    excludeEvents?: string[];
+    /**
+     * Custom key generator for grouping requests.
+     * Default uses socket.id.
+     */
+    keyGenerator?: (socket: Socket, eventName: string) => string;
+    /**
+     * Callback when rate limit is exceeded.
+     */
+    onRateLimitExceeded?: (socket: Socket, eventName: string) => void;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+}
+/**
+ * Rate limiter instance.
+ */
+interface RateLimiter {
+    /**
+     * Check if a request should be allowed.
+     * Returns true if allowed, false if rate limited.
+     */
+    check: (key: string) => boolean;
+    /**
+     * Get remaining requests for a key.
+     */
+    getRemaining: (key: string) => number;
+    /**
+     * Get time until rate limit resets for a key.
+     */
+    getResetTime: (key: string) => number;
+    /**
+     * Clear all rate limit entries (useful for testing).
+     */
+    clear: () => void;
+    /**
+     * Configuration options.
+     */
+    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents">>;
+}
+/**
+ * Create a rate limiter instance.
+ *
+ * @param options - Rate limiter configuration
+ * @returns Rate limiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   maxRequests: 100,
+ * });
+ *
+ * if (limiter.check('user-123')) {
+ *   // Request allowed
+ * } else {
+ *   // Rate limited
+ * }
+ * ```
+ */
+declare function createRateLimiter(options?: RateLimitOptions): RateLimiter;
+/**
+ * Apply rate limiting middleware to a Socket.io server.
+ *
+ * This intercepts all incoming events and checks them against
+ * the rate limiter before allowing them to proceed.
+ *
+ * @param io - Socket.io server instance
+ * @param rateLimiter - Rate limiter instance
+ * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimiter({ maxRequests: 100 });
+ *
+ * applyRateLimitMiddleware(io, rateLimiter, {
+ *   keyGenerator: (socket) => socket.userId ?? socket.id,
+ *   onRateLimitExceeded: (socket, event) => {
+ *     socket.emit('error', { code: 'RATE_LIMITED', event });
+ *   },
+ * });
+ * ```
+ */
+declare function applyRateLimitMiddleware(io: Server, rateLimiter: RateLimiter, options?: Pick<RateLimitOptions, "keyGenerator" | "onRateLimitExceeded" | "logger">): void;
+/**
+ * Create a tiered rate limiter with different limits for different event types.
+ *
+ * @param tiers - Map of event patterns to rate limit options
+ * @param defaultOptions - Default options for events not matching any tier
+ * @returns Rate limiter that applies different limits based on event name
+ *
+ * @example
+ * ```typescript
+ * const tieredLimiter = createTieredRateLimiter(
+ *   {
+ *     // Strict limits for write operations
+ *     'create*': { maxRequests: 10, windowMs: 60000 },
+ *     'update*': { maxRequests: 20, windowMs: 60000 },
+ *     'delete*': { maxRequests: 5, windowMs: 60000 },
+ *     // Generous limits for reads
+ *     'list*': { maxRequests: 200, windowMs: 60000 },
+ *     'get*': { maxRequests: 200, windowMs: 60000 },
+ *   },
+ *   { maxRequests: 100, windowMs: 60000 } // Default
+ * );
+ * ```
+ */
+declare function createTieredRateLimiter(tiers: Record<string, RateLimitOptions>, defaultOptions?: RateLimitOptions): {
+    check: (key: string, eventName: string) => boolean;
+    getRemaining: (key: string, eventName: string) => number;
+    clear: () => void;
+};
+
 interface JWTPayload {
     userId: string;
     email?: string;
@@ -333,4 +771,134 @@ interface GoogleUser {
  */
 declare const googleProvider: OAuthProvider<GoogleUser>;
 
-export { BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, ServiceRegistry, ServiceRegistryInstance, createJWT, createOAuthURL, createQuickdrawServer, discordProvider, exchangeOAuthCode, googleProvider, verifyJWT };
+/**
+ * Environment variable validation utilities.
+ * Helps ensure required environment variables are set before the application starts.
+ */
+interface ValidateEnvOptions {
+    /**
+     * List of required environment variable names.
+     * Validation will fail if any of these are missing or empty.
+     */
+    required: string[];
+    /**
+     * Only enforce validation in production environment.
+     * @default true
+     */
+    productionOnly?: boolean;
+    /**
+     * Custom error message prefix.
+     * @default "Missing required environment variables"
+     */
+    errorPrefix?: string;
+}
+interface EnvValidationResult {
+    success: boolean;
+    missing: string[];
+    message?: string;
+}
+/**
+ * Validate that required environment variables are set.
+ * Throws an error if any required variables are missing.
+ *
+ * @param options - Validation configuration
+ * @throws {Error} If required environment variables are missing
+ *
+ * @example
+ * ```typescript
+ * // Validate required vars on startup
+ * validateEnv({
+ *   required: ['JWT_SECRET', 'DATABASE_URL', 'CLIENT_URL'],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Only validate in production
+ * validateEnv({
+ *   required: ['JWT_SECRET', 'DATABASE_URL'],
+ *   productionOnly: true,
+ * });
+ * ```
+ */
+declare function validateEnv(options: ValidateEnvOptions): void;
+/**
+ * Check environment variables without throwing.
+ * Returns a result object with validation status and missing variables.
+ *
+ * @param options - Validation configuration
+ * @returns Validation result with missing variables list
+ *
+ * @example
+ * ```typescript
+ * const result = checkEnv({ required: ['JWT_SECRET'] });
+ * if (!result.success) {
+ *   console.warn('Missing env vars:', result.missing);
+ * }
+ * ```
+ */
+declare function checkEnv(options: ValidateEnvOptions): EnvValidationResult;
+/**
+ * Get an environment variable or throw if it's missing.
+ * Useful for individual variable access with validation.
+ *
+ * @param name - Environment variable name
+ * @param defaultValue - Optional default value (if provided, won't throw)
+ * @returns The environment variable value
+ * @throws {Error} If variable is missing and no default provided
+ *
+ * @example
+ * ```typescript
+ * const jwtSecret = requireEnv('JWT_SECRET');
+ * const port = requireEnv('PORT', '4000');
+ * ```
+ */
+declare function requireEnv(name: string, defaultValue?: string): string;
+
+/**
+ * Options for customizing field generation.
+ */
+interface ZodToAdminFieldsOptions {
+    /** Fields to exclude from the result */
+    hiddenFields?: string[];
+    /** Override which fields appear in table */
+    tableColumns?: string[];
+    /** Override specific field configurations */
+    fieldOverrides?: Partial<Record<string, Partial<AdminFieldConfig>>>;
+}
+/**
+ * Convert a Zod object schema to AdminFieldConfig array.
+ *
+ * @param schema - A Zod object schema (z.object({ ... }))
+ * @param options - Optional customization
+ * @returns Array of AdminFieldConfig for each field
+ *
+ * @example
+ * ```typescript
+ * const userSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string().optional(),
+ *   email: z.string().email(),
+ *   role: z.enum(["user", "admin"]),
+ *   createdAt: z.date(),
+ * });
+ *
+ * const fields = zodToAdminFields(userSchema);
+ * // Returns field configs with appropriate types, labels, editability
+ * ```
+ */
+declare function zodToAdminFields(schema: z.ZodTypeAny, options?: ZodToAdminFieldsOptions): AdminFieldConfig[];
+/**
+ * Generate AdminFieldConfig for common entity fields that aren't in the create schema.
+ * These are typically auto-generated fields like id, createdAt, updatedAt.
+ */
+declare function getDefaultEntityFields(): AdminFieldConfig[];
+/**
+ * Merge schema-derived fields with default entity fields.
+ * Default fields come first (id, createdAt, updatedAt), then schema fields.
+ */
+declare function mergeWithDefaultFields(schemaFields: AdminFieldConfig[], options?: {
+    includeDefaults?: string[];
+}): AdminFieldConfig[];
+
+export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, type EnvValidationResult, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, ServiceRegistry, ServiceRegistryInstance, type ServiceRegistryOptions, type ValidateEnvOptions, type ZodToAdminFieldsOptions, applyRateLimitMiddleware, checkEnv, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, getDefaultEntityFields, googleProvider, isRedisAdapterAvailable, mergeWithDefaultFields, requireEnv, setupRedisAdapter, validateEnv, verifyJWT, zodToAdminFields };