chargeback-guard 2.0.0

package/src/types/index.ts

@@ -0,0 +1,790 @@
+// ============================================================
+//  CHARGEBACK GUARD — Core Type Definitions (Ultra Pro)
+//  All interfaces, enums, and shared types used across the pkg
+// ============================================================
+
+// ────────────────────────────────────────────────────────────
+//  ENUMS
+// ────────────────────────────────────────────────────────────
+
+export enum Environment {
+  DEVELOPMENT = 'development',
+  STAGING = 'staging',
+  PRODUCTION = 'production',
+}
+
+export enum PaymentProvider {
+  STRIPE = 'stripe',
+  PAYPAL = 'paypal',
+  SQUARE = 'square',
+  BRAINTREE = 'braintree',
+}
+
+export enum DisputeReason {
+  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',
+}
+
+export enum DisputeStatus {
+  NEEDS_RESPONSE = 'needs_response',
+  UNDER_REVIEW = 'under_review',
+  CHARGE_REFUNDED = 'charge_refunded',
+  WON = 'won',
+  LOST = 'lost',
+  WARNING_NEEDS_RESPONSE = 'warning_needs_response',
+  WARNING_UNDER_REVIEW = 'warning_under_review',
+  WARNING_CLOSED = 'warning_closed',
+}
+
+export enum RiskLevel {
+  VERY_LOW = 'very_low',
+  LOW = 'low',
+  MEDIUM = 'medium',
+  HIGH = 'high',
+  CRITICAL = 'critical',
+}
+
+export enum ConfidenceLevel {
+  VERY_HIGH = 'very_high',
+  HIGH = 'high',
+  MEDIUM = 'medium',
+  LOW = 'low',
+}
+
+export enum EvidenceType {
+  DELIVERY_PROOF = 'delivery_proof',
+  DEVICE_FINGERPRINT = 'device_fingerprint',
+  CUSTOMER_COMMUNICATION = 'customer_communication',
+  TRANSACTION_LOG = 'transaction_log',
+  BEHAVIOR_ANALYSIS = 'behavior_analysis',
+  CUSTOMER_HISTORY = 'customer_history',
+  EMAIL_CONFIRMATION = 'email_confirmation',
+  PAYMENT_LOG = 'payment_log',
+  GEOLOCATION = 'geolocation',
+  BROWSER_SCREENSHOT = 'browser_screenshot',
+}
+
+export enum NotificationChannel {
+  EMAIL = 'email',
+  SMS = 'sms',
+  WEBHOOK = 'webhook',
+  IN_APP = 'in_app',
+}
+
+export enum NotificationEvent {
+  PAYMENT_REGISTERED = 'payment:registered',
+  DISPUTE_DETECTED = 'dispute:detected',
+  DISPUTE_REPLIED = 'dispute:replied',
+  DISPUTE_WON = 'dispute:won',
+  DISPUTE_LOST = 'dispute:lost',
+  HIGH_RISK_TRANSACTION = 'transaction:high_risk',
+  FRAUD_DETECTED = 'fraud:detected',
+  ERROR = 'error',
+}
+
+export enum SubscriptionPlan {
+  FREE = 'free',
+  STARTER = 'starter',
+  PRO = 'pro',
+  ENTERPRISE = 'enterprise',
+  CUSTOM = 'custom',
+}
+
+// ────────────────────────────────────────────────────────────
+//  CONFIGURATION INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface ChargebackGuardConfig {
+  apiKey: string;
+  webhookSecret?: string;
+  environment?: Environment;
+  autoReply?: boolean;
+  evidenceCollection?: boolean;
+  database?: DatabaseConfig;
+  redis?: RedisConfig;
+  notifications?: NotificationConfig;
+  security?: SecurityConfig;
+  ai?: AIConfig;
+  billing?: BillingConfig;
+}
+
+export interface DatabaseConfig {
+  type: 'sqlite' | 'postgresql' | 'mysql';
+  url: string;
+  poolMin?: number;
+  poolMax?: number;
+  debug?: boolean;
+}
+
+export interface RedisConfig {
+  url: string;
+  password?: string;
+  db?: number;
+  ttl?: number;
+}
+
+export interface NotificationConfig {
+  email?: EmailConfig;
+  sms?: SMSConfig;
+  webhooks?: WebhookConfig[];
+  channels?: NotificationChannel[];
+}
+
+export interface EmailConfig {
+  host: string;
+  port: number;
+  secure: boolean;
+  user: string;
+  pass: string;
+  fromName: string;
+  fromAddress: string;
+}
+
+export interface SMSConfig {
+  accountSid: string;
+  authToken: string;
+  phoneNumber: string;
+}
+
+export interface WebhookConfig {
+  url: string;
+  secret?: string;
+  events?: NotificationEvent[];
+  retries?: number;
+}
+
+export interface SecurityConfig {
+  jwtSecret: string;
+  jwtExpiresIn?: string;
+  encryptionKey: string;
+  bcryptRounds?: number;
+  rateLimit?: RateLimitConfig;
+}
+
+export interface RateLimitConfig {
+  windowMs: number;
+  maxRequests: number;
+  skipFailedRequests?: boolean;
+}
+
+export interface AIConfig {
+  openaiApiKey?: string;
+  modelPath?: string;
+  fraudThreshold?: number;
+  riskScoreHigh?: number;
+  riskScoreMedium?: number;
+}
+
+export interface BillingConfig {
+  plan?: SubscriptionPlan;
+  revenueSharePercentage?: number;
+  monthlyPrice?: number;
+}
+
+// ────────────────────────────────────────────────────────────
+//  PAYMENT & ORDER INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface PaymentData {
+  orderId: string;
+  amount: number;
+  currency: string;
+  customerEmail: string;
+  customerName?: string;
+  customerIp?: string;
+  userAgent?: string;
+  sessionData?: SessionData;
+  deviceFingerprint?: DeviceFingerprint;
+  shippingAddress?: Address;
+  billingAddress?: Address;
+  paymentMethod?: string;
+  cardLastFour?: string;
+  cardBrand?: string;
+  transactionId?: string;
+  provider?: PaymentProvider;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SessionData {
+  sessionId: string;
+  startedAt: string;
+  duration?: number;
+  pageViews?: PageView[];
+  clickTracking?: ClickEvent[];
+  formInteractions?: FormInteraction[];
+  mouseTracking?: MousePosition[];
+  scrollDepth?: number;
+  timeOnCheckout?: number;
+  referrer?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+}
+
+export interface PageView {
+  url: string;
+  title?: string;
+  duration: number;
+  timestamp: string;
+}
+
+export interface ClickEvent {
+  element: string;
+  x: number;
+  y: number;
+  timestamp: string;
+}
+
+export interface FormInteraction {
+  field: string;
+  action: 'focus' | 'blur' | 'change' | 'submit';
+  timestamp: string;
+}
+
+export interface MousePosition {
+  x: number;
+  y: number;
+  timestamp: string;
+}
+
+export interface DeviceFingerprint {
+  screenResolution?: string;
+  timezone?: string;
+  language?: string;
+  plugins?: string[];
+  fonts?: string[];
+  webgl?: string;
+  canvas?: string;
+  cookiesEnabled?: boolean;
+  doNotTrack?: string;
+  platform?: string;
+  hardwareConcurrency?: number;
+  deviceMemory?: number;
+  touchPoints?: number;
+}
+
+export interface Address {
+  line1: string;
+  line2?: string;
+  city: string;
+  state?: string;
+  postalCode: string;
+  country: string;
+}
+
+export interface ShippingInfo {
+  address: Address;
+  carrier?: string;
+  trackingNumber?: string;
+  estimatedDelivery?: string;
+  shippedAt?: string;
+  deliveredAt?: string;
+  signature?: boolean;
+  signatureTimestamp?: string;
+  gpsCoordinates?: GeoCoordinates;
+  deliveryStatus?: 'pending' | 'in_transit' | 'delivered' | 'failed';
+}
+
+export interface GeoCoordinates {
+  lat: number;
+  lng: number;
+  accuracy?: number;
+}
+
+// ────────────────────────────────────────────────────────────
+//  EVIDENCE INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface Evidence {
+  collectionId: string;
+  orderId: string;
+  timestamp: string;
+  trustScore: number;
+  riskLevel: RiskLevel;
+  data: EvidenceData;
+  encrypted?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface EvidenceData {
+  customerData: CustomerEvidenceData;
+  transactionData: TransactionEvidenceData;
+  shippingData?: ShippingEvidenceData;
+  interactionData?: InteractionEvidenceData;
+  deviceFingerprint?: DeviceEvidenceData;
+  emailConfirmation?: EmailEvidenceData;
+  customerHistory?: CustomerHistoryData;
+  paymentLog?: PaymentLogData;
+  geolocation?: GeolocationData;
+}
+
+export interface CustomerEvidenceData {
+  ipAddress: string;
+  userAgent: string;
+  acceptLanguage?: string;
+  referer?: string;
+  deviceId: string;
+  email?: string;
+  countryCode?: string;
+  city?: string;
+  isp?: string;
+  ipReputation?: number;
+}
+
+export interface TransactionEvidenceData {
+  timestamp: string;
+  amount: number;
+  currency: string;
+  paymentMethod?: string;
+  cardLastFour?: string;
+  transactionId: string;
+  processorResponse?: string;
+  cvvMatch?: boolean;
+  avsMatch?: boolean;
+}
+
+export interface ShippingEvidenceData {
+  address?: Address;
+  zip?: string;
+  country?: string;
+  shippingDate?: string;
+  trackingNumber?: string;
+  estimatedDelivery?: string;
+  deliveryDate?: string;
+  signature?: boolean;
+  gpsCoordinates?: GeoCoordinates;
+  carrierVerification?: string;
+}
+
+export interface InteractionEvidenceData {
+  sessionDuration: number;
+  pageViews: PageView[];
+  clickTracking: ClickEvent[];
+  formInteractions: FormInteraction[];
+  timeOnCheckout: number;
+  mouseTracking?: MousePosition[];
+  scrollDepth?: number;
+}
+
+export interface DeviceEvidenceData {
+  screenResolution?: string;
+  timezone?: string;
+  language?: string;
+  plugins?: string[];
+  fonts?: string[];
+  webgl?: string;
+  canvas?: string;
+  fingerprint?: string;
+}
+
+export interface EmailEvidenceData {
+  sentTo: string;
+  sentAt: string;
+  opened?: boolean;
+  openedAt?: string;
+  clickedLinks?: string[];
+  bouncedAt?: string;
+}
+
+export interface CustomerHistoryData {
+  accountCreatedAt: string;
+  accountAge: number;
+  previousPurchases: number;
+  previousDisputes: number;
+  riskScore: number;
+  trustScore: number;
+  loyaltyStatus?: string;
+  reviewsGiven?: number;
+  supportTickets?: number;
+}
+
+export interface PaymentLogData {
+  attempts: number;
+  successful: number;
+  failed: number;
+  lastAttemptAt?: string;
+  methods?: string[];
+}
+
+export interface GeolocationData {
+  ip: string;
+  country: string;
+  city: string;
+  timezone: string;
+  latitude?: number;
+  longitude?: number;
+  isp?: string;
+  org?: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  DISPUTE INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface Dispute {
+  id: string;
+  orderId?: string;
+  amount: number;
+  currency?: string;
+  reason: DisputeReason;
+  status: DisputeStatus;
+  provider: PaymentProvider;
+  evidenceDueBy?: string;
+  createdAt: string;
+  updatedAt?: string;
+  metadata?: Record<string, unknown>;
+  evidence?: Record<string, unknown>;
+}
+
+export interface DisputeAnalysis {
+  disputeId: string;
+  riskLevel: RiskLevel;
+  confidenceScore: number;
+  deliveryProofStrength: number;
+  deviceConsistency: number;
+  customerReputationScore: number;
+  transactionNormality: number;
+  fraudProbability: number;
+  recommendedAction: 'fight' | 'accept' | 'review';
+  analysisReasons: string[];
+  analyzedAt: string;
+}
+
+export interface DisputeReply {
+  disputeId: string;
+  orderId?: string;
+  generatedAt: string;
+  evidenceItems: EvidenceItem[];
+  summary: ReplySummary;
+  caseArgument?: string;
+  attachments?: Attachment[];
+  bankFormat?: BankReplyFormat;
+}
+
+export interface EvidenceItem {
+  type: EvidenceType | string;
+  description: string;
+  data: Record<string, unknown>;
+  weight?: number;
+}
+
+export interface ReplySummary {
+  trustScore: number;
+  confidenceLevel: ConfidenceLevel;
+  recommendation: string;
+  keyPoints?: string[];
+}
+
+export interface Attachment {
+  type: string;
+  name: string;
+  mimeType: string;
+  description: string;
+  base64Data?: string;
+  url?: string;
+}
+
+export interface BankReplyFormat {
+  dispute_id: string;
+  evidence_items: EvidenceItem[];
+  merchant_reference: string;
+  submitted_at: string;
+  case_argument: string;
+  attachment_files?: Attachment[];
+}
+
+// ────────────────────────────────────────────────────────────
+//  ANALYTICS INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface ProtectionStats {
+  totalOrders: number;
+  totalDisputes: number;
+  resolvedDisputes: number;
+  wonDisputes: number;
+  lostDisputes: number;
+  pendingDisputes: number;
+  winRate: number;
+  totalMoneyRecovered: number;
+  totalMoneyLost: number;
+  averageResolutionTime: number;
+  chargebackRate: number;
+  estimatedSavings: number;
+  period?: StatsPeriod;
+}
+
+export interface StatsPeriod {
+  from: string;
+  to: string;
+  granularity: 'day' | 'week' | 'month' | 'year';
+}
+
+export interface TimeSeriesPoint {
+  date: string;
+  value: number;
+  label?: string;
+}
+
+export interface DashboardMetrics {
+  realTime: RealTimeMetrics;
+  charts: ChartData;
+  alerts: AlertItem[];
+  topRisks: RiskItem[];
+}
+
+export interface RealTimeMetrics {
+  activeDisputes: number;
+  pendingReplies: number;
+  lastHourTransactions: number;
+  suspiciousActivities: number;
+  systemHealth: 'healthy' | 'degraded' | 'down';
+}
+
+export interface ChartData {
+  monthlyChargebacks: TimeSeriesPoint[];
+  recoveryRate: TimeSeriesPoint[];
+  disputesByReason: Record<string, number>;
+  riskDistribution: Record<string, number>;
+  costSavings: TimeSeriesPoint[];
+}
+
+export interface AlertItem {
+  id: string;
+  severity: 'info' | 'warning' | 'critical';
+  message: string;
+  orderId?: string;
+  createdAt: string;
+  resolved: boolean;
+}
+
+export interface RiskItem {
+  orderId: string;
+  amount: number;
+  riskScore: number;
+  riskLevel: RiskLevel;
+  reason: string;
+  detectedAt: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  API INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: ApiError;
+  meta?: ApiMeta;
+}
+
+export interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  stack?: string;
+}
+
+export interface ApiMeta {
+  timestamp: string;
+  requestId: string;
+  version: string;
+  pagination?: PaginationMeta;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+export interface PaginationQuery {
+  page?: number;
+  limit?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface FilterQuery extends PaginationQuery {
+  from?: string;
+  to?: string;
+  status?: string;
+  reason?: string;
+  provider?: string;
+  riskLevel?: string;
+  search?: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  NOTIFICATION INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface NotificationPayload {
+  event: NotificationEvent;
+  channel: NotificationChannel;
+  recipient: NotificationRecipient;
+  data: Record<string, unknown>;
+  template?: string;
+  priority?: 'low' | 'normal' | 'high' | 'urgent';
+}
+
+export interface NotificationRecipient {
+  email?: string;
+  phone?: string;
+  webhookUrl?: string;
+  userId?: string;
+  name?: string;
+}
+
+export interface NotificationResult {
+  success: boolean;
+  channel: NotificationChannel;
+  messageId?: string;
+  error?: string;
+  sentAt: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  ML / AI INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface FraudFeatures {
+  deviceFingerprint: string;
+  ipReputation: number;
+  customerAge: number;
+  purchaseHistory: number;
+  behavioralScore: number;
+  geoRiskScore: number;
+  velocityScore: number;
+  cardRiskScore: number;
+  emailRiskScore: number;
+  timeRiskScore: number;
+}
+
+export interface FraudPrediction {
+  isFraud: boolean;
+  probability: number;
+  riskScore: number;
+  riskLevel: RiskLevel;
+  features: Partial<FraudFeatures>;
+  modelVersion: string;
+  predictedAt: string;
+  explanation?: string[];
+}
+
+export interface PatternResult {
+  patternType: string;
+  detected: boolean;
+  confidence: number;
+  evidence: string[];
+  severity: 'low' | 'medium' | 'high';
+}
+
+// ────────────────────────────────────────────────────────────
+//  WEBHOOK INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface WebhookEvent {
+  id: string;
+  type: string;
+  provider: PaymentProvider;
+  created: number;
+  data: {
+    object: Record<string, unknown>;
+    previous_attributes?: Record<string, unknown>;
+  };
+  livemode?: boolean;
+  request?: {
+    id: string | null;
+    idempotency_key: string | null;
+  };
+}
+
+export interface ProcessedWebhookResult {
+  eventId: string;
+  type: string;
+  processed: boolean;
+  action?: string;
+  error?: string;
+  processedAt: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  DATABASE MODEL INTERFACES
+// ────────────────────────────────────────────────────────────
+
+export interface OrderRecord {
+  id: number;
+  orderId: string;
+  merchantId: string;
+  amount: number;
+  currency: string;
+  customerEmail: string;
+  status: string;
+  provider: PaymentProvider;
+  registeredAt: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EvidenceRecord {
+  id: number;
+  orderId: string;
+  collectionId: string;
+  evidenceJson: string;
+  trustScore: number;
+  riskLevel: RiskLevel;
+  collectedAt: string;
+  createdAt: string;
+}
+
+export interface DisputeRecord {
+  id: number;
+  disputeId: string;
+  orderId: string;
+  amount: number;
+  reason: DisputeReason;
+  status: DisputeStatus;
+  provider: PaymentProvider;
+  replyJson?: string;
+  replySubmittedAt?: string;
+  resolvedAt?: string;
+  wonAt?: string;
+  lostAt?: string;
+  evidenceDueBy?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MerchantRecord {
+  id: number;
+  merchantId: string;
+  name: string;
+  email: string;
+  apiKey: string;
+  plan: SubscriptionPlan;
+  webhookUrl?: string;
+  settings?: string;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  UTILITY TYPE HELPERS
+// ────────────────────────────────────────────────────────────
+
+export type AsyncResult<T> = Promise<ApiResponse<T>>;
+export type Nullable<T> = T | null;
+export type Optional<T> = T | undefined;
+export type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
+  Pick<T, Exclude<keyof T, Keys>> & { [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>> }[Keys];