@massalabs/gossip-sdk 0.0.2-dev.20260128094509 → 0.0.2-dev.20260128160824

package/dist/utils/logs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logger utility for SDK
+ *
+ * Provides structured console logging with module and context support.
+ * All output goes to the terminal via console methods.
+ */
+export declare class Logger {
+    private module;
+    private context;
+    constructor(module: string, context?: string);
+    private getSource;
+    private formatMainMessage;
+    info(message: string, extra?: unknown): void;
+    error(messageOrError: string | Error | unknown, extra?: unknown): void;
+    debug(message: string, extra?: unknown): void;
+    warn(message: string, extra?: unknown): void;
+    withContext(newContext: string): Logger;
+    forMethod(methodName: string): Logger;
+}

package/dist/utils/logs.js

@@ -0,0 +1,89 @@
+/**
+ * Logger utility for SDK
+ *
+ * Provides structured console logging with module and context support.
+ * All output goes to the terminal via console methods.
+ */
+export class Logger {
+    constructor(module, context = '') {
+        Object.defineProperty(this, "module", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.module = module;
+        this.context = context;
+    }
+    getSource() {
+        return this.context ? `${this.module}:${this.context}` : this.module;
+    }
+    formatMainMessage(message) {
+        const source = this.getSource();
+        return `[${source}] ${message}`;
+    }
+    info(message, extra) {
+        const main = this.formatMainMessage(message);
+        if (extra !== undefined) {
+            console.log(main, extra);
+        }
+        else {
+            console.log(main);
+        }
+    }
+    error(messageOrError, extra) {
+        const source = this.getSource();
+        if (messageOrError instanceof Error) {
+            const main = `[${source}] ${messageOrError.message}`;
+            console.error(main, messageOrError, extra);
+        }
+        else {
+            const message = typeof messageOrError === 'string'
+                ? messageOrError
+                : messageOrError instanceof Error
+                    ? messageOrError.message
+                    : JSON.stringify(messageOrError);
+            const main = `[${source}] ${message}`;
+            if (extra !== undefined) {
+                console.error(main, extra);
+            }
+            else {
+                console.error(main);
+            }
+        }
+    }
+    debug(message, extra) {
+        const main = this.formatMainMessage(message);
+        if (extra !== undefined) {
+            console.debug(main, extra);
+        }
+        else {
+            console.debug(main);
+        }
+    }
+    warn(message, extra) {
+        const main = this.formatMainMessage(message);
+        if (extra !== undefined) {
+            console.warn(main, extra);
+        }
+        else {
+            console.warn(main);
+        }
+    }
+    // Chainable context builder
+    withContext(newContext) {
+        const fullContext = this.context
+            ? `${this.context}:${newContext}`
+            : newContext;
+        return new Logger(this.module, fullContext);
+    }
+    forMethod(methodName) {
+        return this.withContext(methodName);
+    }
+}

package/dist/utils/messageSerialization.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Message Serialization Utilities
+ *
+ * Functions for serializing and deserializing messages for the protocol.
+ * Supports regular text messages, replies, forwards, and keep-alive messages.
+ */
+import { MessageType } from '../db';
+export declare const MESSAGE_TYPE_KEEP_ALIVE = 3;
+export interface DeserializedMessage {
+    content: string;
+    replyTo?: {
+        originalContent: string;
+        originalSeeker: Uint8Array;
+    };
+    forwardOf?: {
+        originalContent: string;
+        originalSeeker: Uint8Array;
+    };
+    type: MessageType;
+}
+/**
+ * Serialize a keep-alive message
+ * Keep-alive messages are used to maintain session activity
+ */
+export declare function serializeKeepAliveMessage(): Uint8Array;
+/**
+ * Serialize a regular text message
+ *
+ * Format: [type: 1 byte][content: variable]
+ *
+ * @param content - The message content string
+ * @returns Serialized message bytes
+ */
+export declare function serializeRegularMessage(content: string): Uint8Array;
+/**
+ * Serialize a reply message
+ *
+ * Format: [type: 1 byte][originalContentLen: 4 bytes][originalContent][seeker: 34 bytes][newContent]
+ *
+ * @param newContent - The reply content
+ * @param originalContent - The content being replied to
+ * @param originalSeeker - The seeker of the original message
+ * @returns Serialized reply message bytes
+ */
+export declare function serializeReplyMessage(newContent: string, originalContent: string, originalSeeker: Uint8Array): Uint8Array;
+/**
+ * Serialize a forward message
+ *
+ * Format: [type: 1 byte][forwardContentLen: 4 bytes][forwardContent][seeker: 34 bytes][newContent]
+ *
+ * @param forwardContent - The content being forwarded
+ * @param newContent - Optional new content to add (empty string if none)
+ * @param originalSeeker - The seeker of the original message
+ * @returns Serialized forward message bytes
+ */
+export declare function serializeForwardMessage(forwardContent: string, newContent: string, originalSeeker: Uint8Array): Uint8Array;
+/**
+ * Deserialize a message from bytes
+ *
+ * @param buffer - The serialized message bytes
+ * @returns Deserialized message object
+ * @throws Error if message format is invalid
+ */
+export declare function deserializeMessage(buffer: Uint8Array): DeserializedMessage;

package/dist/utils/messageSerialization.js

@@ -0,0 +1,184 @@
+/**
+ * Message Serialization Utilities
+ *
+ * Functions for serializing and deserializing messages for the protocol.
+ * Supports regular text messages, replies, forwards, and keep-alive messages.
+ */
+import { strToBytes, bytesToStr, U32 } from '@massalabs/massa-web3';
+import { MessageType } from '../db';
+// Message type constants (protocol-level)
+const MESSAGE_TYPE_REGULAR = 0x00;
+const MESSAGE_TYPE_REPLY = 0x01;
+const MESSAGE_TYPE_FORWARD = 0x02;
+export const MESSAGE_TYPE_KEEP_ALIVE = 0x03;
+// Seeker size: 1 byte length prefix + 32 bytes hash + 1 byte key index
+const SEEKER_SIZE = 34;
+/**
+ * Serialize a keep-alive message
+ * Keep-alive messages are used to maintain session activity
+ */
+export function serializeKeepAliveMessage() {
+    return new Uint8Array([MESSAGE_TYPE_KEEP_ALIVE]);
+}
+/**
+ * Serialize a regular text message
+ *
+ * Format: [type: 1 byte][content: variable]
+ *
+ * @param content - The message content string
+ * @returns Serialized message bytes
+ */
+export function serializeRegularMessage(content) {
+    const contentBytes = strToBytes(content);
+    const result = new Uint8Array(1 + contentBytes.length);
+    result[0] = MESSAGE_TYPE_REGULAR;
+    result.set(contentBytes, 1);
+    return result;
+}
+/**
+ * Serialize a reply message
+ *
+ * Format: [type: 1 byte][originalContentLen: 4 bytes][originalContent][seeker: 34 bytes][newContent]
+ *
+ * @param newContent - The reply content
+ * @param originalContent - The content being replied to
+ * @param originalSeeker - The seeker of the original message
+ * @returns Serialized reply message bytes
+ */
+export function serializeReplyMessage(newContent, originalContent, originalSeeker) {
+    const newContentBytes = strToBytes(newContent);
+    const originalContentBytes = strToBytes(originalContent);
+    const originalContentLenBytes = U32.toBytes(BigInt(originalContentBytes.length));
+    // Calculate total size
+    const totalSize = 1 + // type
+        originalContentLenBytes.length + // length prefix (4 bytes)
+        originalContentBytes.length + // original content
+        SEEKER_SIZE + // seeker
+        newContentBytes.length; // new content
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    // Type byte
+    result[offset++] = MESSAGE_TYPE_REPLY;
+    // Original content length (4 bytes)
+    result.set(originalContentLenBytes, offset);
+    offset += originalContentLenBytes.length;
+    // Original content
+    result.set(originalContentBytes, offset);
+    offset += originalContentBytes.length;
+    // Seeker (34 bytes)
+    result.set(originalSeeker, offset);
+    offset += SEEKER_SIZE;
+    // New content
+    result.set(newContentBytes, offset);
+    return result;
+}
+/**
+ * Serialize a forward message
+ *
+ * Format: [type: 1 byte][forwardContentLen: 4 bytes][forwardContent][seeker: 34 bytes][newContent]
+ *
+ * @param forwardContent - The content being forwarded
+ * @param newContent - Optional new content to add (empty string if none)
+ * @param originalSeeker - The seeker of the original message
+ * @returns Serialized forward message bytes
+ */
+export function serializeForwardMessage(forwardContent, newContent, originalSeeker) {
+    const newContentBytes = strToBytes(newContent);
+    const forwardContentBytes = strToBytes(forwardContent);
+    const forwardContentLenBytes = U32.toBytes(BigInt(forwardContentBytes.length));
+    // Calculate total size
+    const totalSize = 1 + // type
+        forwardContentLenBytes.length + // length prefix (4 bytes)
+        forwardContentBytes.length + // forward content
+        SEEKER_SIZE + // seeker
+        newContentBytes.length; // new content
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    // Type byte
+    result[offset++] = MESSAGE_TYPE_FORWARD;
+    // Forward content length (4 bytes)
+    result.set(forwardContentLenBytes, offset);
+    offset += forwardContentLenBytes.length;
+    // Forward content
+    result.set(forwardContentBytes, offset);
+    offset += forwardContentBytes.length;
+    // Seeker (34 bytes)
+    result.set(originalSeeker, offset);
+    offset += SEEKER_SIZE;
+    // New content
+    result.set(newContentBytes, offset);
+    return result;
+}
+/**
+ * Deserialize a message from bytes
+ *
+ * @param buffer - The serialized message bytes
+ * @returns Deserialized message object
+ * @throws Error if message format is invalid
+ */
+export function deserializeMessage(buffer) {
+    if (buffer.length < 1) {
+        throw new Error('Empty message buffer');
+    }
+    const messageType = buffer[0];
+    switch (messageType) {
+        case MESSAGE_TYPE_KEEP_ALIVE:
+            return {
+                content: '',
+                type: MessageType.KEEP_ALIVE,
+            };
+        case MESSAGE_TYPE_REGULAR:
+            return {
+                content: bytesToStr(buffer.slice(1)),
+                type: MessageType.TEXT,
+            };
+        case MESSAGE_TYPE_REPLY: {
+            // Format: [type: 1][originalContentLen: 4][originalContent][seeker: 34][newContent]
+            let offset = 1;
+            // Read original content length (4 bytes)
+            const originalContentLen = Number(U32.fromBytes(buffer.slice(offset, offset + 4)));
+            offset += 4;
+            // Read original content
+            const originalContent = bytesToStr(buffer.slice(offset, offset + originalContentLen));
+            offset += originalContentLen;
+            // Read seeker (34 bytes)
+            const originalSeeker = buffer.slice(offset, offset + SEEKER_SIZE);
+            offset += SEEKER_SIZE;
+            // Read new content (rest of buffer)
+            const content = bytesToStr(buffer.slice(offset));
+            return {
+                content,
+                replyTo: {
+                    originalContent,
+                    originalSeeker,
+                },
+                type: MessageType.TEXT,
+            };
+        }
+        case MESSAGE_TYPE_FORWARD: {
+            // Format: [type: 1][forwardContentLen: 4][forwardContent][seeker: 34][newContent]
+            let offset = 1;
+            // Read forward content length (4 bytes)
+            const forwardContentLen = Number(U32.fromBytes(buffer.slice(offset, offset + 4)));
+            offset += 4;
+            // Read forward content
+            const originalContent = bytesToStr(buffer.slice(offset, offset + forwardContentLen));
+            offset += forwardContentLen;
+            // Read seeker (34 bytes)
+            const originalSeeker = buffer.slice(offset, offset + SEEKER_SIZE);
+            offset += SEEKER_SIZE;
+            // Read new content (rest of buffer)
+            const content = bytesToStr(buffer.slice(offset));
+            return {
+                content,
+                forwardOf: {
+                    originalContent,
+                    originalSeeker,
+                },
+                type: MessageType.TEXT,
+            };
+        }
+        default:
+            throw new Error(`Unknown message type: ${messageType}`);
+    }
+}

package/dist/utils/queue.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Promise Queue
+ *
+ * Ensures async operations are executed sequentially.
+ * Used to serialize session manager operations per contact.
+ */
+/**
+ * A simple promise queue that executes tasks sequentially.
+ * Tasks are processed in FIFO order.
+ */
+export declare class PromiseQueue {
+    private queue;
+    private processing;
+    /**
+     * Add a task to the queue. Returns a promise that resolves
+     * when the task completes.
+     */
+    enqueue<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Process the next task in the queue.
+     */
+    private processNext;
+    /**
+     * Check if the queue is currently processing.
+     */
+    get isProcessing(): boolean;
+    /**
+     * Get the number of pending tasks.
+     */
+    get pendingCount(): number;
+}
+/**
+ * Manages multiple queues keyed by string (e.g., contact ID).
+ * Creates queues lazily on first use.
+ */
+export declare class QueueManager {
+    private queues;
+    /**
+     * Get or create a queue for the given key.
+     */
+    getQueue(key: string): PromiseQueue;
+    /**
+     * Enqueue a task for a specific key.
+     */
+    enqueue<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear all queues.
+     */
+    clear(): void;
+}

package/dist/utils/queue.js

@@ -0,0 +1,110 @@
+/**
+ * Promise Queue
+ *
+ * Ensures async operations are executed sequentially.
+ * Used to serialize session manager operations per contact.
+ */
+/**
+ * A simple promise queue that executes tasks sequentially.
+ * Tasks are processed in FIFO order.
+ */
+export class PromiseQueue {
+    constructor() {
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "processing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+    }
+    /**
+     * Add a task to the queue. Returns a promise that resolves
+     * when the task completes.
+     */
+    enqueue(fn) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                fn: fn,
+                resolve: resolve,
+                reject,
+            });
+            this.processNext();
+        });
+    }
+    /**
+     * Process the next task in the queue.
+     */
+    async processNext() {
+        if (this.processing || this.queue.length === 0) {
+            return;
+        }
+        this.processing = true;
+        const task = this.queue.shift();
+        try {
+            const result = await task.fn();
+            task.resolve(result);
+        }
+        catch (error) {
+            task.reject(error);
+        }
+        finally {
+            this.processing = false;
+            this.processNext();
+        }
+    }
+    /**
+     * Check if the queue is currently processing.
+     */
+    get isProcessing() {
+        return this.processing;
+    }
+    /**
+     * Get the number of pending tasks.
+     */
+    get pendingCount() {
+        return this.queue.length;
+    }
+}
+/**
+ * Manages multiple queues keyed by string (e.g., contact ID).
+ * Creates queues lazily on first use.
+ */
+export class QueueManager {
+    constructor() {
+        Object.defineProperty(this, "queues", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Get or create a queue for the given key.
+     */
+    getQueue(key) {
+        let queue = this.queues.get(key);
+        if (!queue) {
+            queue = new PromiseQueue();
+            this.queues.set(key, queue);
+        }
+        return queue;
+    }
+    /**
+     * Enqueue a task for a specific key.
+     */
+    enqueue(key, fn) {
+        return this.getQueue(key).enqueue(fn);
+    }
+    /**
+     * Clear all queues.
+     */
+    clear() {
+        this.queues.clear();
+    }
+}

package/dist/utils/type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Common type utilities for the SDK
+ */
+export type Result<T, E = Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};

package/dist/utils/type.js

@@ -0,0 +1,4 @@
+/**
+ * Common type utilities for the SDK
+ */
+export {};

package/dist/utils/userId.d.ts

@@ -0,0 +1,40 @@
+/**
+ * User ID encoding/decoding utilities using Bech32 format
+ * Format: gossip1<encoded-32-bytes>
+ *
+ * Uses @scure/base for reliable, battle-tested Bech32 encoding
+ */
+/**
+ * Encode a 32-byte user ID to Bech32 format with "gossip" prefix
+ * @param userId - 32-byte user ID as Uint8Array
+ * @returns Bech32-encoded string (e.g., "gossip1qpzry9x8gf2tvdw0s3jn54khce6mua7l...")
+ * @throws Error if userId is not exactly 32 bytes
+ */
+export declare function encodeUserId(userId: Uint8Array): string;
+/**
+ * Decode a Bech32-encoded user ID back to 32 bytes
+ * @param encoded - Bech32-encoded string (e.g., "gossip1qpzry9x8gf2tvdw0s3jn54khce6mua7l...")
+ * @returns 32-byte user ID as Uint8Array
+ * @throws Error if the format is invalid, checksum fails, or decoded length is not 32 bytes
+ */
+export declare function decodeUserId(encoded: string): Uint8Array;
+/**
+ * Validate a Bech32-encoded user ID string
+ * @param encoded - Bech32-encoded string to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidUserId(encoded: string): boolean;
+/**
+ * Format a user ID for display (shortened version)
+ * @param userId - Bech32-encoded user ID string
+ * @param prefixChars - Number of characters to show after prefix (default: 8)
+ * @param suffixChars - Number of characters to show at end (default: 6)
+ * @returns Formatted string (e.g., "gossip1qpzry9x8...mua7l")
+ */
+export declare function formatUserId(userId: string, prefixChars?: number, suffixChars?: number): string;
+/**
+ * Generates a random 32-byte user ID
+ * @param password - Optional password
+ * @returns gossip Bech32 string representing a 32-byte user ID
+ */
+export declare function generate(password?: string): Promise<string>;

package/dist/utils/userId.js

@@ -0,0 +1,90 @@
+/**
+ * User ID encoding/decoding utilities using Bech32 format
+ * Format: gossip1<encoded-32-bytes>
+ *
+ * Uses @scure/base for reliable, battle-tested Bech32 encoding
+ */
+import { bech32 } from '@scure/base';
+import { generateUserKeys } from '../wasm';
+const GOSSIP_PREFIX = 'gossip';
+const USER_ID_BYTE_LENGTH = 32;
+/**
+ * Encode a 32-byte user ID to Bech32 format with "gossip" prefix
+ * @param userId - 32-byte user ID as Uint8Array
+ * @returns Bech32-encoded string (e.g., "gossip1qpzry9x8gf2tvdw0s3jn54khce6mua7l...")
+ * @throws Error if userId is not exactly 32 bytes
+ */
+export function encodeUserId(userId) {
+    if (userId.length !== USER_ID_BYTE_LENGTH) {
+        throw new Error(`User ID must be exactly ${USER_ID_BYTE_LENGTH} bytes, got ${userId.length}`);
+    }
+    return bech32.encode(GOSSIP_PREFIX, bech32.toWords(userId));
+}
+/**
+ * Decode a Bech32-encoded user ID back to 32 bytes
+ * @param encoded - Bech32-encoded string (e.g., "gossip1qpzry9x8gf2tvdw0s3jn54khce6mua7l...")
+ * @returns 32-byte user ID as Uint8Array
+ * @throws Error if the format is invalid, checksum fails, or decoded length is not 32 bytes
+ */
+export function decodeUserId(encoded) {
+    // Type assertion needed as bech32.decode expects a template literal type
+    const { prefix, words } = bech32.decode(encoded, 90);
+    // Verify prefix
+    if (prefix !== GOSSIP_PREFIX) {
+        throw new Error(`Invalid prefix: expected "${GOSSIP_PREFIX}", got "${prefix}"`);
+    }
+    // Convert from 5-bit words back to bytes
+    const decoded = bech32.fromWords(words);
+    // Verify length
+    if (decoded.length !== USER_ID_BYTE_LENGTH) {
+        throw new Error(`Decoded user ID must be ${USER_ID_BYTE_LENGTH} bytes, got ${decoded.length}`);
+    }
+    return new Uint8Array(decoded);
+}
+/**
+ * Validate a Bech32-encoded user ID string
+ * @param encoded - Bech32-encoded string to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidUserId(encoded) {
+    try {
+        decodeUserId(encoded);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a user ID for display (shortened version)
+ * @param userId - Bech32-encoded user ID string
+ * @param prefixChars - Number of characters to show after prefix (default: 8)
+ * @param suffixChars - Number of characters to show at end (default: 6)
+ * @returns Formatted string (e.g., "gossip1qpzry9x8...mua7l")
+ */
+export function formatUserId(userId, prefixChars = 8, suffixChars = 6) {
+    if (!userId)
+        return '';
+    // Find separator position
+    const sepPos = userId.indexOf('1');
+    if (sepPos === -1)
+        return userId;
+    const prefix = userId.substring(0, sepPos + 1); // "gossip1"
+    const data = userId.substring(sepPos + 1); // rest of the string
+    if (data.length <= prefixChars + suffixChars) {
+        return userId; // Too short to format
+    }
+    const start = data.slice(0, prefixChars);
+    const end = data.slice(-suffixChars);
+    return `${prefix}${start}...${end}`;
+}
+/**
+ * Generates a random 32-byte user ID
+ * @param password - Optional password
+ * @returns gossip Bech32 string representing a 32-byte user ID
+ */
+export async function generate(password) {
+    const identity = await generateUserKeys(password || '');
+    const userId = identity.public_keys().derive_id();
+    return encodeUserId(userId);
+}