chargeback-guard 2.0.0

package/src/utils/formatters.ts

@@ -0,0 +1,72 @@
+// ============================================================
+//  CHARGEBACK GUARD — Data Formatters
+// ============================================================
+
+export function formatAmount(cents: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: 2,
+  }).format(cents / 100);
+}
+
+export function formatDate(date: string | Date, locale = 'en-US'): string {
+  return new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  }).format(new Date(date));
+}
+
+export function formatDateTime(date: string | Date, locale = 'en-US'): string {
+  return new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(new Date(date));
+}
+
+export function formatTrustScore(score: number): string {
+  if (score >= 90) { return `${score} (Excellent)`; }
+  if (score >= 75) { return `${score} (Good)`; }
+  if (score >= 55) { return `${score} (Fair)`; }
+  if (score >= 35) { return `${score} (Poor)`; }
+  return `${score} (Critical)`;
+}
+
+export function formatRiskLevel(level: string): string {
+  const labels: Record<string, string> = {
+    very_low:  '🟢 Very Low',
+    low:       '🟢 Low',
+    medium:    '🟡 Medium',
+    high:      '🟠 High',
+    critical:  '🔴 Critical',
+  };
+  return labels[level] ?? level;
+}
+
+export function formatDisputeReason(reason: string): string {
+  const labels: Record<string, string> = {
+    product_not_received:     'Product Not Received',
+    product_unacceptable:     'Product Unacceptable',
+    unauthorized_transaction: 'Unauthorized Transaction',
+    duplicate_transaction:    'Duplicate Transaction',
+    credit_not_processed:     'Credit Not Processed',
+    subscription_cancelled:   'Subscription Cancelled',
+    fraudulent:               'Fraudulent',
+    general:                  'General',
+  };
+  return labels[reason] ?? reason.replace(/_/g, ' ');
+}
+
+export function formatConfidenceLevel(level: string): string {
+  const labels: Record<string, string> = {
+    very_high: '✅ Very High (>85%)',
+    high:      '👍 High (>65%)',
+    medium:    '⚠️ Medium (>45%)',
+    low:       '❌ Low (<45%)',
+  };
+  return labels[level] ?? level;
+}

package/src/utils/helpers.ts

