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.

16.8 KB
Raw Blame
#!/usr/bin/env node
// Instagram scheduled post publisher, run by GitHub Actions every 15 minutes with no npm install.
// Node 22.18+ runs this file directly by stripping its types; it needs SUPABASE_URL and
// SUPABASE_SERVICE_KEY (a sb_secret_ key or the legacy service_role key) as GitHub secrets.

import {
    MAX_PUBLISH_ATTEMPTS, containerStep, fairPublishOrder, failureMessage, failureOutcome, isTransientGraphCode, staleClaimCutoff,
} from '../backend/lib/scheduledPublishing.ts';
import { redactSecrets } from '../backend/lib/redact.ts';
import type { Account, Platform, PostStatus, ScheduledPost } from '../shared/types/domain.ts';
import type { InstagramContainerStatusCode } from '../shared/types/instagram.ts';

interface AccountRow {
    id: string;
    platform: Platform;
    data: Omit<Account, 'id' | 'platform'> | null;
}

interface ScheduledPostRow {
    id: string;
    account_id: string;
    status: PostStatus;
    scheduled_at: string;
    claimed_at: string | null;
    attempts: number | null;
    data: Partial<ScheduledPost> | null;
}

interface GraphResponse {
    id?: string;
    error?: { message: string; code?: number };
    status_code?: InstagramContainerStatusCode;
    status?: string;
}

// the account and container an attempt reached, which the error path needs to ask Instagram what happened
interface Attempt {
    account: Account | null;
    containerId: string | null;
}

// 'left' means the outcome on Instagram is unknown, so the claim stays and a run after the lease decides
type Settled = 'published' | 'retry' | 'failed' | 'left';

// transient marks a failure that may pass on its own, such as a timeout or one of Instagram's temporary codes
class PublishError extends Error {
    readonly transient: boolean;

    constructor(message: string, transient: boolean) {
        super(message);
        this.transient = transient;
    }
}

const SUPABASE_URL = (process.env.SUPABASE_URL || '').replace(/[^\x20-\x7E]/g, '').trim();
const SUPABASE_SERVICE_KEY = (process.env.SUPABASE_SERVICE_KEY || '').replace(/[^\x20-\x7E]/g, '').trim();

if (!SUPABASE_URL || !SUPABASE_SERVICE_KEY) {
    console.error('Error: missing SUPABASE_URL or SUPABASE_SERVICE_KEY');
    console.error('   Add these as GitHub Actions secrets in your repo settings.');
    process.exit(1);
}

const GRAPH_URL = 'https://graph.instagram.com/v25.0';
const POST_COLUMNS = 'id,account_id,status,scheduled_at,claimed_at,attempts,data';
const REQUEST_TIMEOUT_MS = 15000;
// the workflow stops the job at 14 minutes; Instagram calls stop at 12 so every claimed post still gets its outcome saved
const RUN_DEADLINE = AbortSignal.timeout(12 * 60 * 1000);

// Supabase REST helpers (no SDK, native fetch only)

// Legacy service_role keys are JWTs and go in both headers. New sb_secret_ keys are not JWTs
// and Supabase expects them on apikey only.
const sbHeaders: Record<string, string> = {
    'apikey': SUPABASE_SERVICE_KEY,
    ...(SUPABASE_SERVICE_KEY.startsWith('eyJ') ? { 'Authorization': `Bearer ${SUPABASE_SERVICE_KEY}` } : {}),
    'Content-Type': 'application/json',
};

// run logs on a public fork can be read by anyone, so a failed call names only the kind of request and a short,
// redacted answer; the path can hold account ids and the body can echo stored data
async function supabaseFailure(kind: string, res: Response): Promise<Error> {
    return new Error(`Supabase ${kind} failed (status ${res.status}): ${redactSecrets((await res.text()).slice(0, 200))}`);
}

