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