@thenavidm/threads-mcp-cli 1.1.0

package/dist/content/media.js

@@ -0,0 +1,125 @@
+/**
+ * Media rules, checked before a container is created.
+ *
+ * Threads does not upload bytes. You hand it a public URL and it fetches the
+ * file itself, asynchronously, and reports the result minutes later as a
+ * container in state ERROR with a message like "Media download failed". By
+ * then the useful context is gone.
+ *
+ * So the checks that can be made locally are made locally, in the one place the
+ * numbers are written down. Everything here comes from Meta's published specs.
+ */
+export const IMAGE_SPEC = {
+    formats: ["jpeg", "jpg", "png"],
+    maxBytes: 8 * 1024 * 1024,
+    minWidth: 320,
+    maxWidth: 1440,
+    /** Widest and tallest Threads will accept, as width:height. */
+    maxAspect: 10,
+};
+export const VIDEO_SPEC = {
+    formats: ["mp4", "mov"],
+    maxBytes: 1024 * 1024 * 1024,
+    maxSeconds: 300,
+    codecs: ["h264", "hevc"],
+    recommendedAspect: "9:16",
+};
+export const CAROUSEL = { min: 2, max: 20 };
+/**
+ * Reject a media URL that cannot possibly work, before spending a container on
+ * it.
+ *
+ * Deliberately narrow. It refuses what is certainly wrong (not a URL, not
+ * HTTPS, a local path, a `data:` URI) and lets everything else through, because
+ * a URL with no file extension is completely normal for a CDN and refusing it
+ * would break more than it fixed.
+ */
+export function assertMediaUrl(url, kind) {
+    const value = url.trim();
+    if (!value)
+        throw new Error(`A ${kind} URL is required.`);
+    if (value.startsWith("data:")) {
+        throw new Error(`Threads cannot take a data: URI. It fetches media from a public URL itself, so the ${kind} has to be hosted somewhere it can reach.`);
+    }
+    if (/^(file:|\/|\.\/|~\/|[A-Za-z]:\\)/.test(value)) {
+        throw new Error(`"${value}" is a local path. Threads has no upload endpoint: it fetches media from a public URL, so upload the ${kind} somewhere reachable first and pass that URL.`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`"${value}" is not a valid URL.`);
+    }
+    if (parsed.protocol !== "https:") {
+        if (parsed.protocol === "http:") {
+            throw new Error(`Threads requires HTTPS for media URLs. "${value}" is plain HTTP.`);
+        }
+        throw new Error(`Media URLs must be HTTPS. "${value}" uses ${parsed.protocol}`);
+    }
+    if (/^(localhost|127\.|0\.0\.0\.0|\[::1\]|192\.168\.|10\.)/i.test(parsed.hostname)) {
+        throw new Error(`"${parsed.hostname}" is not reachable from Meta's servers. Threads fetches the ${kind} itself, so a URL that only works on your machine will fail as a container error several minutes later.`);
+    }
+}
+/** The extension, lowercased, when the URL has one. */
+export function extensionOf(url) {
+    try {
+        const path = new URL(url).pathname;
+        const match = /\.([A-Za-z0-9]+)$/.exec(path);
+        return match?.[1]?.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Warn about an extension Threads does not support.
+ *
+ * A warning rather than an error: the extension in a URL is a hint, not a
+ * content type, and plenty of perfectly good CDN URLs end in `.webp?format=jpg`
+ * or nothing at all. Being told up front that a `.webp` is likely to fail is
+ * worth more than being stopped by it.
+ */
+export function formatWarning(url, kind) {
+    const ext = extensionOf(url);
+    if (!ext)
+        return undefined;
+    const allowed = kind === "image" ? IMAGE_SPEC.formats : VIDEO_SPEC.formats;
+    if (allowed.includes(ext))
+        return undefined;
+    return `The URL ends in .${ext}. Threads accepts ${allowed.join(", ")} for ${kind}s; anything else usually comes back as a container error a few minutes after posting.`;
+}
+/** Which container type a set of arguments implies. */
+export function mediaTypeFor(item) {
+    if (item.video_url)
+        return "VIDEO";
+    if (item.image_url)
+        return "IMAGE";
+    return "TEXT";
+}
+/** Validate one carousel item or post attachment. Returns any warnings. */
+export function checkMedia(item) {
+    const warnings = [];
+    if (item.image_url && item.video_url) {
+        throw new Error("A Threads post carries an image or a video, not both. For several pieces of media use create_carousel.");
+    }
+    if (item.image_url) {
+        assertMediaUrl(item.image_url, "image");
+        const warning = formatWarning(item.image_url, "image");
+        if (warning)
+            warnings.push(warning);
+    }
+    if (item.video_url) {
+        assertMediaUrl(item.video_url, "video");
+        const warning = formatWarning(item.video_url, "video");
+        if (warning)
+            warnings.push(warning);
+    }
+    return warnings;
+}
+export function assertCarouselSize(count) {
+    if (count < CAROUSEL.min || count > CAROUSEL.max) {
+        throw new Error(`A Threads carousel holds ${CAROUSEL.min} to ${CAROUSEL.max} items. You passed ${count}.`);
+    }
+}
+//# sourceMappingURL=media.js.map

package/dist/content/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/content/media.ts"],"names":[],"mappings":"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"}

package/dist/content/text.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Measuring a Threads post, and escaping text for the output format.
+ *
+ * Threads caps a post at 500 characters, and Meta's own documentation adds that
+ * emoji "count as UTF-8 bytes". Those are two different limits, and neither is
+ * JavaScript's `String.length`:
+ *
+ *   "👨‍👩‍👧‍👦"   1 character to a reader, 11 UTF-16 code units to `.length`,
+ *              25 bytes in UTF-8.
+ *   "é"        1 character, but 1 or 2 code units depending on whether it
+ *              arrived composed or decomposed, and 2 or 3 bytes.
+ *
+ * So a post of 480 emoji passes a naive `.length < 500` check and is refused by
+ * Threads, and a post of 300 family emoji fails a naive byte check that Threads
+ * would have accepted. Both limits are measured here, separately, and the error
+ * says which one was crossed and by how much. That matters most for
+ * `create_thread`, which checks every part before it posts any of them: a
+ * thread that half-publishes and then fails on part four cannot be un-posted.
+ *
+ * Graphemes are counted with `Intl.Segmenter`, which is in every Node 20
+ * runtime, so a flag or a family emoji counts as the one character a person
+ * sees rather than the several code points it is made of.
+ */
+/** Threads' published limit for post and reply text. */
+export declare const MAX_POST_CHARS = 500;
+/**
+ * The byte ceiling. Meta documents the character limit and notes that emoji are
+ * counted as UTF-8 bytes, without publishing a separate byte number. 500 is
+ * used for both, which is the conservative reading: a post inside both limits
+ * is accepted under either interpretation.
+ */
+export declare const MAX_POST_BYTES = 500;
+/** Threads' limit on a topic tag. */
+export declare const MAX_TOPIC_TAG_CHARS = 50;
+/** Threads accepts at most this many distinct URLs in one post's text. */
+export declare const MAX_LINKS_PER_POST = 5;
+/** Count what a reader would call characters, not UTF-16 code units. */
+export declare function graphemeLength(text: string): number;
+/** UTF-8 byte length, which is what Meta counts emoji against. */
+export declare function byteLength(text: string): number;
+export type Measurement = {
+    graphemes: number;
+    bytes: number;
+    /** True when the text is within both limits. */
+    ok: boolean;
+    /** Which limit was crossed, when one was. */
+    over?: "characters" | "bytes";
+};
+export declare function measure(text: string): Measurement;
+/**
+ * A one-line explanation of why a piece of text will not post.
+ *
+ * `label` names the part, so a thread failure says "part 4 of 6" rather than
+ * making the reader work out which string was the problem.
+ */
+export declare function overLimitMessage(text: string, label?: string): string | undefined;
+/** Count distinct URLs in post text, against Threads' five-link ceiling. */
+export declare function countLinks(text: string): number;
+/** Escape for an XML attribute or text node in the output format. */
+export declare function escapeXml(value: unknown): string;
+/**
+ * Validate a topic tag.
+ *
+ * Threads allows one per post, 1 to 50 characters, and rejects periods and
+ * ampersands. It is also written without a leading `#`, which is the mistake
+ * everyone makes once, so a leading hash is stripped rather than refused.
+ */
+export declare function normalizeTopicTag(raw: string): string;

package/dist/content/text.js

@@ -0,0 +1,106 @@
+/**
+ * Measuring a Threads post, and escaping text for the output format.
+ *
+ * Threads caps a post at 500 characters, and Meta's own documentation adds that
+ * emoji "count as UTF-8 bytes". Those are two different limits, and neither is
+ * JavaScript's `String.length`:
+ *
+ *   "👨‍👩‍👧‍👦"   1 character to a reader, 11 UTF-16 code units to `.length`,
+ *              25 bytes in UTF-8.
+ *   "é"        1 character, but 1 or 2 code units depending on whether it
+ *              arrived composed or decomposed, and 2 or 3 bytes.
+ *
+ * So a post of 480 emoji passes a naive `.length < 500` check and is refused by
+ * Threads, and a post of 300 family emoji fails a naive byte check that Threads
+ * would have accepted. Both limits are measured here, separately, and the error
+ * says which one was crossed and by how much. That matters most for
+ * `create_thread`, which checks every part before it posts any of them: a
+ * thread that half-publishes and then fails on part four cannot be un-posted.
+ *
+ * Graphemes are counted with `Intl.Segmenter`, which is in every Node 20
+ * runtime, so a flag or a family emoji counts as the one character a person
+ * sees rather than the several code points it is made of.
+ */
+/** Threads' published limit for post and reply text. */
+export const MAX_POST_CHARS = 500;
+/**
+ * The byte ceiling. Meta documents the character limit and notes that emoji are
+ * counted as UTF-8 bytes, without publishing a separate byte number. 500 is
+ * used for both, which is the conservative reading: a post inside both limits
+ * is accepted under either interpretation.
+ */
+export const MAX_POST_BYTES = 500;
+/** Threads' limit on a topic tag. */
+export const MAX_TOPIC_TAG_CHARS = 50;
+/** Threads accepts at most this many distinct URLs in one post's text. */
+export const MAX_LINKS_PER_POST = 5;
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Count what a reader would call characters, not UTF-16 code units. */
+export function graphemeLength(text) {
+    let count = 0;
+    for (const _ of segmenter.segment(text))
+        count++;
+    return count;
+}
+/** UTF-8 byte length, which is what Meta counts emoji against. */
+export function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+export function measure(text) {
+    const graphemes = graphemeLength(text);
+    const bytes = byteLength(text);
+    if (graphemes > MAX_POST_CHARS)
+        return { graphemes, bytes, ok: false, over: "characters" };
+    if (bytes > MAX_POST_BYTES)
+        return { graphemes, bytes, ok: false, over: "bytes" };
+    return { graphemes, bytes, ok: true };
+}
+/**
+ * A one-line explanation of why a piece of text will not post.
+ *
+ * `label` names the part, so a thread failure says "part 4 of 6" rather than
+ * making the reader work out which string was the problem.
+ */
+export function overLimitMessage(text, label = "This post") {
+    const m = measure(text);
+    if (m.ok)
+        return undefined;
+    if (m.over === "characters") {
+        return `${label} is ${m.graphemes} characters. Threads allows ${MAX_POST_CHARS}. Trim ${m.graphemes - MAX_POST_CHARS}, or split it across a thread.`;
+    }
+    return `${label} is ${m.bytes} UTF-8 bytes (${m.graphemes} characters). Threads allows ${MAX_POST_BYTES} bytes, and counts emoji as bytes rather than characters, so an emoji-heavy post runs out of room before it looks full. Remove about ${m.bytes - MAX_POST_BYTES} bytes.`;
+}
+/** Count distinct URLs in post text, against Threads' five-link ceiling. */
+export function countLinks(text) {
+    const matches = text.match(/https?:\/\/[^\s<>"']+/gi) ?? [];
+    return new Set(matches.map((u) => u.replace(/[.,;:!?)\]]+$/, ""))).size;
+}
+/** Escape for an XML attribute or text node in the output format. */
+export function escapeXml(value) {
+    return String(value)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Validate a topic tag.
+ *
+ * Threads allows one per post, 1 to 50 characters, and rejects periods and
+ * ampersands. It is also written without a leading `#`, which is the mistake
+ * everyone makes once, so a leading hash is stripped rather than refused.
+ */
+export function normalizeTopicTag(raw) {
+    const tag = raw.trim().replace(/^#/, "");
+    if (!tag)
+        throw new Error("A topic tag cannot be empty.");
+    if (tag.length > MAX_TOPIC_TAG_CHARS) {
+        throw new Error(`Topic tag is ${tag.length} characters. Threads allows ${MAX_TOPIC_TAG_CHARS}.`);
+    }
+    if (/[.&]/.test(tag)) {
+        throw new Error(`Topic tag "${tag}" contains a period or an ampersand. Threads rejects both.`);
+    }
+    return tag;
+}
+//# sourceMappingURL=text.js.map

package/dist/content/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/content/text.ts"],"names":[],"mappings":"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"}

package/dist/doctor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `threads-mcp doctor`: find out what is actually wrong.
+ *
+ * Threads fails in ways that look identical from a tool call. A missing scope
+ * usually returns an empty result rather than an error. An expired token and a
+ * token that was never long-lived both read as "rejected". A profile with 99
+ * followers gets nothing back from demographics and no explanation.
+ *
+ * So this probes each capability separately with the cheapest call that proves
+ * it, and reports what is granted, what is missing, and what to do about each.
+ */
+export declare function runDoctor(): Promise<number>;
+/** `threads-mcp refresh`: extend every stored token now. */
+export declare function runRefresh(): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,218 @@
+/**
+ * `threads-mcp doctor`: find out what is actually wrong.
+ *
+ * Threads fails in ways that look identical from a tool call. A missing scope
+ * usually returns an empty result rather than an error. An expired token and a
+ * token that was never long-lived both read as "rejected". A profile with 99
+ * followers gets nothing back from demographics and no explanation.
+ *
+ * So this probes each capability separately with the cheapest call that proves
+ * it, and reports what is granted, what is missing, and what to do about each.
+ */
+import { accountsFromStore } from "./auth/store.js";
+import { ThreadsClient } from "./api/client.js";
+import { loadConfig } from "./config.js";
+import { daysRemaining } from "./auth/tokens.js";
+import { ThreadsError } from "./api/errors.js";
+const PASS = "  ok   ";
+const FAIL = " fail  ";
+const WARN = " warn  ";
+function line(check) {
+    const mark = check.ok ? PASS : check.detail.startsWith("not granted") ? WARN : FAIL;
+    const fix = check.fix && !check.ok ? `\n         ${check.fix}` : "";
+    return `[${mark}] ${check.name}: ${check.detail}${fix}`;
+}
+/**
+ * Probe one capability.
+ *
+ * A permission failure is reported as a warning rather than an error: an app
+ * that never asked for keyword search is not broken, it just cannot search.
+ */
+async function probe(name, fix, run) {
+    try {
+        return { name, ok: true, detail: await run() };
+    }
+    catch (error) {
+        if (error instanceof ThreadsError && error.name === "PermissionError") {
+            return { name, ok: false, detail: "not granted", fix };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { name, ok: false, detail: message.slice(0, 160), fix };
+    }
+}
+async function checkAccount(client, account, config) {
+    const label = account.username ? `@${account.username}` : (account.userId ?? "unresolved");
+    const lines = [`\n${label}  (credential from ${account.source})`];
+    let userId;
+    try {
+        const profile = await client.profile(account);
+        userId = profile.id;
+        lines.push(line({
+            name: "token",
+            ok: true,
+            detail: `valid, acting as @${profile.username ?? profile.id}${profile.is_verified ? ", verified" : ""}`,
+        }));
+    }
+    catch (error) {
+        lines.push(line({
+            name: "token",
+            ok: false,
+            detail: error instanceof Error ? error.message.slice(0, 200) : String(error),
+            fix: "Run `threads-mcp login` to authorise again. An expired Threads token cannot be refreshed, only replaced.",
+        }));
+        return lines;
+    }
+    const days = daysRemaining(account);
+    if (days === undefined) {
+        lines.push(line({
+            name: "expiry",
+            ok: true,
+            detail: "unknown — this token came from the environment, so its expiry was never recorded",
+            fix: "Run `threads-mcp login` so the server owns the token and can refresh it before it lapses.",
+        }));
+    }
+    else if (days <= 7) {
+        lines.push(line({
+            name: "expiry",
+            ok: false,
+            detail: `${days} days left`,
+            fix: "Run `threads-mcp refresh` now. A token that lapses cannot be recovered.",
+        }));
+    }
+    else {
+        lines.push(line({ name: "expiry", ok: true, detail: `${days} days left` }));
+    }
+    const checks = await Promise.all([
+        probe("read own posts", "threads_basic is missing, which is unusual — re-authorise.", async () => {
+            const response = (await client.call(account, `/${userId}/threads`, { params: { fields: "id", limit: 1 } }));
+            return `${response.data?.length ?? 0} post(s) readable`;
+        }),
+        probe("publishing quota", "Add threads_content_publish and re-authorise.", async () => {
+            const response = (await client.call(account, `/${userId}/threads_publishing_limit`, {
+                params: { fields: "quota_usage,reply_quota_usage" },
+            }));
+            const row = response.data?.[0] ?? {};
+            return `${row.quota_usage ?? 0}/250 posts and ${row.reply_quota_usage ?? 0}/1000 replies used today`;
+        }),
+        probe("replies", "Add threads_read_replies and re-authorise.", async () => {
+            const response = (await client.call(account, `/${userId}/replies`, { params: { fields: "id", limit: 1 } }));
+            return `readable (${response.data?.length ?? 0} recent)`;
+        }),
+        probe("insights", "Add threads_manage_insights and re-authorise.", async () => {
+            const response = (await client.call(account, `/${userId}/threads_insights`, {
+                params: { metric: "followers_count" },
+            }));
+            const followers = response.data?.[0]?.total_value?.value;
+            return followers === undefined ? "readable" : `${followers} followers`;
+        }),
+        probe("keyword search", "Needs threads_keyword_search, which requires App Review. Without it, searches quietly return only your own posts.", async () => {
+            const response = (await client.call(account, "/keyword_search", {
+                params: { q: "threads", search_type: "TOP", fields: "id,username", limit: 2 },
+            }));
+            const rows = response.data ?? [];
+            const mine = account.username;
+            const onlyMine = rows.length > 0 && rows.every((r) => r.username?.toLowerCase() === mine);
+            return onlyMine ? "granted, but every result was your own — likely unapproved" : `${rows.length} result(s)`;
+        }),
+        probe("profile discovery", "Needs threads_profile_discovery and expanded access. Without it, only Meta's own accounts resolve.", async () => {
+            const response = (await client.call(account, "/profile_lookup", {
+                params: { username: "threads", fields: "id,username" },
+            }));
+            return response.username ? `resolved @${response.username}` : "reachable";
+        }),
+    ]);
+    lines.push(...checks.map(line));
+    const geo = (await client.profile(account)).is_eligible_for_geo_gating;
+    lines.push(line({
+        name: "geo-gating",
+        ok: geo === true,
+        detail: geo === true ? "eligible" : "not enabled for this profile",
+        fix: "Meta enables geo-gating per profile. There is no way to request it through the API.",
+    }));
+    return lines;
+}
+export async function runDoctor() {
+    const stored = accountsFromStore(loadConfig().storePath);
+    const config = loadConfig(stored);
+    const out = (text) => process.stdout.write(`${text}\n`);
+    out("threads-mcp doctor");
+    out("");
+    // Network first. Every check below is meaningless if this fails, and the
+    // errors it produces would all blame the token instead.
+    try {
+        const res = await fetch(`${config.graphHost}/v1.0/me`, { method: "GET" });
+        out(line({ name: "network", ok: true, detail: `${config.graphHost} reachable (HTTP ${res.status} without a token, as expected)` }));
+    }
+    catch (error) {
+        out(line({
+            name: "network",
+            ok: false,
+            detail: `cannot reach ${config.graphHost}: ${error.message}`,
+            fix: "Check the connection, a proxy, or THREADS_GRAPH_HOST.",
+        }));
+        return 1;
+    }
+    out(line({
+        name: "app credentials",
+        ok: Boolean(config.appId && config.appSecret),
+        detail: config.appId && config.appSecret ? "THREADS_APP_ID and THREADS_APP_SECRET are set" : "not set",
+        fix: "Only `threads-mcp login` needs these. Refreshing an existing token does not.",
+    }));
+    out(line({
+        name: "token store",
+        ok: true,
+        detail: `${stored.length} token(s) at ${config.storePath}`,
+    }));
+    if (config.readOnly)
+        out(`[${WARN}] mode: THREADS_READ_ONLY=1, every write is hidden from the tool list`);
+    if (!config.allowDestructive)
+        out(`[${WARN}] mode: THREADS_ALLOW_DESTRUCTIVE=0, posting and deleting are blocked`);
+    if (!config.accounts.length) {
+        out("");
+        out("No Threads profile is connected.");
+        out("  Run `threads-mcp login`, or set THREADS_ACCESS_TOKEN to a long-lived token.");
+        return 1;
+    }
+    const client = new ThreadsClient(config);
+    let failed = false;
+    for (const account of config.accounts) {
+        const lines = await checkAccount(client, account, config);
+        for (const l of lines)
+            out(l);
+        if (lines.some((l) => l.includes(FAIL)))
+            failed = true;
+    }
+    out("");
+    out(failed ? "Something above needs fixing." : "Everything checks out.");
+    return failed ? 1 : 0;
+}
+/** `threads-mcp refresh`: extend every stored token now. */
+export async function runRefresh() {
+    const stored = accountsFromStore(loadConfig().storePath);
+    const config = loadConfig(stored);
+    const out = (text) => process.stdout.write(`${text}\n`);
+    if (!config.accounts.length) {
+        out("No Threads profile is connected. Run `threads-mcp login`.");
+        return 1;
+    }
+    const client = new ThreadsClient(config);
+    let failed = false;
+    for (const account of config.accounts) {
+        const label = account.username ? `@${account.username}` : (account.userId ?? "unresolved");
+        if (account.source !== "store") {
+            out(`[${WARN}] ${label}: token came from the environment, so a refreshed value cannot be saved anywhere.`);
+            continue;
+        }
+        const before = daysRemaining(account);
+        const ok = await client.refresh(account);
+        if (ok) {
+            out(`[${PASS}] ${label}: ${before ?? "?"} → ${daysRemaining(account) ?? "?"} days`);
+        }
+        else {
+            failed = true;
+            out(`[${FAIL}] ${label}: refresh refused. A token must be at least 24 hours old and not yet expired. Run \`threads-mcp login\`.`);
+        }
+    }
+    return failed ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/format/posts.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rendering posts for a model to read.
+ *
+ * The Threads Graph API answers with an object per post whose useful content is
+ * a `text` field surrounded by ids, media URLs, permalinks, paging cursors and
+ * a `quoted_post` that repeats the whole shape one level down. Handed straight
+ * to a model, a 50-post listing is mostly punctuation, and the model spends its
+ * attention finding the text rather than reading it.
+ *
+ * The tagged format below runs roughly a tenth the size and puts the text where
+ * a model expects it. Rules that matter:
+ *
+ *   - **Timestamps are ISO-8601 UTC.** Threads returns an offset format
+ *     (`2026-08-31T09:14:02+0000`) that `new Date()` parses but that two
+ *     different posts can express differently. Normalized, so they compare.
+ *   - **Every attribute is escaped.** A display name containing a quote must
+ *     not be able to produce malformed output, or worse, close a tag.
+ *   - **One renderer.** Posts, replies, quoted posts and search results all go
+ *     through `renderPost`, so their handling cannot drift apart.
+ *   - **Hidden and deleted replies render as themselves** rather than
+ *     vanishing, so a gap in a conversation is visible instead of implied.
+ *   - **`quoted_post` and `reposted_post` are nested, not flattened.** A repost
+ *     with no text of its own is otherwise indistinguishable from an empty post.
+ */
+type Any = Record<string, any>;
+export declare function renderPost(post: Any, depth?: number, tag?: string): string;
+export type ListOptions = {
+    /** What produced this list: "posts", "replies", "search", "conversation". */
+    source: string;
+    cursor?: string;
+    /** Extra attributes on the root element, e.g. the account or query. */
+    meta?: Record<string, unknown>;
+};
+export declare function renderList(posts: Any[], options: ListOptions, tag?: string): string;
+/** A profile, for whoami and lookup_profile. */
+export declare function renderProfile(profile: Any, extra?: Record<string, unknown>): string;
+/** Pull the paging cursor out of a Graph API listing. */
+export declare function cursorOf(response: Any): string | undefined;
+/** The `data` array of a Graph API listing, whatever shape it arrived in. */
+export declare function dataOf(response: Any): Any[];
+export {};