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 a Cloudinary client for imports by URL and signed deletes

spacesdrivef330c4dd4650
diff --git a/backend/lib/config.ts b/backend/lib/config.ts
index e1a74f3..4e05e47 100644
--- a/backend/lib/config.ts
+++ b/backend/lib/config.ts
@@ -22,6 +22,13 @@ export interface CloudinaryConfig {
uploadPreset: string;
}
+// the signed API, only for deleting files; kept apart from CloudinaryConfig, which the browser receives
+export interface CloudinaryAdminConfig {
+ cloudName: string;
+ apiKey: string;
+ apiSecret: string;
+}
+
// appId and appSecret are undefined when the Worker secrets are not set
export interface InstagramOAuthConfig {
frontendUrl: string;
@@ -65,6 +72,7 @@ export interface AppConfig {
youtubeApiKey: string | undefined;
instagram: InstagramOAuthConfig;
cloudinary: CloudinaryConfig | null;
+ cloudinaryAdmin: CloudinaryAdminConfig | null;
allowedOrigins: string[];
authEmail: AuthEmailConfig;
automation: AutomationConfig;
@@ -193,10 +201,13 @@ export function readMcpConfig(env: Env): McpConfig {
export function readConfig(env: Env): AppConfig {
const cloudName = cleanSecret(env.CLOUDINARY_CLOUD_NAME);
const uploadPreset = cleanSecret(env.CLOUDINARY_UPLOAD_PRESET);
+ const apiKey = cleanSecret(env.CLOUDINARY_API_KEY);
+ const apiSecret = cleanSecret(env.CLOUDINARY_API_SECRET);
return {
youtubeApiKey: cleanSecret(env.YOUTUBE_API_KEY),
instagram: readInstagramOAuthConfig(env),
cloudinary: cloudName && uploadPreset ? { cloudName, uploadPreset } : null,
+ cloudinaryAdmin: cloudName && apiKey && apiSecret ? { cloudName, apiKey, apiSecret } : null,
allowedOrigins: allowedOrigins(env),
authEmail: readAuthEmailConfig(env),
automation: readAutomationConfig(env),
diff --git a/backend/services/cloudinary/cloudinaryApi.ts b/backend/services/cloudinary/cloudinaryApi.ts
new file mode 100644
index 0000000..c15c0f9
--- /dev/null
+++ b/backend/services/cloudinary/cloudinaryApi.ts
@@ -0,0 +1,56 @@
+import { UpstreamError, UpstreamTimeoutError, isAbortError } from '../../lib/errors.ts';
+import type { CloudinaryAdminConfig, CloudinaryConfig } from '../../lib/config.ts';
+
+const CLOUDINARY_API = 'https://api.cloudinary.com/v1_1';
+
+export type MediaResourceType = 'image' | 'video';
+
+// the parts of Cloudinary's upload answer Twiligent keeps
+export interface CloudinaryUpload {
+ public_id: string;
+ secure_url: string;
+ resource_type: string;
+ format?: string;
+ bytes?: number;
+ width?: number;
+ height?: number;
+ duration?: number;
+}
+
+interface CloudinaryErrorBody {
+ error?: { message?: string };
+}
+
+async function post<T>(url: string, body: URLSearchParams, signal?: AbortSignal): Promise<T> {
+ let response: Response;
+ try {
+ response = await fetch(url, { method: 'POST', body, 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 data = await response.json().catch(() => ({})) as T & CloudinaryErrorBody;
+ if (!response.ok || data.error) throw new UpstreamError(`Cloudinary refused the request: ${data.error?.message ?? `status ${response.status}`}`, { status: response.status });
+ return data;
+}
+
+// Cloudinary downloads the file itself, so the Worker never fetches an address a caller chose
+export function uploadFromUrl(config: CloudinaryConfig, fileUrl: string, resourceType: MediaResourceType, signal?: AbortSignal): Promise<CloudinaryUpload> {
+ const body = new URLSearchParams({ file: fileUrl, upload_preset: config.uploadPreset });
+ return post<CloudinaryUpload>(`${CLOUDINARY_API}/${config.cloudName}/${resourceType}/upload`, body, signal);
+}
+
+// a signature is SHA-1 over the sorted signed parameters followed by the API secret
+export async function signParams(params: Record<string, string>, apiSecret: string): Promise<string> {
+ const serialized = Object.keys(params).sort().map(name => `${name}=${params[name]}`).join('&');
+ const digest = await crypto.subtle.digest('SHA-1', new TextEncoder().encode(`${serialized}${apiSecret}`));
+ return [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+// removes the file from the shared account; 'not found' means it was already gone, which is the same outcome
+export async function destroyFile(config: CloudinaryAdminConfig, publicId: string, resourceType: MediaResourceType, signal?: AbortSignal): Promise<void> {
+ const params = { public_id: publicId, timestamp: String(Math.floor(Date.now() / 1000)) };
+ const body = new URLSearchParams({ ...params, api_key: config.apiKey, signature: await signParams(params, config.apiSecret) });
+ const answer = await post<{ result?: string }>(`${CLOUDINARY_API}/${config.cloudName}/${resourceType}/destroy`, body, signal);
+ if (answer.result !== 'ok' && answer.result !== 'not found') throw new UpstreamError(`Cloudinary did not delete the file (${answer.result ?? 'no answer'})`);
+}
diff --git a/backend/tests/services/cloudinary/cloudinaryApi.test.ts b/backend/tests/services/cloudinary/cloudinaryApi.test.ts
new file mode 100644
index 0000000..bd9ba0d
--- /dev/null
+++ b/backend/tests/services/cloudinary/cloudinaryApi.test.ts
@@ -0,0 +1,39 @@
+import { test, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { destroyFile, signParams, uploadFromUrl } from '../../../services/cloudinary/cloudinaryApi.ts';
+import { UpstreamError } from '../../../lib/errors.ts';
+
+test('the signature matches the example in Cloudinary\'s documentation', async () => {
+ const signature = await signParams({ timestamp: '1315060510', public_id: 'sample_image', eager: 'w_400,h_300,c_pad|w_260,h_200,c_crop' }, 'abcd');
+ assert.equal(signature, 'bfd09f95f331f558cbd1320e67aa8d488770583e');
+});
+
+test('an import asks Cloudinary to fetch the address with the unsigned preset', async t => {
+ const calls: { url: string; body: string }[] = [];
+ const fetchMock = mock.method(globalThis, 'fetch', async (url: string, init: RequestInit) => {
+ calls.push({ url, body: String(init.body) });
+ return Response.json({ public_id: 'abc', secure_url: 'https://res.cloudinary.com/demo/image/upload/abc.jpg', resource_type: 'image' });
+ });
+ t.after(() => fetchMock.mock.restore());
+ const uploaded = await uploadFromUrl({ cloudName: 'demo', uploadPreset: 'unsigned' }, 'https://example.com/a.jpg', 'image');
+ assert.equal(uploaded.public_id, 'abc');
+ assert.equal(calls[0].url, 'https://api.cloudinary.com/v1_1/demo/image/upload');
+ assert.equal(calls[0].body, 'file=https%3A%2F%2Fexample.com%2Fa.jpg&upload_preset=unsigned');
+});
+
+test('a refused import or delete is an upstream error with Cloudinary\'s reason, and an already deleted file counts as deleted', async t => {
+ const answers = [
+ Response.json({ error: { message: 'Resource not found - https://example.com/missing.jpg' } }, { status: 400 }),
+ Response.json({ result: 'not found' }),
+ Response.json({ result: 'error' }),
+ ];
+ const fetchMock = mock.method(globalThis, 'fetch', async () => answers.shift());
+ t.after(() => fetchMock.mock.restore());
+ await assert.rejects(
+ uploadFromUrl({ cloudName: 'demo', uploadPreset: 'p' }, 'https://example.com/missing.jpg', 'image'),
+ (err: Error) => err instanceof UpstreamError && /Resource not found/.test(err.message),
+ );
+ const admin = { cloudName: 'demo', apiKey: 'KEY', apiSecret: 'SECRET' };
+ await destroyFile(admin, 'abc', 'image');
+ await assert.rejects(destroyFile(admin, 'abc', 'image'), UpstreamError);
+});
diff --git a/backend/types/env.ts b/backend/types/env.ts
index 14ed9d4..4f14873 100644
--- a/backend/types/env.ts
+++ b/backend/types/env.ts
@@ -8,6 +8,8 @@ export interface Env {
INSTAGRAM_APP_SECRET?: string;
CLOUDINARY_CLOUD_NAME?: string;
CLOUDINARY_UPLOAD_PRESET?: string;
+ CLOUDINARY_API_KEY?: string;
+ CLOUDINARY_API_SECRET?: string;
BACKEND_URL?: string;
FRONTEND_URL?: string;
// comma-separated extra browser origins allowed by CORS, besides FRONTEND_URL