@fitzzero/quickdraw-core 1.0.0 → 1.2.0

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-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-CDhCEpTU.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 { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
 import 'http';
 
 /**
@@ -54,6 +54,7 @@ declare abstract class BaseService<TEntity extends {
     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.
@@ -242,10 +243,22 @@ declare abstract class BaseService<TEntity extends {
      *     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.
      */
@@ -315,15 +328,28 @@ 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;
+    private readonly methodLoggingEnabled;
+    private readonly logPayloads;
+    private readonly logResponses;
     private connectionHandlerInstalled;
     private readonly methodRegistry;
-    constructor(io: Server, options?: {
-        logger?: Logger;
-    });
+    constructor(io: Server, options?: ServiceRegistryOptions);
     /**
      * Install the single connection handler that wires all registered services.
      * This is called lazily on first service registration.
@@ -745,4 +771,134 @@ interface GoogleUser {
  */
 declare const googleProvider: OAuthProvider<GoogleUser>;
 
-export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, 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, applyRateLimitMiddleware, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, googleProvider, isRedisAdapterAvailable, setupRedisAdapter, 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 };

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