@x12i/youtube-video-uploader-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# @x12i/youtube-video-uploader-cli 📺
+
+> Automated batch video uploader for YouTube Data API v3 with OAuth2 authentication, playlist assignment, quota estimation, and smart upload-state resume.
+
+---
+
+## 🚀 Features
+
+- **🔐 Interactive OAuth2 Authentication**: Authenticates with YouTube using Google OAuth2. Features a local loopback server to automatically capture the callback redirect, with a terminal prompt fallback.
+- **💾 Token Persistence**: Caches tokens locally in `token.json` so you only need to authorize once. Automatically handles token refresh.
+- **📄 Metadata-Driven Batch Uploads**: Configure titles, descriptions, tags, category, privacy, and playlist via a simple `metadata.json` file.
+- **⚡ Smart Skip & Resume**: Saves upload status to `.upload-history.json` and skips previously uploaded files on rerun to protect your API quota.
+- **📑 Playlist Integration**: Automatically adds uploaded videos to a specified YouTube Playlist (`playlistId`).
+- **📊 Quota Estimation**: Calculates estimated YouTube Data API units (1,600 units/video, 50 units/playlist addition) and warns if approaching the standard 10,000 units/day limit.
+- **🔍 Dry Run Mode**: Validate your `metadata.json`, inspect files, and check estimated quota before uploading.
+
+---
+
+## 🔑 Google Cloud Setup (Prerequisite)
+
+Before using the uploader, you need OAuth2 credentials from Google Cloud:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project and enable the **YouTube Data API v3**.
+3. Under **OAuth consent screen**:
+   - Set user type to **External**.
+   - Add your Google account email under **Test Users**.
+4. Under **APIs & Services > Credentials**:
+   - Click **Create Credentials > OAuth client ID**.
+   - Application type: **Desktop App** (or Web Application with redirect URI `http://localhost:3000/oauth2callback`).
+   - Download the `client_secret.json` or copy your `Client ID` and `Client Secret`.
+
+---
+
+## 📦 Installation & Quick Start
+
+### Run immediately via `npx`
+
+```bash
+# In the folder containing your .mp4 files and metadata.json:
+npx @x12i/youtube-video-uploader-cli
+```
+
+### Install globally
+
+```bash
+npm install -g @x12i/youtube-video-uploader-cli
+
+# Now you can use any of these commands anywhere:
+youtube-video-uploader [folder]
+yt-uploader [folder]
+yvu-cli [folder]
+```
+
+---
+
+## 📂 Folder Structure & `metadata.json`
+
+Place your videos and a `metadata.json` file in your target folder:
+
+```text
+my-videos/
+├── metadata.json
+├── track1.mp4
+├── track2.mp4
+└── track3.mp4
+```
+
+### `metadata.json` Schema
+
+```json
+{
+  "playlistId": "PLxXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+  "privacyStatus": "private",
+  "categoryId": "10",
+  "videos": [
+    {
+      "filename": "track1.mp4",
+      "title": "Ambient Track 01 - Chill Beats",
+      "description": "Full track audio with custom artwork.\n\nSubscribe for more!",
+      "tags": ["ambient", "lofi", "chill"]
+    },
+    {
+      "filename": "track2.mp4",
+      "title": "Ambient Track 02 - Night Drives",
+      "description": "Relaxing night vibes.",
+      "tags": ["night", "vibes"]
+    }
+  ]
+}
+```
+
+#### Category IDs:
+- `"10"` = Music (default)
+- `"22"` = People & Blogs
+- `"27"` = Education
+- `"28"` = Science & Technology
+
+---
+
+## ⚙️ CLI Options Reference
+
+```text
+Usage: youtube-video-uploader [directory] [options]
+
+Arguments:
+  directory                     Target folder containing MP4 videos and metadata.json (default: ".")
+
+Options:
+  -v, --version                 Output current version
+  -d, --dir <path>              Explicit target directory path
+  -m, --metadata <file>         Custom path to metadata.json file
+  -f, --force                   Force re-upload of already uploaded videos (default: false)
+  -n, --dry-run                 Preview video uploads and estimate quota without uploading (default: false)
+  --client-id <id>              Google OAuth Client ID
+  --client-secret <secret>      Google OAuth Client Secret
+  --client-secrets-file <file>  Path to client_secret.json downloaded from Google Cloud
+  --token-file <file>           Path to store or read OAuth token (default: token.json in target dir)
+  -q, --quiet                   Minimal output mode (default: false)
+  -h, --help                    Display help
+```
+
+---
+
+## 💡 Examples
+
+### 1. Dry run (verify metadata and estimate API quota)
+```bash
+npx @x12i/youtube-video-uploader-cli ./my-videos --dry-run
+```
+
+### 2. Upload with credentials from environment variables
+```bash
+export YOUTUBE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+export YOUTUBE_CLIENT_SECRET="your-client-secret"
+
+npx @x12i/youtube-video-uploader-cli ./my-videos
+```
+
+### 3. Upload with downloaded `client_secret.json`
+```bash
+npx @x12i/youtube-video-uploader-cli ./my-videos --client-secrets-file ./client_secret.json
+```
+
+---
+
+## 🛠️ Programmatic Node.js API
+
+```javascript
+import { batchUpload, uploadVideo, loadMetadata } from '@x12i/youtube-video-uploader-cli';
+
+const result = await batchUpload('./my-videos', {
+  clientId: process.env.YOUTUBE_CLIENT_ID,
+  clientSecret: process.env.YOUTUBE_CLIENT_SECRET,
+  onEvent: (event) => {
+    if (event.type === 'upload_success') {
+      console.log(`Uploaded ${event.item.filename} -> ${event.record.url}`);
+    }
+  },
+});
+
+console.log(`Uploaded: ${result.uploaded.length}, Skipped: ${result.skipped.length}`);
+```
+
+---
+
+## 📜 License
+
+MIT License.

