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): serve the publishing routes and run uploads from the five minute cron

spacesdrive25f84d3e3155
diff --git a/backend/container.ts b/backend/container.ts
index fb4c370..116690d 100644
--- a/backend/container.ts
+++ b/backend/container.ts
@@ -7,6 +7,12 @@ import { createEmailQuotaRepository } from './repositories/emailQuotaRepository.
import { createYouTubeQuotaRepository } from './repositories/youtubeQuotaRepository.ts';
import { createYouTubeQuotaService } from './services/youtubeQuotaService.ts';
import { createMediaAssetRepository } from './repositories/mediaAssetRepository.ts';
+import { createYouTubeConnectionRepository } from './repositories/youtubeConnectionRepository.ts';
+import { createYouTubeUploadRepository } from './repositories/youtubeUploadRepository.ts';
+import { createYouTubeQuotaLedgerRepository } from './repositories/youtubeQuotaLedgerRepository.ts';
+import { createYouTubeConnectService } from './services/youtubeConnectService.ts';
+import { createYouTubeUploadService } from './services/youtubeUploadService.ts';
+import { createYouTubeUploadRunner } from './services/youtubeUploadRunner.ts';
import { createMediaService } from './services/mediaService.ts';
import { createAuditRepository } from './repositories/auditRepository.ts';
import { createAutomationRuleRepository } from './repositories/automationRuleRepository.ts';
@@ -64,6 +70,9 @@ import type { RetentionService } from './services/retentionService.ts';
import type { McpAccessService, McpPrincipal } from './services/mcpAccessService.ts';
import type { McpService } from './services/mcpService.ts';
import type { MediaService } from './services/mediaService.ts';
+import type { YouTubeConnectService } from './services/youtubeConnectService.ts';
+import type { YouTubeUploadService } from './services/youtubeUploadService.ts';
+import type { YouTubeUploadRunner } from './services/youtubeUploadRunner.ts';
import type { AppConfig } from './lib/config.ts';
import type { RequestContext } from './types/context.ts';
import type { Redis, SupabaseClient } from './types/app.ts';
@@ -87,6 +96,9 @@ export interface Services {
overview: OverviewService;
settings: SettingsService;
media: MediaService;
+ youtubeConnect: YouTubeConnectService;
+ youtubeUploads: YouTubeUploadService;
+ youtubeRunner: YouTubeUploadRunner;
instagramConnect: InstagramConnectService;
authEmail: AuthEmailService;
automations: AutomationService;
@@ -119,6 +131,10 @@ export function createServices(clients: Clients, config: AppConfig, context: Req
const mcpTokens = createMcpAccessTokenRepository(clients.supabase);
const mcpGrants = createMcpClientGrantRepository(clients.supabase);
const scheduledPublisher = createScheduledPublisher({ accounts, posts, context });
+ const media = createMediaAssetRepository(clients.supabase);
+ const youtubeConnections = createYouTubeConnectionRepository(clients.supabase);
+ const youtubeUploadRows = createYouTubeUploadRepository(clients.supabase);
+ const youtubeConnect = createYouTubeConnectService({ connections: youtubeConnections, uploads: youtubeUploadRows, accounts, audit, config, context });
// counters on the fail-fast client the rate limits use: without Redis nothing is metered
const youtubeQuota = createYouTubeQuotaService({ quota: createYouTubeQuotaRepository(clients.rateLimitRedis) });
const services: Services = {
@@ -132,7 +148,10 @@ export function createServices(clients: Clients, config: AppConfig, context: Req
trackedContent: createTrackedContentService({ tracked, config, context, youtubeQuota }),
overview: createOverviewService({ accounts, tracked, cache, config, youtubeQuota }),
settings: createSettingsService({ settings, config }),
- media: createMediaService({ media: createMediaAssetRepository(clients.supabase), audit, config, context }),
+ media: createMediaService({ media, audit, config, context }),
+ youtubeConnect,
+ youtubeUploads: createYouTubeUploadService({ uploads: youtubeUploadRows, connections: youtubeConnections, media, audit, config }),
+ youtubeRunner: createYouTubeUploadRunner({ uploads: youtubeUploadRows, connections: youtubeConnections, connect: youtubeConnect, ledger: createYouTubeQuotaLedgerRepository(clients.supabase), context }),
instagramConnect: createInstagramConnectService({ accounts, audit, config, context }),
authEmail: createAuthEmailService({ quota: createEmailQuotaRepository(clients.rateLimitRedis), config, context }),
automations: createAutomationService({ accounts, rules, comments, followups, publicReplies, automationAccounts, audit, automation, context }),
diff --git a/backend/controllers/mediaController.ts b/backend/controllers/mediaController.ts
new file mode 100644
index 0000000..471da1b
--- /dev/null
+++ b/backend/controllers/mediaController.ts
@@ -0,0 +1,14 @@
+import { controller, servicesFor } from './http.ts';
+import { jsonBody } from '../middleware/validate.ts';
+import { parseMediaRegistration } from '../validators/mediaValidators.ts';
+import type { MediaListResponse, MediaResponse } from '../../shared/types/media.ts';
+
+export const listMedia = controller.createHandlers(async c => {
+ return c.json({ success: true, media: await servicesFor(c).media.list(c.get('userId')) } satisfies MediaListResponse);
+});
+
+// the composer uploads to Cloudinary from the browser, then adds the file to the person's library here
+export const registerMedia = controller.createHandlers(jsonBody(parseMediaRegistration), async c => {
+ const media = await servicesFor(c).media.registerUpload(c.get('userId'), c.req.valid('json'));
+ return c.json({ success: true, media } satisfies MediaResponse, 201);
+});
diff --git a/backend/controllers/youtubeController.ts b/backend/controllers/youtubeController.ts
new file mode 100644
index 0000000..5508201
--- /dev/null
+++ b/backend/controllers/youtubeController.ts
@@ -0,0 +1,73 @@
+import { controller, pathParam, servicesFor } from './http.ts';
+import { jsonBody, queryParams } from '../middleware/validate.ts';
+import { requestLogger } from '../middleware/requestContext.ts';
+import { parseYouTubeCallback, parseYouTubeComplete, parseYouTubeUpload, parseYouTubeUploadUpdate } from '../validators/youtubeValidators.ts';
+import { errorFields } from '../lib/logger.ts';
+import type { SuccessResponse } from '../../shared/types/domain.ts';
+import type {
+ YouTubeAuthUrlResponse, YouTubeConnectCompleteResponse, YouTubeConnectionListResponse, YouTubeUploadListResponse, YouTubeUploadResponse,
+} from '../../shared/types/youtubePublishing.ts';
+
+// protected: the signed state carries the user id to the public callback
+export const getYouTubeAuthUrl = controller.createHandlers(async c => {
+ const url = await servicesFor(c).youtubeConnect.authorizationUrl(c.get('userId'));
+ return c.json({ success: true, url } satisfies YouTubeAuthUrlResponse);
+});
+
+// public: Google sends the browser here. The state proves the sign-in came from this app but not who opened the link,
+// so the code goes back to the app in the fragment and the signed-in person finishes through the complete route
+export const handleYouTubeCallback = controller.createHandlers(queryParams(parseYouTubeCallback), async c => {
+ const { code, state, error } = c.req.valid('query');
+ const connect = servicesFor(c).youtubeConnect;
+ if (!connect.configured()) return c.text('YouTube publishing is not set up on this server.', 503);
+ const backToAccounts = (query: string) => c.redirect(`${connect.accountsPageUrl()}?${query}`);
+ if (error || !code || !state) return backToAccounts(`yt_error=${encodeURIComponent(error || 'cancelled')}`);
+ try {
+ if (!await connect.stateIsValid(state)) return backToAccounts('yt_error=invalid_state');
+ } catch (err) {
+ requestLogger(c).error('youtube callback failed', errorFields(err));
+ return backToAccounts('yt_error=invalid_state');
+ }
+ return c.redirect(`${connect.accountsPageUrl()}#yt_code=${encodeURIComponent(code)}&yt_state=${encodeURIComponent(state)}`);
+});
+
+// protected: connects the channel only when the sign-in was started by the person now signed in
+export const completeYouTubeConnection = controller.createHandlers(jsonBody(parseYouTubeComplete), async c => {
+ const { code, state } = c.req.valid('json');
+ const { connection, outcome } = await servicesFor(c).youtubeConnect.completeForUser(c.get('userId'), code, state);
+ return c.json({ success: true, connection, outcome } satisfies YouTubeConnectCompleteResponse);
+});
+
+export const listYouTubeConnections = controller.createHandlers(async c => {
+ const connect = servicesFor(c).youtubeConnect;
+ return c.json({ success: true, connections: await connect.list(c.get('userId')), configured: connect.configured() } satisfies YouTubeConnectionListResponse);
+});
+
+export const deleteYouTubeConnection = controller.createHandlers(async c => {
+ await servicesFor(c).youtubeConnect.disconnect(c.get('userId'), pathParam(c, 'id'));
+ return c.json({ success: true } satisfies SuccessResponse);
+});
+
+export const listYouTubeUploads = controller.createHandlers(async c => {
+ return c.json({ success: true, uploads: await servicesFor(c).youtubeUploads.list(c.get('userId')) } satisfies YouTubeUploadListResponse);
+});
+
+export const createYouTubeUpload = controller.createHandlers(jsonBody(parseYouTubeUpload), async c => {
+ const { upload, existing } = await servicesFor(c).youtubeUploads.create(c.get('userId'), c.req.valid('json'));
+ return c.json({ success: true, upload } satisfies YouTubeUploadResponse, existing ? 200 : 201);
+});
+
+export const updateYouTubeUpload = controller.createHandlers(jsonBody(parseYouTubeUploadUpdate), async c => {
+ const upload = await servicesFor(c).youtubeUploads.update(c.get('userId'), pathParam(c, 'id'), c.req.valid('json'));
+ return c.json({ success: true, upload } satisfies YouTubeUploadResponse);
+});
+
+export const cancelYouTubeUpload = controller.createHandlers(async c => {
+ const upload = await servicesFor(c).youtubeUploads.cancel(c.get('userId'), pathParam(c, 'id'));
+ return c.json({ success: true, upload } satisfies YouTubeUploadResponse);
+});
+
+export const retryYouTubeUpload = controller.createHandlers(async c => {
+ const upload = await servicesFor(c).youtubeUploads.retry(c.get('userId'), pathParam(c, 'id'));
+ return c.json({ success: true, upload } satisfies YouTubeUploadResponse);
+});
diff --git a/backend/jobs/scheduled.ts b/backend/jobs/scheduled.ts
index 60ab947..afa0991 100644
--- a/backend/jobs/scheduled.ts
+++ b/backend/jobs/scheduled.ts
@@ -15,6 +15,10 @@ export const DAILY_CRON = '0 0 * * *';
// due posts are published on the quarter hour, as before; the other five minute runs reconcile the reply queue
const PUBLISH_EVERY_MINUTES = 15;
+// minutes 5, 20, 35 and 50 belong to YouTube uploads, four runs an hour
+const YOUTUBE_MINUTE = 5;
+// a YouTube run stops starting chunks with this much of its 14 minutes left, so it never runs into the deadline
+const YOUTUBE_RUN_MS = 12 * 60 * 1000;
// a dispatch stops starting sends well before the next minute's run, so runs rarely overlap; when they do, the claim's
// row locks keep them apart
const DISPATCH_TIME_MS = 50 * 1000;
@@ -32,16 +36,19 @@ function cronContext(cron: string): RequestContext {
return { requestId, signal: AbortSignal.timeout(CRON_DEADLINE_MS), log: createLogger({ requestId, cron }) };
}
-// dispatch sends due replies, follow-ups and public replies; publish sends due posts; reconcile expires, checks lost replies and reports
-// the queue's health; daily refreshes tokens and removes old data
-export type CronPlan = 'dispatch' | 'publish' | 'reconcile' | 'daily' | 'none';
+// dispatch sends due replies, follow-ups and public replies; publish sends due posts; youtube moves one YouTube upload;
+// reconcile expires, checks lost replies and reports the queue's health; daily refreshes tokens and removes old data
+export type CronPlan = 'dispatch' | 'publish' | 'youtube' | 'reconcile' | 'daily' | 'none';
// which work a trigger firing at scheduledTime carries
export function cronPlan(cron: string, scheduledTime: number): CronPlan {
if (cron === EVERY_MINUTE_CRON) return 'dispatch';
if (cron === DAILY_CRON) return 'daily';
if (cron !== EVERY_FIVE_MINUTES_CRON) return 'none';
- return new Date(scheduledTime).getUTCMinutes() % PUBLISH_EVERY_MINUTES === 0 ? 'publish' : 'reconcile';
+ const minute = new Date(scheduledTime).getUTCMinutes() % PUBLISH_EVERY_MINUTES;
+ // of each quarter hour's three runs: the first publishes, the second uploads to YouTube, the third reconciles
+ if (minute === 0) return 'publish';
+ return minute === YOUTUBE_MINUTE ? 'youtube' : 'reconcile';
}
// private replies first, since Instagram allows them only for 7 days and a public reply often points to them, then
@@ -89,6 +96,9 @@ export async function runScheduledJob(cron: string, env: Env, scheduledTime = Da
} else if (plan === 'publish') {
const run = await services.scheduledPublisher.publishDue();
context.log.info('scheduled publish run', { processed: run.processed, failed: run.errors.length });
+ } else if (plan === 'youtube') {
+ const run = await services.youtubeRunner.run({ subrequests: FREE_PLAN_SUBREQUESTS, timeBudgetMs: YOUTUBE_RUN_MS });
+ if (run.jobId) context.log.info('youtube upload run', { jobId: run.jobId, state: run.state, chunks: run.chunks, subrequests: run.subrequests });
} else if (plan === 'reconcile') {
await services.automationReconciler.run();
} else if (plan === 'daily') {
diff --git a/backend/routes/index.ts b/backend/routes/index.ts
index 4d7c852..0827158 100644
--- a/backend/routes/index.ts
+++ b/backend/routes/index.ts
@@ -6,6 +6,8 @@ import analyticsRoutes from './analyticsRoutes.ts';
import instagramAuthRoutes from './instagramAuthRoutes.ts';
import instagramWebhookRoutes from './instagramWebhookRoutes.ts';
import mcpRoutes from './mcpRoutes.ts';
+import mediaRoutes from './mediaRoutes.ts';
+import youtubeRoutes from './youtubeRoutes.ts';
import overviewRoutes from './overviewRoutes.ts';
import publishingRoutes from './publishingRoutes.ts';
import scheduledPostRoutes from './scheduledPostRoutes.ts';
@@ -13,6 +15,7 @@ import settingsRoutes from './settingsRoutes.ts';
import trackedContentRoutes from './trackedContentRoutes.ts';
import { getHealth, getReadiness } from '../controllers/healthController.ts';
import { handleInstagramCallback } from '../controllers/instagramAuthController.ts';
+import { handleYouTubeCallback } from '../controllers/youtubeController.ts';
import { rateLimit, clientIp } from '../middleware/rateLimit.ts';
import { RATE_LIMIT_RULES } from '../lib/rateLimit/rules.ts';
import type { AppEnv } from '../types/app.ts';
@@ -23,6 +26,7 @@ export const publicRoutes = new Hono<AppEnv>();
publicRoutes.get('/health', ...getHealth);
publicRoutes.get('/health/ready', ...getReadiness);
publicRoutes.get('/auth/instagram/callback', rateLimit(RATE_LIMIT_RULES.oauth, clientIp), ...handleInstagramCallback);
+publicRoutes.get('/auth/youtube/callback', rateLimit(RATE_LIMIT_RULES.oauth, clientIp), ...handleYouTubeCallback);
publicRoutes.route('/', authHookRoutes);
publicRoutes.route('/', instagramWebhookRoutes);
@@ -30,7 +34,7 @@ publicRoutes.route('/', instagramWebhookRoutes);
export const protectedRoutes = new Hono<AppEnv>();
for (const routes of [
accountRoutes, analyticsRoutes, publishingRoutes, scheduledPostRoutes, trackedContentRoutes,
- overviewRoutes, settingsRoutes, instagramAuthRoutes, automationRoutes, mcpRoutes,
+ overviewRoutes, settingsRoutes, instagramAuthRoutes, automationRoutes, mcpRoutes, mediaRoutes, youtubeRoutes,
]) {
protectedRoutes.route('/', routes);
}
diff --git a/backend/routes/mediaRoutes.ts b/backend/routes/mediaRoutes.ts
new file mode 100644
index 0000000..d76d427
--- /dev/null
+++ b/backend/routes/mediaRoutes.ts
@@ -0,0 +1,11 @@
+import { Hono } from 'hono';
+import { listMedia, registerMedia } from '../controllers/mediaController.ts';
+import type { AppEnv } from '../types/app.ts';
+
+// each person's media library on the instance's Cloudinary account
+const router = new Hono<AppEnv>();
+
+router.get('/media', ...listMedia);
+router.post('/media', ...registerMedia);
+
+export default router;
diff --git a/backend/routes/youtubeRoutes.ts b/backend/routes/youtubeRoutes.ts
new file mode 100644
index 0000000..2b2260f
--- /dev/null
+++ b/backend/routes/youtubeRoutes.ts
@@ -0,0 +1,21 @@
+import { Hono } from 'hono';
+import {
+ cancelYouTubeUpload, completeYouTubeConnection, createYouTubeUpload, deleteYouTubeConnection, getYouTubeAuthUrl,
+ listYouTubeConnections, listYouTubeUploads, retryYouTubeUpload, updateYouTubeUpload,
+} from '../controllers/youtubeController.ts';
+import type { AppEnv } from '../types/app.ts';
+
+// YouTube publishing; the public callback is in routes/index.ts
+const router = new Hono<AppEnv>();
+
+router.get('/auth/youtube/url', ...getYouTubeAuthUrl);
+router.post('/auth/youtube/complete', ...completeYouTubeConnection);
+router.get('/youtube/connections', ...listYouTubeConnections);
+router.delete('/youtube/connections/:id', ...deleteYouTubeConnection);
+router.get('/youtube/uploads', ...listYouTubeUploads);
+router.post('/youtube/uploads', ...createYouTubeUpload);
+router.put('/youtube/uploads/:id', ...updateYouTubeUpload);
+router.post('/youtube/uploads/:id/cancel', ...cancelYouTubeUpload);
+router.post('/youtube/uploads/:id/retry', ...retryYouTubeUpload);
+
+export default router;
diff --git a/backend/services/cloudinary/cloudinaryApi.ts b/backend/services/cloudinary/cloudinaryApi.ts
index 52fc9bc..d66a60e 100644
--- a/backend/services/cloudinary/cloudinaryApi.ts
+++ b/backend/services/cloudinary/cloudinaryApi.ts
@@ -98,3 +98,19 @@ export async function fetchWholeFile(fileUrl: string, maxBytes: number, signal?:
if (file.byteLength > maxBytes) throw new UpstreamError(`The file is larger than ${Math.round(maxBytes / 1024 / 1024)} MB.`);
return file;
}
+
+// the stored size of a file, from Cloudinary's own answer; null size means the file is not there
+export async function fileSize(fileUrl: string, signal?: AbortSignal): Promise<number> {
+ const url = new URL(fileUrl);
+ if (!isCloudinaryFile(url)) throw new UpstreamError('The file is not stored on Cloudinary.');
+ let response: Response;
+ try {
+ response = await fetch(url, { method: 'HEAD', signal });
+ } catch (err) {
+ if (isAbortError(err)) throw new UpstreamTimeoutError('Cloudinary', err);
+ throw new UpstreamError(`Cloudinary could not be reached (${(err as Error).message})`, { reason: 'unreachable', cause: err });
+ }
+ const size = Number(response.headers.get('Content-Length'));
+ if (!response.ok || !Number.isFinite(size) || size <= 0) throw new UpstreamError(`Cloudinary does not have this file (status ${response.status})`, { status: response.status });
+ return size;
+}
diff --git a/backend/services/mediaService.ts b/backend/services/mediaService.ts
index 2974377..fa1536d 100644
--- a/backend/services/mediaService.ts
+++ b/backend/services/mediaService.ts
@@ -1,5 +1,6 @@
-import { destroyFile, uploadFromUrl } from './cloudinary/cloudinaryApi.ts';
-import { NotConfiguredError, NotFoundError, UpstreamError, isUniqueViolation } from '../lib/errors.ts';
+import { destroyFile, fileSize, uploadFromUrl } from './cloudinary/cloudinaryApi.ts';
+import { NotConfiguredError, NotFoundError, UpstreamError, ValidationError, isUniqueViolation } from '../lib/errors.ts';
+import type { MediaRegistration } from '../validators/mediaValidators.ts';
import type { MediaResourceType } from './cloudinary/cloudinaryApi.ts';
import type { MediaAssetRepository, StoredMediaAsset } from '../repositories/mediaAssetRepository.ts';
import type { AuditRepository } from '../repositories/auditRepository.ts';
@@ -28,6 +29,8 @@ export interface MediaRemoval {
export interface MediaService {
list(userId: string): Promise<MediaAsset[]>;
importFromUrl(userId: string, request: MediaImport): Promise<MediaAsset>;
+ // a file the browser already uploaded to the instance's Cloudinary account, added to the person's library
+ registerUpload(userId: string, upload: MediaRegistration): Promise<MediaAsset>;
updateLabel(userId: string, id: string, label: string): Promise<MediaAsset>;
remove(userId: string, id: string): Promise<MediaRemoval>;
canDeleteFiles(): boolean;
@@ -82,6 +85,28 @@ export function createMediaService({ media, audit, config, context }: MediaDeps)
return publicView(saved);
},
+ async registerUpload(userId, upload) {
+ if (!config.cloudinary) throw new NotConfiguredError('Cloudinary is not set up on this server.');
+ const url = new URL(upload.url);
+ // only a file on this instance's own cloud, at the address Cloudinary gives the id it names
+ const ownPath = `/${config.cloudinary.cloudName}/${upload.resourceType}/upload/`;
+ if (url.hostname !== 'res.cloudinary.com' || !url.pathname.startsWith(ownPath) || !decodeURIComponent(url.pathname).includes(`/${upload.publicId}`)) {
+ throw new ValidationError('The file is not on this server\'s Cloudinary account. Upload it from the Publish page.');
+ }
+ // the size decides every chunk boundary, so it is measured, not taken from the browser
+ const bytes = await fileSize(upload.url, signal);
+ const record = { ...upload, bytes };
+ try {
+ const saved = await media.createForUser(userId, record);
+ await audit.recordForUser(userId, { action: 'media_asset.imported', subjectType: 'media_asset', subjectId: saved.id, details: { resourceType: upload.resourceType } });
+ return publicView(saved);
+ } catch (err) {
+ const existing = isUniqueViolation(err) ? await media.findByPublicIdForUser(upload.publicId, userId) : null;
+ if (!existing) throw err;
+ return publicView(existing);
+ }
+ },
+
async updateLabel(userId, id, label) {
const updated = await media.updateLabelForUser(id, userId, label);
if (!updated) throw new NotFoundError(NOT_FOUND);
diff --git a/backend/services/youtubeConnectService.ts b/backend/services/youtubeConnectService.ts
index a73d263..640f186 100644
--- a/backend/services/youtubeConnectService.ts
+++ b/backend/services/youtubeConnectService.ts
@@ -56,7 +56,7 @@ export function createYouTubeConnectService({ connections, uploads, accounts, au
return {
configured: () => config.youtubeOAuth !== null,
accountsPageUrl: () => oauth().accountsPageUrl,
- authorizationUrl: userId => authorizationUrl(oauth(), userId),
+ authorizationUrl: async userId => authorizationUrl(oauth(), userId),
stateIsValid: async state => (await verifyOAuthState(state, oauth().clientSecret)) !== null,
async completeForUser(userId, code, state) {
diff --git a/backend/tests/jobs/scheduled.test.ts b/backend/tests/jobs/scheduled.test.ts
index 9c37e7d..e3bd4b3 100644
--- a/backend/tests/jobs/scheduled.test.ts
+++ b/backend/tests/jobs/scheduled.test.ts
@@ -11,12 +11,14 @@ test('the every minute trigger dispatches due replies and follow-ups at every mi
for (const time of ['12:00', '12:01', '12:15', '23:59']) assert.equal(cronPlan(EVERY_MINUTE_CRON, at(time)), 'dispatch');
});
-test('the five minute trigger publishes on the quarter hour and reconciles the reply queue on every other run', () => {
+test('the five minute trigger publishes on the quarter hour, uploads to YouTube five minutes later and reconciles on the third run', () => {
assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:00')), 'publish');
assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:15')), 'publish');
assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:45')), 'publish');
- assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:05')), 'reconcile');
- assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:50')), 'reconcile');
+ assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:05')), 'youtube');
+ assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:50')), 'youtube');
+ assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:10')), 'reconcile');
+ assert.equal(cronPlan(EVERY_FIVE_MINUTES_CRON, at('12:55')), 'reconcile');
});
test('the daily trigger runs the upkeep and an unknown cron runs nothing', () => {
diff --git a/backend/tests/routes/youtubeRoutes.test.ts b/backend/tests/routes/youtubeRoutes.test.ts
new file mode 100644
index 0000000..e3fc2e1
--- /dev/null
+++ b/backend/tests/routes/youtubeRoutes.test.ts
@@ -0,0 +1,33 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { handleYouTubeCallback } from '../../controllers/youtubeController.ts';
+import { createOAuthState } from '../../lib/oauthState.ts';
+import { fakeSupabase } from '../fixtures/fakeSupabase.ts';
+import { mountWithContext } from '../fixtures/routeHarness.ts';
+import type { Env } from '../../types/env.ts';
+
+const ENV: Partial<Env> = {
+ GOOGLE_CLIENT_ID: 'client', GOOGLE_CLIENT_SECRET: 'google-secret', TOKEN_ENCRYPTION_KEY: 'k'.repeat(48),
+ BACKEND_URL: 'https://api.example.com', FRONTEND_URL: 'https://app.example.com',
+};
+
+function app() {
+ return mountWithContext(server => server.get('/auth/youtube/callback', ...handleYouTubeCallback), { supabase: fakeSupabase(), redis: null, rateLimitRedis: null });
+}
+
+test('a signed callback hands the code back to the app in the fragment, never in a query a server or referrer sees', async () => {
+ const state = await createOAuthState('user-1', 'google-secret');
+ const response = await app().request(`/auth/youtube/callback?code=CODE&state=${encodeURIComponent(state)}`, {}, ENV);
+ assert.equal(response.status, 302);
+ const location = response.headers.get('Location') ?? '';
+ assert.ok(location.startsWith('https://app.example.com/accounts#yt_code=CODE&yt_state='));
+});
+
+test('a changed state, a cancelled sign-in or an unconfigured server never reach the app with a code', async () => {
+ const changed = await app().request('/auth/youtube/callback?code=CODE&state=abc.def', {}, ENV);
+ assert.equal(changed.headers.get('Location'), 'https://app.example.com/accounts?yt_error=invalid_state');
+ const cancelled = await app().request('/auth/youtube/callback?error=access_denied', {}, ENV);
+ assert.equal(cancelled.headers.get('Location'), 'https://app.example.com/accounts?yt_error=access_denied');
+ const unconfigured = await app().request('/auth/youtube/callback?code=CODE&state=x', {}, {});
+ assert.equal(unconfigured.status, 503);
+});
diff --git a/backend/tests/services/youtubeConnectService.test.ts b/backend/tests/services/youtubeConnectService.test.ts
new file mode 100644
index 0000000..30972c0
--- /dev/null
+++ b/backend/tests/services/youtubeConnectService.test.ts
@@ -0,0 +1,102 @@
+import { test, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createYouTubeConnectService } from '../../services/youtubeConnectService.ts';
+import { createOAuthState } from '../../lib/oauthState.ts';
+import { decryptToken, encryptToken } from '../../lib/tokenCrypto.ts';
+import { ForbiddenError, NotConfiguredError, ValidationError } from '../../lib/errors.ts';
+import { readConfig } from '../../lib/config.ts';
+import { createLogger } from '../../lib/logger.ts';
+import type { NewYouTubeConnection, StoredYouTubeConnection, YouTubeConnectionRepository, YouTubeConnectionTokens } from '../../repositories/youtubeConnectionRepository.ts';
+import type { YouTubeUploadRepository } from '../../repositories/youtubeUploadRepository.ts';
+import type { AccountRepository } from '../../repositories/accountRepository.ts';
+import type { AuditRepository } from '../../repositories/auditRepository.ts';
+import type { Env } from '../../types/env.ts';
+
+const SECRET = 'k'.repeat(48);
+const ENV = { GOOGLE_CLIENT_ID: 'client', GOOGLE_CLIENT_SECRET: 'google-secret', TOKEN_ENCRYPTION_KEY: SECRET, BACKEND_URL: 'https://api.example.com', FRONTEND_URL: 'https://app.example.com' } as Env;
+const CONTEXT = { requestId: 'req', signal: new AbortController().signal, log: createLogger() };
+
+function memory() {
+ const rows: StoredYouTubeConnection[] = [];
+ const parked: string[] = [];
+ const resumed: string[] = [];
+ const connections = {
+ listForUser: async (userId: string) => rows.filter(row => row.userId === userId),
+ findForUser: async (id: string, userId: string) => rows.find(row => row.id === id && row.userId === userId) ?? null,
+ findByChannelForUser: async (channelId: string, userId: string) => rows.find(row => row.channelId === channelId && row.userId === userId) ?? null,
+ async createForUser(userId: string, connection: NewYouTubeConnection) {
+ const row = { ...connection, id: `c${rows.length + 1}`, userId, status: 'active' as const, createdAt: '2026-11-05T00:00:00Z' };
+ rows.push(row);
+ return row;
+ },
+ async reconnectForUser(id: string, userId: string, tokens: YouTubeConnectionTokens) {
+ const row = rows.find(item => item.id === id && item.userId === userId);
+ if (row) Object.assign(row, tokens, { status: 'active' });
+ return row ?? null;
+ },
+ deleteForUser: async () => true,
+ updateTokensById: async (id: string, tokens: YouTubeConnectionTokens) => { Object.assign(rows.find(row => row.id === id) ?? {}, tokens); },
+ markNeedsReconnectById: async (id: string) => { Object.assign(rows.find(row => row.id === id) ?? {}, { status: 'needs_reconnect' }); },
+ } as unknown as YouTubeConnectionRepository;
+ const uploads = {
+ parkForConnection: async (id: string) => { parked.push(id); },
+ resumeParkedForUser: async (id: string) => { resumed.push(id); },
+ } as unknown as YouTubeUploadRepository;
+ const accounts = { listForUser: async () => [{ id: 'acc-1', platform: 'youtube', channelId: 'UC123' }] } as unknown as AccountRepository;
+ const audit = { recordForUser: async () => undefined } as unknown as AuditRepository;
+ return { rows, parked, resumed, service: createYouTubeConnectService({ connections, uploads, accounts, audit, config: readConfig(ENV), context: CONTEXT }) };
+}
+
+function google(t: { after(fn: () => void): void }, token: Record<string, unknown>) {
+ const fetchMock = mock.method(globalThis, 'fetch', async (url: string) => (String(url).includes('oauth2.googleapis.com/token')
+ ? Response.json(token, { status: token.error ? 400 : 200 })
+ : Response.json({ items: [{ id: 'UC123', snippet: { title: 'Cooking' } }] })));
+ t.after(() => fetchMock.mock.restore());
+ return fetchMock;
+}
+
+test('a sign-in started by one person cannot be finished by another, and a changed state is refused', async () => {
+ const { service } = memory();
+ const state = await createOAuthState('user-1', 'google-secret');
+ await assert.rejects(service.completeForUser('user-2', 'code', state), ForbiddenError);
+ await assert.rejects(service.completeForUser('user-1', 'code', `${state}x`), ValidationError);
+});
+
+test('finishing a sign-in seals both tokens, links the analytics account, and a second sign-in renews in place and resumes parked uploads', async t => {
+ google(t, { access_token: 'ACCESS', refresh_token: 'REFRESH', expires_in: 3600, scope: 'https://www.googleapis.com/auth/youtube.upload' });
+ const { rows, resumed, service } = memory();
+ const state = await createOAuthState('user-1', 'google-secret');
+ const first = await service.completeForUser('user-1', 'code', state);
+ assert.equal(first.outcome, 'connected');
+ assert.equal(first.connection.accountId, 'acc-1');
+ assert.equal(JSON.stringify(first).includes('REFRESH'), false);
+ assert.equal(await decryptToken(rows[0].refreshTokenEnc, SECRET), 'REFRESH');
+ assert.ok(!rows[0].refreshTokenEnc.includes('REFRESH'));
+ const again = await service.completeForUser('user-1', 'code', await createOAuthState('user-1', 'google-secret'));
+ assert.equal(again.outcome, 'reconnected');
+ assert.equal(rows.length, 1);
+ assert.deepEqual(resumed, [rows[0].id]);
+});
+
+test('a refresh Google refuses marks the channel for a new sign-in and parks its uploads', async t => {
+ google(t, { error: 'invalid_grant', error_description: 'Token has been expired or revoked.' });
+ const { rows, parked, service } = memory();
+ rows.push({
+ id: 'c1', userId: 'user-1', channelId: 'UC123', channelTitle: 'Cooking', accountId: null, status: 'active', scopes: [], createdAt: '',
+ refreshTokenEnc: await encryptToken('REFRESH', SECRET), accessTokenEnc: null, accessTokenExpiresAt: null,
+ });
+ const warn = mock.method(console, 'warn', () => undefined);
+ t.after(() => warn.mock.restore());
+ assert.equal(await service.accessTokenFor(rows[0]), null);
+ assert.equal(rows[0].status, 'needs_reconnect');
+ assert.deepEqual(parked, ['c1']);
+});
+
+test('without the Google client settings, connecting says what the owner must set', async () => {
+ const service = createYouTubeConnectService({
+ connections: {} as YouTubeConnectionRepository, uploads: {} as YouTubeUploadRepository, accounts: {} as AccountRepository,
+ audit: {} as AuditRepository, config: readConfig({} as Env), context: CONTEXT,
+ });
+ assert.equal(service.configured(), false);
+ await assert.rejects(service.authorizationUrl('user-1'), (err: Error) => err instanceof NotConfiguredError && /GOOGLE_CLIENT_ID/.test(err.message));
+});
diff --git a/backend/tests/services/youtubeUploadService.test.ts b/backend/tests/services/youtubeUploadService.test.ts
new file mode 100644
index 0000000..d050635
--- /dev/null
+++ b/backend/tests/services/youtubeUploadService.test.ts
@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createYouTubeUploadService } from '../../services/youtubeUploadService.ts';
+import { NotFoundError, ValidationError } from '../../lib/errors.ts';
+import { readConfig } from '../../lib/config.ts';
+import type { NewYouTubeUpload, StoredYouTubeUpload, UploadEdit, UploadProgress, YouTubeUploadRepository } from '../../repositories/youtubeUploadRepository.ts';
+import type { YouTubeConnectionRepository } from '../../repositories/youtubeConnectionRepository.ts';
+import type { MediaAssetRepository, StoredMediaAsset } from '../../repositories/mediaAssetRepository.ts';
+import type { AuditRepository } from '../../repositories/auditRepository.ts';
+import type { YouTubeUploadRequest, YouTubeUploadState } from '../../../shared/types/youtubePublishing.ts';
+import type { Env } from '../../types/env.ts';
+
+const ENV = { GOOGLE_CLIENT_ID: 'client', GOOGLE_CLIENT_SECRET: 'secret', TOKEN_ENCRYPTION_KEY: 'k'.repeat(48) } as Env;
+
+const VIDEO: StoredMediaAsset = {
+ id: 'm-video', publicId: 'v', resourceType: 'video', url: 'https://res.cloudinary.com/demo/video/upload/v.mp4', format: 'mp4',
+ bytes: 1000, width: 1080, height: 1920, durationSeconds: 45, label: '', createdAt: '',
+};
+const IMAGE: StoredMediaAsset = { ...VIDEO, id: 'm-image', resourceType: 'image', url: 'https://res.cloudinary.com/demo/image/upload/t.jpg', format: 'jpg', bytes: 5000 };
+
+function memory() {
+ const rows: (StoredYouTubeUpload & { clientRequestId: string | null; lease: boolean })[] = [];
+ const uploads = {
+ async createForUser(userId: string, upload: NewYouTubeUpload) {
+ const existing = rows.find(row => row.userId === userId && upload.clientRequestId && row.clientRequestId === upload.clientRequestId);
+ if (existing) return { upload: existing, existing: true };
+ const row = {
+ ...upload, id: `u${rows.length + 1}`, userId, hasThumbnail: upload.thumbnailUrl !== null, state: 'queued' as YouTubeUploadState,
+ bytesConfirmed: 0, videoId: null, attempts: 0, nextAttemptAt: '', lastError: null, createdAt: '', updatedAt: '', sessionUri: null, lease: false,
+ };
+ rows.push(row);
+ return { upload: row, existing: false };
+ },
+ listForUser: async (userId: string) => rows.filter(row => row.userId === userId),
+ findForUser: async (id: string, userId: string) => rows.find(row => row.id === id && row.userId === userId) ?? null,
+ async editQueuedForUser(id: string, userId: string, edit: UploadEdit) {
+ const row = rows.find(item => item.id === id && item.userId === userId && item.state === 'queued' && item.sessionUri === null && !item.lease);
+ if (row) Object.assign(row, edit);
+ return row ?? null;
+ },
+ async setStateForUser(id: string, userId: string, from: YouTubeUploadState[], to: YouTubeUploadState, extra: UploadProgress = {}) {
+ const row = rows.find(item => item.id === id && item.userId === userId && from.includes(item.state) && !item.lease);
+ if (row) Object.assign(row, extra, { state: to });
+ return row ?? null;
+ },
+ } as unknown as YouTubeUploadRepository;
+ const connections = { findForUser: async (id: string, userId: string) => (id === 'conn-1' && userId === 'user-1' ? { id: 'conn-1' } : null) } as unknown as YouTubeConnectionRepository;
+ const media = { findForUser: async (id: string, userId: string) => (userId !== 'user-1' ? null : id === VIDEO.id ? VIDEO : id === IMAGE.id ? IMAGE : null) } as unknown as MediaAssetRepository;
+ const audit = { recordForUser: async () => undefined } as unknown as AuditRepository;
+ return { rows, service: createYouTubeUploadService({ uploads, connections, media, audit, config: readConfig(ENV) }) };
+}
+
+const REQUEST: YouTubeUploadRequest = { connectionId: 'conn-1', mediaId: 'm-video', title: 'Launch day', privacy: 'private', madeForKids: false };
+
+test('a queued upload takes its source from the person\'s own media and knows a vertical clip is a Short', async () => {
+ const { service } = memory();
+ const { upload, existing } = await service.create('user-1', { ...REQUEST, thumbnailMediaId: 'm-image' });
+ assert.equal(existing, false);
+ assert.equal(upload.isShort, true);
+ assert.equal(upload.hasThumbnail, true);
+ assert.equal(upload.sourceBytes, 1000);
+ assert.equal('sourceUrl' in upload, false);
+ assert.equal('sessionUri' in upload, false);
+});
+
+test('another person\'s channel or media is not found, and metadata outside YouTube\'s limits is refused', async () => {
+ const { service } = memory();
+ await assert.rejects(service.create('user-2', REQUEST), NotFoundError);
+ await assert.rejects(service.create('user-1', { ...REQUEST, mediaId: 'm-image' }), NotFoundError);
+ await assert.rejects(service.create('user-1', { ...REQUEST, title: 'x'.repeat(101) }), ValidationError);
+});
+
+test('the same request id twice queues the video once', async () => {
+ const { rows, service } = memory();
+ const first = await service.create('user-1', { ...REQUEST, clientRequestId: 'req-1' });
+ const second = await service.create('user-1', { ...REQUEST, clientRequestId: 'req-1' });
+ assert.equal(second.existing, true);
+ assert.equal(second.upload.id, first.upload.id);
+ assert.equal(rows.length, 1);
+});
+
+test('details change only before the upload starts, and a publish time needs a private video', async () => {
+ const { rows, service } = memory();
+ const { upload } = await service.create('user-1', REQUEST);
+ assert.equal((await service.update('user-1', upload.id, { title: 'Better title' })).title, 'Better title');
+ await assert.rejects(service.update('user-1', upload.id, { privacy: 'public', publishAt: '2030-01-01T00:00:00Z' }), /must be private/);
+ rows[0].sessionUri = 'https://upload.example/session';
+ await assert.rejects(service.update('user-1', upload.id, { title: 'Too late' }), /has started/);
+});
+
+test('a job can be cancelled until YouTube has the video, and only a failed one is retried, from a fresh session', async () => {
+ const { rows, service } = memory();
+ const { upload } = await service.create('user-1', REQUEST);
+ rows[0].state = 'processing';
+ await assert.rejects(service.cancel('user-1', upload.id), /cannot be cancelled now/);
+ rows[0].state = 'failed';
+ rows[0].sessionUri = 'https://upload.example/old';
+ const retried = await service.retry('user-1', upload.id);
+ assert.equal(retried.state, 'queued');
+ assert.equal(rows[0].sessionUri, null);
+ assert.equal(rows[0].attempts, 0);
+ assert.equal((await service.cancel('user-1', upload.id)).state, 'cancelled');
+ await assert.rejects(service.retry('user-1', upload.id), /Only a failed upload/);
+});
diff --git a/backend/validators/mediaValidators.ts b/backend/validators/mediaValidators.ts
index a5b24c0..b5c698c 100644
--- a/backend/validators/mediaValidators.ts
+++ b/backend/validators/mediaValidators.ts
@@ -41,3 +41,39 @@ export function parseMediaImport(fields: Fields): MediaImport {
label: parseMediaLabel(fields),
};
}
+
+export interface MediaRegistration {
+ url: string;
+ publicId: string;
+ resourceType: 'image' | 'video';
+ format: string | null;
+ width: number | null;
+ height: number | null;
+ durationSeconds: number | null;
+ label: string;
+}
+
+function optionalCount(fields: Fields, name: string): number | null {
+ const value = fields[name];
+ if (value === undefined || value === null) return null;
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) throw new ValidationError(`${name} must be a positive number`);
+ return value;
+}
+
+// what Cloudinary told the browser after an upload; the service checks the address is on this instance's own cloud
+export function parseMediaRegistration(fields: Fields): MediaRegistration {
+ const resourceType = fields.resourceType;
+ if (!RESOURCE_TYPES.includes(resourceType as typeof RESOURCE_TYPES[number])) throw new ValidationError('resourceType must be image or video');
+ const publicId = requiredString(fields, 'publicId', 'publicId is required: Cloudinary\'s id for the upload').trim();
+ if (publicId.length === 0 || publicId.length > 300) throw new ValidationError('publicId must be Cloudinary\'s id for the upload');
+ return {
+ url: parseMediaUrl(requiredString(fields, 'url', 'url is required')),
+ publicId,
+ resourceType: resourceType as MediaRegistration['resourceType'],
+ format: optionalString(fields, 'format')?.trim().slice(0, 20) || null,
+ width: optionalCount(fields, 'width'),
+ height: optionalCount(fields, 'height'),
+ durationSeconds: optionalCount(fields, 'durationSeconds'),
+ label: parseMediaLabel(fields),
+ };
+}
diff --git a/backend/validators/youtubeValidators.ts b/backend/validators/youtubeValidators.ts
index 495d80c..485e4fc 100644
--- a/backend/validators/youtubeValidators.ts
+++ b/backend/validators/youtubeValidators.ts
@@ -91,3 +91,18 @@ export function parseYouTubeComplete(body: Fields): YouTubeConnectCompleteReques
state: requiredString(body, 'state', 'The Google sign-in state is missing. Start connecting again.'),
};
}
+
+export interface YouTubeCallbackQuery {
+ code?: string;
+ state?: string;
+ error?: string;
+}
+
+// a cancelled sign-in comes back with error instead of a code
+export function parseYouTubeCallback(query: Fields): YouTubeCallbackQuery {
+ return {
+ code: optionalString(query, 'code') || undefined,
+ state: optionalString(query, 'state') || undefined,
+ error: optionalString(query, 'error') || undefined,
+ };
+}
diff --git a/shared/types/media.ts b/shared/types/media.ts
index 399e38f..cd71ddf 100644
--- a/shared/types/media.ts
+++ b/shared/types/media.ts
@@ -12,3 +12,27 @@ export interface MediaAsset {
label: string;
createdAt: string;
}
+
+// GET /api/media
+export interface MediaListResponse {
+ success: true;
+ media: MediaAsset[];
+}
+
+// POST /api/media
+export interface MediaResponse {
+ success: true;
+ media: MediaAsset;
+}
+
+// body of POST /api/media: what Cloudinary returned to the browser after an upload
+export interface MediaRegistrationRequest {
+ url: string;
+ publicId: string;
+ resourceType: 'image' | 'video';
+ format?: string | null;
+ width?: number | null;
+ height?: number | null;
+ durationSeconds?: number | null;
+ label?: string;
+}