@chronicle.app/youtube 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+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,58 @@
+# Chronicle YouTube Plugin
+
+Extract liked videos and channel subscriptions from YouTube via the Data API v3 with OAuth authentication.
+
+## Features
+
+- **Liked Videos**: Extract your liked videos (from the account's likes playlist, with like timestamps)
+- **Subscriptions**: Extract your channel subscriptions (with subscribe timestamps)
+- **Playlists**: Extract your own playlists and their videos (creation and item-add timestamps, privacy status)
+- **Uploads**: Extract videos published to your own channel
+- **OAuth Authentication**: Google OAuth 2.0 with offline refresh tokens
+
+Watch and search history are not exposed by the Data API (Google Takeout only) and are out of scope for this plugin.
+
+## Setup
+
+### 1. Create Google OAuth credentials
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create (or reuse) a project and enable the **YouTube Data API v3**
+3. Create an OAuth client ID (web application)
+4. Note your **Client ID** and **Client Secret**
+5. Add Chronicle's callback to the authorized redirect URIs
+
+### 2. Authenticate
+
+```bash
+chronicle auth login youtube --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+```
+
+This opens your browser for Google consent and stores the tokens (including the offline refresh token) in Chronicle's credential store. Access tokens expire after an hour and are refreshed automatically.
+
+### 3. Extract Data
+
+```bash
+# Liked videos (default extraction type)
+chronicle extract youtube --type likes
+
+# Subscriptions
+chronicle extract youtube --type subscriptions
+
+# Playlists and uploads
+chronicle extract youtube --type playlists
+chronicle extract youtube --type uploads
+```
+
+## Data Mapping
+
+- Liked video → `LikeAction` by the account owner (`@me`) on a `VideoObject` (title, description, duration, thumbnail, uploading channel as author)
+- Subscription → `FollowAction` on the channel as an `Agent`, keyed on the channel id so re-runs supersede
+- Playlist → `Collection` (with `visibility` from the privacy status), created via a `CreateAction` at the playlist's real creation time; each video in it → `AddAction` keyed on the playlist item id with the `Collection` as `targetCollection`
+- Upload → `PublishAction` with the account owner as agent and the `VideoObject` as result
+- Channels are `Agent`s keyed on their YouTube channel id
+
+Tests run the pipeline against a fake Data API served on 127.0.0.1 with a fake
+access token, and against a small synthetic Takeout folder in a temporary
+directory. They never call Google, read stored credentials, or read the host's
+data or accounts.

package/dist/auth/GoogleOAuthProvider.d.ts

@@ -0,0 +1,14 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+export declare class GoogleOAuthProvider extends OAuthProvider {
+    static providerId: string;
+    static authorizationUrl: string;
+    static tokenUrl: string;
+    static scopes: string[];
+    static requiresClientSecret: boolean;
+    static extraAuthParams: {
+        access_type: string;
+        prompt: string;
+        include_granted_scopes: string;
+    };
+}
+//# sourceMappingURL=GoogleOAuthProvider.d.ts.map

package/dist/auth/GoogleOAuthProvider.js

@@ -0,0 +1,15 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+export class GoogleOAuthProvider extends OAuthProvider {
+    static providerId = 'youtube';
+    static authorizationUrl = 'https://accounts.google.com/o/oauth2/v2/auth';
+    static tokenUrl = 'https://oauth2.googleapis.com/token';
+    static scopes = ['https://www.googleapis.com/auth/youtube.readonly'];
+    static requiresClientSecret = true;
+    // Without offline access + forced consent Google issues no refresh token,
+    // leaving the stored credential unable to outlive the first hour.
+    static extraAuthParams = {
+        access_type: 'offline',
+        prompt: 'consent',
+        include_granted_scopes: 'true',
+    };
+}

package/dist/connectors/YouTubeBaseExtractor.d.ts

@@ -0,0 +1,36 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import YouTubeTransformer from './YouTubeTransformer.js';
+import YouTubeProxy, { YouTubeSelfChannel } from '../utils/YouTubeProxy.js';
+export declare abstract class YouTubeBaseExtractor<T extends typeof YouTubeBaseExtractor> extends Extractor<T> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static defaultTransformer: typeof YouTubeTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    protected proxy: YouTubeProxy;
+    protected user?: YouTubeSelfChannel;
+    static hasValidCredentials(): Promise<boolean>;
+    setup(): Promise<void>;
+    protected createRecordWithUser(data: any, options: {
+        recordType: string;
+    }): Record;
+}
+//# sourceMappingURL=YouTubeBaseExtractor.d.ts.map

package/dist/connectors/YouTubeBaseExtractor.js

