@mannyflussnpm/adapter-youtube 1.0.0

package/fixtures/activities.json

@@ -0,0 +1,32 @@
+[
+  {
+    "id": "act-001",
+    "snippet": {
+      "publishedAt": "2023-11-14T10:00:00.000Z",
+      "title": "How to Build a Data Vault in TypeScript",
+      "description": "A walkthrough of building a personal data vault from scratch",
+      "type": "upload",
+      "channelTitle": "Tech With Tim"
+    },
+    "contentDetails": {
+      "upload": {
+        "videoId": "dQw4w9WgXcQ"
+      }
+    }
+  },
+  {
+    "id": "act-002",
+    "snippet": {
+      "publishedAt": "2023-11-14T14:30:00.000Z",
+      "title": "The Future of Local-First Software",
+      "description": "Why local-first is the next big thing in software architecture",
+      "type": "upload",
+      "channelTitle": "Fireship"
+    },
+    "contentDetails": {
+      "upload": {
+        "videoId": "jNQXAC9IVRw"
+      }
+    }
+  }
+]

package/index.ts

@@ -0,0 +1,211 @@
+/**
+ * youtube — Google YouTube adapter via OAuth 2.0.
+ *
+ * Reads the user's YouTube watch history using the watch history playlist
+ * (playlist ID "HL"). Emits `video_watched` envelopes with video title,
+ * channel, URL, and watch date.
+ *
+ * Cursor format: JSON with `pageToken` (for pagination) and `maxDate`
+ * (ISO string). During initial backfill, pageToken drives pagination in
+ * chunks of ~500. Once backfill is complete, only new watches (after
+ * maxDate) are pulled.
+ *
+ * Prerequisites:
+ *   1. Create a Google Cloud project, enable YouTube Data API v3
+ *   2. Create OAuth 2.0 Desktop client ID
+ *   3. Save credentials to ~/.personal-data-vault/google-credentials.json
+ *   4. First run opens browser for consent
+ *
+ * Falls back to synthetic fixture when credentials are absent (conformance).
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { google, youtube_v3 } from "googleapis";
+import {
+  ENVELOPE_VERSION,
+  type Adapter,
+  type AdapterContext,
+  type Cursor,
+  type Envelope,
+  type PullResult,
+} from "@mannyflussnpm/spec";
+import { getAuthClient, SCOPES } from "@mannyflussnpm/adapter-google";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const FIXTURE_PATH = fileURLToPath(
+  new URL("./fixtures/activities.json", import.meta.url),
+);
+
+const PER_PAGE = 50;
+const MAX_PER_PULL = 500;
+
+// ---------------------------------------------------------------------------
+// Cursor helpers
+// ---------------------------------------------------------------------------
+
+interface YoutubeCursor {
+  pageToken: string | null;
+  maxDate: string; // ISO
+}
+
+function parseCursor(cursor: Cursor): YoutubeCursor {
+  if (!cursor) return { pageToken: null, maxDate: "1970-01-01T00:00:00.000Z" };
+  try {
+    return JSON.parse(cursor) as YoutubeCursor;
+  } catch {
+    return { pageToken: null, maxDate: cursor };
+  }
+}
+
+function encodeCursor(c: YoutubeCursor): string {
+  return JSON.stringify(c);
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+const adapter: Adapter = {
+  name: "youtube",
+
+  async pull(cursor: Cursor, _ctx: AdapterContext): Promise<PullResult> {
+    // --- Fixture mode (no credentials, or forced) ---
+    const useFixture =
+      process.env.PDV_FIXTURE_MODE === "1" ||
+      !existsSync(
+        process.env.GOOGLE_CREDENTIALS_PATH ??
+          `${process.env.HOME}/.personal-data-vault/google-credentials.json`,
+      );
+
+    if (useFixture) {
+        let raw: string;
+        try {
+          raw = readFileSync(FIXTURE_PATH, "utf8");
+        } catch {
+          return { events: [], cursor, hasMore: false };
+        }
+        const activities = JSON.parse(raw) as youtube_v3.Schema$Activity[];
+        const cur = parseCursor(cursor);
+        const since = new Date(cur.maxDate);
+        const events: Envelope[] = [];
+        let maxDate = since;
+
+        for (const act of activities) {
+          const ts = new Date(act.snippet?.publishedAt ?? 0);
+          if (ts <= since) continue;
+
+          const videoId = act.contentDetails?.upload?.videoId;
+          events.push({
+            v: ENVELOPE_VERSION,
+            ts: ts.toISOString(),
+            source: adapter.name,
+            type: "video_watched",
+            id: act.id!,
+            payload: {
+              title: act.snippet?.title ?? "",
+              channel: act.snippet?.channelTitle ?? "",
+              videoId,
+              url: videoId ? `https://youtube.com/watch?v=${videoId}` : null,
+            },
+          });
+
+          if (ts > maxDate) maxDate = ts;
+        }
+
+        return {
+          events,
+          cursor: events.length > 0
+            ? encodeCursor({ pageToken: null, maxDate: maxDate.toISOString() })
+            : cursor,
+          hasMore: false,
+        };
+    }
+
+    // --- Live mode: activities feed ---
+    const auth = await getAuthClient("youtube", SCOPES.youtube);
+    const youtube = google.youtube({ version: "v3", auth });
+
+    const cur = parseCursor(cursor);
+    const since = new Date(cur.maxDate);
+    const events: Envelope[] = [];
+    let maxDate = since;
+    let pageToken: string | undefined = cur.pageToken ?? undefined;
+
+    let capped = false;
+
+    do {
+      const res = await youtube.activities.list({
+        mine: true,
+        part: ["snippet", "contentDetails"],
+        maxResults: PER_PAGE,
+        pageToken,
+        publishedAfter:
+          !cur.pageToken && cur.maxDate !== "1970-01-01T00:00:00.000Z"
+            ? since.toISOString()
+            : undefined,
+      });
+
+      const items = res.data.items ?? [];
+      for (const item of items) {
+        if (events.length >= MAX_PER_PULL) {
+          capped = true;
+          break;
+        }
+
+        const ts = new Date(item.snippet?.publishedAt ?? 0);
+        if (!cur.pageToken && ts <= since) continue;
+
+        const videoId =
+          item.contentDetails?.upload?.videoId ??
+          item.contentDetails?.playlistItem?.resourceId?.videoId ??
+          item.contentDetails?.subscription?.resourceId?.channelId;
+
+        const activityType = item.snippet?.type ?? "unknown";
+        events.push({
+          v: ENVELOPE_VERSION,
+          ts: ts.toISOString(),
+          source: adapter.name,
+          type: activityType === "upload" ? "video_watched" : "youtube_activity",
+          id: item.id!,
+          payload: {
+            activityType,
+            title: item.snippet?.title ?? "",
+            channel: item.snippet?.channelTitle ?? "",
+            videoId,
+            url: videoId
+              ? `https://youtube.com/watch?v=${videoId}`
+              : null,
+          },
+        });
+
+        if (ts > maxDate) maxDate = ts;
+      }
+
+      if (capped) {
+        pageToken = res.data.nextPageToken ?? undefined;
+        break;
+      }
+
+      pageToken = res.data.nextPageToken ?? undefined;
+    } while (pageToken);
+
+    return {
+      events,
+      cursor:
+        events.length > 0 || pageToken
+          ? encodeCursor({
+              pageToken: pageToken ?? null,
+              maxDate: maxDate.toISOString(),
+            })
+          : cursor,
+      hasMore: !!pageToken,
+    };
+  },
+};
+
+export default adapter;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@mannyflussnpm/adapter-youtube",
+  "version": "1.0.0",
+  "description": "adapter for Personal Data Vault",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "pdv": {
+    "type": "adapter"
+  },
+  "peerDependencies": {
+    "@mannyflussnpm/spec": "^1.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@mannyflussnpm/adapter-google": "^1.0.0"
+  }
+}