@privateaim/messenger-http-kit
HTTP client for the Hub messenger's durable store-and-forward broker surface.
Unlike the other Hub HTTP kits this is not an entity API: the messenger exposes a protocol (send / pull / acknowledge), so nothing here carries the { data, meta } envelope and the pull query is plain limit / wait parameters rather than rapiq (an unset one is not sent).
Installation
npm install @privateaim/messenger-http-kitUsage
import { Client } from '@privateaim/messenger-http-kit';
const client = new Client({
baseURL: 'http://localhost:4003',
});
// Send one message; the hub persists a durable row per recipient.
const ids = await client.message.send({ /* … */ });
// Pull pending (un-acked) messages, oldest first.
const { messages } = await client.message.pull({ limit: 50, wait: 30 });
// Acknowledge by id — the hub deletes them for the caller (delete-on-ack).
await client.message.ack({ ids: messages.map((message) => message.id) });Cancellation & Per-Call Timeouts
send, pull and ack take one optional APIRequestOptions object ({ signal?, timeout? }) as their last parameter: signal aborts the call, timeout (milliseconds) overrides the client's for this call. A long-poll pull({ wait }) extends that deadline (else the client's timeout) by wait, so an empty mailbox is not a timeout. subscribe() takes the same object as its only argument.
Wakeup subscription
message.subscribe() reads the caller's GET /messages/stream (Server-Sent Events) and yields typed wakeups. A wakeup carries only the recipient, never a payload: on each one, pull() the mailbox. The hub sends one wakeup right after connecting, so a fresh subscription also catches up on anything already queued.
import { WakeupEventName } from '@privateaim/messenger-kit';
const controller = new AbortController();
for await (const event of client.message.subscribe({ signal: controller.signal })) {
if (event.type === WakeupEventName.MESSAGE_PENDING) {
const { messages } = await client.message.pull();
// … process, then ack
}
}
// elsewhere: controller.abort() closes the stream; the loop ends without an error- Events:
MessageStreamEventis a union discriminated bytype; today it has one member,messagePendingwithdata: MessagePendingEvent({ recipient }).lastEventIdandretrycarry the stream's lastid/retryfields (the hub sends neither today). - Skipped: keep-alive comments, event types the kit does not know and a
messagePendingwhose data is not a wakeup payload. - No deadline: the call passes
timeout: 0, so a client-leveltimeoutdoes not cut the open-ended stream. Bound it with thesignalinstead; atimeoutpassed tosubscribe()replaces the0and cuts the stream. - Abort: aborting the signal (or
breaking out of the loop) closes the connection; the iteration ends without throwing. A non-2xx answer rejects with the usual hapicClientError. - No reconnect: one response is read. When the loop ends without an abort, the server closed the stream: reconnect (with your own backoff), then pull once. The durable mailbox loses nothing across the gap, so no
Last-Event-IDreplay is needed.
Contract
Client implements IMessengerClient, and MessageAPI implements IMessageAPI:
import type { IMessengerClient } from '@privateaim/messenger-http-kit';
// Depend on the CONTRACT, not the class.
function relay(client: IMessengerClient) { /* … */ }| Sub-API | Contract |
|---|---|
message | IMessageAPI — send / pull / ack / subscribe |
MessageAPI extends hapic's BaseAPI.
Testing
@privateaim/messenger-http-kit/testing ships a FakeClient: a real Client wired to hapic's MemoryTransport. Only the transport is replaced, so header merging, body transformation, decoding, retries and the client's own RESPONSE_ERROR hook all still run.
import { createFakeClient, fakeResponse } from '@privateaim/messenger-http-kit/testing';
const client = createFakeClient({
handlers: {
'GET /messages': () => ({ messages: [{ id: 'm1' }] }),
'POST /messages/ack': () => undefined,
},
});
const { messages } = await client.message.pull({ limit: 5 });
// Every dispatched request is recorded, normalized.
expect(client.requests[0].url).toContain('limit=5');- Handler keys are
'<METHOD> /<path>'; a:namesegment captures intoreq.params. - The query string is ignored for matching and
'*'is a catch-all that always loses to a specific pattern. - A handler returns the response body; return
fakeResponse(status, body)for a non-2xx. - Keep the default path-free
baseURL— abaseURLcarrying a path shifts every pathname, and patterns silently stop matching. - A recorded request's
optionsholds thesignalandtimeoutit was sent with (client defaults included, sosubscribe()showstimeout: 0), each key only when set.
To test a consumer of subscribe(), serve a FakeEventStream: an open text/event-stream response you feed by hand.
import { FakeEventStream, createFakeClient } from '@privateaim/messenger-http-kit/testing';
const stream = new FakeEventStream();
const client = createFakeClient({
handlers: { 'GET /messages/stream': () => stream.response },
});
stream.write('event: messagePending\ndata: {"recipient":{"type":"client","id":"c1"}}\n\n');
stream.close(); // ends the subscription; omit it to keep the stream open
// stream.cancelled turns true once the consumer aborts or breaksA handler Response is tied to the request's signal as fetch does, so an abort or a hapic timeout errors the body and cancels the source. Serve one FakeEventStream per request: a body is read once.
API
Exports
| Module | Description |
|---|---|
Client | The messenger HTTP client |
IMessengerClient / ClientOptions | The client contract and its construction options |
MessageAPI / IMessageAPI | The message sub-API and its contract |
MessageStreamEvent / MessageSubscribeOptions | The typed wakeup yielded by subscribe() and its options |
APIRequestOptions | The per-call { signal?, timeout? } every API method takes last |
toMessageStreamEvent / isMessagePendingEvent | Turn a parsed SSE message into a typed wakeup (or undefined); guard a wakeup payload |
./testing (subpath) | FakeClient, createFakeClient, fakeResponse, matchRoute, FakeEventStream |
Dependencies
@privateaim/messenger-kit— Message domain typeshapic— HTTP client base