Add YouTube video duration filtering with --duration option (#20)

Co-authored-by: Marc Anguera Insa <srmarc.ai@gmail.com>

Author: Copilot

README.md

@@ -19,6 +19,8 @@ The CLI allows you to search videos without leaving the terminal:
 
     > suchtube funny cats
     > suchtube football top goals --random --open
+    > suchtube trending videos --duration=short
+    > suchtube documentary --duration=long --random
 
 Or start the server:
 
@@ -55,19 +57,23 @@ The server listens by default on port 3333, if you want to change this, you can
 
 Options while using the CLI are available in the following formats: `--time=10` or `--time 10`. For the server, you should pass the options along with the query, inside the `q` paramater, ie: `?q=funny+cats+--time=10`.
 
-- `--time=10`, `-t=10`
+#### `--time=10`, `-t=10`
 
 Starts the video at the given time in seconds.
 
-- `--random`, `-r`
+#### `--random`, `-r`
 
 Returns a random video taking into account the given topic.
 
-- `--open`, `-o` *(CLI only)*
+#### `--duration=short`, `-d=short`
+
+Filters videos by duration. Available values: `any` (default), `short`, `medium`, `long`. Uses YouTube's videoDuration parameter to filter results directly from the API.
+
+#### `--open`, `-o` *(CLI only)*
 
 Opens the video in your browser.
 
-- `--full`, `-f` *(CLI only)*
+#### `--full`, `-f` *(CLI only)*
 
 Displays full video's information. It corresponds to hit `GET /search.json?q=` against the server.
 
@@ -78,7 +84,7 @@ You can use the SuchTube search as a library:
 ```js
 import { search } from 'suchtube'
 
-search('funny cats', { random: true }).then(video => {
+search('funny cats', { random: true, duration: 'short' }).then(video => {
   console.log(video.title)
   console.log(video.link)
   console.log(video.publishedAt)

src/cli.js

@@ -10,6 +10,7 @@ const yargsInstance = yargs(hideBin(process.argv))
   .example('suchtube funny cats')
   .example('suchtube football top goals --open')
   .example('suchtube top summer songs --random')
+  .example('suchtube trending videos --duration=short')
   .example('suchtube --server')
   .alias('version', 'v')
   .alias('help', 'h')
@@ -25,6 +26,11 @@ const yargsInstance = yargs(hideBin(process.argv))
     description: 'Open the video in your browser',
     alias: 'o'
   })
+  .option('duration', {
+    description: 'Filter videos by duration',
+    alias: 'd',
+    choices: ['any', 'short', 'medium', 'long']
+  })
   .option('full', {
     description: 'Display full information',
     alias: 'f'

src/search.js

@@ -8,6 +8,11 @@ const youtubeAPI = async (query, options) => {
     part: 'snippet'
   }
 
+  if (options.duration && options.duration !== 'any') {
+    params.videoDuration = options.duration
+    params.type = 'video'
+  }
+
   if (!params.key || params.key == "") {
     console.error('Whoops! You should setup your YouTube Data API key')
   }