cannaiq/backend/src/utils/image-storage.ts

/**
 * Local Image Storage Utility
 *
 * Downloads and stores product images to local filesystem with proper hierarchy.
 *
 * Directory structure:
 *   /images/products/<state>/<store_slug>/<brand_slug>/<product_id>/image.webp
 *   /images/products/<state>/<store_slug>/<brand_slug>/<product_id>/image-medium.webp
 *   /images/products/<state>/<store_slug>/<brand_slug>/<product_id>/image-thumb.webp
 *   /images/brands/<brand_slug>/logo.webp
 *
 * This structure allows:
 * - Easy migration to MinIO/S3 (bucket per state)
 * - Browsing by state/store/brand
 * - Multiple images per product (future: gallery)
 */

import axios from 'axios';
// @ts-ignore - sharp module typing quirk
const sharp = require('sharp');
import * as fs from 'fs/promises';
import * as path from 'path';
import { createHash } from 'crypto';

// Base path for image storage - configurable via env
function getImagesBasePath(): string {
  if (process.env.IMAGES_PATH) {
    return process.env.IMAGES_PATH;
  }
  if (process.env.STORAGE_BASE_PATH) {
    return path.join(process.env.STORAGE_BASE_PATH, 'images');
  }
  return './storage/images';
}
const IMAGES_BASE_PATH = getImagesBasePath();

// Public URL base for serving images
const IMAGES_PUBLIC_URL = process.env.IMAGES_PUBLIC_URL || '/images';

export interface LocalImageSizes {
  original: string;   // URL path to original image
  // Legacy compatibility - all point to original until we add image proxy
  full: string;
  medium: string;
  thumb: string;
}

export interface DownloadResult {
  success: boolean;
  urls?: LocalImageSizes;
  localPaths?: LocalImageSizes;
  error?: string;
  bytesDownloaded?: number;
  skipped?: boolean;  // True if image already exists
}

export interface ProductImageContext {
  stateCode: string;      // e.g., "AZ", "CA"
  storeSlug: string;      // e.g., "deeply-rooted"
  brandSlug: string;      // e.g., "high-west-farms"
  productId: string;      // External product ID
  dispensaryId?: number;  // For backwards compat
}

/**
 * Ensure a directory exists
 */
async function ensureDir(dirPath: string): Promise<void> {
  try {
    await fs.mkdir(dirPath, { recursive: true });
  } catch (error: any) {
    if (error.code !== 'EEXIST') throw error;
  }
}

/**
 * Sanitize a string for use in file paths
 */
function slugify(str: string): string {
  return str
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '')
    .substring(0, 50) || 'unknown';
}

/**
 * Generate a short hash from a URL for deduplication
 */
function hashUrl(url: string): string {
  return createHash('md5').update(url).digest('hex').substring(0, 8);
}

/**
 * Download an image from a URL and return the buffer
 */
async function downloadImage(imageUrl: string): Promise<Buffer> {
  const response = await axios.get(imageUrl, {
    responseType: 'arraybuffer',
    timeout: 30000,
    headers: {
      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
      'Accept': 'image/webp,image/apng,image/*,*/*;q=0.8',
    },
  });
  return Buffer.from(response.data);
}

/**
 * Process and save original image (convert to webp for consistency)
 *
 * We store only the original - resizing will be done on-demand via
 * an image proxy service (imgproxy, thumbor, or similar) in the future.
 */
async function processAndSaveImage(
  buffer: Buffer,
  outputDir: string,
  baseFilename: string
): Promise<{ original: string; totalBytes: number }> {
  await ensureDir(outputDir);

  const originalPath = path.join(outputDir, `${baseFilename}.webp`);

  // Convert to webp, preserve original dimensions, high quality
  const originalBuffer = await sharp(buffer)
    .webp({ quality: 90 })
    .toBuffer();

  await fs.writeFile(originalPath, originalBuffer);

  return {
    original: originalPath,
    totalBytes: originalBuffer.length,
  };
}

/**
 * Convert a file path to a public URL
 */
