@massalabs/gossip-sdk 0.0.1

package/src/utils/logs.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 {
+  private module: string;
+  private context: string;
+
+  constructor(module: string, context: string = '') {
+    this.module = module;
+    this.context = context;
+  }
+
+  private getSource(): string {
+    return this.context ? `${this.module}:${this.context}` : this.module;
+  }
+
+  private formatMainMessage(message: string): string {
+    const source = this.getSource();
+    return `[${source}] ${message}`;
+  }
+
+  info(message: string, extra?: unknown): void {
+    const main = this.formatMainMessage(message);
+    if (extra !== undefined) {
+      console.log(main, extra);
+    } else {
+      console.log(main);
+    }
+  }
+
+  error(messageOrError: string | Error | unknown, extra?: unknown): void {
+    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: string, extra?: unknown): void {
+    const main = this.formatMainMessage(message);
+    if (extra !== undefined) {
+      console.debug(main, extra);
+    } else {
+      console.debug(main);
+    }
+  }
+
+  warn(message: string, extra?: unknown): void {
+    const main = this.formatMainMessage(message);
+    if (extra !== undefined) {
+      console.warn(main, extra);
+    } else {
+      console.warn(main);
+    }
+  }
+
+  // Chainable context builder
+  withContext(newContext: string): Logger {
+    const fullContext = this.context
+      ? `${this.context}:${newContext}`
+      : newContext;
+    return new Logger(this.module, fullContext);
+  }
+
+  forMethod(methodName: string): Logger {
+    return this.withContext(methodName);
+  }
+}

package/src/utils/messageSerialization.ts

@@ -0,0 +1,257 @@
+/**
+ * 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;
+
+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 function serializeKeepAliveMessage(): Uint8Array {
+  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: string): Uint8Array {
+  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: string,
+  originalContent: string,
+  originalSeeker: Uint8Array
+): Uint8Array {
+  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: string,
+  newContent: string,
+  originalSeeker: Uint8Array
+): Uint8Array {
+  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: Uint8Array): DeserializedMessage {
+  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/src/utils/queue.ts

@@ -0,0 +1,106 @@
+/**
+ * Promise Queue
+ *
+ * Ensures async operations are executed sequentially.
+ * Used to serialize session manager operations per contact.
+ */
+
+type QueuedTask<T> = {
+  fn: () => Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+};
+
+/**
+ * A simple promise queue that executes tasks sequentially.
+ * Tasks are processed in FIFO order.
+ */
+export class PromiseQueue {
+  private queue: QueuedTask<unknown>[] = [];
+  private processing = false;
+
+  /**
+   * Add a task to the queue. Returns a promise that resolves
+   * when the task completes.
+   */
+  enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.queue.push({
+        fn: fn as () => Promise<unknown>,
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+      this.processNext();
+    });
+  }
+
+  /**
+   * Process the next task in the queue.
+   */
+  private async processNext(): Promise<void> {
+    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(): boolean {
+    return this.processing;
+  }
+
+  /**
+   * Get the number of pending tasks.
+   */
+  get pendingCount(): number {
+    return this.queue.length;
+  }
+}
+
+/**
+ * Manages multiple queues keyed by string (e.g., contact ID).
+ * Creates queues lazily on first use.
+ */
+export class QueueManager {
+  private queues = new Map<string, PromiseQueue>();
+
+  /**
+   * Get or create a queue for the given key.
+   */
+  getQueue(key: string): PromiseQueue {
+    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<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    return this.getQueue(key).enqueue(fn);
+  }
+
+  /**
+   * Clear all queues.
+   */
+  clear(): void {
+    this.queues.clear();
+  }
+}

package/src/utils/type.ts

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

package/src/utils/userId.ts

@@ -0,0 +1,114 @@
+/**
+ * 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: Uint8Array): string {
+  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: string): Uint8Array {
+  // Type assertion needed as bech32.decode expects a template literal type
+  const { prefix, words } = bech32.decode(encoded as `${string}1${string}`, 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: string): boolean {
+  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: string,
+  prefixChars: number = 8,
+  suffixChars: number = 6
+): string {
+  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?: string): Promise<string> {
+  const identity = await generateUserKeys(password || '');
+  const userId = identity.public_keys().derive_id();
+  return encodeUserId(userId);
+}

package/src/utils/validation.ts

@@ -0,0 +1,144 @@
+/**
+ * Validation Utilities
+ *
+ * Functions for validating user input like usernames, passwords, and user IDs.
+ */
+
+import { type UserProfile, type GossipDatabase } from '../db';
+import { isValidUserId } from './userId';
+
+export type ValidationResult =
+  | { valid: true; error?: never }
+  | { valid: false; error: string };
+
+/**
+ * Validate a password meets requirements
+ *
+ * @param value - The password to validate
+ * @returns Validation result
+ */
+export function validatePassword(value: string): ValidationResult {
+  if (!value || value.trim().length === 0) {
+    return { valid: false, error: 'Password is required' };
+  }
+
+  if (value.length < 8) {
+    return {
+      valid: false,
+      error: 'Password must be at least 8 characters long',
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate a username format (without checking availability)
+ *
+ * @param value - The username to validate
+ * @returns Validation result
+ */
+export function validateUsernameFormat(value: string): ValidationResult {
+  const trimmed = value.trim();
+
+  if (!trimmed) {
+    return { valid: false, error: 'Username is required' };
+  }
+
+  // Disallow any whitespace inside the username (single token only)
+  if (/\s/.test(trimmed)) {
+    return {
+      valid: false,
+      error: 'Username cannot contain spaces',
+    };
+  }
+
+  if (trimmed.length < 3) {
+    return {
+      valid: false,
+      error: 'Username must be at least 3 characters long',
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate a username is available (not already in use)
+ *
+ * @param value - The username to check
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export async function validateUsernameAvailability(
+  value: string,
+  db: GossipDatabase
+): Promise<ValidationResult> {
+  try {
+    if (!db.isOpen()) {
+      await db.open();
+    }
+
+    const existingProfile = await db.userProfile
+      .filter(
+        (profile: UserProfile) =>
+          profile.username.trim().toLowerCase() === value.trim().toLowerCase()
+      )
+      .first();
+
+    if (existingProfile) {
+      return {
+        valid: false,
+        error: 'This username is already in use. Please choose another.',
+      };
+    }
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error:
+        error instanceof Error
+          ? error.message
+          : 'Unable to verify username availability. Please try again.',
+    };
+  }
+}
+
+/**
+ * Validate a username format and availability
+ *
+ * @param value - The username to validate
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export async function validateUsernameFormatAndAvailability(
+  value: string,
+  db: GossipDatabase
+): Promise<ValidationResult> {
+  const result = validateUsernameFormat(value);
+  if (!result.valid) {
+    return result;
+  }
+
+  return await validateUsernameAvailability(value, db);
+}
+
+/**
+ * Validate a user ID format (Bech32 gossip1... format)
+ *
+ * @param value - The user ID to validate
+ * @returns Validation result
+ */
+export function validateUserIdFormat(value: string): ValidationResult {
+  const userId = value.trim();
+
+  if (!isValidUserId(userId)) {
+    return {
+      valid: false,
+      error: 'Invalid format — must be a valid user ID',
+    };
+  }
+
+  return { valid: true };
+}