@dxos/plugin-youtube 0.8.3

package/src/operations/clear-synced-videos.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+
+import { Channel, Video } from '../types';
+
+import { ClearSyncedVideos } from './definitions';
+
+const handler: Operation.WithHandler<typeof ClearSyncedVideos> = ClearSyncedVideos.pipe(
+  Operation.withHandler(({ channel: channelRef }) =>
+    Effect.gen(function* () {
+      log('clearing youtube channel synced videos', { channel: channelRef.dxn.toString() });
+      const channel = (yield* Database.load(channelRef)) as Channel.YouTubeChannel;
+      const oldFeed = yield* Database.load(channel.feed as Ref.Ref<Feed.Feed>);
+
+      const videos = yield* Feed.runQuery(oldFeed, Filter.type(Video.YouTubeVideo));
+      log('removing synced videos', { count: videos.length });
+
+      const newFeed = Feed.make();
+      yield* Database.add(newFeed);
+      Obj.setParent(newFeed, channel);
+
+      Obj.change(channel, (mutable) => {
+        mutable.feed = Ref.make(newFeed);
+        delete mutable.lastSyncedAt;
+      });
+
+      if (videos.length > 0) {
+        yield* Feed.remove(oldFeed, videos);
+      }
+
+      for (const video of videos) {
+        yield* Database.remove(video);
+      }
+
+      yield* Database.remove(oldFeed);
+
+      log('replaced youtube channel feed', { removedVideos: videos.length });
+      return { removedVideos: videos.length };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/definitions.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Operation } from '@dxos/operation';
+import * as Schema from 'effect/Schema';
+
+import { Database, Feed, Ref } from '@dxos/echo';
+import { CredentialsService } from '@dxos/functions';
+
+import { Channel, Video } from '../types';
+
+export const Sync = Operation.make({
+  meta: {
+    key: 'dxos.org/function/youtube/sync',
+    name: 'Sync YouTube Channel',
+    description: 'Sync videos from a YouTube channel to the feed.',
+  },
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.YouTubeChannel).annotations({
+      description: 'Reference to the YouTube channel to sync videos from.',
+    }),
+    restrictedMode: Schema.Boolean.pipe(
+      Schema.annotations({
+        description:
+          'Use restricted mode to limit to max 20 videos. Reduces API calls. Useful for testing or quick syncs.',
+      }),
+      Schema.optional,
+    ),
+    includeTranscripts: Schema.Boolean.pipe(
+      Schema.annotations({
+        description:
+          'Whether to fetch transcripts: Data API when your account can manage the video, otherwise watch-page captions (browser uses a public CORS proxy for YouTube fetches).',
+      }),
+      Schema.optional,
+    ),
+  }),
+  output: Schema.Struct({
+    newVideos: Schema.Number,
+    channelTitle: Schema.String.pipe(Schema.optional),
+  }),
+  types: [Channel.YouTubeChannel, Video.YouTubeVideo],
+  services: [Database.Service, Feed.Service, CredentialsService],
+});
+
+export const ClearSyncedVideos = Operation.make({
+  meta: {
+    key: 'dxos.org/function/youtube/clear-synced-videos',
+    name: 'Clear Synced YouTube Videos',
+    description: 'Remove all synced videos from the channel by replacing its feed with a new empty feed.',
+  },
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.YouTubeChannel).annotations({
+      description: 'Reference to the YouTube channel whose synced videos should be cleared.',
+    }),
+  }),
+  output: Schema.Struct({
+    removedVideos: Schema.Number,
+  }),
+  types: [Channel.YouTubeChannel, Video.YouTubeVideo],
+  services: [Database.Service, Feed.Service],
+});

package/src/operations/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export { YouTube } from './apis';
+export * from './definitions';
+
+export const YouTubeHandlers = OperationHandlerSet.lazy(
+  () => import('./clear-synced-videos'),
+  () => import('./sync'),
+);

