Library admin API

A video library with an admin API that runs on Cloudflare Workers, Node, Bun or Deno. It covers storage in memory or D1, one HTTP handler, a typed client, stacks, resync and auto-fill.

extract-youtube/library is the server half of the video library. It stores videos and serves them to the grid through an HTTP API. It also gives admins routes to add, edit, auto-fill and remove videos and keep them in sync with YouTube.

It was ported from the admin routes behind debate-ai.com's video library. There, a dozen Next.js route files each re-checked the session. Here it is one framework-agnostic Request → Response handler. The entry imports no Node built-ins and no React, so it runs unchanged on Cloudflare Workers.

The pieces

PieceWhat it is
StoreWhere rows live: createMemoryLibraryStore() or createD1LibraryStore(env.DB), or your own VideoLibraryStore.
HandlercreateVideoLibraryHandler({ store, authorize, customFields }), the HTTP API.
ClientcreateLibraryClient({ baseUrl }), the typed caller the React components use.
OperationsimportLibraryVideos, resyncLibrary, autofillVideo, recomputeStacks and friends, for scripts and cron jobs.

Quick start on a Worker

src/index.ts
import { bearerTokenAuth, createD1LibraryStore, createVideoLibraryHandler } from 'extract-youtube/library';
import { fields } from './fields';

interface Env {
  DB: D1Database;
  ADMIN_TOKEN: string;
  YOUTUBE_API_KEY?: string;
}

export default {
  async fetch(request: Request, env: Env) {
    const store = createD1LibraryStore(env.DB);
    await store.ensureSchema(); // idempotent; cheap per cold start

    const library = createVideoLibraryHandler({
      store,
      basePath: '/api/library',
      authorize: bearerTokenAuth(env.ADMIN_TOKEN),
      customFields: fields,
      youtubeApiKey: env.YOUTUBE_API_KEY,
    });

    return (await library.handle(request)) ?? new Response('Not found', { status: 404 });
  },
};
wrangler.jsonc
{
  "name": "my-library",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [{ "binding": "DB", "database_name": "my-library", "database_id": "<id from wrangler d1 create>" }]
}
wrangler d1 create my-library
wrangler secret put ADMIN_TOKEN
wrangler secret put YOUTUBE_API_KEY   # optional: resync and richer auto-fill
wrangler deploy

handle() resolves null for paths outside basePath, so the library can share a Worker with other routes. fetch() answers 404 instead, for mounting it as a whole route.

Other runtimes

The handler takes a web-standard Request, so it mounts anywhere that has one:

// Next.js or vinext: app/api/library/[...path]/route.ts
const library = createVideoLibraryHandler({ store, authorize });
export const GET = library.fetch, POST = library.fetch, PATCH = library.fetch, DELETE = library.fetch;

// Hono
app.all('/api/library/*', (c) => library.fetch(c.req.raw));

// Bun
Bun.serve({ fetch: (request) => library.fetch(request) });

Routes

Paths are relative to basePath (default /api/library). Errors are always JSON { error } with a 4xx or 5xx status.

MethodPathAccessDoes
GET/videospublicA page of the library. Query below.
GET/videos/:idpublicOne video. Hidden ones only to admins.
GET/stacks?keys=a,bpublicMembers of each stacked playlist.
GET/categoriespublicDistinct categories, for filters.
GET/fieldspublicYour custom field declarations.
GET/sessionpublic{ admin }: whether this request passes authorize.
POST/videosadminAdd a video. 409 if it exists, 400 if the id or title is bad.
PATCH/videos/:idadminEdit a video. Only the fields sent change.
DELETE/videos/:idadminRemove a video and record an exclusion so imports skip it.
POST/autofilladminSuggest form values from YouTube and your suggest hook. Writes nothing.
GET/resyncadmin{ videos, quotaCost, configured }, before running one.
POST/resyncadminRefresh view counts and availability. 501 without youtubeApiKey.
GET/availabilityadminVideos YouTube no longer plays.
POST/availabilityadmin{ videoId }: mark one available again.
POST/importadminBulk-load { videos: [...], overwriteEdited? }.
POST/stacks/recomputeadminRebuild every stack from descriptions.
GET/exclusionsadminVideos an admin removed.
DELETE/exclusions/:idadminLet a removed video be imported again.

Listing query

Param
qCase-insensitive search over title, channel, description, tags and searchable custom fields.
categoryExact category.
availabilityavailable, private, not_embeddable or removed.
featuredtrue for top picks only.
idsComma-separated allow-list, such as a user's favorites. Present but empty matches nothing.
includeHiddenAdmins only. Ignored for everyone else.
sortpublished (default), views, title, channel, category or updated.
dirdesc (default) or asc. Empty values sort last either way.
page, limit1-based page; limit 25 by default, 100 at most. A page past the end returns the last page.

The answer is { videos, total, page, pageCount, limit }.

Admin access

authorize decides who may use the admin routes. It gets the Request and returns something truthy to allow it. A string is recorded as the acting admin, for example in the exclusion a delete writes. false, null or undefined means 403.

  • Leave authorize out and every admin route answers 403. The library is then a read-only public API. An unset option never means "open".
  • bearerTokenAuth(token) accepts Authorization: Bearer <token>, compared in constant time. An empty token refuses everything, so a missing secret cannot open the API.
  • Anything else is a function. Check your own session cookie, Cloudflare Access headers, or an API key table:
authorize: async (request) => {
  const user = await getSessionUser(request);
  return user?.role === 'admin' ? user.email : false;
},

() => true opens the API to everyone. Use it only for a throwaway in-memory sandbox, like the live demo when it runs with no secrets.

Storage

In memory

