@quilibrium/quorum-shared 2.1.0-1

package/src/utils/encoding.ts

@@ -0,0 +1,106 @@
+/**
+ * Encoding utilities for hex and base64 conversions
+ *
+ * These are platform-agnostic utilities for converting between
+ * byte arrays and string representations.
+ */
+
+/**
+ * Convert a hex string to a byte array
+ * @param hex - Hexadecimal string (with or without 0x prefix)
+ * @returns Array of bytes
+ */
+export function hexToBytes(hex: string): number[] {
+  // Remove 0x prefix if present
+  const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const bytes: number[] = [];
+  for (let i = 0; i < cleanHex.length; i += 2) {
+    bytes.push(parseInt(cleanHex.substr(i, 2), 16));
+  }
+  return bytes;
+}
+
+/**
+ * Convert a byte array to a hex string
+ * @param bytes - Array of bytes (number[] or Uint8Array)
+ * @returns Hexadecimal string (lowercase, no prefix)
+ */
+export function bytesToHex(bytes: number[] | Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Convert a base64 string to a Uint8Array
+ * @param base64 - Base64-encoded string
+ * @returns Uint8Array of bytes
+ */
+export function base64ToBytes(base64: string): Uint8Array {
+  // Handle both browser and Node.js environments
+  if (typeof atob === 'function') {
+    // Browser environment
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  } else {
+    // Node.js environment
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+}
+
+/**
+ * Convert a byte array to a base64 string
+ * @param bytes - Array of bytes (number[] or Uint8Array)
+ * @returns Base64-encoded string
+ */
+export function bytesToBase64(bytes: number[] | Uint8Array): string {
+  // Handle both browser and Node.js environments
+  if (typeof btoa === 'function') {
+    // Browser environment
+    const binaryString = Array.from(bytes)
+      .map((b) => String.fromCharCode(b))
+      .join('');
+    return btoa(binaryString);
+  } else {
+    // Node.js environment
+    return Buffer.from(bytes).toString('base64');
+  }
+}
+
+/**
+ * Convert a UTF-8 string to a byte array
+ * @param str - UTF-8 string
+ * @returns Array of bytes
+ */
+export function stringToBytes(str: string): number[] {
+  const encoder = new TextEncoder();
+  return Array.from(encoder.encode(str));
+}
+
+/**
+ * Convert a byte array to a UTF-8 string
+ * @param bytes - Array of bytes (number[] or Uint8Array)
+ * @returns UTF-8 string
+ */
+export function bytesToString(bytes: number[] | Uint8Array): string {
+  const decoder = new TextDecoder();
+  return decoder.decode(new Uint8Array(bytes));
+}
+
+/**
+ * Convert a number to an 8-byte big-endian array (int64)
+ * Used for timestamp serialization in signatures
+ *
+ * @param num - The number to convert (must be within safe integer range)
+ * @returns 8-byte Uint8Array in big-endian format
+ */
+export function int64ToBytes(num: number): Uint8Array {
+  const arr = new Uint8Array(8);
+  const view = new DataView(arr.buffer);
+  view.setBigInt64(0, BigInt(num), false);
+  return arr;
+}

package/src/utils/formatting.ts

@@ -0,0 +1,139 @@
+/**
+ * Date and text formatting utilities
+ */
+
+/**
+ * Format timestamp to time string (e.g., "2:30 PM")
+ */
+export function formatTime(timestamp: number): string {
+  const date = new Date(timestamp);
+  return date.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+}
+
+/**
+ * Format timestamp to date string (e.g., "Dec 24, 2025")
+ */
+export function formatDate(timestamp: number): string {
+  const date = new Date(timestamp);
+  return date.toLocaleDateString([], {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
+/**
+ * Format timestamp to full datetime string (e.g., "Dec 24, 2025 at 2:30 PM")
+ */
+export function formatDateTime(timestamp: number): string {
+  const date = new Date(timestamp);
+  return date.toLocaleString([], {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+
+/**
+ * Format timestamp to relative time (e.g., "5 minutes ago", "Yesterday")
+ */
+export function formatRelativeTime(timestamp: number): string {
+  const now = Date.now();
+  const diff = now - timestamp;
+
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (seconds < 60) {
+    return 'Just now';
+  }
+  if (minutes < 60) {
+    return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  }
+  if (hours < 24) {
+    return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  }
+  if (days === 1) {
+    return 'Yesterday';
+  }
+  if (days < 7) {
+    return `${days} days ago`;
+  }
+
+  return formatDate(timestamp);
+}
+
+/**
+ * Format message date header (e.g., "Today", "Yesterday", "December 24, 2025")
+ */
+export function formatMessageDate(timestamp: number): string {
+  const date = new Date(timestamp);
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+
+  if (isSameDay(date, today)) {
+    return 'Today';
+  }
+  if (isSameDay(date, yesterday)) {
+    return 'Yesterday';
+  }
+
+  return date.toLocaleDateString([], {
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+    year: date.getFullYear() !== today.getFullYear() ? 'numeric' : undefined,
+  });
+}
+
+/**
+ * Check if two dates are the same day
+ */
+export function isSameDay(d1: Date, d2: Date): boolean {
+  return (
+    d1.getFullYear() === d2.getFullYear() &&
+    d1.getMonth() === d2.getMonth() &&
+    d1.getDate() === d2.getDate()
+  );
+}
+
+/**
+ * Truncate text to a maximum length with ellipsis
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.slice(0, maxLength - 1) + '\u2026';
+}
+
+/**
+ * Format file size (e.g., "1.5 MB")
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+
+/**
+ * Format member count (e.g., "1.2K members")
+ */
+export function formatMemberCount(count: number): string {
+  if (count < 1000) {
+    return `${count} member${count === 1 ? '' : 's'}`;
+  }
+  if (count < 1000000) {
+    return `${(count / 1000).toFixed(1)}K members`;
+  }
+  return `${(count / 1000000).toFixed(1)}M members`;
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility exports
+ */
+
+export * from './validation';
+export * from './mentions';
+export * from './formatting';
+export * from './encoding';
+export * from './logger';

package/src/utils/logger.ts

@@ -0,0 +1,141 @@
+/**
+ * Logger utility that respects build environment
+ *
+ * In development: logs to console
+ * In production: no-ops for performance
+ *
+ * Usage:
+ *   import { logger } from '@quorum/shared';
+ *   logger.log('[MyModule]', 'some message', data);
+ *   logger.warn('[MyModule]', 'warning message');
+ *   logger.error('[MyModule]', 'error message', error);
+ */
+
+type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+
+interface LoggerConfig {
+  enabled: boolean;
+  minLevel: LogLevel;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  log: 1,
+  info: 2,
+  warn: 3,
+  error: 4,
+};
+
+// Default config - can be overridden by calling logger.configure()
+let config: LoggerConfig = {
+  enabled: true, // Will be set based on environment
+  minLevel: 'log',
+};
+
+// Detect environment
+function detectEnvironment(): boolean {
+  // React Native / Expo
+  if (typeof __DEV__ !== 'undefined') {
+    return __DEV__;
+  }
+  // Node.js / Electron
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NODE_ENV !== 'production';
+  }
+  // Browser
+  if (typeof window !== 'undefined') {
+    return window.location?.hostname === 'localhost';
+  }
+  // Default to enabled
+  return true;
+}
+
+// Initialize based on environment
+config.enabled = detectEnvironment();
+
+// No-op function for production
+const noop = (): void => {};
+
+function shouldLog(level: LogLevel): boolean {
+  if (!config.enabled) return false;
+  return LOG_LEVELS[level] >= LOG_LEVELS[config.minLevel];
+}
+
+function createLogMethod(level: LogLevel): (...args: unknown[]) => void {
+  return (...args: unknown[]) => {
+    if (shouldLog(level)) {
+      console[level](...args);
+    }
+  };
+}
+
+export const logger = {
+  /**
+   * Configure the logger
+   */
+  configure(newConfig: Partial<LoggerConfig>): void {
+    config = { ...config, ...newConfig };
+  },
+
+  /**
+   * Check if logging is enabled
+   */
+  isEnabled(): boolean {
+    return config.enabled;
+  },
+
+  /**
+   * Enable logging (useful for debugging production issues)
+   */
+  enable(): void {
+    config.enabled = true;
+  },
+
+  /**
+   * Disable logging
+   */
+  disable(): void {
+    config.enabled = false;
+  },
+
+  /**
+   * Log at debug level
+   */
+  debug: createLogMethod('debug'),
+
+  /**
+   * Log at default level
+   */
+  log: createLogMethod('log'),
+
+  /**
+   * Log at info level
+   */
+  info: createLogMethod('info'),
+
+  /**
+   * Log at warn level
+   */
+  warn: createLogMethod('warn'),
+
+  /**
+   * Log at error level (always logs unless explicitly disabled)
+   */
+  error: createLogMethod('error'),
+
+  /**
+   * Create a scoped logger with a prefix
+   */
+  scope(prefix: string) {
+    return {
+      debug: (...args: unknown[]) => logger.debug(prefix, ...args),
+      log: (...args: unknown[]) => logger.log(prefix, ...args),
+      info: (...args: unknown[]) => logger.info(prefix, ...args),
+      warn: (...args: unknown[]) => logger.warn(prefix, ...args),
+      error: (...args: unknown[]) => logger.error(prefix, ...args),
+    };
+  },
+};
+
+// Type declaration for React Native's __DEV__ global
+declare const __DEV__: boolean | undefined;

package/src/utils/mentions.ts

@@ -0,0 +1,135 @@
+/**
+ * Mention parsing utilities
+ */
+
+import type { Mentions } from '../types';
+
+/** Mention patterns */
+export const MENTION_PATTERNS = {
+  user: /<@([a-zA-Z0-9]+)>/g,
+  role: /<@&([a-zA-Z0-9]+)>/g,
+  channel: /<#([a-zA-Z0-9]+)>/g,
+  everyone: /@everyone/g,
+  here: /@here/g,
+};
+
+/** Parsed mention */
+export interface ParsedMention {
+  type: 'user' | 'role' | 'channel' | 'everyone' | 'here';
+  id?: string;
+  raw: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * Parse mentions from message text
+ */
+export function parseMentions(text: string): ParsedMention[] {
+  const mentions: ParsedMention[] = [];
+
+  // Parse user mentions
+  let match: RegExpExecArray | null;
+  const userRegex = new RegExp(MENTION_PATTERNS.user.source, 'g');
+  while ((match = userRegex.exec(text)) !== null) {
+    mentions.push({
+      type: 'user',
+      id: match[1],
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  // Parse role mentions
+  const roleRegex = new RegExp(MENTION_PATTERNS.role.source, 'g');
+  while ((match = roleRegex.exec(text)) !== null) {
+    mentions.push({
+      type: 'role',
+      id: match[1],
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  // Parse channel mentions
+  const channelRegex = new RegExp(MENTION_PATTERNS.channel.source, 'g');
+  while ((match = channelRegex.exec(text)) !== null) {
+    mentions.push({
+      type: 'channel',
+      id: match[1],
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  // Parse @everyone
+  const everyoneRegex = new RegExp(MENTION_PATTERNS.everyone.source, 'g');
+  while ((match = everyoneRegex.exec(text)) !== null) {
+    mentions.push({
+      type: 'everyone',
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  // Parse @here
+  const hereRegex = new RegExp(MENTION_PATTERNS.here.source, 'g');
+  while ((match = hereRegex.exec(text)) !== null) {
+    mentions.push({
+      type: 'here',
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  // Sort by position
+  return mentions.sort((a, b) => a.start - b.start);
+}
+
+/**
+ * Extract Mentions object from parsed mentions
+ */
+export function extractMentions(text: string): Mentions {
+  const parsed = parseMentions(text);
+
+  const memberIds = parsed
+    .filter((m) => m.type === 'user' && m.id)
+    .map((m) => m.id!);
+
+  const roleIds = parsed
+    .filter((m) => m.type === 'role' && m.id)
+    .map((m) => m.id!);
+
+  const channelIds = parsed
+    .filter((m) => m.type === 'channel' && m.id)
+    .map((m) => m.id!);
+
+  const everyone = parsed.some((m) => m.type === 'everyone' || m.type === 'here');
+
+  return {
+    memberIds: [...new Set(memberIds)],
+    roleIds: [...new Set(roleIds)],
+    channelIds: [...new Set(channelIds)],
+    everyone,
+    totalMentionCount: memberIds.length + roleIds.length + channelIds.length,
+  };
+}
+
+/**
+ * Format mention for display
+ */
+export function formatMention(type: 'user' | 'role' | 'channel', id: string): string {
+  switch (type) {
+    case 'user':
+      return `<@${id}>`;
+    case 'role':
+      return `<@&${id}>`;
+    case 'channel':
+      return `<#${id}>`;
+  }
+}

package/src/utils/validation.ts

@@ -0,0 +1,84 @@
+/**
+ * Message validation utilities
+ */
+
+import type { Message, PostMessage } from '../types';
+
+/** Maximum message length */
+export const MAX_MESSAGE_LENGTH = 4000;
+
+/** Maximum number of mentions per message */
+export const MAX_MENTIONS = 50;
+
+/** Validation result */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate message content before sending
+ */
+export function validateMessageContent(content: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!content || content.trim().length === 0) {
+    errors.push('Message cannot be empty');
+  }
+
+  if (content.length > MAX_MESSAGE_LENGTH) {
+    errors.push(`Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validate a message object
+ */
+export function validateMessage(message: Partial<Message>): ValidationResult {
+  const errors: string[] = [];
+
+  if (!message.messageId) {
+    errors.push('Message ID is required');
+  }
+
+  if (!message.channelId) {
+    errors.push('Channel ID is required');
+  }
+
+  if (!message.spaceId) {
+    errors.push('Space ID is required');
+  }
+
+  if (!message.content) {
+    errors.push('Message content is required');
+  }
+
+  if (message.content?.type === 'post') {
+    const postContent = message.content as PostMessage;
+    const text = Array.isArray(postContent.text)
+      ? postContent.text.join('')
+      : postContent.text;
+
+    if (text.length > MAX_MESSAGE_LENGTH) {
+      errors.push(`Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Sanitize message content for display
+ */
+export function sanitizeContent(content: string): string {
+  // Remove null bytes and control characters (except newlines/tabs)
+  return content.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}