Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Frontend API Layer
Location: frontend/src/services/api.ts
The single source of truth for all frontend-to-backend communication. Never call fetch() directly in components or contexts. Always add methods here and call them from components.
The request() Function
const API = import.meta.env.VITE_API_URL || 'http://localhost:8787/api';
// every failure arrives with a 4xx or 5xx status and the ApiFailure body, so a 2xx is always a success
async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
const { data: { session } } = await supabase.auth.getSession();
const token = session?.access_token;
const res = await fetch(`${API}${path}`, {
headers: {
'Content-Type': 'application/json',
...(token ? { 'Authorization': `Bearer ${token}` } : {}),
},
...options,
});
// a proxy error page is not JSON; the status still explains the failure
const data = await res.json().catch(() => null) as unknown;
if (!res.ok) throw new Error(failureMessage(res.status, data as Partial<ApiFailure> | null));
return data as T;
}
T is the response type from shared/types/ that the route returns; request<T>() casts the parsed JSON to it once and does not validate it at runtime. import.meta.env is typed by ImportMetaEnv in frontend/src/vite-env.d.ts; add a new VITE_* variable there.
What it does automatically:
- Gets the current Supabase session token
- Attaches
Authorization: Bearer <token>header if logged in - Parses the JSON response (a body that is not JSON, such as a proxy error page, is read as
null) - Throws an
Errorfor any status outside 2xx; a 2xx response is always a success
Error handling: The backend answers every failure with a 4xx or 5xx status and one body, the ApiFailure type in shared/types/domain.ts:
{ "success": false, "code": "NOT_FOUND", "message": "Account not found", "requestId": "3f2a..." }
failureMessage(status, body) in frontend/src/lib/apiErrors.ts builds the thrown message: the backend's message, or The server answered with status <status>. Try again in a moment. when there is none. For a 5xx failure it adds the request id, (request <id>), so a user can quote it and the owner can find the matching log line. Callers are responsible for catching this error and showing appropriate UI. Callers never check success on a 2xx response; there is no failure body with a success status.
// a server-side failure is logged under its request id, so the message carries the id for the user to quote
export function failureMessage(status: number, body: Partial<ApiFailure> | null): string {
const message = body?.message || `The server answered with status ${status}. Try again in a moment.`;
return status >= 500 && body?.requestId ? `${message} (request ${body.requestId})` : message;
}
A 429 body also carries retryAfter (seconds); request() shows its message, which already says how long to wait. See docs/architecture/backend/REQUEST_PIPELINE.md for the codes and statuses.
The api Object
All backend endpoints are methods on the exported api object. Each method types its parameters and passes the shared response type to request<T>(), so the call site gets a typed result without a cast:
export const api = {
health: () => request<HealthResponse>('/health'),
getAccounts: () => request<AccountListResponse>('/accounts'),
addAccount: (input: string) => request<YouTubeAccountAddResponse>('/accounts', { method: 'POST', body: JSON.stringify({ input }) }),
// ... (see api.ts for full list)
};
The response types are imported with import type from @shared/types/*.ts, so nothing from shared/ reaches the bundle.
Fresh reads
getVideos(id, fresh?) and getIGMedia(id, fresh?) read the server's cache by default. Passing fresh = true
adds ?fresh=1, which skips the cache; pages send it only from their Refresh button, so opening a page never
spends platform quota by itself.
Adding a New API Method
Add or reuse the request and response types in
shared/types/.Add to
api.ts:export const api = { // ... existing methods getMyResource: (id: string) => request<MyResource>(`/my-resource/${id}`), createMyResource: (data: MyResourceCreateRequest) => request<MyResourceCreateResponse>('/my-resource', { method: 'POST', body: JSON.stringify(data) }), };Use in a component:
import { api } from '../services/api'; // ... const data = await api.getMyResource(id); // typed as MyResourceRun
npm run typecheck, and updatedocs/architecture/backend/ROUTES.mdif this is a new backend route
Error Handling Pattern in Components
const [loading, setLoading] = useState(false);
const { showToast } = useAppContext();
async function handleAction() {
setLoading(true);
try {
const result = await api.someMethod(data);
showToast('Changes saved');
// update state with result
} catch (err) {
showToast((err as Error).message, 'error');
} finally {
setLoading(false);
}
}
Overview Method
getOverview: () => request<OverviewResponse>('/overview'),
Returns OverviewResponse from shared/types/domain.ts: { tracked: TrackedPost[], analyticsCache: OverviewAnalyticsCache }, where analyticsCache maps each account ID to its cached totals.
The analyticsCache is populated from Redis on the backend; no live API calls are made. Data is only present for accounts whose analytics pages have been previously visited (which populates the Redis cache). The Overview dashboard uses this to compute Total Content, Total Comments, and Total Likes across all platforms without expensive per-account API calls on load.
Automation Methods
getAutomations: () => request<AutomationOverviewResponse>('/automations'),
createAutomationRule: (data: AutomationRuleRequest) => request<AutomationRuleResponse>('/automations/rules', { method: 'POST', body: JSON.stringify(data) }),
updateAutomationRule: (id: string, data: AutomationRuleUpdateRequest) => request<AutomationRuleResponse>(`/automations/rules/${id}`, { method: 'PUT', body: JSON.stringify(data) }),
duplicateAutomationRule: (id: string) => request<AutomationRuleResponse>(`/automations/rules/${id}/duplicate`, { method: 'POST' }),
deleteAutomationRule: (id: string) => request<SuccessMessageResponse>(`/automations/rules/${id}`, { method: 'DELETE' }),
testAutomationRule: (data: AutomationTestRequest) => request<AutomationTestResponse>('/automations/test', { method: 'POST', body: JSON.stringify(data) }),
getAutomationActivity: (query: URLSearchParams) => request<AutomationActivityResponse>(`/automations/activity?${query}`),
retryAutomationActivity: (id: string) => request<AutomationActivityItemResponse>(`/automations/activity/${id}/retry`, { method: 'POST' }),
retryAutomationPublicReply: (id: string) => request<AutomationActivityItemResponse>(`/automations/activity/${id}/public-reply/retry`, { method: 'POST' }),
getAutomationStats: (query: URLSearchParams) => request<AutomationStatsResponse>(`/automations/stats?${query}`),
setAutomationAccountPaused: (accountId: string, paused: boolean) => request<AutomationAccountResponse>(`/automations/accounts/${accountId}`, { method: 'PUT', body: JSON.stringify({ paused }) }),
subscribeAutomationAccount: (accountId: string) => request<AutomationAccountResponse>(`/automations/accounts/${accountId}/subscribe`, { method: 'POST' }),
The types are in shared/types/automation.ts. Activity and stats take their filters as URLSearchParams (accountId, ruleId, status as a comma-separated list, from, to, before, limit), built in features/automations/useAutomationActivity.ts. An accepted reply means Instagram took the request; the API reports nothing about delivery or reading. Rules carry matchMode (contains, exact or any) and the followers-only fields requireFollow, followPromptText and notFollowingText; account states carry limitedUntil and messagesSubscribed; activity items carry gateStatus and followup.
Claude (MCP) Methods
getMcpInfo: () => request<McpServerInfoResponse>('/mcp/info'),
getMcpTokens: () => request<McpAccessTokenListResponse>('/mcp/tokens'),
createMcpToken: (data: McpAccessTokenCreateRequest) => request<McpAccessTokenCreateResponse>('/mcp/tokens', { method: 'POST', body: JSON.stringify(data) }),
revokeMcpToken: (id: string) => request<SuccessResponse>(`/mcp/tokens/${id}`, { method: 'DELETE' }),
getMcpClients: () => request<McpClientGrantListResponse>('/mcp/clients'),
approveMcpClient: (data: McpClientApprovalRequest) => request<SuccessResponse>('/mcp/clients', { method: 'POST', body: JSON.stringify(data) }),
revokeMcpClient: (id: string) => request<SuccessResponse>(`/mcp/clients/${id}`, { method: 'DELETE' }),
The types are in shared/types/mcp.ts. Settings, Claude (features/settings/useClaudeAccess.ts) uses all but approveMcpClient, which the consent page (pages/useOAuthConsent.ts) calls before it approves the request with supabase.auth.oauth.approveAuthorization. The token from createMcpToken is kept only in component state until the person dismisses it. These calls manage access; the MCP endpoint itself (/mcp) is never called from the app.
YouTube Publishing and Media Methods
getMedia, registerMedia and uploadWithDetails (a browser upload to Cloudinary that also returns the id, size and dimensions) feed the media library. getYouTubeConnections, getYouTubeAuthUrl(accountId) (Verify on a YouTube card), completeYouTubeConnection and deleteYouTubeConnection (Turn off) serve the publishing row on the Accounts page YouTube cards; getYouTubeUploads, createYouTubeUpload, updateYouTubeUpload, cancelYouTubeUpload and retryYouTubeUpload serve the YouTube uploads page. Types are in shared/types/youtubePublishing.ts and shared/types/media.ts.
Tracked Content Methods
Added to the api object in api.ts. Tracked content is YouTube videos only:
getTrackedContent: () => request<TrackedContentItem[]>('/tracked-content'),
addTrackedContent: (url: string, label: string, category: string) => request<TrackedContentItem>('/tracked-content', { method: 'POST', body: JSON.stringify({ url, label, category }) }),
updateTrackedContent: (id: string, updates: TrackedContentUpdateRequest) => request<TrackedContentItem>(`/tracked-content/${id}`, { method: 'PUT', body: JSON.stringify(updates) }),
deleteTrackedContent: (id: string) => request<SuccessResponse>(`/tracked-content/${id}`, { method: 'DELETE' }),
refreshTrackedContent: (id: string) => request<TrackedContentItem>(`/tracked-content/${id}/refresh`, { method: 'POST' }),
The Worker reads each video with its own YOUTUBE_API_KEY, so an item names no account. A link that is not a YouTube
video answers 400 Only YouTube video links can be tracked. Paste a youtube.com or youtu.be link.
updateTrackedContent takes a partial object, so only the keys present are changed. Accepted
keys are label and category.
Cloudinary Uploads
This is the only call in api.ts that does not go to the Worker.
uploadToCloudinary(file: File, cloudConfig: CloudinaryUploadConfig, { onProgress }: UploadOptions = {}): Promise<string>
Used by publishing. It posts file and the unsigned
upload_preset from getCloudinaryConfig() to
https://api.cloudinary.com/v1_1/<cloudName>/<video|image>/upload (video for video/* files, image otherwise) with XMLHttpRequest, so
upload progress is available, and resolves with the response's secure_url.
cloudConfig:CloudinaryUploadConfig, thecloudNameanduploadPresetfromgetCloudinaryConfig(). Callers check it is set first.onProgress(percent): optional; called with a whole number from 0 to 100. The progress listener is only attached when this is passed.
Failures reject with an UploadError (an Error with a reason of type UploadErrorReason and the extra fields below), so each page keeps its own wording. api.ts exports these types:
reason |
When | Default message |
Extra fields |
|---|---|---|---|
network |
The request lost its connection | The upload lost its network connection |
none |
rejected |
Cloudinary answered with a non-2xx status | Upload failed |
cloudinaryMessage (Cloudinary's error.message, if any) or parseMessage (the body was not JSON) |
The bulk upload shows the default messages. The single post flow maps the error to its own
wording (singleUploadMessage in features/publishing/publishHelpers.ts).
Authentication
The request() function automatically attaches the JWT. Components do not need to handle auth tokens - the API layer manages this transparently. If the user is not logged in, the token will be absent and the backend will return 401, which request() will throw as an error.
Instagram sign-in finishes through api.completeInstagramConnection(code, state): the public OAuth callback hands the code back in the URL fragment, and this authenticated call lets the Worker check that the signed-in person started the sign-in before it connects anything.
Base URL
| Environment | Value |
|---|---|
| Local development | http://localhost:8787/api (default fallback) |
| Production | https://twiligent.ujjwalkrai.workers.dev/api (from VITE_API_URL) |
Set VITE_API_URL in frontend/.env for local development if your Worker runs on a different port.