function pathToUrl(filePath: string): string {
  // Find /products/ or /brands/ in the path and extract from there
  const productsMatch = filePath.match(/(\/products\/.*)/);
  const brandsMatch = filePath.match(/(\/brands\/.*)/);

  if (productsMatch) {
    return `${IMAGES_PUBLIC_URL}${productsMatch[1]}`;
  }
  if (brandsMatch) {
    return `${IMAGES_PUBLIC_URL}${brandsMatch[1]}`;
  }

  // Fallback: try to replace base path (works if paths match exactly)
  const relativePath = filePath.replace(IMAGES_BASE_PATH, '');
  return `${IMAGES_PUBLIC_URL}${relativePath}`;
}

/**
 * Build the directory path for a product image
 * Structure: /images/products/<state>/<store>/<brand>/<product>/
 */
function buildProductImagePath(ctx: ProductImageContext): string {
  const state = slugify(ctx.stateCode || 'unknown');
  const store = slugify(ctx.storeSlug || 'unknown');
  const brand = slugify(ctx.brandSlug || 'unknown');
  const product = slugify(ctx.productId || 'unknown');

  return path.join(IMAGES_BASE_PATH, 'products', state, store, brand, product);
}

/**
 * Download and store a product image with proper hierarchy
 *
 * @param imageUrl - The third-party image URL to download
 * @param ctx - Product context (state, store, brand, product)
 * @param options - Download options
 * @returns Download result with local URLs
 */
export async function downloadProductImage(
  imageUrl: string,
  ctx: ProductImageContext,
  options: { skipIfExists?: boolean } = {}
): Promise<DownloadResult> {
  const { skipIfExists = true } = options;

  try {
    if (!imageUrl) {
      return { success: false, error: 'No image URL provided' };
    }

    const outputDir = buildProductImagePath(ctx);
    const urlHash = hashUrl(imageUrl);
    const baseFilename = `image-${urlHash}`;

    // Check if image already exists
    if (skipIfExists) {
      const existingPath = path.join(outputDir, `${baseFilename}.webp`);
      try {
        await fs.access(existingPath);
        // Image exists, return existing URL
        const url = pathToUrl(existingPath);
        return {
          success: true,
          skipped: true,
          urls: {
            original: url,
            full: url,
            medium: url,
            thumb: url,
          },
          localPaths: {
            original: existingPath,
            full: existingPath,
            medium: existingPath,
            thumb: existingPath,
          },
        };
      } catch {
        // Image doesn't exist, continue to download
      }
    }

    // Download the image
    const buffer = await downloadImage(imageUrl);

    // Process and save (original only)
    const result = await processAndSaveImage(buffer, outputDir, baseFilename);
    const url = pathToUrl(result.original);

    return {
      success: true,
      urls: {
        original: url,
        full: url,
        medium: url,
        thumb: url,
      },
      localPaths: {
        original: result.original,
        full: result.original,
        medium: result.original,
        thumb: result.original,
      },
      bytesDownloaded: result.totalBytes,
    };
  } catch (error: any) {
    return {
      success: false,
      error: error.message || 'Failed to download image',
    };
  }
}

/**
 * Legacy function - backwards compatible with old signature
 * Maps to new hierarchy using dispensary_id as store identifier
 */
export async function downloadProductImageLegacy(
  imageUrl: string,
  dispensaryId: number,
  productId: string | number
): Promise<DownloadResult> {
  return downloadProductImage(imageUrl, {
    stateCode: 'unknown',
    storeSlug: `store-${dispensaryId}`,
    brandSlug: 'unknown',
    productId: String(productId),
    dispensaryId,
  });
}

/**
 * Download and store a brand logo
 *
 * @param logoUrl - The brand logo URL
 * @param brandSlug - The brand slug/ID
 * @returns Download result with local URL
 */
