yappr 0.1.0

package/dist/src/wallet.js

@@ -0,0 +1,241 @@
+import { config } from "./config.js";
+import { log } from "./log.js";
+import { bankrApi, bankrX402Pay } from "./bankr.js";
+import { createBankrSigner, createPayFetch } from "./x402.js";
+import { resolveEvmAddress } from "./compute.js";
+import { recordSpend } from "./stats.js";
+import { sleep, envNumber } from "./util.js";
+let _walletAddress = null;
+let _payFetch = null;
+export async function initBankr() {
+    // `/wallet/me` returns the EVM wallet under `wallets[]` (the Bankr EIP-7702 wallet
+    // has no top-level `address`), so resolve it the same robust way as everywhere else
+    // — and throw clearly if it's missing, rather than silently storing `undefined`.
+    _walletAddress = await resolveEvmAddress(config.bankrApiKey);
+    return _walletAddress;
+}
+export function walletAddress() {
+    if (!_walletAddress)
+        throw new Error("initBankr() not called yet");
+    return _walletAddress;
+}
+function requestUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.toString();
+    return input.url;
+}
+// Redact credentials carried as query params (auth_token/ct0) before logging a URL.
+function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        for (const k of ["auth_token", "ct0"]) {
+            if (u.searchParams.has(k))
+                u.searchParams.set(k, "[redacted]");
+        }
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+// Atomic USDC amount paid for a given Response, captured from the X-PAYMENT header
+// the x402 client attaches to its (paid) retry request. Keyed on the Response so
+// concurrent paid calls can't clobber each other's amount. wrapFetchWithPayment
+// returns the paid response object directly, so the lookup in payFetch hits.
+const _paidAtomic = new WeakMap();
+// Read the EIP-3009 `authorization.value` (atomic USDC) out of a base64 X-PAYMENT /
+// PAYMENT-SIGNATURE header so we can report what each call actually cost.
+function paymentAtomic(headers) {
+    const raw = headers.get("x-payment") ?? headers.get("payment-signature");
+    if (!raw)
+        return undefined;
+    try {
+        const decoded = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+        const value = decoded?.payload?.authorization?.value;
+        return value != null ? BigInt(value) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Base fetch that records the paid amount per response, then delegates to fetch.
+const tracedFetch = async (input, init) => {
+    const res = await fetch(input, init);
+    // wrapFetchWithPayment sends a Request object (headers on it, no init) on the
+    // paid retry; a first, unpaid attempt carries no payment header and is ignored.
+    const headers = input instanceof Request ? input.headers : new Headers(init?.headers);
+    const atomic = paymentAtomic(headers);
+    if (atomic != null)
+        _paidAtomic.set(res, atomic);
+    return res;
+};
+// Client-side x402 paid fetch: the @x402/fetch client signs the EIP-3009 payment
+// authorization locally (via Bankr /wallet/sign) and sends the X-PAYMENT header
+// itself — instead of delegating the whole flow to Bankr's /wallet/x402-pay
+// gateway. Built lazily (after initBankr() resolves the wallet address) and reused.
+function paidFetch() {
+    if (!_payFetch) {
+        const signer = createBankrSigner(config.bankrApiKey, walletAddress());
+        _payFetch = createPayFetch(signer, tracedFetch);
+    }
+    return _payFetch;
+}
+// Safety cap on what the /wallet/x402-pay fallback may authorize per call — used
+// verbatim when the 402's payment requirements can't be parsed, and as a ceiling
+// when they can (guards against an endpoint demanding an absurd amount).
+const FALLBACK_MAX_USD = envNumber("X402_FALLBACK_MAX_USD", 5);
+const FALLBACK_ATTEMPTS = 2;
+// USD price asked by a 402 response: the base64 payment-required header (Bankr
+// style) or the JSON body (Coinbase x402 style), whichever parses.
+async function requiredUsd(res) {
+    let req;
+    const raw = res.headers.get("payment-required") ?? res.headers.get("x-payment-required");
+    if (raw) {
+        try {
+            req = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+        }
+        catch { /* try body */ }
+    }
+    if (!req) {
+        try {
+            req = await res.clone().json();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const accept = req?.accepts?.[0];
+    const atomic = accept?.maxAmountRequired ?? accept?.amount;
+    const n = Number(atomic);
+    return atomic != null && Number.isFinite(n) ? n / 1e6 : undefined;
+}
+// Repackage a /wallet/x402-pay gateway result as a Response so callers see the
+// same shape as the client-side path, including the paid amount for paidUsd().
+function gatewayResponse(result) {
+    const body = typeof result.response === "string" ? result.response : JSON.stringify(result.response ?? null);
+    const res = new Response(body, {
+        status: result.status || (result.success ? 200 : 402),
+        headers: typeof result.response === "string" ? undefined : { "Content-Type": "application/json" },
+    });
+    if (result.paymentMade?.amountUsd) {
+        _paidAtomic.set(res, BigInt(Math.round(result.paymentMade.amountUsd * 1e6)));
+    }
+    return res;
+}
+// Which spend category an x402 call bills to, by host: the compute API
+// (compute.x402layer.cc) and the X data endpoint (x402.twit.sh) keep their own lines;
+// everything else a skill/hook pays for (image gen, other x402 APIs) rolls up under "x402".
+function spendCategory(url) {
+    if (url.includes("compute.x402layer.cc"))
+        return "compute";
+    if (url.includes("twit.sh"))
+        return "x-api";
+    return "x402";
+}
+export async function payFetch(input, init = {}) {
+    const url = requestUrl(input);
+    const method = (init.method ?? "GET").toUpperCase();
+    let res;
+    let clientErr;
+    try {
+        res = await paidFetch()(input, init);
+    }
+    catch (err) {
+        clientErr = err;
+    }
+    // Fallback: a 402 left after the client-side payment retry (or a thrown payment
+    // error) is usually Bankr having EIP-7702-delegated the wallet to a smart account
+    // after a server-side op (transfer/swap/fee claim) — the EOA then has code, USDC
+    // validates EIP-3009 signatures via ERC-1271 on the delegate, and the plain
+    // /wallet/sign signature is rejected. Bankr's /wallet/x402-pay gateway clears the
+    // delegation and pays in one call, so route the same request through it.
+    if (!res || res.status === 402) {
+        const maxUsd = Math.min((res && (await requiredUsd(res))) ?? FALLBACK_MAX_USD, FALLBACK_MAX_USD);
+        log.warn({ url: redactUrl(url), method, status: res?.status, maxUsd, err: clientErr instanceof Error ? clientErr.message : clientErr }, "x402 client-side payment failed — falling back to Bankr /wallet/x402-pay");
+        for (let attempt = 1; attempt <= FALLBACK_ATTEMPTS; attempt++) {
+            try {
+                const result = await bankrX402Pay(config.bankrApiKey, url, method, typeof init.body === "string" ? init.body : undefined, maxUsd);
+                if (result.success) {
+                    res = gatewayResponse(result);
+                    break;
+                }
+                log.warn({ url: redactUrl(url), attempt, status: result.status, err: result.error }, "x402-pay fallback failed");
+            }
+            catch (err) {
+                log.warn({ url: redactUrl(url), attempt, err: err instanceof Error ? err.message : String(err) }, "x402-pay fallback errored");
+            }
+        }
+        // Both paths exhausted: surface the original client-side failure — the 402
+        // response if there was one, otherwise the thrown error.
+        if (!res)
+            throw clientErr;
+    }
+    // /tweets/mentions is polled constantly — skip its success log to keep logs
+    // clean. Failures are always logged. The per-call USD cost is captured per
+    // response (see paidUsd) and logged by the caller (x/client, treasury) on the
+    // line that's actually shown, so the amount appears next to the call itself.
+    const isMentions = url.includes("/tweets/mentions");
+    const safeUrl = redactUrl(url);
+    // warn, not error: this layer rethrows nothing itself but every caller throws on
+    // !res.ok and the failure is logged as ONE error where it's finally handled —
+    // logging error here too would count a single failure 2-3× in the stats ledger.
+    if (!res.ok)
+        log.warn({ url: safeUrl, method, status: res.status }, "x402 payFetch failed");
+    else if (!isMentions)
+        log.info({ url: safeUrl, method, status: res.status }, "x402 payFetch ok");
+    // Every x402 payment funnels through here, so it's the one place to record spend
+    // into the ledger. Categorise by host: the compute API, the X data endpoint, or any
+    // other x402 endpoint a skill/hook calls (image gen, etc.) → the generic "x402".
+    // (Inference isn't x402 — it's recorded separately from the credit balance.)
+    const paid = paidUsd(res);
+    if (paid != null && paid > 0)
+        recordSpend(spendCategory(url), paid);
+    return res;
+}
+// USD cost (USDC, 6 decimals) of the paid call that produced `res`, or undefined if
+// the response wasn't a paid one. Callers log this on their own success line so the
+// amount shows up where the call is reported (e.g. "x-api GET ... ok {usd}").
+export function paidUsd(res) {
+    const atomic = _paidAtomic.get(res);
+    return atomic != null ? Number(atomic) / 1e6 : undefined;
+}
+// Fixed pause before each submit so rapid back-to-back treasury txs (dev cut → burn →
+// swap → extend) don't trip the Bankr signer's in-flight limit; and attempts/backoff for
+// retrying transient signer/provider errors (provider_inflight_limit, 5xx, timeouts, …).
+const SUBMIT_PAUSE_MS = envNumber("TX_SUBMIT_PAUSE_MS", 1500);
+const SUBMIT_MAX_ATTEMPTS = envNumber("TX_SUBMIT_MAX_ATTEMPTS", 5);
+export async function submitTx(to, data) {
+    if (config.treasuryDryRun) {
+        log.info({ to, data: data.slice(0, 66) + "..." }, "bankr [dry run] submitTx");
+        return "0xdry000000000000000000000000000000000000000000000000000000000000";
+    }
+    // Space submissions out, then retry any failure with exponential backoff (2s, 4s, 8s,
+    // 16s) — gives a busy signer time to clear before the next attempt.
+    await sleep(SUBMIT_PAUSE_MS);
+    let lastErr;
+    for (let attempt = 1; attempt <= SUBMIT_MAX_ATTEMPTS; attempt++) {
+        try {
+            // Bankr's /wallet/submit expects the tx nested under `transaction` (not flat) and
+            // returns `transactionHash`.
+            const res = await bankrApi(config.bankrApiKey, "/wallet/submit", {
+                method: "POST",
+                body: JSON.stringify({
+                    transaction: { to, data, chainId: 8453 },
+                    waitForConfirmation: true,
+                }),
+            });
+            return res.transactionHash ?? res.txHash ?? "";
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt < SUBMIT_MAX_ATTEMPTS) {
+                const delayMs = 2000 * 2 ** (attempt - 1); // 2s → 4s → 8s → 16s
+                log.warn({ to, attempt, maxAttempts: SUBMIT_MAX_ATTEMPTS, delayMs, err: err instanceof Error ? err.message : String(err) }, "submitTx failed — retrying after backoff");
+                await sleep(delayMs);
+            }
+        }
+    }
+    throw lastErr;
+}

package/dist/src/x/client.d.ts

@@ -0,0 +1,74 @@
+import type { SearchResponse, Tweet } from "./types.js";
+export declare function extractTweetId(raw: string): string;
+export declare function tweetImageUrls(tweet: Tweet): string[];
+export declare function getTweetById(id: string): Promise<Tweet>;
+export declare function getTweets(ids: string[]): Promise<Tweet[]>;
+export declare function getUserTweets(username: string, next_token?: string): Promise<SearchResponse>;
+export type TweetSearchParams = {
+    words?: string;
+    phrase?: string;
+    anyWords?: string;
+    noneWords?: string;
+    hashtags?: string;
+    from?: string;
+    to?: string;
+    mentioning?: string;
+    minReplies?: number;
+    minLikes?: number;
+    minReposts?: number;
+    since?: string;
+    until?: string;
+    next_token?: string;
+};
+export declare function searchTweets(params: TweetSearchParams): Promise<SearchResponse>;
+export declare function searchMentions(handle: string): Promise<SearchResponse>;
+export declare function getTweetReplies(id: string, next_token?: string): Promise<SearchResponse>;
+export declare function getRetweetedBy(id: string, next_token?: string): Promise<SearchResponse>;
+export declare function getQuoteTweets(id: string, next_token?: string): Promise<SearchResponse>;
+export declare function postTweet(text: string, opts?: {
+    replyTo?: string;
+    quoteTweetId?: string;
+    mediaIds?: string[];
+}): Promise<void>;
+export declare function postReply(tweetId: string, text: string, mediaIds?: string[]): Promise<void>;
+export declare function deleteTweet(id: string): Promise<void>;
+export declare function likeTweet(id: string): Promise<void>;
+export declare function unlikeTweet(id: string): Promise<void>;
+export declare function retweetTweet(id: string): Promise<void>;
+export declare function unretweetTweet(id: string): Promise<void>;
+export declare function bookmarkTweet(id: string): Promise<void>;
+export declare function unbookmarkTweet(id: string): Promise<void>;
+export declare function uploadMedia(file: Blob | ArrayBuffer | Uint8Array, opts?: {
+    filename?: string;
+    contentType?: string;
+}): Promise<string>;
+export declare function uploadMediaFromUrl(url: string): Promise<string>;
+export declare function getUserByUsername(username: string): Promise<unknown>;
+export declare function getUserById(id: string): Promise<unknown>;
+export declare function searchUsers(query: string, next_token?: string): Promise<unknown>;
+export declare function getUsers(ids: string[]): Promise<unknown>;
+export declare function getFollowers(id: string, next_token?: string): Promise<unknown>;
+export declare function getFollowing(id: string, next_token?: string): Promise<unknown>;
+export declare function followUser(opts: {
+    id?: string;
+    username?: string;
+}): Promise<void>;
+export declare function unfollowUser(opts: {
+    id?: string;
+    username?: string;
+}): Promise<void>;
+export declare function setProfile(opts: {
+    name?: string;
+    bio?: string;
+    location?: string;
+    url?: string;
+}): Promise<void>;
+export declare function getArticle(id: string): Promise<unknown>;
+export declare function getList(id: string): Promise<unknown>;
+export declare function getListMembers(id: string, next_token?: string): Promise<unknown>;
+export declare function getListFollowers(id: string, next_token?: string): Promise<unknown>;
+export declare function getListTweets(id: string, next_token?: string): Promise<SearchResponse>;
+export declare function getCommunity(id: string): Promise<unknown>;
+export declare function getCommunityMembers(id: string, next_token?: string): Promise<unknown>;
+export declare function getCommunityPosts(id: string, next_token?: string): Promise<SearchResponse>;
+export declare function getUserInsights(username: string): Promise<unknown>;

package/dist/src/x/client.js

@@ -0,0 +1,323 @@
+import { payFetch, paidUsd } from "../wallet.js";
+import { config } from "../config.js";
+import { log } from "../log.js";
+import { sleep } from "../util.js";
+// Full X/Twitter API SDK over the x402-paid data endpoint. Not every export is
+// wired to a skill — these are the building blocks skills (e.g. config/skills/x)
+// compose into actions.
+// ─── helpers ────────────────────────────────────────────────────────────────
+function base(path) {
+    return `${config.xApiBaseUrl}${path}`;
+}
+function auth() {
+    return { auth_token: config.twitterAuthToken, ct0: config.twitterCt0 };
+}
+// twit.sh endpoints that act on behalf of the authenticated user. They require
+// auth_token + ct0, which we inject automatically (from env) on every call — these
+// params are never exposed to the LLM/skill. Read endpoints don't need auth.
+const AUTHENTICATED_PATHS = new Set([
+    "/tweets",
+    "/tweets/long",
+    "/tweets/like",
+    "/tweets/bookmark",
+    "/tweets/retweet",
+    "/users/following",
+    "/users/setProfile",
+    // (/tweets/mediaUpload is also authenticated, but uploadMedia injects auth itself —
+    // it's multipart/form-data and bypasses the JSON post()/withAuth() path.)
+]);
+function withAuth(path, params) {
+    return AUTHENTICATED_PATHS.has(path) ? { ...params, ...auth() } : params;
+}
+function buildUrl(path, params) {
+    const url = new URL(base(path));
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined)
+            url.searchParams.set(k, String(v));
+    }
+    return url.toString();
+}
+async function get(path, params = {}) {
+    const t = Date.now();
+    log.info({ path, params: sanitizeParams(params) }, `x-api GET ${path}`);
+    const res = await payFetch(buildUrl(path, params));
+    if (!res.ok) {
+        const body = await res.text();
+        // warn before throwing: the catch site logs the (counted) error — see log.ts.
+        log.warn({ path, status: res.status, ms: Date.now() - t }, `x-api GET ${path} failed`);
+        throw new Error(`GET ${path} failed: ${res.status} ${body}`);
+    }
+    log.info({ path, status: res.status, ms: Date.now() - t, usd: paidUsd(res) }, `x-api GET ${path} ok`);
+    return res.json();
+}
+async function post(path, body) {
+    const payload = withAuth(path, body);
+    // twit.sh proxy endpoints read their params (including auth_token/ct0) from the
+    // QUERY STRING, not the body — confirmed: a correctly-sent body-only POST still
+    // returns "ct0 is null". So put the payload on the URL (and keep it in the body
+    // too for any endpoint that reads it, e.g. /tweets/long's `text`).
+    const url = buildUrl(path, payload);
+    for (let attempt = 1; attempt <= 5; attempt++) {
+        const t = Date.now();
+        log.info({ path, attempt }, `x-api POST ${path}`);
+        const res = await payFetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        // twit.sh returns 2xx (often 201) even when the action failed — the real
+        // signal is an `errors` array embedded in the body (e.g. a created tweet has
+        // `data.id`, a failure has `data.errors` like the 186 length/auth error). So
+        // on a 2xx we inspect the body and treat an embedded error as a failure.
+        if (res.ok) {
+            const json = await res.json().catch(() => undefined);
+            const apiErrors = json?.errors ?? json?.data?.errors;
+            if (Array.isArray(apiErrors) && apiErrors.length > 0) {
+                log.warn({ path, status: res.status, ms: Date.now() - t, errors: apiErrors }, `x-api POST ${path} returned errors`);
+                throw new Error(`POST ${path} failed: ${JSON.stringify(apiErrors)}`);
+            }
+            // Log the raw twit.sh response body (e.g. the created tweet on POST /tweets).
+            log.info({ path, status: res.status, ms: Date.now() - t, usd: paidUsd(res), response: json }, `x-api POST ${path} ok`);
+            return json;
+        }
+        const text = await res.text();
+        if (res.status === 500 && attempt < 5) {
+            log.warn({ path, attempt, status: res.status }, `x-api POST ${path} 500, retrying`);
+            await sleep(attempt * 1000);
+            continue;
+        }
+        log.warn({ path, status: res.status, ms: Date.now() - t, body: text }, `x-api POST ${path} failed`);
+        throw new Error(`POST ${path} failed: ${res.status} ${text}`);
+    }
+    throw new Error(`POST ${path} exhausted retries`);
+}
+async function del(path, params) {
+    const all = withAuth(path, params);
+    const t = Date.now();
+    log.info({ path }, `x-api DELETE ${path}`);
+    const res = await payFetch(buildUrl(path, all), { method: "DELETE" });
+    if (!res.ok) {
+        const body = await res.text();
+        log.warn({ path, status: res.status, ms: Date.now() - t }, `x-api DELETE ${path} failed`);
+        throw new Error(`DELETE ${path} failed: ${res.status} ${body}`);
+    }
+    log.info({ path, status: res.status, ms: Date.now() - t, usd: paidUsd(res) }, `x-api DELETE ${path} ok`);
+    return res.json();
+}
+function sanitizeParams(params) {
+    const safe = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (k === "auth_token" || k === "ct0")
+            safe[k] = "[redacted]";
+        else
+            safe[k] = v;
+    }
+    return safe;
+}
+// ─── tweets ─────────────────────────────────────────────────────────────────
+export function extractTweetId(raw) {
+    return raw.match(/\/status\/(\d+)/)?.[1] ?? raw.trim();
+}
+// Direct CDN URLs of the still images attached to a tweet (photos only — video /
+// animated_gif are skipped). Reads entities.media first, falling back to the
+// parallel media_metadata list, and dedupes. Used by the reply loop to attach the
+// image to a vision model when a mention carries one.
+export function tweetImageUrls(tweet) {
+    const urls = new Set();
+    for (const m of tweet.entities?.media ?? []) {
+        if ((m.type ?? "photo") === "photo" && m.media_url_https)
+            urls.add(m.media_url_https);
+    }
+    for (const m of tweet.media_metadata ?? []) {
+        if (m.media_url)
+            urls.add(m.media_url);
+    }
+    return [...urls];
+}
+export async function getTweetById(id) {
+    return get("/tweets/by/id", { id });
+}
+export async function getTweets(ids) {
+    if (ids.length === 0)
+        return [];
+    log.info({ ids }, "GET x-api /tweets");
+    const json = await get("/tweets", { ids: ids.join(",") });
+    return json.data ?? [];
+}
+export async function getUserTweets(username, next_token) {
+    return get("/tweets/user", { username, next_token });
+}
+export async function searchTweets(params) {
+    return get("/tweets/search", params);
+}
+// Poll the authenticated account's mentions. Uses the purpose-built
+// /tweets/mentions endpoint, which returns the same shape as search but only
+// needs auth (auth_token + ct0). `type` is an optional filter we leave unset.
+// Poll for mentions using the method chosen in config (POLL_METHOD):
+//  - "search":   /tweets/search filtered to tweets mentioning the agent handle.
+//  - "mentions": the dedicated /tweets/mentions endpoint (auth_token + ct0 only).
+// Both return the same SearchResponse shape.
+export async function searchMentions(handle) {
+    // No banner log here — the underlying get()/searchTweets already logs the request
+    // and its "ok" line (with cost), so a separate line would just triple the output.
+    if (config.pollMethod === "mentions") {
+        return get("/tweets/mentions", auth());
+    }
+    return searchTweets({ mentioning: handle });
+}
+export async function getTweetReplies(id, next_token) {
+    return get("/tweets/replies", { id, next_token });
+}
+export async function getRetweetedBy(id, next_token) {
+    return get("/tweets/retweeted_by", { id, next_token });
+}
+export async function getQuoteTweets(id, next_token) {
+    return get("/tweets/quote_tweets", { id, next_token });
+}
+export async function postTweet(text, opts = {}) {
+    // /tweets/long supports the full character limit; plain /tweets rejects longer text.
+    // Both accept `medias` — a comma-separated list of media IDs from uploadMedia() — to
+    // attach images to the post.
+    await post("/tweets/long", {
+        text,
+        ...(opts.replyTo ? { in_reply_to_tweet_id: opts.replyTo } : {}),
+        ...(opts.quoteTweetId ? { quote_tweet_id: opts.quoteTweetId } : {}),
+        ...(opts.mediaIds?.length ? { medias: opts.mediaIds.join(",") } : {}),
+    });
+}
+export async function postReply(tweetId, text, mediaIds) {
+    log.info({ tweetId, media: mediaIds?.length ?? 0 }, "POST x-api reply");
+    await postTweet(text, { replyTo: tweetId, mediaIds });
+}
+export async function deleteTweet(id) {
+    await del("/tweets", { id });
+}
+export async function likeTweet(id) {
+    await post("/tweets/like", { id });
+}
+export async function unlikeTweet(id) {
+    await del("/tweets/like", { id });
+}
+export async function retweetTweet(id) {
+    await post("/tweets/retweet", { id });
+}
+export async function unretweetTweet(id) {
+    await del("/tweets/retweet", { id });
+}
+export async function bookmarkTweet(id) {
+    await post("/tweets/bookmark", { id });
+}
+export async function unbookmarkTweet(id) {
+    await del("/tweets/bookmark", { id });
+}
+// ─── media ─────────────────────────────────────────────────────────────────
+// Upload an image to X and return its media_id — attach it to a post via
+// postTweet({ mediaIds: [id] }). This endpoint is multipart/form-data with auth on the
+// query string (per the twit.sh spec), so it bypasses the JSON post() helper and builds
+// the request itself. Accepts raw bytes (Blob / Uint8Array / ArrayBuffer).
+export async function uploadMedia(file, opts = {}) {
+    const path = "/tweets/mediaUpload";
+    const url = buildUrl(path, auth()); // auth_token + ct0 on the query string
+    // Cast at the Blob boundary: TS 5.7's generic Uint8Array<ArrayBufferLike> doesn't
+    // structurally match lib.dom's BlobPart (ArrayBufferView<ArrayBuffer>), though the
+    // bytes are valid — see microsoft/TypeScript#59417.
+    const blob = file instanceof Blob ? file : new Blob([file], { type: opts.contentType ?? "application/octet-stream" });
+    const form = new FormData();
+    form.append("file", blob, opts.filename ?? "image.png");
+    const t = Date.now();
+    log.info({ path }, `x-api POST ${path}`);
+    // No Content-Type header: fetch sets multipart/form-data with the correct boundary.
+    const res = await payFetch(url, { method: "POST", body: form });
+    if (!res.ok) {
+        const body = await res.text();
+        log.warn({ path, status: res.status, ms: Date.now() - t }, `x-api POST ${path} failed`);
+        throw new Error(`POST ${path} failed: ${res.status} ${body}`);
+    }
+    const json = (await res.json().catch(() => undefined));
+    // The success body is undocumented in the spec; pull the id from the usual
+    // Twitter/twit.sh field names (media_id_string is the canonical Twitter one).
+    const id = json?.media_id_string ?? json?.media_id ?? json?.data?.media_id_string ?? json?.data?.media_id ?? json?.id ?? json?.data?.id;
+    log.info({ path, status: res.status, ms: Date.now() - t, usd: paidUsd(res), mediaId: id }, `x-api POST ${path} ok`);
+    if (id == null)
+        throw new Error(`mediaUpload: no media id in response ${JSON.stringify(json)}`);
+    return String(id);
+}
+// Convenience: fetch an image by URL (plain fetch — public CDN, not x402) and upload it,
+// returning the media_id. Pairs with image-generation skills that produce a hosted URL.
+export async function uploadMediaFromUrl(url) {
+    const res = await fetch(url, { signal: AbortSignal.timeout(20_000) });
+    if (!res.ok)
+        throw new Error(`fetch media ${url} failed: ${res.status}`);
+    const contentType = res.headers.get("content-type") ?? "image/png";
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const filename = new URL(url).pathname.split("/").pop() || "image.png";
+    return uploadMedia(bytes, { filename, contentType });
+}
+// ─── users ──────────────────────────────────────────────────────────────────
+export async function getUserByUsername(username) {
+    return get("/users/by/username", { username });
+}
+export async function getUserById(id) {
+    return get("/users/by/id", { id });
+}
+export async function searchUsers(query, next_token) {
+    return get("/users/search", { query, next_token });
+}
+// Batch-fetch several users in one call. Cheaper than N `getUserById` calls when
+// you already have the numeric ids (e.g. resolving a list of authors/followers).
+export async function getUsers(ids) {
+    return get("/users", { ids: ids.join(",") });
+}
+export async function getFollowers(id, next_token) {
+    return get("/users/followers", { id, next_token });
+}
+export async function getFollowing(id, next_token) {
+    return get("/users/following", { id, next_token });
+}
+export async function followUser(opts) {
+    await post("/users/following", opts);
+}
+export async function unfollowUser(opts) {
+    await del("/users/following", opts);
+}
+// Update the authenticated user's profile. Only the fields you pass are sent; an
+// omitted field is left unchanged (pass an empty string to clear one).
+export async function setProfile(opts) {
+    await post("/users/setProfile", {
+        ...(opts.name !== undefined ? { name: opts.name } : {}),
+        ...(opts.bio !== undefined ? { bio: opts.bio } : {}),
+        ...(opts.location !== undefined ? { location: opts.location } : {}),
+        ...(opts.url !== undefined ? { url: opts.url } : {}),
+    });
+}
+// ─── articles ───────────────────────────────────────────────────────────────
+export async function getArticle(id) {
+    return get("/articles/by/id", { id });
+}
+// ─── lists ──────────────────────────────────────────────────────────────────
+export async function getList(id) {
+    return get("/lists/by/id", { id });
+}
+export async function getListMembers(id, next_token) {
+    return get("/lists/members", { id, next_token });
+}
+export async function getListFollowers(id, next_token) {
+    return get("/lists/followers", { id, next_token });
+}
+export async function getListTweets(id, next_token) {
+    return get("/lists/tweets", { id, next_token });
+}
+// ─── communities ─────────────────────────────────────────────────────────────
+export async function getCommunity(id) {
+    return get("/communities/by/id", { id });
+}
+export async function getCommunityMembers(id, next_token) {
+    return get("/communities/members", { id, next_token });
+}
+export async function getCommunityPosts(id, next_token) {
+    return get("/communities/posts", { id, next_token });
+}
+// ─── workflows ───────────────────────────────────────────────────────────────
+export async function getUserInsights(username) {
+    return get("/workflows/userInsights", { username });
+}