const store = createMemoryLibraryStore({ seed: videos, customFields: fields });

It lives as long as the process or Worker isolate. Good for tests, Storybook, demos and prototypes. The seed takes partial rows; every missing field gets its default.

Cloudflare D1

const store = createD1LibraryStore(env.DB, { tablePrefix: 'eyt_' });
await store.ensureSchema();
  • Two tables, <prefix>videos and <prefix>video_exclusions, so the library can share a database with your app. The prefix must be an identifier.
  • librarySchemaSql(prefix) returns the CREATE statements, for a migration file: librarySchemaSql().join(';\n') + ';'.
  • Written against D1's limits. Id lists bind as one JSON parameter expanded with json_each, never as IN (?, ?, …), so a 500-id favorites list stays under D1's 100-parameter cap. Bulk writes go through batch() in groups of 50.
  • It needs only D1's prepare().bind().all() shape (D1DatabaseLike), so node:sqlite and bun:sqlite wrap to it in a few lines. The package's own tests run it that way.

Your own

Implement VideoLibraryStore: list, get, getMany, all, getStacks, categories, insert, update, updateMany, remove, and four exclusion methods. applyLibraryQuery(rows, query) is the reference implementation of listing semantics, so an in-memory or KV-backed store can use it directly.

The data model

A LibraryVideo has these fields:

Field
videoIdThe 11-character YouTube id and the primary key.
title, channel, descriptionText. A write that blanks the title keeps the stored one.
publishedAtISO date or timestamp, '' when unknown.
viewCountViews, refreshed by resync.
category, tagsOne shelf, and free-form tags.
featuredA top pick. The grid shows a badge.
hiddenOut of public listings without being deleted.
availabilityavailable, private, not_embeddable or removed.
stackKey, stackPositionIts stacked playlist, if any.
customYour custom fields.
adminEditedSet by any admin edit, so imports leave the row alone.
updatedAtLast write.
publishedMs, searchTextDerived on every write, for sorting and search. Never sent by clients.

Writes are validated and coerced in one place (buildLibraryUpdate), whichever store is behind them: text is trimmed, numbers must be finite, tags are de-duplicated, and custom values are coerced by their declared type.

The client

import { createLibraryClient, LibraryApiError } from 'extract-youtube/library';

const client = createLibraryClient({
  baseUrl: '/api/library',
  headers: () => ({ authorization: `Bearer ${getToken()}` }), // called per request
});

const { videos, total } = await client.list({ q: 'python', sort: 'views' });
try {
  await client.create('dQw4w9WgXcQ', { title: 'Never Gonna Give You Up', custom: { speaker: 'Rick' } });
} catch (error) {
  if (error instanceof LibraryApiError && error.status === 409) console.log('Already in the library');
}

It has one method per route: list, get, stacks, categories, fields, session, create, update, remove, autofill, resyncStatus, resync, unavailable, markAvailable, importVideos, recomputeStacks, exclusions and removeExclusion. Any non-2xx answer throws a LibraryApiError with status and the API's message.

createLocalLibraryClient({ store, customFields }) runs the real handler in-process, with no server. The Storybook and the tests use it: same routes, same validation, same status codes. latencyMs adds a delay so loading states are visible.

Operations

The handler's admin routes are thin wrappers over functions you can call from a script, a cron trigger or a queue consumer:

FunctionDoes
importLibraryVideos(store, videos, { customFields, overwriteEdited })Inserts new ids, refreshes existing ones unless an admin edited them, and skips excluded ids. Then it recomputes stacks once. Returns counts: inserted, updated, skippedEdited, skippedExcluded, invalid.
resyncLibrary(store, { apiKey })One YouTube Data API pass for view counts and availability. It writes only rows that changed and costs one quota unit per 50 videos (resyncQuotaCost(n)).
autofillVideo({ videoId, title? }, { apiKey, suggest, customFields })Suggests form values. See below.
createLibraryVideo, updateLibraryVideo, deleteLibraryVideoWhat POST, PATCH and DELETE /videos run, stack upkeep included.
recomputeStacks(store)Rebuilds every stack. Returns how many rows moved.

A nightly resync on a Worker is a scheduled handler:

export default {
  fetch: (request, env) => handlerFor(env).fetch(request),
  async scheduled(_event, env) {
    await resyncLibrary(createD1LibraryStore(env.DB), { apiKey: env.YOUTUBE_API_KEY });
  },
};

Auto-fill

POST /autofill fills the add-video form from what YouTube knows, in this order:

  1. The YouTube Data API, when youtubeApiKey is set: title, channel, publish date, views, description and tags.
  2. oEmbed, when there is no key or the API failed: title and channel. It needs no key.
  3. Your suggest hook, for everything else, such as custom fields.

Text the admin already typed wins over YouTube's, so re-running auto-fill never undoes a correction. The answer lists which sources contributed and any warnings ("no API key, used oEmbed").

createVideoLibraryHandler({
  store,
  authorize,
  customFields: fields,
  // e.g. ask a model to fill custom fields from the title and description
  suggest: async ({ title, description, customFields }) => ({
    custom: await classify(title, description, customFields),
  }),
});

Availability

Resync sorts each video into available, private, not_embeddable or removed. The first two can be undone by the uploader and are worth keeping; removed is permanent. Public pages usually list with availability=available. GET /availability feeds the availability panel, where an admin marks a video available again or removes it.

YouTube metadata without the library

fetchYouTubeMetadata(ids, { apiKey }) batches ids 50 at a time through the Data API's videos.list and reports each video's snippet, statistics and status. fetchYouTubeOEmbed(videoId) needs no key. classifyAvailability(metadata) gives the availability value. They are exported for use on their own.

On this page