cms.c2sgmbh/docs/plans/2026-02-14-youtube-thumbnail-download.md

YouTube Thumbnail Download — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Automatically download YouTube video thumbnails and channel images as Payload Media documents so they're available offline and optimized by Payload's Sharp pipeline.

Architecture: Inline download during sync flow (no separate queue). A reusable downloadAndUploadImage() utility fetches images from URLs and creates Payload Media documents. Integration hooks on YouTubeContent and YouTubeChannels trigger downloads. A bulk endpoint backfills existing records.

Tech Stack: Node.js fetch API, Payload CMS Local API (payload.create), Sharp (via Payload's Media collection)

---

Task 1: Create downloadAndUploadImage utility

Files:

• Create: src/lib/utils/media-download.ts
• Test: tests/unit/media-download.test.ts

Step 1: Write the test file

// tests/unit/media-download.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { downloadAndUploadImage } from '../../src/lib/utils/media-download'

// Mock fetch globally
const mockFetch = vi.fn()
vi.stubGlobal('fetch', mockFetch)

// Mock payload instance
const mockPayload = {
  find: vi.fn(),
  create: vi.fn(),
}

describe('downloadAndUploadImage', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('should download image and create media document', async () => {
    // Mock successful fetch
    const mockBuffer = Buffer.from('fake-image-data')
    mockFetch.mockResolvedValue({
      ok: true,
      headers: { get: (h: string) => h === 'content-type' ? 'image/jpeg' : '1024' },
      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
    })

    // Mock no existing duplicate
    mockPayload.find.mockResolvedValue({ docs: [], totalDocs: 0 })

    // Mock media creation
    mockPayload.create.mockResolvedValue({ id: 42 })

    const result = await downloadAndUploadImage(mockPayload as any, {
      url: 'https://img.youtube.com/vi/abc123/hqdefault.jpg',
      filename: 'abc123_thumbnail.jpg',
      alt: 'Video Thumbnail',
    })

    expect(result).toBe(42)
    expect(mockFetch).toHaveBeenCalledWith(
      'https://img.youtube.com/vi/abc123/hqdefault.jpg',
      expect.objectContaining({ signal: expect.any(AbortSignal) })
    )
    expect(mockPayload.create).toHaveBeenCalledWith(
      expect.objectContaining({
        collection: 'media',
        file: expect.objectContaining({
          name: 'abc123_thumbnail.jpg',
          mimetype: 'image/jpeg',
        }),
      })
    )
  })

  it('should return existing media ID if duplicate found', async () => {
    mockPayload.find.mockResolvedValue({
      docs: [{ id: 99 }],
      totalDocs: 1,
    })

    const result = await downloadAndUploadImage(mockPayload as any, {
      url: 'https://img.youtube.com/vi/abc123/hqdefault.jpg',
      filename: 'abc123_thumbnail.jpg',
    })

    expect(result).toBe(99)
    expect(mockFetch).not.toHaveBeenCalled()
  })

  it('should return null on fetch error', async () => {
    mockPayload.find.mockResolvedValue({ docs: [], totalDocs: 0 })
    mockFetch.mockRejectedValue(new Error('Network error'))

    const result = await downloadAndUploadImage(mockPayload as any, {
      url: 'https://img.youtube.com/vi/bad/hqdefault.jpg',
      filename: 'bad_thumbnail.jpg',
    })

    expect(result).toBeNull()
  })

  it('should return null on non-ok response', async () => {
    mockPayload.find.mockResolvedValue({ docs: [], totalDocs: 0 })
    mockFetch.mockResolvedValue({ ok: false, status: 404 })

    const result = await downloadAndUploadImage(mockPayload as any, {
      url: 'https://img.youtube.com/vi/notfound/hqdefault.jpg',
      filename: 'notfound_thumbnail.jpg',
    })

    expect(result).toBeNull()
  })
})

Step 2: Run test to verify it fails

Run: pnpm vitest run tests/unit/media-download.test.ts Expected: FAIL — module ../../src/lib/utils/media-download not found

Step 3: Write the implementation

