@x12i/youtube-video-uploader-cli 1.1.0 → 1.3.0

package/src/swap/steps.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { uploadVideo } from '../uploader.js';
+
+/**
+ * The five individual steps of a playlist video swap. Each is a plain
+ * function over the googleapis youtube client so they can be composed and
+ * tested independently.
+ */
+
+/**
+ * Step 1 — Upload the new video as unlisted (never straight to public).
+ *
+ * Metadata (title/description/tags/category) is carried over from the old
+ * video's snippet when available so the replacement stays continuous.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} newVideoPath
+ * @param {object} [opts]
+ * @param {string} [opts.oldVideoId] - Fetch old video's snippet to carry over
+ * @param {object} [opts.meta] - Explicit metadata overrides
+ * @param {number} [opts.retries=3]
+ * @returns {Promise<{ videoId: string, url: string }>}
+ */
+export async function uploadNewVideo(youtube, newVideoPath, opts = {}) {
+  if (!fs.existsSync(newVideoPath)) {
+    throw new Error(`New video file not found: ${newVideoPath}`);
+  }
+
+  let meta = {
+    title: opts.meta?.title,
+    description: opts.meta?.description,
+    tags: opts.meta?.tags,
+    categoryId: opts.meta?.categoryId,
+    privacyStatus: 'unlisted',
+    selfDeclaredMadeForKids: opts.meta?.selfDeclaredMadeForKids ?? false,
+  };
+
+  // Carry over metadata from the old video where not explicitly overridden
+  if (opts.oldVideoId) {
+    try {
+      const res = await youtube.videos.list({
+        part: ['snippet', 'status'],
+        id: [opts.oldVideoId],
+      });
+      const old = res.data.items?.[0];
+      if (old) {
+        meta = {
+          title: meta.title || old.snippet?.title,
+          description: meta.description ?? old.snippet?.description,
+          tags: meta.tags || old.snippet?.tags || [],
+          categoryId: meta.categoryId || old.snippet?.categoryId,
+          privacyStatus: 'unlisted',
+          selfDeclaredMadeForKids: meta.selfDeclaredMadeForKids
+            ?? (old.status?.madeForKids !== undefined ? old.status.madeForKids : false),
+        };
+      }
+    } catch {
+      // Metadata carry-over is best-effort; explicit meta or defaults still apply
+    }
+  }
+
+  if (!meta.title) {
+    throw new Error('Cannot upload swap video without a title: provide meta.title or a reachable oldVideoId');
+  }
+
+  // Uploads are the most failure-prone step — retry with backoff
+  const retries = opts.retries ?? 3;
+  let lastErr;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await uploadVideo(youtube, newVideoPath, meta, 'unlisted');
+    } catch (err) {
+      lastErr = err;
+      if (attempt < retries) {
+        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1)));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Step 2 — Locate the old video's playlistItem id and position.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string} oldVideoId
+ * @returns {Promise<{ playlistItemId: string, position: number } | null>} Null when the video is not in the playlist
+ */
+export async function findPlaylistItem(youtube, playlistId, oldVideoId) {
+  let pageToken;
+  do {
+    const { data } = await youtube.playlistItems.list({
+      part: ['snippet'],
+      playlistId,
+      maxResults: 50,
+      pageToken,
+    });
+    const match = (data.items || []).find(
+      item => item.snippet?.resourceId?.videoId === oldVideoId
+    );
+    if (match) {
+      return { playlistItemId: match.id, position: match.snippet.position };
+    }
+    pageToken = data.nextPageToken;
+  } while (pageToken);
+  return null;
+}
+
+/**
+ * Step 3 — Insert the new video into the playlist at the old item's position.
+ * The old item shifts down one slot temporarily; it is removed in step 4.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string} newVideoId
+ * @param {number} position
+ * @returns {Promise<{ newPlaylistItemId: string }>}
+ */
+export async function insertAtPosition(youtube, playlistId, newVideoId, position) {
+  const res = await youtube.playlistItems.insert({
+    part: ['snippet'],
+    requestBody: {
+      snippet: {
+        playlistId,
+        position,
+        resourceId: { kind: 'youtube#video', videoId: newVideoId },
+      },
+    },
+  });
+  return { newPlaylistItemId: res.data.id };
+}
+
+/**
+ * Step 4 — Remove the old video's playlist item.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} oldPlaylistItemId
+ */
+export async function removeOldItem(youtube, oldPlaylistItemId) {
+  await youtube.playlistItems.delete({ id: oldPlaylistItemId });
+}
+
+/**
+ * Step 5 — Finalize: unlist the old video (never delete), then publish the
+ * new one. Ordered so any earlier failure leaves the old video untouched.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} oldVideoId
+ * @param {string} newVideoId
+ */
+export async function finalizeSwap(youtube, oldVideoId, newVideoId) {
+  await youtube.videos.update({
+    part: ['status'],
+    requestBody: { id: oldVideoId, status: { privacyStatus: 'unlisted' } },
+  });
+  await youtube.videos.update({
+    part: ['status'],
+    requestBody: { id: newVideoId, status: { privacyStatus: 'public' } },
+  });
+}

