// src/types/job-data.ts

/**
 * Common metadata for context propagation across job queues (ADR-051).
 * This enables tracing a request from API layer through worker execution.
 */
export interface JobMeta {
  /** The request ID from the initiating API request */
  requestId?: string;
  /** The user ID who triggered the job (if authenticated) */
  userId?: string;
  /** The origin of the job (e.g., 'api', 'scheduler', 'admin') */
  origin?: 'api' | 'api-reprocess' | 'scheduler' | 'admin' | 'manual';
}

/**
 * Defines the shape of the data payload for a flyer processing job.
 * This is the data that gets passed to the BullMQ worker.
 */
export interface FlyerJobData {
  filePath: string;
  originalFileName: string;
  checksum: string;
  userId?: string;
  submitterIp?: string;
  userProfileAddress?: string;
  baseUrl: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a file cleanup job.
 */
export interface CleanupJobData {
  flyerId: number;
  paths?: string[];
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a token cleanup job.
 */
export interface TokenCleanupJobData {
  timestamp: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a daily analytics report job.
 */
export interface AnalyticsJobData {
  reportDate: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a weekly analytics report job.
 */
export interface WeeklyAnalyticsJobData {
  reportYear: number;
  reportWeek: number;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for an email sending job.
 */
export interface EmailJobData {
  to: string;
  subject: string;
  text: string;
  html: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a receipt processing job.
 */
export interface ReceiptJobData {
  /** ID of the receipt record in the database */
  receiptId: number;
  /** Path to the uploaded receipt image */
  imagePath: string;
  /** User who uploaded the receipt */
  userId: string;
  /** Known store ID (optional, for hint to OCR) */
  storeId?: number;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for an expiry alert job.
 */
export interface ExpiryAlertJobData {
  /** Type of alert job */
  alertType: 'daily_check' | 'user_specific';
  /** For user_specific jobs, the target user */
  userId?: string;
  /** Days ahead to check for expiring items */
  daysAhead?: number;
  /** Timestamp when the job was scheduled */
  scheduledAt: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}

/**
 * Defines the shape of the data payload for a barcode detection job.
 */
export interface BarcodeDetectionJobData {
  /** ID of the scan record in the database */
  scanId: number;
  /** Path to the uploaded barcode image */
  imagePath: string;
  /** User who uploaded the image */
  userId: string;
  /** Context propagation metadata (ADR-051) */
  meta?: JobMeta;
}