// src/lib/utils/media-download.ts
import type { Payload } from 'payload'

interface DownloadOptions {
  url: string
  filename: string
  alt?: string
  tenantId?: number
}

/**
 * Downloads an image from a URL and creates a Payload Media document.
 *
 * - Checks for existing media with same filename first (deduplication)
 * - Returns the Media document ID on success, null on failure
 * - Never throws — errors are logged and null is returned
 */
export async function downloadAndUploadImage(
  payload: Payload,
  options: DownloadOptions
): Promise<number | null> {
  const { url, filename, alt, tenantId } = options

  try {
    // Check for existing media with same filename
    const existing = await payload.find({
      collection: 'media',
      where: {
        filename: { equals: filename },
        ...(tenantId ? { tenant: { equals: tenantId } } : {}),
      },
      limit: 1,
      depth: 0,
    })

    if (existing.docs[0]) {
      return existing.docs[0].id as number
    }

    // Download the image with timeout
    const controller = new AbortController()
    const timeout = setTimeout(() => controller.abort(), 10_000)

    const response = await fetch(url, { signal: controller.signal })
    clearTimeout(timeout)

    if (!response.ok) {
      console.log(`[media-download] HTTP ${response.status} for ${url}`)
      return null
    }

    const arrayBuffer = await response.arrayBuffer()
    const buffer = Buffer.from(arrayBuffer)
    const contentType = response.headers.get('content-type') || 'image/jpeg'

    // Create Payload Media document
    const media = await payload.create({
      collection: 'media',
      data: {
        alt: alt || filename.replace(/[-_]/g, ' ').replace(/\.\w+$/, ''),
        ...(tenantId ? { tenant: tenantId } : {}),
      },
      file: {
        name: filename,
        data: buffer,
        mimetype: contentType,
        size: buffer.length,
      },
    })

    console.log(`[media-download] Created media ${media.id} from ${url}`)
    return media.id as number
  } catch (error) {
    console.log(`[media-download] Failed to download ${url}:`, (error as Error).message)
    return null
  }
}

Step 4: Run test to verify it passes

Run: pnpm vitest run tests/unit/media-download.test.ts Expected: All 4 tests PASS

Step 5: Commit

git add src/lib/utils/media-download.ts tests/unit/media-download.test.ts
git commit -m "feat: add downloadAndUploadImage utility for YouTube thumbnails"

---

Task 2: Add afterChange hook to YouTubeContent for auto-download

Files:

• Create: src/hooks/youtubeContent/downloadThumbnail.ts
• Modify: src/collections/YouTubeContent.ts:40-41 — add hook to afterChange array

Step 1: Write the hook

// src/hooks/youtubeContent/downloadThumbnail.ts
import type { CollectionAfterChangeHook } from 'payload'
import { downloadAndUploadImage } from '../../lib/utils/media-download'
import { getYouTubeThumbnail } from '../../lib/utils/youtube'

/**
 * After a YouTubeContent document is created or updated,
 * automatically download the YouTube thumbnail if the thumbnail field is empty
 * and a YouTube videoId is present.
 */
export const downloadThumbnail: CollectionAfterChangeHook = async ({
  doc,
  req,
  operation,
}) => {
  // Skip if thumbnail already exists (manual upload or previous download)
  if (doc.thumbnail) return doc

  // Get the YouTube video ID
  const videoId = doc.youtube?.videoId
  if (!videoId) return doc

  const thumbnailUrl = getYouTubeThumbnail(videoId, 'hq')
  const filename = `yt-thumb-${videoId}.jpg`

  // Determine tenant from doc or channel
  const tenantId = typeof doc.tenant === 'object' ? doc.tenant?.id : doc.tenant

  const mediaId = await downloadAndUploadImage(req.payload, {
    url: thumbnailUrl,
    filename,
    alt: doc.title ? `Thumbnail: ${typeof doc.title === 'string' ? doc.title : doc.title?.de || doc.title?.en || videoId}` : `YouTube Thumbnail ${videoId}`,
    tenantId: tenantId || undefined,
  })

  if (mediaId) {
    // Update the document with the downloaded thumbnail
    // Use depth: 0 to avoid triggering this hook recursively
    await req.payload.update({
      collection: 'youtube-content',
      id: doc.id,
      data: { thumbnail: mediaId },
      depth: 0,
    })
    console.log(`[yt-thumbnail] Auto-downloaded thumbnail for video ${videoId} (media: ${mediaId})`)
  }

  return doc
}

