@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/shared/types/stats-filtering.schema.ts

@@ -0,0 +1,375 @@
+/**
+ * Shared Stats Filtering Schemas and Enums
+ * Reusable filtering infrastructure for stats endpoints
+ * @deprecated This file should no longer be used and will be removed in the future.
+ */
+
+import { dateSchema } from "next-vibe/shared/types/common.schema";
+import { z } from "zod";
+
+import type { Countries, Languages } from "@/i18n/core/config";
+import type { TranslationKey } from "@/i18n/core/static-types";
+
+// Re-export dateSchema for consistency
+export { dateSchema };
+
+/**
+ * Time Period Enum
+ * Defines different time periods for historical data aggregation
+ */
+export enum TimePeriod {
+  HOUR = "hour",
+  DAY = "day",
+  WEEK = "week",
+  MONTH = "month",
+  QUARTER = "quarter",
+  YEAR = "year",
+}
+
+/**
+ * Date Range Preset Enum
+ * Common date range presets for quick filtering
+ */
+export enum DateRangePreset {
+  TODAY = "today",
+  YESTERDAY = "yesterday",
+  LAST_7_DAYS = "last_7_days",
+  LAST_30_DAYS = "last_30_days",
+  LAST_90_DAYS = "last_90_days",
+  THIS_WEEK = "this_week",
+  LAST_WEEK = "last_week",
+  THIS_MONTH = "this_month",
+  LAST_MONTH = "last_month",
+  THIS_QUARTER = "this_quarter",
+  LAST_QUARTER = "last_quarter",
+  THIS_YEAR = "this_year",
+  LAST_YEAR = "last_year",
+  CUSTOM = "custom",
+}
+
+/**
+ * Chart Type Enum
+ * Different chart visualization types
+ */
+export enum ChartType {
+  LINE = "line",
+  BAR = "bar",
+  AREA = "area",
+  PIE = "pie",
+  DONUT = "donut",
+}
+
+/**
+ * Base Stats Filter Schema
+ * Common filtering options for all stats endpoints
+ */
+export const baseStatsFilterSchema = z.object({
+  // Time-based filtering
+  timePeriod: z.enum(TimePeriod).default(TimePeriod.DAY),
+  dateRangePreset: z
+    .nativeEnum(DateRangePreset)
+    .default(DateRangePreset.LAST_30_DAYS),
+  dateFrom: dateSchema.optional(),
+  dateTo: dateSchema.optional(),
+
+  // Chart configuration
+  chartType: z.enum(ChartType).default(ChartType.LINE),
+
+  // Data options
+  includeComparison: z.coerce.boolean().default(false),
+  comparisonPeriod: z.enum(DateRangePreset).optional(),
+});
+
+export type BaseStatsFilterType = z.infer<typeof baseStatsFilterSchema>;
+
+/**
+ * Historical Data Point Schema
+ * Structure for time-series data points
+ */
+export const historicalDataPointSchema = z.object({
+  date: dateSchema,
+  value: z.coerce.number(),
+  label: z.string().optional() as z.ZodType<TranslationKey | undefined>,
+  labelParams: z
+    .record(z.string(), z.union([z.string(), z.coerce.number()]))
+    .optional(),
+  metadata: z
+    .record(z.string(), z.union([z.string(), z.coerce.number(), z.boolean()]))
+    .optional(),
+});
+
+export type HistoricalDataPointType = z.infer<typeof historicalDataPointSchema>;
+
+/**
+ * Historical Data Series Schema
+ * Structure for a complete data series
+ */
+export const historicalDataSeriesSchema = z.object({
+  name: z.string() as z.ZodType<TranslationKey>,
+  nameParams: z
+    .record(z.string(), z.union([z.string(), z.coerce.number()]))
+    .optional(),
+  data: z.array(historicalDataPointSchema),
+  color: z.string().optional(),
+  type: z.enum(ChartType).optional(),
+});
+
+export type HistoricalDataSeriesType = z.infer<
+  typeof historicalDataSeriesSchema
+>;
+
+/**
+ * Chart Data Schema
+ * Complete chart data structure
+ */
+export const chartDataSchema = z.object({
+  series: z.array(historicalDataSeriesSchema),
+  categories: z.array(z.string()).optional(),
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  yAxisLabel: z.string().optional(),
+  xAxisLabel: z.string().optional(),
+});
+
+export type ChartDataType = z.infer<typeof chartDataSchema>;
+
+/**
+ * Current period stats schema for summary numbers
+ */
+export const currentPeriodStatsSchema = z.object({
+  // Core metrics
+  totalCount: z.coerce.number().describe("Total count for the current period"),
+  newCount: z.coerce.number().describe("New items in the current period"),
+  activeCount: z.coerce.number().describe("Active items in the current period"),
+
+  // Engagement metrics (for emails/campaigns)
+  totalSent: z.coerce.number().optional().describe("Total emails sent"),
+  totalOpened: z.coerce.number().optional().describe("Total emails opened"),
+  totalClicked: z.coerce.number().optional().describe("Total emails clicked"),
+  totalBounced: z.coerce.number().optional().describe("Total emails bounced"),
+  totalUnsubscribed: z.coerce
+    .number()
+    .optional()
+    .describe("Total unsubscribed"),
+
+  // Conversion metrics (for leads)
+  totalSignedUp: z.coerce.number().optional().describe("Total leads signed up"),
+  totalConsultationBooked: z
+    .number()
+    .optional()
+    .describe("Total consultations booked"),
+  totalConverted: z.coerce
+    .number()
+    .optional()
+    .describe("Total converted leads"),
+
+  // Rate calculations
+  openRate: z.coerce.number().optional().describe("Email open rate (0-1)"),
+  clickRate: z.coerce.number().optional().describe("Email click rate (0-1)"),
+  bounceRate: z.coerce.number().optional().describe("Email bounce rate (0-1)"),
+  unsubscribeRate: z
+    .number()
+    .optional()
+    .describe("Email unsubscribe rate (0-1)"),
+  conversionRate: z.coerce
+    .number()
+    .optional()
+    .describe("Lead conversion rate (0-1)"),
+  signupRate: z.coerce.number().optional().describe("Lead signup rate (0-1)"),
+  consultationBookingRate: z
+    .number()
+    .optional()
+    .describe("Consultation booking rate (0-1)"),
+
+  // Distribution data
+  // Generic string keys - specific implementations should override with proper enum types
+  byType: z
+    .record(z.string(), z.coerce.number())
+    .optional()
+    .describe("Distribution by type"),
+  byStatus: z
+    .record(z.string(), z.coerce.number())
+    .optional()
+    .describe("Distribution by status"),
+  bySource: z
+    .record(z.string(), z.coerce.number())
+    .optional()
+    .describe("Distribution by source"),
+  // Proper enum types for country and language
+  byCountry: z
+    .record(z.custom<Countries>(), z.coerce.number())
+    .optional()
+    .describe("Distribution by country"),
+  byLanguage: z
+    .record(z.custom<Languages>(), z.coerce.number())
+    .optional()
+    .describe("Distribution by language"),
+
+  // Time-based metrics
+  todayCount: z.coerce.number().optional().describe("Count for today"),
+  thisWeekCount: z.coerce.number().optional().describe("Count for this week"),
+  thisMonthCount: z.coerce.number().optional().describe("Count for this month"),
+  lastMonthCount: z.coerce.number().optional().describe("Count for last month"),
+
+  // Top performers
+  topPerforming: z
+    .array(z.record(z.string(), z.unknown()))
+    .optional()
+    .describe("Top performing items"),
+  recentActivity: z
+    .array(z.record(z.string(), z.unknown()))
+    .optional()
+    .describe("Recent activity"),
+});
+
+export type CurrentPeriodStatsType = z.infer<typeof currentPeriodStatsSchema>;
+
+/**
+ * Date Range Calculation Utilities
+ */
+
+/**
+ * Calculate date range from preset
+ */
+export function getDateRangeFromPreset(preset: DateRangePreset): {
+  from: Date;
+  to: Date;
+} {
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+
+  switch (preset) {
+    case DateRangePreset.TODAY:
+      return {
+        from: today,
+        to: new Date(today.getTime() + 24 * 60 * 60 * 1000 - 1),
+      };
+
+    case DateRangePreset.YESTERDAY: {
+      const yesterday = new Date(today.getTime() - 24 * 60 * 60 * 1000);
+      return {
+        from: yesterday,
+        to: new Date(yesterday.getTime() + 24 * 60 * 60 * 1000 - 1),
+      };
+    }
+
+    case DateRangePreset.LAST_7_DAYS:
+      return {
+        from: new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000),
+        to: now,
+      };
+
+    case DateRangePreset.LAST_30_DAYS:
+      return {
+        from: new Date(today.getTime() - 30 * 24 * 60 * 60 * 1000),
+        to: now,
+      };
+
+    case DateRangePreset.LAST_90_DAYS:
+      return {
+        from: new Date(today.getTime() - 90 * 24 * 60 * 60 * 1000),
+        to: now,
+      };
+
+    case DateRangePreset.THIS_WEEK: {
+      const startOfWeek = new Date(today);
+      startOfWeek.setDate(today.getDate() - today.getDay());
+      return { from: startOfWeek, to: now };
+    }
+    case DateRangePreset.LAST_WEEK: {
+      const lastWeekStart = new Date(today);
+      lastWeekStart.setDate(today.getDate() - today.getDay() - 7);
+      const lastWeekEnd = new Date(lastWeekStart);
+      lastWeekEnd.setDate(lastWeekStart.getDate() + 6);
+      lastWeekEnd.setHours(23, 59, 59, 999);
+      return { from: lastWeekStart, to: lastWeekEnd };
+    }
+    case DateRangePreset.THIS_MONTH: {
+      const startOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
+      return { from: startOfMonth, to: now };
+    }
+    case DateRangePreset.LAST_MONTH: {
+      const lastMonthStart = new Date(
+        today.getFullYear(),
+        today.getMonth() - 1,
+        1,
+      );
+      const lastMonthEnd = new Date(today.getFullYear(), today.getMonth(), 0);
+      lastMonthEnd.setHours(23, 59, 59, 999);
+      return { from: lastMonthStart, to: lastMonthEnd };
+    }
+    case DateRangePreset.THIS_QUARTER: {
+      const quarterStart = new Date(
+        today.getFullYear(),
+        Math.floor(today.getMonth() / 3) * 3,
+        1,
+      );
+      return { from: quarterStart, to: now };
+    }
+    case DateRangePreset.LAST_QUARTER: {
+      const lastQuarterMonth = Math.floor(today.getMonth() / 3) * 3 - 3;
+      const lastQuarterStart = new Date(
+        today.getFullYear(),
+        lastQuarterMonth,
+        1,
+      );
+      if (lastQuarterMonth < 0) {
+        lastQuarterStart.setFullYear(today.getFullYear() - 1);
+        lastQuarterStart.setMonth(9);
+      }
+      const lastQuarterEnd = new Date(
+        lastQuarterStart.getFullYear(),
+        lastQuarterStart.getMonth() + 3,
+        0,
+      );
+      lastQuarterEnd.setHours(23, 59, 59, 999);
+      return { from: lastQuarterStart, to: lastQuarterEnd };
+    }
+
+    case DateRangePreset.THIS_YEAR: {
+      const startOfYear = new Date(today.getFullYear(), 0, 1);
+      return { from: startOfYear, to: now };
+    }
+
+    case DateRangePreset.LAST_YEAR: {
+      const lastYearStart = new Date(today.getFullYear() - 1, 0, 1);
+      const lastYearEnd = new Date(
+        today.getFullYear() - 1,
+        11,
+        31,
+        23,
+        59,
+        59,
+        999,
+      );
+      return { from: lastYearStart, to: lastYearEnd };
+    }
+    default:
+      return {
+        from: new Date(today.getTime() - 30 * 24 * 60 * 60 * 1000),
+        to: now,
+      };
+  }
+}
+
+/**
+ * Get time period format string for SQL GROUP BY
+ */
+export function getTimePeriodFormat(period: TimePeriod): string {
+  switch (period) {
+    case TimePeriod.HOUR:
+      return "DATE_TRUNC('hour', created_at)";
+    case TimePeriod.DAY:
+      return "DATE(created_at)";
+    case TimePeriod.WEEK:
+      return "DATE_TRUNC('week', created_at)";
+    case TimePeriod.MONTH:
+      return "DATE_TRUNC('month', created_at)";
+    case TimePeriod.QUARTER:
+      return "DATE_TRUNC('quarter', created_at)";
+    case TimePeriod.YEAR:
+      return "DATE_TRUNC('year', created_at)";
+    default:
+      return "DATE(created_at)";
+  }
+}

