@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/system/unified-interface/shared/endpoints/route/multi.ts

@@ -0,0 +1,184 @@
+import "server-only";
+
+/**
+ * Endpoint Handler Implementation
+ * Main function for creating type-safe multi-method handlers
+ */
+import type { ResponseType } from "next-vibe/shared/types/response.schema";
+
+import type { UserRoleValue } from "@/app/api/[locale]/user/user-roles/enum";
+import type { CountryLanguage } from "@/i18n/core/config";
+
+import type { CreateApiEndpointAny } from "../../types/endpoint";
+import { Methods } from "../../types/enums";
+import type {
+  GenericHandlerReturnType as GenericHandlerReturnTypeImport,
+  MethodHandlerConfig,
+} from "./handler";
+import { endpointHandler } from "./single";
+
+/**
+ * Base constraint for endpoint definitions
+ * All endpoint objects must be a partial record of Methods to CreateApiEndpoint
+ */
+export type EndpointDefinitionsConstraint = Partial<
+  Record<Methods, CreateApiEndpointAny>
+>;
+
+/**
+ * Type-safe configuration that enforces handler types match endpoint types
+ * Uses conditional types to extract exact types from each endpoint
+ * Only requires handlers for methods that exist in the endpoint definition
+ * Handlers receive OUTPUT types (validated data) and return OUTPUT types
+ */
+export type EndpointHandlerConfig<T extends EndpointDefinitionsConstraint> = {
+  endpoint: T;
+} & {
+  [K in Methods]?: K extends keyof T
+    ? T[K] extends CreateApiEndpointAny
+      ? MethodHandlerConfig<
+          T[K]["types"]["RequestOutput"],
+          T[K]["types"]["ResponseOutput"],
+          T[K]["types"]["UrlVariablesOutput"],
+          T[K]["allowedRoles"]
+        >
+      : never
+    : never;
+};
+
+/**
+ * Type for tools object exported from route handlers
+ * Contains method handlers (GET, POST, etc.) with their specific types
+ * T must be a partial record of Methods to endpoint definitions with proper structure
+ */
+export type ToolsObject<T extends EndpointDefinitionsConstraint> = {
+  [K in keyof T]: T[K] extends CreateApiEndpointAny
+    ? GenericHandlerReturnTypeImport<
+        T[K]["types"]["RequestOutput"],
+        T[K]["types"]["ResponseOutput"],
+        T[K]["types"]["UrlVariablesOutput"],
+        T[K]["allowedRoles"]
+      >
+    : never;
+};
+
+/**
+ * Return type for endpointsHandler with proper Next.js handler types
+ * CLI handlers receive RAW input data (TRequestOutput, TUrlVariablesOutput)
+ * tRPC handlers receive RAW input data (TRequestOutput, TUrlVariablesOutput)
+ * Next.js handlers work with raw request objects
+ * All return VALIDATED response data (TResponseOutput)
+ */
+type EndpointsHandlerReturn<T extends EndpointDefinitionsConstraint> = {
+  [K in keyof T]: undefined;
+} & {
+  tools: ToolsObject<T>;
+};
+
+/**
+ * Creates handlers for multiple HTTP methods from endpoint definitions
+ * Returns an object with Next.js handlers, generic tool handlers, and definitions
+ *
+ * Note: We use direct endpointHandler calls instead of a helper function because
+ * endpointHandler has complex type inference that extracts types from the endpoint.
+ * TypeScript can properly infer types when we call endpointHandler directly with
+ * the specific endpoint and handler, but not when we try to abstract it into a
+ * generic helper function.
+ */
+export function endpointsHandler<const T extends EndpointDefinitionsConstraint>(
+  config: EndpointHandlerConfig<T>,
+): EndpointsHandlerReturn<T> {
+  const { endpoint: definitions, ...methodConfigs } = config;
+
+  // Build the result object dynamically with flexible typing
+  // We construct the result object gradually and assert the final type at return
+  // This pattern is necessary because TypeScript cannot properly track conditional
+  // types during dynamic object construction
+  type FlexibleResult = Record<string, undefined> & {
+    tools: Record<
+      string,
+      GenericHandlerReturnTypeImport<
+        Record<string, string | number | boolean>,
+        ResponseType<Record<string, string | number | boolean>>,
+        Record<string, string> & { locale: CountryLanguage },
+        readonly UserRoleValue[]
+      >
+    >;
+  };
+
+  const result: FlexibleResult = {
+    tools: {} as FlexibleResult["tools"],
+  } as FlexibleResult;
+
+  // Process GET method
+  if (Methods.GET in definitions && Methods.GET in methodConfigs) {
+    const endpoint = definitions[Methods.GET];
+    const methodConfig = methodConfigs[Methods.GET];
+    if (endpoint && methodConfig && "handler" in methodConfig) {
+      const handler = endpointHandler({
+        endpoint,
+        handler: methodConfig.handler,
+      });
+      result[Methods.GET] = undefined;
+      result.tools[Methods.GET] = handler.tools[Methods.GET];
+    }
+  }
+
+  // Process POST method
+  if (Methods.POST in definitions && Methods.POST in methodConfigs) {
+    const endpoint = definitions[Methods.POST];
+    const methodConfig = methodConfigs[Methods.POST];
+    if (endpoint && methodConfig && "handler" in methodConfig) {
+      const handler = endpointHandler({
+        endpoint,
+        handler: methodConfig.handler,
+      });
+      result[Methods.POST] = undefined;
+      result.tools[Methods.POST] = handler.tools[Methods.POST];
+    }
+  }
+
+  // Process PUT method
+  if (Methods.PUT in definitions && Methods.PUT in methodConfigs) {
+    const endpoint = definitions[Methods.PUT];
+    const methodConfig = methodConfigs[Methods.PUT];
+    if (endpoint && methodConfig && "handler" in methodConfig) {
+      const handler = endpointHandler({
+        endpoint,
+        handler: methodConfig.handler,
+      });
+      result[Methods.PUT] = handler[Methods.PUT];
+      result.tools[Methods.PUT] = handler.tools[Methods.PUT];
+    }
+  }
+
+  // Process PATCH method
+  if (Methods.PATCH in definitions && Methods.PATCH in methodConfigs) {
+    const endpoint = definitions[Methods.PATCH];
+    const methodConfig = methodConfigs[Methods.PATCH];
+    if (endpoint && methodConfig && "handler" in methodConfig) {
+      const handler = endpointHandler({
+        endpoint,
+        handler: methodConfig.handler,
+      });
+      result[Methods.PATCH] = handler[Methods.PATCH];
+      result.tools[Methods.PATCH] = handler.tools[Methods.PATCH];
+    }
+  }
+
+  // Process DELETE method
+  if (Methods.DELETE in definitions && Methods.DELETE in methodConfigs) {
+    const endpoint = definitions[Methods.DELETE];
+    const methodConfig = methodConfigs[Methods.DELETE];
+    if (endpoint && methodConfig && "handler" in methodConfig) {
+      const handler = endpointHandler({
+        endpoint,
+        handler: methodConfig.handler,
+      });
+      result[Methods.DELETE] = handler[Methods.DELETE];
+      result.tools[Methods.DELETE] = handler.tools[Methods.DELETE];
+    }
+  }
+
+  return result as EndpointsHandlerReturn<T>;
+}

