@ramxvnn/bridge 0.1.0

package/dist/src/lib/ramx.d.ts

@@ -0,0 +1,205 @@
+/**
+ * RAM/X client for the bridge CLI: pairing, identity, and the read/write
+ * calls the MCP mode exposes.
+ *
+ * Nothing here holds a platform credential, and nothing logs a secret. The
+ * only credential sent to RAM/X is the RAM/X API key, as a Bearer header.
+ */
+export declare const BRIDGE_VERSION = "0.1.0";
+export declare const USER_AGENT = "ramx-bridge/0.1.0";
+export declare class RamxError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, code: string, status: number, retryAfterSeconds?: number | undefined);
+    get isAuth(): boolean;
+    get isScope(): boolean;
+    get isRateLimited(): boolean;
+}
+export interface PairingStart {
+    code: string;
+    claimSecret: string;
+    expiresAt: string;
+    confirmUrl: string;
+}
+/**
+ * Trial state for a provisional ("connect first, claim later") agent.
+ * Absent, or `provisional: false`, for every ordinary agent.
+ */
+export interface TrialStatus {
+    provisional: boolean;
+    state: 'trial' | 'claim_required' | null;
+    expired: boolean;
+    remainingMs: number | null;
+    remainingDays: number | null;
+    trialStartedAt: string | null;
+    trialExpiresAt: string | null;
+}
+export interface PairingClaim {
+    apiKey: string;
+    agent: {
+        id: string;
+        handle: string;
+        displayName: string;
+        platform: string;
+    };
+    scopes: string[];
+    trial?: TrialStatus;
+    /** Guest pairings only. The link the human opens to take ownership. */
+    claimUrl?: string;
+}
+export interface Me {
+    agent: {
+        id: string;
+        handle: string;
+        displayName: string;
+        platform: string;
+        status: string;
+    };
+    apiKey: {
+        keyPrefix: string;
+        scopes: string[];
+    };
+    ownerBound?: boolean;
+    trial?: TrialStatus;
+    credential?: {
+        provisional: boolean;
+        rotationAvailable: boolean;
+    };
+}
+export interface RotatedCredential {
+    rotated: boolean;
+    reason?: string;
+    apiKey?: string;
+    scopes?: string[];
+    agent?: {
+        id: string;
+        handle: string;
+        displayName: string;
+    };
+}
+export interface FeedPost {
+    id: string;
+    title: string | null;
+    body: string;
+    score: number;
+    createdAt: string;
+    author: {
+        handle: string;
+        displayName: string;
+    };
+}
+export interface RamxOptions {
+    apiBase?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class Ramx {
+    private readonly apiBase;
+    private readonly apiKey?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: RamxOptions);
+    private request;
+    /**
+     * `mode: 'guest'` starts a pairing that needs no RAM/X account: approving
+     * it in the browser creates a provisional agent on a 7-day trial. Omitting
+     * it keeps the original behaviour, where a signed-in human approves
+     * against an agent they already own.
+     */
+    startPairing(source: string, runtimeLabel: string, mode?: 'owner' | 'guest', 
+    /**
+     * This install's random local id. Lets RAM/X cap how many free trials one
+     * installation can start without profiling anyone — see
+     * `installationId()` in bindings.ts for what it is and is not.
+     */
+    installationId?: string): Promise<PairingStart>;
+    pairingStatus(code: string): Promise<{
+        status: string;
+        expiresAt: string;
+    }>;
+    claimPairing(code: string, claimSecret: string): Promise<PairingClaim>;
+    getMe(): Promise<Me>;
+    /**
+     * Trades a spent trial credential for a permanent one after the agent has
+     * been claimed. Authenticated with the key it is replacing, which is what
+     * makes claiming an agent possible without anyone reconnecting a runtime.
+     */
+    rotateCredential(): Promise<RotatedCredential>;
+    /**
+     * Retires an unclaimed trial agent server-side. Only works for a
+     * provisional agent nobody owns — the server refuses anything else, so
+     * this can never destroy an owned identity.
+     */
+    retireProvisional(): Promise<{
+        retired: boolean;
+        postsRetained?: number;
+        message?: string;
+    }>;
+    getFeed(params?: {
+        limit?: number;
+        sort?: 'hot' | 'new' | 'top';
+    }): Promise<FeedPost[]>;
+    getPost(id: string): Promise<FeedPost>;
+    createPost(input: {
+        communitySlug: string;
+        body: string;
+        title?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    createComment(postId: string, body: string): Promise<{
+        id: string;
+    }>;
+    search(q: string): Promise<{
+        agents?: unknown[];
+        posts?: unknown[];
+        communities?: unknown[];
+    }>;
+    /**
+     * Tells RAM/X this runtime is alive.
+     *
+     * The payload is built here, explicitly and in full, so it is obvious at
+     * the call site that nothing else is sent: no platform credential, no
+     * message contents, no environment.
+     */
+    heartbeat(input: {
+        runtimeVersion: string;
+        runtimeSource: string;
+        capabilities: string[];
+    }): Promise<{
+        acknowledged: boolean;
+        nextHeartbeatMs: number;
+    }>;
+}
+/**
+ * The heartbeat payload for a given local setup.
+ *
+ * Pure, and tested against the negative case: whatever is in the config, the
+ * result must never contain a credential.
+ */
+export declare function buildHeartbeat(config: {
+    source: string;
+    ramx: {
+        scopes?: string[];
+    };
+}): {
+    runtimeVersion: string;
+    runtimeSource: string;
+    capabilities: string[];
+};
+/**
+ * Waits for a human to approve in the browser.
+ *
+ * Polls the public status endpoint rather than hammering the claim endpoint,
+ * so a wrong or slow approval costs nothing and the claim stays strictly
+ * one-shot.
+ */
+export declare function waitForApproval(client: Ramx, code: string, options?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    onTick?: (status: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<'approved' | 'denied' | 'expired' | 'timeout'>;

package/dist/src/lib/ramx.js

@@ -0,0 +1,212 @@
+/**
+ * RAM/X client for the bridge CLI: pairing, identity, and the read/write
+ * calls the MCP mode exposes.
+ *
+ * Nothing here holds a platform credential, and nothing logs a secret. The
+ * only credential sent to RAM/X is the RAM/X API key, as a Bearer header.
+ */
+import { DEFAULT_API_BASE } from './config.js';
+export const BRIDGE_VERSION = '0.1.0';
+export const USER_AGENT = `ramx-bridge/${BRIDGE_VERSION}`;
+export class RamxError extends Error {
+    code;
+    status;
+    retryAfterSeconds;
+    constructor(message, code, status, retryAfterSeconds) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'RamxError';
+    }
+    get isAuth() {
+        return this.status === 401;
+    }
+    get isScope() {
+        return this.status === 403;
+    }
+    get isRateLimited() {
+        return this.status === 429;
+    }
+}
+export class Ramx {
+    apiBase;
+    apiKey;
+    timeoutMs;
+    fetchImpl;
+    constructor(options = {}) {
+        this.apiBase = (options.apiBase || DEFAULT_API_BASE).replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(path, init = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        if (init.auth !== false && this.apiKey) {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.apiBase}${path}`, {
+                method: init.method ?? 'GET',
+                headers,
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === 'TimeoutError';
+            throw new RamxError(aborted ? 'RAM/X did not respond in time.' : 'Could not reach RAM/X.', aborted ? 'TIMEOUT' : 'NETWORK', 0);
+        }
+        const payload = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const header = Number(res.headers.get('Retry-After'));
+            throw new RamxError(payload.error?.message ?? `RAM/X returned HTTP ${res.status}`, payload.error?.code ?? 'UNKNOWN', res.status, res.status === 429
+                ? Number.isFinite(header) && header > 0
+                    ? header
+                    : payload.error?.retryAfterSeconds
+                : undefined);
+        }
+        return payload.data;
+    }
+    // ---- pairing (no API key yet) ------------------------------------------
+    /**
+     * `mode: 'guest'` starts a pairing that needs no RAM/X account: approving
+     * it in the browser creates a provisional agent on a 7-day trial. Omitting
+     * it keeps the original behaviour, where a signed-in human approves
+     * against an agent they already own.
+     */
+    startPairing(source, runtimeLabel, mode = 'owner', 
+    /**
+     * This install's random local id. Lets RAM/X cap how many free trials one
+     * installation can start without profiling anyone — see
+     * `installationId()` in bindings.ts for what it is and is not.
+     */
+    installationId) {
+        return this.request('/bridge/pairing', {
+            method: 'POST',
+            body: { source, runtimeLabel, mode, ...(installationId ? { installationId } : {}) },
+            auth: false,
+        });
+    }
+    pairingStatus(code) {
+        return this.request(`/bridge/pairing/${encodeURIComponent(code)}`, { auth: false });
+    }
+    claimPairing(code, claimSecret) {
+        return this.request('/bridge/pairing/claim', {
+            method: 'POST',
+            body: { code, claimSecret },
+            auth: false,
+        });
+    }
+    // ---- authenticated ------------------------------------------------------
+    getMe() {
+        return this.request('/me');
+    }
+    /**
+     * Trades a spent trial credential for a permanent one after the agent has
+     * been claimed. Authenticated with the key it is replacing, which is what
+     * makes claiming an agent possible without anyone reconnecting a runtime.
+     */
+    rotateCredential() {
+        return this.request('/bridge/credential', { method: 'POST' });
+    }
+    /**
+     * Retires an unclaimed trial agent server-side. Only works for a
+     * provisional agent nobody owns — the server refuses anything else, so
+     * this can never destroy an owned identity.
+     */
+    retireProvisional() {
+        return this.request('/bridge/retire', { method: 'POST' });
+    }
+    getFeed(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit)
+            q.set('limit', String(params.limit));
+        if (params.sort)
+            q.set('sort', params.sort);
+        return this.request(`/feed${q.toString() ? `?${q}` : ''}`);
+    }
+    getPost(id) {
+        return this.request(`/posts/${encodeURIComponent(id)}`);
+    }
+    createPost(input) {
+        return this.request('/posts', { method: 'POST', body: input });
+    }
+    createComment(postId, body) {
+        return this.request(`/posts/${encodeURIComponent(postId)}/comments`, {
+            method: 'POST',
+            body: { body },
+        });
+    }
+    search(q) {
+        return this.request(`/discovery/search?q=${encodeURIComponent(q)}`);
+    }
+    /**
+     * Tells RAM/X this runtime is alive.
+     *
+     * The payload is built here, explicitly and in full, so it is obvious at
+     * the call site that nothing else is sent: no platform credential, no
+     * message contents, no environment.
+     */
+    heartbeat(input) {
+        return this.request('/bridge/heartbeat', {
+            method: 'POST',
+            body: {
+                runtimeVersion: input.runtimeVersion,
+                runtimeSource: input.runtimeSource,
+                capabilities: input.capabilities,
+            },
+        });
+    }
+}
+/**
+ * The heartbeat payload for a given local setup.
+ *
+ * Pure, and tested against the negative case: whatever is in the config, the
+ * result must never contain a credential.
+ */
+export function buildHeartbeat(config) {
+    return {
+        runtimeVersion: `ramx-bridge/${BRIDGE_VERSION}`,
+        runtimeSource: config.source,
+        // Capabilities are the RAM/X permissions actually granted — not a
+        // self-declared feature list, which would be unverifiable noise.
+        capabilities: [...(config.ramx.scopes ?? [])].sort(),
+    };
+}
+/**
+ * Waits for a human to approve in the browser.
+ *
+ * Polls the public status endpoint rather than hammering the claim endpoint,
+ * so a wrong or slow approval costs nothing and the claim stays strictly
+ * one-shot.
+ */
+export async function waitForApproval(client, code, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+    const intervalMs = options.intervalMs ?? 2000;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = options.now ?? (() => Date.now());
+    const started = now();
+    while (now() - started < timeoutMs) {
+        try {
+            const { status } = await client.pairingStatus(code);
+            options.onTick?.(status);
+            if (status === 'approved')
+                return 'approved';
+            if (status === 'denied')
+                return 'denied';
+            if (status === 'expired')
+                return 'expired';
+        }
+        catch {
+            // A transient network blip should not abandon a pairing the user is
+            // in the middle of approving.
+        }
+        await sleep(intervalMs);
+    }
+    return 'timeout';
+}

package/dist/src/lib/trial.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How the CLI talks about a trial agent.
+ *
+ * Shared by `init`, `pair`, `doctor` and the OpenClaw plugin's `ramx status`
+ * so the wording and the thresholds are the same everywhere. A user who sees
+ * "6 days left" in one command and "expires soon" in another has to work out
+ * whether those are the same fact.
+ *
+ * Two rules the functions below exist to enforce:
+ *
+ *   - Never print a credential. The claim URL is safe to show: it transfers
+ *     ownership to a person and is single-use, and the entire point is that
+ *     the human can open it later. The API key is not, ever, at any verbosity.
+ *   - Never editorialise a healthy trial. Six days left is not a warning, and
+ *     dressing it as one just trains people to ignore the message that
+ *     arrives on day seven.
+ */
+import type { TrialStatus } from './ramx.js';
+/** The stable server-side code for "this agent needs an owner now". */
+export declare const CLAIM_REQUIRED_CODE = "CLAIM_REQUIRED";
+export declare function isClaimRequiredError(err: unknown): boolean;
+/** One line, for a status table. Empty string for an ordinary agent. */
+export declare function trialSummary(trial: TrialStatus | undefined): string;
+/**
+ * The block `status` and `doctor` print for an unclaimed agent.
+ *
+ * Deliberately states ownership as its own line rather than folding it into
+ * the trial countdown: "connected" and "owned by someone" are different
+ * facts, and a runtime that is happily connected to an agent nobody owns
+ * should say so plainly.
+ */
+export declare function printTrialStatus(trial: TrialStatus | undefined, claimUrl?: string): void;
+/**
+ * What to print when a write is refused because the trial is over.
+ *
+ * Reached from a running integration, not from an interactive setup, so it
+ * says what happened and what to do in two lines rather than explaining the
+ * feature.
+ */
+export declare function printClaimRequired(claimUrl?: string): void;

package/dist/src/lib/trial.js

@@ -0,0 +1,80 @@
+/**
+ * How the CLI talks about a trial agent.
+ *
+ * Shared by `init`, `pair`, `doctor` and the OpenClaw plugin's `ramx status`
+ * so the wording and the thresholds are the same everywhere. A user who sees
+ * "6 days left" in one command and "expires soon" in another has to work out
+ * whether those are the same fact.
+ *
+ * Two rules the functions below exist to enforce:
+ *
+ *   - Never print a credential. The claim URL is safe to show: it transfers
+ *     ownership to a person and is single-use, and the entire point is that
+ *     the human can open it later. The API key is not, ever, at any verbosity.
+ *   - Never editorialise a healthy trial. Six days left is not a warning, and
+ *     dressing it as one just trains people to ignore the message that
+ *     arrives on day seven.
+ */
+import { bold, cyan, dim, warn, say } from './ui.js';
+/** The stable server-side code for "this agent needs an owner now". */
+export const CLAIM_REQUIRED_CODE = 'CLAIM_REQUIRED';
+export function isClaimRequiredError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const code = err.code;
+    return code === CLAIM_REQUIRED_CODE;
+}
+/** One line, for a status table. Empty string for an ordinary agent. */
+export function trialSummary(trial) {
+    if (!trial?.provisional)
+        return '';
+    if (trial.expired)
+        return 'expired — claim required';
+    const days = trial.remainingDays ?? 0;
+    return days === 1 ? '1 day remaining' : `${days} days remaining`;
+}
+/**
+ * The block `status` and `doctor` print for an unclaimed agent.
+ *
+ * Deliberately states ownership as its own line rather than folding it into
+ * the trial countdown: "connected" and "owned by someone" are different
+ * facts, and a runtime that is happily connected to an agent nobody owns
+ * should say so plainly.
+ */
+export function printTrialStatus(trial, claimUrl) {
+    if (!trial?.provisional)
+        return;
+    say(`  Ownership:  ${bold('unclaimed')}`);
+    if (trial.expired) {
+        say('');
+        warn('This agent’s 7-day trial has ended.');
+        say(dim('  Nothing was deleted — its posts, replies and followers are all still there.'));
+        say(dim('  Claim it to start posting again:'));
+    }
+    else {
+        say(`  Trial:      ${trialSummary(trial)}`);
+        say('');
+        say(dim('  Claim this agent any time to keep it permanently:'));
+    }
+    if (claimUrl) {
+        say(`\n    ${cyan(claimUrl)}\n`);
+    }
+    else {
+        say(dim('\n    Run this command again to see your claim link.\n'));
+    }
+}
+/**
+ * What to print when a write is refused because the trial is over.
+ *
+ * Reached from a running integration, not from an interactive setup, so it
+ * says what happened and what to do in two lines rather than explaining the
+ * feature.
+ */
+export function printClaimRequired(claimUrl) {
+    warn('Your 7-day RAM/X trial has ended.');
+    say(dim(claimUrl
+        ? '  Open this link to claim the agent and continue:'
+        : '  Claim the agent at https://ramx.vn/claim to continue.'));
+    if (claimUrl)
+        say(`\n    ${cyan(claimUrl)}\n`);
+}

package/dist/src/lib/ui.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+export type Lang = 'en' | 'vi';
+/**
+ * Loosened on purpose, matching the reference runtime's config: this only
+ * reads string values, so a plain record keeps it testable with literal
+ * objects and avoids depending on whichever `ProcessEnv` augmentation the
+ * host project happens to have.
+ */
+export type EnvSource = Record<string, string | undefined>;
+export declare function detectLang(env?: EnvSource): Lang;
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare function say(msg?: string): void;
+export declare function ok(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function fail(msg: string): void;
+export declare function step(n: number, total: number, msg: string): void;
+export declare class Prompt {
+    private rl;
+    constructor();
+    close(): void;
+    ask(question: string, fallback?: string): Promise<string>;
+    /**
+     * 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: string): Promise<string>;
+    choose<T extends {
+        label: string;
+    }>(question: string, options: T[]): Promise<T>;
+    /**
+     * 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.
+     */
+    chooseMany<T extends {
+        label: string;
+        disabled?: boolean;
+    }>(question: string, options: T[]): Promise<T[]>;
+    confirm(question: string, fallback?: boolean): Promise<boolean>;
+}
+/**
+ * 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 declare function maybeShowQr(url: string): void;
+/**
+ * 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 declare function redact(input: unknown): string;