YouTube API Integration

async function getPlaylist(
  playlistId: string,
  maxResults = 50,
  part = "contentDetails,snippet,status"
): Promise<YouTubePlaylistItemResponse | null>

interface YouTubePlaylistItemResponse {
  kind: "youtube#playlistItemListResponse";  // Resource type
  etag: string;                               // ETag for caching
  items: PlaylistItem[];                      // Array of playlist items
  pageInfo: PageInfo;                         // Pagination metadata
  // nextPageToken?: string;                  // Token for next page (if applicable)
}

interface PlaylistItem {
  kind: "youtube#playlistItem";    // Resource type
  etag: string;                    // ETag for caching
  id: string;                      // Playlist item ID
  snippet: Snippet;                // Video metadata
  contentDetails: ContentDetails;  // Video ID and publish date
  status: Status;                  // Privacy status
}

interface Snippet {
  publishedAt: string;             // ISO 8601 timestamp
  channelId: string;               // Channel ID
  title: string;                   // Video title
  description: string;             // Video description
  thumbnails: Thumbnails;          // Thumbnail images (multiple sizes)
  channelTitle: string;            // Channel name
  playlistId: string;              // Parent playlist ID
  position: number;                // Position in playlist (0-indexed)
  resourceId: ResourceId;          // Video resource identifier
  videoOwnerChannelTitle: string;  // Video uploader channel name
  videoOwnerChannelId: string;     // Video uploader channel ID
}

interface ContentDetails {
  videoId: string;                 // YouTube video ID
  videoPublishedAt: string;        // ISO 8601 timestamp
}

interface Status {
  privacyStatus: "public" | "unlisted" | "private";  // Video visibility
}

interface PageInfo {
  totalResults: number;            // Total items in playlist
  resultsPerPage: number;          // Items returned in this response
}

interface Thumbnails {
  default: Thumbnail;              // 120x90px
  medium: Thumbnail;               // 320x180px
  high: Thumbnail;                 // 480x360px
  standard: Thumbnail;             // 640x480px
  maxres: Thumbnail;               // 1280x720px (if available)
}

interface Thumbnail {
  url: string;                     // Image URL
  width: number;                   // Image width in pixels
  height: number;                  // Image height in pixels
}

interface ResourceId {
  kind: "youtube#video";           // Resource type
  videoId: string;                 // YouTube video ID
}

GET https://www.googleapis.com/youtube/v3/playlistItems
  ?playlistId={playlistId}
  &maxResults={maxResults}
  &part={part}
  &key={apiKey}

import { getPlaylist } from '@/server/services/youtube/playlist';

// Basic usage - get first 50 items with default parts
const playlist = await getPlaylist('PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf');

if (playlist) {
  console.log(`Total videos: ${playlist.pageInfo.totalResults}`);
  console.log(`Returned: ${playlist.items.length}`);
  
  playlist.items.forEach((item, index) => {
    console.log(`${index + 1}. ${item.snippet.title}`);
    console.log(`   Video ID: ${item.contentDetails.videoId}`);
    console.log(`   Channel: ${item.snippet.channelTitle}`);
    console.log(`   Privacy: ${item.status.privacyStatus}`);
    console.log(`   Thumbnail: ${item.snippet.thumbnails.high.url}`);
  });
}

// Custom maxResults
const shortPlaylist = await getPlaylist('PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf', 10);

// Request only specific parts to save quota
const minimalPlaylist = await getPlaylist(
  'PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf',
  50,
  'contentDetails'
);

// Access thumbnail variations
if (playlist && playlist.items.length > 0) {
  const firstVideo = playlist.items[0];
  const thumbs = firstVideo.snippet.thumbnails;
  
  console.log('Available thumbnails:');
  console.log(`Default (120x90): ${thumbs.default.url}`);
  console.log(`Medium (320x180): ${thumbs.medium.url}`);
  console.log(`High (480x360): ${thumbs.high.url}`);
  console.log(`Standard (640x480): ${thumbs.standard.url}`);
  if (thumbs.maxres) {
    console.log(`Max Res (1280x720): ${thumbs.maxres.url}`);
  }
}

const playlist = await getPlaylist('PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf');

if (playlist) {
  playlist.items.forEach(item => {
    const videoId = item.contentDetails.videoId;
    const videoUrl = `https://www.youtube.com/watch?v=${videoId}`;
    const embedUrl = `https://www.youtube.com/embed/${videoId}`;
    
    console.log(`Watch: ${videoUrl}`);
    console.log(`Embed: ${embedUrl}`);
  });
}

// Different cache keys for different queries
getPlaylist('PLabcd', 50, 'snippet,contentDetails');
// Cache key: "youtube_playlist_PLabcd_maxresults50_partsnippet,contentDetails"

getPlaylist('PLabcd', 10, 'snippet,contentDetails');
// Cache key: "youtube_playlist_PLabcd_maxresults10_partsnippet,contentDetails"

getPlaylist('PLabcd', 50, 'snippet');
// Cache key: "youtube_playlist_PLabcd_maxresults50_partsnippet"

const playlist = await getPlaylist('invalid_playlist_id');
if (!playlist) {
  console.error('Failed to retrieve playlist');
  // Check server logs for detailed error message:
  // "Error al obtener la playlist de YouTube {playlistId}"
}

// Default: part="contentDetails,snippet,status"
// Cost: 1 (base) + 2 (contentDetails) + 2 (snippet) + 2 (status) = 7 units
await getPlaylist('PLabc');

// Minimal: part="contentDetails"
// Cost: 1 (base) + 2 (contentDetails) = 3 units
await getPlaylist('PLabc', 50, 'contentDetails');

// With caching, subsequent calls = 0 units (within 1 hour)
await getPlaylist('PLabc');  // 7 units (first call)
await getPlaylist('PLabc');  // 0 units (from cache)

// Future enhancement for pagination support
async function getAllPlaylistItems(playlistId: string) {
  let allItems: PlaylistItem[] = [];
  let nextPageToken: string | undefined;
  
  do {
    const response = await getPlaylist(playlistId, 50);
    if (!response) break;
    
    allItems = allItems.concat(response.items);
    nextPageToken = response.nextPageToken;  // Currently not returned
    
    // Would need to pass nextPageToken to getPlaylist()
  } while (nextPageToken);
  
  return allItems;
}