package/src/app/api/[locale]/system/unified-interface/shared/endpoints/route/request-validator.ts

@@ -0,0 +1,201 @@
+/**
+ * Core Validation Module
+ * Generic validation utilities used by all handler types
+ * Platform-specific validation logic should be in respective handler folders
+ */
+
+import "server-only";
+
+import {
+  ErrorResponseTypes,
+  fail,
+  type ResponseType,
+  success,
+} from "next-vibe/shared/types/response.schema";
+import { parseError, validateData } from "next-vibe/shared/utils";
+import { z } from "zod";
+
+import type { CountryLanguage } from "@/i18n/core/config";
+import { CountryLanguageValues } from "@/i18n/core/config";
+
+import type { EndpointLogger } from "../../logger/endpoint";
+import type { Methods } from "../../types/enums";
+
+/**
+ * Validate locale using the standard schema
+ */
+export function validateLocale(
+  locale: CountryLanguage,
+  logger: EndpointLogger,
+): ResponseType<CountryLanguage> {
+  const localeValidation = validateData(
+    locale,
+    z.enum(CountryLanguageValues).optional(),
+    logger,
+  );
+  const validatedLocale = localeValidation.success
+    ? localeValidation.data
+    : undefined;
+  if (!validatedLocale) {
+    logger.error("Invalid locale provided:", locale);
+    return fail({
+      message: ErrorResponseTypes.INVALID_REQUEST_ERROR.errorKey,
+      errorType: ErrorResponseTypes.INVALID_REQUEST_ERROR,
+      messageParams: {
+        error: "Invalid locale provided",
+      },
+    });
+  }
+  return success(validatedLocale);
+}
+
+/**
+ * CLI validation context
+ */
+export interface HandlerValidationContext<TRequestData, TUrlParameters> {
+  /** HTTP method being used */
+  method: Methods;
+  /** Direct request data */
+  requestData: TRequestData;
+  /** Direct URL parameters */
+  urlParameters: TUrlParameters;
+  /** Locale for error messages */
+  locale: CountryLanguage;
+}
+
+/**
+ * Validated request data - contains validated data (OUTPUT types) ready for handler
+ * This represents the final validated data that domain handlers receive
+ */
+export interface ValidatedRequestData<TRequestOutput, TUrlVariablesOutput> {
+  /** Validated request data (OUTPUT type - what handlers receive) */
+  requestData: TRequestOutput;
+  /** Validated URL parameters (OUTPUT type - what handlers receive) */
+  urlPathParams: TUrlVariablesOutput;
+  /** Validated locale */
+  locale: CountryLanguage;
+}
+
+/**
+ * Validate CLI request data
+ * Types flow naturally from schemas - no explicit type parameters needed
+ */
+export function validateHandlerRequestData<
+  TRequestSchema extends z.ZodTypeAny,
+  TUrlSchema extends z.ZodTypeAny,
+>(
+  endpoint: {
+    requestSchema: TRequestSchema;
+    requestUrlPathParamsSchema: TUrlSchema;
+  },
+  context: HandlerValidationContext<
+    z.input<TRequestSchema>,
+    z.input<TUrlSchema>
+  >,
+  logger: EndpointLogger,
+): ResponseType<
+  ValidatedRequestData<z.output<TRequestSchema>, z.output<TUrlSchema>>
+> {
+  try {
+    // Validate locale
+    const localeResult = validateLocale(context.locale, logger);
+    if (!localeResult.success) {
+      return localeResult;
+    }
+    const validatedLocale = localeResult.data;
+
+    const urlValidation = validateData(
+      context.urlParameters,
+      endpoint.requestUrlPathParamsSchema,
+      logger,
+    );
+    if (!urlValidation.success) {
+      logger.error("URL validation failed", {
+        error: urlValidation.message,
+        messageParams: urlValidation.messageParams,
+      });
+      return {
+        success: false,
+        message: ErrorResponseTypes.INVALID_QUERY_ERROR.errorKey,
+        errorType: ErrorResponseTypes.INVALID_QUERY_ERROR,
+        messageParams: {
+          error: urlValidation.message,
+        },
+      };
+    }
+
+    // Now validate the final merged data
+    const requestValidation = validateData(
+      context.requestData,
+      endpoint.requestSchema,
+      logger,
+    );
+    if (!requestValidation.success) {
+      logger.error("Request validation failed", {
+        error: requestValidation.message,
+        messageParams: requestValidation.messageParams,
+      });
+      return {
+        success: false,
+        message: ErrorResponseTypes.INVALID_REQUEST_ERROR.errorKey,
+        errorType: ErrorResponseTypes.INVALID_REQUEST_ERROR,
+        messageParams: {
+          error: requestValidation.message,
+        },
+        cause: requestValidation,
+      };
+    }
+
+    return {
+      success: true,
+      data: {
+        requestData: requestValidation.data,
+        urlPathParams: urlValidation.data,
+        locale: validatedLocale,
+      },
+    };
+  } catch (error) {
+    logger.error("Request validation failed", parseError(error));
+    return {
+      success: false,
+      message: ErrorResponseTypes.INVALID_REQUEST_ERROR.errorKey,
+      errorType: ErrorResponseTypes.INVALID_REQUEST_ERROR,
+      messageParams: {
+        error: parseError(error).message,
+      },
+    };
+  }
+}
+
+/**
+ * Validate response data against endpoint schema
+ * Returns validated data or error
+ */
+export function validateResponseData<TResponseOutput>(
+  // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Schema validation: Response data can be any type until validated against schema, so unknown is correct.
+  data: unknown,
+  schema: z.ZodTypeAny,
+  logger: EndpointLogger,
+): ResponseType<TResponseOutput> {
+  const validation = validateData(data, schema, logger);
+
+  if (!validation.success) {
+    logger.error("[Request Validator] Response validation failed", {
+      error: validation.message,
+      messageParams: validation.messageParams,
+    });
+    return {
+      success: false,
+      message: "app.api.shared.errorTypes.invalid_response_error",
+      errorType: ErrorResponseTypes.INVALID_RESPONSE_ERROR,
+      messageParams: {
+        error: validation.message,
+      },
+    };
+  }
+
+  return {
+    success: true,
+    data: validation.data as TResponseOutput,
+  };
+}