@@ -0,0 +1,40 @@
+import { Extractor } from '@chronicle.app/etl';
+import { TokenHelper } from '@chronicle.app/auth';
+import { z } from 'zod';
+import YouTubeTransformer from './YouTubeTransformer.js';
+import YouTubeProxy from '../utils/YouTubeProxy.js';
+export class YouTubeBaseExtractor extends Extractor {
+    static source = 'youtube';
+    static description = 'Base extractor for YouTube data';
+    static delivery = 'api';
+    static strategy = 'api';
+    static defaultTransformer = YouTubeTransformer;
+    static schema = Extractor.schema.extend({
+        accessToken: z
+            .string()
+            .optional()
+            .describe('OAuth access token for the YouTube Data API (auto-retrieved if not provided)'),
+    });
+    proxy;
+    user;
+    static async hasValidCredentials() {
+        try {
+            await TokenHelper.getValidToken('youtube');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async setup() {
+        const config = this.config;
+        this.proxy = new YouTubeProxy(config.accessToken);
+        this.user = await this.proxy.getUser();
+    }
+    createRecordWithUser(data, options) {
+        return this.createRecord(data, {
+            recordType: options.recordType,
+            user: this.user,
+        });
+    }
+}

package/dist/connectors/YouTubeLikesExtractor.d.ts

@@ -0,0 +1,17 @@
+import { Record } from '@chronicle.app/etl';
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+import { YouTubePlaylistItem, YouTubeVideo } from '../utils/YouTubeProxy.js';
+export interface YouTubeLikedVideo {
+    item: YouTubePlaylistItem;
+    video?: YouTubeVideo;
+}
+export declare class YouTubeLikesExtractor extends YouTubeBaseExtractor<typeof YouTubeLikesExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    private likesPlaylistId;
+    setup(): Promise<void>;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=YouTubeLikesExtractor.d.ts.map

package/dist/connectors/YouTubeLikesExtractor.js

@@ -0,0 +1,54 @@
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+export class YouTubeLikesExtractor extends YouTubeBaseExtractor {
+    static description = 'Liked videos';
+    static recordTypes = ['likes'];
+    static default = true;
+    likesPlaylistId;
+    async setup() {
+        await super.setup();
+        const likesPlaylistId = this.user?.contentDetails?.relatedPlaylists?.likes;
+        if (!likesPlaylistId) {
+            throw new Error('YouTube API did not expose a likes playlist for this account');
+        }
+        this.likesPlaylistId = likesPlaylistId;
+    }
+    async *extract() {
+        const { since, until } = this.config;
+        // The likes playlist is newest-first, so a `since` bound also caps how far
+        // we need to paginate; without one we fetch to the configured limit.
+        let items = await this.proxy.getLikes({
+            likesPlaylistId: this.likesPlaylistId,
+            limit: since ? undefined : (this.getEffectiveLimit() ?? undefined),
+        });
+        items = items.filter(item => {
+            const likedAt = new Date(item.snippet.publishedAt);
+            if (since && likedAt <= since)
+                return false;
+            if (until && likedAt > until)
+                return false;
+            return true;
+        });
+        const limit = this.getEffectiveLimit();
+        if (limit !== null) {
+            items = items.slice(0, limit);
+        }
+        const details = await this.proxy.getVideoDetails(items.map(item => item.snippet.resourceId.videoId));
+        const detailsById = new Map(details.map(video => [video.id, video]));
+        this.logger.info(`Retrieved ${items.length} liked videos from YouTube`);
+        for (const item of items) {
+            const liked = {
+                item,
+                video: detailsById.get(item.snippet.resourceId.videoId),
+            };
+            yield this.createRecordWithUser(liked, { recordType: 'likes' });
+        }
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getPlaylistItemCount(this.likesPlaylistId);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/YouTubePlaylistsExtractor.d.ts

@@ -0,0 +1,16 @@
+import { Record } from '@chronicle.app/etl';
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+import { YouTubePlaylist, YouTubePlaylistItem, YouTubeVideo } from '../utils/YouTubeProxy.js';
+export interface YouTubePlaylistItemRecord {
+    playlist: YouTubePlaylist;
+    item: YouTubePlaylistItem;
+    video?: YouTubeVideo;
+}
+export declare class YouTubePlaylistsExtractor extends YouTubeBaseExtractor<typeof YouTubePlaylistsExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static temporality: "snapshot";
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=YouTubePlaylistsExtractor.d.ts.map

package/dist/connectors/YouTubePlaylistsExtractor.js

@@ -0,0 +1,44 @@
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+export class YouTubePlaylistsExtractor extends YouTubeBaseExtractor {
+    static description = 'Your playlists and their videos';
+    static recordTypes = ['playlists', 'playlist-items'];
+    // Re-running re-reports every playlist and its current membership, so
+    // sightings belong at read time and removed items depart via completeness.
+    static temporality = 'snapshot';
+    async *extract() {
+        const playlists = await this.proxy.getPlaylists();
+        this.logger.info(`Retrieved ${playlists.length} playlists from YouTube`);
+        let recordCount = 0;
+        for (const playlist of playlists) {
+            if (this.shouldStopExtracting(recordCount))
+                break;
+            yield this.createRecordWithUser(playlist, { recordType: 'playlists' });
+            recordCount++;
+            const items = await this.proxy.getPlaylistItems(playlist.id);
+            const details = await this.proxy.getVideoDetails(items.map(item => item.snippet.resourceId.videoId));
+            const detailsById = new Map(details.map(video => [video.id, video]));
+            for (const item of items) {
+                if (this.shouldStopExtracting(recordCount))
+                    break;
+                const data = {
+                    playlist,
+                    item,
+                    video: detailsById.get(item.snippet.resourceId.videoId),
+                };
+                yield this.createRecordWithUser(data, {
+                    recordType: 'playlist-items',
+                });
+                recordCount++;
+            }
+        }
+    }
+    async determineCount() {
+        try {
+            const playlists = await this.proxy.getPlaylists();
+            return playlists.reduce((sum, playlist) => sum + 1 + (playlist.contentDetails?.itemCount ?? 0), 0);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/YouTubeSubscriptionsExtractor.d.ts

@@ -0,0 +1,10 @@
+import { Record } from '@chronicle.app/etl';
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+export declare class YouTubeSubscriptionsExtractor extends YouTubeBaseExtractor<typeof YouTubeSubscriptionsExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static temporality: "snapshot";
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=YouTubeSubscriptionsExtractor.d.ts.map

package/dist/connectors/YouTubeSubscriptionsExtractor.js

@@ -0,0 +1,27 @@
+import { YouTubeBaseExtractor } from './YouTubeBaseExtractor.js';
+export class YouTubeSubscriptionsExtractor extends YouTubeBaseExtractor {
+    static description = 'Channel subscriptions';
+    static recordTypes = ['subscriptions'];
+    // Re-running re-reports the full current subscription list with each
+    // channel's latest title/avatar, so sightings belong at read time.
+    static temporality = 'snapshot';
+    async *extract() {
+        const subscriptions = await this.proxy.getSubscriptions({
+            limit: this.getEffectiveLimit() ?? undefined,
+        });
+        this.logger.info(`Retrieved ${subscriptions.length} subscriptions from YouTube`);
+        for (const subscription of subscriptions) {
+            yield this.createRecordWithUser(subscription, {
+                recordType: 'subscriptions',
+            });
+        }
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getSubscriptionsCount();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/YouTubeTakeoutExtractor.d.ts

@@ -0,0 +1,92 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import YouTubeTakeoutTransformer from './YouTubeTakeoutTransformer.js';
+export interface TakeoutSelfChannel {
+    id: string;
+    title?: string;
+}
+export interface TakeoutWatchRecord {
+    videoId: string;
+    title?: string;
+    titleUrl?: string;
+    channelId?: string;
+    channelName?: string;
+    time: string;
+}
+export interface TakeoutSearchRecord {
+    query: string;
+    time: string;
+}
+export interface TakeoutSubscriptionRecord {
+    channelId: string;
+    channelTitle?: string;
+}
+export interface TakeoutPlaylistRecord {
+    playlistId: string;
+    title: string;
+    createdAt: string;
+    visibility?: string;
+}
+export interface TakeoutPlaylistItemRecord {
+    playlistId: string;
+    playlistTitle: string;
+    videoId: string;
+    addedAt: string;
+}
+export interface TakeoutUploadRecord {
+    videoId: string;
+    title?: string;
+    description?: string;
+    durationMs?: string;
+    publishedAt: string;
+}
+export interface TakeoutCommentRecord {
+    commentId: string;
+    videoId: string;
+    rawText: string;
+    createdAt: string;
+}
+export declare class YouTubeTakeoutExtractor extends Extractor<typeof YouTubeTakeoutExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "export";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static temporality: "snapshot";
+    static defaultTransformer: typeof YouTubeTakeoutTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        input?: string | undefined;
+    }, {
+        limit?: number | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        input?: string | undefined;
+    }>;
+    private archiveAsOf;
+    private selfChannel;
+    private inputPath;
+    private fileExists;
+    setup(): Promise<void>;
+    protected asOfTime(): Date;
+    private inRange;
+    /** `[playlist title, csv path]` for each per-playlist membership file. */
+    private playlistItemFiles;
+    extract(): AsyncGenerator<Record>;
+    private extractWatches;
+    private extractSearches;
+    private extractSubscriptions;
+    private extractPlaylists;
+    private extractUploads;
+    private extractComments;
+}
+//# sourceMappingURL=YouTubeTakeoutExtractor.d.ts.map