@chronicle.app/youtube 0.3.0

package/dist/utils/YouTubeProxy.js

@@ -0,0 +1,138 @@
+import { ApiAuthError, ApiProxy } from '@chronicle.app/etl';
+import { TokenHelper } from '@chronicle.app/auth';
+export default class YouTubeProxy extends ApiProxy {
+    constructor(accessToken) {
+        super({
+            baseURL: 'https://www.googleapis.com/youtube/v3',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            pageDelayMs: 100,
+        });
+        if (accessToken) {
+            this.setAccessToken(accessToken);
+        }
+    }
+    async initialize() {
+        await this.ensureAuthenticated();
+    }
+    // Lazily resolves a token from the keychain the first time a request needs
+    // one; a token passed to the constructor short-circuits this.
+    async ensureAuthenticated() {
+        if (this.accessToken) {
+            return;
+        }
+        const token = await TokenHelper.getValidToken('youtube');
+        this.setAccessToken(token);
+    }
+    // Keep the actionable re-auth guidance the generic 401 mapping would lose.
+    mapError(error) {
+        const mapped = super.mapError(error);
+        if (mapped instanceof ApiAuthError) {
+            return new ApiAuthError('YouTube authentication failed. Please re-authenticate:\n' +
+                '  chronicle auth login youtube --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n\n' +
+                'Create OAuth credentials at: https://console.cloud.google.com/apis/credentials');
+        }
+        return mapped;
+    }
+    async get(path, params) {
+        await this.ensureAuthenticated();
+        return this.request({ url: path, method: 'GET', params });
+    }
+    /** Self channel (drives the @me agent) plus the likes playlist id. */
+    async getUser() {
+        const data = await this.get('/channels', {
+            part: 'snippet,contentDetails',
+            mine: true,
+        });
+        const channel = data.items?.[0];
+        if (!channel) {
+            throw new Error('YouTube API returned no channel for this account');
+        }
+        return channel;
+    }
+    /**
+     * Liked videos, newest first, from the account's likes playlist.
+     * snippet.publishedAt on a playlist item is when the video was liked.
+     */
+    async getLikes(options) {
+        return this.getPlaylistItems(options.likesPlaylistId, {
+            limit: options.limit,
+        });
+    }
+    /** Items of any playlist. snippet.publishedAt is when the item was added. */
+    async getPlaylistItems(playlistId, options = {}) {
+        return this.paginateCursor({
+            limit: options.limit,
+            fetchPage: async (cursor) => {
+                const data = await this.get('/playlistItems', {
+                    part: 'snippet',
+                    playlistId,
+                    maxResults: 50,
+                    ...(cursor && { pageToken: cursor }),
+                });
+                return { items: data.items ?? [], cursor: data.nextPageToken };
+            },
+        });
+    }
+    /** The account's own playlists (created playlists, not saved ones). */
+    async getPlaylists(options = {}) {
+        return this.paginateCursor({
+            limit: options.limit,
+            fetchPage: async (cursor) => {
+                const data = await this.get('/playlists', {
+                    part: 'snippet,contentDetails,status',
+                    mine: true,
+                    maxResults: 50,
+                    ...(cursor && { pageToken: cursor }),
+                });
+                return { items: data.items ?? [], cursor: data.nextPageToken };
+            },
+        });
+    }
+    /** Hydrate video details (duration, tags, canonical channel) in batches. */
+    async getVideoDetails(ids) {
+        let details = [];
+        for (let i = 0; i < ids.length; i += 50) {
+            const chunk = ids.slice(i, i + 50);
+            const data = await this.get('/videos', {
+                part: 'snippet,contentDetails',
+                id: chunk.join(','),
+                maxResults: 50,
+            });
+            details = details.concat(data.items ?? []);
+            await this.delay(100);
+        }
+        return details;
+    }
+    async getSubscriptions(options) {
+        return this.paginateCursor({
+            limit: options.limit,
+            fetchPage: async (cursor) => {
+                const data = await this.get('/subscriptions', {
+                    part: 'snippet',
+                    mine: true,
+                    maxResults: 50,
+                    ...(cursor && { pageToken: cursor }),
+                });
+                return { items: data.items ?? [], cursor: data.nextPageToken };
+            },
+        });
+    }
+    async getPlaylistItemCount(playlistId) {
+        const data = await this.get('/playlistItems', {
+            part: 'id',
+            playlistId,
+            maxResults: 1,
+        });
+        return data.pageInfo?.totalResults ?? 0;
+    }
+    async getSubscriptionsCount() {
+        const data = await this.get('/subscriptions', {
+            part: 'id',
+            mine: true,
+            maxResults: 1,
+        });
+        return data.pageInfo?.totalResults ?? 0;
+    }
+}