package/bin/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import path from 'node:path';
+import fs from 'node:fs';
+import pc from 'picocolors';
+import { batchUpload, DAILY_DEFAULT_QUOTA } from '../src/index.js';
+
+// Read package.json for version
+const pkgPath = new URL('../package.json', import.meta.url);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('youtube-video-uploader')
+  .description('Batch upload MP4 videos to YouTube via YouTube Data API v3 with OAuth2 authentication and metadata.json')
+  .version(pkg.version, '-v, --version', 'Output current version')
+  .argument('[directory]', 'Target folder containing MP4 videos and metadata.json (default: current directory)', '.')
+  .option('-d, --dir <path>', 'Explicit target directory path')
+  .option('-m, --metadata <file>', 'Custom path to metadata.json file')
+  .option('-f, --force', 'Force re-upload of already uploaded videos', false)
+  .option('-n, --dry-run', 'Preview video uploads and estimate quota without uploading', false)
+  .option('--client-id <id>', 'Google OAuth Client ID')
+  .option('--client-secret <secret>', 'Google OAuth Client Secret')
+  .option('--client-secrets-file <file>', 'Path to client_secret.json downloaded from Google Cloud')
+  .option('--token-file <file>', 'Path to store or read OAuth token (default: token.json in target dir)')
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (directoryArg, options) => {
+    const targetDir = path.resolve(options.dir || directoryArg || process.cwd());
+    const isQuiet = options.quiet;
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.red(`📺 YouTube Video Uploader CLI`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('📂 Target Folder   :')} ${pc.white(targetDir)}`);
+      if (options.metadata) {
+        console.log(`${pc.bold('📄 Metadata File   :')} ${pc.white(path.resolve(options.metadata))}`);
+      }
+      if (options.dryRun) {
+        console.log(`${pc.yellow(pc.bold('🔍 Mode            :'))} ${pc.yellow('DRY RUN (no uploads will be made)')}`);
+      }
+      if (options.force) {
+        console.log(`${pc.magenta(pc.bold('⚡ Force           :'))} ${pc.magenta('ENABLED (re-uploading previously uploaded videos)')}`);
+      }
+      console.log();
+    }
+
+    try {
+      const tokenFile = options.tokenFile
+        ? path.resolve(options.tokenFile)
+        : path.join(targetDir, 'token.json');
+
+      const result = await batchUpload(targetDir, {
+        metadataFile: options.metadata,
+        force: options.force,
+        dryRun: options.dryRun,
+        tokenFile,
+        clientSecretsFile: options.clientSecretsFile,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        onEvent: (event) => {
+          if (isQuiet) return;
+
+          if (event.type === 'plan') {
+            console.log(
+              pc.bold(`Found `) +
+              pc.green(pc.bold(`${event.total}`)) +
+              pc.bold(` item(s): `) +
+              pc.cyan(`${event.toProcess.length} to upload`) +
+              `, ` +
+              pc.dim(`${event.skipped.length} skipped`)
+            );
+
+            if (event.playlistId) {
+              console.log(pc.dim(`Playlist ID: ${event.playlistId}`));
+            }
+
+            console.log(
+              pc.bold(`Estimated API Quota: `) +
+              (event.estimatedQuota > DAILY_DEFAULT_QUOTA ? pc.red(pc.bold(`${event.estimatedQuota} units`)) : pc.cyan(`${event.estimatedQuota} units`)) +
+              pc.dim(` / ${DAILY_DEFAULT_QUOTA} daily default units`)
+            );
+
+            if (event.estimatedQuota > DAILY_DEFAULT_QUOTA) {
+              console.log(pc.yellow(`⚠️  Warning: Estimated quota exceeds standard daily 10,000 units quota limit!`));
+            }
+            console.log();
+
+            if (event.skipped.length > 0) {
+              for (const s of event.skipped) {
+                console.log(`  ${pc.dim('⏭️  [SKIPPED]')} ${pc.dim(s.filename)} ${pc.dim(`(${s.reason})`)}`);
+              }
+              console.log();
+            }
+          } else if (event.type === 'upload_start') {
+            process.stdout.write(`  ${pc.cyan('⬆️ ')} [${event.index + 1}/${event.total}] Uploading ${pc.bold(event.item.filename)} ("${event.item.title}")... `);
+          } else if (event.type === 'upload_success') {
+            console.log(pc.green(`UPLOADED!`));
+            console.log(`     ${pc.dim('↳ Video URL:')} ${pc.underline(pc.blue(event.record.url))}`);
+            if (event.record.addedToPlaylist) {
+              console.log(`     ${pc.dim('↳ Added to Playlist!')}`);
+            }
+            console.log();
+          } else if (event.type === 'upload_error') {
+            console.log(pc.red(`FAILED`));
+            console.error(pc.red(`     Error: ${event.error.message}\n`));
+          } else if (event.type === 'playlist_error') {
+            console.warn(pc.yellow(`     ⚠️  Playlist Error: ${event.error.message}`));
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        if (options.dryRun) {
+          console.log(pc.yellow(`✨ Dry run complete. No uploads were performed.`));
+          console.log();
+          process.exit(0);
+        }
+
+        console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+        console.log(pc.bold(`📊 Summary:`));
+        console.log(`  • Total items    : ${pc.bold(result.total)}`);
+        console.log(`  • Uploaded       : ${pc.green(pc.bold(result.uploaded.length))}`);
+        console.log(`  • Skipped        : ${pc.dim(result.skipped.length)}`);
+        if (result.failed.length > 0) {
+          console.log(`  • Failed         : ${pc.red(pc.bold(result.failed.length))}`);
+        }
+        console.log();
+
+        if (result.failed.length > 0) {
+          console.log(pc.red(`⚠️  Batch completed with ${result.failed.length} failure(s).`));
+          process.exit(1);
+        } else if (result.uploaded.length > 0) {
+          console.log(pc.green(pc.bold(`🎉 All videos successfully uploaded to YouTube!`)));
+          console.log();
+        } else {
+          console.log(pc.green(`✅ All videos are up to date. Nothing to upload.`));
+          console.log();
+        }
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@x12i/youtube-video-uploader-cli",
+  "version": "1.0.0",
+  "description": "CLI tool to batch upload MP4 videos to YouTube via YouTube Data API v3 with OAuth2, metadata.json config, playlist assignment, and smart upload-state resume.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "youtube-video-uploader": "bin/cli.js",
+    "yt-uploader": "bin/cli.js",
+    "yvu-cli": "bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "youtube",
+    "uploader",
+    "youtube-data-api",
+    "oauth2",
+    "video-upload",
+    "playlist",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "googleapis": "^144.0.0",
+    "open": "^10.1.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/auth.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import readline from 'node:readline';
+import { google } from 'googleapis';
+import open from 'open';
+import pc from 'picocolors';
+
+export const YOUTUBE_SCOPES = [
+  'https://www.googleapis.com/auth/youtube.upload',
+  'https://www.googleapis.com/auth/youtube',
+];
+
+export const DEFAULT_REDIRECT_URI = 'http://localhost:3000/oauth2callback';
+export const DEFAULT_TOKEN_FILENAME = 'token.json';
+
+/**
+ * Extract Client ID and Client Secret from file or environment.
+ * @param {object} options
+ * @returns {{ clientId: string, clientSecret: string, redirectUri: string }}
+ */
+export function resolveOAuthCredentials(options = {}) {
+  let clientId = options.clientId || process.env.YOUTUBE_CLIENT_ID || process.env.GOOGLE_CLIENT_ID;
+  let clientSecret = options.clientSecret || process.env.YOUTUBE_CLIENT_SECRET || process.env.GOOGLE_CLIENT_SECRET;
+  const redirectUri = options.redirectUri || DEFAULT_REDIRECT_URI;
+
+  if (options.clientSecretsFile && fs.existsSync(options.clientSecretsFile)) {
+    try {
+      const fileData = JSON.parse(fs.readFileSync(options.clientSecretsFile, 'utf-8'));
+      const credentials = fileData.installed || fileData.web || fileData;
+      clientId = credentials.client_id || clientId;
+      clientSecret = credentials.client_secret || clientSecret;
+    } catch (err) {
+      throw new Error(`Failed to parse client secrets file: ${err.message}`);
+    }
+  }
+
+  // Also check default client_secret.json in current directory or target folder
+  if (!clientId || !clientSecret) {
+    const localSecrets = ['client_secret.json', 'client_secrets.json', 'credentials.json'];
+    for (const name of localSecrets) {
+      const checkPath = path.resolve(name);
+      if (fs.existsSync(checkPath)) {
+        try {
+          const fileData = JSON.parse(fs.readFileSync(checkPath, 'utf-8'));
+          const credentials = fileData.installed || fileData.web || fileData;
+          if (credentials.client_id && credentials.client_secret) {
+            clientId = credentials.client_id;
+            clientSecret = credentials.client_secret;
+            break;
+          }
+        } catch {
+          // Ignore
+        }
+      }
+    }
+  }
+
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      `Missing Google OAuth2 Credentials!\n` +
+      `Please provide them via:\n` +
+      `  • Environment variables: YOUTUBE_CLIENT_ID and YOUTUBE_CLIENT_SECRET\n` +
+      `  • CLI flags: --client-id <id> --client-secret <secret>\n` +
+      `  • File: --client-secrets-file <path/to/client_secret.json>`
+    );
+  }
+
+  return { clientId, clientSecret, redirectUri };
+}
+
+/**
+ * Authenticate with YouTube Data API using OAuth2 and cached tokens.
+ * 
+ * @param {object} [options]
+ * @param {string} [options.clientId]
+ * @param {string} [options.clientSecret]
+ * @param {string} [options.clientSecretsFile]
+ * @param {string} [options.tokenFile]
+ * @param {string} [options.redirectUri]
+ * @param {boolean} [options.noBrowser=false]
+ * @returns {Promise<InstanceType<typeof google.auth.OAuth2>>}
+ */
+export async function authenticate(options = {}) {
+  const { clientId, clientSecret, redirectUri } = resolveOAuthCredentials(options);
+  const tokenPath = path.resolve(options.tokenFile || DEFAULT_TOKEN_FILENAME);
+
+  const oauth2Client = new google.auth.OAuth2(clientId, clientSecret, redirectUri);
+
+  // Automatically save refreshed tokens
+  oauth2Client.on('tokens', (tokens) => {
+    try {
+      let currentTokens = {};
+      if (fs.existsSync(tokenPath)) {
+        currentTokens = JSON.parse(fs.readFileSync(tokenPath, 'utf-8'));
+      }
+      const updated = { ...currentTokens, ...tokens };
+      fs.writeFileSync(tokenPath, JSON.stringify(updated, null, 2), 'utf-8');
+    } catch (err) {
+      console.warn(pc.yellow(`Warning: Could not save refreshed token to ${tokenPath}: ${err.message}`));
+    }
+  });
+
+  // 1. Check if token already exists locally
+  if (fs.existsSync(tokenPath)) {
+    try {
+      const tokenContent = fs.readFileSync(tokenPath, 'utf-8');
+      const tokens = JSON.parse(tokenContent);
+      oauth2Client.setCredentials(tokens);
+      return oauth2Client;
+    } catch (err) {
+      console.warn(pc.yellow(`Warning: Existing token file is invalid (${err.message}). Re-authenticating...`));
+    }
+  }
+
+  // 2. Perform interactive authorization flow
+  const authUrl = oauth2Client.generateAuthUrl({
+    access_type: 'offline',
+    prompt: 'consent',
+    scope: YOUTUBE_SCOPES,
+  });
+
+  console.log();
+  console.log(pc.bold(pc.cyan(`🔐 YouTube OAuth2 Authorization Required`)));
+  console.log(pc.dim(`─────────────────────────────────────────────────`));
+  console.log(`Please visit the following URL to authorize access to your YouTube channel:\n`);
+  console.log(pc.underline(pc.blue(authUrl)));
+  console.log();
+
+  if (!options.noBrowser) {
+    try {
+      await open(authUrl);
+      console.log(pc.dim(`(Opened browser automatically. If it didn't open, copy the URL above.)`));
+    } catch {
+      // Ignore if browser launch failed
+    }
+  }
+
+  const code = await waitForAuthCode(redirectUri);
+
+  const { tokens } = await oauth2Client.getToken(code.trim());
+  oauth2Client.setCredentials(tokens);
+
+  try {
+    fs.writeFileSync(tokenPath, JSON.stringify(tokens, null, 2), 'utf-8');
+    console.log(pc.green(`✅ Authentication successful! Tokens saved to: ${tokenPath}`));
+  } catch (err) {
+    console.warn(pc.yellow(`Warning: Could not write token to ${tokenPath}: ${err.message}`));
+  }
+
+  return oauth2Client;
+}
+
+/**
+ * Capture auth code via lightweight local server with terminal prompt fallback.
+ * @param {string} redirectUri 
+ * @returns {Promise<string>}
+ */
+function waitForAuthCode(redirectUri) {
+  return new Promise((resolve) => {
+    let server = null;
+    let resolved = false;
+
+    const cleanup = () => {
+      if (server) {
+        try { server.close(); } catch {}
+        server = null;
+      }
+    };
+
+    try {
+      const parsed = new URL(redirectUri);
+      const port = parseInt(parsed.port, 10) || 3000;
+      const pathname = parsed.pathname || '/oauth2callback';
+
+      server = http.createServer((req, res) => {
+        try {
+          const reqUrl = new URL(req.url, `http://localhost:${port}`);
+          if (reqUrl.pathname === pathname) {
+            const code = reqUrl.searchParams.get('code');
+            const error = reqUrl.searchParams.get('error');
+
+            if (code) {
+              res.writeHead(200, { 'Content-Type': 'text/html' });
+              res.end(`
+                <html>
+                  <body style="font-family: system-ui, sans-serif; text-align: center; padding: 50px;">
+                    <h1 style="color: #2e7d32;">Authorization Successful!</h1>
+                    <p>You can close this tab and return to the terminal.</p>
+                  </body>
+                </html>
+              `);
+              if (!resolved) {
+                resolved = true;
+                cleanup();
+                resolve(code);
+              }
+              return;
+            } else if (error) {
+              res.writeHead(400, { 'Content-Type': 'text/html' });
+              res.end(`<h1>Authorization Error: ${error}</h1>`);
+            }
+          }
+        } catch {
+          // Ignore
+        }
+      });
+
+      server.listen(port, () => {
+        // Listening on localhost for callback
+      });
+
+      server.on('error', () => {
+        cleanup();
+      });
+    } catch {
+      cleanup();
+    }
+
+    // Terminal prompt fallback
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(pc.bold('\nEnter the authorization code (or URL query code): '), (inputCode) => {
+      rl.close();
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(inputCode);
+      }
+    });
+  });
+}