Step 2: Register the hook in YouTubeContent collection

In src/collections/YouTubeContent.ts, add the import at the top:

import { downloadThumbnail } from '../hooks/youtubeContent/downloadThumbnail'

Then modify the hooks section (line ~40):

hooks: {
    afterChange: [createTasksOnStatusChange, downloadThumbnail],
    // ... rest unchanged
},

Step 3: Verify the build compiles

Run: pnpm tsc --noEmit 2>&1 | head -20 Expected: No new type errors from these files

Step 4: Commit

git add src/hooks/youtubeContent/downloadThumbnail.ts src/collections/YouTubeContent.ts
git commit -m "feat: auto-download YouTube thumbnails on content create/update"

---

Task 3: Add afterChange hook to YouTubeChannels for channel images

Files:

• Create: src/hooks/youtubeChannels/downloadChannelImage.ts
• Modify: src/collections/YouTubeChannels.ts — add hook

Step 1: Check current YouTubeChannels hooks

Read: src/collections/YouTubeChannels.ts — find the hooks section and the field for channel profile image URL from YouTube API.

The YouTube Data API returns channel thumbnail URLs in snippet.thumbnails. We need to find if/where this data is stored in the collection (likely youtube.thumbnailUrl or similar field that holds the raw API URL).

Step 2: Write the hook

// src/hooks/youtubeChannels/downloadChannelImage.ts
import type { CollectionAfterChangeHook } from 'payload'
import { downloadAndUploadImage } from '../../lib/utils/media-download'

/**
 * After a YouTubeChannels document is created or updated,
 * automatically download the channel profile image if the branding.logo field is empty
 * and a YouTube channel thumbnail URL is available.
 */
export const downloadChannelImage: CollectionAfterChangeHook = async ({
  doc,
  req,
}) => {
  // Skip if logo already exists
  if (doc.branding?.logo) return doc

  // YouTube channels store their profile image URL — check for it
  // The URL typically comes from YouTube API: snippet.thumbnails.high.url
  const channelId = doc.youtubeChannelId
  if (!channelId) return doc

  // YouTube channel profile images follow this pattern:
  // https://yt3.ggpht.com/CHANNEL_IMAGE_PATH
  // We need the URL to be stored somewhere — check channelThumbnailUrl or similar
  const thumbnailUrl = doc.channelThumbnailUrl || doc.youtube?.thumbnailUrl
  if (!thumbnailUrl) return doc

  const filename = `yt-channel-${channelId}.jpg`
  const tenantId = typeof doc.tenant === 'object' ? doc.tenant?.id : doc.tenant

  const mediaId = await downloadAndUploadImage(req.payload, {
    url: thumbnailUrl,
    filename,
    alt: doc.name ? `Kanal: ${doc.name}` : `YouTube Channel ${channelId}`,
    tenantId: tenantId || undefined,
  })

  if (mediaId) {
    await req.payload.update({
      collection: 'youtube-channels',
      id: doc.id,
      data: { branding: { ...doc.branding, logo: mediaId } },
      depth: 0,
    })
    console.log(`[yt-thumbnail] Auto-downloaded channel image for ${channelId} (media: ${mediaId})`)
  }

  return doc
}

Step 3: Register the hook

Import and add to YouTubeChannels.ts hooks section.

Step 4: Verify build compiles

Run: pnpm tsc --noEmit 2>&1 | head -20

Step 5: Commit

git add src/hooks/youtubeChannels/downloadChannelImage.ts src/collections/YouTubeChannels.ts
git commit -m "feat: auto-download YouTube channel images on create/update"

---

Task 4: Create bulk-import endpoint

Files:

• Create: src/app/(payload)/api/youtube/thumbnails/bulk/route.ts

