@mathieuc/tradingview 3.5.1 → 4.0.0-beta.0

package/dist/http/request.js

@@ -0,0 +1,83 @@
+import { TradingViewError, toTradingViewError } from '../errors.js';
+export const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 '
+    + '(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+/** Builds the `cookie` header value for credentials. */
+export function authCookies(credentials) {
+    if (!credentials?.session)
+        return '';
+    if (!credentials.signature)
+        return `sessionid=${credentials.session}`;
+    return `sessionid=${credentials.session};sessionid_sign=${credentials.signature}`;
+}
+function requestUrl(url, query) {
+    const target = new URL(url);
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined && value !== null)
+            target.searchParams.set(key, String(value));
+    }
+    return target;
+}
+function requestBody(init, headers) {
+    if (init.form) {
+        const form = new URLSearchParams();
+        for (const [key, value] of Object.entries(init.form)) {
+            if (value !== undefined && value !== null)
+                form.set(key, String(value));
+        }
+        headers['content-type'] = 'application/x-www-form-urlencoded';
+        return form.toString();
+    }
+    if (init.json !== undefined) {
+        headers['content-type'] = 'application/json';
+        return JSON.stringify(init.json);
+    }
+    return undefined;
+}
+function responseData(text) {
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Performs a request. Like the historical client, 5xx statuses throw. */
+export async function request(url, init, options = {}) {
+    const target = requestUrl(url, init.query);
+    const headers = { ...options.headers, ...init.headers };
+    const cookie = authCookies(init.credentials);
+    if (cookie)
+        headers.cookie = cookie;
+    const body = requestBody(init, headers);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+        response = await fetchImpl(target.toString(), {
+            method: init.method ?? (body === undefined ? 'GET' : 'POST'),
+            headers,
+            body,
+            redirect: init.redirect ?? 'follow',
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        throw toTradingViewError(error, 'HTTP_ERROR');
+    }
+    const text = await response.text();
+    if (response.status >= 500) {
+        throw new TradingViewError('HTTP_ERROR', `${target.host} answered HTTP ${response.status}`, {
+            details: { status: response.status, body: text.slice(0, 500) },
+        });
+    }
+    return {
+        status: response.status, headers: response.headers, url: target.toString(), text, data: responseData(text),
+    };
+}
+/** Reads every `set-cookie` header, across runtimes. */
+export function getSetCookies(headers) {
+    const withGetter = headers;
+    if (typeof withGetter.getSetCookie === 'function')
+        return withGetter.getSetCookie();
+    const raw = headers.get('set-cookie');
+    return raw ? raw.split(/,(?=\s*[^;,=\s]+=)/) : [];
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TradingView-API v4.
+ *
+ * - High-level data API (also available from `@mathieuc/tradingview/data`):
+ *   `getCandles`, `watchCandles`, `getQuote`, `watchQuotes`, `getIndicatorData`...
+ * - Low-level API: `TradingViewClient`, chart and quote sessions, studies.
+ * - HTTP API: search, technical analysis, indicators, accounts, layouts.
+ *
+ * Independent community project, not affiliated with TradingView.
+ */
+export * from './data/index.js';
+export * from './client/index.js';
+export * from './chart/index.js';
+export * from './quote/index.js';
+export * from './indicators/index.js';
+export * from './http/index.js';
+export * as protocol from './protocol/index.js';
+export { Emitter } from './events.js';
+export type { AnyListener, Listener, Unsubscribe } from './events.js';
+export { TradingViewError, toTradingViewError } from './errors.js';
+export type { TradingViewErrorCode, TradingViewErrorOptions } from './errors.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * TradingView-API v4.
+ *
+ * - High-level data API (also available from `@mathieuc/tradingview/data`):
+ *   `getCandles`, `watchCandles`, `getQuote`, `watchQuotes`, `getIndicatorData`...
+ * - Low-level API: `TradingViewClient`, chart and quote sessions, studies.
+ * - HTTP API: search, technical analysis, indicators, accounts, layouts.
+ *
+ * Independent community project, not affiliated with TradingView.
+ */
+export * from './data/index.js';
+export * from './client/index.js';
+export * from './chart/index.js';
+export * from './quote/index.js';
+export * from './indicators/index.js';
+export * from './http/index.js';
+export * as protocol from './protocol/index.js';
+export { Emitter } from './events.js';
+export { TradingViewError, toTradingViewError } from './errors.js';

package/dist/indicators/builtin-indicator.d.ts

@@ -0,0 +1,17 @@
+/** Known built-in (non-Pine) study types. Any other type string is accepted too. */
+export type BuiltInIndicatorType = 'Volume@tv-basicstudies-241' | 'VbPFixed@tv-basicstudies-241' | 'VbPFixed@tv-basicstudies-241!' | 'VbPFixed@tv-volumebyprice-53!' | 'VbPSessions@tv-volumebyprice-53' | 'VbPSessionsRough@tv-volumebyprice-53!' | 'VbPSessionsDetailed@tv-volumebyprice-53!' | 'VbPVisible@tv-volumebyprice-53' | (string & {});
+export type BuiltInIndicatorOption = 'length' | 'col_prev_close' | 'rowsLayout' | 'rows' | 'volume' | 'vaVolume' | 'subscribeRealtime' | 'first_bar_time' | 'first_visible_bar_time' | 'last_bar_time' | 'last_visible_bar_time' | 'extendToRight' | 'mapRightBoundaryToBarStartTime' | 'extendPocRight' | (string & {});
+/** A built-in TradingView study such as Volume or Volume Profile. */
+export declare class BuiltInIndicator {
+    #private;
+    readonly type: BuiltInIndicatorType;
+    readonly options: Record<string, unknown>;
+    constructor(type: BuiltInIndicatorType, options?: Record<string, unknown>);
+    /**
+     * Changes an option. For known types, the key and value type are validated
+     * unless `force` is true.
+     */
+    setOption(key: BuiltInIndicatorOption, value: unknown, force?: boolean): this;
+    /** Parameters sent with `create_study` / `modify_study`. */
+    toStudyInputs(): Record<string, unknown>;
+}

package/dist/indicators/builtin-indicator.js

@@ -0,0 +1,75 @@
+import { TradingViewError } from '../errors.js';
+function defaultOptions(type) {
+    const now = Date.now();
+    const profile = {
+        rowsLayout: 'Number Of Rows', rows: 24, volume: 'Up/Down', vaVolume: 70,
+    };
+    switch (type) {
+        case 'Volume@tv-basicstudies-241':
+            return { length: 20, col_prev_close: false };
+        case 'VbPFixed@tv-basicstudies-241':
+            return {
+                ...profile,
+                subscribeRealtime: false,
+                first_bar_time: NaN,
+                last_bar_time: now,
+                extendToRight: false,
+                mapRightBoundaryToBarStartTime: true,
+            };
+        case 'VbPFixed@tv-basicstudies-241!':
+        case 'VbPFixed@tv-volumebyprice-53!':
+            return {
+                ...profile, subscribeRealtime: false, first_bar_time: NaN, last_bar_time: now,
+            };
+        case 'VbPSessions@tv-volumebyprice-53':
+            return { ...profile, extendPocRight: false };
+        case 'VbPSessionsRough@tv-volumebyprice-53!':
+            return { volume: 'Up/Down', vaVolume: 70 };
+        case 'VbPSessionsDetailed@tv-volumebyprice-53!':
+            return {
+                volume: 'Up/Down', vaVolume: 70, subscribeRealtime: false, first_visible_bar_time: NaN, last_visible_bar_time: now,
+            };
+        case 'VbPVisible@tv-volumebyprice-53':
+            return {
+                ...profile, subscribeRealtime: false, first_visible_bar_time: NaN, last_visible_bar_time: now,
+            };
+        default:
+            return undefined;
+    }
+}
+/** A built-in TradingView study such as Volume or Volume Profile. */
+export class BuiltInIndicator {
+    type;
+    options;
+    #defaults;
+    constructor(type, options = {}) {
+        if (!type)
+            throw new TradingViewError('INVALID_ARGUMENT', 'A built-in indicator type is required');
+        this.type = type;
+        this.#defaults = defaultOptions(type);
+        this.options = { ...this.#defaults };
+        for (const [key, value] of Object.entries(options))
+            this.setOption(key, value);
+    }
+    /**
+     * Changes an option. For known types, the key and value type are validated
+     * unless `force` is true.
+     */
+    setOption(key, value, force = false) {
+        if (!force && this.#defaults) {
+            if (!(key in this.#defaults)) {
+                throw new TradingViewError('INVALID_ARGUMENT', `Option '${key}' is not allowed for '${this.type}'`);
+            }
+            const expected = typeof this.#defaults[key];
+            if (typeof value !== expected) {
+                throw new TradingViewError('INVALID_ARGUMENT', `Option '${key}' must be a ${expected}`);
+            }
+        }
+        this.options[key] = value;
+        return this;
+    }
+    /** Parameters sent with `create_study` / `modify_study`. */
+    toStudyInputs() {
+        return { ...this.options };
+    }
+}

package/dist/indicators/index.d.ts

@@ -0,0 +1,8 @@
+export { PineIndicator } from './pine-indicator.js';
+export type { PineIndicatorDefinition, PineInput, PineInputType, PineStudyType, } from './pine-indicator.js';
+export { BuiltInIndicator } from './builtin-indicator.js';
+export type { BuiltInIndicatorOption, BuiltInIndicatorType } from './builtin-indicator.js';
+import type { BuiltInIndicator } from './builtin-indicator.js';
+import type { PineIndicator } from './pine-indicator.js';
+/** Anything that can run as a study on a chart. */
+export type Indicator = PineIndicator | BuiltInIndicator;

package/dist/indicators/index.js

@@ -0,0 +1,2 @@
+export { PineIndicator } from './pine-indicator.js';
+export { BuiltInIndicator } from './builtin-indicator.js';

package/dist/indicators/pine-indicator.d.ts

@@ -0,0 +1,63 @@
+/** Pine input types sent by TradingView. */
+export type PineInputType = 'text' | 'source' | 'integer' | 'float' | 'resolution' | 'bool' | 'color' | 'session' | 'symbol' | 'time' | 'price' | 'textarea' | (string & {});
+export interface PineInput {
+    /** Display name. */
+    name: string;
+    /** Name usable with `setInput` (inline name or sanitised display name). */
+    inline: string;
+    /** Internal ID, when the script defines one. */
+    internalID?: string;
+    tooltip?: string;
+    type: PineInputType;
+    value: unknown;
+    isHidden: boolean;
+    isFake: boolean;
+    /** Allowed values for select inputs. */
+    options?: unknown[];
+}
+/** Study type used to create the indicator on a chart. */
+export type PineStudyType = 'Script@tv-scripting-101!' | 'StrategyScript@tv-scripting-101!';
+export interface PineIndicatorDefinition {
+    /** Script ID, like `STD;RSI`, `PUB;xxxx` or `USER;xxxx`. */
+    id: string;
+    version: string;
+    description: string;
+    shortDescription: string;
+    /** Inputs indexed by input ID (`in_0`, `in_1`...). */
+    inputs: Record<string, PineInput>;
+    /** Plot names indexed by plot ID (`plot_0`...). */
+    plots: Record<string, string>;
+    /** Compiled script (IL template) sent to the chart. */
+    script: string;
+    /** Study type. Defaults to `Script@tv-scripting-101!`. */
+    type?: PineStudyType;
+}
+/** A Pine script (built-in, public, invite-only or private) ready to run on a chart. */
+export declare class PineIndicator {
+    #private;
+    readonly id: string;
+    readonly version: string;
+    readonly description: string;
+    readonly shortDescription: string;
+    readonly inputs: Record<string, PineInput>;
+    readonly plots: Record<string, string>;
+    readonly script: string;
+    constructor(definition: PineIndicatorDefinition);
+    /** Study type used to create the indicator on a chart. */
+    get type(): PineStudyType;
+    /** Changes the study type, for example to run a strategy as `StrategyScript`. */
+    setType(type: PineStudyType): this;
+    /** Finds the input ID for an input ID (`in_0`), its number (`0`), inline name or internal ID. */
+    findInput(key: string | number): string | undefined;
+    /**
+     * Changes an input value, with type and option validation.
+     * @param key Input ID (`in_0`), number (`0`), inline name or internal ID.
+     */
+    setInput(key: string | number, value: unknown): this;
+    /** Changes several inputs at once. */
+    setInputs(values: Record<string, unknown>): this;
+    /** Independent copy, so one definition can run with different inputs. */
+    clone(): PineIndicator;
+    /** Parameters sent with `create_study` / `modify_study`. */
+    toStudyInputs(): Record<string, unknown>;
+}

package/dist/indicators/pine-indicator.js

@@ -0,0 +1,101 @@
+import { TradingViewError } from '../errors.js';
+const INPUT_TYPES = {
+    bool: 'boolean',
+    integer: 'number',
+    float: 'number',
+    text: 'string',
+};
+/** A Pine script (built-in, public, invite-only or private) ready to run on a chart. */
+export class PineIndicator {
+    id;
+    version;
+    description;
+    shortDescription;
+    inputs;
+    plots;
+    script;
+    #type;
+    constructor(definition) {
+        this.id = definition.id;
+        this.version = definition.version;
+        this.description = definition.description;
+        this.shortDescription = definition.shortDescription;
+        this.inputs = structuredClone(definition.inputs);
+        this.plots = { ...definition.plots };
+        this.script = definition.script;
+        this.#type = definition.type ?? 'Script@tv-scripting-101!';
+    }
+    /** Study type used to create the indicator on a chart. */
+    get type() {
+        return this.#type;
+    }
+    /** Changes the study type, for example to run a strategy as `StrategyScript`. */
+    setType(type) {
+        this.#type = type;
+        return this;
+    }
+    /** Finds the input ID for an input ID (`in_0`), its number (`0`), inline name or internal ID. */
+    findInput(key) {
+        if (this.inputs[`in_${key}`])
+            return `in_${key}`;
+        if (this.inputs[key])
+            return String(key);
+        return Object.keys(this.inputs).find((id) => (this.inputs[id].inline === key || this.inputs[id].internalID === key));
+    }
+    /**
+     * Changes an input value, with type and option validation.
+     * @param key Input ID (`in_0`), number (`0`), inline name or internal ID.
+     */
+    setInput(key, value) {
+        const id = this.findInput(key);
+        if (!id)
+            throw new TradingViewError('INVALID_ARGUMENT', `Input '${key}' not found`);
+        const input = this.inputs[id];
+        const expected = INPUT_TYPES[input.type];
+        if (expected && typeof value !== expected) {
+            throw new TradingViewError('INVALID_ARGUMENT', `Input '${input.name}' (${id}) must be a ${expected}`);
+        }
+        if (input.options && !input.options.includes(value)) {
+            throw new TradingViewError('INVALID_ARGUMENT', `Input '${input.name}' (${id}) must be one of: ${input.options.map(String).join(', ')}`, { details: input.options });
+        }
+        input.value = value;
+        return this;
+    }
+    /** Changes several inputs at once. */
+    setInputs(values) {
+        for (const [key, value] of Object.entries(values))
+            this.setInput(key, value);
+        return this;
+    }
+    /** Independent copy, so one definition can run with different inputs. */
+    clone() {
+        return new PineIndicator({
+            id: this.id,
+            version: this.version,
+            description: this.description,
+            shortDescription: this.shortDescription,
+            inputs: this.inputs,
+            plots: this.plots,
+            script: this.script,
+            type: this.#type,
+        });
+    }
+    /** Parameters sent with `create_study` / `modify_study`. */
+    toStudyInputs() {
+        const inputs = { text: this.script };
+        if (this.id)
+            inputs.pineId = this.id;
+        if (this.version)
+            inputs.pineVersion = this.version;
+        Object.keys(this.inputs).forEach((id, index) => {
+            const input = this.inputs[id];
+            inputs[id] = {
+                // TradingView expects colour inputs as their position, not their value.
+                v: input.type !== 'color' ? input.value : index,
+                f: input.isFake,
+                t: input.type,
+            };
+        });
+        return inputs;
+    }
+}

package/dist/protocol/compression.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TradingView sends large strategy reports as base64 data (`dataCompressed`).
+ * The payload is usually a ZIP archive with a single entry, but zlib, raw
+ * deflate, gzip and plain JSON have also been observed. Base64 may be URL-safe
+ * and unpadded.
+ */
+/** Normalises URL-safe and unpadded base64. */
+export declare function normaliseBase64(data: string): string;
+/** Reads the first file of a ZIP archive (stored or deflated). */
+export declare function readFirstZipEntry(archive: Uint8Array): Uint8Array;
+/** Decodes a TradingView compressed payload into JSON. */
+export declare function decodeCompressed(data: string): unknown;

package/dist/protocol/compression.js

@@ -0,0 +1,83 @@
+import { gunzipSync, inflateRawSync, inflateSync } from 'node:zlib';
+import { TradingViewError } from '../errors.js';
+/**
+ * TradingView sends large strategy reports as base64 data (`dataCompressed`).
+ * The payload is usually a ZIP archive with a single entry, but zlib, raw
+ * deflate, gzip and plain JSON have also been observed. Base64 may be URL-safe
+ * and unpadded.
+ */
+/** Normalises URL-safe and unpadded base64. */
+export function normaliseBase64(data) {
+    const normalised = data.replace(/-/g, '+').replace(/_/g, '/').replace(/\s/g, '');
+    return normalised.padEnd(normalised.length + ((4 - (normalised.length % 4)) % 4), '=');
+}
+const LOCAL_FILE_HEADER = 0x04034b50;
+const CENTRAL_DIRECTORY_HEADER = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+function inflateEntry(method, data) {
+    if (method === 0)
+        return data;
+    if (method === 8)
+        return inflateRawSync(data);
+    throw new Error(`Unsupported ZIP compression method ${method}`);
+}
+/** Reads the first file of a ZIP archive (stored or deflated). */
+export function readFirstZipEntry(archive) {
+    const buffer = Buffer.from(archive.buffer, archive.byteOffset, archive.byteLength);
+    // Prefer the central directory: local headers may omit sizes (data descriptors).
+    for (let eocd = buffer.length - 22; eocd >= Math.max(0, buffer.length - 0xffff - 22); eocd -= 1) {
+        if (buffer.readUInt32LE(eocd) !== END_OF_CENTRAL_DIRECTORY)
+            continue;
+        const entries = buffer.readUInt16LE(eocd + 10);
+        let cursor = buffer.readUInt32LE(eocd + 16);
+        for (let i = 0; i < entries; i += 1) {
+            if (buffer.readUInt32LE(cursor) !== CENTRAL_DIRECTORY_HEADER)
+                break;
+            const method = buffer.readUInt16LE(cursor + 10);
+            const compressedSize = buffer.readUInt32LE(cursor + 20);
+            const nameLength = buffer.readUInt16LE(cursor + 28);
+            const extraLength = buffer.readUInt16LE(cursor + 30);
+            const commentLength = buffer.readUInt16LE(cursor + 32);
+            const localOffset = buffer.readUInt32LE(cursor + 42);
+            const name = buffer.toString('utf8', cursor + 46, cursor + 46 + nameLength);
+            cursor += 46 + nameLength + extraLength + commentLength;
+            if (name.endsWith('/'))
+                continue; // Directory entry.
+            const localNameLength = buffer.readUInt16LE(localOffset + 26);
+            const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+            const start = localOffset + 30 + localNameLength + localExtraLength;
+            return inflateEntry(method, buffer.subarray(start, start + compressedSize));
+        }
+        break;
+    }
+    // No usable central directory: fall back to the first local header.
+    if (buffer.length >= 30 && buffer.readUInt32LE(0) === LOCAL_FILE_HEADER) {
+        const method = buffer.readUInt16LE(8);
+        const compressedSize = buffer.readUInt32LE(18);
+        const start = 30 + buffer.readUInt16LE(26) + buffer.readUInt16LE(28);
+        const end = compressedSize > 0 ? start + compressedSize : buffer.length;
+        return inflateEntry(method, buffer.subarray(start, end));
+    }
+    throw new Error('Not a ZIP archive');
+}
+/** Decodes a TradingView compressed payload into JSON. */
+export function decodeCompressed(data) {
+    const buffer = Buffer.from(normaliseBase64(data), 'base64');
+    const readers = [
+        () => readFirstZipEntry(buffer),
+        () => buffer,
+        () => inflateSync(buffer),
+        () => inflateRawSync(buffer),
+        () => gunzipSync(buffer),
+    ];
+    let lastError;
+    for (const read of readers) {
+        try {
+            return JSON.parse(Buffer.from(read()).toString('utf8'));
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new TradingViewError('PARSE_ERROR', 'Unable to decode compressed payload', { cause: lastError });
+}

package/dist/protocol/framing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * TradingView websocket framing.
+ *
+ * Every websocket message contains one or more frames: `~m~<length>~m~<payload>`.
+ * The length counts UTF-16 code units (JavaScript string length). Payloads are
+ * either JSON packets or heartbeats (`~h~<id>`), which the client must echo.
+ */
+/** A JSON packet sent by the server: `m` is the method, `p` its parameters. */
+export interface ServerPacket {
+    m: string;
+    p: unknown[];
+    /** Server timestamp in seconds. */
+    t?: number;
+    /** Server timestamp in milliseconds. */
+    t_ms?: number;
+}
+/** Greeting sent by the server right after the websocket opens. */
+export interface ServerHello {
+    session_id: string;
+    timestamp: number;
+    timestampMs: number;
+    release: string;
+    studies_metadata_hash: string;
+    auth_scheme_vsn: number;
+    protocol: 'json' | string;
+    via: string;
+    javastudies: string[];
+    [key: string]: unknown;
+}
+export type Frame = 
+/** Heartbeat to echo back with `encodeHeartbeat(id)`. */
+{
+    type: 'heartbeat';
+    id: number;
+}
+/** Method packet (`{ m, p }`). */
+ | {
+    type: 'packet';
+    packet: ServerPacket;
+}
+/** Any other JSON payload (for example the server greeting). */
+ | {
+    type: 'data';
+    data: unknown;
+}
+/** A payload that could not be parsed. */
+ | {
+    type: 'invalid';
+    raw: string;
+    error: unknown;
+};
+/** Decodes a raw websocket message into frames. */
+export declare function decodeFrames(input: string): Frame[];
+/** Encodes one frame. Objects are JSON-encoded. */
+export declare function encodeFrame(payload: string | object): string;
+/** Encodes a client packet (`{ m: method, p: params }`). */
+export declare function encodePacket(method: string, params?: readonly unknown[]): string;
+/** Encodes the reply to a server heartbeat. */
+export declare function encodeHeartbeat(id: number): string;

package/dist/protocol/framing.js

@@ -0,0 +1,68 @@
+/**
+ * TradingView websocket framing.
+ *
+ * Every websocket message contains one or more frames: `~m~<length>~m~<payload>`.
+ * The length counts UTF-16 code units (JavaScript string length). Payloads are
+ * either JSON packets or heartbeats (`~h~<id>`), which the client must echo.
+ */
+const HEADER = '~m~';
+const HEARTBEAT = '~h~';
+function decodePayload(raw) {
+    if (raw.startsWith(HEARTBEAT)) {
+        const id = Number(raw.slice(HEARTBEAT.length));
+        if (Number.isFinite(id))
+            return { type: 'heartbeat', id };
+        return { type: 'invalid', raw, error: new Error('Invalid heartbeat') };
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        return { type: 'invalid', raw, error };
+    }
+    if (data && typeof data === 'object' && typeof data.m === 'string') {
+        const packet = data;
+        return { type: 'packet', packet: { ...packet, p: Array.isArray(packet.p) ? packet.p : [] } };
+    }
+    return { type: 'data', data };
+}
+/** Lenient fallback for malformed input: split on frame headers. */
+function splitFrames(input) {
+    return input.split(/~m~\d+~m~/).filter((part) => part.length > 0);
+}
+/** Decodes a raw websocket message into frames. */
+export function decodeFrames(input) {
+    const payloads = [];
+    let position = 0;
+    while (position < input.length) {
+        if (!input.startsWith(HEADER, position)) {
+            payloads.push(...splitFrames(input.slice(position)));
+            break;
+        }
+        const lengthStart = position + HEADER.length;
+        const lengthEnd = input.indexOf(HEADER, lengthStart);
+        const length = Number(input.slice(lengthStart, lengthEnd));
+        if (lengthEnd < 0 || !Number.isInteger(length) || length < 0) {
+            payloads.push(...splitFrames(input.slice(position)));
+            break;
+        }
+        const start = lengthEnd + HEADER.length;
+        payloads.push(input.slice(start, start + length));
+        position = start + length;
+    }
+    return payloads.map(decodePayload);
+}
+/** Encodes one frame. Objects are JSON-encoded. */
+export function encodeFrame(payload) {
+    const body = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    return `${HEADER}${body.length}${HEADER}${body}`;
+}
+/** Encodes a client packet (`{ m: method, p: params }`). */
+export function encodePacket(method, params = []) {
+    return encodeFrame({ m: method, p: params });
+}
+/** Encodes the reply to a server heartbeat. */
+export function encodeHeartbeat(id) {
+    return encodeFrame(`${HEARTBEAT}${id}`);
+}

package/dist/protocol/ids.d.ts

@@ -0,0 +1,2 @@
+/** Creates a random session or request ID such as `cs_Ab12Cd34Ef56`. */
+export declare function createSessionId(prefix?: string): string;

package/dist/protocol/ids.js

@@ -0,0 +1,10 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** Creates a random session or request ID such as `cs_Ab12Cd34Ef56`. */
+export function createSessionId(prefix = 'xs') {
+    const bytes = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(bytes);
+    let id = '';
+    for (const byte of bytes)
+        id += ALPHABET[byte % ALPHABET.length];
+    return `${prefix}_${id}`;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,4 @@
+export { decodeFrames, encodeFrame, encodeHeartbeat, encodePacket, } from './framing.js';
+export type { Frame, ServerHello, ServerPacket } from './framing.js';
+export { decodeCompressed, normaliseBase64, readFirstZipEntry } from './compression.js';
+export { createSessionId } from './ids.js';

package/dist/protocol/index.js

@@ -0,0 +1,3 @@
+export { decodeFrames, encodeFrame, encodeHeartbeat, encodePacket, } from './framing.js';
+export { decodeCompressed, normaliseBase64, readFirstZipEntry } from './compression.js';
+export { createSessionId } from './ids.js';