// src/types/upc.ts
// ============================================================================
// UPC SCANNING TYPE DEFINITIONS
// ============================================================================
// Type definitions for the UPC barcode scanning feature.
// Covers scan requests, results, history, and external API lookups.
// ============================================================================

/**
 * Valid sources for UPC barcode scans.
 * - image_upload: User uploaded an image containing a barcode
 * - manual_entry: User typed the UPC code manually
 * - phone_app: Scan came from a mobile phone app
 * - camera_scan: Real-time camera scanning in browser
 */
export type UpcScanSource = 'image_upload' | 'manual_entry' | 'phone_app' | 'camera_scan';

/**
 * External UPC database providers supported for lookups.
 * - openfoodfacts: Open Food Facts API (free, open source)
 * - upcitemdb: UPC Item DB API
 * - barcodelookup: Barcode Lookup API
 * - manual: Manually entered product info
 * - unknown: Source not identified
 */
export type UpcExternalSource =
  | 'openfoodfacts'
  | 'upcitemdb'
  | 'barcodelookup'
  | 'manual'
  | 'unknown';

// ============================================================================
// REQUEST TYPES
// ============================================================================

/**
 * Request to scan a UPC barcode.
 * Either upc_code (manual entry) or image_base64 (image scan) must be provided.
 */
export interface UpcScanRequest {
  /** UPC code entered manually (8-14 digits) */
  upc_code?: string;
  /** Base64-encoded image containing barcode */
  image_base64?: string;
  /** How the scan was initiated */
  scan_source: UpcScanSource;
}

/**
 * Request to look up a UPC code without recording the scan.
 */
export interface UpcLookupRequest {
  /** UPC code to look up (8-14 digits) */
  upc_code: string;
  /** Whether to check external APIs if not found locally */
  include_external?: boolean;
}

/**
 * Request to link a UPC code to an existing product (admin operation).
 */
export interface UpcLinkRequest {
  /** The UPC code to link */
  upc_code: string;
  /** The product ID to link to */
  product_id: number;
}

// ============================================================================
// RESPONSE TYPES
// ============================================================================

/**
 * Product information returned when a UPC match is found.
 */
export interface UpcProductMatch {
  /** Internal product ID */
  product_id: number;
  /** Product name */
  name: string;
  /** Brand name, if known */
  brand: string | null;
  /** Product category */
  category: string | null;
  /** Product description */
  description: string | null;
  /** Product size/weight (e.g., "500g") */
  size: string | null;
  /** The UPC code */
  upc_code: string;
  /** Product image URL, if available */
  image_url: string | null;
  /** Link to master grocery item */
  master_item_id: number | null;
}

/**
 * Product information from external UPC database lookup.
 */
export interface UpcExternalProductInfo {
  /** Product name from external source */
  name: string;
  /** Brand name from external source */
  brand: string | null;
  /** Product category from external source */
  category: string | null;
  /** Product description from external source */
  description: string | null;
  /** Product image URL from external source */
  image_url: string | null;
  /** Which external API provided this data */
  source: UpcExternalSource;
  /** Raw JSON data from the external API */
  raw_data?: Record<string, unknown>;
}

/**
 * Complete result from a UPC scan operation.
 */
export interface UpcScanResult {
  /** ID of the recorded scan (for history tracking) */
  scan_id: number;
  /** The scanned UPC code */
  upc_code: string;
  /** Matched product from our database, if found */
  product: UpcProductMatch | null;
  /** Product info from external lookup, if performed */
  external_lookup: UpcExternalProductInfo | null;
  /** Confidence score of barcode detection (0.0-1.0) */
  confidence: number | null;
  /** Whether any product info was found (internal or external) */
  lookup_successful: boolean;
  /** Whether this UPC was not previously in our database */
  is_new_product: boolean;
  /** Timestamp of the scan */
  scanned_at: string;
}

/**
 * Result from a UPC lookup (without recording scan history).
 */
export interface UpcLookupResult {
  /** The looked up UPC code */
  upc_code: string;
  /** Matched product from our database, if found */
  product: UpcProductMatch | null;
  /** Product info from external lookup, if performed and enabled */
  external_lookup: UpcExternalProductInfo | null;
  /** Whether any product info was found */
  found: boolean;
  /** Whether the lookup result came from cache */
  from_cache: boolean;
}

// ============================================================================
// DATABASE ENTITY TYPES
// ============================================================================

/**
 * UPC scan history record from the database.
 * Maps to public.upc_scan_history table.
 */
export interface UpcScanHistoryRecord {
  /** Primary key */
  scan_id: number;
  /** User who performed the scan */
  user_id: string;
  /** The scanned UPC code */
  upc_code: string;
  /** Matched product ID, if found */
  product_id: number | null;
  /** How the scan was performed */
  scan_source: UpcScanSource;
  /** Confidence score from barcode detection */
  scan_confidence: number | null;
  /** Path to uploaded barcode image */
  raw_image_path: string | null;
  /** Whether the lookup found product info */
  lookup_successful: boolean;
  /** When the scan was recorded */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

/**
 * External UPC lookup cache record from the database.
 * Maps to public.upc_external_lookups table.
 */
export interface UpcExternalLookupRecord {
  /** Primary key */
  lookup_id: number;
  /** The UPC code that was looked up */
  upc_code: string;
  /** Product name from external API */
  product_name: string | null;
  /** Brand name from external API */
  brand_name: string | null;
  /** Product category from external API */
  category: string | null;
  /** Product description from external API */
  description: string | null;
  /** Product image URL from external API */
  image_url: string | null;
  /** Which external API provided this data */
  external_source: UpcExternalSource;
  /** Full raw JSON response from external API */
  lookup_data: Record<string, unknown> | null;
  /** Whether the external lookup found product info */
  lookup_successful: boolean;
  /** When the lookup was cached */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
}

// ============================================================================
// API RESPONSE TYPES
// ============================================================================

/**
 * Response for scan history listing.
 */
export interface UpcScanHistoryResponse {
  /** List of scan history records */
  scans: UpcScanHistoryRecord[];
  /** Total count for pagination */
  total: number;
}

/**
 * Barcode detection result from image processing.
 */
export interface BarcodeDetectionResult {
  /** Whether a barcode was detected */
  detected: boolean;
  /** The decoded UPC code, if detected */
  upc_code: string | null;
  /** Confidence score of detection (0.0-1.0) */
  confidence: number | null;
  /** Barcode format detected (UPC-A, UPC-E, EAN-13, etc.) */
  format: string | null;
  /** Error message if detection failed */
  error: string | null;
}

// ============================================================================
// UTILITY TYPES
// ============================================================================

/**
 * Options for UPC scan history queries.
 */
export interface UpcScanHistoryQueryOptions {
  /** User ID to filter by */
  user_id: string;
  /** Maximum number of results */
  limit?: number;
  /** Offset for pagination */
  offset?: number;
  /** Filter by lookup success status */
  lookup_successful?: boolean;
  /** Filter by scan source */
  scan_source?: UpcScanSource;
  /** Filter by date range start */
  from_date?: string;
  /** Filter by date range end */
  to_date?: string;
}

/**
 * Options for external UPC lookup.
 */
export interface UpcExternalLookupOptions {
  /** UPC code to look up */
  upc_code: string;
  /** Whether to skip cache and force fresh lookup */
  force_refresh?: boolean;
  /** Maximum age of cached data in hours (default: 168 = 7 days) */
  max_cache_age_hours?: number;
}
