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.

11.8 KB
Raw Blame
import {
    BLOCKED_COOLDOWN_MS, DEFAULT_COOLDOWN_MS, HOLD_RECHECK_MS, MAX_SEND_ATTEMPTS, NOT_SENT_RETRY_MS, classifySendError, cooldownFromUsage, retryDelayMs,
} from './automationDelivery.ts';
import type { ReleasePlan, ReserveOutcome, SendErrorKind, SendResult } from './automationDelivery.ts';
import type { AutomationAttemptOutcome, AutomationPublicReplyStatus } from '../../shared/types/automation.ts';

// the rules for a public reply under a comment; the private reply's rules are in automationDelivery.ts

// a rule rotates between at most five texts, so a busy post does not fill with the same words
export const MAX_PUBLIC_REPLY_TEXTS = 5;
// Instagram allows 2,200 characters in a comment; a short reply reads as a person's and is less likely to look like spam
export const MAX_PUBLIC_REPLY_CHARS = 300;
// Instagram's older API refused comments with more than 4 hashtags or more than 1 link; the same bounds keep replies safe
const MAX_PUBLIC_HASHTAGS = 4;
const MAX_PUBLIC_LINKS = 1;

// reserve, send and finish
export const SUBREQUESTS_PER_PUBLIC_REPLY = 3;

// a lost answer is looked for five minutes after the attempt, then every five minutes; the comment's replies show up
// within seconds, so two checks that miss it mean it never arrived
export const PUBLIC_REVIEW_SETTLE_SECONDS = 5 * 60;
export const PUBLIC_REVIEW_RECHECK_SECONDS = 5 * 60;
export const PUBLIC_REVIEW_MAX_CHECKS = 3;
const RESEND_AFTER_CHECKS = 2;
// a reply is sent again at most once after a lost answer; a second lost answer is left to a person
const MAX_LOST_ANSWERS_BEFORE_RESEND = 1;
// each check reads up to two pages of replies and records what it found
export const MAX_REPLY_PAGES = 2;
export const SUBREQUESTS_PER_PUBLIC_REVIEW = MAX_REPLY_PAGES + 1;
export const PUBLIC_REVIEW_BATCH = 5;

// Graph API code 100 with subcode 33: the comment no longer exists or cannot be seen, as for a deleted or hidden comment
const MISSING_OBJECT_CODE = 100;
const MISSING_OBJECT_SUBCODE = 33;

const HASHTAG = /(^|\s)#[\p{L}\p{N}_]+/gu;
const LINK = /\bhttps?:\/\/\S+|\bwww\.\S+/gi;

// one claimed public reply, as the delivery rules need it; attempts already counts the send being settled
export interface PublicReplyJob {
    attempts: number;
    expiresAt: string;
}

// one finish_automation_public_reply call
export interface PublicFinishPlan {
    status: AutomationPublicReplyStatus;
    outcome: AutomationAttemptOutcome;
    reason: string | null;
    errorMessage: string | null;
    replyId: string | null;
    errorCode: number | null;
    errorSubcode: number | null;
    httpStatus: number | null;
    nextAttemptAt: string | null;
    cooldownUntil: string | null;
    cooldownReason: string | null;
    pauseReason: string | null;
}

export const PUBLIC_ERROR_MESSAGES: Record<SendErrorKind, string> = {
    rate_limited: 'Instagram is limiting this account\'s requests for now. The public reply goes out after the cooldown.',
    blocked: 'Instagram has temporarily blocked comments from this account. Public replies wait a day; check the account in the Instagram app. Private replies are not affected.',
    transient: 'Instagram had a temporary problem. The public reply is tried again.',
    already_replied: 'Instagram refused the public reply.',
    not_authorized: 'Instagram refused this account\'s permission to reply to comments. Replies are held: reconnect the account on the Accounts page, then resume it.',
    not_eligible: 'Instagram does not allow a public reply to this comment: it may be deleted or hidden, or on a live video.',
    refused: 'Instagram refused the public reply.',
};

const PUBLIC_LIMIT_MESSAGES: Partial<Record<ReserveOutcome, string>> = {
    cooldown: 'Waiting for Instagram\'s cooldown on this account\'s public replies to end.',
    account_limit: 'Waiting: this account reached its hourly limit for public replies.',
};

const PUBLIC_EXPIRED_MESSAGE = 'This public reply waited 7 days without going out, so Twiligent stopped trying.';

// what is wrong with one public reply text, or null when Instagram should take it
export function publicReplyTextProblem(text: string): string | null {
    if (text.length > MAX_PUBLIC_REPLY_CHARS) return `A public reply can be at most ${MAX_PUBLIC_REPLY_CHARS} characters`;
    if ((text.match(HASHTAG) ?? []).length > MAX_PUBLIC_HASHTAGS) return `A public reply can have at most ${MAX_PUBLIC_HASHTAGS} hashtags`;
    if ((text.match(LINK) ?? []).length > MAX_PUBLIC_LINKS) return `A public reply can have at most ${MAX_PUBLIC_LINKS} link; put the rest in the private reply`;
    return null;
}

// the same comment always gets the same text, so a redelivered notification and every check agree on the words;
// FNV-1a spreads neighbouring comment ids across the texts
export function pickPublicReplyText(texts: string[], commentId: string): string {
    let hash = 0x811c9dc5;
    for (let index = 0; index < commentId.length; index++) {
        hash ^= commentId.charCodeAt(index);
        hash = Math.imul(hash, 0x01000193) >>> 0;
    }
    return texts[hash % texts.length];
}

