@fitzzero/quickdraw-core 1.0.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;
@@ -26,6 +188,8 @@ var BaseService = class {
   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;
@@ -448,11 +612,50 @@ var BaseService = class {
    *     reemit: "Admin",
    *     unsubscribeAll: "Admin",
    *   },
+   *   schema: createEntitySchema,
+   *   displayName: "Entities",
    * });
    * ```
    */
   installAdminMethods(options) {
-    const { expose, access } = 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",
@@ -550,9 +753,30 @@ var BaseService = class {
         resolveEntryId: (payload) => payload.entryId
       });
     }
-    this.logger.info(
-      `Installed admin methods: ${Object.keys(expose).filter((k) => expose[k]).join(", ")}`
+    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"
+   */
+  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.
@@ -687,12 +911,24 @@ 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.
@@ -798,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
@@ -832,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,
@@ -947,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 {
@@ -994,6 +1253,34 @@ 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 };
 }
 
@@ -1314,6 +1601,45 @@ var googleProvider = {
   }
 };
 
-export { BaseService, ServiceRegistry, applyRateLimitMiddleware, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, googleProvider, isRedisAdapterAvailable, setupRedisAdapter, 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