package/src/index.d.ts

@@ -0,0 +1,83 @@
+import type { OAuth2Client } from 'google-auth-library';
+import type { youtube_v3 } from 'googleapis';
+
+export interface VideoMetadata {
+  filename: string;
+  title: string;
+  description: string;
+  tags: string[];
+  categoryId?: string;
+  privacyStatus?: 'private' | 'unlisted' | 'public';
+  filePath: string;
+}
+
+export interface MetadataConfig {
+  playlistId: string | null;
+  privacyStatus: 'private' | 'unlisted' | 'public';
+  categoryId: string;
+  videos: VideoMetadata[];
+}
+
+export interface BatchUploadOptions {
+  metadataFile?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  tokenFile?: string;
+  clientSecretsFile?: string;
+  clientId?: string;
+  clientSecret?: string;
+  onEvent?: (event: { type: string; [key: string]: any }) => void;
+}
+
+export interface BatchUploadResult {
+  targetFolder: string;
+  total: number;
+  uploaded: Array<{ filename: string; videoId: string; url: string; addedToPlaylist: boolean }>;
+  skipped: Array<{ filename: string; videoId?: string; reason: string }>;
+  failed: Array<{ filename: string; error: Error }>;
+  estimatedQuota: number;
+}
+
+export declare class UploadState {
+  constructor(targetFolder?: string, stateFilename?: string);
+  getUpload(filename: string): { videoId: string; uploadedAt: string; playlistId?: string } | null;
+  recordUpload(filename: string, videoId: string, playlistId?: string | null): void;
+  recordPlaylist(filename: string, playlistId: string): void;
+  save(): void;
+}
+
+export function loadMetadata(targetFolder?: string, customMetadataPath?: string): MetadataConfig;
+export function authenticate(options?: {
+  clientId?: string;
+  clientSecret?: string;
+  clientSecretsFile?: string;
+  tokenFile?: string;
+  redirectUri?: string;
+  noBrowser?: boolean;
+}): Promise<OAuth2Client>;
+
+export function uploadVideo(
+  youtube: youtube_v3.Youtube,
+  filePath: string,
+  meta: VideoMetadata,
+  defaultPrivacy?: string,
+  defaultCategory?: string
+): Promise<{ videoId: string; url: string }>;
+
+export function addToPlaylist(
+  youtube: youtube_v3.Youtube,
+  playlistId: string,
+  videoId: string
+): Promise<any>;
+
+export function batchUpload(
+  targetFolder?: string,
+  options?: BatchUploadOptions
+): Promise<BatchUploadResult>;
+
+export const QUOTA_PER_VIDEO_UPLOAD: number;
+export const QUOTA_PER_PLAYLIST_ITEM: number;
+export const DAILY_DEFAULT_QUOTA: number;
+export const DEFAULT_CATEGORY_ID: string;
+export const DEFAULT_PRIVACY_STATUS: string;
+export const VALID_PRIVACY_STATUSES: Set<string>;

