feat: introduce SERVER_ENV variable and enhance environment validation for startup requirements

Author: mitchdowney

.env.example

@@ -11,6 +11,7 @@
 #####
 
 NODE_ENV=development
+SERVER_ENV=local # prod, beta, alpha, local
 LOG_LEVEL=info
 
 #####
@@ -20,7 +21,7 @@ LOG_LEVEL=info
 API_PORT=1234
 API_PREFIX=/api
 API_VERSION=/v2
-API_ALLOWED_CORS_ORIGINS=http://localhost:3000,https://api.podverse.fm,https://podverse.fm
+API_ALLOWED_CORS_ORIGINS=http://localhost:3000
 
 # REQUIRED: Must be a valid UUID (the API will not start without a valid UUID)
 # Generate one using: uuidgen (macOS/Linux) or https://www.uuidgenerator.net/

ENV.md

@@ -49,6 +49,12 @@ These variables are **always required** regardless of configuration:
 - **`COOKIE_DOMAIN`** (Required) - Domain for cookies
 - **`API_ALLOWED_CORS_ORIGINS`** (Required) - Comma-separated list of allowed CORS origins (must contain at least one origin)
 
+### App / General
+
+- **`SERVER_ENV`** (Required) - Server environment
+  - Must be one of: `prod`, `beta`, `alpha`, `local`
+  - Controls environment-specific behavior (e.g., bypassing free trial restrictions in non-production environments)
+
 ### Web
 
 - **`WEB_PROTOCOL`** (Required) - Web protocol (`http` or `https`)

src/config/index.ts

@@ -7,6 +7,7 @@ type SocialConfig = {
 
 type Config = {
   nodeEnv: string;
+  serverEnv: string;
   userAgent: string;
   log: {
     level: string;
@@ -97,6 +98,7 @@ type Config = {
 
 export const config: Config = {
   nodeEnv: process.env.NODE_ENV!,
+  serverEnv: process.env.SERVER_ENV!,
   userAgent: process.env.USER_AGENT!,
   log: {
     level: process.env.LOG_LEVEL!

src/index.ts

@@ -19,6 +19,7 @@ import { loggerService } from './factories/loggerService';
 import { activeMQArtemisService } from './factories/activeMQArtemisService';
 import { testKeyvaldbConnection, keyvaldb } from './lib/keyvaldb/keyvaldb';
 import { config } from './config';
+import { validateStartupRequirements } from './lib/startup/validation';
 
 let serverInstance: import('http').Server | null = null;
 
@@ -66,6 +67,9 @@ process.on('SIGTERM', () => void shutdown('SIGTERM'));
 
 (async () => {
   try {
+    // Validate podverse-api environment variables first
+    validateStartupRequirements();
+
     // Build module configs from app config
     const ormConfig = {
       nodeEnv: config.nodeEnv,

src/lib/auth/index.ts

@@ -180,10 +180,13 @@ const verifyTokenAndMembership = async (
         return res.status(403).json({ message: 'Membership expired' });
       }
 
-      if (options.noFreeTrial) {
+      if (options.noFreeTrial && config.serverEnv === 'prod') {
         const accountMembership = membershipStatus.account_membership;
         if (accountMembership && accountMembership.id === AccountMembershipEnum.Trial) {
-          return res.status(403).json({ message: 'This feature is only available to premium accounts and is not available to free trials' });
+          return res.status(403).json({ 
+            message: 'This feature is only available to premium accounts and is not available to free trials',
+            i18nKey: 'membership.free_trial_not_allowed'
+          });
         }
       }
     }

src/lib/startup/validation.ts

@@ -1,4 +1,4 @@
-import { isValidUUID, AccountSignupMode, ValidationResult, ValidationSummary, validateRequired, validateOptional, validateConditionalOptional } from 'podverse-helpers';
+import { isValidUUID, AccountSignupMode, ValidationResult, ValidationSummary, validateRequired, validateOptional, validateConditionalOptional, SERVER_ENV_VALUES, isValidServerEnv } from 'podverse-helpers';
 import { loggerService } from '@api/factories/loggerService';
 
 /**
@@ -165,15 +165,16 @@ const validateAllEnvironmentVariables = (): ValidationSummary => {
 
   // General
   results.push(validateOptional('NODE_ENV', 'General'));
+  results.push(validateServerEnv());
   results.push(validateOptional('LOG_LEVEL', 'General'));
 
   // Calculate summary
   const total = results.length;
   const passed = results.filter(r => r.isValid && r.isSet).length;
   const failed = results.filter(r => !r.isValid).length;
   const requiredMissing = results.filter(r => r.isRequired && !r.isValid).length;
-  // Count as skipped only if not set and message is "Skipped" (exclude "Use Default" and "Blank")
-  const skipped = results.filter(r => !r.isRequired && !r.isSet && r.message === 'Skipped').length;
+  // Count as skipped all optional variables that are not set (regardless of message)
+  const skipped = results.filter(r => !r.isRequired && !r.isSet).length;
   // Count defaults used (passed validations with "Use Default" or "Blank" messages)
   const defaultsUsed = results.filter(r => r.isValid && r.isSet && (r.message.includes('Use Default') || r.message === 'Blank')).length;
 
@@ -283,6 +284,48 @@ const validateUserAgent = (): ValidationResult => {
   };
 };
 
+/**
+ * Validates SERVER_ENV
+ */
+const validateServerEnv = (): ValidationResult => {
+  const serverEnv = process.env.SERVER_ENV || '';
+  
+  // Fallback values in case import fails (should match podverse-helpers)
+  const validEnvs = SERVER_ENV_VALUES || ['prod', 'beta', 'alpha', 'local'];
+  const validateEnv = isValidServerEnv || ((value: string) => validEnvs.includes(value));
+
+  if (!serverEnv) {
+    return {
+      name: 'SERVER_ENV',
+      isSet: false,
+      isValid: false,
+      isRequired: true,
+      message: `Missing - must be one of: ${validEnvs.join(', ')}`,
+      category: 'General'
+    };
+  }
+
+  if (!validateEnv(serverEnv)) {
+    return {
+      name: 'SERVER_ENV',
+      isSet: true,
+      isValid: false,
+      isRequired: true,
+      message: `Invalid value: "${serverEnv}" - must be one of: ${validEnvs.join(', ')}`,
+      category: 'General'
+    };
+  }
+
+  return {
+    name: 'SERVER_ENV',
+    isSet: true,
+    isValid: true,
+    isRequired: true,
+    message: `Set to "${serverEnv}"`,
+    category: 'General'
+  };
+};
+
 /**
  * Validates ACCOUNT_SIGNUP_MODE
  */