package/src/app/api/[locale]/system/unified-interface/shared/endpoints/route/single.ts

@@ -0,0 +1,58 @@
+/**
+ * API Handler Implementation
+ * Main function for creating API handlers that support Next.js, tRPC, and CLI
+ */
+
+import "server-only";
+
+import type { CreateApiEndpointAny } from "../../types/endpoint";
+import {
+  type ApiHandlerOptions,
+  createGenericHandler,
+  type GenericHandlerReturnType,
+} from "./handler";
+
+/**
+ * API handler return type that supports both Next.js and tRPC
+ */
+type EndpointHandlerReturn<TEndpoint extends CreateApiEndpointAny> = {
+  [K in TEndpoint["method"]]: undefined;
+} & {
+  tools: {
+    [K in TEndpoint["method"]]: GenericHandlerReturnType<
+      TEndpoint["types"]["RequestOutput"],
+      TEndpoint["types"]["ResponseOutput"],
+      TEndpoint["types"]["UrlVariablesOutput"],
+      TEndpoint["allowedRoles"]
+    >;
+  };
+  definitions: TEndpoint;
+};
+
+/**
+ * Create an API route handler that supports both Next.js, tRPC, and CLI
+ * @param options - API handler options
+ * @returns Object with both Next.js handler, tRPC procedure, and CLI handler
+ *
+ * Type parameters are inferred from options.endpoint.types for proper type flow
+ */
+export function endpointHandler<T extends CreateApiEndpointAny>(
+  options: ApiHandlerOptions<
+    T["types"]["RequestOutput"],
+    T["types"]["ResponseOutput"],
+    T["types"]["UrlVariablesOutput"],
+    T["allowedRoles"],
+    T
+  >,
+): EndpointHandlerReturn<T> {
+  const genericHandler = createGenericHandler(options);
+  const method = options.endpoint.method;
+
+  return {
+    [method]: undefined!,
+    tools: {
+      [method]: genericHandler,
+    },
+    definitions: options.endpoint,
+  } as EndpointHandlerReturn<T>;
+}

