Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

feat(youtube): add the upload rules and the publishing API types

spacesdrive6fcf687dd2c9
diff --git a/backend/lib/youtubeUpload.ts b/backend/lib/youtubeUpload.ts
new file mode 100644
index 0000000..90638c8
--- /dev/null
+++ b/backend/lib/youtubeUpload.ts
@@ -0,0 +1,86 @@
+// the rules of a YouTube upload, pure so tests can check them and any runner can share them
+
+// Google wants every chunk but the last to be a multiple of 256 KiB and the same size; 8 MiB is two subrequests a chunk
+// (one Cloudinary range, one Google PUT), so a run on the Workers Free plan moves about 20 chunks
+export const CHUNK_BYTES = 8 * 1024 * 1024;
+// a failing job is tried this many times over about a day before it waits for a person
+export const MAX_UPLOAD_ATTEMPTS = 8;
+// a run holds a job this long; longer than one run, so a stopped run's job is free again soon after
+export const UPLOAD_LEASE_SECONDS = 10 * 60;
+// Google's daily allowance for the project: 100 video inserts, and 10,000 units for every other call
+export const UPLOADS_PER_DAY = 100;
+export const DEFAULT_UNITS_PER_DAY = 10_000;
+// videos.list and thumbnails.set cost these many units of the default bucket
+export const UNITS = { videosList: 1, thumbnailSet: 50 } as const;
+
+export const TITLE_MAX = 100;
+export const DESCRIPTION_MAX_BYTES = 5000;
+export const TAGS_MAX_CHARS = 500;
+// YouTube counts a vertical or square video of at most three minutes as a Short
+export const SHORT_MAX_SECONDS = 180;
+
+export interface ByteRange {
+ first: number;
+ last: number;
+}
+
+// the next chunk to send after `confirmed` bytes of `total`; null once everything is sent
+export function nextChunk(confirmed: number, total: number, chunk = CHUNK_BYTES): ByteRange | null {
+ if (confirmed >= total) return null;
+ return { first: confirmed, last: Math.min(confirmed + chunk, total) - 1 };
+}
+
+// Google's Range header names the last byte it holds, counted from zero: "bytes=0-524287" means 524,288 received
+export function confirmedFromRange(header: string | null): number {
+ const match = header?.match(/^bytes=0-(\d+)$/);
+ return match ? Number(match[1]) + 1 : 0;
+}
+
+export function isShort(width: number | null, height: number | null, durationSeconds: number | null): boolean {
+ if (width === null || height === null || durationSeconds === null) return false;
+ return height >= width && durationSeconds <= SHORT_MAX_SECONDS;
+}
+
+export interface UploadMetadata {
+ title: string;
+ description: string;
+ tags: string[];
+}
+
+// the first rule broken, in words a person can act on; YouTube refuses angle brackets in titles and descriptions
+export function metadataProblem({ title, description, tags }: UploadMetadata): string | null {
+ if (title.trim().length === 0) return 'Give the video a title.';
+ if ([...title].length > TITLE_MAX) return `The title can have at most ${TITLE_MAX} characters.`;
+ if (/[<>]/.test(title) || /[<>]/.test(description)) return 'YouTube does not accept < or > in a title or description.';
+ if (new TextEncoder().encode(description).length > DESCRIPTION_MAX_BYTES) return `The description can be at most ${DESCRIPTION_MAX_BYTES} bytes.`;
+ // YouTube counts a tag with a space as if it were quoted, two characters more
+ const tagChars = tags.reduce((sum, tag) => sum + tag.length + (tag.includes(' ') ? 2 : 0), 0) + Math.max(tags.length - 1, 0);
+ if (tagChars > TAGS_MAX_CHARS) return `The tags can have at most ${TAGS_MAX_CHARS} characters together.`;
+ return null;
+}
+
+// exponential, from a minute to about four hours, with jitter so jobs that failed together do not retry together
+export function retryDelayMs(attempts: number, random = Math.random): number {
+ const base = 60_000 * 2 ** Math.min(Math.max(attempts - 1, 0), 8);
+ return Math.round(base * (0.75 + random() * 0.5));
+}
+
+export type GoogleFailure = 'quota' | 'reconnect' | 'transient' | 'session_gone' | 'permanent';
+
+// what an error answer from Google means for the job
+export function classifyGoogleFailure(status: number, reason = ''): GoogleFailure {
+ if (reason === 'quotaExceeded' || reason === 'uploadLimitExceeded' || reason === 'dailyLimitExceeded') return 'quota';
+ if (reason === 'invalid_grant' || status === 401) return 'reconnect';
+ if (status === 404 || status === 410) return 'session_gone';
+ if (status === 408 || status === 429 || status >= 500) return 'transient';
+ return 'permanent';
+}
+
+// YouTube's quota resets at midnight Pacific time; a job that hit it waits until just after
+export function nextPacificMidnight(now: number = Date.now()): Date {
+ const pacific = new Intl.DateTimeFormat('en-US', { timeZone: 'America/Los_Angeles', hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' })
+ .formatToParts(now)
+ .reduce<Record<string, number>>((parts, part) => (part.type === 'literal' ? parts : { ...parts, [part.type]: Number(part.value) % 24 }), {});
+ const secondsIntoDay = pacific.hour * 3600 + pacific.minute * 60 + pacific.second;
+ return new Date(now + (86_400 - secondsIntoDay) * 1000 + 5 * 60_000);
+}
diff --git a/backend/tests/lib/youtubeUpload.test.ts b/backend/tests/lib/youtubeUpload.test.ts
new file mode 100644
index 0000000..f0d2ad1
--- /dev/null
+++ b/backend/tests/lib/youtubeUpload.test.ts
@@ -0,0 +1,59 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ CHUNK_BYTES, classifyGoogleFailure, confirmedFromRange, isShort, metadataProblem, nextChunk, nextPacificMidnight, retryDelayMs,
+} from '../../lib/youtubeUpload.ts';
+
+test('chunks are a whole multiple of 256 KiB except the last, and stop when everything is sent', () => {
+ assert.equal(CHUNK_BYTES % (256 * 1024), 0);
+ const total = CHUNK_BYTES * 2 + 1000;
+ assert.deepEqual(nextChunk(0, total), { first: 0, last: CHUNK_BYTES - 1 });
+ assert.deepEqual(nextChunk(CHUNK_BYTES * 2, total), { first: CHUNK_BYTES * 2, last: total - 1 });
+ assert.equal(nextChunk(total, total), null);
+});
+
+test('Google\'s Range header names the last byte it holds, counted from zero', () => {
+ assert.equal(confirmedFromRange('bytes=0-524287'), 524288);
+ assert.equal(confirmedFromRange(null), 0);
+ assert.equal(confirmedFromRange('bytes=10-20'), 0);
+});
+
+test('a vertical or square video of at most three minutes is a Short', () => {
+ assert.equal(isShort(1080, 1920, 59), true);
+ assert.equal(isShort(1080, 1080, 180), true);
+ assert.equal(isShort(1920, 1080, 30), false);
+ assert.equal(isShort(1080, 1920, 181), false);
+ assert.equal(isShort(null, 1920, 30), false);
+});
+
+test('metadata follows YouTube\'s limits and says what to fix', () => {
+ assert.equal(metadataProblem({ title: 'Launch day', description: 'Hello', tags: ['launch', 'news today'] }), null);
+ assert.match(metadataProblem({ title: ' ', description: '', tags: [] }) ?? '', /title/);
+ assert.match(metadataProblem({ title: 'x'.repeat(101), description: '', tags: [] }) ?? '', /100 characters/);
+ assert.match(metadataProblem({ title: 'a <b>', description: '', tags: [] }) ?? '', /< or >/);
+ assert.match(metadataProblem({ title: 'ok', description: 'é'.repeat(2501), tags: [] }) ?? '', /5000 bytes/);
+ assert.match(metadataProblem({ title: 'ok', description: '', tags: ['x'.repeat(498), 'ab'] }) ?? '', /500 characters/);
+});
+
+test('retries back off from about a minute to a few hours', () => {
+ assert.equal(retryDelayMs(1, () => 0.5), 60_000);
+ assert.equal(retryDelayMs(3, () => 0.5), 240_000);
+ assert.equal(retryDelayMs(30, () => 0.5), 60_000 * 256);
+ assert.ok(retryDelayMs(1, () => 0) < retryDelayMs(1, () => 0.99));
+});
+
+test('Google\'s answers sort into what the job does next', () => {
+ assert.equal(classifyGoogleFailure(403, 'quotaExceeded'), 'quota');
+ assert.equal(classifyGoogleFailure(400, 'invalid_grant'), 'reconnect');
+ assert.equal(classifyGoogleFailure(401), 'reconnect');
+ assert.equal(classifyGoogleFailure(404), 'session_gone');
+ assert.equal(classifyGoogleFailure(503), 'transient');
+ assert.equal(classifyGoogleFailure(429), 'transient');
+ assert.equal(classifyGoogleFailure(400, 'invalidTitle'), 'permanent');
+});
+
+test('the quota wait ends just after midnight Pacific time', () => {
+ // 07:00 UTC on 5 November is 23:00 Pacific on 4 November (PST, UTC-8)
+ const resume = nextPacificMidnight(Date.parse('2026-11-05T07:00:00Z'));
+ assert.equal(resume.toISOString(), '2026-11-05T08:05:00.000Z');
+});
diff --git a/shared/types/youtubePublishing.ts b/shared/types/youtubePublishing.ts
new file mode 100644
index 0000000..8ce26d1
--- /dev/null
+++ b/shared/types/youtubePublishing.ts
@@ -0,0 +1,101 @@
+// YouTube publishing: the Google sign-in per channel and the upload jobs, as the API and the Claude tools return them
+
+export type YouTubeConnectionStatus = 'active' | 'needs_reconnect';
+
+// never carries a token; the sealed Google tokens stay in the Worker
+export interface YouTubeConnectionSummary {
+ id: string;
+ channelId: string;
+ channelTitle: string;
+ // the analytics account for the same channel, when there is one
+ accountId: string | null;
+ status: YouTubeConnectionStatus;
+ scopes: string[];
+ createdAt: string;
+}
+
+export type YouTubePrivacy = 'private' | 'unlisted' | 'public';
+
+export type YouTubeUploadState =
+ | 'queued' | 'uploading' | 'processing' | 'finalizing' | 'done'
+ | 'waiting_quota' | 'needs_reconnect' | 'needs_review' | 'failed' | 'cancelled';
+
+export interface YouTubeUploadSummary {
+ id: string;
+ connectionId: string;
+ title: string;
+ description: string;
+ tags: string[];
+ categoryId: string;
+ privacy: YouTubePrivacy;
+ publishAt: string | null;
+ madeForKids: boolean;
+ syntheticMedia: boolean;
+ notifySubscribers: boolean;
+ isShort: boolean;
+ hasThumbnail: boolean;
+ state: YouTubeUploadState;
+ bytesConfirmed: number;
+ sourceBytes: number;
+ videoId: string | null;
+ attempts: number;
+ nextAttemptAt: string;
+ lastError: string | null;
+ createdAt: string;
+ updatedAt: string;
+}
+
+// body of POST /api/youtube/uploads; the video and thumbnail are files already in the person's media library
+export interface YouTubeUploadRequest {
+ connectionId: string;
+ mediaId: string;
+ thumbnailMediaId?: string | null;
+ title: string;
+ description?: string;
+ tags?: string[];
+ categoryId?: string;
+ privacy: YouTubePrivacy;
+ publishAt?: string | null;
+ madeForKids: boolean;
+ syntheticMedia?: boolean;
+ notifySubscribers?: boolean;
+ // the same key twice returns the first job instead of uploading the video again
+ clientRequestId?: string;
+}
+
+// body of PUT /api/youtube/uploads/:id; only a job that has not started uploading can change
+export type YouTubeUploadUpdateRequest = Partial<Pick<YouTubeUploadRequest,
+ 'title' | 'description' | 'tags' | 'categoryId' | 'privacy' | 'publishAt' | 'madeForKids' | 'syntheticMedia' | 'notifySubscribers'>>;
+
+export interface YouTubeConnectionListResponse {
+ success: true;
+ connections: YouTubeConnectionSummary[];
+ // false until the owner sets the Google OAuth client and TOKEN_ENCRYPTION_KEY
+ configured: boolean;
+}
+
+export interface YouTubeAuthUrlResponse {
+ success: true;
+ url: string;
+}
+
+export interface YouTubeConnectCompleteRequest {
+ code: string;
+ state: string;
+}
+
+export interface YouTubeConnectCompleteResponse {
+ success: true;
+ connection: YouTubeConnectionSummary;
+ outcome: 'connected' | 'reconnected';
+}
+
+export interface YouTubeUploadListResponse {
+ success: true;
+ uploads: YouTubeUploadSummary[];
+}
+
+export interface YouTubeUploadResponse {
+ success: true;
+ upload: YouTubeUploadSummary;
+}