package/src/swap/store.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_SWAP_STATE_FILENAME = '.swap-history.json';
+
+export const SWAP_STATUSES = [
+  'pending',
+  'uploaded',
+  'located',
+  'inserted',
+  'removed',
+  'finalized',
+  'failed',
+];
+
+/**
+ * State manager for playlist video swaps. Persists a SwapRecord per song key
+ * so an interrupted swap can be safely resumed without re-uploading or
+ * double-inserting playlist items.
+ *
+ * @typedef {Object} SwapRecord
+ * @property {string} songKey - Stable key identifying this swap (song/file identifier)
+ * @property {string} oldVideoId
+ * @property {string} playlistId
+ * @property {string} [newVideoPath]
+ * @property {string} [newVideoId]
+ * @property {string} [oldPlaylistItemId]
+ * @property {number} [oldPosition]
+ * @property {string} [newPlaylistItemId]
+ * @property {string} status
+ * @property {string} [lastError]
+ * @property {string} [updatedAt]
+ */
+export class SwapStore {
+  /**
+   * @param {string} targetFolder
+   * @param {string} [stateFilename]
+   */
+  constructor(targetFolder, stateFilename = DEFAULT_SWAP_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');
+        const parsed = JSON.parse(content);
+        return { ...parsed, swaps: parsed.swaps || {} };
+      } catch {
+        return { swaps: {} };
+      }
+    }
+    return { swaps: {} };
+  }
+
+  save() {
+    try {
+      fs.writeFileSync(this.statePath, JSON.stringify(this.data, null, 2), 'utf-8');
+    } catch (err) {
+      console.warn(`Warning: Could not save swap state to ${this.statePath}: ${err.message}`);
+    }
+  }
+
+  /**
+   * @param {string} songKey
+   * @returns {SwapRecord | null}
+   */
+  getRecord(songKey) {
+    return this.data.swaps[songKey] || null;
+  }
+
+  /**
+   * Create or reset a pending swap record.
+   * @param {object} record
+   * @returns {SwapRecord}
+   */
+  initRecord(record) {
+    /** @type {SwapRecord} */
+    const full = {
+      status: 'pending',
+      updatedAt: new Date().toISOString(),
+      ...record,
+    };
+    this.data.swaps[full.songKey] = full;
+    this.save();
+    return full;
+  }
+
+  /**
+   * Merge fields into an existing record and persist immediately.
+   * @param {string} songKey
+   * @param {Partial<SwapRecord>} fields
+   * @returns {SwapRecord}
+   */
+  updateRecord(songKey, fields) {
+    if (!this.data.swaps[songKey]) {
+      throw new Error(`No swap record exists for key: ${songKey}`);
+    }
+    this.data.swaps[songKey] = {
+      ...this.data.swaps[songKey],
+      ...fields,
+      songKey,
+      updatedAt: new Date().toISOString(),
+    };
+    this.save();
+    return this.data.swaps[songKey];
+  }
+
+  /**
+   * List all records with the given status (or all records).
+   * @param {string} [status]
+   * @returns {SwapRecord[]}
+   */
+  listRecords(status) {
+    const all = Object.values(this.data.swaps);
+    return status ? all.filter(r => r.status === status) : all;
+  }
+}

package/src/swap/swapSong.js