package/src/index.js

@@ -0,0 +1,11 @@
+export { authenticate, resolveOAuthCredentials, YOUTUBE_SCOPES } from './auth.js';
+export { loadMetadata, DEFAULT_CATEGORY_ID, DEFAULT_PRIVACY_STATUS, VALID_PRIVACY_STATUSES } from './metadata.js';
+export { UploadState, DEFAULT_STATE_FILENAME } from './state.js';
+export {
+  uploadVideo,
+  addToPlaylist,
+  batchUpload,
+  QUOTA_PER_VIDEO_UPLOAD,
+  QUOTA_PER_PLAYLIST_ITEM,
+  DAILY_DEFAULT_QUOTA,
+} from './uploader.js';

package/src/metadata.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const VALID_PRIVACY_STATUSES = new Set(['private', 'unlisted', 'public']);
+
+// YouTube Category IDs reference:
+// 10 = Music, 22 = People & Blogs, 27 = Education, 28 = Science & Technology, etc.
+export const DEFAULT_CATEGORY_ID = '10'; // Music
+export const DEFAULT_PRIVACY_STATUS = 'private';
+
+/**
+ * Load, validate, and normalize metadata for batch video uploading.
+ * 
+ * @param {string} targetFolder - Path to folder containing videos
+ * @param {string} [customMetadataPath] - Optional custom path to metadata.json
+ * @returns {{
+ *   playlistId: string | null,
+ *   privacyStatus: 'private' | 'unlisted' | 'public',
+ *   categoryId: string,
+ *   videos: Array<{
+ *     filename: string,
+ *     title: string,
+ *     description: string,
+ *     tags: string[],
+ *     categoryId?: string,
+ *     privacyStatus?: 'private' | 'unlisted' | 'public',
+ *     filePath: string
+ *   }>
+ * }}
+ */
+export function loadMetadata(targetFolder, customMetadataPath) {
+  const resolvedFolder = path.resolve(targetFolder || process.cwd());
+  const metadataPath = customMetadataPath
+    ? path.resolve(customMetadataPath)
+    : path.join(resolvedFolder, 'metadata.json');
+
+  let rawConfig = {};
+
+  if (fs.existsSync(metadataPath)) {
+    try {
+      const content = fs.readFileSync(metadataPath, 'utf-8');
+      rawConfig = JSON.parse(content);
+    } catch (err) {
+      throw new Error(`Failed to parse metadata file (${metadataPath}): ${err.message}`);
+    }
+  } else {
+    // If metadata.json does not exist, check if there are .mp4 files we can auto-discover
+    if (customMetadataPath) {
+      throw new Error(`Specified metadata file does not exist: ${metadataPath}`);
+    }
+  }
+
+  const defaultPrivacy = VALID_PRIVACY_STATUSES.has(rawConfig.privacyStatus)
+    ? rawConfig.privacyStatus
+    : DEFAULT_PRIVACY_STATUS;
+
+  const defaultCategory = String(rawConfig.categoryId || DEFAULT_CATEGORY_ID);
+  const playlistId = rawConfig.playlistId ? String(rawConfig.playlistId).trim() : null;
+
+  let rawVideos = Array.isArray(rawConfig.videos) ? rawConfig.videos : [];
+
+  // If no videos array was provided in metadata.json, auto-discover all .mp4 files in the folder
+  if (rawVideos.length === 0 && fs.existsSync(resolvedFolder)) {
+    const files = fs.readdirSync(resolvedFolder);
+    const mp4Files = files.filter(f => f.toLowerCase().endsWith('.mp4') && !f.startsWith('.'));
+    rawVideos = mp4Files.map(filename => ({
+      filename,
+      title: path.basename(filename, path.extname(filename)),
+      description: '',
+      tags: [],
+    }));
+  }
+
+  const videos = rawVideos.map((item, index) => {
+    if (!item.filename) {
+      throw new Error(`Video at index ${index} in metadata.json is missing required "filename" property.`);
+    }
+
+    const filename = String(item.filename);
+    const filePath = path.isAbsolute(filename) ? filename : path.join(resolvedFolder, filename);
+    const title = item.title ? String(item.title) : path.basename(filename, path.extname(filename));
+    const description = item.description ? String(item.description) : '';
+    const tags = Array.isArray(item.tags) ? item.tags.map(t => String(t).trim()).filter(Boolean) : [];
+
+    const privacyStatus = item.privacyStatus && VALID_PRIVACY_STATUSES.has(item.privacyStatus)
+      ? item.privacyStatus
+      : defaultPrivacy;
+
+    const categoryId = item.categoryId ? String(item.categoryId) : defaultCategory;
+
+    return {
+      filename,
+      filePath,
+      title,
+      description,
+      tags,
+      categoryId,
+      privacyStatus,
+    };
+  });
+
+  return {
+    playlistId,
+    privacyStatus: defaultPrivacy,
+    categoryId: defaultCategory,
+    videos,
+  };
+}

