@fitzzero/quickdraw-core 0.1.0 → 1.1.0

package/dist/server/index.js

@@ -12,6 +12,168 @@ var consoleLogger = {
   child: () => consoleLogger
 };
 
+// src/server/utils/zodToAdminFields.ts
+var NON_EDITABLE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "createdAt",
+  "updatedAt",
+  "created_at",
+  "updated_at"
+]);
+var DEFAULT_HIDDEN_FIELDS = /* @__PURE__ */ new Set([
+  "acl",
+  "serviceAccess",
+  "service_access"
+]);
+function toLabel(fieldName) {
+  return fieldName.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function getFieldType(zodType) {
+  const typeName = zodType._def.typeName;
+  if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") {
+    const inner = zodType._def.innerType;
+    return getFieldType(inner);
+  }
+  switch (typeName) {
+    case "ZodString":
+      return "string";
+    case "ZodNumber":
+      return "number";
+    case "ZodBoolean":
+      return "boolean";
+    case "ZodDate":
+      return "date";
+    case "ZodEnum":
+    case "ZodNativeEnum":
+      return "enum";
+    case "ZodObject":
+    case "ZodArray":
+    case "ZodRecord":
+      return "json";
+    default:
+      return "string";
+  }
+}
+function getEnumValues(zodType) {
+  const typeName = zodType._def.typeName;
+  if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") {
+    const inner = zodType._def.innerType;
+    return getEnumValues(inner);
+  }
+  if (typeName === "ZodEnum") {
+    return zodType._def.values;
+  }
+  if (typeName === "ZodNativeEnum") {
+    const enumObj = zodType._def.values;
+    return Object.values(enumObj).filter(
+      (v) => typeof v === "string"
+    );
+  }
+  return void 0;
+}
+function isOptional(zodType) {
+  const typeName = zodType._def.typeName;
+  if (typeName === "ZodOptional" || typeName === "ZodNullable") {
+    return true;
+  }
+  if (typeName === "ZodDefault") {
+    return true;
+  }
+  return false;
+}
+function zodToAdminFields(schema, options = {}) {
+  const { hiddenFields = [], tableColumns, fieldOverrides = {} } = options;
+  let shape = {};
+  let currentSchema = schema;
+  while (currentSchema) {
+    const typeName = currentSchema._def.typeName;
+    if (typeName === "ZodObject") {
+      shape = currentSchema._def.shape();
+      break;
+    }
+    if (typeName === "ZodEffects" || typeName === "ZodOptional" || typeName === "ZodNullable") {
+      currentSchema = currentSchema._def.schema || currentSchema._def.innerType;
+      continue;
+    }
+    break;
+  }
+  const hiddenSet = /* @__PURE__ */ new Set([...DEFAULT_HIDDEN_FIELDS, ...hiddenFields]);
+  const fields = [];
+  for (const [name, zodType] of Object.entries(shape)) {
+    if (hiddenSet.has(name)) {
+      continue;
+    }
+    const fieldType = getFieldType(zodType);
+    const required = !isOptional(zodType);
+    const editable = !NON_EDITABLE_FIELDS.has(name);
+    const enumValues = getEnumValues(zodType);
+    let showInTable = true;
+    if (tableColumns) {
+      showInTable = tableColumns.includes(name);
+    } else {
+      showInTable = fieldType !== "json";
+    }
+    const baseConfig = {
+      name,
+      type: fieldType,
+      label: toLabel(name),
+      required,
+      editable,
+      showInTable,
+      sortable: fieldType !== "json" && fieldType !== "relation",
+      enumValues
+    };
+    const override = fieldOverrides[name];
+    if (override) {
+      Object.assign(baseConfig, override);
+    }
+    fields.push(baseConfig);
+  }
+  return fields;
+}
+function getDefaultEntityFields() {
+  return [
+    {
+      name: "id",
+      type: "string",
+      label: "ID",
+      required: true,
+      editable: false,
+      showInTable: true,
+      sortable: true
+    },
+    {
+      name: "createdAt",
+      type: "date",
+      label: "Created At",
+      required: true,
+      editable: false,
+      showInTable: true,
+      sortable: true
+    },
+    {
+      name: "updatedAt",
+      type: "date",
+      label: "Updated At",
+      required: true,
+      editable: false,
+      showInTable: false,
+      sortable: true
+    }
+  ];
+}
+function mergeWithDefaultFields(schemaFields, options = {}) {
+  const { includeDefaults = ["id", "createdAt"] } = options;
+  const defaultFields = getDefaultEntityFields().filter(
+    (f) => includeDefaults.includes(f.name)
+  );
+  const defaultNames = new Set(defaultFields.map((f) => f.name));
+  const filteredSchemaFields = schemaFields.filter(
+    (f) => !defaultNames.has(f.name)
+  );
+  return [...defaultFields, ...filteredSchemaFields];
+}
+
 // src/server/BaseService.ts
 var BaseService = class {
   serviceName;
@@ -22,8 +184,12 @@ var BaseService = class {
   subscribers = /* @__PURE__ */ new Map();
   // Prisma delegate for DB operations
   delegate;
+  // Socket.io server instance for room-based broadcasts
+  io = null;
   // Collection of public methods for registry discovery
   publicMethods = /* @__PURE__ */ new Map();
+  // Admin metadata configuration (set by installAdminMethods)
+  adminMeta = null;
   constructor(options) {
     this.serviceName = options.serviceName;
     this.hasEntryACL = options.hasEntryACL ?? false;
@@ -37,6 +203,13 @@ var BaseService = class {
   setDelegate(delegate) {
     this.delegate = delegate;
   }
+  /**
+   * Set the Socket.io server instance for room-based broadcasts.
+   * Called automatically by ServiceRegistry during registration.
+   */
+  setIo(io) {
+    this.io = io;
+  }
   /**
    * Get the delegate, throwing if not set.
    */
@@ -51,9 +224,17 @@ var BaseService = class {
   // ===========================================================================
   // Subscription Management
   // ===========================================================================
+  /**
+   * Get the Socket.io room name for an entry.
+   * Used for room-based broadcasting across services.
+   */
+  getRoomName(entryId) {
+    return `${this.serviceName}:${entryId}`;
+  }
   /**
    * 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.
    */
   async subscribe(entryId, socket, requiredLevel = "Read") {
     if (!socket.userId) {
@@ -72,9 +253,14 @@ var BaseService = class {
       this.subscribers.set(entryId, /* @__PURE__ */ new Set());
     }
     this.subscribers.get(entryId).add(socket);
-    this.logger.debug(`User ${socket.userId} subscribed to ${entryId}`);
+    const roomName = this.getRoomName(entryId);
+    void socket.join(roomName);
+    this.logger.debug(
+      `User ${socket.userId} subscribed to ${entryId} (room: ${roomName})`
+    );
     const entity = await this.findById(entryId);
-    return entity;
+    if (!entity) return null;
+    return this.filterEntityForSubscriber(entity, socket, entryId);
   }
   /**
    * Unsubscribe a socket from an entity's updates.
@@ -87,6 +273,8 @@ var BaseService = class {
         this.subscribers.delete(entryId);
       }
     }
+    const roomName = this.getRoomName(entryId);
+    void socket.leave(roomName);
   }
   /**
    * Remove a socket from all subscriptions (called on disconnect).
@@ -95,22 +283,74 @@ var BaseService = class {
     for (const [entryId, sockets] of this.subscribers.entries()) {
       if (sockets.has(socket)) {
         sockets.delete(socket);
+        const roomName = this.getRoomName(entryId);
+        void socket.leave(roomName);
         if (sockets.size === 0) {
           this.subscribers.delete(entryId);
         }
       }
     }
   }
+  /**
+   * 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
+   * );
+   * ```
+   */
+  emitToRoom(roomName, eventName, data) {
+    if (this.io) {
+      this.io.to(roomName).emit(eventName, data);
+      this.logger.debug(`Emitted ${eventName} to room ${roomName}`);
+      return;
+    }
+    const anySocket = this.getAnySubscriberSocket();
+    if (!anySocket) {
+      this.logger.debug(`No sockets available to emit to room ${roomName}`);
+      return;
+    }
+    anySocket.to(roomName).emit(eventName, data);
+    this.logger.debug(
+      `Emitted ${eventName} to room ${roomName} (via socket fallback)`
+    );
+  }
+  /**
+   * Get any active socket for room-based operations.
+   */
+  getAnySubscriberSocket() {
+    for (const sockets of this.subscribers.values()) {
+      const first = sockets.values().next();
+      if (!first.done) {
+        return first.value;
+      }
+    }
+    return null;
+  }
   /**
    * 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.
    */
   emitUpdate(entryId, data) {
-    const eventName = `${this.serviceName}:update:${entryId}`;
     const subs = this.subscribers.get(entryId);
-    if (subs) {
-      for (const socket of subs) {
-        socket.emit(eventName, data);
-      }
+    if (!subs || subs.size === 0) return;
+    const eventName = `${this.serviceName}:update:${entryId}`;
+    const fullData = data;
+    const publicData = this.stripProtectedFields(data);
+    for (const socket of subs) {
+      const payload = this.hasElevatedAccess(socket, entryId) ? fullData : publicData;
+      socket.emit(eventName, payload);
     }
   }
   // ===========================================================================
@@ -206,6 +446,72 @@ var BaseService = class {
     throw new Error("Insufficient permissions");
   }
   // ===========================================================================
+  // Protected Fields Filtering
+  // ===========================================================================
+  /**
+   * 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'];
+   * }
+   * ```
+   */
+  getProtectedFields() {
+    return ["email", "serviceAccess"];
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  hasElevatedAccess(socket, entryId) {
+    return socket.userId === entryId || this.hasServiceAccess(socket, "Admin");
+  }
+  /**
+   * Strip protected fields from an entity.
+   * Used internally by filterEntityForSubscriber.
+   */
+  stripProtectedFields(entity) {
+    const protectedFields = this.getProtectedFields();
+    const result = { ...entity };
+    for (const field of protectedFields) {
+      delete result[field];
+    }
+    return result;
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  filterEntityForSubscriber(entity, socket, entryId) {
+    return this.hasElevatedAccess(socket, entryId) ? entity : this.stripProtectedFields(entity);
+  }
+  // ===========================================================================
   // CRUD Operations
   // ===========================================================================
   /**
@@ -285,14 +591,309 @@ var BaseService = class {
     return Array.from(this.publicMethods.values());
   }
   // ===========================================================================
-  // Admin Methods (Scaffolding)
+  // Admin Methods
   // ===========================================================================
   /**
    * 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",
+   * });
+   * ```
+   */
+  installAdminMethods(options) {
+    const {
+      expose,
+      access,
+      schema,
+      displayName,
+      tableColumns,
+      hiddenFields,
+      fieldOverrides
+    } = options;
+    if (schema) {
+      const schemaFields = zodToAdminFields(schema, {
+        hiddenFields,
+        tableColumns,
+        fieldOverrides
+      });
+      const fields = mergeWithDefaultFields(schemaFields);
+      this.adminMeta = {
+        serviceName: this.serviceName,
+        displayName: displayName ?? this.toDisplayName(this.serviceName),
+        fields
+      };
+    } else {
+      this.adminMeta = {
+        serviceName: this.serviceName,
+        displayName: displayName ?? this.toDisplayName(this.serviceName),
+        fields: []
+      };
+    }
+    const shouldExposeMeta = expose.meta ?? (expose.list || expose.get || expose.create || expose.update || expose.delete);
+    if (shouldExposeMeta) {
+      this.publicMethods.set("adminMeta", {
+        name: "adminMeta",
+        access: access.meta ?? access.list,
+        handler: async (_payload, _context) => {
+          return this.getAdminMeta();
+        }
+      });
+    }
+    if (expose.list) {
+      this.publicMethods.set("adminList", {
+        name: "adminList",
+        access: access.list,
+        handler: async (payload, _context) => {
+          return await this.adminList(payload);
+        }
+      });
+    }
+    if (expose.get) {
+      this.publicMethods.set("adminGet", {
+        name: "adminGet",
+        access: access.get,
+        handler: async (payload, _context) => {
+          return await this.adminGet(payload.id);
+        },
+        resolveEntryId: (payload) => payload.id
+      });
+    }
+    if (expose.create) {
+      this.publicMethods.set("adminCreate", {
+        name: "adminCreate",
+        access: access.create,
+        handler: async (payload, _context) => {
+          return await this.adminCreate(
+            payload.data
+          );
+        }
+      });
+    }
+    if (expose.update) {
+      this.publicMethods.set("adminUpdate", {
+        name: "adminUpdate",
+        access: access.update,
+        handler: async (payload, _context) => {
+          const { id, data } = payload;
+          return await this.adminUpdate(id, data);
+        },
+        resolveEntryId: (payload) => payload.id
+      });
+    }
+    if (expose.delete) {
+      this.publicMethods.set("adminDelete", {
+        name: "adminDelete",
+        access: access.delete,
+        handler: async (payload, _context) => {
+          return await this.adminDelete(payload.id);
+        },
+        resolveEntryId: (payload) => payload.id
+      });
+    }
+    if (expose.setEntryACL) {
+      this.publicMethods.set("adminSetEntryACL", {
+        name: "adminSetEntryACL",
+        access: access.setEntryACL,
+        handler: async (payload, _context) => {
+          return await this.adminSetEntryACL(payload);
+        },
+        resolveEntryId: (payload) => payload.entryId
+      });
+    }
+    if (expose.getSubscribers) {
+      this.publicMethods.set("adminGetSubscribers", {
+        name: "adminGetSubscribers",
+        access: access.getSubscribers,
+        handler: async (payload, _context) => {
+          return this.adminGetSubscribers(
+            payload.entryId
+          );
+        },
+        resolveEntryId: (payload) => payload.entryId
+      });
+    }
+    if (expose.reemit) {
+      this.publicMethods.set("adminReemit", {
+        name: "adminReemit",
+        access: access.reemit,
+        handler: async (payload, _context) => {
+          return await this.adminReemit(
+            payload.entryId
+          );
+        },
+        resolveEntryId: (payload) => payload.entryId
+      });
+    }
+    if (expose.unsubscribeAll) {
+      this.publicMethods.set("adminUnsubscribeAll", {
+        name: "adminUnsubscribeAll",
+        access: access.unsubscribeAll,
+        handler: async (payload, _context) => {
+          return this.adminUnsubscribeAll(
+            payload.entryId
+          );
+        },
+        resolveEntryId: (payload) => payload.entryId
+      });
+    }
+    const installedMethods = Object.keys(expose).filter(
+      (k) => expose[k]
+    );
+    if (shouldExposeMeta) installedMethods.push("meta");
+    this.logger.info(`Installed admin methods: ${installedMethods.join(", ")}`);
+  }
+  /**
+   * Convert service name to display name.
+   * e.g., "chatService" -> "Chats", "userService" -> "Users"
    */
-  installAdminMethods(_options) {
-    this.logger.debug("Admin methods installation placeholder");
+  toDisplayName(serviceName) {
+    return serviceName.replace(/Service$/i, "").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase()) + "s";
+  }
+  /**
+   * Get admin metadata for this service.
+   * Returns the configured metadata or throws if not configured.
+   */
+  getAdminMeta() {
+    if (!this.adminMeta) {
+      throw new Error(
+        `Admin methods not installed for ${this.serviceName}. Call installAdminMethods() first.`
+      );
+    }
+    return this.adminMeta;
+  }
+  /**
+   * Admin method: List entities with pagination and filters.
+   */
+  async adminList(payload) {
+    const { page = 1, pageSize = 20, where, orderBy } = payload;
+    const skip = (page - 1) * pageSize;
+    const [items, total] = await Promise.all([
+      this.getDelegate().findMany({
+        where,
+        orderBy,
+        skip,
+        take: pageSize
+      }),
+      this.getDelegate().count({ where })
+    ]);
+    return {
+      items,
+      total,
+      page,
+      pageSize,
+      totalPages: Math.ceil(total / pageSize)
+    };
+  }
+  /**
+   * Admin method: Get a single entity by ID.
+   */
+  async adminGet(id) {
+    return await this.findById(id);
+  }
+  /**
+   * Admin method: Create an entity.
+   */
+  async adminCreate(data) {
+    return await this.create(data);
+  }
+  /**
+   * Admin method: Update an entity.
+   */
+  async adminUpdate(id, data) {
+    return await this.update(id, data);
+  }
+  /**
+   * Admin method: Delete an entity.
+   */
+  async adminDelete(id) {
+    const deleted = await this.delete(id);
+    return { success: deleted, id };
+  }
+  /**
+   * Admin method: Set entry-level ACL.
+   */
+  async adminSetEntryACL(payload) {
+    const { entryId, acl } = payload;
+    try {
+      const entity = await this.getDelegate().update({
+        where: { id: entryId },
+        data: { acl }
+      });
+      this.emitUpdate(entryId, entity);
+      this.logger.info(`Updated ACL for entity ${entryId}`);
+      return entity;
+    } catch (error) {
+      this.logger.error(`Failed to set ACL for ${entryId}`, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return null;
+    }
+  }
+  /**
+   * Admin method: Get active subscribers for an entity.
+   */
+  adminGetSubscribers(entryId) {
+    const subs = this.subscribers.get(entryId);
+    if (!subs) {
+      return { entryId, subscribers: [], count: 0 };
+    }
+    const subscribers = Array.from(subs).map((socket) => ({
+      socketId: socket.id,
+      userId: socket.userId ?? null
+    }));
+    return {
+      entryId,
+      subscribers,
+      count: subscribers.length
+    };
+  }
+  /**
+   * Admin method: Re-emit current entity state to all subscribers.
+   * Useful when you've made direct DB changes or need to force-refresh clients.
+   */
+  async adminReemit(entryId) {
+    const entity = await this.findById(entryId);
+    if (!entity) {
+      return { success: false, subscriberCount: 0 };
+    }
+    const subs = this.subscribers.get(entryId);
+    const count = subs?.size ?? 0;
+    this.emitUpdate(entryId, entity);
+    this.logger.info(`Re-emitted entity ${entryId} to ${count} subscribers`);
+    return { success: true, subscriberCount: count };
+  }
+  /**
+   * Admin method: Unsubscribe all sockets from an entity.
+   */
+  adminUnsubscribeAll(entryId) {
+    const subs = this.subscribers.get(entryId);
+    const count = subs?.size ?? 0;
+    if (subs) {
+      const eventName = `${this.serviceName}:unsubscribed:${entryId}`;
+      for (const socket of subs) {
+        socket.emit(eventName, { reason: "admin_action" });
+      }
+      this.subscribers.delete(entryId);
+    }
+    this.logger.info(`Unsubscribed ${count} sockets from entity ${entryId}`);
+    return { success: true, unsubscribedCount: count };
   }
   // ===========================================================================
   // Utility Methods
@@ -310,47 +911,84 @@ var ServiceRegistry = class {
   io;
   services = /* @__PURE__ */ new Map();
   logger;
+  methodLoggingEnabled;
+  logPayloads;
+  logResponses;
+  connectionHandlerInstalled = false;
+  // Store method metadata for deferred registration
+  methodRegistry = /* @__PURE__ */ new Map();
   constructor(io, options) {
     this.io = io;
     this.logger = options?.logger?.child({ service: "ServiceRegistry" }) ?? consoleLogger.child({ service: "ServiceRegistry" });
+    this.methodLoggingEnabled = options?.methodLogging?.enabled ?? true;
+    this.logPayloads = options?.methodLogging?.logPayloads ?? false;
+    this.logResponses = options?.methodLogging?.logResponses ?? false;
+    if (this.methodLoggingEnabled) {
+      this.logger.info("Automatic method logging enabled", {
+        logPayloads: this.logPayloads,
+        logResponses: this.logResponses
+      });
+    }
+  }
+  /**
+   * Install the single connection handler that wires all registered services.
+   * This is called lazily on first service registration.
+   */
+  installConnectionHandler() {
+    if (this.connectionHandlerInstalled) return;
+    this.connectionHandlerInstalled = true;
+    this.io.on("connection", (socket) => {
+      const quickdrawSocket = socket;
+      this.setupSocketListeners(quickdrawSocket);
+    });
+    this.logger.info("Installed single connection handler for all services");
+  }
+  /**
+   * Set up all event listeners for a newly connected socket.
+   */
+  setupSocketListeners(socket) {
+    for (const [eventName, { method, service }] of this.methodRegistry) {
+      this.registerMethodListener(socket, eventName, method, service);
+    }
+    for (const [serviceName, service] of this.services) {
+      this.registerSubscriptionListener(
+        socket,
+        `${serviceName}:subscribe`,
+        service
+      );
+      this.registerUnsubscriptionListener(
+        socket,
+        `${serviceName}:unsubscribe`,
+        service
+      );
+    }
   }
   /**
    * Register a service and auto-discover its public methods.
    */
   registerService(serviceName, service) {
     this.services.set(serviceName, service);
+    if (service.setIo) {
+      service.setIo(this.io);
+    }
     this.logger.info(`Registered service: ${serviceName}`);
     this.discoverServiceMethods(serviceName, service);
+    this.installConnectionHandler();
   }
   /**
-   * Discover and register all public methods from a service.
+   * Discover and store all public methods from a service.
    */
   discoverServiceMethods(serviceName, service) {
     const methods = service.getPublicMethods();
     for (const method of methods) {
       const eventName = `${serviceName}:${method.name}`;
       this.logger.info(`Registering socket event: ${eventName}`);
-      this.io.on("connection", (socket) => {
-        this.registerMethodListener(
-          socket,
-          eventName,
-          method,
-          service
-        );
+      this.methodRegistry.set(eventName, {
+        serviceName,
+        method,
+        service
       });
     }
-    this.io.on("connection", (socket) => {
-      this.registerSubscriptionListener(
-        socket,
-        `${serviceName}:subscribe`,
-        service
-      );
-      this.registerUnsubscriptionListener(
-        socket,
-        `${serviceName}:unsubscribe`,
-        service
-      );
-    });
   }
   /**
    * Register a method as a socket event listener.
@@ -396,33 +1034,45 @@ var ServiceRegistry = class {
             }
           }
           await service.ensureAccessForMethod(method.access, socket, entryId);
-          this.logger.info(
-            `User ${userIdShort} ${serviceName}.${methodName} -> start`,
-            {
+          if (this.methodLoggingEnabled) {
+            const logContext = {
               category: "request_processing",
               serviceName,
               methodName,
               userId: socket.userId,
               socketId: socket.id
+            };
+            if (this.logPayloads) {
+              logContext.payload = validatedPayload;
             }
-          );
+            this.logger.info(
+              `User ${userIdShort} ${serviceName}.${methodName} -> start`,
+              logContext
+            );
+          }
           const result = await method.handler(validatedPayload, {
             userId: socket.userId,
             socketId: socket.id,
             serviceAccess: socket.serviceAccess ?? {}
           });
-          const durationMs = Date.now() - startedAt;
-          this.logger.info(
-            `User ${userIdShort} ${serviceName}.${methodName} -> success`,
-            {
+          if (this.methodLoggingEnabled) {
+            const durationMs = Date.now() - startedAt;
+            const logContext = {
               category: "request_processing",
               outcome: "success",
               durationMs,
               serviceName,
               methodName,
               userId: socket.userId
+            };
+            if (this.logResponses) {
+              logContext.response = result;
             }
-          );
+            this.logger.info(
+              `User ${userIdShort} ${serviceName}.${methodName} -> success`,
+              logContext
+            );
+          }
           const successResponse = {
             success: true,
             data: result
@@ -430,14 +1080,22 @@ var ServiceRegistry = class {
           callback?.(successResponse);
         } catch (error) {
           const durationMs = Date.now() - startedAt;
+          const logContext = {
+            category: "request_processing",
+            outcome: "fail",
+            durationMs,
+            serviceName,
+            methodName,
+            userId: socket.userId,
+            socketId: socket.id,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+          if (this.logPayloads) {
+            logContext.payload = payload;
+          }
           this.logger.error(
             `User ${userIdShort} ${serviceName}.${methodName} -> fail`,
-            {
-              category: "request_processing",
-              outcome: "fail",
-              durationMs,
-              error: error instanceof Error ? error.message : "Unknown error"
-            }
+            logContext
           );
           const errorResponse = {
             success: false,
@@ -545,7 +1203,10 @@ function createQuickdrawServer(options) {
       credentials: options.cors?.credentials ?? true
     }
   });
-  const registry = new ServiceRegistry(io, { logger });
+  const registry = new ServiceRegistry(io, {
+    logger,
+    methodLogging: options.methodLogging
+  });
   io.use(async (socket, next) => {
     const quickdrawSocket = socket;
     try {
@@ -592,8 +1253,246 @@ function createQuickdrawServer(options) {
       `Registered services: ${registry.getServices().join(", ")}`
     );
   });
+  const shutdown = async (signal) => {
+    serverLogger.info(`Received ${signal}, starting graceful shutdown...`);
+    httpServer.close(() => {
+      serverLogger.info("HTTP server closed");
+    });
+    const sockets = await io.fetchSockets();
+    serverLogger.info(`Closing ${sockets.length} active socket connections...`);
+    for (const socket of sockets) {
+      const quickdrawSocket = socket;
+      for (const service of registry.getServiceInstances()) {
+        try {
+          service.unsubscribeSocket(quickdrawSocket);
+        } catch {
+        }
+      }
+      socket.disconnect(true);
+    }
+    io.close(() => {
+      serverLogger.info("Socket.io server closed");
+      process.exit(0);
+    });
+    setTimeout(() => {
+      serverLogger.error("Graceful shutdown timeout, forcing exit");
+      process.exit(1);
+    }, 1e4);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
   return { io, httpServer, registry };
 }
+
+// src/server/redis.ts
+async function setupRedisAdapter(io, options = {}) {
+  const logger = options.logger?.child({ service: "RedisAdapter" }) ?? consoleLogger.child({ service: "RedisAdapter" });
+  const {
+    host = "localhost",
+    port = 6379,
+    password,
+    db = 0,
+    keyPrefix = "socket.io"
+  } = options;
+  try {
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    const [redisAdapterModule, redisModule] = await Promise.all([
+      dynamicImport("@socket.io/redis-adapter"),
+      dynamicImport("redis")
+    ]);
+    const createAdapter = redisAdapterModule.createAdapter;
+    const createClient = redisModule.createClient;
+    const pubClient = createClient({
+      socket: { host, port },
+      password,
+      database: db
+    });
+    const subClient = pubClient.duplicate();
+    await Promise.all([pubClient.connect(), subClient.connect()]);
+    io.adapter(createAdapter(pubClient, subClient, { key: keyPrefix }));
+    logger.info(`Redis adapter connected to ${host}:${port}`);
+    const cleanup = async () => {
+      try {
+        await Promise.all([pubClient.quit(), subClient.quit()]);
+        logger.info("Redis adapter disconnected");
+      } catch (error) {
+        logger.error("Error disconnecting Redis adapter", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    };
+    return { success: true, cleanup };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("Cannot find module") || errorMessage.includes("MODULE_NOT_FOUND")) {
+      logger.warn(
+        "Redis adapter packages not installed. Install @socket.io/redis-adapter and redis for horizontal scaling support."
+      );
+    } else {
+      logger.error("Failed to set up Redis adapter", { error: errorMessage });
+    }
+    return {
+      success: false,
+      cleanup: async () => {
+      }
+    };
+  }
+}
+async function isRedisAdapterAvailable() {
+  try {
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    await Promise.all([
+      dynamicImport("@socket.io/redis-adapter"),
+      dynamicImport("redis")
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/server/rateLimit.ts
+function createRateLimiter(options = {}) {
+  const {
+    windowMs = 6e4,
+    maxRequests = 100,
+    excludeEvents = []
+  } = options;
+  const entries = /* @__PURE__ */ new Map();
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of entries) {
+      if (entry.resetAt <= now) {
+        entries.delete(key);
+      }
+    }
+  }, windowMs);
+  if (cleanupInterval.unref) {
+    cleanupInterval.unref();
+  }
+  return {
+    check(key) {
+      const now = Date.now();
+      const entry = entries.get(key);
+      if (!entry || entry.resetAt <= now) {
+        entries.set(key, {
+          count: 1,
+          resetAt: now + windowMs
+        });
+        return true;
+      }
+      if (entry.count >= maxRequests) {
+        return false;
+      }
+      entry.count++;
+      return true;
+    },
+    getRemaining(key) {
+      const now = Date.now();
+      const entry = entries.get(key);
+      if (!entry || entry.resetAt <= now) {
+        return maxRequests;
+      }
+      return Math.max(0, maxRequests - entry.count);
+    },
+    getResetTime(key) {
+      const now = Date.now();
+      const entry = entries.get(key);
+      if (!entry || entry.resetAt <= now) {
+        return 0;
+      }
+      return entry.resetAt - now;
+    },
+    clear() {
+      entries.clear();
+    },
+    options: {
+      windowMs,
+      maxRequests,
+      excludeEvents
+    }
+  };
+}
+function applyRateLimitMiddleware(io, rateLimiter, options = {}) {
+  const logger = options.logger?.child({ service: "RateLimiter" }) ?? consoleLogger.child({ service: "RateLimiter" });
+  const keyGenerator = options.keyGenerator ?? ((socket) => socket.id);
+  const onRateLimitExceeded = options.onRateLimitExceeded ?? ((socket, eventName) => {
+    socket.emit("error", {
+      code: "RATE_LIMITED",
+      message: `Rate limit exceeded for event: ${eventName}`,
+      retryAfter: rateLimiter.getResetTime(keyGenerator(socket, eventName))
+    });
+  });
+  const { excludeEvents } = rateLimiter.options;
+  io.on("connection", (socket) => {
+    socket.use(([eventName, ...args], next) => {
+      if (excludeEvents.includes(eventName)) {
+        next();
+        return;
+      }
+      if (eventName.startsWith("$")) {
+        next();
+        return;
+      }
+      const key = keyGenerator(socket, eventName);
+      if (rateLimiter.check(key)) {
+        next();
+      } else {
+        logger.warn(`Rate limit exceeded for socket ${socket.id} on event ${eventName}`);
+        onRateLimitExceeded(socket, eventName);
+        const lastArg = args[args.length - 1];
+        if (typeof lastArg === "function") {
+          lastArg({
+            success: false,
+            error: "Rate limit exceeded",
+            code: 429
+          });
+        }
+      }
+    });
+  });
+  logger.info(
+    `Rate limiting enabled: ${rateLimiter.options.maxRequests} requests per ${rateLimiter.options.windowMs}ms`
+  );
+}
+function createTieredRateLimiter(tiers, defaultOptions = {}) {
+  const tierLimiters = /* @__PURE__ */ new Map();
+  const tierPatterns = [];
+  for (const [pattern, options] of Object.entries(tiers)) {
+    const limiter = createRateLimiter({ ...defaultOptions, ...options });
+    tierLimiters.set(pattern, limiter);
+    const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+    tierPatterns.push({
+      pattern: new RegExp(`^${regexPattern}$`),
+      limiter
+    });
+  }
+  const defaultLimiter = createRateLimiter(defaultOptions);
+  function getLimiterForEvent(eventName) {
+    for (const { pattern, limiter } of tierPatterns) {
+      if (pattern.test(eventName)) {
+        return limiter;
+      }
+    }
+    return defaultLimiter;
+  }
+  return {
+    check(key, eventName) {
+      const limiter = getLimiterForEvent(eventName);
+      return limiter.check(`${key}:${eventName}`);
+    },
+    getRemaining(key, eventName) {
+      const limiter = getLimiterForEvent(eventName);
+      return limiter.getRemaining(`${key}:${eventName}`);
+    },
+    clear() {
+      for (const limiter of tierLimiters.values()) {
+        limiter.clear();
+      }
+      defaultLimiter.clear();
+    }
+  };
+}
 var DEFAULT_EXPIRATION = "7d";
 async function createJWT(payload, secret, expiresIn = DEFAULT_EXPIRATION) {
   const secretKey = new TextEncoder().encode(secret);
@@ -702,6 +1601,45 @@ var googleProvider = {
   }
 };
 
-export { BaseService, ServiceRegistry, createJWT, createOAuthURL, createQuickdrawServer, discordProvider, exchangeOAuthCode, googleProvider, verifyJWT };
+// src/server/utils/env.ts
+function validateEnv(options) {
+  const result = checkEnv(options);
+  if (!result.success) {
+    throw new Error(result.message);
+  }
+}
+function checkEnv(options) {
+  const { required, productionOnly = true, errorPrefix = "Missing required environment variables" } = options;
+  if (productionOnly && process.env.NODE_ENV !== "production") {
+    return { success: true, missing: [] };
+  }
+  const missing = [];
+  for (const varName of required) {
+    const value = process.env[varName];
+    if (!value || value.trim() === "") {
+      missing.push(varName);
+    }
+  }
+  if (missing.length > 0) {
+    return {
+      success: false,
+      missing,
+      message: `${errorPrefix}: ${missing.join(", ")}`
+    };
+  }
+  return { success: true, missing: [] };
+}
+function requireEnv(name, defaultValue) {
+  const value = process.env[name];
+  if (!value || value.trim() === "") {
+    if (defaultValue !== void 0) {
+      return defaultValue;
+    }
+    throw new Error(`Environment variable ${name} is required but not set`);
+  }
+  return value;
+}
+
+export { BaseService, ServiceRegistry, applyRateLimitMiddleware, checkEnv, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, getDefaultEntityFields, googleProvider, isRedisAdapterAvailable, mergeWithDefaultFields, requireEnv, setupRedisAdapter, validateEnv, verifyJWT, zodToAdminFields };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map