Step 1: Write the endpoint

// src/app/(payload)/api/youtube/thumbnails/bulk/route.ts
import { NextResponse, type NextRequest } from 'next/server'
import { getPayload } from 'payload'
import config from '@payload-config'
import { downloadAndUploadImage } from '@/lib/utils/media-download'
import { getYouTubeThumbnail } from '@/lib/utils/youtube'

export async function POST(req: NextRequest) {
  const payload = await getPayload({ config })

  // Auth check — require super admin
  const { user } = await payload.auth({ headers: req.headers })
  if (!user?.isSuperAdmin) {
    return NextResponse.json({ error: 'Super-Admin erforderlich' }, { status: 403 })
  }

  const dryRun = req.nextUrl.searchParams.get('dryRun') === 'true'

  // Find all YouTubeContent without thumbnail that have a videoId
  const contentWithoutThumbnail = await payload.find({
    collection: 'youtube-content',
    where: {
      thumbnail: { exists: false },
      'youtube.videoId': { exists: true },
    },
    limit: 500,
    depth: 0,
  })

  const results = { processed: 0, downloaded: 0, skipped: 0, errors: 0, dryRun }

  for (const doc of contentWithoutThumbnail.docs) {
    results.processed++
    const videoId = doc.youtube?.videoId
    if (!videoId) {
      results.skipped++
      continue
    }

    if (dryRun) {
      results.downloaded++
      continue
    }

    try {
      const thumbnailUrl = getYouTubeThumbnail(videoId, 'hq')
      const filename = `yt-thumb-${videoId}.jpg`
      const tenantId = typeof doc.tenant === 'object' ? doc.tenant?.id : doc.tenant

      const mediaId = await downloadAndUploadImage(payload, {
        url: thumbnailUrl,
        filename,
        alt: `Thumbnail: ${typeof doc.title === 'string' ? doc.title : doc.title?.de || videoId}`,
        tenantId: tenantId || undefined,
      })

      if (mediaId) {
        await payload.update({
          collection: 'youtube-content',
          id: doc.id,
          data: { thumbnail: mediaId },
          depth: 0,
        })
        results.downloaded++
      } else {
        results.errors++
      }
    } catch {
      results.errors++
    }

    // Rate-limit delay (500ms between downloads)
    await new Promise((resolve) => setTimeout(resolve, 500))
  }

  return NextResponse.json(results)
}

Step 2: Test endpoint manually

# Dry run first
curl -X POST "https://pl.porwoll.tech/api/youtube/thumbnails/bulk?dryRun=true" \
  -H "Cookie: payload-token=..."

# Actual run
curl -X POST "https://pl.porwoll.tech/api/youtube/thumbnails/bulk" \
  -H "Cookie: payload-token=..."

Step 3: Commit

git add "src/app/(payload)/api/youtube/thumbnails/bulk/route.ts"
git commit -m "feat: add bulk YouTube thumbnail download endpoint"

---

Task 5: Update documentation

Files:

• Modify: CLAUDE.md — add thumbnail API endpoint to URLs section
• Modify: docs/PROJECT_STATUS.md — mark YouTube thumbnails as completed

Step 1: Add to CLAUDE.md URLs section

Add after the Meta OAuth line:

- **YouTube Thumbnail Bulk:** https://pl.porwoll.tech/api/youtube/thumbnails/bulk (POST, Super-Admin)

Step 2: Update PROJECT_STATUS.md

• Mark "YouTube Thumbnail-Download für Offline-Anzeige" as ✅ Erledigt
• Add changelog entry for 14.02.2026

Step 3: Commit

git add CLAUDE.md docs/PROJECT_STATUS.md
git commit -m "docs: add YouTube thumbnail download to documentation"

---

Task 6: Final verification

Step 1: Run full test suite

Run: pnpm vitest run Expected: All tests pass, including new media-download tests

Step 2: Type-check

Run: pnpm tsc --noEmit Expected: No errors

Step 3: Lint

Run: pnpm lint Expected: No new errors

Step 4: Push to develop

git push origin develop