Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Beeper Desktop API client (fork issue #29, part of #1).
*
* Raw `fetch`, deliberately NOT `@beeper/desktop-api` — the published SDK lags
* the live API and exposes no `Account.status`, no `loginID`, no `/v1/bridges`;
* `GET /v1/spec` on the running instance is the authoritative reference.
* Every other Beeper feature (#30-#37) is built on this module.
*
* `server/lib/safeUrlFetch.js` cannot wrap this: it blocks loopback in both
* postures by design, and Beeper Desktop's whole API IS a loopback service
* (default `http://127.0.0.1:23373`). This module goes straight to
* `fetchWithTimeout` instead, same as `ollamaManager.js` / `lmStudioManager.js`
* for the other local-daemon integrations. `safeUrlFetch`'s `readBodyCapped`
* two-stage byte cap (Content-Length early-out, then a streamed abort once
* accumulated bytes exceed the ceiling) is NOT reused here — every JSON
* response this module reads is small, from a local trusted process, read via
* `readResponseJson`. The byte-streaming asset fetch (attachment mirror, #37 —
* `headAsset` / `fetchAssetStream` below) is the one caller that wants that
* two-stage shape, and it enforces its own: a `HEAD` pre-flight plus a
* mid-stream abort, both against `BEEPER_ATTACHMENT_MAX_BYTES`.
*
* Auth and base URL: `settings.beeper.baseUrl` (default below) and, since #31,
* the vault-backed credential store (`beeperCredentials.resolveBeeperToken` —
* AES-256-GCM in Postgres, per fork issue #11 decision 6). `resolveBeeperConfig`
* is the one call site that resolves it; the legacy plaintext
* `settings.beeper.token` from #29 survives there as a READ-only fallback so an
* install that hand-edited one keeps working. Nothing here ever writes a token.
* Every caller-facing function also accepts an explicit `{ baseUrl, token }`
* override, which skips both stores entirely.
*/
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js';
import { readResponseJson } from '../lib/readResponseJson.js';
import { describeFetchError, isReplayableConnectionError } from '../lib/fetchErrorChain.js';
import { ServerError } from '../lib/errorHandler.js';
import { isPlainObject } from '../lib/objects.js';
import { isLoopbackHostname, parseBrowserOrigin } from '../lib/beeperOAuthOrigin.js';
import { getSettings } from './settings.js';
import { resolveBeeperToken } from './beeperCredentials.js';
export const DEFAULT_BASE_URL = 'http://127.0.0.1:23373';
const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
// Fork issue #61, decision 7. The original 1s cap (a live Beeper Desktop
// answers in single-digit-to-low-double-digit ms, and a closed loopback port
// refuses near-instantly) turned out to be too tight on a loaded machine: a
// Beeper Desktop that is genuinely up but briefly slow to answer the bare
// liveness probe timed out and reported the same "unreachable" card as a
// closed app, even seconds after it had handled a real request. 3s is still
// well short of `DEFAULT_REQUEST_TIMEOUT_MS` (this stays a liveness probe, not
// a request budget) but gives a momentarily busy app room to answer before the
// card treats it as gone. A timeout on ITS OWN is still ambiguous, though —
// nothing distinguishes "briefly slow" from "actually closed" from timing
// alone — which is what `RECENT_SUCCESS_WINDOW_MS` below is for.
export const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
// Paired with the cap above: a probe timeout is reported as `probeState:
// 'slow'` (reachable stays true) rather than `'unreachable'` ONLY when a real
// Beeper call — an authenticated API request through this client, or a
// realtime-socket ping (server/services/beeperSocket.js) — succeeded within
// this window. 60s comfortably survives one missed probe against the socket's
// own ~30s ping cadence while staying short enough that an app closed for real
// still reaches the unreachable card within a minute of going quiet — a probe
// timeout with no recent success (nothing else has talked to Beeper lately
// either) is exactly what "unreachable" means, promptly.
export const RECENT_SUCCESS_WINDOW_MS = 60_000;
// Last time ANY call through `beeperRequest` (a real API call, or a successful
// probe) completed. `null` until the first one — `hasRecentBeeperSuccess`
// reads that as "no recent success" rather than an epoch-zero false positive.
let lastSuccessAt = null;
function noteSuccess() {
lastSuccessAt = Date.now();
}
/** Whether a Beeper call has completed within `RECENT_SUCCESS_WINDOW_MS`. */
export function hasRecentBeeperSuccess(nowMs = Date.now()) {
return typeof lastSuccessAt === 'number' && (nowMs - lastSuccessAt) <= RECENT_SUCCESS_WINDOW_MS;
}
// Test-only: `beeperStatus.test.js` and `beeperClient.test.js` need to drive
// `hasRecentBeeperSuccess` without waiting on a real successful request first.
export function __setLastBeeperSuccessAtForTests(value) {
lastSuccessAt = value;
}
// Reads may retry once on a replayable connection failure (Beeper Desktop
// restarting mid-request); a fresh request-scoped budget on the replay, same
// shape as fetchWithTimeout's own retry contract.
const READ_RETRY = { retries: 1, retryDelayMs: 300, shouldRetry: isReplayableConnectionError };
/**
* Typed Beeper API error. `retryable` reflects the mapping in
* `mapBeeperResponseError`, clamped to `false` whenever the originating call
* ran with `allowRetry: false` (every write: send/edit/delete/react/archive/
* read-state) — callers building their own retry policy on top of this client
* should key on it rather than re-deriving from `status`.
*/
export class BeeperApiError extends ServerError {
constructor(message, { status = 500, code, retryable = false, details } = {}) {
super(message, { status, code, context: { retryable, ...(details !== undefined ? { details } : {}) } });
this.name = 'BeeperApiError';
this.retryable = retryable;
// ServerError's constructor does `this.status = options.status || 500`, which
// silently rewrites a deliberate `status: 0` ("no HTTP response at all", the
// network-error case below) into a fabricated 500. Restore the caller's actual
// value here so `err.status === 0` is a reliable way to spot a transport
// failure, not just `err.code === 'NETWORK_ERROR'`.
this.status = status;
}
}
// Logged at most once per distinct rejected value (not on every call — this
// runs on the hot path: every sweep tick, every status poll) so a
// misconfigured install narrates the fallback without spamming the log.
let lastRejectedBaseUrl;
/**
* Normalize a candidate Beeper Desktop base URL, re-applying the SAME
* loopback-only gate `beeperSettingsSchema` enforces on the PUT route
* (SEC-2, `server/lib/mediaValidation.js`) — not belt-and-suspenders.
* `getSettings()` reads `settings.json` off disk with NO schema
* re-validation on read, so a hand-edited file is a path that can still hand
* a non-loopback origin — with a live vault token attached to every request —
* to `beeperRequest`, even though the settings PUT route would have refused
* it. A rejected value falls back to the shipped loopback default rather than
* reaching a single request.
*/
function normalizeBaseUrl(value, { allowNonLoopback = false } = {}) {
const trimmed = String(value || '').trim().replace(/\/+$/, '');
if (!trimmed) return DEFAULT_BASE_URL;
const parsed = parseBrowserOrigin(trimmed);
if (parsed && (isLoopbackHostname(parsed.hostname) || allowNonLoopback)) {
return parsed.origin;
}
if (trimmed !== lastRejectedBaseUrl) {
lastRejectedBaseUrl = trimmed;
console.error(`❌ Beeper baseUrl "${trimmed}" is not a loopback origin and allowNonLoopbackBaseUrl is not set — falling back to ${DEFAULT_BASE_URL}`);
}
return DEFAULT_BASE_URL;
}
/**
* The configured Beeper Desktop base URL, trailing slash trimmed, falling back
* to the loopback default. Exported so the connect flow (#31) resolves it
* exactly the way every API call does instead of re-deriving it.
*/
export async function resolveBeeperBaseUrl() {
const settings = await getSettings().catch(() => null);
return normalizeBaseUrl(settings?.beeper?.baseUrl, {
allowNonLoopback: settings?.beeper?.allowNonLoopbackBaseUrl === true,
});
}
function normalizeToken(value) {
return typeof value === 'string' && value.trim() ? value.trim() : null;
}
/**
* Resolve `{ baseUrl, token }` for a call. An explicit `baseUrl` AND `token`
* (token may be `null`, meaning "deliberately unauthenticated") skip both
* stores entirely — this is what keeps most tests in this file free of any
* mock. Otherwise the base URL falls back to `settings.beeper.baseUrl` and then
* to the hardcoded default, while the token comes from the vault-backed store
* (`resolveBeeperToken`, #31), which itself falls back to the legacy plaintext
* `settings.beeper.token` for reads.
*
* An unreadable vault THROWS out of here rather than resolving `token: null`:
* "the credential cannot be read" and "no credential is configured" are
* different conditions, and collapsing them would report a connected install as
* unconfigured (the absent-vs-empty sentinel rule).
*
* SEC-2's loopback-only gate applies whenever `baseUrl` is resolved FROM
* settings below — the one path a hand-edited `settings.json` can reach. The
* "both explicit" bypass above trusts its caller instead of re-deriving the
* gate here: it exists for values ALREADY resolved through
* `resolveBeeperBaseUrl()` (the OAuth discovery baseUrl, and
* `beeperStatus.js`'s probes — both call `resolveBeeperBaseUrl()` rather than
* reading `settings.beeper.baseUrl` directly for exactly this reason) plus the
* many tests in this file, and gating it a second time would need the
* opt-in re-derived here anyway, defeating "skip both stores entirely." A
* caller with a genuinely unvalidated `baseUrl` must resolve it through
* `resolveBeeperBaseUrl()` first, never pass it straight into this bypass.
*/
export async function resolveBeeperConfig({ baseUrl, token } = {}) {
if (baseUrl !== undefined && token !== undefined) {
// `allowNonLoopback: true` — trust the caller entirely rather than
// re-deriving the settings-sourced opt-in (which would defeat "skip both
// stores"). `normalizeBaseUrl` still enforces the bare-origin SHAPE and
// still trims a trailing slash; only the loopback gate is waived here.
return { baseUrl: normalizeBaseUrl(baseUrl, { allowNonLoopback: true }), token: normalizeToken(token) };
}
const settings = await getSettings().catch(() => null);
const resolvedBaseUrl = baseUrl !== undefined ? baseUrl : settings?.beeper?.baseUrl;
const allowNonLoopback = settings?.beeper?.allowNonLoopbackBaseUrl === true;
if (token !== undefined) {
return { baseUrl: normalizeBaseUrl(resolvedBaseUrl, { allowNonLoopback }), token: normalizeToken(token) };
}
const stored = await resolveBeeperToken();
return { baseUrl: normalizeBaseUrl(resolvedBaseUrl, { allowNonLoopback }), token: normalizeToken(stored?.token) };
}
/**
* Map a non-ok Beeper response to a typed, retry-classified error.
*
* `retryEligible` (default `true`) clamps every status-table verdict to
* non-retryable when the call itself was never eligible to retry. A write
* call runs with `allowRetry: false` (the client-wide send-safe default) and
* must never hand back `retryable: true` on its thrown error — that field is
* the client's own documented "key on this, not on status" contract
* (`BeeperApiError` above), and a caller following it would otherwise
* duplicate a real send. `beeperRequest` passes its own `allowRetry` through
* unchanged as `retryEligible`; only the asset-502 branch below ignores it,
* since that mapping is `retryable: false` unconditionally regardless of
* retry eligibility.
*
* The one non-conventional case: `GET`/`HEAD /v1/assets/serve` answers `502`
* for a missing/expired asset, not `404` (live-verified on both methods). A
* generic "5xx is transient" retry policy loops forever on media the network
* has aged out, so an asset-endpoint `502` maps to a TERMINAL
* `ASSET_UNAVAILABLE` rather than the ordinarily-retryable `UPSTREAM_ERROR`.
* `POST /v1/assets/download` does NOT share this — it answers `200` with an
* `{ error }` body instead, so this `502` branch never fires for it; that
* shape is validated separately in `downloadAsset` below. Every other status
* follows the spec's documented meaning; `code` is never a published enum, so
* it rides along under `details` for logging only.
*/
export function mapBeeperResponseError(status, body, { isAssetEndpoint = false, retryEligible = true } = {}) {
const beeperCode = body?.code;
const message = typeof body?.message === 'string' && body.message
? body.message
: `Beeper API error: ${status}`;
const details = beeperCode !== undefined ? { beeperCode } : undefined;
if (status === 502 && isAssetEndpoint) {
return new BeeperApiError(message, { status, code: 'ASSET_UNAVAILABLE', retryable: false, details });
}
const STATUS_TABLE = {
400: { code: 'BAD_REQUEST', retryable: false },
401: { code: 'UNAUTHORIZED', retryable: false },
403: { code: 'FORBIDDEN', retryable: false },
404: { code: 'NOT_FOUND', retryable: false },
409: { code: 'CONFLICT', retryable: false },
422: { code: 'VALIDATION_ERROR', retryable: false },
429: { code: 'RATE_LIMITED', retryable: true },
500: { code: 'INTERNAL_ERROR', retryable: true },
502: { code: 'UPSTREAM_ERROR', retryable: true },
};
const mapped = STATUS_TABLE[status] || { code: 'UNKNOWN_ERROR', retryable: status >= 500 };
return new BeeperApiError(message, { status, code: mapped.code, retryable: retryEligible && mapped.retryable, details });
}
/**
* Low-level authenticated request. Every call goes through `fetchWithTimeout`
* (requirement: "fetchWithTimeout on every call"). `allowRetry` is OFF by
* default — the send-safe default, since Beeper has no idempotency key on
* send and a retried POST duplicates a real message. Read call sites opt in
* explicitly with `allowRetry: true`.
*/
async function beeperRequest(path, {
method = 'GET',
body,
headers,
timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
baseUrl,
token,
requireAuth = true,
allowRetry = false,
isAssetEndpoint = false,
} = {}) {
const resolved = await resolveBeeperConfig({ baseUrl, token });
if (requireAuth && !resolved.token) {
throw new BeeperApiError('Beeper access token is not configured', {
status: 401, code: 'NOT_CONFIGURED', retryable: false,
});
}
const reqHeaders = { 'Content-Type': 'application/json', ...headers };
if (resolved.token) reqHeaders.Authorization = `Bearer ${resolved.token}`;
// `timeoutMs` covers headers AND body consumption inside `fetchWithTimeout`
// (#7236), so there is no second body deadline to keep here. What that helper
// deliberately does NOT bound is a whole retry SEQUENCE — each replay gets a
// fresh budget — so a read that may replay carries a caller-owned signal as
// the TOTAL deadline, which is exactly the hook `waitForRetry` honors. A
// Beeper that keeps dropping connections therefore cannot stretch one logical
// request across unbounded backoffs.
const totalDeadline = allowRetry && Number.isFinite(timeoutMs) && timeoutMs > 0 ? new AbortController() : null;
const totalDeadlineId = totalDeadline ? setTimeout(() => totalDeadline.abort(), timeoutMs) : null;
let response;
let data;
try {
response = await fetchWithTimeout(`${resolved.baseUrl}${path}`, {
method,
headers: reqHeaders,
redirect: 'error',
body: body === undefined ? undefined : JSON.stringify(body),
...(totalDeadline ? { signal: totalDeadline.signal } : {}),
}, timeoutMs, allowRetry ? READ_RETRY : {});
if (response.status === 204) {
noteSuccess();
return null;
}
data = await readResponseJson(response, { fallback: (text) => ({ message: text }) });
} catch (err) {
const description = describeFetchError(err);
// AbortController firing (during headers OR body consumption) is the one
// network failure that means "no answer arrived in time" rather than
// "nothing is listening" — the distinction `probeBeeperInfo` needs to
// tell `slow` from `unreachable` (fork issue #61, decision 7).
const timedOut = /\babort/i.test(description);
throw new BeeperApiError(`Beeper request failed: ${description}`, {
status: 0, code: 'NETWORK_ERROR', retryable: allowRetry && isReplayableConnectionError(err),
details: timedOut ? { timedOut: true } : undefined,
});
} finally {
if (totalDeadlineId !== null) clearTimeout(totalDeadlineId);
}
if (!response.ok) throw mapBeeperResponseError(response.status, data, { isAssetEndpoint, retryEligible: allowRetry });
noteSuccess();
return data;
}
// ---------------------------------------------------------------------------
// Discovery / liveness
// ---------------------------------------------------------------------------
/**
* `GET /v1/info` — the one endpoint that also answers UNAUTHENTICATED, which is
* what makes it the liveness probe and what disqualifies it as a credential
* check: it answers 200 for a bogus token just as happily (#31's connect flow
* introspects instead). `token: null` is explicit, so a probe never triggers a
* credential read.
*/
export async function getInfo({ baseUrl, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS } = {}) {
return beeperRequest('/v1/info', { baseUrl, token: null, requireAuth: false, timeoutMs });
}
/**
* Structural check on `/v1/info`'s response body (#30 — a wave-one reviewer
* requirement on the status probe). `app.name` and `server.status` are the
* two fields every documented shape carries (see the API-surface research
* note). A 200 with an unexpected body — some other local HTTP service
* answering on a misconfigured `settings.beeper.baseUrl` (#30 makes that
* user-editable), or a Beeper Desktop version mid-upgrade — must not be
* reported as a healthy probe just because the transport succeeded. Exported
* so a caller that wants the raw typed error (rather than `probeBeeperInfo`'s
* swallowed boolean) can throw it directly.
*/
export function assertValidInfoResponse(info) {
const valid = isPlainObject(info)
&& typeof info?.app?.name === 'string' && info.app.name.length > 0
&& typeof info?.server?.status === 'string' && info.server.status.length > 0;
if (!valid) {
throw new BeeperApiError('Beeper API returned an unexpected /v1/info response shape (expected { app: { name }, server: { status } })', {
status: 502, code: 'MALFORMED_RESPONSE', retryable: false,
});
}
}
/**
* Liveness probe with a `DEFAULT_PROBE_TIMEOUT_MS` cap (#11, revised at fork
* issue #61 decision 7) — generous headroom over a live Beeper Desktop's
* actual response time, without being a real request budget. Never throws —
* an unreachable/misconfigured install is a normal outcome for a feature the
* user hasn't set up yet, not an exceptional one. A shape-invalid 200 (see
* `assertValidInfoResponse`) reports `reachable: false` exactly like a
* transport failure — a body that isn't Beeper's `/v1/info` never counts as
* "reachable" just because *something* answered.
*
* `timedOut` and `latencyMs` are additive fields for `beeperStatus.js` to
* derive `probeState: 'ok' | 'slow' | 'unreachable'` from — see
* `hasRecentBeeperSuccess` above. Every existing caller that reads only
* `reachable`/`info`/`error` is unaffected.
*/
export async function probeBeeperInfo({ baseUrl, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS } = {}) {
const startedAt = Date.now();
try {
const info = await getInfo({ baseUrl, timeoutMs });
assertValidInfoResponse(info);
return {
reachable: true, info, error: null, timedOut: false, latencyMs: Date.now() - startedAt,
};
} catch (err) {
const timedOut = err instanceof BeeperApiError && err.context?.details?.timedOut === true;
return {
reachable: false,
info: null,
error: err instanceof BeeperApiError ? err.message : describeFetchError(err),
timedOut,
latencyMs: Date.now() - startedAt,
};
}
}
// ---------------------------------------------------------------------------
// Cursor pagination
// ---------------------------------------------------------------------------
/**
* Walk a cursor-paginated Beeper endpoint as an async iterator, so callers
* never hand-roll the cursor loop. `fetchPage({ cursor, direction })` must
* return the standard envelope `{ items, hasMore, oldestCursor, newestCursor }`.
*
* `direction: 'before'` (default) walks `oldestCursor` — the only direction
* the endpoints this client wraps document as safe to auto-paginate (the SDK's
* own auto-pagination only ever walks backwards too). `hasMore: true` with no
* cursor to continue on is treated as exhausted rather than looping forever —
* a defensive stop, since the spec never documents that combination. Same
* defense if a server answers `hasMore: true` with the SAME cursor it was
* just called with (a value that would otherwise walk in place forever).
*
* A page whose `items` isn't an array (a malformed/unexpected response body —
* see `getAccounts`/`getBridges` below for the same rule) throws a typed
* `MALFORMED_RESPONSE` `BeeperApiError` rather than silently coercing to `[]`
* and reporting "no items" — the AGENTS.md "sentinel + validate" rule: absent,
* failed, and invalid must never collapse into the same value as
* legitimately-empty.
*/
export async function* paginateBeeperCursor(fetchPage, { direction = 'before' } = {}) {
let cursor;
for (;;) {
const page = await fetchPage({ cursor, direction });
if (!Array.isArray(page?.items)) {
throw new BeeperApiError('Beeper API returned an unexpected paginated response shape (expected { items: [] })', {
status: 502, code: 'MALFORMED_RESPONSE', retryable: false,
});
}
for (const item of page.items) yield item;
if (!page?.hasMore) return;
const nextCursor = direction === 'after' ? page?.newestCursor : page?.oldestCursor;
if (!nextCursor || nextCursor === cursor) return;
cursor = nextCursor;
}
}
function cursorQuery({ cursor, direction }) {
const qs = new URLSearchParams();
if (cursor) qs.set('cursor', cursor);
if (direction) qs.set('direction', direction);
const query = qs.toString();
return query ? `?${query}` : '';
}
function clampLimit(value, { min = 1, max, fallback }) {
const n = Number(value);
if (!Number.isFinite(n)) return fallback;
return Math.min(max, Math.max(min, Math.trunc(n)));
}
/**
* Append arbitrary search/filter params onto a `URLSearchParams`. An array
* value (`accountIDs`, `chatIDs`, `mediaTypes` — all declared as array query
* params in `/v1/spec`) is serialized as REPEATED keys (`?chatIDs=a&chatIDs=b`),
* not `qs.set(key, String(array))`, which would comma-join it into one value
* (`chatIDs=a%2Cb`) that the server reads as a single id matching nothing.
*/
function appendSearchParams(qs, params) {
for (const [key, value] of Object.entries(params)) {
if (value === undefined || value === null || value === '') continue;
if (Array.isArray(value)) {
for (const item of value) {
if (item === undefined || item === null || item === '') continue;
qs.append(key, String(item));
}
continue;
}
qs.set(key, String(value));
}
}
// ---------------------------------------------------------------------------
// Chats
// ---------------------------------------------------------------------------
/**
* `GET /v1/chats` — no `limit` param (server-chosen page size). One page.
*
* `accountIDs` is the endpoint's only filter and is declared as an ARRAY query
* param, so it goes through `appendSearchParams` (repeated keys) rather than
* `qs.set`, which would comma-join two ids into one value matching no account.
* The ingestion sweep (#32) pages one account at a time so a chat row is
* always attributable to the account whose cursor bounds it — without the
* filter it would have to page the whole cross-account list once per account.
* An omitted/empty `accountIDs` sends no filter at all (every account), never
* an empty `accountIDs=` that the server would read as "match nothing".
*/
export async function listChatsPage({ cursor, direction = 'before', accountIDs, baseUrl, token, timeoutMs } = {}) {
const qs = new URLSearchParams();
appendSearchParams(qs, { accountIDs });
if (cursor) qs.set('cursor', cursor);
if (direction) qs.set('direction', direction);
const query = qs.toString();
return beeperRequest(`/v1/chats${query ? `?${query}` : ''}`, { baseUrl, token, timeoutMs, allowRetry: true });
}
/** Async iterator over every chat, walking cursors automatically. */
export function listChats({ direction = 'before', accountIDs, baseUrl, token, timeoutMs } = {}) {
return paginateBeeperCursor(
({ cursor, direction: dir }) => listChatsPage({
cursor, direction: dir, accountIDs, baseUrl, token, timeoutMs,
}),
{ direction },
);
}
export async function getChat(chatId, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}`, { baseUrl, token, timeoutMs, allowRetry: true });
}
/** Create a direct chat without sending a first message or retrying a write. */
export async function createChat(accountID, participantID, options = {}) {
return beeperRequest('/v1/chats', {
...options, method: 'POST',
body: { accountID, participantIDs: [participantID], type: 'single' },
});
}
/** `GET /v1/chats/search` — has `limit` (default 50, max 200). One page. */
export async function searchChatsPage({ limit, cursor, direction = 'before', baseUrl, token, timeoutMs, ...params } = {}) {
const qs = new URLSearchParams();
appendSearchParams(qs, params);
const clamped = clampLimit(limit, { min: 1, max: 200, fallback: undefined });
if (clamped !== undefined) qs.set('limit', String(clamped));
if (cursor) qs.set('cursor', cursor);
if (direction) qs.set('direction', direction);
const query = qs.toString();
return beeperRequest(`/v1/chats/search${query ? `?${query}` : ''}`, { baseUrl, token, timeoutMs, allowRetry: true });
}
// ---------------------------------------------------------------------------
// Messages
// ---------------------------------------------------------------------------
/** `GET /v1/chats/{chatID}/messages` — no `limit` param. One page. */
export async function listMessagesPage(chatId, { cursor, direction = 'before', baseUrl, token, timeoutMs } = {}) {
return beeperRequest(
`/v1/chats/${encodeURIComponent(chatId)}/messages${cursorQuery({ cursor, direction })}`,
{ baseUrl, token, timeoutMs, allowRetry: true },
);
}
/** Async iterator over every message in a chat, walking cursors automatically. */
export function listMessages(chatId, { direction = 'before', baseUrl, token, timeoutMs } = {}) {
return paginateBeeperCursor(
({ cursor, direction: dir }) => listMessagesPage(chatId, { cursor, direction: dir, baseUrl, token, timeoutMs }),
{ direction },
);
}
export async function getMessage(chatId, messageId, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(
`/v1/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}`,
{ baseUrl, token, timeoutMs, allowRetry: true },
);
}
/** `GET /v1/messages/search` — `limit` is hard-capped at 20 (default 20). One page. */
export async function searchMessagesPage({ limit, cursor, direction = 'before', baseUrl, token, timeoutMs, ...params } = {}) {
const qs = new URLSearchParams();
appendSearchParams(qs, params);
const clamped = clampLimit(limit, { min: 1, max: 20, fallback: 20 });
qs.set('limit', String(clamped));
if (cursor) qs.set('cursor', cursor);
if (direction) qs.set('direction', direction);
return beeperRequest(`/v1/messages/search?${qs.toString()}`, { baseUrl, token, timeoutMs, allowRetry: true });
}
/**
* Send a message. Retry is OFF (the client-wide default) — there is no
* idempotency key on send, so a retried POST sends a second real message.
*/
export async function sendMessage(chatId, { text, replyToMessageID, attachment } = {}, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}/messages`, {
method: 'POST',
body: { text, replyToMessageID, attachment },
baseUrl, token, timeoutMs,
});
}
/** Edit a message. No retry — same send-safety posture as `sendMessage`. */
export async function editMessage(chatId, messageId, text, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}`, {
method: 'PUT',
body: { text },
baseUrl, token, timeoutMs,
});
}
/**
* Delete (unsend) a message. `forEveryone` is REQUIRED and must be an
* explicit boolean — the API defaults it to `true` when omitted, unsending
* for every participant on networks that support it. No retry.
*/
export async function deleteMessage(chatId, messageId, forEveryone, { baseUrl, token, timeoutMs } = {}) {
if (typeof forEveryone !== 'boolean') {
throw new BeeperApiError(
'deleteMessage requires an explicit boolean forEveryone — Beeper defaults an omitted value to true (unsend for everyone)',
{ status: 400, code: 'FOR_EVERYONE_REQUIRED', retryable: false },
);
}
return beeperRequest(
`/v1/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}?forEveryone=${forEveryone}`,
{ method: 'DELETE', baseUrl, token, timeoutMs },
);
}
export async function addReaction(chatId, messageId, reactionKey, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}/reactions`, {
method: 'POST',
body: { reactionKey },
baseUrl, token, timeoutMs,
});
}
export async function removeReaction(chatId, messageId, reactionKey, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(
`/v1/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}/reactions/${encodeURIComponent(reactionKey)}`,
{ method: 'DELETE', baseUrl, token, timeoutMs },
);
}
// ---------------------------------------------------------------------------
// Chat state (archive / read)
// ---------------------------------------------------------------------------
/** `PATCH /v1/chats/{chatID}` with `{isArchived}` — returns the updated Chat. */
export async function archiveChat(chatId, archived = true, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}`, {
method: 'PATCH',
body: { isArchived: archived },
baseUrl, token, timeoutMs,
});
}
/**
* `PATCH /v1/chats/{chatID}` — the chat-state update endpoint, and the write
* path behind the two rail controls #9 wired (Archive, Low priority). The body
* is an explicit allowlist rather than a passthrough: `PATCH` also carries the
* draft field, and a spread of caller-supplied keys would let a route body
* clear a draft (or set one) as a side effect of archiving a chat.
*
* `archiveChat` above stays as the narrow archive-only spelling; this is the
* general form and returns the updated `Chat` either way. Retries are OFF
* (`beeperRequest`'s default) — a Beeper write has no idempotency key.
*/
export async function updateChat(chatId, patch = {}, { baseUrl, token, timeoutMs } = {}) {
const body = {};
if (typeof patch.isArchived === 'boolean') body.isArchived = patch.isArchived;
if (typeof patch.isLowPriority === 'boolean') body.isLowPriority = patch.isLowPriority;
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}`, {
method: 'PATCH',
body,
baseUrl, token, timeoutMs,
});
}
export async function markRead(chatId, { messageID } = {}, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}/read`, {
method: 'POST',
body: messageID ? { messageID } : {},
baseUrl, token, timeoutMs,
});
}
export async function markUnread(chatId, { messageID } = {}, { baseUrl, token, timeoutMs } = {}) {
return beeperRequest(`/v1/chats/${encodeURIComponent(chatId)}/unread`, {
method: 'POST',
body: messageID ? { messageID } : {},
baseUrl, token, timeoutMs,
});
}
// ---------------------------------------------------------------------------
// Assets
// ---------------------------------------------------------------------------
/**
* `POST /v1/assets/download` — resolves an `mxc://`/`localmxc://` reference to
* a local file URL, returned as `{ srcURL }`. A missing/expired asset answers
* HTTP `200` here — NOT `502` — with `{ error: '<message>' }` and no `srcURL`
* (`AssetDownloadResponse` documents both fields as optional siblings on the
* one 200 shape; live-verified against an unresolvable `mxc://` reference).
* `beeperRequest` only maps non-2xx statuses, so a 200-with-`error` body would
* otherwise pass through as a "success" carrying no file to read. Validate the
* body here instead: an `error` string, or a response missing a non-empty
* `srcURL`, is the same terminal condition the 502 branch of
* `mapBeeperResponseError` exists for — `ASSET_UNAVAILABLE`, never retryable
* — so both failure shapes converge on the same caller-facing error. The
* `502`-on-`assets/serve` case (`GET`/`HEAD`, see below) is unrelated and
* still goes through `mapBeeperResponseError`'s status branch. Byte streaming
* (`GET /v1/assets/serve`, implemented below as `fetchAssetStream`/
* `headAsset`) and disk mirroring (`beeperAttachments.js`) are not
* implemented in `downloadAsset`.
*/
export async function downloadAsset(url, { baseUrl, token, timeoutMs } = {}) {
const data = await beeperRequest('/v1/assets/download', {
method: 'POST',
body: { url },
baseUrl, token, timeoutMs,
isAssetEndpoint: true,
});
const srcURL = typeof data?.srcURL === 'string' ? data.srcURL : '';
if (typeof data?.error === 'string' && data.error) {
throw new BeeperApiError(data.error, { status: 200, code: 'ASSET_UNAVAILABLE', retryable: false });
}
if (!srcURL) {
throw new BeeperApiError('Beeper /v1/assets/download returned no srcURL', {
status: 200, code: 'ASSET_UNAVAILABLE', retryable: false,
});
}
return data;
}
/**
* The byte-streaming half of the asset surface (#37): `GET /v1/assets/serve`.
*
* `beeperRequest` cannot serve these — it reads every response through
* `readResponseJson`, which is right for the small local JSON the rest of this
* client speaks to and catastrophic for a 30 MB video (it would buffer the
* whole body in memory to hand back a `{ message: '<binary>' }`). These two
* functions therefore go to `fetchWithTimeout` directly and hand the caller
* the RAW `Response`, whose body the mirror streams to disk.
*
* What they do NOT skip is the error mapping. `serve` answers `502` for media
* the network has aged out — unlike `POST /v1/assets/download`, which answers
* 200 with an { error } body — so both run through `mapBeeperResponseError`
* with `isAssetEndpoint: true` — a terminal `ASSET_UNAVAILABLE`, never the
* ordinarily-retryable `UPSTREAM_ERROR` a generic "5xx is transient" policy
* would loop on forever.
*/
// Time to the RESPONSE HEADERS, not to the last byte — which is why this is the
// one call site that opts out of `fetchWithTimeout`'s body deadline below.
// Generous rather than the 15s a JSON call gets, because Beeper may have to
// pull the media off the network before it can answer at all. The BODY is
// bounded separately by the mirror's own idle-abort (`STREAM_IDLE_TIMEOUT_MS`
// in `beeperAttachments.js`), which is what a caller passing `signal` here is
// usually doing — a whole-transfer ceiling here would instead kill a large
// attachment that is streaming along perfectly happily.
const ASSET_REQUEST_TIMEOUT_MS = 60_000;
function assetErrorFrom(response) {
// A `serve`/HEAD failure body is not reliably JSON (and a HEAD has no body
// at all), so the mapper is handed the status alone and builds its own
// message rather than inventing a `code` that never came from Beeper.
return mapBeeperResponseError(response.status, null, { isAssetEndpoint: true, retryEligible: false });
}
async function assetRequest(mxcId, { method, baseUrl, token, timeoutMs = ASSET_REQUEST_TIMEOUT_MS, signal } = {}) {
const resolved = await resolveBeeperConfig({ baseUrl, token });
if (!resolved.token) {
throw new BeeperApiError('Beeper access token is not configured', {
status: 401, code: 'NOT_CONFIGURED', retryable: false,
});
}
const reference = String(mxcId || '').trim();
if (!reference) {
throw new BeeperApiError('Beeper asset reference is empty', {
status: 400, code: 'BAD_REQUEST', retryable: false,
});
}
const url = `${resolved.baseUrl}/v1/assets/serve?url=${encodeURIComponent(reference)}`;
const response = await fetchWithTimeout(url, {
method,
headers: { Authorization: `Bearer ${resolved.token}` },
redirect: 'error',
signal,
}, timeoutMs, { bodyDeadline: false }).catch((err) => {
throw new BeeperApiError(`Beeper asset request failed: ${describeFetchError(err)}`, {
status: 0, code: 'NETWORK_ERROR', retryable: false,
});
});
if (!response.ok) {
// Drain, so an error body cannot hold the socket open.
await response.body?.cancel?.().catch(() => {});
throw assetErrorFrom(response);
}
return response;
}
/**
* `HEAD /v1/assets/serve` — the pre-flight the size ceiling and the eviction
* guard both key on. Returns `{ bytes }`, with `bytes: null` when the server
* declines to say (the absent-vs-empty rule: "unknown size" must not read as
* "zero bytes", which would sail under any ceiling).
*
* A `502` here is the eviction guard's whole point: it means Beeper can no
* longer supply the file, so the local copy is the last one and must be kept
* regardless of age.
*/
export async function headAsset(mxcId, { baseUrl, token, timeoutMs, signal } = {}) {
const response = await assetRequest(mxcId, { method: 'HEAD', baseUrl, token, timeoutMs, signal });
const raw = response.headers?.get?.('content-length');
const bytes = Number(raw);
return { bytes: raw !== null && raw !== undefined && Number.isFinite(bytes) ? bytes : null };
}
/**
* `GET /v1/assets/serve` — the raw streaming response. The caller owns the
* body: it must consume or cancel it.
*
* `serve` sends NO `Content-Type` (probed live, #13), which is why the mirror
* stores Beeper's declared `mimeType` from the message payload and serves from
* that instead of sniffing anything here. `timeoutMs` covers the headers only;
* pass `signal` to bound the body.
*/
export async function fetchAssetStream(mxcId, { baseUrl, token, timeoutMs, signal } = {}) {
return assetRequest(mxcId, { method: 'GET', baseUrl, token, timeoutMs, signal });
}
// ---------------------------------------------------------------------------
// Accounts / bridges
// ---------------------------------------------------------------------------
// Strips the top-level `loginID` field — it is the user's phone number
// (requirement: never log or persist it from either /v1/accounts or
// /v1/bridges) — and ONLY that field. This is a narrow, named boundary, not a
// PII allowlist: `GET /v1/spec`'s `Account.user` (a `User`) carries its own
// `phoneNumber`/`email`/`fullName`, and none of those are touched here — they
// deliberately survive into every caller of `getAccounts`/`getBridges`/
// `getJoinedAccounts`, because fork issue #10 (Tribe identity) needs
// `user.phoneNumber` from this same client. A caller that logs or persists a
// whole account/user row is still responsible for that PII itself.
function stripLoginId(account) {
if (!account || typeof account !== 'object') return account;
const { loginID, ...rest } = account;
return rest;
}
// Also strips `activeAccountCount` — documented to over-report (requirement:
// do not surface it) — alongside the nested loginID strip, so a bridge row
// never carries either field past this boundary.
function stripBridgeAccountsLoginId(bridge) {
if (!bridge || typeof bridge !== 'object') return bridge;
const { activeAccountCount, ...rest } = bridge;
return {
...rest,
accounts: Array.isArray(bridge.accounts) ? bridge.accounts.map(stripLoginId) : bridge.accounts,
};
}
/**
* `GET /v1/accounts` — a BARE array, not a paginated envelope.
*
* Throws a typed `MALFORMED_RESPONSE` `BeeperApiError` when the body isn't an
* array, instead of coercing to `[]` — the AGENTS.md "sentinel + validate"
* rule (`lmStudioManager.getLastListError` is the named precedent): a 200 with
* a non-JSON body becomes `{ message: text }` and a blank 200 becomes `{}` via
* `readResponseJson`'s fallback, and both used to be indistinguishable from a
* genuinely empty roster. With `settings.beeper.baseUrl` user-editable (#30),
* any other local service answering 200 must surface as a fault here, not as
* "no accounts connected".
*/
export async function getAccounts({ baseUrl, token, timeoutMs } = {}) {
const raw = await beeperRequest('/v1/accounts', { baseUrl, token, timeoutMs, allowRetry: true });
if (!Array.isArray(raw)) {
throw new BeeperApiError('Beeper API returned an unexpected /v1/accounts response shape (expected an array)', {
status: 502, code: 'MALFORMED_RESPONSE', retryable: false,
});
}
return raw.map(stripLoginId);
}
/**
* `GET /v1/bridges` — `{ items: Bridge[] }`. Deliberately does not surface
* `activeAccountCount` (documented to over-report; requirement: do not use it).
*
* Same "sentinel + validate" rule as `getAccounts` above: throws a typed
* `MALFORMED_RESPONSE` `BeeperApiError` when `items` isn't an array, instead
* of coercing a missing/invalid `items` to `[]`.
*/
export async function getBridges({ baseUrl, token, timeoutMs } = {}) {
const raw = await beeperRequest('/v1/bridges', { baseUrl, token, timeoutMs, allowRetry: true });
if (!Array.isArray(raw?.items)) {
throw new BeeperApiError('Beeper API returned an unexpected /v1/bridges response shape (expected { items: [] })', {
status: 502, code: 'MALFORMED_RESPONSE', retryable: false,
});
}
return { items: raw.items.map(stripBridgeAccountsLoginId) };
}
/**
* Join accounts to their bridge by `accountID` through each bridge's nested
* `accounts[]` — NOT by `network` (accounts carry a display name, bridges
* carry a lowercase slug; that join returns zero rows). An account with no
* matching bridge is kept, with bridge-derived fields `null`.
*
* `statusText` is taken from the bridge only — observed live (#11) to exist
* only on `connected` bridge rows and never populated on the account itself,
* even though the account schema allows the field.
*
* Pure — no I/O — so it's testable directly against a fixture without a
* network mock. `getJoinedAccounts` is the I/O wrapper below.
*/
export function joinAccountsWithBridges(accounts, bridgesResponse) {
const bridges = Array.isArray(bridgesResponse?.items) ? bridgesResponse.items : [];
const bridgeByAccountId = new Map();
for (const bridge of bridges) {
for (const acct of Array.isArray(bridge?.accounts) ? bridge.accounts : []) {
if (acct?.accountID) bridgeByAccountId.set(acct.accountID, bridge);
}
}
return (Array.isArray(accounts) ? accounts : []).map((account) => {
const safeAccount = stripLoginId(account);
const bridge = safeAccount?.accountID ? bridgeByAccountId.get(safeAccount.accountID) : null;
return {
...safeAccount,
network: safeAccount.network ?? bridge?.network ?? null,
bridgeId: bridge?.id ?? null,
bridgeStatus: bridge?.status ?? null,
statusText: bridge?.statusText ?? null,
};
});
}
/** `getAccounts()` joined to `getBridges()` by `accountID`. */
export async function getJoinedAccounts({ baseUrl, token, timeoutMs } = {}) {
const [accounts, bridges] = await Promise.all([
getAccounts({ baseUrl, token, timeoutMs }),
getBridges({ baseUrl, token, timeoutMs }),
]);
return joinAccountsWithBridges(accounts, bridges);
}