@@ -0,0 +1,193 @@
+// ============================================================
+//  CHARGEBACK GUARD — General Helper Utilities
+// ============================================================
+
+import crypto from 'crypto';
+
+// ────────────────────────────────────────────────────────────
+//  STRING HELPERS
+// ────────────────────────────────────────────────────────────
+
+export function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) { return str; }
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function slugify(str: string): string {
+  return str.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '');
+}
+
+export function maskEmail(email: string): string {
+  const [local, domain] = email.split('@');
+  if (!local || !domain) { return email; }
+  const masked = local.slice(0, 2) + '*'.repeat(Math.max(0, local.length - 2));
+  return `${masked}@${domain}`;
+}
+
+// ────────────────────────────────────────────────────────────
+//  NUMBER HELPERS
+// ────────────────────────────────────────────────────────────
+
+export function centsToDollars(cents: number): string {
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+export function dollarsToCents(dollars: number): number {
+  return Math.round(dollars * 100);
+}
+
+export function formatPercentage(value: number, decimals = 1): string {
+  return `${value.toFixed(decimals)}%`;
+}
+
+// ────────────────────────────────────────────────────────────
+//  DATE HELPERS
+// ────────────────────────────────────────────────────────────
+
+export function daysFromNow(days: number): Date {
+  const d = new Date();
+  d.setDate(d.getDate() + days);
+  return d;
+}
+
+export function daysBetween(from: Date, to: Date): number {
+  return Math.floor((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+export function isExpired(date: Date | string): boolean {
+  return new Date(date).getTime() < Date.now();
+}
+
+export function isDeadlineClose(date: Date | string, hoursThreshold = 48): boolean {
+  const remaining = new Date(date).getTime() - Date.now();
+  return remaining > 0 && remaining < hoursThreshold * 3600000;
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000)  { return `${ms}ms`; }
+  if (ms < 60000) { return `${(ms / 1000).toFixed(1)}s`; }
+  if (ms < 3600000) { return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`; }
+  return `${(ms / 3600000).toFixed(1)}h`;
+}
+
+// ────────────────────────────────────────────────────────────
+//  OBJECT HELPERS
+// ────────────────────────────────────────────────────────────
+
+export function omit<T extends object, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Omit<T, K> {
+  const result = { ...obj };
+  keys.forEach(key => delete result[key]);
+  return result;
+}
+
+export function pick<T extends object, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  keys.forEach(key => { result[key] = obj[key]; });
+  return result;
+}
+
+export function deepClone<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+export function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) { return true; }
+  if (typeof value === 'string')  { return value.trim().length === 0; }
+  if (Array.isArray(value))       { return value.length === 0; }
+  if (typeof value === 'object')  { return Object.keys(value).length === 0; }
+  return false;
+}
+
+// ────────────────────────────────────────────────────────────
+//  ARRAY HELPERS
+// ────────────────────────────────────────────────────────────
+
+export function chunkArray<T>(arr: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+
+export function uniqueBy<T>(arr: T[], key: keyof T): T[] {
+  const seen = new Set();
+  return arr.filter(item => {
+    const val = item[key];
+    if (seen.has(val)) { return false; }
+    seen.add(val);
+    return true;
+  });
+}
+
+export function groupBy<T>(arr: T[], key: keyof T): Record<string, T[]> {
+  return arr.reduce((groups, item) => {
+    const k = String(item[key]);
+    if (!groups[k]) { groups[k] = []; }
+    groups[k].push(item);
+    return groups;
+  }, {} as Record<string, T[]>);
+}
+
+// ────────────────────────────────────────────────────────────
+//  ASYNC HELPERS
+// ────────────────────────────────────────────────────────────
+
+export async function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+export async function retry<T>(
+  fn: () => Promise<T>,
+  retries = 3,
+  delayMs = 1000
+): Promise<T> {
+  let lastError: Error | undefined;
+  for (let i = 0; i <= retries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (i < retries) { await sleep(delayMs * Math.pow(2, i)); } // exponential backoff
+    }
+  }
+  throw lastError;
+}
+
+export async function timeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message = `Operation timed out after ${ms}ms`
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(message)), ms)
+    ),
+  ]);
+}
+
+// ────────────────────────────────────────────────────────────
+//  ID GENERATION
+// ────────────────────────────────────────────────────────────
+
+export function generateId(prefix = ''): string {
+  const random = crypto.randomBytes(12).toString('base64url');
+  return prefix ? `${prefix}_${random}` : random;
+}
+
+export function generateOrderId(): string {
+  const ts   = Date.now().toString(36).toUpperCase();
+  const rand = crypto.randomBytes(4).toString('hex').toUpperCase();
+  return `ORD-${ts}-${rand}`;
+}

package/src/utils/logger.ts

@@ -0,0 +1,88 @@
+// ============================================================
+//  CHARGEBACK GUARD — Logger Utility
+// ============================================================
+
+import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
+import path from 'path';
+import { appConfig } from '../config';
+
+const { combine, timestamp, printf, colorize, errors, json } = winston.format;
+
+// ────────────────────────────────────────────────────────────
+//  CUSTOM FORMATS
+// ────────────────────────────────────────────────────────────
+
+const devFormat = combine(
+  colorize({ all: true }),
+  timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }),
+  errors({ stack: true }),
+  printf(({ level, message, timestamp: ts, ...meta }) => {
+    const metaStr = Object.keys(meta).length ? `\n${JSON.stringify(meta, null, 2)}` : '';
+    return `[${ts}] ${level}: ${message}${metaStr}`;
+  })
+);
+
+const prodFormat = combine(
+  timestamp(),
+  errors({ stack: true }),
+  json()
+);
+
+// ────────────────────────────────────────────────────────────
+//  TRANSPORTS
+// ────────────────────────────────────────────────────────────
+
+const transports: winston.transport[] = [
+  new winston.transports.Console({
+    format: appConfig.isDev ? devFormat : prodFormat,
+    silent: process.env.NODE_ENV === 'test',
+  }),
+];
+
+// Add file transports in production / staging
+if (!appConfig.isDev && process.env.NODE_ENV !== 'test') {
+  transports.push(
+    new DailyRotateFile({
+      filename: path.join('logs', 'application-%DATE%.log'),
+      datePattern: 'YYYY-MM-DD',
+      zippedArchive: true,
+      maxSize: '20m',
+      maxFiles: '30d',
+      format: prodFormat,
+    }),
+    new DailyRotateFile({
+      filename: path.join('logs', 'error-%DATE%.log'),
+      datePattern: 'YYYY-MM-DD',
+      zippedArchive: true,
+      maxSize: '20m',
+      maxFiles: '30d',
+      level: 'error',
+      format: prodFormat,
+    })
+  );
+}
+
+// ────────────────────────────────────────────────────────────
+//  LOGGER INSTANCE
+// ────────────────────────────────────────────────────────────
+
+export const logger = winston.createLogger({
+  level: appConfig.logLevel,
+  defaultMeta: {
+    service: 'chargeback-guard',
+    version: appConfig.version,
+  },
+  transports,
+  exitOnError: false,
+});
+
+// ────────────────────────────────────────────────────────────
+//  CHILD LOGGER FACTORY
+// ────────────────────────────────────────────────────────────
+
+export const createLogger = (module: string): winston.Logger => {
+  return logger.child({ module });
+};
+
+export default logger;

package/src/utils/validators.ts

@@ -0,0 +1,39 @@
+// ============================================================
+//  CHARGEBACK GUARD — Validation Utility Functions
+// ============================================================
+
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+export function isValidIP(ip: string): boolean {
+  const ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;
+  const ipv6  = /^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/;
+  return ipv4.test(ip) || ipv6.test(ip);
+}
+
+export function isValidCurrency(currency: string): boolean {
+  return /^[A-Z]{3}$/.test(currency);
+}
+
+export function isValidUrl(url: string): boolean {
+  try { new URL(url); return true; }
+  catch { return false; }
+}
+
+export function isValidUUID(id: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+}
+
+export function isPositiveAmount(amount: number): boolean {
+  return typeof amount === 'number' && amount > 0 && isFinite(amount);
+}
+
+export function sanitizeString(str: string, maxLength = 255): string {
+  return str.trim().slice(0, maxLength).replace(/[<>]/g, '');
+}
+
+export function isValidDisputeId(id: string): boolean {
+  // Stripe: dp_xxx | PayPal: PP-D-xxx
+  return /^(dp_|PP-D-|ch_)[A-Za-z0-9_-]{10,}$/.test(id) || id.length >= 5;
+}