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.

8.0 KB
Raw Blame
// how a rule's keywords are compared with a comment: anywhere as whole words, or as the whole comment; any answers
// every comment with text in it and has no keywords
export type AutomationMatchMode = 'contains' | 'exact' | 'any';

// the life of a received comment; ignored ones matched no rule, the rest are reply jobs
export type AutomationCommentStatus =
    | 'ignored' | 'queued' | 'processing' | 'retry_wait' | 'sending'
    | 'accepted' | 'failed' | 'needs_review' | 'skipped' | 'expired';

// what one private reply request to Instagram ended as
export type AutomationAttemptOutcome = 'sending' | 'accepted' | 'rejected' | 'rate_limited' | 'ambiguous';

// a followers-only reply: waiting for the person to answer, link sent, or every reminder used
export type AutomationGateStatus = 'awaiting_reply' | 'completed' | 'closed';

// the message sent after the person answered: the reply and link once they follow, a reminder otherwise
export type AutomationFollowupKind = 'link' | 'reminder';

// a follow-up message moves through the same states as a reply, except ignored
export type AutomationFollowupStatus = Exclude<AutomationCommentStatus, 'ignored'>;

// a public reply under the comment moves through the same states, apart from the private reply
export type AutomationPublicReplyStatus = Exclude<AutomationCommentStatus, 'ignored'>;

export interface AutomationRule {
    id: string;
    accountId: string;
    name: string;
    keywords: string[];
    matchMode: AutomationMatchMode;
    caseSensitive: boolean;
    // empty means every post and reel of the account
    mediaIds: string[];
    // the private reply; empty when the rule only replies publicly
    privateReplyEnabled: boolean;
    replyText: string;
    linkUrl: string | null;
    // a public reply under the comment, one of these texts picked per comment
    publicReplyEnabled: boolean;
    publicReplyTexts: string[];
    enabled: boolean;
    // null uses only the account's limit; it counts private replies
    hourlyLimit: number | null;
    // the private reply asks the person to follow and answer; the reply and link go out once Instagram says they follow
    requireFollow: boolean;
    followPromptText: string | null;
    notFollowingText: string | null;
    createdAt: string;
    updatedAt: string;
}

// body of POST /api/automations/rules
export interface AutomationRuleRequest {
    accountId: string;
    name: string;
    keywords: string[];
    matchMode?: AutomationMatchMode;
    caseSensitive?: boolean;
    mediaIds?: string[];
    privateReplyEnabled?: boolean;
    // may be empty when privateReplyEnabled is false
    replyText: string;
    linkUrl?: string | null;
    publicReplyEnabled?: boolean;
    publicReplyTexts?: string[];
    enabled?: boolean;
    hourlyLimit?: number | null;
    requireFollow?: boolean;
    followPromptText?: string | null;
    notFollowingText?: string | null;
}

// body of PUT /api/automations/rules/:id; a rule stays on its account
export type AutomationRuleUpdateRequest = Partial<Omit<AutomationRuleRequest, 'accountId'>>;

// one connected Instagram account as the automation sees it
export interface AutomationAccountState {
    accountId: string;
    username: string;
    profilePictureUrl: string;
    paused: boolean;
    cooldownUntil: string | null;
    cooldownReason: string | null;
    // when Instagram confirmed it sends this account's comments to the webhook
    subscribedAt: string | null;
    // the account reached its hourly reply limit; its replies wait until then
    limitedUntil: string | null;
    // Instagram also sends this account's messages, which followers-only rules need
    messagesSubscribed: boolean;
    // public replies cool down and fill up apart from private replies
    publicCooldownUntil: string | null;
    publicCooldownReason: string | null;
    publicLimitedUntil: string | null;
}

export interface AutomationLimits {
    accountHourly: number;
    userHourly: number;
    globalHourly: number;
    recipientDaily: number;
    // public replies an hour per account; Instagram publishes no number for them, so Twiligent keeps a human pace
    publicAccountHourly: number;
}

