Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
import type {
AutomationAttemptOutcome, AutomationCommentStatus, AutomationFollowupKind, AutomationGateStatus,
} from '../../shared/types/automation.ts';
// Instagram refuses message text longer than 1,000 bytes
export const MAX_MESSAGE_BYTES = 1000;
// Instagram accepts a private reply for 7 days after the comment
export const REPLY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
// a run holding a job longer than this has stopped: a sweep ends within 15 minutes and a webhook's work within 30 seconds
export const CLAIM_LEASE_SECONDS = 20 * 60;
// five tries over about half an hour give a passing Instagram problem time to clear without retrying forever
export const MAX_SEND_ATTEMPTS = 5;
// a webhook's background work has 30 seconds in all, so one send may take a third of it
export const SEND_TIMEOUT_MS = 10_000;
// the Workers Free plan allows 50 subrequests per invocation; a run that hits the cap cannot even record what happened
export const FREE_PLAN_SUBREQUESTS = 50;
// a request's own middleware and queries (authentication, rate limits, its writes) stay under this before background work starts
export const REQUEST_SUBREQUESTS = 10;
// reserve, send and finish; a reply stopped before sending costs one release instead
export const SUBREQUESTS_PER_REPLY = 3;
// background work after a response gets 25 seconds; a send starts only with its whole timeout and a margin left
export const BACKGROUND_RUN_MS = 20_000;
// new and retried jobs are due a little in the past, so a database clock slightly behind the Worker's still sees them as due
export const DUE_NOW_SKEW_MS = 30_000;
// a follow-up costs the follow check as well as reserve, send and finish
export const SUBREQUESTS_PER_FOLLOWUP = 4;
// the follow check is a read and safe to ask again, so it gets less time than a send: both fit a webhook's 20 seconds
export const FOLLOW_CHECK_TIMEOUT_MS = 5_000;
// a person who does not follow yet is reminded at most twice, then the wait ends
export const MAX_FOLLOW_REMINDERS = 2;
// a follow check Instagram could not answer now is asked again on a later run
const FOLLOW_CHECK_RETRY_MS = 5 * 60 * 1000;
// a reply held by a pause is looked at again on a later sweep, not every five minutes for a week
export const HOLD_RECHECK_MS = 15 * 60 * 1000;
// backoff: 1, 2, 4, 8 minutes, then at most an hour, plus up to 30 seconds so retries of one burst spread out
const BACKOFF_BASE_MS = 60 * 1000;
const BACKOFF_MAX_MS = 60 * 60 * 1000;
const BACKOFF_JITTER_MS = 30 * 1000;
// the next sweep, when a run could not start the request
export const NOT_SENT_RETRY_MS = 5 * 60 * 1000;
// used when Instagram limits the account without saying for how long
export const DEFAULT_COOLDOWN_MS = 15 * 60 * 1000;
// code 368 is a temporary block for activity Instagram considers abusive, so the account rests for a day
export const BLOCKED_COOLDOWN_MS = 24 * 60 * 60 * 1000;
// Graph API codes Meta documents for throttling: app, user, page and business use case limits
const RATE_LIMIT_CODES = new Set([4, 17, 32, 613, 80002, 80006]);
// unknown and service errors that Meta says to retry later
const TRANSIENT_CODES = new Set([1, 2]);
// the comment is deleted, too old, or its author does not accept messages
const NOT_ELIGIBLE_CODES = new Set([551, 10903]);
const NOT_ELIGIBLE_SUBCODES = new Set([2534014, 2534022, 2534025, 2018001]);
// a second private reply to one comment
const ALREADY_REPLIED_CODE = 10900;
const ALREADY_REPLIED_SUBCODE = 2534023;
// the token is invalid, or the account does not grant or allow messaging
const NOT_AUTHORIZED_CODES = new Set([3, 190, 200]);
const NOT_AUTHORIZED_SUBCODES = new Set([2534041]);
export type SendErrorKind = 'rate_limited' | 'blocked' | 'transient' | 'already_replied' | 'not_authorized' | 'not_eligible' | 'refused';
export interface GraphSendError {
code?: number;
subcode?: number;
httpStatus: number;
message: string;
}
// what one request to Instagram's messages endpoint came back as; ambiguous means it may have been delivered,
// not_sent that the Worker refused to start the request
export type SendResult =
| { kind: 'accepted'; messageId: string | null; recipientId: string | null }
| ({ kind: 'error'; usageHeader: string | null } & GraphSendError)
| { kind: 'ambiguous'; message: string }
| { kind: 'not_sent'; message: string };
// a claimed job, as the delivery rules need it; attempts already counts the send being settled
export interface DeliveryJob {
attempts: number;
expiresAt: string;
// who the reply goes to when Instagram does not name them, and whether it starts a followers-only wait
fromId?: string | null;
awaitsReply?: boolean;
// a follow-up's window is Instagram's 24 hours, not the 7 days of a private reply
expiredMessage?: string;
}
// what Instagram said about whether the person follows the account; retry means it could not answer now
export type FollowCheck =
| { kind: 'following' }
| { kind: 'not_following' }
| { kind: 'unverifiable'; message: string }
| { kind: 'not_authorized'; message: string }
| { kind: 'retry'; message: string };
// a claimed follow-up, as the follow-up rules need it
export interface FollowupJob {
attempts: number;
windowExpiresAt: string;
ruleEnabled: boolean;
requireFollow: boolean;
gateStatus: AutomationGateStatus | null;
gatePrompts: number;
replyText: string | null;
linkUrl: string | null;
notFollowingText: string | null;
accessToken: string | null;
}
// the message a follow check leads to, and what its acceptance does to the comment's wait
export interface FollowupMessage {
kind: AutomationFollowupKind;
text: string;
gateStatus: AutomationGateStatus | null;
countReminder: boolean;
}
// one finish_automation_send or finish_automation_followup call
export interface FinishPlan {
status: AutomationCommentStatus;
outcome: AutomationAttemptOutcome;
reason: string | null;
errorMessage: string | null;
messageId: string | null;
errorCode: number | null;
errorSubcode: number | null;
httpStatus: number | null;
nextAttemptAt: string | null;
cooldownUntil: string | null;
cooldownReason: string | null;
pauseReason: string | null;
// who Instagram says received an accepted reply, and the followers-only wait it starts or ends
recipientId: string | null;
gateStatus: AutomationGateStatus | null;
}
// a job given back without sending: where it goes and why
export interface ReleasePlan {
status: AutomationCommentStatus;
reason: string;
errorMessage: string | null;
nextAttemptAt: string | null;
}
export type ReserveOutcome =
| 'ok' | 'gone' | 'paused' | 'cooldown' | 'recipient_limit'
| 'rule_limit' | 'account_limit' | 'user_limit' | 'global_limit';
export const SEND_ERROR_MESSAGES: Record<SendErrorKind, string> = {
rate_limited: 'Instagram is limiting replies from this account for now. The reply goes out after the cooldown.',
blocked: 'Instagram has temporarily blocked private replies from this account. Replies wait a day; check the account in the Instagram app.',
transient: 'Instagram had a temporary problem. The reply is tried again.',
already_replied: 'Instagram says this comment already has a private reply, so a second one was not sent.',
not_authorized: 'Instagram refused this account\'s permission to send messages. Replies are held: reconnect the account on the Accounts page, check that it allows access to messages in the Instagram app, then resume it.',
not_eligible: 'Instagram does not allow a private reply to this comment: it may be deleted or older than 7 days, or its author does not accept messages.',
refused: 'Instagram refused the reply.',
};
const LIMIT_MESSAGES: Record<Exclude<ReserveOutcome, 'ok' | 'gone' | 'paused' | 'recipient_limit'>, string> = {
cooldown: 'Waiting for Instagram\'s cooldown on this account to end.',
rule_limit: 'Waiting: this rule reached its hourly reply limit.',
account_limit: 'Waiting: this account reached its hourly reply limit.',
user_limit: 'Waiting: your accounts reached their combined hourly reply limit.',
global_limit: 'Waiting: this Twiligent instance reached its hourly reply limit.',
};
const EXPIRED_MESSAGE = 'The 7 days in which Instagram allows a private reply to this comment ran out.';
export const FOLLOWUP_EXPIRED_MESSAGE = 'The 24 hours in which Instagram allows a message after the person\'s reply ran out.';
export function composeReply(replyText: string, linkUrl: string | null): string {
return linkUrl ? `${replyText}\n\n${linkUrl}` : replyText;
}
export function messageBytes(message: string): number {
return new TextEncoder().encode(message).length;
}
export function expiresAtFor(notifiedAt: Date): string {
return new Date(notifiedAt.getTime() + REPLY_WINDOW_MS).toISOString();
}
// sha-256 of the text sent, so a reply whose answer was lost can be recognised in the conversation later
export async function messageDigest(text: string): Promise<string> {
const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
return [...new Uint8Array(hash)].map(byte => byte.toString(16).padStart(2, '0')).join('');
}
// the private reply a job sends: the request to follow and answer for a followers-only rule, the reply and link otherwise
export function replyMessage(job: { requireFollow: boolean; followPromptText: string | null; replyText: string; linkUrl: string | null }): string {
return job.requireFollow && job.followPromptText ? job.followPromptText : composeReply(job.replyText, job.linkUrl);
}
export function classifySendError({ code, subcode, httpStatus }: GraphSendError): SendErrorKind {
if (httpStatus === 429 || (code !== undefined && RATE_LIMIT_CODES.has(code))) return 'rate_limited';
if (code === 368) return 'blocked';
if (code === ALREADY_REPLIED_CODE || subcode === ALREADY_REPLIED_SUBCODE) return 'already_replied';
if (subcode !== undefined && NOT_ELIGIBLE_SUBCODES.has(subcode)) return 'not_eligible';
if (code !== undefined && NOT_ELIGIBLE_CODES.has(code)) return 'not_eligible';
if (subcode !== undefined && NOT_AUTHORIZED_SUBCODES.has(subcode)) return 'not_authorized';
// a bare code 10 is a missing permission; with a subcode it is about the recipient, handled above
if ((code !== undefined && NOT_AUTHORIZED_CODES.has(code)) || (code === 10 && subcode === undefined)) return 'not_authorized';
if ((code !== undefined && TRANSIENT_CODES.has(code)) || httpStatus >= 500) return 'transient';
return 'refused';
}
// waits 1, 2, 4 and 8 minutes after the first four tries, never more than an hour
export function retryDelayMs(attempts: number, random: () => number = Math.random): number {
const backoff = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempts - 1));
return backoff + Math.floor(random() * BACKOFF_JITTER_MS);
}
// Meta's X-Business-Use-Case-Usage header says, per business, how many minutes until calls are allowed again
export function cooldownFromUsage(usageHeader: string | null): number {
if (!usageHeader) return DEFAULT_COOLDOWN_MS;
try {
const usage = JSON.parse(usageHeader) as Record<string, { estimated_time_to_regain_access?: number }[]>;
const minutes = Object.values(usage).flat().map(entry => entry.estimated_time_to_regain_access ?? 0);
const longest = Math.max(0, ...minutes);
return longest > 0 ? Math.min(BLOCKED_COOLDOWN_MS, longest * 60 * 1000) : DEFAULT_COOLDOWN_MS;
} catch {
// a header Meta changed is not a reason to stop; the default cooldown still protects the account
return DEFAULT_COOLDOWN_MS;
}
}
function emptyPlan(): Omit<FinishPlan, 'status' | 'outcome'> {
return {
reason: null, errorMessage: null, messageId: null, errorCode: null, errorSubcode: null, httpStatus: null,
nextAttemptAt: null, cooldownUntil: null, cooldownReason: null, pauseReason: null, recipientId: null, gateStatus: null,
};
}
// a wait that ends after Instagram's reply window would only fail, so the job expires instead
function waitUntil(at: number, job: DeliveryJob, reason: string, message: string): Pick<FinishPlan, 'status' | 'reason' | 'errorMessage' | 'nextAttemptAt'> {
if (at >= Date.parse(job.expiresAt)) return { status: 'expired', reason: 'expired', errorMessage: job.expiredMessage ?? EXPIRED_MESSAGE, nextAttemptAt: null };
return { status: 'retry_wait', reason, errorMessage: message, nextAttemptAt: new Date(at).toISOString() };
}
// what to record for the answer to one send
export function finishPlan(result: SendResult, job: DeliveryJob, now: number, random: () => number = Math.random): FinishPlan {
if (result.kind === 'accepted') {
return {
...emptyPlan(),
status: 'accepted',
outcome: 'accepted',
messageId: result.messageId,
recipientId: result.recipientId ?? job.fromId ?? null,
gateStatus: job.awaitsReply ? 'awaiting_reply' : null,
};
}
if (result.kind === 'not_sent') {
return { ...emptyPlan(), ...waitUntil(now + NOT_SENT_RETRY_MS, job, 'not_sent', `The reply was not sent (${result.message}). It is tried again on the next run.`), outcome: 'rejected' };
}
if (result.kind === 'ambiguous') {
return {
...emptyPlan(),
status: 'needs_review',
outcome: 'ambiguous',
reason: 'no_answer',
errorMessage: `Instagram did not answer (${result.message}), so the reply may or may not have been sent. Check the conversation on Instagram before you retry.`,
};
}
const kind = classifySendError(result);
const details = { ...emptyPlan(), errorCode: result.code ?? null, errorSubcode: result.subcode ?? null, httpStatus: result.httpStatus };
const message = kind === 'refused' ? `${SEND_ERROR_MESSAGES.refused} ${result.message}`.trim() : SEND_ERROR_MESSAGES[kind];
if (kind === 'rate_limited' || kind === 'blocked') {
const until = now + (kind === 'blocked' ? BLOCKED_COOLDOWN_MS : cooldownFromUsage(result.usageHeader));
const cooldownUntil = new Date(until).toISOString();
return {
...details,
...waitUntil(until, job, kind, message),
outcome: kind === 'rate_limited' ? 'rate_limited' : 'rejected',
cooldownUntil,
cooldownReason: SEND_ERROR_MESSAGES[kind],
};
}
if (kind === 'transient' && job.attempts < MAX_SEND_ATTEMPTS) {
return { ...details, ...waitUntil(now + retryDelayMs(job.attempts, random), job, kind, message), outcome: 'rejected' };
}
if (kind === 'already_replied') {
return { ...details, status: 'skipped', outcome: 'rejected', reason: kind, errorMessage: message };
}
if (kind === 'not_authorized') {
// the reply did not go out, so it waits with the account's other replies until the owner fixes the account
return {
...details,
status: 'queued',
outcome: 'rejected',
reason: 'paused',
errorMessage: message,
nextAttemptAt: new Date(now + HOLD_RECHECK_MS).toISOString(),
pauseReason: SEND_ERROR_MESSAGES.not_authorized,
};
}
const finalMessage = kind === 'transient' ? `${message.replace(/ The reply is tried again\.$/, '')} Sending stopped after ${MAX_SEND_ATTEMPTS} tries.` : message;
return { ...details, status: 'failed', outcome: 'rejected', reason: kind, errorMessage: finalMessage };
}
// a claimed job that cannot be sent as it is, checked before any limit is spent; null means it may go ahead. ruleEnabled
// is false once the rule or its private reply is off
export function readinessPlan(job: { ruleEnabled: boolean; accessToken: string | null; expiresAt: string }, now: number): ReleasePlan | null {
if (now >= Date.parse(job.expiresAt)) return { status: 'expired', reason: 'expired', errorMessage: EXPIRED_MESSAGE, nextAttemptAt: null };
if (!job.ruleEnabled) {
return { status: 'skipped', reason: 'rule_disabled', errorMessage: 'The rule, or its private reply, was turned off or removed before the reply was sent.', nextAttemptAt: null };
}
if (!job.accessToken) {
return { status: 'failed', reason: 'not_connected', errorMessage: 'The Instagram account has no access token. Reconnect it on the Accounts page, then retry.', nextAttemptAt: null };
}
return null;
}
// where a job goes when the reservation says no; null when it was sent (ok) or is no longer this run's (gone)
export function releasePlan(outcome: ReserveOutcome, retryAt: string | null, job: DeliveryJob, now: number): ReleasePlan | null {
if (outcome === 'ok' || outcome === 'gone') return null;
if (outcome === 'paused') {
return { status: 'queued', reason: 'paused', errorMessage: 'Held while automation for this account is paused.', nextAttemptAt: new Date(now + HOLD_RECHECK_MS).toISOString() };
}
if (outcome === 'recipient_limit') {
return { status: 'skipped', reason: outcome, errorMessage: 'This person already received the most private replies allowed in a day, so no more were sent.', nextAttemptAt: null };
}
const at = retryAt ? Date.parse(retryAt) : now + DEFAULT_COOLDOWN_MS;
const { status, reason, errorMessage, nextAttemptAt } = waitUntil(at, job, outcome, LIMIT_MESSAGES[outcome]);
return { status, reason: reason ?? outcome, errorMessage, nextAttemptAt };
}
// a claimed follow-up that cannot go ahead, checked before Instagram is asked anything; null means it may
export function followupReadiness(job: FollowupJob, now: number): ReleasePlan | null {
if (now >= Date.parse(job.windowExpiresAt)) return { status: 'expired', reason: 'expired', errorMessage: FOLLOWUP_EXPIRED_MESSAGE, nextAttemptAt: null };
if (!job.ruleEnabled) {
return { status: 'skipped', reason: 'rule_disabled', errorMessage: 'The rule was turned off or removed before the follow-up was sent.', nextAttemptAt: null };
}
if (!job.requireFollow) {
return { status: 'skipped', reason: 'rule_changed', errorMessage: 'The rule no longer asks people to follow, so no follow-up was sent.', nextAttemptAt: null };
}
if (job.gateStatus !== 'awaiting_reply') {
return { status: 'skipped', reason: 'answered', errorMessage: 'This person already got the link or every reminder.', nextAttemptAt: null };
}
if (!job.accessToken) {
return { status: 'failed', reason: 'not_connected', errorMessage: 'The Instagram account has no access token. Reconnect it on the Accounts page, then retry.', nextAttemptAt: null };
}
return null;
}
// what the follow check leads to: a message to send, or why nothing is sent. Only a confirmed follow sends the link
export function followupMessage(check: FollowCheck, job: FollowupJob, now: number): { message: FollowupMessage } | { release: ReleasePlan } {
if (check.kind === 'following') {
return { message: { kind: 'link', text: composeReply(job.replyText ?? '', job.linkUrl), gateStatus: 'completed', countReminder: false } };
}
if (check.kind === 'not_following') {
if (job.gatePrompts >= MAX_FOLLOW_REMINDERS || !job.notFollowingText) {
return { release: { status: 'skipped', reason: 'reminders_used', errorMessage: 'This person does not follow the account and already got every reminder.', nextAttemptAt: null } };
}
const last = job.gatePrompts + 1 >= MAX_FOLLOW_REMINDERS;
return { message: { kind: 'reminder', text: job.notFollowingText, gateStatus: last ? 'closed' : null, countReminder: true } };
}
if (check.kind === 'unverifiable') {
return {
release: {
status: 'failed',
reason: 'follow_unverifiable',
errorMessage: `Instagram did not say whether this person follows the account (${check.message}), so the link was not sent.`.slice(0, 500),
nextAttemptAt: null,
},
};
}
if (check.kind === 'not_authorized') {
return {
release: {
status: 'failed',
reason: 'not_authorized',
errorMessage: 'Instagram refused this account\'s permission to check followers or send messages. Reconnect the account on the Accounts page, then retry.',
nextAttemptAt: null,
},
};
}
const wait = waitUntil(now + FOLLOW_CHECK_RETRY_MS, { attempts: job.attempts, expiresAt: job.windowExpiresAt, expiredMessage: FOLLOWUP_EXPIRED_MESSAGE },
'follow_check', `Instagram could not answer the follow check (${check.message}). It is asked again in a few minutes.`);
return { release: { status: wait.status, reason: wait.reason ?? 'follow_check', errorMessage: wait.errorMessage, nextAttemptAt: wait.nextAttemptAt } };
}