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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}