export interface AutomationSettings {
    // the webhook secrets are set, so Meta's requests can be verified
    webhookConfigured: boolean;
    // AUTOMATION_PAUSED holds every reply on this instance
    paused: boolean;
    limits: AutomationLimits;
}

export interface AutomationActivityItem {
    id: string;
    accountId: string;
    ruleId: string | null;
    commentId: string;
    mediaId: string | null;
    fromUsername: string | null;
    text: string | null;
    status: AutomationCommentStatus;
    statusReason: string | null;
    errorMessage: string | null;
    attempts: number;
    nextAttemptAt: string | null;
    acceptedAt: string | null;
    expiresAt: string;
    createdAt: string;
    // followers-only rules: where the wait for the person's answer stands, and the latest message sent after it
    gateStatus: AutomationGateStatus | null;
    followup: AutomationFollowupState | null;
    // the public reply under the comment, when the rule asked for one
    publicReply: AutomationPublicReplyState | null;
}

export interface AutomationPublicReplyState {
    status: AutomationPublicReplyStatus;
    statusReason: string | null;
    errorMessage: string | null;
    text: string;
    attempts: number;
    // the id Instagram gave the reply, once it is known to be there
    replyId: string | null;
    nextAttemptAt: string | null;
    acceptedAt: string | null;
}

export interface AutomationFollowupState {
    status: AutomationFollowupStatus;
    kind: AutomationFollowupKind | null;
    errorMessage: string | null;
    createdAt: string;
}

export interface AutomationStats {
    comments: Partial<Record<AutomationCommentStatus, number>>;
    publicReplies: Partial<Record<AutomationPublicReplyStatus, number>>;
    attempts: Partial<Record<AutomationAttemptOutcome, number>>;
}

// GET /api/automations
export interface AutomationOverviewResponse {
    success: true;
    rules: AutomationRule[];
    accounts: AutomationAccountState[];
    settings: AutomationSettings;
}

// POST /api/automations/rules, PUT /api/automations/rules/:id and POST /api/automations/rules/:id/duplicate
export interface AutomationRuleResponse {
    success: true;
    rule: AutomationRule;
}

// body of POST /api/automations/test: a rule draft and a sample comment; nothing is sent
export interface AutomationTestRequest {
    keywords: string[];
    matchMode?: AutomationMatchMode;
    caseSensitive?: boolean;
    mediaIds?: string[];
    privateReplyEnabled?: boolean;
    replyText: string;
    linkUrl?: string | null;
    requireFollow?: boolean;
    followPromptText?: string | null;
    comment: string;
    mediaId?: string;
}

export interface AutomationTestResponse {
    success: true;
    matched: boolean;
    // the keyword that matched, or null, as for an any-comment rule
    keyword: string | null;
    // the private reply exactly as it would be sent; for a followers-only rule, the request to follow and answer
    message: string;
    messageBytes: number;
    maxMessageBytes: number;
}

// GET /api/automations/activity; pass nextBefore as before for the next page
export interface AutomationActivityResponse {
    success: true;
    items: AutomationActivityItem[];
    nextBefore: string | null;
}

// POST /api/automations/activity/:id/retry (the private reply or its follow-up) and
// POST /api/automations/activity/:id/public-reply/retry (the public reply alone)
export interface AutomationActivityItemResponse {
    success: true;
    item: AutomationActivityItem;
}

// GET /api/automations/stats
export interface AutomationStatsResponse {
    success: true;
    from: string;
    to: string;
    stats: AutomationStats;
}

// body of PUT /api/automations/accounts/:accountId
export interface AutomationAccountRequest {
    paused: boolean;
}

// PUT /api/automations/accounts/:accountId and POST /api/automations/accounts/:accountId/subscribe
export interface AutomationAccountResponse {
    success: true;
    account: AutomationAccountState;
}