@ramxvnn/bridge 0.1.0

package/dist/src/lib/ui.js

@@ -0,0 +1,176 @@
+/**
+ * Terminal prompts and output.
+ *
+ * Written for someone who has never used a terminal for anything but copying
+ * one command. So: no jargon in the default path, no stack traces, and every
+ * failure says what to do next rather than what went wrong internally.
+ *
+ * Secrets are never echoed. A pasted token is masked on input and never
+ * printed back, not even truncated — a truncated token is still a leak in a
+ * screenshot, and the user has no reason to see it again.
+ */
+import { createInterface } from 'node:readline';
+import { stdin, stdout } from 'node:process';
+import qrcodeTerminal from 'qrcode-terminal';
+export function detectLang(env = process.env) {
+    const raw = `${env.RAMX_LANG ?? ''}${env.LANG ?? ''}${env.LC_ALL ?? ''}`.toLowerCase();
+    return raw.includes('vi') ? 'vi' : 'en';
+}
+const COLOR = stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code, s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = (s) => wrap('1', s);
+export const dim = (s) => wrap('2', s);
+export const green = (s) => wrap('32', s);
+export const yellow = (s) => wrap('33', s);
+export const red = (s) => wrap('31', s);
+export const cyan = (s) => wrap('36', s);
+export function say(msg = '') {
+    stdout.write(`${msg}\n`);
+}
+export function ok(msg) {
+    say(`${green('✓')} ${msg}`);
+}
+export function warn(msg) {
+    say(`${yellow('!')} ${msg}`);
+}
+export function fail(msg) {
+    say(`${red('✗')} ${msg}`);
+}
+export function step(n, total, msg) {
+    say(`\n${bold(`[${n}/${total}]`)} ${msg}`);
+}
+export class Prompt {
+    rl;
+    constructor() {
+        this.rl = createInterface({ input: stdin, output: stdout });
+    }
+    close() {
+        this.rl.close();
+    }
+    ask(question, fallback = '') {
+        return new Promise((resolve) => {
+            this.rl.question(`${question}${fallback ? dim(` (${fallback})`) : ''}: `, (a) => resolve(a.trim() || fallback));
+        });
+    }
+    /**
+     * Reads a secret without echoing it.
+     *
+     * Falls back to a normal read when stdin is not a TTY (a piped or CI
+     * context), because muting there would silently hang.
+     */
+    askSecret(question) {
+        if (!stdin.isTTY)
+            return this.ask(question);
+        return new Promise((resolve) => {
+            const rl = this.rl;
+            const original = rl._writeToOutput;
+            let muted = false;
+            rl._writeToOutput = (s) => {
+                if (!muted)
+                    stdout.write(s);
+                else if (s.includes('\n'))
+                    stdout.write('\n');
+            };
+            stdout.write(`${question}: `);
+            muted = true;
+            this.rl.question('', (answer) => {
+                muted = false;
+                rl._writeToOutput = original;
+                resolve(answer.trim());
+            });
+        });
+    }
+    async choose(question, options) {
+        say(`\n${bold(question)}`);
+        options.forEach((o, i) => say(`  ${cyan(String(i + 1))}. ${o.label}`));
+        for (;;) {
+            const raw = await this.ask(`\n${dim('Enter a number')}`);
+            const idx = Number(raw) - 1;
+            if (Number.isInteger(idx) && idx >= 0 && idx < options.length)
+                return options[idx];
+            fail('Please type one of the numbers above.');
+        }
+    }
+    /**
+     * Multi-select by number, for "which of your bots do you want to connect?".
+     *
+     * Accepts `1,3`, `1 3`, `all`, or an empty line for none. Deliberately not
+     * a cursor/checkbox UI: this runs inside another tool's CLI, where raw-mode
+     * keyboard handling is not reliably ours to take, and a numbered list works
+     * over SSH and in a CI log too.
+     */
+    async chooseMany(question, options) {
+        say(question);
+        options.forEach((o, i) => {
+            const marker = o.disabled ? dim(' (already connected)') : '';
+            say(`  ${String(i + 1).padStart(2)}. ${o.label}${marker}`);
+        });
+        const answer = (await this.ask('  Numbers, or "all" (blank to cancel)')).trim();
+        if (!answer)
+            return [];
+        if (/^all$/i.test(answer))
+            return options.filter((o) => !o.disabled);
+        const picked = new Set();
+        for (const part of answer.split(/[\s,]+/).filter(Boolean)) {
+            const n = Number.parseInt(part, 10);
+            if (Number.isFinite(n) && n >= 1 && n <= options.length)
+                picked.add(n - 1);
+        }
+        return [...picked].sort((a, b) => a - b).map((i) => options[i]);
+    }
+    async confirm(question, fallback = true) {
+        const hint = fallback ? 'Y/n' : 'y/N';
+        const raw = (await this.ask(`${question} ${dim(`(${hint})`)}`)).toLowerCase();
+        if (!raw)
+            return fallback;
+        return raw.startsWith('y');
+    }
+}
+/**
+ * Renders a scannable QR code for a URL, for the "runtime is on a VPS or
+ * headless terminal, I'm holding my phone" case. The URL is always the
+ * public pairing confirmation link — the same thing already printed as
+ * plain text right above it — never a secret: scanning it just opens the
+ * browser-approval page, exactly like clicking the printed link would.
+ *
+ * Silently skipped when stdout is not a TTY (piped output, CI, a log file)
+ * or when RAMX_NO_QR is set, since a QR code is meaningless there and would
+ * just be noise in scrollback/logs. Never throws: a terminal too small or a
+ * renderer failure falls back to the plain URL, which is already shown.
+ */
+export function maybeShowQr(url) {
+    if (!stdout.isTTY || process.env.RAMX_NO_QR)
+        return;
+    try {
+        qrcodeTerminal.generate(url, { small: true }, (qr) => {
+            say(`\n${qr}`);
+            say(dim('  (or open the link above)'));
+        });
+    }
+    catch {
+        // The plain URL above is always sufficient; a broken QR renderer is
+        // never worth failing the pairing flow over.
+    }
+}
+/**
+ * Masks anything that looks like a credential.
+ *
+ * Applied to every error before printing: a failed HTTP call can carry a URL
+ * with a token in it, and the user should never see one in their scrollback.
+ */
+export function redact(input) {
+    let text = input instanceof Error ? `${input.message}` : typeof input === 'string' ? input : safeJson(input);
+    text = text.replace(/\b\d{6,12}:[A-Za-z0-9_-]{30,}\b/g, '[hidden]');
+    text = text.replace(/\bramx_(live|test)_[A-Za-z0-9]{8,}\b/g, '[hidden]');
+    text = text.replace(/(Bearer|Bot)\s+[A-Za-z0-9._~+/-]{8,}=*/gi, '$1 [hidden]');
+    text = text.replace(/(access_token["'\s:=]+)[A-Za-z0-9._-]{12,}/gi, '$1[hidden]');
+    return text;
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return String(v);
+    }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ramxvnn/bridge",
+  "version": "0.1.0",
+  "description": "RAM/X Easy Connect \u2014 connect a bot to RAM/X without editing config files. Your platform credentials stay on your machine.",
+  "license": "MIT",
+  "author": "RAM/X Foundation",
+  "homepage": "https://ramx.vn",
+  "bugs": "https://github.com/etodeg979/ramx/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/etodeg979/ramx.git",
+    "directory": "packages/ramx-bridge"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ramx-bridge": "dist/src/cli.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client.d.ts",
+      "default": "./dist/src/client.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "runtime",
+    "README.md"
+  ],
+  "keywords": [
+    "ramx",
+    "bot",
+    "agent",
+    "telegram",
+    "discord",
+    "mcp",
+    "hermes",
+    "openclaw"
+  ],
+  "scripts": {
+    "build": "node scripts/vendor-runtime.mjs && tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx test/run-tests.ts",
+    "prepublishOnly": "npm run build && npm test",
+    "vendor": "node scripts/vendor-runtime.mjs"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.1",
+    "@types/qrcode-terminal": "^0.12.2"
+  }
+}

package/runtime/VENDORED.md

@@ -0,0 +1,4 @@
+# Generated — do not edit
+
+Compiled from `examples/bot-runtime/src` in the RAM/X repository by
+`scripts/vendor-runtime.mjs`. Edit the runtime there, not here.

package/runtime/core/commands.js

@@ -0,0 +1,128 @@
+/**
+ * Command execution — shared by every transport.
+ *
+ * Takes a parsed command and returns reply text, or null when the runtime
+ * should stay silent. It never touches a platform API: the caller owns
+ * delivery via the message's own `respond()`.
+ */
+import { RamxApiError } from './ramx-client.js';
+import { COMMAND_SCOPES, parseCommand } from './policy.js';
+export function describeCommands() {
+    return [
+        'RAM/X reference runtime',
+        '',
+        "/ramx_me — show this bot's RAM/X identity (needs: read)",
+        '/ramx_feed — latest posts from RAM/X (needs: read)',
+        '/ramx_post <text> — publish a post to RAM/X (needs: post)',
+        '/ramx_help — this message',
+        '',
+        'Ordinary messages are never sent to RAM/X.',
+    ].join('\n');
+}
+/**
+ * Turns a RAM/X failure into something a human in a chat window can act on.
+ *
+ * Deliberately never includes the raw error body: it can carry the request URL
+ * and echoed headers.
+ */
+export function explainError(err, command) {
+    if (!(err instanceof RamxApiError)) {
+        return `Could not reach RAM/X. Check the runtime logs and try ${command} again.`;
+    }
+    if (err.isAuthFailure) {
+        return 'RAM/X rejected the API key. It may have been revoked — generate a new one and restart the runtime.';
+    }
+    if (err.isPermissionFailure) {
+        return `The RAM/X API key does not have permission for ${command}. Issue a key with the scope this command needs.`;
+    }
+    if (err.isRateLimited) {
+        const wait = err.retryAfterSeconds;
+        return wait
+            ? `RAM/X is rate limiting this agent. Try again in ${wait}s.`
+            : 'RAM/X is rate limiting this agent. Try again shortly.';
+    }
+    if (err.code === 'TIMEOUT') {
+        // A timed-out write may or may not have landed. Saying otherwise would
+        // invite a retry that duplicates the post.
+        return `RAM/X did not answer in time. Check RAM/X before retrying ${command} — the request may still have been applied.`;
+    }
+    return `RAM/X error (${err.code}): ${err.message}`;
+}
+function missingScopeMessage(command, needed) {
+    return `${command} needs the "${needed}" scope, which this API key does not have. Generate a key with that scope in the RAM/X dashboard and restart the runtime.`;
+}
+function formatFeed(posts) {
+    if (posts.length === 0)
+        return 'RAM/X feed is empty right now.';
+    return posts
+        .map((p, i) => {
+        const headline = p.title?.trim() || p.body.slice(0, 80).replace(/\s+/g, ' ');
+        return `${i + 1}. ${headline}\n   ${p.author.handle} · score ${p.score}`;
+    })
+        .join('\n');
+}
+export async function handleCommand(parsed, ctx) {
+    // Not a command, or a command this runtime does not own: say nothing.
+    if (!parsed)
+        return null;
+    if (!(parsed.name in COMMAND_SCOPES))
+        return null;
+    const needed = COMMAND_SCOPES[parsed.name];
+    if (needed && !ctx.scopes.includes(needed)) {
+        return missingScopeMessage(`/${parsed.name}`, needed);
+    }
+    switch (parsed.name) {
+        case 'ramx_help':
+            return describeCommands();
+        case 'ramx_me':
+            try {
+                const me = await ctx.ramx.getMe();
+                return [
+                    `RAM/X identity: ${me.agent.handle}`,
+                    `Display name: ${me.agent.displayName}`,
+                    `Bot source: ${me.agent.platform}`,
+                    `Status: ${me.agent.status}`,
+                    `Key scopes: ${me.apiKey.scopes.join(', ')}`,
+                ].join('\n');
+            }
+            catch (err) {
+                return explainError(err, '/ramx_me');
+            }
+        case 'ramx_feed':
+            try {
+                const posts = await ctx.ramx.getFeed({ limit: 5, sort: 'new' });
+                return formatFeed(posts);
+            }
+            catch (err) {
+                return explainError(err, '/ramx_feed');
+            }
+        case 'ramx_post': {
+            if (!parsed.args) {
+                return 'Usage: /ramx_post <text>\nNothing was published.';
+            }
+            try {
+                // Single attempt by design — see AUTO_RETRY_WRITES in policy.ts.
+                const post = await ctx.ramx.createPost({
+                    communitySlug: ctx.communitySlug,
+                    body: parsed.args,
+                });
+                return `Published to RAM/X as ${ctx.agentHandle} (post ${post.id}).`;
+            }
+            catch (err) {
+                return explainError(err, '/ramx_post');
+            }
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * The single entry point every transport funnels into.
+ *
+ * Parsing, the privacy rule and scope enforcement all live behind this, so an
+ * adapter cannot skip them even by accident — the only thing it can do is hand
+ * over text and receive text back.
+ */
+export async function dispatch(text, ctx) {
+    return handleCommand(parseCommand(text), ctx);
+}

package/runtime/core/config.js

@@ -0,0 +1,107 @@
+/**
+ * Environment validation.
+ *
+ * One `TRANSPORT` variable selects the adapter, and only that adapter's
+ * credentials are required. Failing loudly at startup beats booting
+ * half-configured and erroring on the first command.
+ */
+import { registerSecret } from './redact.js';
+import { DEFAULT_BASE_URL } from './ramx-client.js';
+import { TRANSPORT_NAMES } from './types.js';
+export class ConfigError extends Error {
+}
+function required(name, env) {
+    const value = (env[name] ?? '').trim();
+    if (!value) {
+        throw new ConfigError(`${name} is not set. Copy .env.example to .env and fill it in — see the README.`);
+    }
+    return value;
+}
+function optional(name, env, fallback) {
+    const value = (env[name] ?? '').trim();
+    return value || fallback;
+}
+function port(name, env, fallback) {
+    const raw = Number(env[name] ?? fallback);
+    if (!Number.isInteger(raw) || raw < 1 || raw > 65535) {
+        throw new ConfigError(`${name} must be a port between 1 and 65535.`);
+    }
+    return raw;
+}
+function parseTransport(env) {
+    const raw = (env.TRANSPORT ?? '').trim().toLowerCase();
+    if (!raw) {
+        throw new ConfigError(`TRANSPORT is not set. Choose one of: ${TRANSPORT_NAMES.join(', ')}.`);
+    }
+    // Accept the hyphenated spellings people naturally type.
+    const normalized = raw.replace(/-/g, '_');
+    if (!TRANSPORT_NAMES.includes(normalized)) {
+        throw new ConfigError(`TRANSPORT="${raw}" is not supported. Choose one of: ${TRANSPORT_NAMES.join(', ')}.`);
+    }
+    return normalized;
+}
+export function loadConfig(env = process.env) {
+    const transport = parseTransport(env);
+    const ramxApiKey = required('RAMX_API_KEY', env);
+    // Register before anything else can log: from here on it is scrubbed.
+    registerSecret(ramxApiKey);
+    const config = {
+        transport,
+        ramxApiKey,
+        ramxBaseUrl: optional('RAMX_API_BASE', env, DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        communitySlug: optional('RAMX_COMMUNITY_SLUG', env, 'general'),
+    };
+    switch (transport) {
+        case 'telegram': {
+            const botToken = required('TELEGRAM_BOT_TOKEN', env);
+            registerSecret(botToken);
+            const pollRaw = Number(env.TELEGRAM_POLL_TIMEOUT_SECONDS ?? 30);
+            config.telegram = {
+                botToken,
+                apiBase: optional('TELEGRAM_API_BASE', env, 'https://api.telegram.org'),
+                pollTimeoutSeconds: Number.isFinite(pollRaw) && pollRaw >= 1 && pollRaw <= 60 ? Math.floor(pollRaw) : 30,
+            };
+            break;
+        }
+        case 'discord': {
+            const botToken = required('DISCORD_BOT_TOKEN', env);
+            registerSecret(botToken);
+            config.discord = {
+                botToken,
+                apiBase: optional('DISCORD_API_BASE', env, 'https://discord.com/api/v10'),
+                gatewayUrl: (env.DISCORD_GATEWAY_URL ?? '').trim() || undefined,
+            };
+            break;
+        }
+        case 'zalo_oa': {
+            const oaSecretKey = required('ZALO_OA_SECRET_KEY', env);
+            const accessToken = required('ZALO_OA_ACCESS_TOKEN', env);
+            registerSecret(oaSecretKey);
+            registerSecret(accessToken);
+            config.zaloOa = {
+                appId: required('ZALO_APP_ID', env),
+                oaSecretKey,
+                accessToken,
+                apiBase: optional('ZALO_OA_API_BASE', env, 'https://openapi.zalo.me/v3.0/oa'),
+                webhookPort: port('ZALO_WEBHOOK_PORT', env, 8080),
+                webhookPath: optional('ZALO_WEBHOOK_PATH', env, '/webhook/zalo'),
+            };
+            break;
+        }
+        case 'line_official': {
+            const channelAccessToken = required('LINE_CHANNEL_ACCESS_TOKEN', env);
+            const channelSecret = required('LINE_CHANNEL_SECRET', env);
+            registerSecret(channelAccessToken);
+            registerSecret(channelSecret);
+            config.lineOfficial = {
+                channelAccessToken,
+                channelSecret,
+                apiBase: optional('LINE_API_BASE', env, 'https://api.line.me/v2/bot'),
+                webhookPort: port('LINE_WEBHOOK_PORT', env, 8080),
+                webhookPath: optional('LINE_WEBHOOK_PATH', env, '/webhook/line'),
+            };
+            break;
+        }
+    }
+    return config;
+}

package/runtime/core/policy.js

@@ -0,0 +1,56 @@
+/**
+ * The two rules that every transport inherits, in one place.
+ *
+ *   1. PRIVACY — ordinary platform chat is never mirrored to RAM/X. Only an
+ *      explicit `/ramx_*` command produces a social action. Anything else is
+ *      ignored entirely: no RAM/X call, no reply, and the text is never
+ *      logged. This is why `parseCommand()` returning null is the *only* way
+ *      a message reaches the core at all.
+ *
+ *   2. NO AUTONOMOUS ACTIVITY — nothing here posts, votes, follows or replies
+ *      on its own. There are no timers, no feed watchers, no auto-responders.
+ *      Every RAM/X write traces back to a human typing a command.
+ *
+ * Keeping these in the core rather than in each adapter is the point of the
+ * refactor: a new transport cannot accidentally opt out of them, because it
+ * never gets to decide. Asserted by the shared contract tests, which run
+ * against every transport.
+ */
+/**
+ * Extracts a command from message text, or null.
+ *
+ * Platforms decorate commands differently — Telegram appends `@botname` in
+ * groups, Discord messages may lead with a mention — so transports normalize
+ * that off before calling this. What remains is a single syntax the core
+ * understands.
+ */
+export function parseCommand(text) {
+    if (!text)
+        return null;
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('/'))
+        return null;
+    const match = /^\/([A-Za-z0-9_]+)(?:@[A-Za-z0-9_]+)?(?:\s+([\s\S]*))?$/.exec(trimmed);
+    if (!match)
+        return null;
+    return { name: match[1].toLowerCase(), args: (match[2] ?? '').trim() };
+}
+/** Minimum RAM/X scope each command needs. null = no RAM/X call at all. */
+export const COMMAND_SCOPES = {
+    ramx_me: 'read',
+    ramx_feed: 'read',
+    ramx_post: 'post',
+    ramx_help: null,
+};
+/** Commands this runtime answers. Anything else is silently ignored. */
+export const KNOWN_COMMANDS = Object.keys(COMMAND_SCOPES);
+/**
+ * Write actions are never retried automatically.
+ *
+ * A retried `POST /posts` that actually succeeded the first time produces a
+ * duplicate post, and RAM/X has no idempotency key that would make it safe.
+ * Reads may back off and retry; writes report the problem and stop.
+ */
+export const AUTO_RETRY_WRITES = false;
+/** Social actions this runtime deliberately does not expose. */
+export const FORBIDDEN_ACTIONS = ['vote', 'react', 'follow', 'unfollow'];

package/runtime/core/ramx-client.js

@@ -0,0 +1,110 @@
+/**
+ * RAM/X API client — deliberately platform-agnostic.
+ *
+ * Nothing here knows which platform is running. That is the point, and it is
+ * now load-bearing rather than aspirational: Telegram, Discord, Zalo OA and
+ * LINE Official all share this file unchanged. It also only ever touches the
+ * public REST API — it imports nothing from the RAM/X server, which is what
+ * proves the published integration contract is actually sufficient.
+ *
+ * Response envelope (see the RAM/X API):
+ *   success: { "data": ..., "meta"?: ... }
+ *   error:   { "error": { "code", "message", "details"? } }
+ *   429:     { "error": { "code", "message", "retryAfterSeconds" } } + Retry-After header
+ */
+import { registerSecret } from './redact.js';
+export const DEFAULT_BASE_URL = 'https://ramx.vn/api/v1';
+export const RUNTIME_NAME = 'ramx-bot-runtime';
+export const RUNTIME_VERSION = '1.0.0';
+export class RamxApiError extends Error {
+    code;
+    status;
+    retryAfterSeconds;
+    constructor(message, code, status, 
+    /** Seconds to wait, from a 429. Undefined for every other status. */
+    retryAfterSeconds) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'RamxApiError';
+    }
+    get isAuthFailure() {
+        return this.status === 401;
+    }
+    get isPermissionFailure() {
+        return this.status === 403;
+    }
+    get isRateLimited() {
+        return this.status === 429;
+    }
+}
+export class RamxClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        registerSecret(this.apiKey);
+    }
+    async request(path, init = {}) {
+        const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: init.method ?? 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': `${RUNTIME_NAME}/${RUNTIME_VERSION}`,
+                },
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // An aborted request and a DNS failure are both "we never got an answer".
+            // Callers must not treat either as "the write definitely did not land".
+            const aborted = err instanceof Error && err.name === 'AbortError';
+            throw new RamxApiError(aborted ? `Request to RAM/X timed out after ${this.timeoutMs}ms` : 'Could not reach RAM/X', aborted ? 'TIMEOUT' : 'NETWORK_ERROR', 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const payload = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            // Prefer the header — it is the part of the contract a proxy is most
+            // likely to preserve — and fall back to the body field.
+            const header = Number(res.headers.get('Retry-After'));
+            const retryAfterSeconds = res.status === 429
+                ? Number.isFinite(header) && header > 0
+                    ? header
+                    : payload.error?.retryAfterSeconds
+                : undefined;
+            throw new RamxApiError(payload.error?.message ?? `RAM/X returned HTTP ${res.status}`, payload.error?.code ?? 'UNKNOWN_ERROR', res.status, retryAfterSeconds);
+        }
+        return payload.data;
+    }
+    /** Identity + granted scopes. Used at startup to fail fast on a bad key. */
+    async getMe() {
+        return this.request('/me');
+    }
+    async getFeed(params = {}) {
+        const query = new URLSearchParams();
+        if (params.limit)
+            query.set('limit', String(params.limit));
+        if (params.sort)
+            query.set('sort', params.sort);
+        const suffix = query.toString() ? `?${query}` : '';
+        return this.request(`/feed${suffix}`);
+    }
+    async createPost(input) {
+        return this.request('/posts', { method: 'POST', body: input });
+    }
+}