@crievo/omni 0.0.0-stage → 0.1.0

package/tools/lib/platforms/instagram.mjs

@@ -0,0 +1,469 @@
+/* ============================================================================
+   Instagram (Instagram API with Instagram login): token renewal, the account,
+   media, comments, private replies and the Reel / carousel publishing flow.
+   Pure: no fs, no console. The token lives in an injected TokenStore and every
+   call takes injected deps (fetch, clock, sleep, log).
+   ============================================================================ */
+
+import { request, withDefaults, DAY } from "../http.mjs";
+
+/** @typedef {import("../http.mjs").Deps} Deps */
+/** @typedef {import("../http.mjs").TokenStore} TokenStore */
+
+/**
+ * The Graph base URL for an API version.
+ * @param {string} [apiVersion]
+ */
+export const igBase = (apiVersion = "v23.0") => `https://graph.instagram.com/${apiVersion}`;
+
+/** The token lasts 60 days; below this it is renewed (Meta only renews tokens older than 24 h). */
+export const REFRESH_BELOW = 20 * DAY;
+
+/**
+ * What to do with the stored Instagram token.
+ * @param {{ expires: number, now: number }} p `expires` is epoch ms (NaN when unknown)
+ * @returns {"expired" | "refresh" | "ok"}
+ */
+export function instagramTokenDecision({ expires, now }) {
+  if (Number.isFinite(expires) && expires < now) return "expired";
+  if (!Number.isFinite(expires) || expires - now < REFRESH_BELOW) return "refresh";
+  return "ok";
+}
+
+/**
+ * The usable token and the account id. Renews it (and writes it back to the
+ * store) when less than 20 days are left; a failed renewal is only a warning.
+ * @param {{ store: TokenStore } & Deps} p
+ * @returns {Promise<{ token: string, id: string }>}
+ */
+export async function instagramToken({ store, ...deps }) {
+  const d = withDefaults(deps);
+  let token = store.get("INSTAGRAM_TOKEN");
+  const id = store.get("INSTAGRAM_USER_ID");
+  if (!token || !id) throw new Error("Instagram não conectado: rode node tools/publish.mjs auth instagram <token>");
+  const expires = Date.parse(store.get("INSTAGRAM_TOKEN_EXPIRES"));
+  const decision = instagramTokenDecision({ expires, now: d.now() });
+  if (decision === "expired") {
+    throw new Error(
+      `o token do Instagram venceu em ${new Date(expires).toLocaleDateString("pt-BR")}: gere outro no painel da Meta e rode auth instagram <token>`,
+    );
+  }
+  if (decision === "refresh") {
+    try {
+      const { j } = await request(
+        `https://graph.instagram.com/refresh_access_token?${new URLSearchParams({ grant_type: "ig_refresh_token", access_token: token })}`,
+        {},
+        "renovar token do Instagram",
+        d,
+      );
+      token = j.access_token;
+      await store.set({
+        INSTAGRAM_TOKEN: token,
+        INSTAGRAM_TOKEN_EXPIRES: new Date(d.now() + j.expires_in * 1000).toISOString(),
+      });
+    } catch (e) {
+      d.warn(`aviso: ${/** @type {Error} */ (e).message}`);
+    }
+  }
+  return { token, id };
+}
+
+/**
+ * The values `auth instagram <token>` stores: the dashboard token is already the 60-day one.
+ * @param {{ token: string, account: { user_id?: string, id?: string }, now: number }} p
+ */
+export const instagramAuthValues = ({ token, account, now }) => ({
+  INSTAGRAM_TOKEN: token,
+  INSTAGRAM_USER_ID: String(account.user_id ?? account.id),
+  INSTAGRAM_TOKEN_EXPIRES: new Date(now + 60 * DAY).toISOString(),
+});
+
+/**
+ * A message with buttons (Instagram's button template: text up to 640 characters, up to 3 buttons with a
+ * title of up to 20). A button with `payload` is a postback (the tap comes back by webhook); one with `url`
+ * opens the link.
+ * @param {string} text @param {Array<{ title: string, payload?: string, url?: string }>} buttons
+ */
+export const buttonMessage = (text, buttons) => ({
+  attachment: {
+    type: "template",
+    payload: {
+      template_type: "button",
+      text,
+      buttons: buttons.map(b =>
+        b.url
+          ? { type: "web_url", title: b.title, url: b.url }
+          : { type: "postback", title: b.title, payload: b.payload },
+      ),
+    },
+  },
+});
+
+/**
+ * The same ask as quick replies (a tap arrives as a `messages` event, not a postback).
+ * @param {string} text @param {Array<{ title: string, payload: string }>} buttons
+ */
+export const quickReplyMessage = (text, buttons) => ({
+  text,
+  quick_replies: buttons.map(b => ({ content_type: "text", title: b.title, payload: b.payload })),
+});
+
+/**
+ * A client bound to one token: every Graph call the tools make.
+ * @param {{ token: string, apiVersion?: string } & Deps} p
+ */
+export function instagramClient({ token, apiVersion, ...deps }) {
+  const d = withDefaults(deps);
+  const base = igBase(apiVersion);
+  /** @param {Record<string, string>} p */
+  const q = p => new URLSearchParams({ ...p, access_token: token });
+  /** @param {string} url @param {RequestInit} opts @param {string} label */
+  const call = (url, opts, label) => request(url, opts, label, d);
+  /** @param {Record<string, string>} p */
+  const form = p => q(p);
+
+  return {
+    base,
+    token,
+
+    /** @param {string} [fields] */
+    async account(fields = "user_id,username,name,account_type,profile_picture_url") {
+      return (await call(`${base}/me?${q({ fields })}`, {}, "conta do Instagram")).j;
+    },
+
+    /** @param {string} media @param {string} fields @param {string} [label] */
+    async media(media, fields, label = "Instagram (post)") {
+      return (await call(`${base}/${media}?${q({ fields })}`, {}, label)).j;
+    },
+
+    /** The account's recent media (one page). @param {string} fields @param {string} limit */
+    async recentMedia(fields, limit) {
+      return (await call(`${base}/me/media?${q({ fields, limit })}`, {}, "Instagram (posts)")).j;
+    },
+
+    /** Raw GET on a full URL (paging links). @param {string} url @param {string} label */
+    async get(url, label) {
+      return (await call(url, {}, label)).j;
+    },
+
+    /** The first page URL of the account's media. @param {string} fields @param {string} limit */
+    mediaListUrl: (fields, limit) => `${base}/me/media?${q({ fields, limit })}`,
+
+    /** Insights of one media. @param {string} id @param {string[]} metrics */
+    async insights(id, metrics) {
+      const { j } = await call(
+        `${base}/${id}/insights?${q({ metric: metrics.join(",") })}`,
+        {},
+        `métricas do Reel ${id}`,
+      );
+      return Object.fromEntries(
+        (j.data ?? []).map(
+          (/** @type {any} */ x) =>
+            /** @type {[string, any]} */ ([x.name, x.values?.[0]?.value ?? x.total_value?.value ?? null]),
+        ),
+      );
+    },
+
+    /** Profile visits of the day, or throws. */
+    async profileVisits() {
+      const { j } = await call(
+        `${base}/me/insights?${q({ metric: "profile_views", period: "day", metric_type: "total_value" })}`,
+        {},
+        "visitas ao perfil",
+      );
+      return j.data?.[0]?.total_value?.value ?? null;
+    },
+
+    /**
+     * The post's comments, newest to oldest, down to `limit` (epoch ms) or `maxPages` pages.
+     * `resume` is where a previous read stopped (URL without the token); `next` is where this one
+     * stopped (without the token), or null if it reached the limit.
+     * @param {string} media @param {number} limit @param {string | null} [resume] @param {number} [maxPages]
+     * @returns {Promise<{ read: any[], next: string | null }>}
+     */
+    async comments(media, limit, resume, maxPages = 20) {
+      let url = resume
+        ? `${resume}${resume.includes("?") ? "&" : "?"}${new URLSearchParams({ access_token: token })}`
+        : `${base}/${media}/comments?${q({ fields: "id,text,timestamp,from,username,replies{id,username,text,timestamp,from}", limit: "50" })}`;
+      const read = [];
+      let pages = 0,
+        reached = false;
+      while (url && pages++ < maxPages) {
+        const { j } = await call(url, {}, "Instagram (comentários)");
+        for (const c of j.data ?? []) {
+          if (Date.parse(c.timestamp) < limit) {
+            reached = true;
+            break;
+          }
+          read.push(c);
+        }
+        url = reached ? null : (j.paging?.next ?? null);
+      }
+      /* the token does not go to disk */
+      let next = null;
+      if (url) {
+        const u = new URL(url);
+        u.searchParams.delete("access_token");
+        next = u.toString();
+      }
+      return { read, next };
+    },
+
+    /** One page of a media's comments, ids only (the permission check). @param {string} media */
+    async commentIds(media) {
+      return (await call(`${base}/${media}/comments?${q({ fields: "id", limit: "1" })}`, {}, "Instagram (comentários)"))
+        .j;
+    },
+
+    /**
+     * The comment's private reply (one per comment, up to 7 days): a text or a message object (buttons).
+     * @param {string} userId @param {string} commentId @param {string | Record<string, any>} message
+     */
+    async privateReply(userId, commentId, message) {
+      const { j } = await call(
+        `${base}/${userId}/messages`,
+        {
+          method: "POST",
+          headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          body: JSON.stringify({
+            recipient: { comment_id: commentId },
+            message: typeof message === "string" ? { text: message } : message,
+          }),
+        },
+        "Instagram (DM)",
+      );
+      return { id: j.message_id ?? null };
+    },
+
+    /**
+     * A message to someone who has an open conversation (24 h after their last message or tap).
+     * @param {string} userId @param {string} recipientId the person's Instagram-scoped id @param {string | Record<string, any>} message
+     */
+    async sendMessage(userId, recipientId, message) {
+      const { j } = await call(
+        `${base}/${userId}/messages`,
+        {
+          method: "POST",
+          headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          body: JSON.stringify({
+            recipient: { id: recipientId },
+            message: typeof message === "string" ? { text: message } : message,
+          }),
+        },
+        "Instagram (mensagem)",
+      );
+      return { id: j.message_id ?? null };
+    },
+
+    /**
+     * Who the person is to the account: `is_user_follow_business` says whether they follow it.
+     * Only for someone who has messaged the account (or tapped a button of it).
+     * @param {string} igsid
+     * @returns {Promise<{ username?: string, is_user_follow_business?: boolean, is_business_follow_user?: boolean }>}
+     */
+    async userProfile(igsid) {
+      return (
+        await call(
+          `${base}/${igsid}?${q({ fields: "username,is_user_follow_business,is_business_follow_user" })}`,
+          {},
+          "Instagram (perfil de quem tocou)",
+        )
+      ).j;
+    },
+
+    /** The webhook fields this app receives for the account. @param {string} userId */
+    async webhookFields(userId) {
+      const { j } = await call(`${base}/${userId}/subscribed_apps?${q({})}`, {}, "Instagram (webhook)");
+      return /** @type {string[]} */ ((j.data ?? []).flatMap((/** @type {any} */ a) => a.subscribed_fields ?? []));
+    },
+
+    /** Subscribes the account to webhook fields. @param {string} userId @param {string[]} fields */
+    async subscribeWebhook(userId, fields) {
+      await call(
+        `${base}/${userId}/subscribed_apps`,
+        { method: "POST", body: new URLSearchParams({ subscribed_fields: fields.join(","), access_token: token }) },
+        "Instagram (inscrever webhook)",
+      );
+    },
+
+    /** A public reply on the comment. @param {string} commentId @param {string} message */
+    async publicReply(commentId, message) {
+      const { j } = await call(
+        `${base}/${commentId}/replies`,
+        { method: "POST", body: new URLSearchParams({ message, access_token: token }) },
+        "Instagram (resposta)",
+      );
+      return { id: j.id ?? null };
+    },
+
+    /** Deletes a comment (the post's, or one the account wrote). @param {string} commentId */
+    async deleteComment(commentId) {
+      await call(`${base}/${commentId}?${q({})}`, { method: "DELETE" }, "Instagram (apagar comentário)");
+    },
+
+    /** @param {string} userId @param {Record<string, string>} params @param {string} label */
+    async createContainer(userId, params, label) {
+      return (await call(`${base}/${userId}/media`, { method: "POST", body: form(params) }, label)).j;
+    },
+
+    /**
+     * Waits for a container to be FINISHED.
+     * @param {string} cid @param {{ label: string, timeoutMs: number, everyMs: number, refused: (s: string) => string, late: () => string }} o
+     */
+    async waitContainer(cid, { label, timeoutMs, everyMs, refused, late }) {
+      const deadline = d.now() + timeoutMs;
+      for (;;) {
+        const { j: s } = await call(`${base}/${cid}?${q({ fields: "status_code,status" })}`, {}, label);
+        if (s.status_code === "FINISHED") return;
+        if (s.status_code === "ERROR" || s.status_code === "EXPIRED")
+          throw new Error(refused(s.status ?? s.status_code));
+        if (d.now() > deadline) throw new Error(late());
+        await d.sleep(everyMs);
+      }
+    },
+
+    /** One look at a container: FINISHED, IN_PROGRESS, ERROR or EXPIRED (with the reason). @param {string} cid */
+    async containerStatus(cid) {
+      const { j } = await call(`${base}/${cid}?${q({ fields: "status_code,status" })}`, {}, "Instagram (status)");
+      return { code: String(j.status_code ?? ""), status: j.status ?? null };
+    },
+
+    /** @param {string} userId @param {string} creationId */
+    async publishContainer(userId, creationId) {
+      return (
+        await call(
+          `${base}/${userId}/media_publish`,
+          { method: "POST", body: form({ creation_id: creationId }) },
+          "Instagram (publicar)",
+        )
+      ).j;
+    },
+
+    /** The post's link, or null (published; just no link). @param {string} id */
+    async permalink(id) {
+      try {
+        return (await call(`${base}/${id}?${q({ fields: "permalink" })}`, {}, "Instagram (link)")).j.permalink ?? null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/** @typedef {ReturnType<typeof instagramClient>} InstagramClient */
+
+/**
+ * Publishes a Reel from a public video URL (and an optional public cover URL).
+ * With Instagram login Meta downloads the file itself: the caller provides the
+ * URLs (a local tunnel on the CLI, object storage in the cloud) and `release`,
+ * called once Instagram has finished downloading.
+ * @param {{ client: InstagramClient, userId: string, videoUrl: string, coverUrl?: string | null,
+ *   cover?: { version: string } | null, caption: string, shareToFeed: boolean, coverAtS?: number | null,
+ *   release?: () => void } & Deps} p
+ * @returns {Promise<{ id: string, url: string | null, cover?: { version: string, applied: boolean, error?: string } }>}
+ */
+export async function publishReel({
+  client,
+  userId,
+  videoUrl,
+  coverUrl,
+  cover,
+  caption,
+  shareToFeed,
+  coverAtS,
+  release,
+  ...deps
+}) {
+  const d = withDefaults(deps);
+  /* the container: with the cover, and without it if Instagram refuses (the cover never brings down the video) */
+  /** @param {boolean} withCover */
+  const create = async withCover => {
+    const c = await client.createContainer(
+      userId,
+      {
+        media_type: "REELS",
+        video_url: videoUrl,
+        caption,
+        share_to_feed: String(!!shareToFeed),
+        ...(withCover
+          ? { cover_url: /** @type {string} */ (coverUrl) }
+          : coverAtS != null
+            ? { thumb_offset: String(Math.round(coverAtS * 1000)) }
+            : {}),
+      },
+      "Instagram (criar container)",
+    );
+    d.log("Instagram: baixando e processando o vídeo…");
+    await client.waitContainer(c.id, {
+      label: "Instagram (status)",
+      timeoutMs: 10 * 60_000,
+      everyMs: 5000,
+      refused: s => `o Instagram recusou o vídeo: ${s}`,
+      late: () => `10 min e o Instagram não terminou de processar (container ${c.id})`,
+    });
+    return c;
+  };
+  let c,
+    coverResult = null;
+  try {
+    if (cover) {
+      try {
+        c = await create(true);
+        coverResult = { version: cover.version, applied: true };
+      } catch (e) {
+        const msg = /** @type {Error} */ (e).message;
+        d.warn(`aviso: instagram: com a capa ${cover.version} não foi (${msg}); tentando sem a capa`);
+        coverResult = { version: cover.version, applied: false, error: msg };
+      }
+    }
+    if (!c) c = await create(false);
+  } finally {
+    release?.();
+  }
+  const pub = await client.publishContainer(userId, c.id);
+  const url = await client.permalink(pub.id);
+  return { id: pub.id, url, ...(coverResult ? { cover: coverResult } : {}) };
+}
+
+/**
+ * Publishes a carousel from public image URLs (2+), same contract as publishReel.
+ * @param {{ client: InstagramClient, userId: string, imageUrls: string[], caption: string, release?: () => void } & Deps} p
+ * @returns {Promise<{ id: string, url: string | null }>}
+ */
+export async function publishCarouselPost({ client, userId, imageUrls, caption, release, ...deps }) {
+  const d = withDefaults(deps);
+  /** @param {string} cid @param {string} label */
+  const ready = (cid, label) =>
+    client.waitContainer(cid, {
+      label: `Instagram (${label})`,
+      timeoutMs: 5 * 60_000,
+      everyMs: 2000,
+      refused: s => `o Instagram recusou ${label}: ${s}`,
+      late: () => `5 min e o Instagram não terminou ${label} (container ${cid})`,
+    });
+  let carousel;
+  try {
+    const children = [];
+    for (const [i, url] of imageUrls.entries()) {
+      const c = await client.createContainer(
+        userId,
+        { image_url: url, is_carousel_item: "true" },
+        `Instagram (slide ${i + 1})`,
+      );
+      await ready(c.id, `o slide ${i + 1}`);
+      children.push(c.id);
+      d.log(`Instagram: slide ${i + 1}/${imageUrls.length} recebido`);
+    }
+    const c = await client.createContainer(
+      userId,
+      { media_type: "CAROUSEL", children: children.join(","), caption },
+      "Instagram (carrossel)",
+    );
+    await ready(c.id, "o carrossel");
+    carousel = c;
+  } finally {
+    release?.();
+  }
+  const done = await client.publishContainer(userId, carousel.id);
+  return { id: done.id, url: await client.permalink(done.id) };
+}