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 service for queueing, editing, cancelling and retrying

spacesdrivedbd62023d5b0
diff --git a/backend/services/youtubeUploadService.ts b/backend/services/youtubeUploadService.ts
new file mode 100644
index 0000000..b1dbe1c
--- /dev/null
+++ b/backend/services/youtubeUploadService.ts
@@ -0,0 +1,123 @@
+import { isShort, metadataProblem } from '../lib/youtubeUpload.ts';
+import { NotConfiguredError, NotFoundError, ValidationError } from '../lib/errors.ts';
+import { uploadSummary } from '../repositories/youtubeUploadRepository.ts';
+import type { StoredYouTubeUpload, UploadEdit, YouTubeUploadRepository } from '../repositories/youtubeUploadRepository.ts';
+import type { YouTubeConnectionRepository } from '../repositories/youtubeConnectionRepository.ts';
+import type { MediaAssetRepository } from '../repositories/mediaAssetRepository.ts';
+import type { AuditRepository } from '../repositories/auditRepository.ts';
+import type { AppConfig } from '../lib/config.ts';
+import type { YouTubeUploadRequest, YouTubeUploadState, YouTubeUploadSummary, YouTubeUploadUpdateRequest } from '../../shared/types/youtubePublishing.ts';
+
+export interface YouTubeUploadDeps {
+ uploads: YouTubeUploadRepository;
+ connections: YouTubeConnectionRepository;
+ media: MediaAssetRepository;
+ audit: AuditRepository;
+ config: AppConfig;
+}
+
+export interface YouTubeUploadService {
+ list(userId: string): Promise<YouTubeUploadSummary[]>;
+ get(userId: string, id: string): Promise<YouTubeUploadSummary>;
+ create(userId: string, request: YouTubeUploadRequest): Promise<{ upload: YouTubeUploadSummary; existing: boolean }>;
+ update(userId: string, id: string, edit: YouTubeUploadUpdateRequest): Promise<YouTubeUploadSummary>;
+ cancel(userId: string, id: string): Promise<YouTubeUploadSummary>;
+ retry(userId: string, id: string): Promise<YouTubeUploadSummary>;
+}
+
+// a job can be stopped until YouTube holds a finished video; after that the video is on the channel and is managed there
+const CANCELLABLE: YouTubeUploadState[] = ['queued', 'uploading', 'waiting_quota', 'needs_reconnect', 'failed', 'needs_review'];
+const RETRYABLE: YouTubeUploadState[] = ['failed', 'needs_review'];
+// YouTube takes custom thumbnails as JPEG or PNG up to 2 MB
+const THUMBNAIL_MAX_BYTES = 2 * 1024 * 1024;
+const NOT_FOUND = 'No YouTube upload with that id.';
+
+function contentTypeOf(format: string | null): string {
+ const known: Record<string, string> = { mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm', avi: 'video/x-msvideo', mkv: 'video/x-matroska' };
+ return (format && known[format.toLowerCase()]) || 'application/octet-stream';
+}
+
+export function createYouTubeUploadService({ uploads, connections, media, audit, config }: YouTubeUploadDeps): YouTubeUploadService {
+ async function findOwned(userId: string, id: string): Promise<StoredYouTubeUpload> {
+ const upload = await uploads.findForUser(id, userId);
+ if (!upload) throw new NotFoundError(NOT_FOUND);
+ return upload;
+ }
+
+ return {
+ list: async userId => (await uploads.listForUser(userId)).map(uploadSummary),
+ get: async (userId, id) => uploadSummary(await findOwned(userId, id)),
+
+ async create(userId, request) {
+ if (!config.youtubeOAuth) throw new NotConfiguredError('YouTube publishing is not set up on this server.');
+ const problem = metadataProblem({ title: request.title, description: request.description ?? '', tags: request.tags ?? [] });
+ if (problem) throw new ValidationError(problem);
+ const connection = await connections.findForUser(request.connectionId, userId);
+ if (!connection) throw new NotFoundError('No connected YouTube channel with that id. Connect YouTube on the Accounts page first.');
+ const video = await media.findForUser(request.mediaId, userId);
+ if (!video || video.resourceType !== 'video') throw new NotFoundError('No video with that id in your media.');
+ if (!video.bytes) throw new ValidationError('The size of this video is unknown, so it cannot be uploaded in parts. Upload it again.');
+ let thumbnailUrl: string | null = null;
+ if (request.thumbnailMediaId) {
+ const image = await media.findForUser(request.thumbnailMediaId, userId);
+ if (!image || image.resourceType !== 'image') throw new NotFoundError('No image with that id in your media for the thumbnail.');
+ if (image.bytes && image.bytes > THUMBNAIL_MAX_BYTES) throw new ValidationError('A YouTube thumbnail can be at most 2 MB.');
+ thumbnailUrl = image.url;
+ }
+ const created = await uploads.createForUser(userId, {
+ connectionId: connection.id,
+ sourceUrl: video.url,
+ sourceBytes: video.bytes,
+ contentType: contentTypeOf(video.format),
+ thumbnailUrl,
+ isShort: isShort(video.width, video.height, video.durationSeconds),
+ title: request.title,
+ description: request.description ?? '',
+ tags: request.tags ?? [],
+ categoryId: request.categoryId ?? '22',
+ privacy: request.privacy,
+ publishAt: request.publishAt ?? null,
+ madeForKids: request.madeForKids,
+ syntheticMedia: request.syntheticMedia ?? false,
+ notifySubscribers: request.notifySubscribers ?? true,
+ clientRequestId: request.clientRequestId ?? null,
+ });
+ if (!created.existing) {
+ await audit.recordForUser(userId, { action: 'youtube_upload.created', subjectType: 'youtube_upload', subjectId: created.upload.id, details: { privacy: request.privacy } });
+ }
+ return { upload: uploadSummary(created.upload), existing: created.existing };
+ },
+
+ async update(userId, id, edit) {
+ const current = await findOwned(userId, id);
+ const merged = { title: edit.title ?? current.title, description: edit.description ?? current.description, tags: edit.tags ?? current.tags };
+ const problem = metadataProblem(merged);
+ if (problem) throw new ValidationError(problem);
+ const privacy = edit.privacy ?? current.privacy;
+ const publishAt = edit.publishAt !== undefined ? edit.publishAt : current.publishAt;
+ if (publishAt && privacy !== 'private') throw new ValidationError('A scheduled video must be private until it publishes. Choose private, or remove the publish time.');
+ const updated = await uploads.editQueuedForUser(id, userId, edit as UploadEdit);
+ if (!updated) throw new ValidationError('This upload has started, so its details can no longer change. Change them on YouTube Studio once it is done.');
+ return uploadSummary(updated);
+ },
+
+ // an upload YouTube never finished leaves no video behind, so stopping it is clean
+ async cancel(userId, id) {
+ await findOwned(userId, id);
+ const cancelled = await uploads.setStateForUser(id, userId, CANCELLABLE, 'cancelled');
+ if (!cancelled) throw new ValidationError('This upload cannot be cancelled now: it is being worked on, or YouTube already has the video.');
+ await audit.recordForUser(userId, { action: 'youtube_upload.cancelled', subjectType: 'youtube_upload', subjectId: id });
+ return uploadSummary(cancelled);
+ },
+
+ async retry(userId, id) {
+ await findOwned(userId, id);
+ // a fresh session from byte 0: the old one is gone or ended in an error YouTube will not take back
+ const queued = await uploads.setStateForUser(id, userId, RETRYABLE, 'queued', {
+ attempts: 0, nextAttemptAt: new Date().toISOString(), lastError: null, sessionUri: null, bytesConfirmed: 0,
+ });
+ if (!queued) throw new ValidationError('Only a failed upload, or one waiting for your check, can be tried again.');
+ return uploadSummary(queued);
+ },
+ };
+}
diff --git a/backend/validators/youtubeValidators.ts b/backend/validators/youtubeValidators.ts
new file mode 100644
index 0000000..495d80c
--- /dev/null
+++ b/backend/validators/youtubeValidators.ts
@@ -0,0 +1,93 @@
+import { ValidationError } from '../lib/errors.ts';
+import { optionalBoolean, optionalString, requiredString } from './fields.ts';
+import type { Fields } from './fields.ts';
+import type {
+ YouTubeConnectCompleteRequest, YouTubePrivacy, YouTubeUploadRequest, YouTubeUploadUpdateRequest,
+} from '../../shared/types/youtubePublishing.ts';
+
+const PRIVACY: YouTubePrivacy[] = ['private', 'unlisted', 'public'];
+const MAX_ID = 100;
+const MAX_TAGS = 50;
+// YouTube's category ids are small numbers; 22 is People and Blogs, its own default
+const CATEGORY = /^\d{1,3}$/;
+
+function id(fields: Fields, name: string, what: string): string {
+ const value = requiredString(fields, name, `${name} is required: the ${what} id`).trim();
+ if (value.length > MAX_ID) throw new ValidationError(`${name} must be a ${what} id`);
+ return value;
+}
+
+function privacy(value: unknown): YouTubePrivacy {
+ if (PRIVACY.includes(value as YouTubePrivacy)) return value as YouTubePrivacy;
+ throw new ValidationError('privacy must be private, unlisted or public');
+}
+
+function tags(value: unknown): string[] {
+ if (value === undefined) return [];
+ if (!Array.isArray(value) || value.length > MAX_TAGS || value.some(tag => typeof tag !== 'string')) {
+ throw new ValidationError(`tags must be a list of at most ${MAX_TAGS} words or phrases`);
+ }
+ return value.map(tag => (tag as string).trim()).filter(Boolean);
+}
+
+// a publish time is an exact moment in the future; YouTube only schedules private videos
+function publishAt(value: unknown, chosenPrivacy: YouTubePrivacy | undefined): string | null {
+ if (value === undefined || value === null || value === '') return null;
+ const when = new Date(String(value));
+ if (Number.isNaN(when.getTime()) || when.getTime() <= Date.now()) throw new ValidationError('publishAt must be a date and time in the future');
+ if (chosenPrivacy !== undefined && chosenPrivacy !== 'private') throw new ValidationError('A scheduled video must be private until it publishes; choose private');
+ return when.toISOString();
+}
+
+function category(value: unknown): string | undefined {
+ if (value === undefined) return undefined;
+ if (typeof value !== 'string' || !CATEGORY.test(value)) throw new ValidationError('categoryId must be a YouTube category number, such as 22');
+ return value;
+}
+
+export function parseYouTubeUpload(body: Fields): YouTubeUploadRequest {
+ const chosen = privacy(body.privacy);
+ const madeForKids = optionalBoolean(body, 'madeForKids');
+ // the law asks every uploader to say whether a video is made for children, so there is no default
+ if (madeForKids === undefined) throw new ValidationError('Say whether the video is made for kids (madeForKids true or false)');
+ const clientRequestId = optionalString(body, 'clientRequestId')?.trim();
+ if (clientRequestId && clientRequestId.length > MAX_ID) throw new ValidationError('clientRequestId must be at most 100 characters');
+ return {
+ connectionId: id(body, 'connectionId', 'YouTube channel connection'),
+ mediaId: id(body, 'mediaId', 'video'),
+ thumbnailMediaId: optionalString(body, 'thumbnailMediaId')?.trim() || null,
+ title: requiredString(body, 'title', 'Give the video a title').trim(),
+ description: optionalString(body, 'description') ?? '',
+ tags: tags(body.tags),
+ categoryId: category(body.categoryId) ?? '22',
+ privacy: chosen,
+ publishAt: publishAt(body.publishAt, chosen),
+ madeForKids,
+ syntheticMedia: optionalBoolean(body, 'syntheticMedia') ?? false,
+ notifySubscribers: optionalBoolean(body, 'notifySubscribers') ?? true,
+ clientRequestId: clientRequestId || undefined,
+ };
+}
+
+export function parseYouTubeUploadUpdate(body: Fields): YouTubeUploadUpdateRequest {
+ const edit: YouTubeUploadUpdateRequest = {};
+ if (body.title !== undefined) edit.title = requiredString(body, 'title', 'Give the video a title').trim();
+ if (body.description !== undefined) edit.description = optionalString(body, 'description') ?? '';
+ if (body.tags !== undefined) edit.tags = tags(body.tags);
+ if (body.categoryId !== undefined) edit.categoryId = category(body.categoryId);
+ if (body.privacy !== undefined) edit.privacy = privacy(body.privacy);
+ if (body.publishAt !== undefined) edit.publishAt = publishAt(body.publishAt, edit.privacy);
+ for (const flag of ['madeForKids', 'syntheticMedia', 'notifySubscribers'] as const) {
+ const value = optionalBoolean(body, flag);
+ if (value !== undefined) edit[flag] = value;
+ }
+ if (Object.keys(edit).length === 0) throw new ValidationError('Name at least one detail to change, such as title or privacy');
+ return edit;
+}
+
+export function parseYouTubeComplete(body: Fields): YouTubeConnectCompleteRequest {
+ return {
+ code: requiredString(body, 'code', 'The Google sign-in code is missing. Start connecting again.'),
+ state: requiredString(body, 'state', 'The Google sign-in state is missing. Start connecting again.'),
+ };
+}