@payez/next-mvp 3.0.0

package/dist/lib/site-logger.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Site Logger Utility
+ *
+ * Logs user activity events to the site_logs table via Redis buffer.
+ * Fire-and-forget - logging failures never break the app.
+ *
+ * Uses Redis queue (vibe:site-logs:pending) which is drained by
+ * DotNetPert's SiteLogDrainBackgroundService to Vibe site_logs table.
+ *
+ * @version 1.0
+ */
+export type SiteLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type SiteLogCategory = 'auth' | 'session' | 'navigation' | 'user_action' | 'page_view' | 'error' | 'api';
+export interface SiteLogEntry {
+    level: SiteLogLevel;
+    category: SiteLogCategory;
+    message: string;
+    context?: Record<string, unknown>;
+    user_id?: string | number;
+    session_id?: string;
+    url?: string;
+    user_agent?: string;
+    ip_address?: string;
+}
+export interface SiteLoggerConfig {
+    app_slug?: string;
+    vibe_client_id?: string;
+}
+/**
+ * Configure the site logger with app-specific settings
+ */
+export declare function configureSiteLogger(config: SiteLoggerConfig): void;
+/**
+ * Log a site event to the site_logs table
+ * Fire-and-forget - never awaited in critical path
+ */
+export declare function logSiteEvent(entry: SiteLogEntry): Promise<void>;
+/**
+ * Helper to extract client IP from request headers
+ */
+export declare function getClientIp(headers: Headers | Record<string, string | string[] | undefined>): string | null;
+/**
+ * Pre-built event loggers for common auth events
+ */
+export declare const siteEvents: {
+    loginSuccess: (opts: {
+        user_id: string | number;
+        session_id?: string;
+        method?: string;
+        provider?: string;
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    loginFailed: (opts: {
+        reason: string;
+        email?: string;
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    logout: (opts: {
+        user_id: string | number;
+        session_id?: string;
+        trigger?: "user" | "session_timeout" | "admin";
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    twoFactorSuccess: (opts: {
+        user_id: string | number;
+        session_id?: string;
+        method: "totp" | "sms" | "email";
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    twoFactorFailed: (opts: {
+        user_id?: string | number;
+        method: "totp" | "sms" | "email";
+        attempts?: number;
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    sessionCreated: (opts: {
+        user_id: string | number;
+        session_id: string;
+        device_type?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    adminAccess: (opts: {
+        user_id: string | number;
+        page: string;
+        session_id?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    pageView: (opts: {
+        url: string;
+        user_id?: string | number;
+        session_id?: string;
+        referrer?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    error: (opts: {
+        message: string;
+        error?: string;
+        stack?: string;
+        user_id?: string | number;
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+    userAction: (opts: {
+        action: string;
+        target?: string;
+        user_id?: string | number;
+        session_id?: string;
+        url?: string;
+        user_agent?: string;
+        ip_address?: string;
+    }) => void;
+};
+declare const _default: {
+    logSiteEvent: typeof logSiteEvent;
+    getClientIp: typeof getClientIp;
+    siteEvents: {
+        loginSuccess: (opts: {
+            user_id: string | number;
+            session_id?: string;
+            method?: string;
+            provider?: string;
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        loginFailed: (opts: {
+            reason: string;
+            email?: string;
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        logout: (opts: {
+            user_id: string | number;
+            session_id?: string;
+            trigger?: "user" | "session_timeout" | "admin";
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        twoFactorSuccess: (opts: {
+            user_id: string | number;
+            session_id?: string;
+            method: "totp" | "sms" | "email";
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        twoFactorFailed: (opts: {
+            user_id?: string | number;
+            method: "totp" | "sms" | "email";
+            attempts?: number;
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        sessionCreated: (opts: {
+            user_id: string | number;
+            session_id: string;
+            device_type?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        adminAccess: (opts: {
+            user_id: string | number;
+            page: string;
+            session_id?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        pageView: (opts: {
+            url: string;
+            user_id?: string | number;
+            session_id?: string;
+            referrer?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        error: (opts: {
+            message: string;
+            error?: string;
+            stack?: string;
+            user_id?: string | number;
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+        userAction: (opts: {
+            action: string;
+            target?: string;
+            user_id?: string | number;
+            session_id?: string;
+            url?: string;
+            user_agent?: string;
+            ip_address?: string;
+        }) => void;
+    };
+    configureSiteLogger: typeof configureSiteLogger;
+};
+export default _default;

package/dist/lib/site-logger.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Site Logger Utility
+ *
+ * Logs user activity events to the site_logs table via Redis buffer.
+ * Fire-and-forget - logging failures never break the app.
+ *
+ * Uses Redis queue (vibe:site-logs:pending) which is drained by
+ * DotNetPert's SiteLogDrainBackgroundService to Vibe site_logs table.
+ *
+ * @version 1.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.siteEvents = void 0;
+exports.configureSiteLogger = configureSiteLogger;
+exports.logSiteEvent = logSiteEvent;
+exports.getClientIp = getClientIp;
+const redis_1 = require("./redis");
+// Redis key for site logs (separate from data_logs)
+const REDIS_SITE_LOG_KEY = 'vibe:site-logs:pending';
+const REDIS_LOG_TTL = 7 * 24 * 60 * 60; // 1 week
+let _config = {};
+/**
+ * Configure the site logger with app-specific settings
+ */
+function configureSiteLogger(config) {
+    _config = { ..._config, ...config };
+}
+/**
+ * Log a site event to the site_logs table
+ * Fire-and-forget - never awaited in critical path
+ */
+async function logSiteEvent(entry) {
+    try {
+        const redis = (0, redis_1.getRedis)();
+        const logRecord = JSON.stringify({
+            log_level: entry.level,
+            category: entry.category,
+            message: entry.message,
+            context: entry.context || {},
+            user_id: entry.user_id ? (typeof entry.user_id === 'number' ? entry.user_id : null) : null,
+            session_id: entry.session_id || null,
+            url: entry.url || null,
+            user_agent: entry.user_agent || null,
+            ip_address: entry.ip_address || null,
+            created_at: new Date().toISOString(),
+            app_slug: _config.app_slug || process.env.APP_SLUG || process.env.CLIENT_ID || 'unknown',
+            vibe_client_id: _config.vibe_client_id || process.env.VIBE_CLIENT_ID || '',
+        });
+        // Fire and forget - use .then().catch() to not block
+        console.log('[site-logger] Pushing to Redis:', REDIS_SITE_LOG_KEY, entry.category, entry.message);
+        redis.lpush(REDIS_SITE_LOG_KEY, logRecord).then((result) => {
+            console.log('[site-logger] Redis push success, queue length:', result);
+            redis.expire(REDIS_SITE_LOG_KEY, REDIS_LOG_TTL).catch(() => { });
+        }).catch(err => {
+            console.error('[site-logger] Redis push failed:', err.message);
+        });
+    }
+    catch (error) {
+        // Fail silently - logging should never break the app
+        console.error('[site-logger] Failed to log event:', error);
+    }
+}
+/**
+ * Helper to extract client IP from request headers
+ */
+function getClientIp(headers) {
+    const getHeader = (name) => {
+        if (headers instanceof Headers) {
+            return headers.get(name);
+        }
+        const value = headers[name];
+        return Array.isArray(value) ? value[0] : value || null;
+    };
+    return (getHeader('x-forwarded-for')?.split(',')[0]?.trim() ||
+        getHeader('x-real-ip') ||
+        getHeader('cf-connecting-ip') ||
+        null);
+}
+/**
+ * Pre-built event loggers for common auth events
+ */
+exports.siteEvents = {
+    loginSuccess: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'auth',
+            message: 'User logged in',
+            context: { method: opts.method || 'password', provider: opts.provider },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.url || '/auth/login',
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    loginFailed: (opts) => {
+        logSiteEvent({
+            level: 'warn',
+            category: 'auth',
+            message: 'Login failed',
+            context: { reason: opts.reason, email: opts.email },
+            url: opts.url || '/auth/login',
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    logout: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'auth',
+            message: 'User logged out',
+            context: { trigger: opts.trigger || 'user' },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.url || '/auth/logout',
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    twoFactorSuccess: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'auth',
+            message: '2FA verified',
+            context: { method: opts.method },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.url || '/auth/2fa',
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    twoFactorFailed: (opts) => {
+        logSiteEvent({
+            level: 'warn',
+            category: 'auth',
+            message: '2FA verification failed',
+            context: { method: opts.method, attempts: opts.attempts },
+            user_id: opts.user_id,
+            url: opts.url || '/auth/2fa',
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    sessionCreated: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'session',
+            message: 'Session created',
+            context: { device_type: opts.device_type },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    adminAccess: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'navigation',
+            message: 'Admin panel accessed',
+            context: { page: opts.page },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.page,
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    pageView: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'page_view',
+            message: 'Page viewed',
+            context: { referrer: opts.referrer },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.url,
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    error: (opts) => {
+        logSiteEvent({
+            level: 'error',
+            category: 'error',
+            message: opts.message,
+            context: { error: opts.error, stack: opts.stack },
+            user_id: opts.user_id,
+            url: opts.url,
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+    userAction: (opts) => {
+        logSiteEvent({
+            level: 'info',
+            category: 'user_action',
+            message: opts.action,
+            context: { target: opts.target },
+            user_id: opts.user_id,
+            session_id: opts.session_id,
+            url: opts.url,
+            user_agent: opts.user_agent,
+            ip_address: opts.ip_address,
+        });
+    },
+};
+exports.default = { logSiteEvent, getClientIp, siteEvents: exports.siteEvents, configureSiteLogger };

package/dist/lib/standardized-client-api.d.ts

@@ -0,0 +1,161 @@
+/**
+ * ERROR THROWN WHEN API RESPONSE FORMAT IS INVALID
+ * This means the API is NOT following our standardized format
+ */
+export declare class ApiResponseFormatError extends Error {
+    readonly endpoint: string;
+    readonly rawResponse: unknown;
+    constructor(message: string, endpoint: string, rawResponse: unknown);
+}
+/**
+ * ERROR THROWN WHEN API RETURNS A STANDARDIZED ERROR RESPONSE
+ * This is a properly formatted error from the API
+ */
+export declare class ApiBusinessLogicError extends Error {
+    readonly errorCode: string;
+    readonly operation: string;
+    readonly details?: unknown | undefined;
+    constructor(errorCode: string, message: string, operation: string, details?: unknown | undefined);
+}
+/**
+ * ERROR THROWN WHEN VALIDATION FAILS
+ * This is a properly formatted validation error from the API
+ */
+export declare class ApiValidationError extends Error {
+    readonly operation: string;
+    readonly validationErrors: Record<string, string[]>;
+    readonly invalidValue?: unknown | undefined;
+    readonly primaryField?: string | undefined;
+    constructor(message: string, operation: string, validationErrors: Record<string, string[]>, invalidValue?: unknown | undefined, primaryField?: string | undefined);
+}
+/**
+ * ERROR THROWN WHEN NETWORK/HTTP ISSUES OCCUR
+ */
+export declare class ApiNetworkError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(message: string, status: number, endpoint: string);
+}
+/**
+ * SUCCESSFUL API CALL RESULT
+ * This is what gets returned to the calling code for successful operations
+ */
+export interface ApiSuccessResult<TData> {
+    /** Always true for success */
+    success: true;
+    /** The actual data - NO NESTING! Direct access! */
+    data: TData;
+    /** Human-readable success message from API */
+    message: string;
+    /** Operation code for tracking/debugging */
+    operation_code: string;
+    /** Server timestamp (if provided) */
+    timestamp?: string;
+}
+/**
+ * SUCCESSFUL PAGED API CALL RESULT
+ * This is what gets returned for successful paged operations
+ */
+export interface ApiPagedResult<TData> {
+    /** Always true for success */
+    success: true;
+    /** The actual data array - NO NESTING! Direct access! */
+    items: TData[];
+    /** Human-readable success message from API */
+    message: string;
+    /** Operation code for tracking/debugging */
+    operation_code: string;
+    /** Pagination information */
+    pagination: {
+        current_page: number;
+        total_pages: number;
+        page_size: number;
+        total_items: number;
+        has_next_page: boolean;
+        has_previous_page: boolean;
+    };
+    /** Server timestamp (if provided) */
+    timestamp?: string;
+}
+/**
+ * FAILED API CALL RESULT
+ * This is what gets returned to the calling code for failed operations
+ */
+export interface ApiErrorResult {
+    /** Always false for errors */
+    success: false;
+    /** Standardized error code */
+    error_code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Operation that failed */
+    operation: string;
+    /** Additional error details (if any) */
+    details?: unknown;
+    /** Validation errors (if any) */
+    validation_errors?: Record<string, string[]>;
+    /** Server-provided request identifier for tracing (only set on real errors) */
+    request_id?: string;
+}
+/** UNION TYPE FOR ALL POSSIBLE API RESULTS */
+export type ApiResult<TData> = ApiSuccessResult<TData> | ApiPagedResult<TData> | ApiErrorResult;
+declare class StandardizedClientApiService {
+    private baseUrl;
+    constructor();
+    /**
+     * MAKES HTTP REQUEST AND VALIDATES RESPONSE FORMAT
+     * This method ENFORCES standardized response format compliance
+     * Will throw ApiResponseFormatError if format is invalid
+     */
+    private makeRequest;
+    /**
+     * CONVERTS VALIDATED STANDARDIZED RESPONSE TO CLIENT RESULT
+     * This normalizes the response for client consumption
+     */
+    private convertToApiResult;
+    /**
+     * GET REQUEST - Returns typed result with direct data access
+     */
+    get<TData = unknown>(endpoint: string, sessionToken?: string): Promise<ApiResult<TData>>;
+    /**
+     * POST REQUEST - Returns typed result with direct data access
+     */
+    post<TData = unknown>(endpoint: string, data?: unknown, sessionToken?: string): Promise<ApiResult<TData>>;
+    /**
+     * PUT REQUEST - Returns typed result with direct data access
+     */
+    put<TData = unknown>(endpoint: string, data?: unknown, sessionToken?: string): Promise<ApiResult<TData>>;
+    /**
+     * DELETE REQUEST - Returns typed result with direct data access
+     */
+    delete<TData = unknown>(endpoint: string): Promise<ApiResult<TData>>;
+}
+export declare const standardizedApi: StandardizedClientApiService;
+/**
+ * TYPE-SAFE SUCCESS CHECK
+ * Use this to check if API call was successful with proper type narrowing
+ */
+export declare function isApiSuccess<TData>(result: ApiResult<TData>): result is ApiSuccessResult<TData>;
+/**
+ * TYPE-SAFE PAGED SUCCESS CHECK
+ * Use this to check if API call was successful paged response with proper type narrowing
+ */
+export declare function isApiPagedSuccess<TData>(result: ApiResult<TData>): result is ApiPagedResult<TData>;
+/**
+ * TYPE-SAFE ERROR CHECK
+ * Use this to check if API call failed with proper type narrowing
+ */
+export declare function isApiError<TData>(result: ApiResult<TData>): result is ApiErrorResult;
+/**
+ * EXTRACT DATA FROM SUCCESS RESULT
+ * Use this to get the data from a successful API call
+ * Will throw if result is not successful
+ */
+export declare function extractApiData<TData>(result: ApiResult<TData>): TData;
+/**
+ * EXTRACT ITEMS FROM PAGED SUCCESS RESULT
+ * Use this to get the items array from a successful paged API call
+ * Will throw if result is not successful paged response
+ */
+export declare function extractApiItems<TData>(result: ApiResult<TData>): TData[];
+export {};