async function sbGet<T>(path: string): Promise<T> {
    const res = await fetch(`${SUPABASE_URL}/rest/v1${path}`, { headers: sbHeaders, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
    if (!res.ok) throw await supabaseFailure('read', res);
    return res.json() as Promise<T>;
}

async function sbRpc(fn: string, args: Record<string, unknown>): Promise<unknown> {
    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/${fn}`, {
        method: 'POST',
        headers: sbHeaders,
        body: JSON.stringify(args),
        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
    });
    if (!res.ok) throw await supabaseFailure(`call ${fn}`, res);
    return res.json();
}

async function sbPatch<T>(path: string, body: unknown): Promise<T[]> {
    const res = await fetch(`${SUPABASE_URL}/rest/v1${path}`, {
        method: 'PATCH',
        headers: { ...sbHeaders, 'Prefer': 'return=representation' },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
    });
    if (!res.ok) throw await supabaseFailure('update', res);
    return res.json() as Promise<T[]>;
}

// Data access

function toPost(row: ScheduledPostRow): ScheduledPost {
    return {
        id: row.id,
        accountId: row.account_id,
        status: row.status,
        scheduledAt: row.scheduled_at,
        ...(row.data || {}),
        claimedAt: row.claimed_at,
        attempts: row.attempts ?? 0,
    };
}

async function getDuePosts(): Promise<ScheduledPost[]> {
    const now = encodeURIComponent(new Date().toISOString());
    const rows = await sbGet<ScheduledPostRow[]>(`/scheduled_posts?status=eq.pending&scheduled_at=lte.${now}&select=${POST_COLUMNS}`);
    return (rows || []).map(toPost);
}

// posts still publishing under a claim older than the lease belong to a run that died
async function getStalePosts(): Promise<ScheduledPost[]> {
    const cutoff = encodeURIComponent(staleClaimCutoff(Date.now()));
    const rows = await sbGet<ScheduledPostRow[]>(`/scheduled_posts?status=eq.publishing&claimed_at=lt.${cutoff}&select=${POST_COLUMNS}`);
    return (rows || []).map(toPost);
}

async function getAccount(accountId: string): Promise<Account | null> {
    const rows = await sbGet<AccountRow[]>(`/accounts?id=eq.${encodeURIComponent(accountId)}&select=id,platform,data`);
    if (!rows || rows.length === 0) return null;
    return { id: rows[0].id, platform: rows[0].platform, ...(rows[0].data || {}) };
}

// one atomic merge in the database (supabase/migrations), the same function the Worker calls
async function updatePost(id: string, updates: Partial<ScheduledPost>): Promise<void> {
    const { status, ...patch } = updates;
    await sbRpc('merge_scheduled_post', { p_id: id, p_user_id: null, p_patch: patch, p_status: status ?? null });
}

// matches only the post as it was listed (pending, or the same expired claim) with the same attempts, as the Worker does
async function claimPost(post: ScheduledPost): Promise<ScheduledPost | null> {
    const attempts = post.attempts ?? 0;
    const unchanged = post.status === 'publishing'
        ? `status=eq.publishing&claimed_at=eq.${encodeURIComponent(post.claimedAt ?? '')}`
        : 'status=eq.pending';
    const rows = await sbPatch<ScheduledPostRow>(
        `/scheduled_posts?id=eq.${encodeURIComponent(post.id)}&attempts=eq.${attempts}&${unchanged}&select=${POST_COLUMNS}`,
        { status: 'publishing', claimed_at: new Date().toISOString(), attempts: attempts + 1 },
    );
    return rows[0] ? toPost(rows[0]) : null;
}

// Instagram publishing

function sleep(ms: number): Promise<void> { return new Promise(r => setTimeout(r, ms)); }

async function graph(method: 'GET' | 'POST', path: string, params: Record<string, string>): Promise<GraphResponse> {
    const url = `${GRAPH_URL}${path}?${new URLSearchParams(params).toString()}`;
    let res: Response;
    try {
        res = await fetch(url, { method, signal: AbortSignal.any([RUN_DEADLINE, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) });
    } catch (err) {
        throw new PublishError(`Instagram API unreachable (${(err as Error).name})`, true);
    }
    const data = await res.json().catch(() => ({})) as GraphResponse;
    // Instagram errors can echo the request url with its access token; the run log may be public, so they are redacted
    if (data.error) throw new PublishError(redactSecrets(data.error.message), isTransientGraphCode(data.error.code));
    if (!res.ok) throw new PublishError(`Instagram answered with status ${res.status}`, res.status >= 500);
    return data;
}

function containerParams(post: ScheduledPost, token: string): Record<string, string> {
    // URLSearchParams needs strings, so the boolean, number and list values are written out here
    const params: Record<string, string> = { access_token: token };
    const tags = post.userTags?.length ? JSON.stringify(post.userTags) : '';

    if (post.mediaType === 'REELS') {
        params.media_type = 'REELS';
        params.video_url = post.mediaUrl ?? '';
        if (post.caption) params.caption = post.caption;
        if (post.shareToFeed !== undefined) params.share_to_feed = String(post.shareToFeed);
        if (post.coverUrl) params.cover_url = post.coverUrl;
        if (post.collaborators?.length) params.collaborators = JSON.stringify(post.collaborators);
        if (post.audioName) params.audio_name = post.audioName;
        if (post.thumbOffset != null) params.thumb_offset = String(post.thumbOffset);
        if (post.locationId) params.location_id = post.locationId;
        if (tags) params.user_tags = tags;
    } else if (post.mediaType === 'STORIES') {
        params.media_type = 'STORIES';
        if (post.mediaUrl?.match(/\.(mp4|mov|avi|webm)/i)) {
            params.video_url = post.mediaUrl;
        } else {
            params.image_url = post.mediaUrl ?? '';
        }
        if (tags) params.user_tags = tags;
    } else {
        params.image_url = post.mediaUrl ?? '';
        if (post.caption) params.caption = post.caption;
        if (post.locationId) params.location_id = post.locationId;
        if (tags) params.user_tags = tags;
        if (post.altText) params.alt_text = post.altText;
    }
    return params;
}

async function containerStatus(containerId: string, token: string): Promise<GraphResponse> {
    return graph('GET', `/${containerId}`, { fields: 'status_code,status', access_token: token });
}

async function waitForContainer(post: ScheduledPost, containerId: string, token: string): Promise<void> {
    if (post.mediaType !== 'REELS' && post.mediaType !== 'STORIES') {
        await sleep(2000);
        return;
    }
    for (let i = 0; i < 60; i++) {
        await sleep(3000);
        const status = await containerStatus(containerId, token);
        if (status.status_code === 'FINISHED' || status.status_code === 'PUBLISHED') return;
        if (status.status_code === 'ERROR') throw new PublishError('Processing failed: ' + redactSecrets(status.status || ''), false);
        if (status.status_code === 'EXPIRED') throw new PublishError('Container expired', false);
    }
    throw new PublishError('Instagram did not finish processing the media within 3 minutes', false);
}

// a container from an earlier attempt is checked first, so a post that already went out is never published again
async function publishToInstagram(post: ScheduledPost, attempt: Attempt): Promise<string | null> {
    const account = await getAccount(post.accountId);
    if (!account) throw new PublishError('The account this post was scheduled for was removed', false);
    if (account.platform !== 'instagram' || !account.igUserId) throw new PublishError('Scheduled posts can only publish to Instagram accounts', false);
    if (!account.accessToken) throw new PublishError('No Instagram access token stored - reconnect this account', false);
    attempt.account = account;
    const igId = account.igUserId;
    const token = account.accessToken;

    if (attempt.containerId) {
        const status = await containerStatus(attempt.containerId, token);
        const step = containerStep(status.status_code ?? 'IN_PROGRESS');
        if (step === 'published') return null;
        if (step === 'fail') throw new PublishError('Processing failed: ' + redactSecrets(status.status || ''), false);
        if (step === 'recreate') attempt.containerId = null;
    }
    if (!attempt.containerId) {
        const created = await graph('POST', `/${igId}/media`, containerParams(post, token));
        if (!created.id) throw new PublishError('Instagram did not return a container id', true);
        await updatePost(post.id, { containerId: created.id });
        attempt.containerId = created.id;
    }

    await waitForContainer(post, attempt.containerId, token);
    const published = await graph('POST', `/${igId}/media_publish`, { creation_id: attempt.containerId, access_token: token });
    return published.id ?? null;
}

// an error before Instagram could have published needs no check; after that, the container's status decides
async function settleFailure(post: ScheduledPost, attempt: Attempt, err: unknown, transientError: boolean): Promise<Settled> {
    let statusCode: InstagramContainerStatusCode | null = null;
    if (attempt.account?.accessToken && attempt.containerId) {
        try {
            statusCode = (await containerStatus(attempt.containerId, attempt.account.accessToken)).status_code ?? 'IN_PROGRESS';
        } catch {
            console.error('  Left for the next run: the container status could not be read');
            return 'left';
        }
    }
    if (statusCode === 'PUBLISHED') {
        await updatePost(post.id, { status: 'published', publishedAt: new Date().toISOString(), error: null });
        return 'published';
    }

    const attempts = post.attempts ?? 1;
    const transient = transientError || statusCode === 'IN_PROGRESS' || statusCode === 'EXPIRED';
    const reason = (err as Error).message;
    if (failureOutcome(transient, attempts) === 'retry') {
        await updatePost(post.id, { status: 'pending', error: reason, ...(statusCode === 'EXPIRED' && { containerId: null }) });
        console.error(`  Will retry (attempt ${attempts} of ${MAX_PUBLISH_ATTEMPTS}): ${reason}`);
        return 'retry';
    }
    await updatePost(post.id, { status: 'failed', error: failureMessage(reason, transient, attempts) });
    console.error(`  Failed: ${reason}`);
    return 'failed';
}

async function settle(post: ScheduledPost, attempt: Attempt, err: unknown, transient: boolean): Promise<Settled> {
    try {
        return await settleFailure(post, attempt, err, transient);
    } catch (writeErr) {
        // the claim stays, so the next run after the lease finds out what happened from the saved container
        console.error(`  Left for the next run: the outcome could not be saved (${(writeErr as Error).message})`);
        return 'left';
    }
}

async function publishClaimed(post: ScheduledPost): Promise<Settled> {
    const attempt: Attempt = { account: null, containerId: post.containerId ?? null };

    // a post taken over after its last attempt is only checked on Instagram, never started again
    if ((post.attempts ?? 1) > MAX_PUBLISH_ATTEMPTS) {
        attempt.account = await getAccount(post.accountId).catch(() => null);
        return settle(post, attempt, new Error('The publishing run stopped before it finished.'), true);
    }

    try {
        const mediaId = await publishToInstagram(post, attempt);
        await updatePost(post.id, { status: 'published', publishedMediaId: mediaId, publishedAt: new Date().toISOString(), error: null });
        console.log(`  Published: media ${mediaId ?? '(already published by an earlier attempt)'}`);
        return 'published';
    } catch (err) {
        // anything that is not Instagram's answer is the database or the network, which may pass on its own
        return settle(post, attempt, err, err instanceof PublishError ? err.transient : true);
    }
}

// Main

async function main(): Promise<void> {
    console.log('Instagram scheduled post publisher');
    console.log(`   Time: ${new Date().toISOString()}\n`);

    const [stalePosts, duePosts] = await Promise.all([getStalePosts(), getDuePosts()]);
    // the same order as the Worker: stale claims first, then due posts taking turns by account
    const candidates = [...stalePosts, ...fairPublishOrder(duePosts)];

    if (candidates.length === 0) {
        console.log('No posts due for publishing');
        process.exit(0);
    }

    console.log(`${candidates.length} post(s) due for publishing\n`);
    let processed = 0;

    for (const candidate of candidates) {
        // past the deadline every Instagram call fails, so a new claim would only sit out the lease
        if (RUN_DEADLINE.aborted) break;
        console.log(`  Publishing: ${candidate.id} (${candidate.mediaType}) - scheduled ${candidate.scheduledAt}`);
        let post: ScheduledPost | null;
        try {
            post = await claimPost(candidate);
        } catch (err) {
            console.error(`  Skipped: the claim could not be saved (${(err as Error).message})`);
            continue;
        }
        if (!post) {
            console.log('  Skipped: already claimed by the other scheduler');
            continue;
        }
        if (candidate.status === 'publishing') console.log(`  Taken over: the claim from ${candidate.claimedAt} expired`);
        if (await publishClaimed(post) === 'published') processed++;
    }

    console.log(`\nResults: ${processed}/${candidates.length} published`);
    process.exit(0);
}

main().catch(err => {
    console.error('Fatal error:', redactSecrets(err instanceof Error ? err.message : String(err)));
    process.exit(1);
});