package/src/app/api/[locale]/system/unified-interface/shared/env/define-env-client.ts

@@ -0,0 +1,49 @@
+/**
+ * Client Environment Definition
+ * Enforces explicit process.env references for Next.js bundler
+ */
+
+import type { z } from "zod";
+import { z as zod } from "zod";
+
+interface FieldDef<T extends z.ZodTypeAny = z.ZodTypeAny> {
+  schema: T;
+  value: z.input<T>; // Must pass explicit process.env.VAR_NAME
+  example: string;
+  comment?: string;
+}
+
+type Fields = Record<string, FieldDef>;
+
+type InferEnv<T extends Fields> = {
+  [K in keyof T]: z.infer<T[K]["schema"]>;
+};
+
+/**
+ * Define client environment with explicit process.env references
+ *
+ * @example
+ * export const { env } = defineEnvClient({
+ *   NEXT_PUBLIC_APP_URL: {
+ *     schema: z.string().url(),
+ *     value: process.env.NEXT_PUBLIC_APP_URL,  // Required for bundler
+ *     example: "http://localhost:3000"
+ *   },
+ * });
+ */
+export function defineEnvClient<T extends Fields>(
+  fields: T,
+): { envClient: InferEnv<T> } {
+  const schemaShape = Object.fromEntries(
+    Object.entries(fields).map(([key, def]) => [key, def.schema]),
+  );
+  const schema = zod.object(schemaShape);
+
+  const values = Object.fromEntries(
+    Object.entries(fields).map(([key, def]) => [key, def.value]),
+  );
+
+  const envClient = schema.parse(values) as InferEnv<T>;
+
+  return { envClient };
+}

