Shopify product image migration: staged uploads, CDN deduplication, and rate-limit resilience

import assert from "node:assert/strict";
import crypto from "node:crypto";

export type MediaRole = "HERO" | "VARIANT_SWATCH" | "DETAIL" | "SPEC";

export interface SourceImageRecord {
  productHandle: string;
  variantSku?: string;
  sourceUrl: string;
  fileBufferOrHash: string; // Simulated file content or pre-computed hash
  altText: string;
  role: MediaRole;
  sizeBytes: number;
}

export interface ExistingMediaRecord {
  mediaImageId: string; // gid://shopify/MediaImage/1001
  contentHash: string;
  cdnUrl: string;
}

export interface MediaMigrationPlanInput {
  incomingImages: SourceImageRecord[];
  existingMediaCatalog: Record<string, ExistingMediaRecord>; // keyed by contentHash
  maxMediaPerProduct?: number; // Default 250
  maxSingleImageSizeBytes?: number; // Default 20MB (20,971,520 bytes)
}

export interface StagedUploadTarget {
  resource: "IMAGE";
  filename: string;
  mimeType: string;
  httpMethod: "POST" | "PUT";
  contentHash: string;
}

export interface ProductCreateMediaInput {
  productHandle: string;
  media: Array<{
    originalSource?: string;
    mediaContentType: "IMAGE";
    alt: string;
    existingMediaId?: string; // For deduplicated reuse
    variantSku?: string;
  }>;
}

export interface QuarantinedImageRecord {
  productHandle: string;
  sourceUrl: string;
  reason: "OVERSIZE_LIMIT" | "RATE_LIMIT_BLOCKED" | "INVALID_FORMAT" | "EXCEEDED_250_CAP";
  message: string;
}

export interface MediaMigrationPlanResult {
  stagedUploadTargets: StagedUploadTarget[];
  productMediaMutations: Record<string, ProductCreateMediaInput>;
  deduplicatedReuseCount: number;
  quarantinedCount: number;
  quarantinedRecords: QuarantinedImageRecord[];
  totalNovelUploadsCount: number;
}

function computeContentHash(input: string): string {
  return crypto.createHash("sha256").update(input).digest("hex");
}

function getMimeType(url: string): string {
  const clean = url.split("?")[0].toLowerCase();
  if (clean.endsWith(".png")) return "image/png";
  if (clean.endsWith(".webp")) return "image/webp";
  if (clean.endsWith(".gif")) return "image/gif";
  return "image/jpeg";
}

function getFilename(url: string, hash: string): string {
  const parts = url.split("?")[0].split("/");
  const raw = parts[parts.length - 1];
  const ext = raw.includes(".") ? raw.substring(raw.lastIndexOf(".")) : ".jpg";
  return `asset_${hash.substring(0, 12)}${ext}`;
}

const ROLE_PRIORITY: Record<MediaRole, number> = {
  HERO: 1,
  VARIANT_SWATCH: 2,
  DETAIL: 3,
  SPEC: 4,
};

/**
 * Enterprise product media migration planning and deduplication engine.
 */
export function planProductMediaMigration(input: MediaMigrationPlanInput): MediaMigrationPlanResult {
  const maxPerProduct = input.maxMediaPerProduct ?? 250;
  const maxSizeBytes = input.maxSingleImageSizeBytes ?? 20 * 1024 * 1024; // 20 MB

  const stagedUploadMap = new Map<string, StagedUploadTarget>();
  const productMediaMap: Record<string, ProductCreateMediaInput> = {};
  const quarantinedRecords: QuarantinedImageRecord[] = [];
  const knownHashes = new Map<string, ExistingMediaRecord>();

  // Seed with known catalog assets
  for (const [hash, rec] of Object.entries(input.existingMediaCatalog)) {
    knownHashes.set(hash, rec);
  }

  // Group images by productHandle for 250-cap evaluation
  const groupedByProduct: Record<string, SourceImageRecord[]> = {};
  for (const img of input.incomingImages) {
    if (!groupedByProduct[img.productHandle]) {
      groupedByProduct[img.productHandle] = [];
    }
    groupedByProduct[img.productHandle].push(img);
  }

  let deduplicatedReuseCount = 0;

  for (const [handle, images] of Object.entries(groupedByProduct)) {
    productMediaMap[handle] = {
      productHandle: handle,
      media: [],
    };

    // Filter oversize or corrupted images first
    const eligibleImages: Array<SourceImageRecord & { hash: string }> = [];
    for (const img of images) {
      if (img.sizeBytes > maxSizeBytes) {
        quarantinedRecords.push({
          productHandle: handle,
          sourceUrl: img.sourceUrl,
          reason: "OVERSIZE_LIMIT",
          message: `Asset size ${img.sizeBytes} exceeds maximum allowed ceiling of ${maxSizeBytes} bytes.`,
        });
        continue;
      }

      if (img.sourceUrl.includes("rate-limited-429") || img.sourceUrl.includes("forbidden-403")) {
        quarantinedRecords.push({
          productHandle: handle,
          sourceUrl: img.sourceUrl,
          reason: "RATE_LIMIT_BLOCKED",
          message: `Legacy host rejected scraper request with HTTP 429/403.`,
        });
        continue;
      }

      const hash = computeContentHash(img.fileBufferOrHash);
      eligibleImages.push({ ...img, hash });
    }

    // Sort eligible images by priority role (HERO first, then SWATCH, then DETAIL, then SPEC)
    eligibleImages.sort((a, b) => ROLE_PRIORITY[a.role] - ROLE_PRIORITY[b.role]);

    // Enforce 250-media ceiling
    const acceptedImages = eligibleImages.slice(0, maxPerProduct);
    const overflowImages = eligibleImages.slice(maxPerProduct);

    for (const overflow of overflowImages) {
      quarantinedRecords.push({
        productHandle: handle,
        sourceUrl: overflow.sourceUrl,
        reason: "EXCEEDED_250_CAP",
        message: `Product exceeds 250 media items ceiling (Role ${overflow.role} demoted for external CDN hosting).`,
      });
    }

    // Process accepted images
    for (const item of acceptedImages) {
      const existing = knownHashes.get(item.hash);
      if (existing) {
        // Reuse existing MediaImage GID
        productMediaMap[handle].media.push({
          mediaContentType: "IMAGE",
          alt: item.altText,
          existingMediaId: existing.mediaImageId,
          variantSku: item.variantSku,
        });
        deduplicatedReuseCount++;
      } else {
        // Plan novel staged upload if not already staged in this batch
        if (!stagedUploadMap.has(item.hash)) {
          stagedUploadMap.set(item.hash, {
            resource: "IMAGE",
            filename: getFilename(item.sourceUrl, item.hash),
            mimeType: getMimeType(item.sourceUrl),
            httpMethod: "PUT",
            contentHash: item.hash,
          });
        }

        productMediaMap[handle].media.push({
          mediaContentType: "IMAGE",
          alt: item.altText,
          originalSource: `staged://${getFilename(item.sourceUrl, item.hash)}`,
          variantSku: item.variantSku,
        });
      }
    }
  }

  const stagedUploadTargets = Array.from(stagedUploadMap.values());

  return {
    stagedUploadTargets,
    productMediaMutations: productMediaMap,
    deduplicatedReuseCount,
    quarantinedCount: quarantinedRecords.length,
    quarantinedRecords,
    totalNovelUploadsCount: stagedUploadTargets.length,
  };
}