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 {
AutomationAccountState, AutomationActivityItem, AutomationCommentStatus, AutomationMatchMode, AutomationPublicReplyState, AutomationPublicReplyStatus,
AutomationRule, AutomationRuleRequest, AutomationStats,
} from '../../../../shared/types/automation.ts';
export type BadgeTone = 'success' | 'destructive' | 'warning' | 'info' | 'secondary';
export interface StatusDisplay {
label: string;
tone: BadgeTone;
}
// accepted means Instagram took the request; it does not report whether the person has read the message
export const STATUS_DISPLAY: Record<AutomationCommentStatus, StatusDisplay> = {
ignored: { label: 'No match', tone: 'secondary' },
queued: { label: 'Waiting', tone: 'warning' },
processing: { label: 'Sending', tone: 'info' },
retry_wait: { label: 'Trying again', tone: 'warning' },
sending: { label: 'Sending', tone: 'info' },
accepted: { label: 'Accepted by Instagram', tone: 'success' },
failed: { label: 'Failed', tone: 'destructive' },
needs_review: { label: 'Needs review', tone: 'warning' },
skipped: { label: 'Skipped', tone: 'secondary' },
expired: { label: 'Expired', tone: 'secondary' },
};
// a public reply is accepted only with the id Instagram gave it, so it is shown as posted
export const PUBLIC_STATUS_DISPLAY: Record<AutomationPublicReplyStatus, StatusDisplay> = {
queued: { label: 'Waiting', tone: 'warning' },
processing: { label: 'Posting', tone: 'info' },
retry_wait: { label: 'Trying again', tone: 'warning' },
sending: { label: 'Posting', tone: 'info' },
accepted: { label: 'Posted', tone: 'success' },
failed: { label: 'Failed', tone: 'destructive' },
needs_review: { label: 'Checking', tone: 'warning' },
skipped: { label: 'Skipped', tone: 'secondary' },
expired: { label: 'Expired', tone: 'secondary' },
};
export type ActivityFilter = 'all' | 'accepted' | 'waiting' | 'attention' | 'skipped' | 'ignored';
export const ACTIVITY_FILTERS: Record<ActivityFilter, { label: string; statuses: AutomationCommentStatus[] | null }> = {
all: { label: 'All', statuses: null },
accepted: { label: 'Accepted', statuses: ['accepted'] },
waiting: { label: 'Waiting', statuses: ['queued', 'processing', 'retry_wait', 'sending'] },
attention: { label: 'Needs attention', statuses: ['failed', 'needs_review'] },
skipped: { label: 'Skipped or expired', statuses: ['skipped', 'expired'] },
ignored: { label: 'No match', statuses: ['ignored'] },
};
export type StatsPeriod = '24h' | '7d' | '30d';
const HOUR_MS = 60 * 60 * 1000;
export const STATS_PERIODS: Record<StatsPeriod, { label: string; ms: number }> = {
'24h': { label: 'Last 24 hours', ms: 24 * HOUR_MS },
'7d': { label: 'Last 7 days', ms: 7 * 24 * HOUR_MS },
'30d': { label: 'Last 30 days', ms: 30 * 24 * HOUR_MS },
};
// Instagram refuses message text longer than 1,000 bytes; the Worker checks the same
export const MAX_MESSAGE_BYTES = 1000;
const MAX_KEYWORDS = 10;
const MAX_HOURLY_LIMIT = 750;
// the Worker's bounds for public replies: a few short texts, few hashtags and one link at most
export const MAX_PUBLIC_REPLY_TEXTS = 5;
export const MAX_PUBLIC_REPLY_CHARS = 300;
const MAX_PUBLIC_HASHTAGS = 4;
const MAX_PUBLIC_LINKS = 1;
const HASHTAG = /(^|\s)#[\p{L}\p{N}_]+/gu;
const LINK = /\bhttps?:\/\/\S+|\bwww\.\S+/gi;
// Instagram allows a message for 24 hours after the person's reply, so a follow-up can be retried only inside it
const FOLLOWUP_WINDOW_MS = 24 * HOUR_MS;
// where a followers-only rule starts; the owner edits both before saving
export const DEFAULT_FOLLOW_PROMPT = 'Thanks for your comment. Follow this account, then reply to this message and the link is on its way.';
export const DEFAULT_NOT_FOLLOWING = 'It looks like you do not follow this account yet. Follow it, then reply here again and the link is on its way.';
// where a public reply starts; it says nothing about the private reply, which can fail on its own
export const DEFAULT_PUBLIC_REPLY = 'Thanks for your comment.';
export interface AutomationSummary {
received: number;
matched: number;
accepted: number;
publicPosted: number;
waiting: number;
attention: number;
rateLimited: number;
}
export type RuleScope = 'all' | 'selected';
// the rule editor's fields, as typed; keywords and the limit stay text until saved
export interface RuleForm {
accountId: string;
name: string;
keywordsText: string;
matchMode: AutomationMatchMode;
caseSensitive: boolean;
scope: RuleScope;
mediaIds: string[];
privateReplyEnabled: boolean;
replyText: string;
linkUrl: string;
publicReplyEnabled: boolean;
publicReplyTexts: string[];
hourlyLimit: string;
enabled: boolean;
requireFollow: boolean;
followPromptText: string;
notFollowingText: string;
}
// the field a problem belongs to, so the editor can show it under that field and move focus there
export type RuleField =
| 'accountId' | 'name' | 'keywordsText' | 'mediaIds' | 'replies' | 'replyText' | 'linkUrl' | 'hourlyLimit'
| 'publicReplyTexts' | 'requireFollow' | 'followPromptText' | 'notFollowingText';
export interface RuleFieldProblem {
field: RuleField;
message: string;
}
export function periodStart(period: StatsPeriod, now: number): string {
return new Date(now - STATS_PERIODS[period].ms).toISOString();
}
type ActivityStatus = Pick<AutomationActivityItem, 'status' | 'statusReason'> & Partial<Pick<AutomationActivityItem, 'gateStatus' | 'followup'>>;
// a followers-only reply that Instagram accepted shows where the wait for the person stands, not just the first message
export function statusDisplay(item: ActivityStatus): StatusDisplay {
if (item.status === 'queued' && item.statusReason === 'paused') return { label: 'Held', tone: 'warning' };
if (item.status === 'skipped' && item.statusReason === 'private_reply_off') return { label: 'Off', tone: 'secondary' };
if (item.status !== 'accepted' || !item.gateStatus) return STATUS_DISPLAY[item.status];
if (item.gateStatus === 'completed') return { label: 'Link sent', tone: 'success' };
if (item.gateStatus === 'closed') return { label: 'Not following', tone: 'secondary' };
if (item.followup?.status === 'needs_review') return { label: 'Needs review', tone: 'warning' };
if (item.followup?.status === 'failed') return { label: 'Follow-up failed', tone: 'destructive' };
return { label: 'Asked to follow', tone: 'info' };
}
// the sentence under a followers-only reply; null for any other item
export function gateDetail(item: Pick<AutomationActivityItem, 'status' | 'gateStatus' | 'followup'>): string | null {
if (item.status !== 'accepted' || !item.gateStatus) return null;
if (item.gateStatus === 'completed') return 'Instagram confirmed they follow the account, and accepted the reply with the link.';
if (item.gateStatus === 'closed') return 'They did not follow after the reminders, so the link was not sent.';
if (item.followup?.errorMessage) return item.followup.errorMessage;
if (item.followup?.kind === 'reminder') return 'Reminded them to follow. Their next reply is checked again.';
return 'Asked them to follow and reply. When they reply, Instagram says whether they follow, and the link goes out if they do.';
}
export function publicStatusDisplay(reply: Pick<AutomationPublicReplyState, 'status' | 'statusReason'>): StatusDisplay {
if (reply.status === 'queued' && reply.statusReason === 'paused') return { label: 'Held', tone: 'warning' };
return PUBLIC_STATUS_DISPLAY[reply.status];
}
function count(counts: Partial<Record<string, number>>, statuses: string[]): number {
return statuses.reduce((total, status) => total + (counts[status] ?? 0), 0);
}
// waiting and attention count both replies, so a failed public reply is not hidden by a private one that went out
export function summarizeStats(stats: AutomationStats): AutomationSummary {
const received = Object.values(stats.comments).reduce((total, value) => total + (value ?? 0), 0);
const publicReplies = stats.publicReplies ?? {};
return {
received,
matched: received - (stats.comments.ignored ?? 0),
accepted: stats.comments.accepted ?? 0,
publicPosted: publicReplies.accepted ?? 0,
waiting: count(stats.comments, ACTIVITY_FILTERS.waiting.statuses!) + count(publicReplies, ACTIVITY_FILTERS.waiting.statuses!),
attention: count(stats.comments, ACTIVITY_FILTERS.attention.statuses!) + count(publicReplies, ACTIVITY_FILTERS.attention.statuses!),
rateLimited: stats.attempts.rate_limited ?? 0,
};
}
export function ruleScopeLabel(rule: Pick<AutomationRule, 'mediaIds'>): string {
const posts = rule.mediaIds.length;
if (posts === 0) return 'All posts and reels';
return posts === 1 ? '1 selected post' : `${posts} selected posts`;
}
export function matchModeLabel(rule: Pick<AutomationRule, 'matchMode' | 'caseSensitive'>): string {
if (rule.matchMode === 'any') return 'Any comment';
const mode = rule.matchMode === 'exact' ? 'Whole comment' : 'Anywhere in the comment';
return rule.caseSensitive ? `${mode}, same letter case` : mode;
}
const RETRYABLE = ['failed', 'needs_review', 'skipped'];
// failed, skipped and review items can be tried again until Instagram's 7 days run out, except a private reply the rule
// does not send; on an accepted followers-only
// reply, a failed follow-up can be tried again inside the 24 hours after the person's answer
export function canRetry(
item: Pick<AutomationActivityItem, 'status' | 'expiresAt'> & Partial<Pick<AutomationActivityItem, 'followup' | 'statusReason'>>,
now: number,
): boolean {
if (item.status === 'skipped' && item.statusReason === 'private_reply_off') return false;
if (RETRYABLE.includes(item.status)) return Date.parse(item.expiresAt) > now;
const followup = item.followup;
return item.status === 'accepted' && !!followup && RETRYABLE.includes(followup.status) && Date.parse(followup.createdAt) + FOLLOWUP_WINDOW_MS > now;
}
// a failed, skipped or unconfirmed public reply can be posted again until 7 days after the comment, whatever the
// private reply did
export function canRetryPublic(item: Pick<AutomationActivityItem, 'publicReply' | 'expiresAt'>, now: number): boolean {
return !!item.publicReply && RETRYABLE.includes(item.publicReply.status) && Date.parse(item.expiresAt) > now;
}
// what is wrong with one public reply text, or null; the Worker checks the same
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 public texts as they will be saved: trimmed, without blanks or repeats
export function publicReplyTexts(texts: string[]): string[] {
return [...new Set(texts.map(text => text.trim()).filter(Boolean))];
}
// comma or line separated, trimmed, without blanks or repeats
export function parseKeywords(text: string, caseSensitive: boolean): string[] {
const seen = new Set<string>();
const keywords: string[] = [];
for (const keyword of text.split(/[,\n]/).map(item => item.trim()).filter(Boolean)) {
const key = caseSensitive ? keyword : keyword.toLowerCase();
if (seen.has(key)) continue;
seen.add(key);
keywords.push(keyword);
}
return keywords;
}
export function composeReply(replyText: string, linkUrl: string): string {
const link = linkUrl.trim();
return link ? `${replyText.trim()}\n\n${link}` : replyText.trim();
}
export function messageBytes(message: string): number {
return new TextEncoder().encode(message).length;
}
export function emptyRuleForm(accountId: string): RuleForm {
return {
accountId, name: '', keywordsText: '', matchMode: 'contains', caseSensitive: false, scope: 'all', mediaIds: [],
privateReplyEnabled: true, replyText: '', linkUrl: '', publicReplyEnabled: false, publicReplyTexts: [DEFAULT_PUBLIC_REPLY], hourlyLimit: '', enabled: true,
requireFollow: false, followPromptText: DEFAULT_FOLLOW_PROMPT, notFollowingText: DEFAULT_NOT_FOLLOWING,
};
}
export function ruleToForm(rule: AutomationRule): RuleForm {
return {
accountId: rule.accountId,
name: rule.name,
keywordsText: rule.keywords.join(', '),
matchMode: rule.matchMode,
caseSensitive: rule.caseSensitive,
scope: rule.mediaIds.length > 0 ? 'selected' : 'all',
mediaIds: rule.mediaIds,
privateReplyEnabled: rule.privateReplyEnabled,
replyText: rule.replyText,
linkUrl: rule.linkUrl ?? '',
publicReplyEnabled: rule.publicReplyEnabled,
publicReplyTexts: rule.publicReplyTexts.length > 0 ? rule.publicReplyTexts : [DEFAULT_PUBLIC_REPLY],
hourlyLimit: rule.hourlyLimit === null ? '' : String(rule.hourlyLimit),
enabled: rule.enabled,
requireFollow: rule.requireFollow,
followPromptText: rule.followPromptText ?? DEFAULT_FOLLOW_PROMPT,
notFollowingText: rule.notFollowingText ?? DEFAULT_NOT_FOLLOWING,
};
}
export function formToRequest(form: RuleForm): AutomationRuleRequest {
return {
accountId: form.accountId,
name: form.name.trim(),
// an any-comment rule takes no keywords, so ones typed before switching to it are not sent
keywords: form.matchMode === 'any' ? [] : parseKeywords(form.keywordsText, form.caseSensitive),
matchMode: form.matchMode,
caseSensitive: form.caseSensitive,
mediaIds: form.scope === 'selected' ? form.mediaIds : [],
privateReplyEnabled: form.privateReplyEnabled,
replyText: form.replyText.trim(),
linkUrl: normalizeLink(form.linkUrl) || null,
publicReplyEnabled: form.publicReplyEnabled,
// texts kept while the public reply is off come back when it is turned on again
publicReplyTexts: publicReplyTexts(form.publicReplyTexts),
enabled: form.enabled,
hourlyLimit: form.hourlyLimit.trim() ? Number(form.hourlyLimit) : null,
requireFollow: form.requireFollow,
followPromptText: form.followPromptText.trim() || null,
notFollowingText: form.notFollowingText.trim() || null,
};
}
// people paste "example.com/guide" as often as the full address, so a link without a scheme is taken as https
export function normalizeLink(linkUrl: string): string {
const link = linkUrl.trim();
if (!link || /^[a-z][a-z0-9+.-]*:/i.test(link)) return link;
return `https://${link.replace(/^\/\//, '')}`;
}
function linkProblem(linkUrl: string): string | null {
const link = normalizeLink(linkUrl);
if (!link) return null;
try {
const url = new URL(link);
if (url.protocol !== 'https:') return 'The link must start with https://';
if (url.username || url.password) return 'The link cannot contain a user name or password';
if (!url.hostname.includes('.')) return 'The link must be a full address, such as https://example.com/guide';
} catch {
return 'The link must be a full address, such as https://example.com/guide';
}
return null;
}
// the first thing to fix before the rule can be saved and the field it belongs to, or null; the Worker checks the same
export function ruleFormError(form: RuleForm): RuleFieldProblem | null {
const problem = (field: RuleField, message: string): RuleFieldProblem => ({ field, message });
if (!form.accountId) return problem('accountId', 'Choose the Instagram account');
if (!form.name.trim()) return problem('name', 'Give the rule a name');
if (form.matchMode !== 'any') {
const keywords = parseKeywords(form.keywordsText, form.caseSensitive);
if (keywords.length === 0) return problem('keywordsText', 'Add at least one keyword');
if (keywords.length > MAX_KEYWORDS) return problem('keywordsText', `A rule can have at most ${MAX_KEYWORDS} keywords`);
}
if (form.scope === 'selected' && form.mediaIds.length === 0) return problem('mediaIds', 'Choose at least one post, or answer comments on every post');
if (!form.privateReplyEnabled && !form.publicReplyEnabled) return problem('replies', 'Turn on the private reply, the public reply, or both');
if (form.privateReplyEnabled && !form.replyText.trim()) return problem('replyText', 'Write the reply to send');
const link = linkProblem(form.linkUrl);
if (link) return problem('linkUrl', link);
const limit = form.hourlyLimit.trim();
if (limit && !(/^\d+$/.test(limit) && Number(limit) >= 1 && Number(limit) <= MAX_HOURLY_LIMIT)) {
return problem('hourlyLimit', `The hourly limit must be a whole number from 1 to ${MAX_HOURLY_LIMIT}`);
}
const bytes = messageBytes(composeReply(form.replyText, normalizeLink(form.linkUrl)));
if (form.privateReplyEnabled && bytes > MAX_MESSAGE_BYTES) {
return problem('replyText', `The reply with its link is ${bytes} bytes; Instagram accepts at most ${MAX_MESSAGE_BYTES}`);
}
if (form.publicReplyEnabled) {
const texts = publicReplyTexts(form.publicReplyTexts);
if (texts.length === 0) return problem('publicReplyTexts', 'Write at least one public reply');
if (texts.length > MAX_PUBLIC_REPLY_TEXTS) return problem('publicReplyTexts', `A rule can have at most ${MAX_PUBLIC_REPLY_TEXTS} public replies`);
for (const text of texts) {
const textProblem = publicReplyTextProblem(text);
if (textProblem) return problem('publicReplyTexts', textProblem);
}
}
if (form.requireFollow && !form.privateReplyEnabled) {
return problem('requireFollow', 'Sending the link only to followers needs the private reply. Turn it on, or turn off the followers-only option');
}
if (form.requireFollow) {
if (!form.followPromptText.trim()) return problem('followPromptText', 'Write the message that asks people to follow you and reply');
if (!form.notFollowingText.trim()) return problem('notFollowingText', 'Write the reminder for people who do not follow you yet');
const prompt = messageBytes(form.followPromptText.trim());
const reminder = messageBytes(form.notFollowingText.trim());
if (Math.max(prompt, reminder) > MAX_MESSAGE_BYTES) {
return problem(prompt >= reminder ? 'followPromptText' : 'notFollowingText', `A followers-only message is ${Math.max(prompt, reminder)} bytes; Instagram accepts at most ${MAX_MESSAGE_BYTES}`);
}
}
return null;
}
// a followers-only rule that is on needs Instagram to send the account's messages as well as its comments
export function needsMessageEvents(rules: Pick<AutomationRule, 'accountId' | 'enabled' | 'requireFollow'>[], accountId: string): boolean {
return rules.some(rule => rule.accountId === accountId && rule.enabled && rule.requireFollow);
}
export interface AccountStatus {
label: string;
tone: BadgeTone;
detail: string;
}
// what an account's automation is doing right now, from its controls; needsMessages when a followers-only rule is on
export function accountStatus(account: AutomationAccountState, now: number, needsMessages = false): AccountStatus {
if (account.paused && account.cooldownReason) return { label: 'Held', tone: 'destructive', detail: account.cooldownReason };
if (account.paused) return { label: 'Paused', tone: 'secondary', detail: 'Comments are still recorded; replies wait until you resume, within Instagram\'s 7 days.' };
if (account.cooldownUntil && Date.parse(account.cooldownUntil) > now) {
return { label: 'Cooling down', tone: 'warning', detail: account.cooldownReason ?? 'Instagram is limiting replies from this account for now.' };
}
if (account.limitedUntil && Date.parse(account.limitedUntil) > now) {
return { label: 'At its hourly limit', tone: 'warning', detail: 'This account sent its hourly number of replies. The rest go out as the hour frees up, within Instagram\'s 7 days.' };
}
if (account.publicCooldownUntil && Date.parse(account.publicCooldownUntil) > now) {
return {
label: 'Public replies cooling down',
tone: 'warning',
detail: account.publicCooldownReason ?? 'Instagram is limiting comments from this account for now. Private replies still go out.',
};
}
if (account.publicLimitedUntil && Date.parse(account.publicLimitedUntil) > now) {
return { label: 'Public replies at their hourly limit', tone: 'warning', detail: 'This account posted its hourly number of public replies. The rest go out as the hour frees up.' };
}
if (!account.subscribedAt) return { label: 'Not receiving comments', tone: 'warning', detail: 'Turn on comment events so Instagram sends this account\'s comments to Twiligent.' };
if (needsMessages && !account.messagesSubscribed) {
return {
label: 'Follow checks off',
tone: 'warning',
detail: 'A followers-only rule needs this account\'s messages. Select messages in the Meta dashboard webhook settings, then turn on message events. Until then, people who reply never get the link.',
};
}
return { label: 'Receiving comments', tone: 'success', detail: 'New comments that match an active rule get a reply.' };
}