package/dist/utils/time.d.ts

@@ -0,0 +1,12 @@
+/**
+ * YouTube reports the same instant at different precisions on different
+ * surfaces: the Data API carries milliseconds where Takeout carries whole
+ * seconds. Every timestamp the plugin emits is truncated to the second — the
+ * shared precision — so same-key assertions from the two paths land on one
+ * instant instead of a millisecond-inverted occurrence range.
+ */
+export declare function ytTime(value: string | number | Date): Date;
+/** Takeout's videos.csv reports duration in milliseconds; the schema (like the
+ * Data API) carries ISO-8601 durations. */
+export declare function msToIsoDuration(ms: number): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.js

@@ -0,0 +1,30 @@
+/**
+ * YouTube reports the same instant at different precisions on different
+ * surfaces: the Data API carries milliseconds where Takeout carries whole
+ * seconds. Every timestamp the plugin emits is truncated to the second — the
+ * shared precision — so same-key assertions from the two paths land on one
+ * instant instead of a millisecond-inverted occurrence range.
+ */
+export function ytTime(value) {
+    const ms = new Date(value).getTime();
+    if (Number.isNaN(ms)) {
+        throw new TypeError(`Invalid YouTube timestamp: ${String(value)}`);
+    }
+    return new Date(Math.floor(ms / 1000) * 1000);
+}
+/** Takeout's videos.csv reports duration in milliseconds; the schema (like the
+ * Data API) carries ISO-8601 durations. */
+export function msToIsoDuration(ms) {
+    const total = Math.round(ms / 1000);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    let out = 'PT';
+    if (hours)
+        out += `${hours}H`;
+    if (minutes)
+        out += `${minutes}M`;
+    if (seconds || out === 'PT')
+        out += `${seconds}S`;
+    return out;
+}

package/dist/utils/urls.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical https URL builders shared by the API and Takeout paths. `url` is a
+ * cardinality-one property and mints a `{url}` identity keyset, so the two
+ * paths must emit byte-identical values — Takeout renders `http://` channel
+ * links and music.youtube.com watch links, which are never passed through.
+ */
+export declare function channelUrl(channelId: string): string;
+export declare function videoUrl(videoId: string): string;
+export declare function playlistUrl(playlistId: string): string;
+//# sourceMappingURL=urls.d.ts.map

package/dist/utils/urls.js

@@ -0,0 +1,15 @@
+/**
+ * Canonical https URL builders shared by the API and Takeout paths. `url` is a
+ * cardinality-one property and mints a `{url}` identity keyset, so the two
+ * paths must emit byte-identical values — Takeout renders `http://` channel
+ * links and music.youtube.com watch links, which are never passed through.
+ */
+export function channelUrl(channelId) {
+    return `https://www.youtube.com/channel/${channelId}`;
+}
+export function videoUrl(videoId) {
+    return `https://www.youtube.com/watch?v=${videoId}`;
+}
+export function playlistUrl(playlistId) {
+    return `https://www.youtube.com/playlist?list=${playlistId}`;
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@chronicle.app/youtube",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "youtube"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for extracting data from YouTube",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/youtube"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/auth": "0.3.0",
+    "axios": "^1.7.9",
+    "csv-parse": "^5.6.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "youtube": {
+        "strategies": {
+          "api": {
+            "delivery": "api",
+            "recordTypes": [
+              "likes",
+              "playlists",
+              "playlist-items",
+              "subscriptions",
+              "uploads"
+            ],
+            "default": true
+          },
+          "takeout": {
+            "delivery": "export",
+            "recordTypes": [
+              "watches",
+              "searches",
+              "subscriptions",
+              "playlists",
+              "playlist-items",
+              "uploads",
+              "comments"
+            ]
+          }
+        }
+      }
+    }
+  }
+}