package/src/operations/services/google-credentials.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Database, type Ref } from '@dxos/echo';
+import { CredentialsService } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { type AccessToken } from '@dxos/types';
+
+import type * as Channel from '../../types/Channel';
+
+/**
+ * Creates the service interface from a cached token.
+ * Falls back to database credentials if no cached token is provided.
+ */
+const makeService = (cachedToken: string | undefined): Context.Tag.Service<GoogleCredentials> => ({
+  get: () =>
+    cachedToken
+      ? Effect.succeed(cachedToken)
+      : Effect.map(CredentialsService.getCredential({ service: 'google.com' }), (credential) => credential.apiKey!),
+});
+
+/**
+ * Loads access token from a ref if available.
+ */
+const loadAccessToken = (accessTokenRef: Ref.Ref<AccessToken.AccessToken> | undefined, label: string) =>
+  Effect.gen(function* () {
+    if (accessTokenRef) {
+      const accessToken = yield* Database.load(accessTokenRef);
+      if (accessToken?.token) {
+        log(`using ${label}-specific access token`, { note: accessToken.note });
+        return accessToken.token;
+      }
+    }
+    return undefined;
+  });
+
+/**
+ * Service for accessing Google API credentials.
+ * Provides the Google API token either from an object's access token or falls back to database credentials.
+ */
+// TODO(dmaretskyi): Remove this service.
+export class GoogleCredentials extends Context.Tag('GoogleCredentials')<
+  GoogleCredentials,
+  {
+    /** Returns the Google API token. */
+    get: () => Effect.Effect<string, never, CredentialsService>;
+  }
+>() {
+  /**
+   * Creates a credentials layer from a channel.
+   * Pre-loads the access token during layer construction.
+   */
+  static fromChannel = (channel: Channel.YouTubeChannel) =>
+    Layer.effect(GoogleCredentials, Effect.map(loadAccessToken(channel.accessToken, 'channel'), makeService));
+
+  /**
+   * Creates a credentials layer from a channel ref.
+   * Loads the channel and pre-loads the access token during layer construction.
+   */
+  static fromChannelRef = (channelRef: Ref.Ref<Channel.YouTubeChannel>) =>
+    Layer.effect(
+      GoogleCredentials,
+      Effect.flatMap(Database.load(channelRef), (channel) =>
+        Effect.map(loadAccessToken(channel.accessToken, 'channel'), makeService),
+      ),
+    );
+
+  /**
+   * Default layer that uses database credentials.
+   * Use this for operations that don't have an associated channel.
+   */
+  static default = Layer.succeed(GoogleCredentials, makeService(undefined));
+
+  /** Convenience accessor - returns the Google API token. */
+  static get = () => Effect.flatMap(GoogleCredentials, (service) => service.get());
+}

package/src/operations/services/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './google-credentials';

