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.
Try it
The admin screens over this API on a Worker, in sandbox mode.
Admin components
The React screens that drive these routes.
The pieces
| Piece | What it is |
|---|---|
| Store | Where rows live: createMemoryLibraryStore() or createD1LibraryStore(env.DB), or your own VideoLibraryStore. |
| Handler | createVideoLibraryHandler({ store, authorize, customFields }), the HTTP API. |
| Client | createLibraryClient({ baseUrl }), the typed caller the React components use. |
| Operations | importLibraryVideos, resyncLibrary, autofillVideo, recomputeStacks and friends, for scripts and cron jobs. |
Quick start on a Worker
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 });
},
};{
"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 deployhandle() 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.
| Method | Path | Access | Does |
|---|---|---|---|
| GET | /videos | public | A page of the library. Query below. |
| GET | /videos/:id | public | One video. Hidden ones only to admins. |
| GET | /stacks?keys=a,b | public | Members of each stacked playlist. |
| GET | /categories | public | Distinct categories, for filters. |
| GET | /fields | public | Your custom field declarations. |
| GET | /session | public | { admin }: whether this request passes authorize. |
| POST | /videos | admin | Add a video. 409 if it exists, 400 if the id or title is bad. |
| PATCH | /videos/:id | admin | Edit a video. Only the fields sent change. |
| DELETE | /videos/:id | admin | Remove a video and record an exclusion so imports skip it. |
| POST | /autofill | admin | Suggest form values from YouTube and your suggest hook. Writes nothing. |
| GET | /resync | admin | { videos, quotaCost, configured }, before running one. |
| POST | /resync | admin | Refresh view counts and availability. 501 without youtubeApiKey. |
| GET | /availability | admin | Videos YouTube no longer plays. |
| POST | /availability | admin | { videoId }: mark one available again. |
| POST | /import | admin | Bulk-load { videos: [...], overwriteEdited? }. |
| POST | /stacks/recompute | admin | Rebuild every stack from descriptions. |
| GET | /exclusions | admin | Videos an admin removed. |
| DELETE | /exclusions/:id | admin | Let a removed video be imported again. |
Listing query
| Param | |
|---|---|
q | Case-insensitive search over title, channel, description, tags and searchable custom fields. |
category | Exact category. |
availability | available, private, not_embeddable or removed. |
featured | true for top picks only. |
ids | Comma-separated allow-list, such as a user's favorites. Present but empty matches nothing. |
includeHidden | Admins only. Ignored for everyone else. |
sort | published (default), views, title, channel, category or updated. |
dir | desc (default) or asc. Empty values sort last either way. |
page, limit | 1-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
authorizeout and every admin route answers 403. The library is then a read-only public API. An unset option never means "open". bearerTokenAuth(token)acceptsAuthorization: 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>videosand<prefix>video_exclusions, so the library can share a database with your app. The prefix must be an identifier. librarySchemaSql(prefix)returns theCREATEstatements, for a migration file:librarySchemaSql().join(';\n') + ';'.- Written against D1's limits. Id lists bind as one JSON parameter expanded with
json_each, never asIN (?, ?, …), so a 500-id favorites list stays under D1's 100-parameter cap. Bulk writes go throughbatch()in groups of 50. - It needs only D1's
prepare().bind().all()shape (D1DatabaseLike), sonode:sqliteandbun:sqlitewrap 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 | |
|---|---|
videoId | The 11-character YouTube id and the primary key. |
title, channel, description | Text. A write that blanks the title keeps the stored one. |
publishedAt | ISO date or timestamp, '' when unknown. |
viewCount | Views, refreshed by resync. |
category, tags | One shelf, and free-form tags. |
featured | A top pick. The grid shows a badge. |
hidden | Out of public listings without being deleted. |
availability | available, private, not_embeddable or removed. |
stackKey, stackPosition | Its stacked playlist, if any. |
custom | Your custom fields. |
adminEdited | Set by any admin edit, so imports leave the row alone. |
updatedAt | Last write. |
publishedMs, searchText | Derived 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:
| Function | Does |
|---|---|
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, deleteLibraryVideo | What 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:
- The YouTube Data API, when
youtubeApiKeyis set: title, channel, publish date, views, description and tags. - oEmbed, when there is no key or the API failed: title and channel. It needs no key.
- Your
suggesthook, 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.
Video grid and list
Cards, a responsive grid, a sortable and groupable table, and stacked playlists for browsing a library of videos that open in the floating player.
Custom fields
Add your own columns to the video library, such as a speaker, a level or a slides link. They are validated, stored, searched and rendered without a schema change.