package/src/state.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_STATE_FILENAME = '.upload-history.json';
+
+/**
+ * State manager to keep track of uploaded videos and playlist statuses.
+ */
+export class UploadState {
+  /**
+   * @param {string} targetFolder 
+   * @param {string} [stateFilename]
+   */
+  constructor(targetFolder, stateFilename = DEFAULT_STATE_FILENAME) {
+    this.targetFolder = path.resolve(targetFolder || process.cwd());
+    this.statePath = path.join(this.targetFolder, stateFilename);
+    this.data = this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.statePath)) {
+      try {
+        const content = fs.readFileSync(this.statePath, 'utf-8');
+        return JSON.parse(content);
+      } catch {
+        return { uploads: {} };
+      }
+    }
+    return { uploads: {} };
+  }
+
+  save() {
+    try {
+      fs.writeFileSync(this.statePath, JSON.stringify(this.data, null, 2), 'utf-8');
+    } catch (err) {
+      console.warn(`Warning: Could not save upload state to ${this.statePath}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Check if a file has already been uploaded.
+   * @param {string} filename 
+   * @returns {{ videoId: string, uploadedAt: string, playlistId?: string } | null}
+   */
+  getUpload(filename) {
+    const key = path.basename(filename);
+    return this.data.uploads[key] || null;
+  }
+
+  /**
+   * Record a successful upload.
+   * @param {string} filename 
+   * @param {string} videoId 
+   * @param {string} [playlistId] 
+   */
+  recordUpload(filename, videoId, playlistId = null) {
+    const key = path.basename(filename);
+    this.data.uploads[key] = {
+      videoId,
+      uploadedAt: new Date().toISOString(),
+      playlistId: playlistId || (this.data.uploads[key]?.playlistId ?? null),
+    };
+    this.save();
+  }
+
+  /**
+   * Record playlist association.
+   * @param {string} filename 
+   * @param {string} playlistId 
+   */
+  recordPlaylist(filename, playlistId) {
+    const key = path.basename(filename);
+    if (!this.data.uploads[key]) {
+      this.data.uploads[key] = { videoId: null, uploadedAt: null };
+    }
+    this.data.uploads[key].playlistId = playlistId;
+    this.save();
+  }
+}

package/src/uploader.js

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { google } from 'googleapis';
+import { loadMetadata } from './metadata.js';
+import { UploadState } from './state.js';
+import { authenticate } from './auth.js';
+
+export const QUOTA_PER_VIDEO_UPLOAD = 1600;
+export const QUOTA_PER_PLAYLIST_ITEM = 50;
+export const DAILY_DEFAULT_QUOTA = 10000;
+
+/**
+ * Upload a single video file to YouTube via YouTube Data API v3.
+ * 
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} filePath
+ * @param {object} meta
+ * @param {string} [defaultPrivacy='private']
+ * @param {string} [defaultCategory='10']
+ * @returns {Promise<{ videoId: string, url: string }>}
+ */
+export async function uploadVideo(youtube, filePath, meta, defaultPrivacy = 'private', defaultCategory = '10') {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Video file not found: ${filePath}`);
+  }
+
+  const stat = fs.statSync(filePath);
+  if (stat.size === 0) {
+    throw new Error(`Video file is empty (0 bytes): ${filePath}`);
+  }
+
+  const res = await youtube.videos.insert({
+    part: ['snippet', 'status'],
+    requestBody: {
+      snippet: {
+        title: meta.title,
+        description: meta.description || '',
+        tags: meta.tags || [],
+        categoryId: meta.categoryId || defaultCategory || '10',
+      },
+      status: {
+        privacyStatus: meta.privacyStatus || defaultPrivacy || 'private',
+      },
+    },
+    media: {
+      body: fs.createReadStream(filePath),
+    },
+  });
+
+  const videoId = res.data.id;
+  return {
+    videoId,
+    url: `https://youtu.be/${videoId}`,
+  };
+}
+
+/**
+ * Add a video to a YouTube Playlist.
+ * 
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string} videoId
+ * @returns {Promise<any>}
+ */
+export async function addToPlaylist(youtube, playlistId, videoId) {
+  const res = await youtube.playlistItems.insert({
+    part: ['snippet'],
+    requestBody: {
+      snippet: {
+        playlistId,
+        resourceId: {
+          kind: 'youtube#video',
+          videoId,
+        },
+      },
+    },
+  });
+  return res.data;
+}
+
+/**
+ * Batch upload all videos from a directory using metadata.json.
+ * 
+ * @param {string} targetFolder - Directory containing videos and metadata.json
+ * @param {object} [options]
+ * @param {string} [options.metadataFile] - Custom metadata JSON path
+ * @param {boolean} [options.force=false] - Re-upload previously uploaded videos
+ * @param {boolean} [options.dryRun=false] - Preview without uploading
+ * @param {string} [options.tokenFile] - Custom token JSON path
+ * @param {string} [options.clientSecretsFile] - Custom client_secret.json path
+ * @param {(event: { type: string, [key: string]: any }) => void} [options.onEvent]
+ * @returns {Promise<{
+ *   targetFolder: string,
+ *   total: number,
+ *   uploaded: Array<{ filename: string, videoId: string, url: string, addedToPlaylist: boolean }>,
+ *   skipped: Array<{ filename: string, videoId?: string, reason: string }>,
+ *   failed: Array<{ filename: string, error: Error }>,
+ *   estimatedQuota: number
+ * }>}
+ */
+export async function batchUpload(targetFolder, options = {}) {
+  const resolvedFolder = path.resolve(targetFolder || process.cwd());
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options.dryRun);
+  const onEvent = options.onEvent || (() => {});
+
+  const config = loadMetadata(resolvedFolder, options.metadataFile);
+  const state = new UploadState(resolvedFolder);
+
+  const playlistId = config.playlistId;
+  const toProcess = [];
+  const skipped = [];
+
+  for (const item of config.videos) {
+    if (!fs.existsSync(item.filePath)) {
+      skipped.push({
+        filename: item.filename,
+        reason: 'File not found on disk',
+      });
+      continue;
+    }
+
+    const previousUpload = state.getUpload(item.filename);
+    if (previousUpload && !force) {
+      skipped.push({
+        filename: item.filename,
+        videoId: previousUpload.videoId,
+        reason: `Already uploaded (Video ID: ${previousUpload.videoId})`,
+      });
+    } else {
+      toProcess.push(item);
+    }
+  }
+
+  const estimatedQuota = (toProcess.length * QUOTA_PER_VIDEO_UPLOAD) +
+    (playlistId ? toProcess.length * QUOTA_PER_PLAYLIST_ITEM : 0);
+
+  onEvent({
+    type: 'plan',
+    total: config.videos.length,
+    toProcess,
+    skipped,
+    estimatedQuota,
+    playlistId,
+  });
+
+  if (dryRun) {
+    return {
+      targetFolder: resolvedFolder,
+      total: config.videos.length,
+      uploaded: [],
+      skipped,
+      failed: [],
+      estimatedQuota,
+    };
+  }
+
+  if (toProcess.length === 0) {
+    return {
+      targetFolder: resolvedFolder,
+      total: config.videos.length,
+      uploaded: [],
+      skipped,
+      failed: [],
+      estimatedQuota: 0,
+    };
+  }
+
+  // Authenticate
+  const auth = await authenticate({
+    tokenFile: options.tokenFile,
+    clientSecretsFile: options.clientSecretsFile,
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+  });
+
+  const youtube = google.youtube({ version: 'v3', auth });
+
+  const uploaded = [];
+  const failed = [];
+
+  for (let i = 0; i < toProcess.length; i++) {
+    const item = toProcess[i];
+    onEvent({ type: 'upload_start', item, index: i, total: toProcess.length });
+
+    try {
+      const uploadRes = await uploadVideo(
+        youtube,
+        item.filePath,
+        item,
+        config.privacyStatus,
+        config.categoryId
+      );
+
+      let addedToPlaylist = false;
+      if (playlistId) {
+        onEvent({ type: 'playlist_start', item, videoId: uploadRes.videoId, playlistId });
+        try {
+          await addToPlaylist(youtube, playlistId, uploadRes.videoId);
+          addedToPlaylist = true;
+          onEvent({ type: 'playlist_success', item, videoId: uploadRes.videoId, playlistId });
+        } catch (playlistErr) {
+          onEvent({ type: 'playlist_error', item, videoId: uploadRes.videoId, error: playlistErr });
+        }
+      }
+
+      state.recordUpload(item.filename, uploadRes.videoId, addedToPlaylist ? playlistId : null);
+
+      const record = {
+        filename: item.filename,
+        videoId: uploadRes.videoId,
+        url: uploadRes.url,
+        addedToPlaylist,
+      };
+
+      uploaded.push(record);
+      onEvent({ type: 'upload_success', item, record });
+    } catch (err) {
+      failed.push({ filename: item.filename, error: err });
+      onEvent({ type: 'upload_error', item, error: err });
+    }
+  }
+
+  return {
+    targetFolder: resolvedFolder,
+    total: config.videos.length,
+    uploaded,
+    skipped,
+    failed,
+    estimatedQuota,
+  };
+}