// a wait that ends after the reply's 7 days would only fail, so it expires instead
function waitUntil(at: number, job: PublicReplyJob, reason: string, message: string): Pick<PublicFinishPlan, 'status' | 'reason' | 'errorMessage' | 'nextAttemptAt'> {
    if (at >= Date.parse(job.expiresAt)) return { status: 'expired', reason: 'expired', errorMessage: PUBLIC_EXPIRED_MESSAGE, nextAttemptAt: null };
    return { status: 'retry_wait', reason, errorMessage: message, nextAttemptAt: new Date(at).toISOString() };
}

function emptyPlan(): Omit<PublicFinishPlan, 'status' | 'outcome'> {
    return {
        reason: null, errorMessage: null, replyId: null, errorCode: null, errorSubcode: null, httpStatus: null,
        nextAttemptAt: null, cooldownUntil: null, cooldownReason: null, pauseReason: null,
    };
}

// what to record for the answer to one public reply; accepted only when Instagram returned the new reply's id
export function publicFinishPlan(result: SendResult, job: PublicReplyJob, now: number, random: () => number = Math.random): PublicFinishPlan {
    if (result.kind === 'accepted') return { ...emptyPlan(), status: 'accepted', outcome: 'accepted', replyId: result.messageId };
    if (result.kind === 'not_sent') {
        return { ...emptyPlan(), ...waitUntil(now + NOT_SENT_RETRY_MS, job, 'not_sent', `The public 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 public reply may or may not be there. Twiligent checks the comment's replies and sends it again only if it is not there.`,
        };
    }

    const details = { ...emptyPlan(), errorCode: result.code ?? null, errorSubcode: result.subcode ?? null, httpStatus: result.httpStatus };
    const kind: SendErrorKind = result.code === MISSING_OBJECT_CODE && result.subcode === MISSING_OBJECT_SUBCODE ? 'not_eligible' : classifySendError(result);
    const message = kind === 'refused' || kind === 'already_replied'
        ? `${PUBLIC_ERROR_MESSAGES.refused} ${result.message}`.trim().slice(0, 500)
        : PUBLIC_ERROR_MESSAGES[kind];

    if (kind === 'rate_limited' || kind === 'blocked') {
        const until = now + (kind === 'blocked' ? BLOCKED_COOLDOWN_MS : cooldownFromUsage(result.usageHeader));
        return {
            ...details,
            ...waitUntil(until, job, kind, message),
            outcome: kind === 'rate_limited' ? 'rate_limited' : 'rejected',
            cooldownUntil: new Date(until).toISOString(),
            cooldownReason: PUBLIC_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 === 'not_eligible') return { ...details, status: 'skipped', outcome: 'rejected', reason: kind, errorMessage: message };
    if (kind === 'not_authorized') {
        // the token is the account's, so private replies are held too 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: PUBLIC_ERROR_MESSAGES.not_authorized,
        };
    }
    const finalMessage = kind === 'transient' ? `Instagram had a temporary problem. Sending stopped after ${MAX_SEND_ATTEMPTS} tries.` : message;
    return { ...details, status: 'failed', outcome: 'rejected', reason: kind, errorMessage: finalMessage };
}

// a claimed public reply that cannot go out as it is, checked before any limit is spent; null means it may go ahead
export function publicReadinessPlan(job: { ruleEnabled: boolean; accessToken: string | null; expiresAt: string }, now: number): ReleasePlan | null {
    if (now >= Date.parse(job.expiresAt)) return { status: 'expired', reason: 'expired', errorMessage: PUBLIC_EXPIRED_MESSAGE, nextAttemptAt: null };
    if (!job.ruleEnabled) {
        return { status: 'skipped', reason: 'rule_disabled', errorMessage: 'The rule, or its public reply, was turned off 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 public reply goes when the reservation says no; null when it was sent (ok) or is no longer this run's (gone)
export function publicReleasePlan(outcome: ReserveOutcome, retryAt: string | null, job: PublicReplyJob, 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 got a public reply on this post today, so no second one was sent.', nextAttemptAt: null };
    }
    const at = retryAt ? Date.parse(retryAt) : now + DEFAULT_COOLDOWN_MS;
    const message = PUBLIC_LIMIT_MESSAGES[outcome] ?? 'Waiting for a limit on public replies to free up.';
    const { status, reason, errorMessage, nextAttemptAt } = waitUntil(at, job, outcome, message);
    return { status, reason: reason ?? outcome, errorMessage, nextAttemptAt };
}

// whether a reply not found among the comment's replies goes out again: only when every reply was read, on enough
// checks minutes apart, and it was not already sent again once
export function shouldResend({ complete, checks, lostAnswers }: { complete: boolean; checks: number; lostAnswers: number }): boolean {
    return complete && checks >= RESEND_AFTER_CHECKS && lostAnswers <= MAX_LOST_ANSWERS_BEFORE_RESEND;
}

// what the person sees on a public reply that was looked for and not found, after this many checks
export function publicReviewNote({ complete, checks }: { complete: boolean; checks: number }): string {
    if (!complete) return 'Twiligent could not read every reply on this comment, so it does not send the public reply again. Check the comment on Instagram before you retry.';
    if (checks < PUBLIC_REVIEW_MAX_CHECKS) return 'Twiligent checked the comment\'s replies and did not find this public reply. It looks again in a few minutes.';
    return 'Twiligent checked the comment\'s replies several times and did not find this public reply. Check the comment on Instagram before you retry.';
}