package/src/app/api/[locale]/shared/types/utils.ts

@@ -0,0 +1,190 @@
+/**
+ * Utility types for cleaning and prettifying complex types
+ */
+
+// eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for type system operations
+export type ExplicitObjectType = object;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ExplicitAnyType = any;
+
+/**
+ * Makes all properties in T optional recursively
+ */
+export type DeepPartial<T> = {
+  // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Makes all properties in T required recursively
+ */
+export type DeepRequired<T> = {
+  // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+  [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+
+/**
+ * Prettifies complex intersection types by flattening them
+ */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Removes readonly modifiers from all properties
+ */
+export type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * Makes specific keys optional while keeping others required
+ */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * Makes specific keys required while keeping others optional
+ */
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> &
+  Required<Pick<T, K>>;
+
+/**
+ * Extracts the return type of a function, handling async functions
+ */
+
+export type ExtractReturnType<T> = T extends (
+  ...args: ExplicitAnyType[]
+) => infer R
+  ? R extends Promise<infer U>
+    ? U
+    : R
+  : never;
+
+/**
+ * Creates a union of all property values in an object type
+ */
+export type ValueOf<T> = T[keyof T];
+
+/**
+ * Excludes null and undefined from a type
+ */
+export type NonNullable<T> = T extends null | undefined ? never : T;
+
+/**
+ * Creates a type with all properties from T except those that extend U
+ */
+export type OmitByType<T, U> = {
+  [K in keyof T as T[K] extends U ? never : K]: T[K];
+};
+
+/**
+ * Creates a type with only properties from T that extend U
+ */
+export type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+/**
+ * Flattens nested object types into a single level
+ */
+// eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+export type Flatten<T> = T extends object
+  ? {
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+      [K in keyof T]: T[K] extends object ? Flatten<T[K]> : T[K];
+    }
+  : T;
+
+/**
+ * Creates a strict subset type where all properties must exist in the original type
+ */
+export type StrictSubset<T, U extends T> = U;
+
+/**
+ * Converts union types to intersection types
+ */
+export type UnionToIntersection<U> = (
+  U extends ExplicitAnyType ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Gets the keys of an object as a union type
+ */
+export type KeysOf<T> = keyof T;
+
+/**
+ * Creates a type that represents either T or an array of T
+ */
+export type MaybeArray<T> = T | T[];
+
+/**
+ * Creates a type that represents a function or the return type of that function
+ */
+export type MaybeFunction<T> = T | (() => T);
+
+/**
+ * Removes functions from an object type
+ */
+export type NonFunctionKeys<T> = {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+
+/**
+ * Creates a type with only non-function properties
+ */
+export type NonFunctionProperties<T> = Pick<T, NonFunctionKeys<T>>;
+
+/**
+ * Creates a deeply readonly version of a type
+ */
+export type DeepReadonly<T> = {
+  // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+
+/**
+ * Extracts the element type from an array type
+ */
+export type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+
+/**
+ * Creates a type that excludes empty object types
+ */
+export type NonEmptyObject<T> = keyof T extends never ? never : T;
+
+/**
+ * Creates a conditional type that resolves to different types based on a condition
+ */
+export type If<C extends boolean, T, F> = C extends true ? T : F;
+
+/**
+ * Creates a type that represents all possible paths through an object
+ */
+// eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+export type Paths<T> = T extends object
+  ? {
+      [K in keyof T]: K extends string
+        ? // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Generic utility type for recursive type operations
+          T[K] extends object
+          ? K | `${K}.${Paths<T[K]>}`
+          : K
+        : never;
+    }[keyof T]
+  : never;
+
+/**
+ * Gets the type at a specific path in an object
+ */
+export type PathValue<T, P extends Paths<T>> = P extends `${infer K}.${infer R}`
+  ? K extends keyof T
+    ? R extends Paths<T[K]>
+      ? PathValue<T[K], R>
+      : never
+    : never
+  : P extends keyof T
+    ? T[P]
+    : never;

package/src/app/api/[locale]/shared/utils/base64.ts

@@ -0,0 +1,49 @@
+/**
+ * Base64 encoding utilities for email templates
+ */
+
+/**
+ * Converts a string to base64 encoding
+ * @param input - The string to encode
+ * @returns The base64 encoded string
+ */
+export function encodeBase64(input: string): string {
+  return Buffer.from(input).toString("base64");
+}
+
+/**
+ * Creates a data URL from content and MIME type
+ * @param content - The content to encode
+ * @param mimeType - The MIME type (e.g., 'image/svg+xml', 'image/png')
+ * @returns A data URL string
+ */
+export function createDataUrl(content: string, mimeType: string): string {
+  const base64Content = encodeBase64(content);
+  // eslint-disable-next-line i18next/no-literal-string
+  return `data:${mimeType};base64,${base64Content}`;
+}
+
+/**
+ * Creates a data URL from base64 content and MIME type
+ * @param base64Content - The base64 encoded content
+ * @param mimeType - The MIME type (e.g., 'image/png', 'image/jpeg')
+ * @returns A data URL string
+ */
+export function createDataUrlFromBase64(
+  base64Content: string,
+  mimeType: string,
+): string {
+  // eslint-disable-next-line i18next/no-literal-string
+  const dataPrefix = "data:";
+  // eslint-disable-next-line i18next/no-literal-string
+  const base64Suffix = ";base64,";
+  return dataPrefix + mimeType + base64Suffix + base64Content;
+}
+
+/**
+ * Creates a transparent 1x1 pixel PNG data URL for placeholders
+ * @returns A data URL for a transparent pixel
+ */
+export function createTransparentPixelDataUrl(): string {
+  return "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+}

package/src/app/api/[locale]/shared/utils/env-util.ts

@@ -0,0 +1,40 @@
+import type { z } from "zod";
+
+import type { EndpointLogger } from "@/app/api/[locale]/system/unified-interface/shared/logger/endpoint";
+
+import { validateData } from "./validation";
+
+export function validateEnv<TSchema extends z.ZodType>(
+  env: {
+    [key: string]:
+      | string
+      | undefined
+      | boolean
+      | number
+      | { [key: string]: string | undefined | boolean | number };
+  },
+  envSchema: TSchema,
+  logger: EndpointLogger,
+): z.infer<TSchema> {
+  const validationResult = validateData<TSchema>(
+    env as z.input<TSchema>,
+    envSchema,
+    logger,
+  );
+  if (!validationResult.success) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Environment validation must throw on startup to prevent invalid configuration
+    throw new Error(
+      // eslint-disable-next-line i18next/no-literal-string
+      `Environment validation error: ${validationResult.message} ${JSON.stringify(
+        validationResult,
+      )}`,
+    );
+  }
+  return validationResult.data as z.infer<TSchema>;
+}
+
+export enum Environment {
+  PRODUCTION = "production",
+  TEST = "test",
+  DEVELOPMENT = "development",
+}

package/src/app/api/[locale]/shared/utils/i18n/de/index.ts

@@ -0,0 +1,21 @@
+import type { translations as enTranslations } from "../en";
+
+export const translations: typeof enTranslations = {
+  parseJsonWithComments: {
+    errors: {
+      invalid_json: "Ungültiges JSON-Format",
+    },
+  },
+  time: {
+    errors: {
+      invalid_time_format: {
+        title: "Ungültiges Zeitformat",
+        description: "Die Zeitangabe muss im Format HH:MM sein",
+      },
+      invalid_time_range: {
+        title: "Ungültiger Zeitbereich",
+        description: "Die Zeitangabe muss zwischen 00:00 und 23:59 liegen",
+      },
+    },
+  },
+};

package/src/app/api/[locale]/shared/utils/i18n/en/index.ts

@@ -0,0 +1,19 @@
+export const translations = {
+  parseJsonWithComments: {
+    errors: {
+      invalid_json: "Invalid JSON format",
+    },
+  },
+  time: {
+    errors: {
+      invalid_time_format: {
+        title: "Invalid Time Format",
+        description: "The time string must be in HH:MM format",
+      },
+      invalid_time_range: {
+        title: "Invalid Time Range",
+        description: "The time value must be between 00:00 and 23:59",
+      },
+    },
+  },
+};