package/src/app/api/[locale]/system/unified-interface/shared/env/define-env.ts

@@ -0,0 +1,47 @@
+/**
+ * Minimal Environment Definition
+ */
+
+import "server-only";
+
+import { validateEnv } from "next-vibe/shared/utils/env-util";
+import type { z } from "zod";
+import { z as zod } from "zod";
+
+import { envValidationLogger } from "./validation-logger";
+
+interface FieldDef<T extends z.ZodTypeAny = z.ZodTypeAny> {
+  schema: T;
+  example: string;
+  comment?: string;
+}
+
+type Fields = Record<string, FieldDef>;
+
+type InferEnv<T extends Fields> = {
+  [K in keyof T]: z.infer<T[K]["schema"]>;
+};
+
+/**
+ * Define and validate environment variables
+ *
+ * @example
+ * export const { env } = defineEnv({
+ *   DATABASE_URL: { schema: z.string().url(), example: "postgres://localhost/db", comment: "DB" },
+ *   API_KEY: { schema: z.string().min(10), example: "your-api-key" },
+ * });
+ */
+export function defineEnv<T extends Fields>(fields: T): { env: InferEnv<T> } {
+  const schemaShape = Object.fromEntries(
+    Object.entries(fields).map(([key, def]) => [key, def.schema]),
+  );
+  const schema = zod.object(schemaShape);
+
+  const env = validateEnv(
+    process.env,
+    schema,
+    envValidationLogger,
+  ) as InferEnv<T>;
+
+  return { env };
+}

package/src/app/api/[locale]/system/unified-interface/shared/env/validation-logger.ts

@@ -0,0 +1,58 @@
+/**
+ * Environment Validation Logger
+ * Simple logger for environment validation that works in both browser and server contexts
+ */
+
+import type { ExplicitAnyType } from "next-vibe/shared/types/utils";
+
+import type { EndpointLogger } from "@/app/api/[locale]/system/unified-interface/shared/logger/endpoint";
+
+declare const process: {
+  env: {
+    [key: string]: string | undefined;
+  };
+  stdout: {
+    write: (message: string) => boolean;
+  };
+  stderr: {
+    write: (message: string) => boolean;
+  };
+};
+
+/**
+ * Simple logger for environment validation
+ * Works in both browser and server contexts
+ */
+export const envValidationLogger: EndpointLogger = {
+  info: (message: string, meta?: ExplicitAnyType) => {
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    if (typeof window === "undefined") {
+      process.stdout.write(`[ENV] ${message}${metaStr}\n`);
+    }
+  },
+  error: (message: string, meta?: ExplicitAnyType) => {
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    if (typeof window === "undefined") {
+      process.stderr.write(`[ENV] ${message}${metaStr}\n`);
+    }
+  },
+  debug: (message: string, meta?: ExplicitAnyType) => {
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    if (typeof window === "undefined") {
+      process.stdout.write(`[ENV] ${message}${metaStr}\n`);
+    }
+  },
+  warn: (message: string, meta?: ExplicitAnyType) => {
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    if (typeof window === "undefined") {
+      process.stderr.write(`[ENV] ${message}${metaStr}\n`);
+    }
+  },
+  vibe: (message: string, meta?: ExplicitAnyType) => {
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    if (typeof window === "undefined") {
+      process.stdout.write(`[ENV] ${message}${metaStr}\n`);
+    }
+  },
+  isDebugEnabled: false,
+};