package/src/operations/sync.test.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import { describe, it } from '@effect/vitest';
+import * as Config from 'effect/Config';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { CredentialsService } from '@dxos/functions';
+
+import { YouTube } from './apis';
+import { GoogleCredentials } from './services/google-credentials';
+import { fetchTranscript } from './transcript';
+
+const TestLayer = Layer.mergeAll(
+  CredentialsService.layerConfig([
+    {
+      service: 'google.com',
+      apiKey: Config.redacted('GOOGLE_ACCESS_TOKEN'),
+    },
+  ]),
+  FetchHttpClient.layer,
+  GoogleCredentials.default,
+);
+
+/**
+ * To get a temporary access token:
+ * 1. Go to Google OAuth Playground: https://developers.google.com/oauthplayground/
+ * 2. Select YouTube Data API v3 (all scopes or readonly)
+ * 3. Authorize and get an access token
+ *
+ * export GOOGLE_ACCESS_TOKEN="xxx"
+ * pnpm vitest sync.test.ts
+ */
+describe.runIf(process.env.GOOGLE_ACCESS_TOKEN)('YouTube API', { timeout: 30_000 }, () => {
+  it.effect(
+    'get channel by handle',
+    Effect.fnUntraced(function* ({ expect }) {
+      const response = yield* YouTube.getChannelByHandle('Google');
+      console.log(JSON.stringify(response, null, 2));
+      expect(response.items.length).toBeGreaterThan(0);
+      expect(response.items[0].snippet?.title).toBeDefined();
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'get channel uploads',
+    Effect.fnUntraced(function* ({ expect }) {
+      const channelResponse = yield* YouTube.getChannelByHandle('Google');
+      const channel = channelResponse.items[0];
+      expect(channel).toBeDefined();
+
+      const uploadsPlaylistId = channel.contentDetails?.relatedPlaylists?.uploads;
+      expect(uploadsPlaylistId).toBeDefined();
+
+      const playlistResponse = yield* YouTube.listPlaylistItems(uploadsPlaylistId!, 5);
+      console.log('Playlist items:', JSON.stringify(playlistResponse.items.slice(0, 2), null, 2));
+      expect(playlistResponse.items.length).toBeGreaterThan(0);
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'get video details',
+    Effect.fnUntraced(function* ({ expect }) {
+      const channelResponse = yield* YouTube.getChannelByHandle('TED');
+      const channel = channelResponse.items[0];
+      expect(channel).toBeDefined();
+
+      const uploadsPlaylistId = channel.contentDetails?.relatedPlaylists?.uploads;
+      expect(uploadsPlaylistId).toBeDefined();
+
+      const playlistResponse = yield* YouTube.listPlaylistItems(uploadsPlaylistId!, 3);
+      const videoIds = playlistResponse.items
+        .map((item) => item.snippet?.resourceId?.videoId)
+        .filter((id): id is string => Boolean(id));
+
+      const videosResponse = yield* YouTube.getVideoDetails(videoIds);
+      console.log('Video details:', JSON.stringify(videosResponse.items[0], null, 2));
+      expect(videosResponse.items.length).toBeGreaterThan(0);
+      expect(videosResponse.items[0].contentDetails?.duration).toBeDefined();
+    }, Effect.provide(TestLayer)),
+  );
+});
+
+/**
+ * Transcripts: uses youtube-caption-extractor to scrape captions from the watch page.
+ */
+describe('YouTube Transcript', { timeout: 30_000 }, () => {
+  it.effect(
+    'fetch transcript for video',
+    Effect.fnUntraced(function* ({ expect }) {
+      const result = yield* fetchTranscript('dQw4w9WgXcQ');
+
+      if (result) {
+        console.log('Transcript segments:', result.segments.length);
+        console.log('Full text preview:', result.fullText.slice(0, 200));
+        expect(result.segments.length).toBeGreaterThan(0);
+        expect(result.fullText.length).toBeGreaterThan(0);
+      } else {
+        console.log('No transcript available for this video');
+      }
+    }),
+  );
+
+  it.effect(
+    'handles video without transcript gracefully',
+    Effect.fnUntraced(function* ({ expect }) {
+      const result = yield* fetchTranscript('nonexistent_video_id_12345');
+      expect(result).toBeUndefined();
+    }),
+  );
+});

package/src/operations/sync.ts

@@ -0,0 +1,309 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import * as Stream from 'effect/Stream';
+
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+
+import { Channel, Video } from '../types';
+
+import { YouTube } from './apis';
+import { Sync } from './definitions';
+import { GoogleCredentials } from './services/google-credentials';
+import { fetchTranscript } from './transcript';
+
+const handler: Operation.WithHandler<typeof Sync> = Sync.pipe(
+  Operation.withHandler(({ channel: channelRef, restrictedMode = false, includeTranscripts = true }) =>
+    Effect.gen(function* () {
+      log('syncing youtube channel', { channel: channelRef.dxn.toString(), restrictedMode, includeTranscripts });
+      const channel = yield* Database.load(channelRef);
+
+      const channelUrl =
+        (channel as Channel.YouTubeChannel).channelUrl ?? (channel as Channel.YouTubeChannel).channelId;
+      if (!channelUrl) {
+        return yield* Effect.fail(new Error('No channel URL or ID configured'));
+      }
+
+      const channelInfo = extractChannelInfo(channelUrl);
+      log('extracted channel info', channelInfo);
+
+      const { channelId, channelTitle, uploadsPlaylistId } = yield* getUploadsPlaylistId(channelInfo);
+      log('found channel', { channelId, channelTitle, uploadsPlaylistId });
+
+      Obj.change(channel as Channel.YouTubeChannel, (channelObj) => {
+        channelObj.channelId = channelId;
+        if (!channelObj.name) {
+          channelObj.name = channelTitle;
+        }
+      });
+
+      // Get the feed and query for existing videos.
+      const feed = yield* Database.load((channel as Channel.YouTubeChannel).feed as Ref.Ref<Feed.Feed>);
+      const existingVideos = yield* Feed.runQuery(feed, Filter.type(Video.YouTubeVideo));
+      const existingVideoIds = new Set(existingVideos.map((video: Video.YouTubeVideo) => video.videoId));
+      log('existing videos', { count: existingVideoIds.size });
+
+      const newVideosCount = yield* streamVideosToFeed(
+        uploadsPlaylistId,
+        feed,
+        existingVideoIds,
+        restrictedMode,
+        includeTranscripts,
+      );
+
+      Obj.change(channel as Channel.YouTubeChannel, (channelObj) => {
+        channelObj.lastSyncedAt = new Date().toISOString();
+      });
+
+      log('sync complete', { newVideos: newVideosCount, channelTitle });
+      return {
+        newVideos: newVideosCount,
+        channelTitle,
+      };
+    }).pipe(Effect.provide(Layer.mergeAll(FetchHttpClient.layer, GoogleCredentials.fromChannelRef(channelRef)))),
+  ),
+);
+
+const STREAMING_CONFIG = {
+  /** Videos per page from YouTube API. */
+  maxResults: 50,
+  /** Parallel transcript fetches. */
+  transcriptFetchConcurrency: 3,
+  /** In-flight video buffer. */
+  bufferSize: 10,
+  /** Videos per feed append. */
+  feedBatchSize: 10,
+  /** Max videos in restricted mode. */
+  restrictedMax: 20,
+} as const;
+
+/**
+ * Extracts channel ID from various YouTube URL formats.
+ */
+const extractChannelInfo = (
+  urlOrHandle: string,
+): { type: 'id'; value: string } | { type: 'handle'; value: string } | { type: 'url'; value: string } => {
+  const trimmed = urlOrHandle.trim();
+
+  if (trimmed.startsWith('@')) {
+    return { type: 'handle', value: trimmed.slice(1) };
+  }
+
+  if (trimmed.startsWith('UC') && trimmed.length === 24) {
+    return { type: 'id', value: trimmed };
+  }
+
+  try {
+    const url = new URL(trimmed);
+    const pathname = url.pathname;
+
+    if (pathname.startsWith('/channel/')) {
+      const channelId = pathname.split('/')[2];
+      if (channelId) {
+        return { type: 'id', value: channelId };
+      }
+    }
+
+    if (pathname.startsWith('/@')) {
+      return { type: 'handle', value: pathname.slice(2) };
+    }
+
+    if (pathname.startsWith('/c/') || pathname.startsWith('/user/')) {
+      const name = pathname.split('/')[2];
+      if (name) {
+        return { type: 'handle', value: name };
+      }
+    }
+  } catch {
+    if (/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+      return { type: 'handle', value: trimmed };
+    }
+  }
+
+  return { type: 'url', value: trimmed };
+};
+
+/**
+ * Gets the uploads playlist ID for a channel.
+ */
+const getUploadsPlaylistId = Effect.fn(function* (channelInfo: { type: string; value: string }) {
+  let channelResponse;
+
+  if (channelInfo.type === 'id') {
+    channelResponse = yield* YouTube.getChannel(channelInfo.value);
+  } else {
+    channelResponse = yield* YouTube.getChannelByHandle(channelInfo.value);
+  }
+
+  const channel = channelResponse.items[0];
+  if (!channel) {
+    return yield* Effect.fail(new Error(`Channel not found: ${channelInfo.value}`));
+  }
+
+  const uploadsPlaylistId = channel.contentDetails?.relatedPlaylists?.uploads;
+  if (!uploadsPlaylistId) {
+    return yield* Effect.fail(new Error(`No uploads playlist found for channel: ${channelInfo.value}`));
+  }
+
+  return {
+    channelId: channel.id,
+    channelTitle: channel.snippet?.title ?? '',
+    uploadsPlaylistId,
+  };
+});
+
+/**
+ * Fetches videos from an uploads playlist, returning them from newest to oldest.
+ */
+const fetchPlaylistVideos = (uploadsPlaylistId: string, maxVideos?: number) => {
+  let videoCount = 0;
+
+  return Stream.unfoldChunkEffect({ pageToken: Option.none<string>(), done: false }, (state) =>
+    Effect.gen(function* () {
+      if (state.done || (maxVideos && videoCount >= maxVideos)) {
+        return Option.none();
+      }
+
+      const response = yield* YouTube.listPlaylistItems(
+        uploadsPlaylistId,
+        STREAMING_CONFIG.maxResults,
+        Option.getOrUndefined(state.pageToken),
+      );
+
+      const videoIds = response.items
+        .map((item) => item.snippet?.resourceId?.videoId)
+        .filter((id): id is string => Boolean(id));
+
+      log('fetched playlist items', {
+        count: videoIds.length,
+        pageToken: Option.getOrUndefined(state.pageToken),
+        hasMore: Boolean(response.nextPageToken),
+      });
+
+      videoCount += videoIds.length;
+
+      const nextState = {
+        pageToken: Option.fromNullable(response.nextPageToken),
+        done: !response.nextPageToken || (maxVideos !== undefined && videoCount >= maxVideos),
+      };
+
+      return Option.some([Chunk.fromIterable(videoIds), nextState]);
+    }),
+  );
+};
+
+type TranscriptData = { segments: Video.TranscriptSegment[]; fullText: string };
+
+/**
+ * Maps YouTube API video item to YouTubeVideo data.
+ */
+const mapVideoData = (
+  item: YouTube.VideoItem,
+  transcript: TranscriptData | undefined,
+  includeTranscripts: boolean,
+): Omit<Video.YouTubeVideo, 'id' | '~@dxos/echo/Kind'> => {
+  const hasTranscript = Boolean(transcript?.fullText?.trim());
+  return {
+    title: item.snippet?.title ?? 'Untitled',
+    videoId: item.id,
+    description: item.snippet?.description,
+    url: `https://www.youtube.com/watch?v=${item.id}`,
+    thumbnailUrl:
+      item.snippet?.thumbnails?.high?.url ??
+      item.snippet?.thumbnails?.medium?.url ??
+      item.snippet?.thumbnails?.default?.url,
+    channelTitle: item.snippet?.channelTitle,
+    publishedAt: item.snippet?.publishedAt ?? new Date().toISOString(),
+    duration: item.contentDetails?.duration,
+    viewCount: item.statistics?.viewCount ? parseInt(item.statistics.viewCount, 10) : undefined,
+    likeCount: item.statistics?.likeCount ? parseInt(item.statistics.likeCount, 10) : undefined,
+    transcript: transcript && hasTranscript ? transcript.fullText : undefined,
+    transcriptSegments: transcript && hasTranscript ? transcript.segments : undefined,
+    transcriptFetched: includeTranscripts ? hasTranscript : false,
+  };
+};
+
+/**
+ * Stream videos with transcripts into a DXOS feed.
+ */
+const streamVideosToFeed = Effect.fn(function* (
+  uploadsPlaylistId: string,
+  feed: Feed.Feed,
+  existingVideoIds: Set<string>,
+  restricted: boolean,
+  includeTranscripts: boolean,
+) {
+  const count = yield* Function.pipe(
+    fetchPlaylistVideos(uploadsPlaylistId, restricted ? STREAMING_CONFIG.restrictedMax : undefined),
+    Stream.filter((videoId) => {
+      const isDuplicate = existingVideoIds.has(videoId);
+      if (isDuplicate) {
+        log('skipping duplicate video', { videoId });
+      }
+      return !isDuplicate;
+    }),
+    restricted ? Stream.take(STREAMING_CONFIG.restrictedMax) : Function.identity,
+    Stream.grouped(10),
+    Stream.flatMap(
+      (videoIdChunk) =>
+        Effect.gen(function* () {
+          const videoIds = Chunk.toArray(videoIdChunk);
+          log('fetching video details', { count: videoIds.length });
+
+          const response = yield* YouTube.getVideoDetails(videoIds);
+          return response.items;
+        }),
+      { concurrency: 1 },
+    ),
+    Stream.flatMap((items) => Stream.fromIterable(items)),
+    Stream.flatMap(
+      (item) =>
+        Effect.gen(function* () {
+          let transcript: TranscriptData | undefined;
+
+          if (includeTranscripts) {
+            log('fetching transcript', { videoId: item.id });
+            const result = yield* fetchTranscript(item.id);
+            if (result) {
+              transcript = result;
+              log('transcript fetched', { videoId: item.id, length: transcript.fullText.length });
+            } else {
+              log('no transcript available', { videoId: item.id });
+            }
+          }
+
+          return mapVideoData(item, transcript, includeTranscripts);
+        }),
+      {
+        concurrency: STREAMING_CONFIG.transcriptFetchConcurrency,
+        bufferSize: STREAMING_CONFIG.bufferSize,
+      },
+    ),
+    Stream.filter(Predicate.isNotNullable),
+    Stream.grouped(STREAMING_CONFIG.feedBatchSize),
+    Stream.mapEffect((batch) =>
+      Effect.gen(function* () {
+        const videos = Chunk.toArray(batch);
+        log('appending batch to feed', { count: videos.length });
+        const videoObjects = videos.map((video) => Obj.make(Video.YouTubeVideo, video));
+        yield* Feed.append(feed, videoObjects);
+        return videos.length;
+      }),
+    ),
+    Stream.runFold(0, (acc, batchCount) => acc + batchCount),
+  );
+
+  return count;
+});
+
+export default handler;

package/src/operations/transcript.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { log } from '@dxos/log';
+
+import type { TranscriptSegment } from '../types/Video';
+
+export type TranscriptResult = {
+  segments: TranscriptSegment[];
+  fullText: string;
+};
+
+/**
+ * Fetches captions for a YouTube video using youtube-caption-extractor.
+ * Works in both browser and Node/edge environments.
+ */
+export const fetchTranscript = (videoId: string, lang?: string): Effect.Effect<TranscriptResult | undefined> =>
+  Effect.tryPromise({
+    try: async () => {
+      const { getSubtitles } = await import('youtube-caption-extractor');
+      const subtitles = await getSubtitles({ videoID: videoId, lang: lang ?? 'en' });
+
+      if (!subtitles || subtitles.length === 0) {
+        return undefined;
+      }
+
+      const segments: TranscriptSegment[] = subtitles.map((sub) => ({
+        text: sub.text,
+        offset: parseFloat(sub.start),
+        duration: parseFloat(sub.dur),
+      }));
+
+      const fullText = segments.map((segment) => segment.text).join(' ');
+      return { segments, fullText };
+    },
+    catch: (error) => {
+      log('failed to fetch transcript', { videoId, error });
+      return undefined;
+    },
+  }).pipe(
+    Effect.catchAll(() => Effect.succeed(undefined)),
+    Effect.timeout('30 seconds'),
+    Effect.catchAll(() => Effect.succeed(undefined)),
+  );