headless-youtube-captions 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.3.0] - 2025-01-24
+
+### Added
+- **NEW**: `searchYouTubeGlobal()` function for searching across all of YouTube
+  - Search for videos and channels globally using any search term
+  - Configurable result types: videos, channels, or both
+  - Adjustable result limits (1-20 results)
+  - Returns structured data with video metadata (title, channel, views, duration, etc.)
+  - Returns structured data with channel metadata (title, subscribers, video count, etc.)
+  - Uses validated DOM selectors for reliable extraction
+  - Consistent API design matching existing functions
+
+### Technical Details
+- Added `src/search.js` with comprehensive YouTube search automation
+- Updated TypeScript definitions with new search interfaces
+- Enhanced exports in main index file
+- Maintains existing browser management and error handling patterns
+
 ## [1.2.0] - 2025-07-06
 
 ### Added

package/README.md

@@ -11,6 +11,7 @@
 - 🎯 Extract video transcripts/captions in multiple languages
 - 📺 Get channel videos with pagination support
 - 🔍 Search videos within a specific channel
+- 🌍 **NEW**: Search across all of YouTube globally
 - 💬 Extract video comments with sorting options
 - 🐳 Docker support with configurable Chrome executable path
 - 📦 Zero build dependencies - runs directly from source
@@ -64,6 +65,19 @@ const result = await searchChannelVideos({
 console.log(result.results);
 ```
 
+### Search YouTube Globally
+```js
+import { searchYouTubeGlobal } from 'headless-youtube-captions';
+
+const result = await searchYouTubeGlobal({
+  query: 'javascript tutorial',
+  maxResults: 10,         // Optional, 1-20, default: 10
+  resultTypes: ['videos'] // Optional, ['videos', 'channels', 'all'], default: ['all']
+});
+
+console.log(result.results);
+```
+
 ### Get Video Comments
 ```js
 import { getVideoComments } from 'headless-youtube-captions';
@@ -332,6 +346,56 @@ Extract comments from a YouTube video with pagination support.
 }
 ```
 
+### `searchYouTubeGlobal(options)`
+
+Search across all of YouTube for videos and channels.
+
+#### Parameters
+
+- `options` (Object):
+  - `query` (String, required): Search term to find content
+  - `maxResults` (Number, optional): Maximum results to return (1-20). Default: `10`
+  - `resultTypes` (Array, optional): Types of results to include. Options: `['videos']`, `['channels']`, `['all']`. Default: `['all']`
+
+#### Returns
+
+```js
+{
+  query: "javascript tutorial",
+  resultTypes: ["videos"],
+  maxResults: 10,
+  totalFound: 8,
+  results: [
+    {
+      id: "videoId123",
+      type: "video",
+      title: "JavaScript Tutorial for Beginners",
+      url: "https://youtube.com/watch?v=videoId123",
+      channel: "Code Academy",
+      views: "2.1M views",
+      uploadTime: "1 year ago",
+      duration: "1:23:45",
+      thumbnail: "https://i.ytimg.com/vi/..."
+    },
+    {
+      id: "channelId456", 
+      type: "channel",
+      title: "JavaScript Mastery",
+      url: "https://youtube.com/@javascriptmastery",
+      subscribers: "1.2M subscribers",
+      videoCount: "200 videos",
+      thumbnail: "https://yt3.ggpht.com/..."
+    }
+    // ... more results
+  ]
+}
+```
+
+#### Result Types
+
+- **Video Results** include: `id`, `type`, `title`, `url`, `channel`, `views`, `uploadTime`, `duration`, `thumbnail`
+- **Channel Results** include: `id`, `type`, `title`, `url`, `subscribers`, `videoCount`, `thumbnail`
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "headless-youtube-captions",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Extract YouTube video transcripts, channel videos, and comments using headless browser automation",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -32,6 +32,7 @@
   "devDependencies": {},
   "keywords": [
     "youtube",
+    "search",
     "captions",
     "subtitles",
     "transcript",
@@ -41,6 +42,8 @@
     "puppeteer",
     "headless",
     "scraper",
-    "api"
+    "api",
+    "automation",
+    "global-search"
   ]
 }

package/src/index.d.ts

@@ -163,4 +163,59 @@ export interface VideoCommentsResult {
  * @param options - Configuration options
  * @returns Promise that resolves to video comments result
  */
-export function getVideoComments(options: GetVideoCommentsOptions): Promise<VideoCommentsResult>;
+export function getVideoComments(options: GetVideoCommentsOptions): Promise<VideoCommentsResult>;
+
+// Types for global YouTube search
+export interface SearchResult {
+  /** Result ID (video ID or channel ID) */
+  id: string;
+  /** Result type */
+  type: 'video' | 'channel';
+  /** Title of the video or channel */
+  title: string;
+  /** Full YouTube URL */
+  url: string;
+  /** Thumbnail URL */
+  thumbnail: string;
+  /** Channel name (for videos) */
+  channel?: string;
+  /** View count (for videos) */
+  views?: string;
+  /** Upload time (for videos) */
+  uploadTime?: string;
+  /** Duration (for videos) */
+  duration?: string;
+  /** Subscriber count (for channels) */
+  subscribers?: string;
+  /** Video count (for channels) */
+  videoCount?: string;
+}
+
+export interface SearchYouTubeGlobalOptions {
+  /** Search query */
+  query: string;
+  /** Maximum number of results to return (1-20, default: 10) */
+  maxResults?: number;
+  /** Types of results to include (default: ['all']) */
+  resultTypes?: ('videos' | 'channels' | 'all')[];
+}
+
+export interface SearchYouTubeGlobalResult {
+  /** Search query used */
+  query: string;
+  /** Result types requested */
+  resultTypes: ('videos' | 'channels' | 'all')[];
+  /** Maximum results requested */
+  maxResults: number;
+  /** Total results found */
+  totalFound: number;
+  /** Array of search results */
+  results: SearchResult[];
+}
+
+/**
+ * Search across all of YouTube for videos and channels
+ * @param options - Configuration options
+ * @returns Promise that resolves to global search results
+ */
+export function searchYouTubeGlobal(options: SearchYouTubeGlobalOptions): Promise<SearchYouTubeGlobalResult>;

package/src/index.js

@@ -258,4 +258,5 @@ export async function getSubtitles({ videoID, lang = 'en' }) {
 
 // Export new functions
 export { getChannelVideos, searchChannelVideos } from './channel.js';
-export { getVideoComments } from './comments.js';
+export { getVideoComments } from './comments.js';
+export { searchYouTubeGlobal } from './search.js';

package/src/search.js

@@ -0,0 +1,171 @@
+import { createBrowser, createPage, handleCookieConsent } from './utils/browser.js';
+
+/**
+ * Search across all of YouTube for videos and channels
+ * @param {Object} options - Search options
+ * @param {string} options.query - Search term
+ * @param {number} [options.maxResults=10] - Maximum number of results (1-20)
+ * @param {string[]} [options.resultTypes=['all']] - Types of results to include ('videos', 'channels', 'all')
+ * @returns {Promise<Object>} Search results with videos and channels
+ */
+export async function searchYouTubeGlobal({ query, maxResults = 10, resultTypes = ['all'] }) {
+  // Validate inputs
+  if (!query || !query.trim()) {
+    throw new Error('Search query cannot be empty');
+  }
+
+  if (maxResults < 1 || maxResults > 20) {
+    throw new Error('maxResults must be between 1 and 20');
+  }
+
+  const browser = await createBrowser();
+
+  try {
+    const page = await createPage(browser);
+    
+    // Navigate to YouTube search results
+    const searchUrl = `https://www.youtube.com/results?search_query=${encodeURIComponent(query.trim())}`;
+    console.error(`Navigating to ${searchUrl}`);
+    
+    await page.goto(searchUrl, {
+      waitUntil: 'networkidle2',
+      timeout: 60000
+    });
+
+    // Handle cookie consent
+    await handleCookieConsent(page);
+    
+    // Wait for search results to load
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    await page.waitForSelector('#contents', { timeout: 30000 });
+    console.error('Search results page loaded');
+
+    // Extract search results using validated selectors from discovery work
+    const searchResults = await page.evaluate((maxResults, resultTypes) => {
+      const results = [];
+      
+      // Use validated selectors from BMAD discovery work
+      const videoElements = document.querySelectorAll('#contents ytd-video-renderer');
+      const channelElements = document.querySelectorAll('#contents ytd-channel-renderer');
+      
+      // Extract video results
+      if (resultTypes.includes('all') || resultTypes.includes('videos')) {
+        Array.from(videoElements).forEach((element, index) => {
+          if (results.length >= maxResults) return;
+          
+          try {
+            // Use validated selectors: h3 a for video titles
+            const titleElement = element.querySelector('h3 a');
+            const title = titleElement ? titleElement.textContent.trim() : '';
+            const url = titleElement ? titleElement.href : '';
+            
+            // Extract video ID from URL
+            const videoId = url.match(/watch\?v=([^&]+)/)?.[1] || '';
+            
+            // Channel name using validated selector
+            const channelElement = element.querySelector('#text a[href*="/channel/"], #text a[href*="/@"]');
+            const channel = channelElement ? channelElement.textContent.trim() : '';
+            
+            // Metadata extraction
+            const metadataElement = element.querySelector('#metadata-line');
+            let views = '';
+            let uploadTime = '';
+            
+            if (metadataElement) {
+              const spans = metadataElement.querySelectorAll('span');
+              if (spans.length >= 2) {
+                views = spans[0].textContent.trim();
+                uploadTime = spans[1].textContent.trim();
+              }
+            }
+            
+            // Duration
+            const durationElement = element.querySelector('ytd-thumbnail-overlay-time-status-renderer span');
+            const duration = durationElement ? durationElement.textContent.trim() : '';
+            
+            // Thumbnail
+            const thumbnailElement = element.querySelector('img');
+            const thumbnail = thumbnailElement ? thumbnailElement.src : '';
+            
+            if (title && url && videoId) {
+              results.push({
+                id: videoId,
+                type: 'video',
+                title: title,
+                url: url,
+                channel: channel,
+                views: views,
+                uploadTime: uploadTime,
+                duration: duration,
+                thumbnail: thumbnail
+              });
+            }
+          } catch (e) {
+            console.error('Error extracting video result:', e);
+          }
+        });
+      }
+      
+      // Extract channel results
+      if (resultTypes.includes('all') || resultTypes.includes('channels')) {
+        Array.from(channelElements).forEach((element, index) => {
+          if (results.length >= maxResults) return;
+          
+          try {
+            // Channel title and URL
+            const titleElement = element.querySelector('#text a');
+            const title = titleElement ? titleElement.textContent.trim() : '';
+            const url = titleElement ? titleElement.href : '';
+            
+            // Extract channel ID from URL
+            const channelId = url.match(/channel\/([^/]+)/)?.[1] || url.match(/@([^/]+)/)?.[1] || '';
+            
+            // Subscriber count
+            const subsElement = element.querySelector('#subscribers');
+            const subscribers = subsElement ? subsElement.textContent.trim() : '';
+            
+            // Video count
+            const videoCountElement = element.querySelector('#video-count');
+            const videoCount = videoCountElement ? videoCountElement.textContent.trim() : '';
+            
+            // Thumbnail
+            const thumbnailElement = element.querySelector('img');
+            const thumbnail = thumbnailElement ? thumbnailElement.src : '';
+            
+            if (title && url && channelId) {
+              results.push({
+                id: channelId,
+                type: 'channel',
+                title: title,
+                url: url,
+                subscribers: subscribers,
+                videoCount: videoCount,
+                thumbnail: thumbnail
+              });
+            }
+          } catch (e) {
+            console.error('Error extracting channel result:', e);
+          }
+        });
+      }
+      
+      return results;
+    }, maxResults, resultTypes);
+
+    console.error(`Successfully extracted ${searchResults.length} search results`);
+    
+    return {
+      query: query.trim(),
+      resultTypes: resultTypes,
+      maxResults: maxResults,
+      totalFound: searchResults.length,
+      results: searchResults
+    };
+
+  } catch (error) {
+    console.error('Error performing YouTube search:', error);
+    throw error;
+  } finally {
+    await browser.close();
+  }
+}