export async function downloadBrandLogo(
  logoUrl: string,
  brandSlug: string,
  options: { skipIfExists?: boolean } = {}
): Promise<DownloadResult> {
  const { skipIfExists = true } = options;

  try {
    if (!logoUrl) {
      return { success: false, error: 'No logo URL provided' };
    }

    const safeBrandSlug = slugify(brandSlug);
    const outputDir = path.join(IMAGES_BASE_PATH, 'brands', safeBrandSlug);
    const urlHash = hashUrl(logoUrl);
    const baseFilename = `logo-${urlHash}`;

    // Check if logo already exists
    if (skipIfExists) {
      const existingPath = path.join(outputDir, `${baseFilename}.webp`);
      try {
        await fs.access(existingPath);
        return {
          success: true,
          skipped: true,
          urls: {
            original: pathToUrl(existingPath),
            full: pathToUrl(existingPath),
            medium: pathToUrl(existingPath),
            thumb: pathToUrl(existingPath),
          },
        };
      } catch {
        // Logo doesn't exist, continue
      }
    }

    // Download the image
    const buffer = await downloadImage(logoUrl);

    // Brand logos in their own directory
    await ensureDir(outputDir);
    const logoPath = path.join(outputDir, `${baseFilename}.webp`);

    const logoBuffer = await sharp(buffer)
      .resize(400, 400, { fit: 'inside', withoutEnlargement: true })
      .webp({ quality: 85 })
      .toBuffer();

    await fs.writeFile(logoPath, logoBuffer);

    return {
      success: true,
      urls: {
        original: pathToUrl(logoPath),
        full: pathToUrl(logoPath),
        medium: pathToUrl(logoPath),
        thumb: pathToUrl(logoPath),
      },
      bytesDownloaded: logoBuffer.length,
    };
  } catch (error: any) {
    return {
      success: false,
      error: error.message || 'Failed to download brand logo',
    };
  }
}

/**
 * Check if a product image already exists
 */
export async function productImageExists(
  ctx: ProductImageContext,
  imageUrl: string
): Promise<boolean> {
  const outputDir = buildProductImagePath(ctx);
  const urlHash = hashUrl(imageUrl);
  const imagePath = path.join(outputDir, `image-${urlHash}.webp`);

  try {
    await fs.access(imagePath);
    return true;
  } catch {
    return false;
  }
}

/**
 * Get the local image URL for a product (if exists)
 */
export async function getProductImageUrl(
  ctx: ProductImageContext,
  imageUrl: string
): Promise<LocalImageSizes | null> {
  const outputDir = buildProductImagePath(ctx);
  const urlHash = hashUrl(imageUrl);
  const imagePath = path.join(outputDir, `image-${urlHash}.webp`);

  try {
    await fs.access(imagePath);
    const url = pathToUrl(imagePath);
    return {
      original: url,
      full: url,
      medium: url,
      thumb: url,
    };
  } catch {
    return null;
  }
}

// Track whether image storage is available
let imageStorageReady = false;

export function isImageStorageReady(): boolean {
  return imageStorageReady;
}

/**
 * Initialize the image storage directories
 */
export async function initializeImageStorage(): Promise<void> {
  try {
    await ensureDir(path.join(IMAGES_BASE_PATH, 'products'));
    await ensureDir(path.join(IMAGES_BASE_PATH, 'brands'));
    console.log(`[ImageStorage] Initialized at ${IMAGES_BASE_PATH}`);
    imageStorageReady = true;
  } catch (error: any) {
    console.warn(`[ImageStorage] WARNING: Could not initialize at ${IMAGES_BASE_PATH}: ${error.message}`);
    console.warn('   Image features disabled. Server will continue without image downloads.');
    imageStorageReady = false;
  }
}

/**
 * Get storage stats
 */
export async function getStorageStats(): Promise<{
  basePath: string;
  productCount: number;
  brandCount: number;
  totalSizeBytes: number;
}> {
  let productCount = 0;
  let brandCount = 0;
  let totalSizeBytes = 0;

  async function countDir(dirPath: string): Promise<{ count: number; size: number }> {
    let count = 0;
    let size = 0;
    try {
      const entries = await fs.readdir(dirPath, { withFileTypes: true });
      for (const entry of entries) {
        const fullPath = path.join(dirPath, entry.name);
        if (entry.isDirectory()) {
          const sub = await countDir(fullPath);
          count += sub.count;
          size += sub.size;
        } else if (entry.name.endsWith('.webp') && !entry.name.includes('-')) {
          count++;
          const stat = await fs.stat(fullPath);
          size += stat.size;
        }
      }
    } catch { /* ignore */ }
    return { count, size };
  }

  const products = await countDir(path.join(IMAGES_BASE_PATH, 'products'));
  const brands = await countDir(path.join(IMAGES_BASE_PATH, 'brands'));

  return {
    basePath: IMAGES_BASE_PATH,
    productCount: products.count,
    brandCount: brands.count,
    totalSizeBytes: products.size + brands.size,
  };
}