@@ -0,0 +1,154 @@
+import { SwapStore } from './store.js';
+import {
+  uploadNewVideo,
+  findPlaylistItem,
+  insertAtPosition,
+  removeOldItem,
+  finalizeSwap,
+} from './steps.js';
+
+/** Shared-pool quota cost of one full swap (list + insert + delete + 2 updates). */
+export const QUOTA_PER_SWAP = 150 + 1; // ~150 shared units + 1 upload-bucket unit
+
+/**
+ * Swap state machine:
+ *
+ *   1. UPLOAD    — upload the new video (videos.insert), unlisted for now
+ *   2. LOCATE    — find the old video's playlistItem id + position
+ *   3. INSERT    — add the new video at the old item's position
+ *   4. REMOVE    — delete the old playlistItem
+ *   5. FINALIZE  — old video → unlisted, new video → public
+ *
+ * Every step persists state before moving on, so a crash or API error at any
+ * point can be safely resumed by re-running swapSong — completed steps are
+ * skipped, the old video is never deleted, and the upload is never repeated.
+ *
+ * @param {object} params
+ * @param {import('googleapis').youtube_v3.Youtube} params.youtube - Authorized youtube client
+ * @param {string} params.songKey - Stable key for this swap (song/file identifier)
+ * @param {string} params.newVideoPath - Path to the replacement video file
+ * @param {string} params.playlistId
+ * @param {string} params.oldVideoId
+ * @param {object} [params.meta] - Explicit new-video metadata overrides
+ * @param {string} [params.stateDir] - Where the swap state file lives (default: cwd)
+ * @param {string} [params.stateFile] - Custom state filename
+ * @param {boolean} [params.fresh=false] - Reset any existing record for songKey
+ * @param {(event: { type: string, [key: string]: any }) => void} [params.onEvent]
+ * @returns {Promise<{ record: any, dryRunPlan?: string[] }>}
+ */
+export async function swapSong(params) {
+  const {
+    youtube,
+    songKey,
+    newVideoPath,
+    playlistId,
+    oldVideoId,
+    meta,
+    stateDir,
+    stateFile,
+    fresh = false,
+    onEvent = () => {},
+  } = params;
+
+  if (!songKey || !newVideoPath || !playlistId || !oldVideoId) {
+    throw new Error('swapSong requires songKey, newVideoPath, playlistId and oldVideoId');
+  }
+
+  const store = new SwapStore(stateDir || process.cwd(), stateFile);
+  const existing = store.getRecord(songKey);
+
+  if (existing && !fresh && ['pending', 'uploaded', 'located', 'inserted', 'removed'].includes(existing.status)) {
+    onEvent({ type: 'swap_resume', songKey, status: existing.status });
+  }
+
+  const record = (existing && !fresh)
+    ? { ...existing, playlistId, oldVideoId, newVideoPath }
+    : store.initRecord({ songKey, playlistId, oldVideoId, newVideoPath, status: 'pending' });
+  if (existing && !fresh) {
+    // persist any refreshed params above
+    store.updateRecord(songKey, { playlistId, oldVideoId, newVideoPath });
+  }
+
+  /**
+   * Run one step, guarding against re-doing completed work.
+   * @template T
+   * @param {string} doneStatus - Status that marks this step complete
+   * @param {() => Promise<T>} fn
+   * @param {(result: T) => Partial<Record<string, any>>} [fieldsFromResult]
+   */
+  async function step(doneStatus, fn, fieldsFromResult) {
+    if (stepIndex(record.status) >= stepIndex(doneStatus)) return;
+    const result = await fn();
+    store.updateRecord(songKey, { status: doneStatus, lastError: undefined, ...(fieldsFromResult ? fieldsFromResult(result) : {}) });
+    onEvent({ type: 'swap_step', songKey, status: doneStatus });
+  }
+
+  try {
+    // 1. UPLOAD
+    await step('uploaded', async () => {
+      const alreadyUploaded = store.getRecord(songKey).newVideoId;
+      if (alreadyUploaded) {
+        return { videoId: alreadyUploaded };
+      }
+      const up = await uploadNewVideo(youtube, newVideoPath, { oldVideoId, meta });
+      onEvent({ type: 'swap_uploaded', songKey, newVideoId: up.videoId, url: up.url });
+      return up;
+    }, r => ({ newVideoId: r.videoId }));
+    const newVideoId = store.getRecord(songKey).newVideoId;
+
+    // 2. LOCATE
+    await step('located', async () => {
+      const found = await findPlaylistItem(youtube, playlistId, oldVideoId);
+      if (!found) {
+        const err = new Error(
+          `Old video ${oldVideoId} not found in playlist ${playlistId} — ` +
+          `it may have already been removed, or the video ID is wrong.`
+        );
+        err.needsManualReview = true;
+        throw err;
+      }
+      return found;
+    }, r => ({ oldPlaylistItemId: r.playlistItemId, oldPosition: r.position }));
+    const current = store.getRecord(songKey);
+
+    // 3. INSERT (guard: if a previous attempt already inserted the new video
+    // but crashed before persisting, reuse that item instead of duplicating it)
+    await step('inserted', async () => {
+      const alreadyInserted = await findPlaylistItem(youtube, playlistId, newVideoId);
+      if (alreadyInserted) {
+        return { newPlaylistItemId: alreadyInserted.playlistItemId };
+      }
+      return await insertAtPosition(youtube, playlistId, newVideoId, current.oldPosition);
+    }, r => ({ newPlaylistItemId: r.newPlaylistItemId }));
+
+    // 4. REMOVE
+    await step('removed', async () => {
+      await removeOldItem(youtube, current.oldPlaylistItemId);
+    });
+
+    // 5. FINALIZE
+    await step('finalized', async () => {
+      await finalizeSwap(youtube, oldVideoId, newVideoId);
+    });
+
+    onEvent({ type: 'swap_complete', songKey, oldVideoId, newVideoId, playlistId });
+    return { record: store.getRecord(songKey) };
+  } catch (err) {
+    const updated = store.updateRecord(songKey, { status: 'failed', lastError: err.message });
+    onEvent({ type: 'swap_error', songKey, error: err, needsManualReview: Boolean(err.needsManualReview) });
+    const wrapped = new Error(`Swap failed for ${songKey} (status persisted, safe to re-run): ${err.message}`);
+    wrapped.cause = err;
+    wrapped.record = updated;
+    throw wrapped;
+  }
+}
+
+/**
+ * Rank a status by how far through the state machine it is.
+ * @param {string} status
+ * @returns {number}
+ */
+function stepIndex(status) {
+  const order = ['pending', 'failed', 'uploaded', 'located', 'inserted', 'removed', 'finalized'];
+  return order.indexOf(status);
+}