@next-vibe/checker 1.0.52 → 3.0.0

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

@@ -1,182 +0,0 @@
-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) or streaming/file responses
- */
-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

@@ -1,173 +0,0 @@
-/**
- * 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 the validation error directly with proper message and params
-      return urlValidation;
-    }
-
-    // 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 the validation error directly with proper message and params
-      return 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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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,
-};

package/src/app/api/[locale]/system/unified-interface/shared/field/enum.ts

@@ -1,107 +0,0 @@
-/**
- * Enum Helper Utilities
- *
- * These utilities help create type-safe enums with proper i18n integration
- * and Zod schema generation for the data-driven UI system.
- */
-
-import type { TranslationKey } from "@/i18n/core/static-types";
-
-export interface EnumOptions<T extends Record<string, TranslationKey>> {
-  enum: { readonly [K in keyof T]: T[K] };
-  options: Array<{ value: keyof T; label: T[keyof T] }>;
-}
-
-/**
- * Wrapper function that creates enum-like object where keys map to their values
- * This ensures the enum object maps keys to the values passed in (KEY -> enumMap[KEY])
- * For PostgreSQL enums, we handle this differently in the DB layer
- */
-function createEnumObjectWithKeyValues<T extends Record<string, string>>(
-  enumMap: T,
-): { readonly [K in keyof T]: T[K] } {
-  const result: { [K in keyof T]: T[K] } = {} as { [K in keyof T]: T[K] };
-  for (const key in enumMap) {
-    result[key] = enumMap[key];
-  }
-  Object.freeze(result);
-  return result;
-}
-
-export function createEnumOptions<
-  const TTranslationKey extends string = TranslationKey,
-  const T extends Record<string, TTranslationKey> = Record<string, TTranslationKey>,
->(
-  enumMap: T,
-): {
-  enum: { readonly [K in keyof T]: T[K] };
-  options: Array<{ [K in keyof T]: { value: T[K]; label: T[K] } }[keyof T]>;
-  Value: T[keyof T];
-} {
-  const enumObj = createEnumObjectWithKeyValues(enumMap);
-
-  const optionsArray = Object.entries(enumMap).map(([, translationValue]) => ({
-    value: translationValue,
-    label: translationValue,
-  })) as Array<{ [K in keyof T]: { value: T[K]; label: T[K] } }[keyof T]>;
-
-  return {
-    enum: enumObj,
-    options: optionsArray,
-    // intentianally unsafe cast to get a enum value type
-    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Infrastructure: Type placeholder for enum value extraction requires 'unknown' cast for type system compatibility. This is a compile-time only type, never used at runtime.
-    Value: undefined as unknown as T[keyof T],
-  };
-}
-
-/**
- * Extract enum values as array
- */
-export function getEnumValues<T extends Record<string, string | number>>(
-  enumObject: T,
-): Array<T[keyof T]> {
-  return Object.values(enumObject) as Array<T[keyof T]>;
-}
-
-/**
- * Extract enum keys as array
- */
-export function getEnumKeys<T extends Record<string, string | number>>(
-  enumObject: T,
-): Array<keyof T> {
-  return Object.keys(enumObject) as Array<keyof T>;
-}
-
-/**
- * Check if a value is a valid enum value
- */
-export function isValidEnumValue<T extends Record<string, string | number>>(
-  enumObject: T,
-  value: string | number | boolean,
-): value is T[keyof T] {
-  const enumValues = Object.values(enumObject);
-  return enumValues.includes(value as T[keyof T]);
-}
-
-/**
- * Get enum value by key with type safety
- */
-export function getEnumValue<T extends Record<string, string | number>>(
-  enumObject: T,
-  key: keyof T,
-): T[keyof T] {
-  return enumObject[key];
-}
-
-/**
- * Convert enum to select options for UI components
- */
-export function enumToSelectOptions<T extends Record<string, string>>(
-  enumObject: T,
-  labelPrefix?: string,
-): Array<{ value: T[keyof T]; label: string }> {
-  return Object.entries(enumObject).map(([key, value]) => ({
-    value: value as T[keyof T],
-    label: labelPrefix ? `${labelPrefix}.${key}` : key,
-  }));
-}