@portalsdk/wire-protocol 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,672 @@
+/**
+ * Protocol version carried by every upgrade as `?v=` (§1.1, §6).
+ *
+ * An unknown version is refused at the upgrade with HTTP 426 `unsupported_version`.
+ * Within v1 the protocol evolves additively only; a breaking change bumps this.
+ */
+declare const PROTOCOL_VERSION = 1;
+/**
+ * Upgrade query-parameter names (§1.1). Build upgrade URLs from these rather than
+ * string literals, so a rename is a compile error rather than a silent 4xx.
+ *
+ * - `version` — required on every upgrade; unknown → 426.
+ * - `token` — the signed JWT. Identifies the user; the apiKey is resolved from it.
+ * - `leaf` — opaque reconnect token; echo back what `ready` gave you, unchanged.
+ * - `meta` — initial presence metadata, base64 JSON (standard channels; ≤1KB decoded).
+ * - `last` — highest contiguous seq held, sent on reconnect to request replay (§1.4).
+ */
+declare const UPGRADE_PARAMS: {
+    readonly version: "v";
+    readonly token: "token";
+    readonly leaf: "leaf";
+    readonly meta: "meta";
+    readonly last: "last";
+};
+/**
+ * Response header carrying the refusal code on a refused upgrade (§1.1).
+ *
+ * Duplicates `code` from the body so a client behind a body-eating proxy can still
+ * tell why the socket never opened.
+ */
+declare const PORTAL_ERROR_HEADER = "x-portal-error";
+
+/**
+ * Why an upgrade was refused (§1.1).
+ *
+ * Refusals happen at the HTTP upgrade — **the socket never opens**. They are therefore
+ * disjoint from {@link PublishErrorCode} (HTTP publish rejections) and from the
+ * in-session `error` frame, which both presuppose a working connection.
+ */
+type RefusalCode = "invalid_token" | "token_expired" | "invalid_api_key" | "not_member" | "banned" | "anonymous_not_allowed" | "unknown_channel" | "unsupported_version" | "channel_at_capacity";
+/**
+ * The HTTP status each refusal is delivered with (§1.1 table).
+ *
+ * The mapping is many-to-one: status alone does not identify the cause, so read
+ * `code` from the body (or the `x-portal-error` header) rather than branching on status.
+ */
+declare const REFUSAL_STATUS: {
+    readonly invalid_token: 401;
+    readonly token_expired: 401;
+    readonly invalid_api_key: 403;
+    readonly not_member: 403;
+    readonly banned: 403;
+    readonly anonymous_not_allowed: 403;
+    readonly unknown_channel: 404;
+    readonly unsupported_version: 426;
+    readonly channel_at_capacity: 429;
+};
+/**
+ * Whether a value is a refusal code this version knows (§1.1).
+ *
+ * A refusal body arriving with an unrecognised code is not a refusal this client can
+ * reason about — treat it as an opaque failure rather than coercing it.
+ */
+declare const isRefusalCode: (value: unknown) => value is RefusalCode;
+/** Body of a refused upgrade (§1.1). */
+type RefusalBody = {
+    code: RefusalCode;
+    reason?: string;
+    /**
+     * Seconds to wait before retrying. Documented for `channel_at_capacity` (429) only
+     * (§1.1); absent on every other refusal.
+     */
+    retryAfter?: number;
+};
+/**
+ * Why an HTTP publish was rejected (§3.1).
+ *
+ * Deliberately NOT merged into {@link RefusalCode}: these arrive on a live connection
+ * in response to `POST /v1/channels/{id}/messages`, and a client reacts to them per
+ * send, not per connection.
+ *
+ * `blocked_by_middleware` carries user-visible copy in `reason`.
+ */
+type PublishErrorCode = "not_permitted" | "blocked_by_middleware" | "content_too_large" | "rate_limited";
+/**
+ * Body of a rejected publish (§3.1).
+ *
+ * SPEC: §3.1 specifies the shape as `4xx { code, reason? }` but does not map each code
+ * to a status, so no status record is exported here (unlike {@link REFUSAL_STATUS}).
+ */
+type PublishErrorBody = {
+    code: PublishErrorCode;
+    reason?: string;
+};
+
+/** A mention as declared by the sender and verified by the platform (§2.1). */
+type Mention = {
+    userId: string;
+};
+/** Who sent a {@link WireMessage} (§2.1). */
+type WireSender = {
+    id: string;
+    anon: boolean;
+    /**
+     * Populated on broadcast channels only — they have no roster to join against.
+     * On standard channels display data is joined app-side by `id`.
+     */
+    username?: string;
+};
+/**
+ * The message envelope as it travels on the wire (§2.1).
+ *
+ * This is the transport form, one layer BELOW the SDK's public `Message`. Notably it
+ * keeps `seq`: ordering, dedup, and gap-fill are expressed in terms of it. Stripping
+ * `seq` and deriving `unread`/`status` is the client runtime's job, not this package's.
+ */
+type WireMessage = {
+    /** Platform-assigned. The dedup and mutation key. */
+    id: string;
+    /**
+     * Per-channel, assigned at persist; contiguous within a connection's delivery stream.
+     *
+     * `null` for ephemeral messages, which are not persisted and carry no ordering or
+     * gap guarantees (§4).
+     */
+    seq: number | null;
+    /** Userland discriminator; defaults to `"message"`. Opaque to the platform. */
+    type: string;
+    /**
+     * Envelope content class; `"text"` throughout v1. Media kinds are reserved and will
+     * not appear in v1 (§7).
+     *
+     * SPEC: §2.1 shows `"kind": "text"` by example but never enumerates the field, so
+     * this is `string` rather than a closed union — a future kind must not cause a v1
+     * parser to drop the frame (§6 forward compatibility).
+     */
+    kind: string;
+    /** Customer payload, ≤2KB. Opaque to the platform and to this package. */
+    content: unknown;
+    sender: WireSender;
+    /** Epoch milliseconds. */
+    timestamp: number;
+    /** Targeted-delivery recipient; the message skips fan-out (§2.1). */
+    to?: string;
+    mentions?: Mention[];
+    /** Flips in place via a `retract` frame; content is stripped per policy. */
+    retracted: boolean;
+    /** Ephemeral messages are not persisted and have `seq: null`. */
+    ephemeral: boolean;
+};
+
+/** Channel mode. Decides presence shape and whether `sender.username` is populated. */
+type ChannelMode = "standard" | "broadcast";
+/** The channel, as described by the connect snapshot (§1.2). */
+type ChannelInfo = {
+    id: string;
+    mode: ChannelMode;
+    name?: string;
+    meta?: Record<string, unknown>;
+};
+/**
+ * What this connection is allowed to do (§1.2).
+ *
+ * Open-ended by design: the index signature lets the platform add capabilities
+ * additively (§6) without breaking older clients. Named keys are the ones observed;
+ * absent means not granted.
+ *
+ * SPEC: §1.2 shows only `publish`, but real `ready` frames also carry `sendDirect`
+ * (fixture `channel_ready.me.capabilities`). The full key set is not enumerated in the
+ * doc.
+ */
+type Capabilities = {
+    /** May publish persistent messages via `POST /v1/channels/{id}/messages` (§3.1). */
+    publish?: boolean;
+    /** May send targeted `to:` messages. Observed in fixtures; not in §1.2. */
+    sendDirect?: boolean;
+    /**
+     * Unrecognised capabilities are `unknown`, not `boolean`: §1.2 neither enumerates the
+     * keys nor promises the values stay boolean, and a stricter type would force the
+     * parser to reject a whole `ready` frame over one unrecognised capability.
+     */
+    [capability: string]: unknown;
+};
+/** The connected user's own verified identity (§1.2). */
+type MeInfo = {
+    id: string;
+    anon: boolean;
+    /** Whatever the token signer signed. Never assembled client-side. */
+    claims: Record<string, unknown>;
+    capabilities: Capabilities;
+};
+/**
+ * A participant as it appears **on the wire** (§1.2 snapshot, §2.1 deltas).
+ *
+ * SPEC: provisional. `{ userId, claims }` is what the current fixtures prove the wire
+ * carries (`channel_ready` presence, and the `presence` frame's `joined`), so it is what
+ * this type says — the type follows recorded evidence, never an anticipated change.
+ *
+ * This shape may change in a future version of the package; treat `claims` as unstable
+ * and do not build against it.
+ */
+type WirePresenceParticipant = {
+    userId: string;
+    claims: Record<string, unknown>;
+};
+/** Presence snapshot on a standard channel, carried by `ready` (§1.2). */
+type DetailedPresenceSnapshot = {
+    mode: "detailed";
+    participants: WirePresenceParticipant[];
+    count: number;
+};
+/**
+ * Presence snapshot on a broadcast channel, carried by `ready` (§1.2).
+ *
+ * SPEC: §1.2 defers the snapshot shape to "detailed | aggregate shape, per mode" and no
+ * fixture covers aggregate mode, so this is modelled on the §2.1 aggregate frame with
+ * `recent` optional. Unverified against a real broadcast `ready`.
+ */
+type AggregatePresenceSnapshot = {
+    mode: "aggregate";
+    count: number;
+    /** SPEC: element shape is elided as `[...]` in §2.1. See {@link AggregatePresenceFrame}. */
+    recent?: unknown[];
+};
+/**
+ * The `presence` value inside `ready` (§1.2), discriminated on `mode`.
+ *
+ * Distinct from {@link PresenceFrame}: the snapshot is the full roster
+ * (`participants`), while the frame is a delta (`joined`/`left`).
+ */
+type ReadyPresence = DetailedPresenceSnapshot | AggregatePresenceSnapshot;
+/**
+ * First frame on a channel socket, exactly once (§1.2).
+ *
+ * One fat snapshot — there is no staged handshake. Initial history is NOT included;
+ * the client fetches `GET /history` (§3.2) in parallel with the upgrade.
+ */
+type ChannelReadyFrame = {
+    t: "ready";
+    channel: ChannelInfo;
+    me: MeInfo;
+    /** Channel head at snapshot time. The gap-fill baseline (§4). */
+    seq: number;
+    /** Opaque reconnect token; send it back unchanged as `?leaf=` on the next connect. */
+    leaf: string;
+    presence: ReadyPresence;
+    /** This user's read position. Absent when watermarks are off (§1.2). */
+    watermark?: number;
+    /**
+     * Cached extension snapshots, keyed by namespace. An unavailable extension is
+     * key-absent rather than null.
+     *
+     * SPEC: §1.2 shows `ext` unconditionally, but real `ready` frames omit it entirely
+     * (fixture `channel_ready`), so it is optional here.
+     */
+    ext?: Record<string, unknown>;
+    /**
+     * Extension namespace → transport, for routing `send()` (§1.2).
+     *
+     * SPEC: shown unconditionally in §1.2 but absent from the fixture; optional here.
+     */
+    bindings?: Record<string, string>;
+};
+/**
+ * THE data frame (§2.1). Messages are coalesced per window; `msgs` is ordered and `seq`
+ * is contiguous within a connection's delivery stream.
+ */
+type BatchFrame = {
+    t: "batch";
+    msgs: WireMessage[];
+};
+/**
+ * A message was retracted (§2.1).
+ *
+ * May reference a `seq` the client does not hold yet (the retraction can outrun its
+ * message): keep a tombstone set and apply on arrival (§4).
+ */
+type RetractFrame = {
+    t: "retract";
+    id: string;
+    seq: number;
+    reason?: string;
+};
+/**
+ * Presence delta on a standard channel (§2.1).
+ *
+ * SPEC: §2.1 elides the `joined`/`left` element shapes as `[...]`. The fixture proves
+ * `joined` carries {@link WirePresenceParticipant}; its `left` is empty, so `left`'s
+ * element shape is assumed symmetric and remains **unverified**.
+ */
+type DetailedPresenceFrame = {
+    t: "presence";
+    mode: "detailed";
+    joined: WirePresenceParticipant[];
+    left: WirePresenceParticipant[];
+    count: number;
+};
+/**
+ * Presence delta on a broadcast channel (§2.1).
+ *
+ * SPEC: `recent` is elided as `[...]` in §2.1 and no fixture covers it, so its element
+ * shape is unproven. It stays `unknown[]` rather than guessing: narrowing it here would
+ * make an invented shape permanent public surface. It awaits a confirmed shape.
+ */
+type AggregatePresenceFrame = {
+    t: "presence";
+    mode: "aggregate";
+    count: number;
+    recent: unknown[];
+};
+/** Presence delta (§2.1), discriminated on `mode`. */
+type PresenceFrame = DetailedPresenceFrame | AggregatePresenceFrame;
+/**
+ * Transient per-user activity — typing, thinking, uploading (§2.1).
+ *
+ * Never echoed for yourself. Peers expire by absence (~5s client-side); there is no
+ * explicit "stopped" frame.
+ */
+type ActivityFrame = {
+    t: "activity";
+    userId: string;
+    kind: string;
+    /** Epoch milliseconds the activity started. */
+    since: number;
+};
+/** Delivery to THIS connection only — `to:`-sends and targeted pushes (§2.1). */
+type DirectFrame = {
+    t: "direct";
+    msg: WireMessage;
+};
+/**
+ * Connection reassignment (§2.1). Close and reconnect, sending the new token back
+ * as `?leaf=`.
+ */
+type ReassignFrame = {
+    t: "reassign";
+    leaf: string;
+};
+/**
+ * An in-session error (§2.1). `ref` echoes the `cl` tag of the client frame it answers,
+ * so a rejected `ephemeral` can be matched back to its send.
+ *
+ * SPEC: §2.1 shows `"code": "not_permitted"` by example but never enumerates in-session
+ * error codes, so `code` is `string`. It is NOT typed as {@link PublishErrorCode}:
+ * §2.2 says upstream gates are "identical" to publish gates, but the doc never states
+ * the two code sets are the same, and inventing that equivalence here would make it
+ * permanent protocol surface.
+ */
+type ErrorFrame = {
+    t: "error";
+    code: string;
+    reason?: string;
+    ref?: string;
+};
+/** Keepalive response (§1.3). Shared with the inbox socket. */
+type PongFrame = {
+    t: "pong";
+};
+/** Every frame the platform can send on a channel socket (§1.2, §2.1). */
+type ChannelServerFrame = ChannelReadyFrame | BatchFrame | RetractFrame | PresenceFrame | ActivityFrame | DirectFrame | ReassignFrame | ErrorFrame | PongFrame;
+/**
+ * The ephemeral lane (§2.2): no persistence, no `seq`, no history. Cursors, transient
+ * signals, and ws-transport extension traffic all ride this.
+ */
+type EphemeralFrame = {
+    t: "ephemeral";
+    /** Client tag. An `error` frame answering this send echoes it as `ref`. */
+    cl: string;
+    type: string;
+    content: unknown;
+};
+/**
+ * Announce own activity (§2.2). Throttled client-side (~3s).
+ *
+ * Distinct from the S→C {@link ActivityFrame}, which adds `userId` and `since`: same
+ * `t`, different shape, different direction.
+ */
+type ActivityUpFrame = {
+    t: "activity";
+    kind: string;
+};
+/** Advance this user's read position (§2.2). Independent of inbox read state (§5). */
+type WatermarkFrame = {
+    t: "watermark";
+    seq: number;
+};
+/**
+ * Replace this session's presence metadata mid-session (§2.2); the change is
+ * re-announced to other participants via presence deltas.
+ *
+ * `metadata` is client-supplied and presentation-only — it never feeds authorization,
+ * which comes from signed token claims. Sends the full replacement bag, not a patch.
+ */
+type MetaFrame = {
+    t: "meta";
+    metadata: Record<string, unknown>;
+};
+/** Keepalive (§1.3). Shared with the inbox socket. */
+type PingFrame = {
+    t: "ping";
+};
+/**
+ * The complete upstream set for a channel socket (§2.2).
+ *
+ * Persistent publishes are NOT here — they go over HTTP (§3.1).
+ */
+type ChannelClientFrame = EphemeralFrame | ActivityUpFrame | WatermarkFrame | MetaFrame | PingFrame;
+
+/**
+ * One conversation row in the inbox (§5).
+ *
+ * `muted` silences aggregation, not data: a muted entry keeps updating and stops
+ * contributing to the counter, but items addressed to you still land.
+ */
+type InboxEntryWire = {
+    /** The channel id this row tracks. */
+    id: string;
+    name?: string;
+    meta?: Record<string, unknown>;
+    /** Preview of the most recent message. Absent on large channels (seq-only tier). */
+    latest?: {
+        text: string;
+        sender: {
+            id: string;
+        };
+        at: number;
+    };
+    unread: number;
+    muted: boolean;
+    /** Recency, epoch milliseconds. The sort key. */
+    at: number;
+};
+/**
+ * A targeted item: a mention, a `to:`-send, or a notify descriptor (§5).
+ *
+ * Items carry per-item read state, unlike channels which are positional (watermark).
+ */
+type InboxItemWire = {
+    /** Event id; the idempotency key. */
+    id: string;
+    /** Userland: `"mention"`, `"ticket.assigned"`, … */
+    type: string;
+    title?: string;
+    /** Userland payload. Opaque to the platform and to this package. */
+    data: unknown;
+    /** Present when the item originated in a channel (mention, `to:`-send). */
+    channelId?: string;
+    at: number;
+    read: boolean;
+};
+/**
+ * First frame on an inbox socket (§5).
+ *
+ * Anonymous tokens never get here — they are refused at the upgrade with 403
+ * `anonymous_not_allowed`, because no inbox exists for them.
+ */
+type InboxReadyFrame = {
+    t: "ready";
+    entries: InboxEntryWire[];
+    items: InboxItemWire[];
+    counter: number;
+};
+/** A row upsert — preview, unread, or mute changed (§5). */
+type InboxEntryFrame = {
+    t: "entry";
+    entry: InboxEntryWire;
+};
+/** A targeted item arrived (§5). */
+type InboxItemFrame = {
+    t: "item";
+    item: InboxItemWire;
+};
+/** The global badge changed (§5). Pushed on change. */
+type InboxCounterFrame = {
+    t: "counter";
+    n: number;
+};
+/** Every frame the platform can send on an inbox socket (§5). */
+type InboxServerFrame = InboxReadyFrame | InboxEntryFrame | InboxItemFrame | InboxCounterFrame | PongFrame;
+/**
+ * Advance the inbox position for one channel — clears its sidebar badge (§5).
+ *
+ * NOT the channel watermark: the inbox tracks *noticing*, the channel tracks *reading*,
+ * and the two may legitimately disagree.
+ */
+type InboxReadFrame = {
+    t: "read";
+    channelId: string;
+};
+/** Flip one item's read flag (§5). Never cascades to older items. */
+type InboxItemReadFrame = {
+    t: "item.read";
+    id: string;
+};
+/** Mark ALL items read (§5). Global and zero-arg — it ignores any client-side filter. */
+type InboxReadAllFrame = {
+    t: "read.all";
+};
+/** Set the durable per-user-per-channel mute preference (§5). */
+type InboxMuteFrame = {
+    t: "mute";
+    channelId: string;
+    muted: boolean;
+};
+/** The complete upstream set for an inbox socket (§5). */
+type InboxClientFrame = InboxReadFrame | InboxItemReadFrame | InboxReadAllFrame | InboxMuteFrame | PingFrame;
+
+/**
+ * Body of `POST /v1/channels/{channelId}/messages` (§3.1).
+ *
+ * Persistent publishes go over HTTP, never the socket (§2.2).
+ */
+type PublishBody = {
+    /** Userland discriminator; defaults to `"message"`. */
+    type?: string;
+    /** ≤2KB, opaque. */
+    content: unknown;
+    /** Defaults to `"text"`. Media kinds are rejected in v1 (§7). */
+    kind?: string;
+    /**
+     * Delivery instruction: skip fan-out and deliver to this member only, writing their
+     * inbox item. A field named `to` inside `content` routes nothing.
+     */
+    to?: string;
+    /** Declared by the sender; the platform verifies, dedupes, and caps them. */
+    mentions?: Mention[];
+};
+/**
+ * A successful publish (§3.1) — the wire form of the SendAck.
+ *
+ * Named `…Wire` deliberately: the SDK's *public* `SendAck` is `{ id, timestamp }` with
+ * no `seq`, because `seq` is transport and gets stripped at the SDK edge. Same concept,
+ * different layer — do not treat the two as interchangeable.
+ *
+ * An ack means accepted and durable; it does not mean permanent (a retraction may
+ * follow).
+ */
+type SendAckWire = {
+    id: string;
+    seq: number;
+    timestamp: number;
+};
+/**
+ * `GET /v1/channels/{channelId}/history` (§3.2).
+ *
+ * One endpoint serves initial backfill, scroll-up paging (`?before=&limit=`), and
+ * gap-fill ranges (`?from=&to=`). Retracted messages come back as tombstoned envelopes,
+ * consistent with live rendering.
+ */
+type HistoryResponse = {
+    msgs: WireMessage[];
+    hasMore: boolean;
+};
+/** One row of the member directory (§3.3). */
+type MemberRow = {
+    userId: string;
+    online: boolean;
+    claims: Record<string, unknown>;
+};
+/**
+ * `GET /v1/channels/{channelId}/members` (§3.3). Standard channels only.
+ *
+ * A fetched directory including offline members — not live presence state. `cursor` is
+ * absent on the last page.
+ */
+type MembersResponse = {
+    members: MemberRow[];
+    cursor?: string;
+};
+
+/**
+ * A well-formed frame whose `t` this version does not know (§6).
+ *
+ * v1 evolves additively: the platform may introduce new frame types, and an older
+ * client MUST ignore them. Ignorable is not the same as droppable — the parser hands
+ * the frame back intact so it survives a parse → serialize round-trip and can be
+ * logged, forwarded, or inspected rather than silently vanishing.
+ */
+type UnknownFrame = {
+    t: string;
+    [field: string]: unknown;
+};
+/**
+ * What {@link parseChannelFrame} yields: a known S→C channel frame, or an
+ * {@link UnknownFrame} passthrough.
+ */
+type ParsedChannelFrame = ChannelServerFrame | UnknownFrame;
+/**
+ * What {@link parseInboxFrame} yields: a known S→C inbox frame, or an
+ * {@link UnknownFrame} passthrough.
+ */
+type ParsedInboxFrame = InboxServerFrame | UnknownFrame;
+/**
+ * What {@link parseChannelClientFrame} yields: a known C→S channel frame, or an
+ * {@link UnknownFrame} passthrough. Used by a server (or mock) receiving upstream frames.
+ */
+type ParsedChannelClientFrame = ChannelClientFrame | UnknownFrame;
+/**
+ * What {@link parseInboxClientFrame} yields: a known C→S inbox frame, or an
+ * {@link UnknownFrame} passthrough.
+ */
+type ParsedInboxClientFrame = InboxClientFrame | UnknownFrame;
+/** Any frame this package can represent, either direction, either socket family. */
+type AnyFrame = ChannelServerFrame | ChannelClientFrame | InboxServerFrame | InboxClientFrame | UnknownFrame;
+
+/**
+ * Parse a text frame from a **channel** socket (S→C).
+ *
+ * Total and non-throwing:
+ * - malformed JSON, a non-object, or a missing/non-string `t` → `null`
+ * - a known `t` whose shape does not match → `null`
+ * - an unknown `t` → the frame is returned intact as an {@link UnknownFrame} (§6),
+ *   because forward compatibility says ignore it, not lose it
+ *
+ * Unknown *fields* on known frames are preserved, so `parse` → {@link serializeFrame}
+ * round-trips without dropping anything.
+ */
+declare function parseChannelFrame(raw: string): ParsedChannelFrame | null;
+/**
+ * Parse a text frame from an **inbox** socket (S→C).
+ *
+ * Same contract as {@link parseChannelFrame}. The two families are disjoint: an inbox
+ * `ready` and a channel `ready` share a `t` but not a shape, so a frame must be parsed
+ * with the function matching the socket it arrived on.
+ */
+declare function parseInboxFrame(raw: string): ParsedInboxFrame | null;
+/**
+ * Parse a text frame a client sent on a **channel** socket (C→S).
+ *
+ * The upstream counterpart of {@link parseChannelFrame}, for a server or test mock
+ * receiving the frames a client sends. Same totality contract: `null` on malformed JSON
+ * / missing `t` / a known `t` with a bad shape, and an {@link UnknownFrame} passthrough
+ * for an unrecognised `t` (§6).
+ */
+declare function parseChannelClientFrame(raw: string): ParsedChannelClientFrame | null;
+/**
+ * Parse a text frame a client sent on an **inbox** socket (C→S).
+ *
+ * Same contract as {@link parseChannelClientFrame}.
+ */
+declare function parseInboxClientFrame(raw: string): ParsedInboxClientFrame | null;
+/**
+ * Serialize a frame to a JSON text frame.
+ *
+ * Primarily for C→S sends. It accepts any frame so that a parsed S→C frame can be
+ * re-serialized intact — the round-trip that proves unknown fields survive (§6).
+ */
+declare function serializeFrame(frame: AnyFrame): string;
+/** True when the parser recognised this channel frame — i.e. it is not an `UnknownFrame`. */
+declare const isKnownChannelFrame: (frame: ParsedChannelFrame) => frame is ChannelServerFrame;
+/** True when the parser recognised this inbox frame — i.e. it is not an `UnknownFrame`. */
+declare const isKnownInboxFrame: (frame: ParsedInboxFrame) => frame is InboxServerFrame;
+/** True when the parser recognised this C→S channel frame (not an `UnknownFrame`). */
+declare const isKnownChannelClientFrame: (frame: ParsedChannelClientFrame) => frame is ChannelClientFrame;
+/** True when the parser recognised this C→S inbox frame (not an `UnknownFrame`). */
+declare const isKnownInboxClientFrame: (frame: ParsedInboxClientFrame) => frame is InboxClientFrame;
+declare const isChannelReady: (f: ParsedChannelFrame) => f is ChannelReadyFrame;
+declare const isBatch: (f: ParsedChannelFrame) => f is BatchFrame;
+declare const isRetract: (f: ParsedChannelFrame) => f is RetractFrame;
+declare const isPresence: (f: ParsedChannelFrame) => f is PresenceFrame;
+declare const isActivity: (f: ParsedChannelFrame) => f is ActivityFrame;
+declare const isDirect: (f: ParsedChannelFrame) => f is DirectFrame;
+declare const isReassign: (f: ParsedChannelFrame) => f is ReassignFrame;
+declare const isError: (f: ParsedChannelFrame) => f is ErrorFrame;
+declare const isPong: (f: ParsedChannelFrame) => f is PongFrame;
+declare const isInboxReady: (f: ParsedInboxFrame) => f is InboxReadyFrame;
+declare const isInboxEntry: (f: ParsedInboxFrame) => f is InboxEntryFrame;
+declare const isInboxItem: (f: ParsedInboxFrame) => f is InboxItemFrame;
+declare const isInboxCounter: (f: ParsedInboxFrame) => f is InboxCounterFrame;
+declare const isInboxPong: (f: ParsedInboxFrame) => f is PongFrame;
+
+export { type ActivityFrame, type ActivityUpFrame, type AggregatePresenceFrame, type AggregatePresenceSnapshot, type AnyFrame, type BatchFrame, type Capabilities, type ChannelClientFrame, type ChannelInfo, type ChannelMode, type ChannelReadyFrame, type ChannelServerFrame, type DetailedPresenceFrame, type DetailedPresenceSnapshot, type DirectFrame, type EphemeralFrame, type ErrorFrame, type HistoryResponse, type InboxClientFrame, type InboxCounterFrame, type InboxEntryFrame, type InboxEntryWire, type InboxItemFrame, type InboxItemReadFrame, type InboxItemWire, type InboxMuteFrame, type InboxReadAllFrame, type InboxReadFrame, type InboxReadyFrame, type InboxServerFrame, type MeInfo, type MemberRow, type MembersResponse, type Mention, type MetaFrame, PORTAL_ERROR_HEADER, PROTOCOL_VERSION, type ParsedChannelClientFrame, type ParsedChannelFrame, type ParsedInboxClientFrame, type ParsedInboxFrame, type PingFrame, type PongFrame, type PresenceFrame, type PublishBody, type PublishErrorBody, type PublishErrorCode, REFUSAL_STATUS, type ReadyPresence, type ReassignFrame, type RefusalBody, type RefusalCode, type RetractFrame, type SendAckWire, UPGRADE_PARAMS, type UnknownFrame, type WatermarkFrame, type WireMessage, type WirePresenceParticipant, type WireSender, isActivity, isBatch, isChannelReady, isDirect, isError, isInboxCounter, isInboxEntry, isInboxItem, isInboxPong, isInboxReady, isKnownChannelClientFrame, isKnownChannelFrame, isKnownInboxClientFrame, isKnownInboxFrame, isPong, isPresence, isReassign, isRefusalCode, isRetract, parseChannelClientFrame, parseChannelFrame, parseInboxClientFrame, parseInboxFrame, serializeFrame };