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(media): add the media service with per-person records

spacesdrive7478598ef530
diff --git a/backend/container.ts b/backend/container.ts
index b51d9df..fb4c370 100644
--- a/backend/container.ts
+++ b/backend/container.ts
@@ -6,6 +6,8 @@ import { createSettingsRepository } from './repositories/settingsRepository.ts';
import { createEmailQuotaRepository } from './repositories/emailQuotaRepository.ts';
import { createYouTubeQuotaRepository } from './repositories/youtubeQuotaRepository.ts';
import { createYouTubeQuotaService } from './services/youtubeQuotaService.ts';
+import { createMediaAssetRepository } from './repositories/mediaAssetRepository.ts';
+import { createMediaService } from './services/mediaService.ts';
import { createAuditRepository } from './repositories/auditRepository.ts';
import { createAutomationRuleRepository } from './repositories/automationRuleRepository.ts';
import { createAutomationCommentRepository } from './repositories/automationCommentRepository.ts';
@@ -61,6 +63,7 @@ import type { AutomationReconciler } from './services/automationReconciler.ts';
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 { AppConfig } from './lib/config.ts';
import type { RequestContext } from './types/context.ts';
import type { Redis, SupabaseClient } from './types/app.ts';
@@ -83,6 +86,7 @@ export interface Services {
trackedContent: TrackedContentService;
overview: OverviewService;
settings: SettingsService;
+ media: MediaService;
instagramConnect: InstagramConnectService;
authEmail: AuthEmailService;
automations: AutomationService;
@@ -128,6 +132,7 @@ 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 }),
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/repositories/mediaAssetRepository.ts b/backend/repositories/mediaAssetRepository.ts
new file mode 100644
index 0000000..6b8d830
--- /dev/null
+++ b/backend/repositories/mediaAssetRepository.ts
@@ -0,0 +1,131 @@
+import { maybeRow, rows } from './query.ts';
+import { newRowId } from '../lib/ids.ts';
+import type { SupabaseClient } from '../types/app.ts';
+import type { MediaAsset } from '../../shared/types/media.ts';
+
+interface MediaRow {
+ id: string;
+ public_id: string;
+ resource_type: MediaAsset['resourceType'];
+ url: string;
+ format: string | null;
+ bytes: number | null;
+ width: number | null;
+ height: number | null;
+ duration_seconds: number | null;
+ label: string;
+ created_at: string;
+}
+
+export interface NewMediaAsset {
+ publicId: string;
+ resourceType: MediaAsset['resourceType'];
+ url: string;
+ format: string | null;
+ bytes: number | null;
+ width: number | null;
+ height: number | null;
+ durationSeconds: number | null;
+ label: string;
+}
+
+// the Cloudinary id stays inside the Worker: it is what deleting needs, and a caller never sends one
+export type StoredMediaAsset = MediaAsset & { publicId: string };
+
+const COLUMNS = 'id, public_id, resource_type, url, format, bytes, width, height, duration_seconds, label, created_at';
+
+function toAsset(row: MediaRow): StoredMediaAsset {
+ return {
+ id: row.id,
+ publicId: row.public_id,
+ resourceType: row.resource_type,
+ url: row.url,
+ format: row.format,
+ bytes: row.bytes === null ? null : Number(row.bytes),
+ width: row.width,
+ height: row.height,
+ durationSeconds: row.duration_seconds === null ? null : Number(row.duration_seconds),
+ label: row.label,
+ createdAt: row.created_at,
+ };
+}
+
+// every method is scoped to the verified user: a file on the shared Cloudinary account belongs to the person whose row names it
+export interface MediaAssetRepository {
+ createForUser(userId: string, asset: NewMediaAsset): Promise<StoredMediaAsset>;
+ listForUser(userId: string): Promise<StoredMediaAsset[]>;
+ findForUser(id: string, userId: string): Promise<StoredMediaAsset | null>;
+ findByPublicIdForUser(publicId: string, userId: string): Promise<StoredMediaAsset | null>;
+ updateLabelForUser(id: string, userId: string, label: string): Promise<StoredMediaAsset | null>;
+ deleteForUser(id: string, userId: string): Promise<boolean>;
+}
+
+export function createMediaAssetRepository(db: SupabaseClient): MediaAssetRepository {
+ return {
+ async createForUser(userId, asset) {
+ const created = await rows<MediaRow>('mediaAssets.create', () => db.from('media_assets').insert({
+ id: newRowId(),
+ user_id: userId,
+ public_id: asset.publicId,
+ resource_type: asset.resourceType,
+ url: asset.url,
+ format: asset.format,
+ bytes: asset.bytes,
+ width: asset.width,
+ height: asset.height,
+ duration_seconds: asset.durationSeconds,
+ label: asset.label,
+ }).select(COLUMNS));
+ return toAsset(created[0]);
+ },
+
+ async listForUser(userId) {
+ const found = await rows<MediaRow>('mediaAssets.listForUser', () => db
+ .from('media_assets')
+ .select(COLUMNS)
+ .eq('user_id', userId)
+ .order('created_at', { ascending: false }));
+ return found.map(toAsset);
+ },
+
+ async findForUser(id, userId) {
+ const row = await maybeRow<MediaRow>('mediaAssets.findForUser', () => db
+ .from('media_assets')
+ .select(COLUMNS)
+ .eq('id', id)
+ .eq('user_id', userId)
+ .maybeSingle());
+ return row ? toAsset(row) : null;
+ },
+
+ async findByPublicIdForUser(publicId, userId) {
+ const row = await maybeRow<MediaRow>('mediaAssets.findByPublicIdForUser', () => db
+ .from('media_assets')
+ .select(COLUMNS)
+ .eq('public_id', publicId)
+ .eq('user_id', userId)
+ .maybeSingle());
+ return row ? toAsset(row) : null;
+ },
+
+ async updateLabelForUser(id, userId, label) {
+ const updated = await rows<MediaRow>('mediaAssets.updateLabelForUser', () => db
+ .from('media_assets')
+ .update({ label })
+ .eq('id', id)
+ .eq('user_id', userId)
+ .select(COLUMNS));
+ return updated[0] ? toAsset(updated[0]) : null;
+ },
+
+ async deleteForUser(id, userId) {
+ const deleted = await rows<{ id: string }>('mediaAssets.deleteForUser', () => db
+ .from('media_assets')
+ .delete()
+ .eq('id', id)
+ .eq('user_id', userId)
+ .select('id'));
+ return deleted.length > 0;
+ },
+ };
+}
diff --git a/backend/services/mediaService.ts b/backend/services/mediaService.ts
new file mode 100644
index 0000000..2974377
--- /dev/null
+++ b/backend/services/mediaService.ts
@@ -0,0 +1,103 @@
+import { destroyFile, uploadFromUrl } from './cloudinary/cloudinaryApi.ts';
+import { NotConfiguredError, NotFoundError, UpstreamError, isUniqueViolation } from '../lib/errors.ts';
+import type { MediaResourceType } from './cloudinary/cloudinaryApi.ts';
+import type { MediaAssetRepository, StoredMediaAsset } from '../repositories/mediaAssetRepository.ts';
+import type { AuditRepository } from '../repositories/auditRepository.ts';
+import type { AppConfig } from '../lib/config.ts';
+import type { RequestContext } from '../types/context.ts';
+import type { MediaAsset } from '../../shared/types/media.ts';
+
+export interface MediaDeps {
+ media: MediaAssetRepository;
+ audit: AuditRepository;
+ config: AppConfig;
+ context: RequestContext;
+}
+
+export interface MediaImport {
+ url: string;
+ resourceType: MediaResourceType;
+ label: string;
+}
+
+export interface MediaRemoval {
+ // false when the instance has no Cloudinary API secret, so only Twiligent's record was removed
+ removedFromCloudinary: boolean;
+}
+
+export interface MediaService {
+ list(userId: string): Promise<MediaAsset[]>;
+ importFromUrl(userId: string, request: MediaImport): Promise<MediaAsset>;
+ updateLabel(userId: string, id: string, label: string): Promise<MediaAsset>;
+ remove(userId: string, id: string): Promise<MediaRemoval>;
+ canDeleteFiles(): boolean;
+}
+
+// the Cloudinary id never leaves the Worker; callers only ever see Twiligent's own id
+function publicView({ publicId: _publicId, ...asset }: StoredMediaAsset): MediaAsset {
+ return asset;
+}
+
+const NOT_FOUND = 'No media with that id. List the media to find it.';
+
+export function createMediaService({ media, audit, config, context }: MediaDeps): MediaService {
+ const { signal } = context;
+
+ async function findOwned(userId: string, id: string): Promise<StoredMediaAsset> {
+ const asset = await media.findForUser(id, userId);
+ if (!asset) throw new NotFoundError(NOT_FOUND);
+ return asset;
+ }
+
+ return {
+ list: async userId => (await media.listForUser(userId)).map(publicView),
+
+ async importFromUrl(userId, { url, resourceType, label }) {
+ if (!config.cloudinary) throw new NotConfiguredError('Cloudinary is not set up on this server, so media cannot be imported.');
+ const uploaded = await uploadFromUrl(config.cloudinary, url, resourceType, signal);
+ if (uploaded.resource_type !== resourceType) {
+ throw new UpstreamError(`Cloudinary stored the file as ${uploaded.resource_type}, not ${resourceType}. Import it with the right type.`);
+ }
+ const record = {
+ publicId: uploaded.public_id,
+ resourceType,
+ url: uploaded.secure_url,
+ format: uploaded.format ?? null,
+ bytes: uploaded.bytes ?? null,
+ width: uploaded.width ?? null,
+ height: uploaded.height ?? null,
+ durationSeconds: uploaded.duration ?? null,
+ label,
+ };
+ let saved: StoredMediaAsset;
+ try {
+ saved = await media.createForUser(userId, record);
+ } catch (err) {
+ // the preset can reuse a public id for the same file; the person already has it
+ const existing = isUniqueViolation(err) ? await media.findByPublicIdForUser(uploaded.public_id, userId) : null;
+ if (!existing) throw err;
+ return publicView(existing);
+ }
+ await audit.recordForUser(userId, { action: 'media_asset.imported', subjectType: 'media_asset', subjectId: saved.id, details: { resourceType } });
+ return publicView(saved);
+ },
+
+ async updateLabel(userId, id, label) {
+ const updated = await media.updateLabelForUser(id, userId, label);
+ if (!updated) throw new NotFoundError(NOT_FOUND);
+ return publicView(updated);
+ },
+
+ // the file goes from Cloudinary first, so a failure there leaves the record and the person can try again
+ async remove(userId, id) {
+ const asset = await findOwned(userId, id);
+ const admin = config.cloudinaryAdmin;
+ if (admin) await destroyFile(admin, asset.publicId, asset.resourceType, signal);
+ await media.deleteForUser(id, userId);
+ await audit.recordForUser(userId, { action: 'media_asset.deleted', subjectType: 'media_asset', subjectId: id, details: { fromCloudinary: Boolean(admin) } });
+ return { removedFromCloudinary: Boolean(admin) };
+ },
+
+ canDeleteFiles: () => config.cloudinaryAdmin !== null,
+ };
+}
diff --git a/backend/tests/services/mediaService.test.ts b/backend/tests/services/mediaService.test.ts
new file mode 100644
index 0000000..99da289
--- /dev/null
+++ b/backend/tests/services/mediaService.test.ts
@@ -0,0 +1,90 @@
+import { test, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createMediaService } from '../../services/mediaService.ts';
+import { NotConfiguredError, NotFoundError, UpstreamError } from '../../lib/errors.ts';
+import { readConfig } from '../../lib/config.ts';
+import { createLogger } from '../../lib/logger.ts';
+import type { AuditRepository } from '../../repositories/auditRepository.ts';
+import type { MediaAssetRepository, NewMediaAsset, StoredMediaAsset } from '../../repositories/mediaAssetRepository.ts';
+import type { Env } from '../../types/env.ts';
+
+const CONTEXT = { requestId: 'req-test', signal: new AbortController().signal, log: createLogger() };
+const WITH_CLOUDINARY = { CLOUDINARY_CLOUD_NAME: 'demo', CLOUDINARY_UPLOAD_PRESET: 'unsigned' } as Env;
+
+// an in-memory table with the same ownership rule as the repository: every lookup needs the user id
+function memory() {
+ const rows: (StoredMediaAsset & { userId: string })[] = [];
+ const audits: string[] = [];
+ const media: MediaAssetRepository = {
+ async createForUser(userId, asset: NewMediaAsset) {
+ const row = { ...asset, id: `m${rows.length + 1}`, createdAt: '2026-11-05T00:00:00Z', userId };
+ rows.push(row);
+ return row;
+ },
+ listForUser: async userId => rows.filter(row => row.userId === userId),
+ findForUser: async (id, userId) => rows.find(row => row.id === id && row.userId === userId) ?? null,
+ findByPublicIdForUser: async (publicId, userId) => rows.find(row => row.publicId === publicId && row.userId === userId) ?? null,
+ async updateLabelForUser(id, userId, label) {
+ const row = rows.find(item => item.id === id && item.userId === userId);
+ if (row) row.label = label;
+ return row ?? null;
+ },
+ async deleteForUser(id, userId) {
+ const index = rows.findIndex(row => row.id === id && row.userId === userId);
+ if (index >= 0) rows.splice(index, 1);
+ return index >= 0;
+ },
+ };
+ const audit = { recordForUser: async (_userId: string, event: { action: string }) => { audits.push(event.action); } } as unknown as AuditRepository;
+ return { rows, audits, media, audit };
+}
+
+function cloudinaryAnswers(t: { after(fn: () => void): void }, ...answers: unknown[]) {
+ const fetchMock = mock.method(globalThis, 'fetch', async () => Response.json(answers.shift()));
+ t.after(() => fetchMock.mock.restore());
+ return fetchMock;
+}
+
+test('an import keeps Cloudinary\'s details for the caller and never shows the Cloudinary id', async t => {
+ cloudinaryAnswers(t, {
+ public_id: 'cld-1', secure_url: 'https://res.cloudinary.com/demo/video/upload/cld-1.mp4', resource_type: 'video',
+ format: 'mp4', bytes: 2048, width: 1080, height: 1920, duration: 12.5,
+ });
+ const { media, audit, audits } = memory();
+ const service = createMediaService({ media, audit, config: readConfig(WITH_CLOUDINARY), context: CONTEXT });
+ const imported = await service.importFromUrl('user-1', { url: 'https://example.com/clip.mp4', resourceType: 'video', label: 'Clip' });
+ assert.equal(imported.url, 'https://res.cloudinary.com/demo/video/upload/cld-1.mp4');
+ assert.equal(imported.durationSeconds, 12.5);
+ assert.equal('publicId' in imported, false);
+ assert.deepEqual(audits, ['media_asset.imported']);
+ assert.equal((await service.list('user-2')).length, 0);
+ await assert.rejects(service.updateLabel('user-2', imported.id, 'Mine now'), NotFoundError);
+});
+
+test('a file Cloudinary stored as another type is refused, and an instance without Cloudinary says so', async t => {
+ cloudinaryAnswers(t, { public_id: 'x', secure_url: 'https://res.cloudinary.com/x', resource_type: 'raw' });
+ const { media, audit } = memory();
+ const service = createMediaService({ media, audit, config: readConfig(WITH_CLOUDINARY), context: CONTEXT });
+ await assert.rejects(service.importFromUrl('user-1', { url: 'https://example.com/a.jpg', resourceType: 'image', label: '' }), UpstreamError);
+ const unset = createMediaService({ media, audit, config: readConfig({} as Env), context: CONTEXT });
+ await assert.rejects(unset.importFromUrl('user-1', { url: 'https://example.com/a.jpg', resourceType: 'image', label: '' }), NotConfiguredError);
+});
+
+test('without the API secret a delete removes only the record and says so; with it the file goes from Cloudinary first', async t => {
+ const fetchMock = cloudinaryAnswers(t,
+ { public_id: 'a', secure_url: 'https://res.cloudinary.com/demo/image/upload/a.jpg', resource_type: 'image' },
+ { public_id: 'b', secure_url: 'https://res.cloudinary.com/demo/image/upload/b.jpg', resource_type: 'image' },
+ { result: 'ok' });
+ const { media, audit, rows } = memory();
+ const plain = createMediaService({ media, audit, config: readConfig(WITH_CLOUDINARY), context: CONTEXT });
+ const first = await plain.importFromUrl('user-1', { url: 'https://example.com/a.jpg', resourceType: 'image', label: '' });
+ const second = await plain.importFromUrl('user-1', { url: 'https://example.com/b.jpg', resourceType: 'image', label: '' });
+ assert.deepEqual(await plain.remove('user-1', first.id), { removedFromCloudinary: false });
+ assert.equal(fetchMock.mock.callCount(), 2);
+ const withSecret = { ...WITH_CLOUDINARY, CLOUDINARY_API_KEY: 'KEY', CLOUDINARY_API_SECRET: 'SECRET' } as Env;
+ const admin = createMediaService({ media, audit, config: readConfig(withSecret), context: CONTEXT });
+ await assert.rejects(admin.remove('user-2', second.id), NotFoundError);
+ assert.deepEqual(await admin.remove('user-1', second.id), { removedFromCloudinary: true });
+ assert.match(String(fetchMock.mock.calls[2].arguments[0]), /\/demo\/image\/destroy$/);
+ assert.equal(rows.length, 0);
+});
diff --git a/backend/tests/validators/mediaValidators.test.ts b/backend/tests/validators/mediaValidators.test.ts
new file mode 100644
index 0000000..1adbaa1
--- /dev/null
+++ b/backend/tests/validators/mediaValidators.test.ts
@@ -0,0 +1,26 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseMediaImport, parseMediaLabel } from '../../validators/mediaValidators.ts';
+import { ValidationError } from '../../lib/errors.ts';
+
+test('an import takes a public https address, a type and a trimmed label', () => {
+ assert.deepEqual(parseMediaImport({ url: ' https://example.com/a.jpg ', resourceType: 'image', label: ' Launch ' }), {
+ url: 'https://example.com/a.jpg', resourceType: 'image', label: 'Launch',
+ });
+});
+
+test('an address that is not public https, or carries credentials, is refused before anything is fetched', () => {
+ const refused = [
+ 'http://example.com/a.jpg', 'ftp://example.com/a.jpg', 'https://localhost/a.jpg', 'https://127.0.0.1/a.jpg',
+ 'https://10.0.0.5/a.jpg', 'https://192.168.1.2/a.jpg', 'https://172.20.0.1/a.jpg', 'https://169.254.169.254/latest',
+ 'https://[::1]/a.jpg', 'https://printer.local/a.jpg', 'https://user:[email protected]/a.jpg', 'not a url',
+ `https://example.com/${'a'.repeat(2100)}`,
+ ];
+ for (const url of refused) assert.throws(() => parseMediaImport({ url, resourceType: 'image' }), ValidationError, url);
+});
+
+test('the type must be image or video, and a label is at most 200 characters', () => {
+ assert.throws(() => parseMediaImport({ url: 'https://example.com/a.pdf', resourceType: 'raw' }), ValidationError);
+ assert.throws(() => parseMediaLabel({ label: 'x'.repeat(201) }), ValidationError);
+ assert.equal(parseMediaLabel({}), '');
+});
diff --git a/backend/validators/mediaValidators.ts b/backend/validators/mediaValidators.ts
new file mode 100644
index 0000000..a5b24c0
--- /dev/null
+++ b/backend/validators/mediaValidators.ts
@@ -0,0 +1,43 @@
+import { ValidationError } from '../lib/errors.ts';
+import { optionalString, requiredString } from './fields.ts';
+import type { Fields } from './fields.ts';
+import type { MediaImport } from '../services/mediaService.ts';
+
+const MAX_URL_LENGTH = 2048;
+export const MAX_MEDIA_LABEL_LENGTH = 200;
+const RESOURCE_TYPES = ['image', 'video'] as const;
+
+// Cloudinary fetches the file, not the Worker, but an address on a private network is never a public file anyone meant
+// to share, so it is refused before any request goes out
+const PRIVATE_HOST = /^(localhost|.*\.local|.*\.internal|127\.|10\.|192\.168\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|0\.|\[)/i;
+
+export function parseMediaUrl(value: string): string {
+ let parsed: URL;
+ try {
+ parsed = new URL(value.trim());
+ } catch {
+ throw new ValidationError('url must be a full https address of an image or video');
+ }
+ if (parsed.protocol !== 'https:') throw new ValidationError('url must start with https://');
+ if (parsed.username || parsed.password) throw new ValidationError('url must not contain a user name or password');
+ if (PRIVATE_HOST.test(parsed.hostname)) throw new ValidationError('url must be a public address on the internet');
+ const url = parsed.toString();
+ if (url.length > MAX_URL_LENGTH) throw new ValidationError(`url must be at most ${MAX_URL_LENGTH} characters`);
+ return url;
+}
+
+export function parseMediaLabel(fields: Fields): string {
+ const label = (optionalString(fields, 'label') ?? '').trim();
+ if (label.length > MAX_MEDIA_LABEL_LENGTH) throw new ValidationError(`label must be at most ${MAX_MEDIA_LABEL_LENGTH} characters`);
+ return label;
+}
+
+export function parseMediaImport(fields: Fields): MediaImport {
+ const resourceType = fields.resourceType;
+ if (!RESOURCE_TYPES.includes(resourceType as typeof RESOURCE_TYPES[number])) throw new ValidationError('resourceType must be image or video');
+ return {
+ url: parseMediaUrl(requiredString(fields, 'url', 'url is required: the https address of the image or video')),
+ resourceType: resourceType as MediaImport['resourceType'],
+ label: parseMediaLabel(fields),
+ };
+}
diff --git a/shared/types/media.ts b/shared/types/media.ts
new file mode 100644
index 0000000..399e38f
--- /dev/null
+++ b/shared/types/media.ts
@@ -0,0 +1,14 @@
+// an image or video a person keeps on the instance's Cloudinary account, as the media tools return it
+export interface MediaAsset {
+ id: string;
+ resourceType: 'image' | 'video';
+ // a public https address Instagram and YouTube can fetch, for scheduling a post
+ url: string;
+ format: string | null;
+ bytes: number | null;
+ width: number | null;
+ height: number | null;
+ durationSeconds: number | null;
+ label: string;
+ createdAt: string;
+}