Transport wire utilities

API at a glance

• encodeFrame(frame, delivery?): Uint8Array
• encodeBinaryEvent(name, bytes, delivery?, maxFrameBytes?): Uint8Array
• binaryEventOverhead(name): number
• decodeFrame(bytes, delivery?): BackendWireFrame
• validateMessageName(name): string
• frameReliablePayload(bytes): Uint8Array
• new ReliableFrameDecoder().push(chunk): Uint8Array[]
• BACKEND_PROTOCOL_VERSION, MAX_RELIABLE_FRAME_BYTES, MAX_UNRELIABLE_FRAME_BYTES, MAX_ACTION_ID_LENGTH
• BackendProtocolError

Ordinary frames are UTF-8 JSON event/action envelopes. Negotiated binary events use IBE/version, name length, ASCII name and raw payload; decodeFrame returns event.binary with Uint8Array bytes. Reliable frames are at most 64 KiB; datagrams at most 1,200 bytes or the smaller transport limit, including the envelope.

Reliable stream framing adds a four-byte length prefix. The decoder buffers partial chunks. These utilities do not create sockets, authenticate peers, encrypt traffic or validate game-specific payloads.

All exported symbols

• BACKEND_PROTOCOL_VERSION
• BINARY_EVENTS_VERSION
• BINARY_NEGOTIATION_ACTION
• BackendProtocolError
• BackendWireFrame
• Delivery
• MAX_ACTION_ID_LENGTH
• MAX_RELIABLE_FRAME_BYTES
• MAX_UNRELIABLE_FRAME_BYTES
• ReliableFrameDecoder
• binaryEventOverhead
• decodeFrame
• encodeBinaryEvent
• encodeFrame
• frameReliablePayload
• validateMessageName

Exact TypeScript API

Generated from the SDK source, including input options, return values, public types and overloads. Relative imports below are links between SDK source modules, not additional package subpaths. Only the entrypoints listed in the reference index are supported import paths.

export declare const BACKEND_PROTOCOL_VERSION: 1;
export declare const MAX_RELIABLE_FRAME_BYTES: number;
export declare const MAX_UNRELIABLE_FRAME_BYTES = 1200;
export declare const MAX_ACTION_ID_LENGTH = 128;
export declare const BINARY_EVENTS_VERSION: 1;
export declare const BINARY_NEGOTIATION_ACTION = "inkwell.binary.negotiate";
export type Delivery = 'reliable' | 'unreliable';
export type BackendWireFrame = {
    version: typeof BACKEND_PROTOCOL_VERSION;
    kind: 'event.binary';
    name: string;
    payload: Uint8Array;
} | {
    version: typeof BACKEND_PROTOCOL_VERSION;
    kind: 'event';
    name: string;
    payload: unknown;
} | {
    version: typeof BACKEND_PROTOCOL_VERSION;
    kind: 'action.request';
    id: string;
    name: string;
    payload: unknown;
} | {
    version: typeof BACKEND_PROTOCOL_VERSION;
    kind: 'action.result';
    id: string;
    payload: unknown;
} | {
    version: typeof BACKEND_PROTOCOL_VERSION;
    kind: 'action.error';
    id: string;
    error: {
        code: string;
        message: string;
    };
};
export declare class BackendProtocolError extends Error {
    constructor(message: string);
}
export declare function validateMessageName(name: string): string;
export declare function encodeFrame(frame: Exclude<BackendWireFrame, {
    kind: 'event.binary';
}>, delivery?: 'reliable' | 'unreliable'): Uint8Array<ArrayBuffer>;
/** Bytes reserved by a binary event's version and validated ASCII name. */
export declare function binaryEventOverhead(name: string): number;
/** Binary events use IBE/version, a one-byte name length, name, then raw payload. */
export declare function encodeBinaryEvent(name: string, payload: Uint8Array, delivery?: Delivery, maxFrameBytes?: number): Uint8Array;
export declare function decodeFrame(bytes: ArrayBuffer | Uint8Array, delivery?: Delivery): BackendWireFrame;
export declare function frameReliablePayload(bytes: Uint8Array): Uint8Array<ArrayBuffer>;
export declare class ReliableFrameDecoder {
    private buffered;
    push(chunk: Uint8Array): Uint8Array<ArrayBufferLike>[];
}

export declare class GameServiceError extends Error {
    readonly status: number;
    readonly code: string;
    constructor(message: string, status?: number, code?: string);
}
export type GameServiceRequest = <T>(service: string, request: Record<string, unknown>) => Promise<T>;
export declare const requestGameService: GameServiceRequest;
/** Server-only adapter. Credentials must never be bundled into browser games. */
export declare function createGameServiceRequest(options: {
    baseUrl: string;
    token: string;
    fetch?: typeof fetch;
}): GameServiceRequest;

export declare const SDK_SOURCE: "inkwell-sdk";
export declare const SDK_VERSION: 1;
export type InkwellMessageType = "ready" | "loading.progress" | "loading.error" | "session.complete" | "analytics.track" | "assets.progress" | "player.get" | "presence.get" | "performance.sample" | "backend.connect" | "backend.fetch";
export type InkwellMessage = {
    source: typeof SDK_SOURCE;
    version: typeof SDK_VERSION;
    type: InkwellMessageType;
    payload?: Record<string, unknown>;
    sentAt: number;
};
export declare function parentOrigin(): string | null;
export declare function requestId(): string;
export declare function emit(type: InkwellMessageType, payload?: Record<string, unknown>): boolean;