@crievo/omni 0.0.0-stage → 0.1.0

package/tools/lib/omnichat/gate.mjs

@@ -0,0 +1,151 @@
+/* ============================================================================
+   The button and the follow gate, like ManyChat. The comment's private reply opens with a
+   button instead of the link; the person's tap (a webhook event) opens the 24 h window, and
+   then the delivery checks the criterion: with `require_follow`, someone who does not follow
+   the account gets "follow and tap again" with a new button, someone who follows gets the link.
+   (Likes are not checkable: the API does not tell who liked a post.)
+   Pure: the record is mutated and persisted by the caller; Instagram goes through an injected client.
+   ============================================================================ */
+
+import { withDefaults } from "../http.mjs";
+import { buttonMessage, quickReplyMessage } from "../platforms/instagram.mjs";
+import { errorType } from "./errors.mjs";
+import {
+  buttonLabel,
+  deliveryMessage,
+  followSkipOn,
+  notFollowingText,
+  openingText,
+  retryLabel,
+  skipDeliveryMessage,
+  skipLabel,
+} from "./text.mjs";
+
+/** @typedef {import("../http.mjs").Deps} Deps */
+/** @typedef {import("./match.mjs").Rule} Rule */
+/** @typedef {import("./config.mjs").OmnichatConfig} OmnichatConfig */
+/** @typedef {import("../platforms/instagram.mjs").InstagramClient} InstagramClient */
+
+/**
+ * Where a gated comment is: `awaiting_tap` (opener sent), `awaiting_follow` (tapped without following)
+ * or `delivered`.
+ * @typedef {object} GateRecord
+ * @property {"awaiting_tap" | "awaiting_follow" | "delivered"} state
+ * @property {"button" | "quick_reply"} [via] how the opener went out
+ * @property {string} [at] when the opener went
+ * @property {string} [igsid] the person's Instagram-scoped id, from the tap
+ * @property {number} [taps]
+ * @property {string} [last_tap_at]
+ * @property {string} [delivered_at] the last delivery
+ * @property {number} [deliveries] how many times the link went out (each tap of a follower sends it)
+ * @property {string | null} [message_id]
+ * @property {string[]} [mids] the events already handled (Meta repeats events it did not see acknowledged)
+ * @property {boolean} [skipped_follow] the link went through "Receber sem seguir"
+ */
+
+/** A button's payload starts with this; anything else a webhook delivers is not ours. */
+export const TAP_PREFIX = "omc1|";
+
+/**
+ * The payload of the button of one comment on one post. `action` "skip" is "Receber sem seguir".
+ * @param {string} media @param {string} commentId @param {"skip"} [action]
+ */
+export const tapPayload = (media, commentId, action) =>
+  `${TAP_PREFIX}${media}|${commentId}${action ? `|${action}` : ""}`;
+
+/**
+ * @param {unknown} payload
+ * @returns {{ media: string, comment: string, action: "skip" | null } | null}
+ */
+export function parseTapPayload(payload) {
+  if (typeof payload !== "string" || !payload.startsWith(TAP_PREFIX)) return null;
+  const [media, comment, action] = payload.slice(TAP_PREFIX.length).split("|");
+  return media && comment ? { media, comment, action: action === "skip" ? "skip" : null } : null;
+}
+
+/**
+ * The opener: the private reply with the button. If Instagram refuses the button template for a private
+ * reply (a permanent error), the same ask goes as a quick reply.
+ * @param {{ client: InstagramClient, userId: string, media: string, commentId: string, rule: Rule,
+ *   username: string | null, C: OmnichatConfig }} p
+ * @returns {Promise<{ id: string | null, via: "button" | "quick_reply" }>}
+ */
+export async function sendOpener({ client, userId, media, commentId, rule, username, C }) {
+  const text = openingText(rule, username, C);
+  const buttons = [{ title: buttonLabel(rule, C), payload: tapPayload(media, commentId) }];
+  try {
+    return { ...(await client.privateReply(userId, commentId, buttonMessage(text, buttons))), via: "button" };
+  } catch (e) {
+    if (errorType(/** @type {any} */ (e)) !== "permanent") throw e;
+    return { ...(await client.privateReply(userId, commentId, quickReplyMessage(text, buttons))), via: "quick_reply" };
+  }
+}
+
+/**
+ * @typedef {object} Tap
+ * @property {string} media
+ * @property {string} comment
+ * @property {string} senderId the person's Instagram-scoped id
+ * @property {string | null} mid
+ * @property {"skip" | null} [action] "skip": the "Receber sem seguir" button
+ */
+
+/**
+ * One tap. Every tap checks the criterion again, even after a delivery: whoever unfollowed is asked to
+ * follow again, whoever follows gets the link again (someone who lost the message just taps once more).
+ * Whoever taps again still without following (they said "já sigo" and don't) gets the same message with a
+ * second button, "Receber sem seguir" (unless follow_skip is false), and that one delivers.
+ * Mutates the record's comment; the caller persists the record when the status is not `unknown`.
+ * An error (the profile or the send failed) throws before anything is marked: the webhook answers an
+ * error and Meta delivers the event again.
+ * @param {{ tap: Tap, rule: Rule, record: { comments?: Record<string, import("./pass.mjs").CommentRecord> },
+ *   account: { client: InstagramClient, id: string }, post: string | null, C: OmnichatConfig } & Deps} p
+ * @returns {Promise<{ status: "unknown" | "duplicate" | "delivered" | "not_following", username?: string | null }>}
+ */
+export async function handleTap({ tap, rule, record, account, post, C, ...deps }) {
+  const d = withDefaults(deps);
+  const iso = () => new Date(d.now()).toISOString();
+  const c = record.comments?.[tap.comment];
+  const g = c?.gate;
+  if (!c || !g) return { status: "unknown" };
+  if (tap.mid && g.mids?.includes(tap.mid)) return { status: "duplicate", username: c.username };
+  const remember = () => {
+    if (tap.mid) g.mids = [...(g.mids ?? []), tap.mid].slice(-20);
+  };
+
+  const skip = tap.action === "skip" && followSkipOn(rule);
+  let follows = true;
+  if (rule.require_follow && !skip) {
+    const profile = await account.client.userProfile(tap.senderId);
+    if (typeof profile.is_user_follow_business !== "boolean")
+      throw new Error(
+        "a API não disse se a pessoa segue a conta (is_user_follow_business): confira o token com instagram_business_manage_messages",
+      );
+    follows = profile.is_user_follow_business;
+  }
+
+  g.igsid = tap.senderId;
+  g.taps = (g.taps ?? 0) + 1;
+  g.last_tap_at = iso();
+  if (!follows) {
+    /* the second time without following: the way out without following */
+    const offerSkip = followSkipOn(rule) && g.state === "awaiting_follow";
+    await account.client.sendMessage(
+      account.id,
+      tap.senderId,
+      buttonMessage(notFollowingText(rule, c.username, C), [
+        { title: retryLabel(rule, C), payload: tapPayload(tap.media, tap.comment) },
+        ...(offerSkip ? [{ title: skipLabel(rule, C), payload: tapPayload(tap.media, tap.comment, "skip") }] : []),
+      ]),
+    );
+    g.state = "awaiting_follow";
+    remember();
+    return { status: "not_following", username: c.username };
+  }
+  const message = skip ? skipDeliveryMessage(rule, c.username, post, C) : deliveryMessage(rule, c.username, post, C);
+  const { id } = await account.client.sendMessage(account.id, tap.senderId, message);
+  Object.assign(g, { state: "delivered", delivered_at: iso(), message_id: id, deliveries: (g.deliveries ?? 0) + 1 });
+  if (skip) g.skipped_follow = true;
+  remember();
+  return { status: "delivered", username: c.username };
+}

