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
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { getSettings } from './settings.js';
import { resolveBeeperToken } from './beeperCredentials.js';
import {
BeeperApiError,
DEFAULT_BASE_URL,
resolveBeeperBaseUrl,
resolveBeeperConfig,
mapBeeperResponseError,
paginateBeeperCursor,
listChatsPage,
listChats,
listMessages,
searchChatsPage,
searchMessagesPage,
getInfo,
probeBeeperInfo,
assertValidInfoResponse,
getAccounts,
getBridges,
joinAccountsWithBridges,
getJoinedAccounts,
sendMessage,
editMessage,
deleteMessage,
downloadAsset,
fetchAssetStream,
updateChat,
} from './beeperClient.js';
// resolveBeeperConfig only touches settings.js (base URL) and the vault-backed
// credential store (token) when EITHER baseUrl or token is omitted; every other
// test in this file passes both explicitly and never exercises these mocks, so
// they're safe to hoist for the whole file. `beeperCredentials` is mocked
// rather than exercised because its own suite covers the vault contract and it
// would otherwise reach for Postgres from here.
vi.mock('./settings.js', () => ({ getSettings: vi.fn() }));
vi.mock('./beeperCredentials.js', () => ({ resolveBeeperToken: vi.fn() }));
// A fixture-shaped fake Response, matching what readResponseJson consumes
// (only `.text()` is read; `.ok`/`.status` drive the beeperRequest branch).
function jsonResponse(status, body) {
return { ok: status >= 200 && status < 300, status, text: async () => JSON.stringify(body) };
}
// A response whose body is NOT valid JSON — readResponseJson's fallback turns
// this into `{ message: text }`, which is the exact shape the malformed-
// response tests below must NOT let getAccounts/getBridges/paginateBeeperCursor
// coerce into an empty (but "successful") roster.
function nonJsonResponse(status, text) {
return { ok: status >= 200 && status < 300, status, text: async () => text };
}
describe('beeperClient', () => {
beforeEach(() => {
vi.restoreAllMocks();
vi.unstubAllGlobals();
});
// -------------------------------------------------------------------------
// Config resolution
// -------------------------------------------------------------------------
describe('resolveBeeperConfig', () => {
it('defaults the base URL and reports no token when neither is configured', async () => {
vi.mocked(getSettings).mockResolvedValue({});
vi.mocked(resolveBeeperToken).mockResolvedValue(null);
const config = await resolveBeeperConfig();
expect(config).toEqual({ baseUrl: DEFAULT_BASE_URL, token: null });
});
it('reads the base URL from settings and the token from the vault-backed store (#31)', async () => {
vi.mocked(getSettings).mockResolvedValue({ beeper: { baseUrl: 'http://127.0.0.1:23373/' } });
vi.mocked(resolveBeeperToken).mockResolvedValue({ token: 'vaulted-token', tokenSource: 'oauth' });
const config = await resolveBeeperConfig();
expect(config).toEqual({ baseUrl: 'http://127.0.0.1:23373', token: 'vaulted-token' });
});
// The vault read throwing means "the credential cannot be read", which is
// NOT "no credential is configured" — collapsing the two would silently
// make an authenticated call anonymous.
it('propagates an unreadable credential store instead of resolving token:null', async () => {
vi.mocked(getSettings).mockResolvedValue({});
vi.mocked(resolveBeeperToken).mockRejectedValue(new Error('Malformed vault ciphertext'));
await expect(resolveBeeperConfig()).rejects.toThrow(/vault ciphertext/);
});
it('an explicit baseUrl + token bypasses settings entirely', async () => {
const config = await resolveBeeperConfig({ baseUrl: 'http://127.0.0.1:9999/', token: 'abc123' });
expect(config).toEqual({ baseUrl: 'http://127.0.0.1:9999', token: 'abc123' });
});
it('an explicit token of null is honored as "deliberately unauthenticated", not "unset"', async () => {
vi.mocked(resolveBeeperToken).mockClear();
const config = await resolveBeeperConfig({ baseUrl: DEFAULT_BASE_URL, token: null });
expect(config.token).toBeNull();
expect(resolveBeeperToken).not.toHaveBeenCalled();
});
// The liveness probe must never trigger a credential read: /v1/info is the
// one endpoint that answers unauthenticated, and a probe that decrypts the
// vault on every status poll would be both slower and a wider blast radius.
it('an explicit token (with no baseUrl) still skips the credential store', async () => {
vi.mocked(resolveBeeperToken).mockClear();
vi.mocked(getSettings).mockResolvedValue({ beeper: { baseUrl: DEFAULT_BASE_URL } });
const config = await resolveBeeperConfig({ token: null });
expect(config).toEqual({ baseUrl: DEFAULT_BASE_URL, token: null });
expect(resolveBeeperToken).not.toHaveBeenCalled();
});
// SEC-2: `getSettings()` reads `settings.json` off disk with no schema
// re-validation on read, so `normalizeBaseUrl` re-applies the SAME
// loopback-only gate `beeperSettingsSchema` enforces on the PUT route —
// otherwise a hand-edited settings.json is a second path to the exact
// value the schema exists to block.
it('falls back to the loopback default for a non-loopback settings baseUrl with no opt-in', async () => {
vi.mocked(getSettings).mockResolvedValue({ beeper: { baseUrl: 'https://example.com:23373' } });
vi.mocked(resolveBeeperToken).mockResolvedValue({ token: 'vaulted-token', tokenSource: 'oauth' });
const config = await resolveBeeperConfig();
expect(config).toEqual({ baseUrl: DEFAULT_BASE_URL, token: 'vaulted-token' });
});
it('honors a non-loopback settings baseUrl once allowNonLoopbackBaseUrl is set', async () => {
vi.mocked(getSettings).mockResolvedValue({
beeper: { baseUrl: 'https://example.com:23373', allowNonLoopbackBaseUrl: true },
});
vi.mocked(resolveBeeperToken).mockResolvedValue({ token: 'vaulted-token', tokenSource: 'oauth' });
const config = await resolveBeeperConfig();
expect(config).toEqual({ baseUrl: 'https://example.com:23373', token: 'vaulted-token' });
});
// The "both explicit" bypass trusts its caller rather than re-deriving the
// opt-in here — it exists for values a caller ALREADY resolved through
// `resolveBeeperBaseUrl()` (which is where the gate lives), not for a raw
// unvalidated string. `beeperStatus.js` is the worked example: it calls
// `resolveBeeperBaseUrl()` first and passes the result in here, rather
// than reading `settings.beeper.baseUrl` straight into this bypass.
it('does not re-derive the opt-in for the "both explicit" bypass — it trusts an already-resolved baseUrl', async () => {
const config = await resolveBeeperConfig({ baseUrl: 'https://example.com:23373', token: 'abc123' });
expect(config).toEqual({ baseUrl: 'https://example.com:23373', token: 'abc123' });
});
});
describe('resolveBeeperBaseUrl', () => {
it('falls back to the loopback default for a non-loopback settings baseUrl with no opt-in', async () => {
vi.mocked(getSettings).mockResolvedValue({ beeper: { baseUrl: 'http://example.com:23373' } });
await expect(resolveBeeperBaseUrl()).resolves.toBe(DEFAULT_BASE_URL);
});
it('honors a non-loopback settings baseUrl once allowNonLoopbackBaseUrl is set', async () => {
vi.mocked(getSettings).mockResolvedValue({
beeper: { baseUrl: 'http://example.com:23373', allowNonLoopbackBaseUrl: true },
});
await expect(resolveBeeperBaseUrl()).resolves.toBe('http://example.com:23373');
});
});
// -------------------------------------------------------------------------
// 502-is-terminal mapping
// -------------------------------------------------------------------------
describe('mapBeeperResponseError', () => {
it('maps a 502 from an asset endpoint to the terminal ASSET_UNAVAILABLE', () => {
const err = mapBeeperResponseError(502, { message: 'Failed to download asset: Transfer failed for mxc://abc', code: 'BRIDGE_ERROR' }, { isAssetEndpoint: true });
expect(err).toBeInstanceOf(BeeperApiError);
expect(err.code).toBe('ASSET_UNAVAILABLE');
expect(err.retryable).toBe(false);
});
it('maps a 502 from a non-asset endpoint to the ordinarily-retryable UPSTREAM_ERROR', () => {
const err = mapBeeperResponseError(502, { message: 'bridge unavailable' }, { isAssetEndpoint: false });
expect(err.code).toBe('UPSTREAM_ERROR');
expect(err.retryable).toBe(true);
});
it('maps 401 to a non-retryable UNAUTHORIZED', () => {
const err = mapBeeperResponseError(401, { message: 'Unauthorized: Invalid or missing token', code: 'unauthorized' });
expect(err.code).toBe('UNAUTHORIZED');
expect(err.retryable).toBe(false);
});
// Live-verified: POST /v1/assets/download answers HTTP 200 for an
// unresolvable mxc:// reference, with an `{ error }` body and no `srcURL`
// — never a 502. beeperRequest treats any `response.ok` body as success,
// so downloadAsset itself must reject a 200 body shaped like a failure.
it('downloadAsset end-to-end surfaces ASSET_UNAVAILABLE on a live 200-with-error body', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
jsonResponse(200, { error: 'Failed to download asset: Transfer failed for mxc://gone' }),
));
await expect(downloadAsset('mxc://gone', { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'ASSET_UNAVAILABLE', retryable: false });
});
it('downloadAsset also rejects a 200 body with neither an error nor a srcURL', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse(200, {})));
await expect(downloadAsset('mxc://odd', { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'ASSET_UNAVAILABLE', retryable: false });
});
it('downloadAsset resolves with the body when srcURL is a non-empty string', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
jsonResponse(200, { srcURL: 'file:///tmp/example.png' }),
));
await expect(downloadAsset('mxc://ok', { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.resolves.toEqual({ srcURL: 'file:///tmp/example.png' });
});
// The mapper's asset-502 branch above still applies to GET/HEAD
// /v1/assets/serve — the byte-streaming half of the asset surface — which
// really does answer 502 for a missing/expired asset (live-verified).
// downloadAsset (POST /v1/assets/download) is the one caller that never
// reaches this branch, per the two tests above.
});
// -------------------------------------------------------------------------
// Cursor pagination / exhaustion
// -------------------------------------------------------------------------
describe('paginateBeeperCursor', () => {
it('walks every page until hasMore is false', async () => {
const pages = [
{ items: ['a', 'b'], hasMore: true, oldestCursor: 'c1', newestCursor: null },
{ items: ['c'], hasMore: true, oldestCursor: 'c2', newestCursor: null },
{ items: ['d'], hasMore: false, oldestCursor: null, newestCursor: null },
];
const fetchPage = vi.fn(async ({ cursor }) => {
if (!cursor) return pages[0];
if (cursor === 'c1') return pages[1];
if (cursor === 'c2') return pages[2];
throw new Error(`unexpected cursor ${cursor}`);
});
const collected = [];
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
expect(collected).toEqual(['a', 'b', 'c', 'd']);
expect(fetchPage).toHaveBeenCalledTimes(3);
});
it('stops (does not loop forever) when hasMore is true but the walked cursor is null', async () => {
const fetchPage = vi.fn(async () => ({ items: ['only'], hasMore: true, oldestCursor: null, newestCursor: null }));
const collected = [];
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
expect(collected).toEqual(['only']);
expect(fetchPage).toHaveBeenCalledTimes(1);
});
it('stops (does not loop forever) when a server echoes back the same cursor it was just called with', async () => {
// hasMore stays true and oldestCursor never advances past 'stuck' — a
// naive loop would walk in place forever.
const fetchPage = vi.fn(async () => ({ items: ['x'], hasMore: true, oldestCursor: 'stuck', newestCursor: null }));
const collected = [];
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
expect(collected).toEqual(['x', 'x']);
expect(fetchPage).toHaveBeenCalledTimes(2);
});
it('yields nothing and makes one call for a single empty page', async () => {
const fetchPage = vi.fn(async () => ({ items: [], hasMore: false }));
const collected = [];
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
expect(collected).toEqual([]);
expect(fetchPage).toHaveBeenCalledTimes(1);
});
it('throws MALFORMED_RESPONSE instead of silently treating a missing items array as exhausted', async () => {
const fetchPage = vi.fn(async () => ({ hasMore: false }));
const collected = [];
await expect((async () => {
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
})()).rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
expect(collected).toEqual([]);
});
it('throws MALFORMED_RESPONSE when a later page (not the first) has a non-array items', async () => {
const fetchPage = vi.fn(async ({ cursor }) => (!cursor
? { items: ['a'], hasMore: true, oldestCursor: 'c1' }
: { items: 'not-an-array', hasMore: true, oldestCursor: 'c2' }));
const collected = [];
await expect((async () => {
for await (const item of paginateBeeperCursor(fetchPage)) collected.push(item);
})()).rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
expect(collected).toEqual(['a']);
});
it('walks newestCursor when direction is "after"', async () => {
const fetchPage = vi.fn(async ({ cursor }) => (!cursor
? { items: [1], hasMore: true, oldestCursor: null, newestCursor: 'n1' }
: { items: [2], hasMore: false }));
const collected = [];
for await (const item of paginateBeeperCursor(fetchPage, { direction: 'after' })) collected.push(item);
expect(collected).toEqual([1, 2]);
expect(fetchPage).toHaveBeenNthCalledWith(2, { cursor: 'n1', direction: 'after' });
});
it('listChats/listMessages iterators drive listChatsPage/listMessagesPage across real HTTP pages', async () => {
const fetchMock = vi.fn()
.mockResolvedValueOnce(jsonResponse(200, { items: [{ id: 'chat1' }], hasMore: true, oldestCursor: 'cur1' }))
.mockResolvedValueOnce(jsonResponse(200, { items: [{ id: 'chat2' }], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
const chats = [];
for await (const chat of listChats({ baseUrl: DEFAULT_BASE_URL, token: 't' })) chats.push(chat);
expect(chats.map((c) => c.id)).toEqual(['chat1', 'chat2']);
expect(fetchMock).toHaveBeenCalledTimes(2);
expect(fetchMock.mock.calls[1][0]).toContain('cursor=cur1');
});
});
// -------------------------------------------------------------------------
// probeBeeperInfo body-shape check (#30 — a wave-one reviewer requirement:
// a 200 with an unexpected body must not be reported as a healthy probe)
// -------------------------------------------------------------------------
describe('probeBeeperInfo / assertValidInfoResponse', () => {
it('reports reachable:true for a well-shaped /v1/info body', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
jsonResponse(200, { app: { name: 'Beeper', version: '4.3.73' }, server: { status: 'running' } }),
));
const result = await probeBeeperInfo({ baseUrl: DEFAULT_BASE_URL });
expect(result).toEqual({
reachable: true, info: expect.objectContaining({ app: expect.any(Object) }), error: null, timedOut: false, latencyMs: expect.any(Number),
});
});
it('reports reachable:false — not true — for a 200 whose body is not the documented /v1/info shape', async () => {
// A misconfigured settings.beeper.baseUrl (#30 makes it user-editable)
// could point at some other local HTTP service that happens to answer
// 200 with an unrelated JSON body. The transport succeeded but this is
// not Beeper, so it must never read as a healthy probe.
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse(200, { ok: true })));
const result = await probeBeeperInfo({ baseUrl: DEFAULT_BASE_URL });
expect(result.reachable).toBe(false);
expect(result.info).toBeNull();
expect(result.error).toMatch(/unexpected \/v1\/info response shape/);
});
it('reports reachable:false for a 200 with a blank/non-JSON body', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(nonJsonResponse(200, '')));
const result = await probeBeeperInfo({ baseUrl: DEFAULT_BASE_URL });
expect(result.reachable).toBe(false);
expect(result.error).toMatch(/unexpected \/v1\/info response shape/);
});
it('assertValidInfoResponse throws a typed MALFORMED_RESPONSE BeeperApiError directly', () => {
expect(() => assertValidInfoResponse({ app: { name: '' }, server: { status: 'running' } }))
.toThrow(expect.objectContaining({ code: 'MALFORMED_RESPONSE', status: 502 }));
expect(() => assertValidInfoResponse(null)).toThrow(BeeperApiError);
expect(() => assertValidInfoResponse({ app: { name: 'Beeper' }, server: { status: 'running' } })).not.toThrow();
});
// Fork issue #61, decision 7: `timedOut` is what `beeperStatus.js` reads to
// tell "briefly slow" from "genuinely closed" — a fast refusal (nothing
// listening) must never be mistaken for a timeout, or a closed Beeper
// Desktop could ride a stale recent-success window into a false "slow".
it('reports timedOut:false for a fast connection refusal, distinct from an abort', async () => {
vi.stubGlobal('fetch', vi.fn().mockRejectedValue(Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNREFUSED' } })));
const result = await probeBeeperInfo({ baseUrl: DEFAULT_BASE_URL });
expect(result.reachable).toBe(false);
expect(result.timedOut).toBe(false);
});
});
// -------------------------------------------------------------------------
// Timeout behaviour with injected time (no real sleeps)
// -------------------------------------------------------------------------
describe('timeout behavior (fake timers)', () => {
function bodyThatRejectsOnAbort(status, signal) {
return {
ok: status >= 200 && status < 300,
status,
text: () => new Promise((_resolve, reject) => {
signal.addEventListener('abort', () => {
reject(new DOMException('aborted while reading body', 'AbortError'));
}, { once: true });
}),
};
}
function tricklingJsonResponse(status, signal) {
let chunksSent = 0;
const stream = new ReadableStream({
start(controller) {
const trickleId = setInterval(() => {
chunksSent++;
controller.enqueue(new TextEncoder().encode(' '));
}, 5);
signal.addEventListener('abort', () => {
clearInterval(trickleId);
controller.error(signal.reason || new DOMException('aborted', 'AbortError'));
}, { once: true });
},
});
return { response: new Response(stream, { status }), chunksSent: () => chunksSent };
}
// Fork issue #61, decision 7: 1s proved too tight for a briefly-busy Beeper
// Desktop, so the cap moved to 3s.
it('probeBeeperInfo caps at 3s and resolves reachable:false/timedOut:true without throwing, and without a real sleep', async () => {
vi.useFakeTimers();
try {
vi.stubGlobal('fetch', vi.fn().mockImplementation((_url, opts) =>
new Promise((_resolve, reject) => {
opts.signal.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')));
})));
const probePromise = probeBeeperInfo({ baseUrl: DEFAULT_BASE_URL });
// Advance virtual time only — a real 3s sleep here would fail CI timing
// budgets and defeats the point of injected time.
await vi.advanceTimersByTimeAsync(3000);
const result = await probePromise;
expect(result.reachable).toBe(false);
expect(result.error).toBeTruthy();
// The abort IS the timeout — this is the signal `beeperStatus.js` reads
// to decide `slow` vs `unreachable` (fork issue #61, decision 7), so a
// regression here is silent everywhere downstream.
expect(result.timedOut).toBe(true);
} finally {
vi.useRealTimers();
}
});
it('a read call (allowRetry) retries a replayable connection error using injected delay, not a real sleep', async () => {
vi.useFakeTimers();
try {
const fetchMock = vi.fn()
.mockRejectedValueOnce(Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNRESET' } }))
.mockResolvedValueOnce(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
const promise = listChatsPage({ baseUrl: DEFAULT_BASE_URL, token: 't' });
// Let the first attempt's rejection settle, then advance past the
// retry delay entirely in virtual time.
await vi.advanceTimersByTimeAsync(400);
const result = await promise;
expect(result).toEqual({ items: [], hasMore: false });
expect(fetchMock).toHaveBeenCalledTimes(2);
} finally {
vi.useRealTimers();
}
});
it('a total deadline cancels retry backoff before another read attempt starts', async () => {
vi.useFakeTimers();
try {
const fetchMock = vi.fn().mockRejectedValue(
Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNRESET' } }),
);
vi.stubGlobal('fetch', fetchMock);
const request = listChatsPage({
baseUrl: DEFAULT_BASE_URL, token: 't', timeoutMs: 25,
});
const rejection = expect(request).rejects.toMatchObject({
code: 'NETWORK_ERROR',
context: { details: { timedOut: true } },
});
await vi.advanceTimersByTimeAsync(25);
await rejection;
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
}
});
it.each([200, 500])('bounds a stalled JSON body after immediate HTTP %s headers', async (status) => {
vi.useFakeTimers();
try {
let requestSignal;
const fetchMock = vi.fn().mockImplementation((_url, opts) => {
requestSignal = opts.signal;
return Promise.resolve(bodyThatRejectsOnAbort(status, requestSignal));
});
vi.stubGlobal('fetch', fetchMock);
const request = getInfo({ baseUrl: DEFAULT_BASE_URL, timeoutMs: 25 });
const rejection = expect(request).rejects.toMatchObject({
code: 'NETWORK_ERROR',
context: { details: { timedOut: true } },
});
await vi.advanceTimersByTimeAsync(25);
await rejection;
expect(requestSignal.aborted).toBe(true);
expect(fetchMock).toHaveBeenCalledTimes(1);
} finally {
vi.useRealTimers();
}
});
it('keeps one total deadline when a JSON body keeps trickling data', async () => {
vi.useFakeTimers();
try {
let requestSignal;
let chunksSent;
vi.stubGlobal('fetch', vi.fn().mockImplementation((_url, opts) => {
requestSignal = opts.signal;
const trickle = tricklingJsonResponse(200, requestSignal);
chunksSent = trickle.chunksSent;
return Promise.resolve(trickle.response);
}));
const request = getInfo({ baseUrl: DEFAULT_BASE_URL, timeoutMs: 30 });
const rejection = expect(request).rejects.toMatchObject({
code: 'NETWORK_ERROR',
context: { details: { timedOut: true } },
});
await vi.advanceTimersByTimeAsync(30);
await rejection;
expect(chunksSent()).toBeGreaterThan(1);
expect(requestSignal.aborted).toBe(true);
} finally {
vi.useRealTimers();
}
});
it('clears the total deadline after a successful JSON read', async () => {
vi.useFakeTimers();
try {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse(200, {
app: { name: 'Beeper' }, server: { status: 'running' },
})));
await expect(getInfo({ baseUrl: DEFAULT_BASE_URL, timeoutMs: 50 })).resolves.toMatchObject({
app: { name: 'Beeper' },
});
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
}
});
it('aborts a stalled send body after one POST without retrying it', async () => {
vi.useFakeTimers();
try {
let requestSignal;
const fetchMock = vi.fn().mockImplementation((_url, opts) => {
requestSignal = opts.signal;
return Promise.resolve(bodyThatRejectsOnAbort(200, requestSignal));
});
vi.stubGlobal('fetch', fetchMock);
const request = sendMessage('chat1', { text: 'hi' }, {
baseUrl: DEFAULT_BASE_URL, token: 't', timeoutMs: 25,
});
const rejection = expect(request).rejects.toMatchObject({ code: 'NETWORK_ERROR', retryable: false });
await vi.advanceTimersByTimeAsync(25);
await rejection;
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][1].method).toBe('POST');
} finally {
vi.useRealTimers();
}
});
it('getInfo does not retry (unauthenticated probe, no allowRetry) — a connection error surfaces immediately', async () => {
const fetchMock = vi.fn().mockRejectedValue(Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNREFUSED' } }));
vi.stubGlobal('fetch', fetchMock);
await expect(getInfo({ baseUrl: DEFAULT_BASE_URL })).rejects.toMatchObject({ code: 'NETWORK_ERROR' });
expect(fetchMock).toHaveBeenCalledTimes(1);
});
});
// -------------------------------------------------------------------------
// Send-safe retries
// -------------------------------------------------------------------------
describe('send-safe retries', () => {
it('refuses redirects for message bodies and attachment requests', async () => {
const fetchMock = vi.fn().mockRejectedValue(new TypeError('unexpected redirect'));
vi.stubGlobal('fetch', fetchMock);
await expect(sendMessage('chat1', { text: 'Example private message' }, { baseUrl: DEFAULT_BASE_URL, token: 'example-token' }))
.rejects.toMatchObject({ code: 'NETWORK_ERROR', retryable: false });
await expect(fetchAssetStream('mxc://example.com/asset', { baseUrl: DEFAULT_BASE_URL, token: 'example-token' }))
.rejects.toMatchObject({ code: 'NETWORK_ERROR', retryable: false });
expect(fetchMock).toHaveBeenCalledTimes(2);
for (const [, options] of fetchMock.mock.calls) expect(options.redirect).toBe('error');
});
it('sendMessage does NOT retry a replayable connection error — a retry would duplicate a real message', async () => {
const fetchMock = vi.fn().mockRejectedValue(Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNRESET' } }));
vi.stubGlobal('fetch', fetchMock);
await expect(sendMessage('chat1', { text: 'hi' }, { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'NETWORK_ERROR', retryable: false });
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('sendMessage rejects with retryable: false on a 429 too — a write\'s thrown error must never advertise retry-safety, regardless of status', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(429, { message: 'Too Many Requests' }));
vi.stubGlobal('fetch', fetchMock);
await expect(sendMessage('chat1', { text: 'hi' }, { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'RATE_LIMITED', retryable: false });
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('editMessage rejects with retryable: false on a 502 — same write send-safety posture as sendMessage', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(502, { message: 'Bad Gateway' }));
vi.stubGlobal('fetch', fetchMock);
await expect(editMessage('chat1', 'msg1', 'edited text', { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'UPSTREAM_ERROR', retryable: false });
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('updateChat does NOT retry a replayable connection error — it is a write, like every other chat-state PATCH', async () => {
const fetchMock = vi.fn().mockRejectedValue(Object.assign(new TypeError('fetch failed'), { cause: { code: 'ECONNRESET' } }));
vi.stubGlobal('fetch', fetchMock);
await expect(updateChat('chat1', { isArchived: true }, { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'NETWORK_ERROR', retryable: false });
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('updateChat sends ONLY the two allowlisted flags — a PATCH body spread could clear the chat draft as a side effect', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { id: 'chat1', isArchived: true }));
vi.stubGlobal('fetch', fetchMock);
await updateChat(
'chat1',
{ isArchived: true, isLowPriority: false, draft: { text: 'nope' }, isPinned: true },
{ baseUrl: DEFAULT_BASE_URL, token: 't' },
);
const [, init] = fetchMock.mock.calls[0];
expect(JSON.parse(init.body)).toEqual({ isArchived: true, isLowPriority: false });
});
it('a read call (allowRetry) still surfaces retryable: true on a 500 — the write clamp above must not leak into reads', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(500, { message: 'Internal Server Error' }));
vi.stubGlobal('fetch', fetchMock);
await expect(listChatsPage({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'INTERNAL_ERROR', retryable: true });
});
it('deleteMessage requires an explicit boolean forEveryone and never calls fetch without one', async () => {
const fetchMock = vi.fn();
vi.stubGlobal('fetch', fetchMock);
await expect(deleteMessage('chat1', 'msg1', undefined, { baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'FOR_EVERYONE_REQUIRED' });
expect(fetchMock).not.toHaveBeenCalled();
});
it('deleteMessage passes forEveryone=false explicitly in the query string', async () => {
const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 204, text: async () => '' });
vi.stubGlobal('fetch', fetchMock);
await deleteMessage('chat1', 'msg1', false, { baseUrl: DEFAULT_BASE_URL, token: 't' });
expect(fetchMock.mock.calls[0][0]).toContain('forEveryone=false');
});
});
// -------------------------------------------------------------------------
// Accounts / bridges join on a fixture where the `network` join is zero rows
// -------------------------------------------------------------------------
describe('joinAccountsWithBridges', () => {
// Deliberately fake identifiers per repo privacy rules — no real handles,
// phone numbers, hostnames, or message bodies. `user` is shaped like the
// live `Account.user` (a `User`, per `GET /v1/spec`) — carrying its own
// `phoneNumber`/`email`/`fullName` — so a test against this fixture would
// actually catch a leak of those fields, not just of the flat `id` the
// old `{ id: 'user-1' }` fixture had no way to catch.
const accounts = [
{
accountID: 'discordgo',
network: 'Discord', // display name
status: 'connected',
loginID: '+15550000001', // must never survive into the joined output
user: {
id: 'user-1',
username: 'example-user-1',
isSelf: true,
phoneNumber: '+15550000001', // deliberately SURVIVES — fork issue #10 needs it
email: '[email protected]', // deliberately SURVIVES
fullName: 'Alice Example', // deliberately SURVIVES
},
},
{
accountID: 'local-whatsapp_ba_example',
network: 'WhatsApp', // display name
status: 'connection_required',
loginID: '+15550000002',
user: {
id: 'user-2',
username: 'example-user-2',
isSelf: true,
phoneNumber: '+15550000002',
email: '[email protected]',
fullName: 'Bob Example',
},
},
{
accountID: 'orphan-account',
network: 'Mystery Network',
status: 'connected',
// no matching bridge below — must be tolerated, not dropped
},
];
const bridgesResponse = {
items: [
{
id: 'bridge-discord',
network: 'discord', // lowercase slug — differs from account.network 'Discord'
status: 'connected',
statusText: 'Connected',
supportsMultipleAccounts: false,
activeAccountCount: 3, // must never survive — documented to over-report
accounts: [{ accountID: 'discordgo', loginID: '+15550000001', user: { id: 'user-1', phoneNumber: '+15550000001' } }],
},
{
id: 'bridge-whatsapp',
network: 'whatsapp', // lowercase slug — differs from account.network 'WhatsApp'
status: 'connection_required',
statusText: null,
activeAccountCount: 1,
accounts: [{ accountID: 'local-whatsapp_ba_example', loginID: '+15550000002', user: { id: 'user-2', phoneNumber: '+15550000002' } }],
},
],
};
it('joins on accountID even though every account.network differs from its bridge.network (the network join is zero rows)', () => {
// Prove the trap: naive equality on network would match nothing.
const naiveMatches = accounts.filter((a) => bridgesResponse.items.some((b) => b.network === a.network));
expect(naiveMatches).toHaveLength(0);
const joined = joinAccountsWithBridges(accounts, bridgesResponse);
const discord = joined.find((a) => a.accountID === 'discordgo');
const whatsapp = joined.find((a) => a.accountID === 'local-whatsapp_ba_example');
expect(discord.bridgeId).toBe('bridge-discord');
expect(discord.statusText).toBe('Connected');
expect(whatsapp.bridgeId).toBe('bridge-whatsapp');
expect(whatsapp.statusText).toBeNull();
});
it('tolerates an account with no matching bridge', () => {
const joined = joinAccountsWithBridges(accounts, bridgesResponse);
const orphan = joined.find((a) => a.accountID === 'orphan-account');
expect(orphan).toMatchObject({ bridgeId: null, bridgeStatus: null, statusText: null });
});
it('never surfaces loginID in the joined output', () => {
const joined = joinAccountsWithBridges(accounts, bridgesResponse);
for (const account of joined) expect(account).not.toHaveProperty('loginID');
});
it('strips ONLY loginID — nested user.phoneNumber/email/fullName deliberately survive the join (fork issue #10 needs user.phoneNumber for Tribe identity)', () => {
const joined = joinAccountsWithBridges(accounts, bridgesResponse);
const discord = joined.find((a) => a.accountID === 'discordgo');
expect(discord).not.toHaveProperty('loginID');
expect(discord.user).toMatchObject({
phoneNumber: '+15550000001',
email: '[email protected]',
fullName: 'Alice Example',
});
});
it('getAccounts / getBridges strip loginID and activeAccountCount at the client boundary too, before any join — but deliberately leave nested user PII (phoneNumber/email/fullName) intact', async () => {
const fetchMock = vi.fn()
.mockResolvedValueOnce(jsonResponse(200, accounts))
.mockResolvedValueOnce(jsonResponse(200, bridgesResponse));
vi.stubGlobal('fetch', fetchMock);
const [gotAccounts, gotBridges] = await Promise.all([
getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' }),
getBridges({ baseUrl: DEFAULT_BASE_URL, token: 't' }),
]);
for (const account of gotAccounts) expect(account).not.toHaveProperty('loginID');
expect(gotAccounts.find((a) => a.accountID === 'discordgo').user).toMatchObject({ phoneNumber: '+15550000001' });
for (const bridge of gotBridges.items) {
expect(bridge).not.toHaveProperty('activeAccountCount');
for (const account of bridge.accounts) expect(account).not.toHaveProperty('loginID');
}
expect(gotBridges.items[0].accounts[0].user).toMatchObject({ phoneNumber: '+15550000001' });
});
it('getJoinedAccounts wires getAccounts + getBridges through the fetch layer end-to-end', async () => {
const fetchMock = vi.fn()
.mockResolvedValueOnce(jsonResponse(200, accounts))
.mockResolvedValueOnce(jsonResponse(200, bridgesResponse));
vi.stubGlobal('fetch', fetchMock);
const joined = await getJoinedAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' });
expect(joined.find((a) => a.accountID === 'discordgo').bridgeId).toBe('bridge-discord');
expect(fetchMock).toHaveBeenCalledTimes(2);
});
});
// -------------------------------------------------------------------------
// Malformed response shapes — must throw a typed MALFORMED_RESPONSE error,
// never silently coerce to an empty roster (AGENTS.md "sentinel + validate":
// absent/failed/invalid must never collapse into "legitimately empty").
// -------------------------------------------------------------------------
describe('getAccounts / getBridges malformed response', () => {
it('getAccounts throws MALFORMED_RESPONSE (not an empty roster) on a 200 with a non-JSON body', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(nonJsonResponse(200, 'not json at all')));
await expect(getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
});
it('getAccounts throws MALFORMED_RESPONSE on a 200 object body where an array is expected', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse(200, { accounts: [] })));
await expect(getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
});
it('getAccounts throws MALFORMED_RESPONSE on a blank 200 body (readResponseJson\'s emptyValue {})', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(nonJsonResponse(200, '')));
await expect(getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
});
it('getBridges throws MALFORMED_RESPONSE (not an empty roster) on a 200 with a non-JSON body', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(nonJsonResponse(200, 'not json at all')));
await expect(getBridges({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
});
it('getBridges throws MALFORMED_RESPONSE on a 200 body whose items is not an array', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse(200, { items: 'not-an-array' })));
await expect(getBridges({ baseUrl: DEFAULT_BASE_URL, token: 't' }))
.rejects.toMatchObject({ code: 'MALFORMED_RESPONSE', retryable: false });
});
it('a genuinely empty roster (200 with []/{ items: [] }) is NOT malformed — still resolves empty', async () => {
const fetchMock = vi.fn()
.mockResolvedValueOnce(jsonResponse(200, []))
.mockResolvedValueOnce(jsonResponse(200, { items: [] }));
vi.stubGlobal('fetch', fetchMock);
await expect(getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 't' })).resolves.toEqual([]);
await expect(getBridges({ baseUrl: DEFAULT_BASE_URL, token: 't' })).resolves.toEqual({ items: [] });
});
});
// -------------------------------------------------------------------------
// Search endpoint limit clamping (limit max 20 on /v1/messages/search)
// -------------------------------------------------------------------------
describe('searchMessagesPage limit clamping', () => {
it('clamps an over-cap limit to 20 rather than passing it through unbounded', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false, chats: {} }));
vi.stubGlobal('fetch', fetchMock);
await searchMessagesPage({ query: 'hello', limit: 500, baseUrl: DEFAULT_BASE_URL, token: 't' });
expect(fetchMock.mock.calls[0][0]).toContain('limit=20');
});
it('defaults limit to 20 when omitted', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await searchMessagesPage({ query: 'hello', baseUrl: DEFAULT_BASE_URL, token: 't' });
expect(fetchMock.mock.calls[0][0]).toContain('limit=20');
});
});
// -------------------------------------------------------------------------
// Array query params (accountIDs, chatIDs, mediaTypes) must serialize as
// repeated keys, not one comma-joined value the server reads as a single id.
// -------------------------------------------------------------------------
describe('array query param serialization', () => {
it('searchMessagesPage serializes an array filter (accountIDs) as repeated keys, not comma-joined', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await searchMessagesPage({ query: 'hello', accountIDs: ['acct-a', 'acct-b'], baseUrl: DEFAULT_BASE_URL, token: 't' });
const url = fetchMock.mock.calls[0][0];
const params = new URL(url).searchParams;
expect(params.getAll('accountIDs')).toEqual(['acct-a', 'acct-b']);
expect(url).not.toContain('acct-a%2Cacct-b');
});
it('searchChatsPage serializes an array filter (chatIDs) as repeated keys, not comma-joined', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await searchChatsPage({ chatIDs: ['chat-a', 'chat-b'], baseUrl: DEFAULT_BASE_URL, token: 't' });
const url = fetchMock.mock.calls[0][0];
const params = new URL(url).searchParams;
expect(params.getAll('chatIDs')).toEqual(['chat-a', 'chat-b']);
expect(url).not.toContain('chat-a%2Cchat-b');
});
// #32: the ingestion sweep pages ONE account at a time so every chat row is
// attributable to the account whose cursor bounds it. `GET /v1/chats` takes
// no `limit`, so `accountIDs` is its only filter and has to survive into the
// query string as repeated keys.
it('listChatsPage sends accountIDs as repeated keys alongside cursor and direction', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await listChatsPage({
accountIDs: ['acct-a', 'acct-b'], cursor: 'cur1', direction: 'after', baseUrl: DEFAULT_BASE_URL, token: 't',
});
const url = fetchMock.mock.calls[0][0];
const params = new URL(url).searchParams;
expect(params.getAll('accountIDs')).toEqual(['acct-a', 'acct-b']);
expect(params.get('cursor')).toBe('cur1');
expect(params.get('direction')).toBe('after');
expect(url).not.toContain('acct-a%2Cacct-b');
expect(url).not.toContain('limit=');
});
it('listChatsPage omits accountIDs entirely when unset — an empty filter must not read as "match nothing"', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await listChatsPage({ baseUrl: DEFAULT_BASE_URL, token: 't' });
const url = fetchMock.mock.calls[0][0];
expect(url).not.toContain('accountIDs');
expect(new URL(url).searchParams.get('direction')).toBe('before');
});
it('the listChats iterator carries accountIDs onto every page it walks', async () => {
const fetchMock = vi.fn()
.mockResolvedValueOnce(jsonResponse(200, { items: [{ id: 'chat1' }], hasMore: true, oldestCursor: 'cur1' }))
.mockResolvedValueOnce(jsonResponse(200, { items: [{ id: 'chat2' }], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
const chats = [];
for await (const chat of listChats({ accountIDs: ['acct-a'], baseUrl: DEFAULT_BASE_URL, token: 't' })) chats.push(chat);
expect(chats.map((c) => c.id)).toEqual(['chat1', 'chat2']);
for (const call of fetchMock.mock.calls) {
expect(new URL(call[0]).searchParams.getAll('accountIDs')).toEqual(['acct-a']);
}
});
it('a scalar filter still serializes as a single key (no regression from the array path)', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], hasMore: false }));
vi.stubGlobal('fetch', fetchMock);
await searchMessagesPage({ query: 'hello', chatType: 'group', baseUrl: DEFAULT_BASE_URL, token: 't' });
const params = new URL(fetchMock.mock.calls[0][0]).searchParams;
expect(params.getAll('chatType')).toEqual(['group']);
});
});
// -------------------------------------------------------------------------
// Auth requirement
// -------------------------------------------------------------------------
describe('auth requirement', () => {
it('an authenticated call with no token configured fails fast with NOT_CONFIGURED, without calling fetch', async () => {
const fetchMock = vi.fn();
vi.stubGlobal('fetch', fetchMock);
await expect(getAccounts({ baseUrl: DEFAULT_BASE_URL, token: null }))
.rejects.toMatchObject({ code: 'NOT_CONFIGURED' });
expect(fetchMock).not.toHaveBeenCalled();
});
it('getInfo requires no token (the one unauthenticated endpoint) and sends no Authorization header', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { app: { name: 'Beeper' } }));
vi.stubGlobal('fetch', fetchMock);
await getInfo({ baseUrl: DEFAULT_BASE_URL });
const [, opts] = fetchMock.mock.calls[0];
expect(opts.headers.Authorization).toBeUndefined();
});
it('an authenticated call sends the configured token as an Authorization: Bearer header', async () => {
const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, []));
vi.stubGlobal('fetch', fetchMock);
await getAccounts({ baseUrl: DEFAULT_BASE_URL, token: 'secret-token' });
const [, opts] = fetchMock.mock.calls[0];
expect(opts.headers.Authorization).toBe('Bearer secret-token');
});
});
});