package/tools/lib/omnichat/manual.mjs

@@ -0,0 +1,166 @@
+/* Sending by hand to chosen comments (the user picked them, so they go even
+   when they don't trigger). Same pace and pause rules as the agent; whoever
+   already got the DM does not get it again. Pure: the caller checks the
+   request (confirmation, rule, pause, lock) and persists through `save`. */
+
+import { withDefaults } from "../http.mjs";
+import { DM_DEADLINE } from "./config.mjs";
+import { errorType, PauseError, pauseFor } from "./errors.mjs";
+import { reply } from "./pass.mjs";
+import { withUsername } from "./text.mjs";
+
+/** @typedef {import("../http.mjs").Deps} Deps */
+/** @typedef {import("./match.mjs").Rule} Rule */
+/** @typedef {import("./config.mjs").OmnichatConfig} OmnichatConfig */
+/** @typedef {import("./pass.mjs").PostRecord} PostRecord */
+/** @typedef {import("./pass.mjs").CommentRecord} CommentRecord */
+/** @typedef {import("../platforms/instagram.mjs").InstagramClient} InstagramClient */
+
+/**
+ * @typedef {{ id: string, username?: string | null, state: string, public_reply?: boolean, reason: string | null }} SendResult
+ */
+
+/**
+ * Sends the rule's DM (and public reply) to the chosen comments, or with `publicOnly`
+ * only the written public reply (no 7-day limit, no rule needed). Stops at the first
+ * rate limit / block, reporting the pause through `onPause`.
+ * @param {{ ids: string[], rule: Rule, publicOnly: boolean, written?: string, media: string,
+ *   stored?: Partial<PostRecord> | null, account: { client: InstagramClient, id: string }, name: string,
+ *   postFallback: string | null, save: (r: PostRecord) => void | Promise<void>,
+ *   onPause: (pause: { until: string, reason: string, at: string }) => void, C: OmnichatConfig } & Deps} p
+ *   `rule` is the one to use (already with the public replies swapped or removed)
+ * @returns {Promise<SendResult[]>}
+ */
+export async function sendManual({
+  ids,
+  rule,
+  publicOnly,
+  written,
+  media,
+  stored,
+  account,
+  name,
+  postFallback,
+  save,
+  onPause,
+  C,
+  ...deps
+}) {
+  const d = withDefaults(deps);
+  const iso = () => new Date(d.now()).toISOString();
+  const pace = () => d.sleep((C.pause_between_s + d.random() * C.pause_between_s) * 1000);
+  /** @type {SendResult[]} */
+  const results = [];
+  const m = await account.client.media(media, "permalink");
+  const post = m.permalink ?? postFallback;
+  /** @type {PostRecord} */
+  const r = /** @type {any} */ (stored ?? {});
+  r.comments ??= {};
+  let done = 0;
+  for (const cid of ids) {
+    if (done >= C.max_per_pass) {
+      results.push({ id: cid, state: "later", reason: `até ${C.max_per_pass} por vez: mande de novo` });
+      continue;
+    }
+    /** @type {CommentRecord | undefined} */
+    let c = r.comments[cid];
+    if (!publicOnly && c?.dm?.at) {
+      results.push({ id: cid, username: c.username, state: "already", reason: "já tinha recebido a DM" });
+      continue;
+    }
+    if (!c) {
+      try {
+        const j = await account.client.media(cid, "id,text,timestamp,from,username,media", "Instagram (comentário)");
+        if (j.media?.id && j.media.id !== media) {
+          results.push({ id: cid, state: "refused", reason: "o comentário não é deste post" });
+          continue;
+        }
+        c = /** @type {CommentRecord} */ ({
+          username: j.from?.username ?? j.username ?? null,
+          text: j.text ?? "",
+          commented_at: j.timestamp,
+        });
+      } catch (e) {
+        results.push({ id: cid, state: "refused", reason: /** @type {Error} */ (e).message });
+        continue;
+      }
+    }
+    const cc = /** @type {CommentRecord} */ (c);
+    if (publicOnly) {
+      if (done) await pace();
+      const text = withUsername(/** @type {string} */ (written), cc.username).trim();
+      try {
+        const { id } = await account.client.publicReply(cid, text);
+        cc.public_reply = { at: iso(), id, text, manual: true };
+        if (!r.comments[cid]) Object.assign(cc, { state: "skipped", reason: "respondido à mão no comentário, sem DM" });
+        r.comments[cid] = cc;
+        await save(r);
+        d.log(`${iso()} ${name}: @${cc.username ?? "?"} respondido no comentário (sem DM)`);
+        results.push({ id: cid, username: cc.username, state: "done", public_reply: true, reason: null });
+      } catch (e) {
+        const err = /** @type {any} */ (e);
+        const type = errorType(err);
+        if (type === "rate_limit" || type === "blocked") {
+          const pause = pauseFor(err.message, d.now(), C);
+          onPause(pause);
+          results.push({
+            id: cid,
+            username: cc.username,
+            state: "paused",
+            reason: `${err.message}: a conta pausa até ${pauseDay(pause.until)}`,
+          });
+          break;
+        }
+        results.push({ id: cid, username: cc.username, state: "failed", reason: err.message });
+      }
+      done++;
+      continue;
+    }
+    if (d.now() - Date.parse(cc.commented_at) > DM_DEADLINE) {
+      results.push({
+        id: cid,
+        username: cc.username,
+        state: "refused",
+        reason: "passou dos 7 dias que a Meta dá para a DM",
+      });
+      continue;
+    }
+    Object.assign(cc, { state: "queued", attempts: 0, pauses: 0, manual: true, manual_at: iso() });
+    delete cc.error;
+    delete cc.reason;
+    r.comments[cid] = cc;
+    if (done) await pace();
+    try {
+      await reply({ cid, c: cc, rule, account, media, name, post, C, ...d });
+    } catch (e) {
+      if (!(e instanceof PauseError)) throw e;
+      const pause = pauseFor(e.message, d.now(), C);
+      onPause(pause);
+      results.push({
+        id: cid,
+        username: cc.username,
+        state: "paused",
+        reason: `${e.message}: a conta pausa até ${pauseDay(pause.until)}`,
+      });
+      break;
+    } finally {
+      await save(r);
+    }
+    done++;
+    results.push({
+      id: cid,
+      username: cc.username,
+      state: cc.state,
+      public_reply: !!cc.public_reply?.at,
+      reason: cc.state === "done" ? null : (cc.error ?? null),
+    });
+  }
+  return results;
+}
+
+/**
+ * The pt-BR "dd/mm, hh:mm" the messages use.
+ * @param {string} iso
+ */
+export const pauseDay = iso =>
+  new Date(iso).toLocaleString("pt-BR", { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit" });

package/tools/lib/omnichat/match.mjs

@@ -0,0 +1,78 @@
+/* Does a comment trigger the rule? Pure keyword matching. */
+
+/**
+ * @typedef {object} Rule omnichat.json `instagram`
+ * @property {boolean} enabled
+ * @property {string[]} keywords
+ * @property {boolean} any_comment
+ * @property {string} link
+ * @property {string} dm
+ * @property {string[]} [public_replies]
+ * @property {boolean} [quote_post]
+ * @property {boolean} [generic_phrases] false: only the keyword triggers
+ * @property {string} [offer]
+ * @property {"skip" | "send"} [already_replied]
+ * @property {string[]} [already_replied_if]
+ * @property {boolean} [button] the DM opens with a button: the link goes out when the person taps it
+ * @property {boolean} [require_follow] the tap only delivers if the person follows the account (implies the button)
+ * @property {string} [opening_dm] text above the button
+ * @property {string} [button_label]
+ * @property {string} [not_following_dm] what goes out when the person taps without following
+ * @property {string} [retry_label] the button of that message
+ * @property {boolean} [link_button] the link goes in a button that opens it, not in the DM's text
+ * @property {string} [link_label] that button's label
+ * @property {boolean} [follow_skip] false: no "Receber sem seguir" for whoever says they follow without following
+ * @property {string} [skip_label] that button's label
+ * @property {string} [skip_dm] the DM of whoever got the link through that button (empty = the config's)
+ * @property {string} [updated_at]
+ * @property {string} [enabled_at]
+ * @property {string} [disabled_at]
+ */
+
+/**
+ * Case, accents, punctuation and emoji don't count: "Quero!!" and "eu QUERO 🙏" become "quero" / "eu quero".
+ * @param {unknown} s
+ */
+export const normalize = s =>
+  String(s ?? "")
+    .normalize("NFD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+
+/**
+ * Whole word or phrase in a normalized text ("querosene" does not contain "quero").
+ * @param {string} t normalized text @param {string} phrase normalized phrase
+ */
+export const hasPhrase = (t, phrase) => ` ${t} `.includes(` ${phrase} `);
+
+/**
+ * Triggers? "yes", "uncertain" or false.
+ * The rule's keyword always triggers (an emoji-only keyword counts as is). The generic
+ * requests ("quero", "me manda"…) too, unless the rule says generic_phrases: false, but
+ * with context: a comment that is only the request, with at most filler words, triggers;
+ * the request in the middle of a sentence is "uncertain" (a classifier decides).
+ * @param {Pick<Rule, "any_comment" | "keywords" | "generic_phrases">} rule
+ * @param {string | null | undefined} text
+ * @param {{ generic_phrases: string[], filler_words: string[] }} C
+ * @returns {"yes" | "uncertain" | false}
+ */
+export function triggers(rule, text, C) {
+  if (rule.any_comment) return "yes";
+  const t = normalize(text);
+  const keyword = (rule.keywords ?? []).some(p => {
+    const n = normalize(p);
+    return n ? hasPhrase(t, n) : !!p.trim() && String(text ?? "").includes(p.trim());
+  });
+  if (keyword) return "yes";
+  if (rule.generic_phrases === false) return false;
+  const generic = C.generic_phrases.map(normalize).filter(Boolean);
+  if (!generic.some(g => hasPhrase(t, g))) return false;
+  const ignored = new Set([
+    ...C.filler_words.map(normalize),
+    ...generic.flatMap(g => g.split(" ")),
+    ...(rule.keywords ?? []).flatMap(p => normalize(p).split(" ")),
+  ]);
+  return t.split(" ").some(w => w && !ignored.has(w)) ? "uncertain" : "yes";
+}