@minicode-dev/chat 0.0.0-stage → 0.1.1

package/index.d.ts

@@ -0,0 +1,470 @@
+// Hand-written public types for @minicode-dev/chat. Keep in sync with src/index.js.
+import type { ComponentType, Context, ReactNode } from 'react';
+import type { StoreApi } from 'zustand/vanilla';
+
+export const MINICODE_CHAT_VERSION: string;
+
+/* ------------------------------------------------------------------ */
+/* Transport                                                           */
+/* ------------------------------------------------------------------ */
+
+export type TransportStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
+
+export interface InboundFrame {
+  event?: string;
+  type?: string;
+  data?: any;
+  payload?: any;
+  [key: string]: any;
+}
+
+export interface ChatIdentity {
+  userId: string | null;
+  /** `${backend}:${userId}` */
+  scope: string;
+}
+
+export interface ChatTransport {
+  /** Opens the connection (the shared adapter delegates to the host). */
+  connect(): Promise<void>;
+  /** Voluntary close. The shared adapter never closes the host socket. */
+  close(code?: number): void;
+  /** Fire-and-forget. Returns false when the socket is not OPEN; never throws. */
+  send(action: string, payload?: object): boolean;
+  /** Adds `request_id`; resolves on CHAT_ACK, rejects on correlated ERROR, timeout or close. */
+  request(action: string, payload?: object, opts?: { timeoutMs?: number }): Promise<InboundFrame>;
+  /** The handler returns true when it consumed the frame. Returns an unsubscribe function. */
+  onEvent(handler: (frame: InboundFrame) => boolean | void): () => void;
+  getStatus(): TransportStatus;
+  onStatus(cb: (status: TransportStatus, prev: TransportStatus) => void): () => void;
+  /** Changes on every reconnection. */
+  getConnectionId(): string | null;
+  getIdentity(): ChatIdentity;
+}
+
+export interface ReconnectOptions {
+  max?: number;
+  baseMs?: number;
+  capMs?: number;
+}
+
+export interface StandaloneTransportOptions {
+  url: string | (() => string | Promise<string>);
+  getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+  tokenParam?: string;
+  reconnect?: ReconnectOptions;
+  isFatal?: (frame: InboundFrame) => boolean;
+  ping?: false | { action?: string; everyMs: number };
+  identity?: () => ChatIdentity;
+  WebSocketImpl?: typeof WebSocket;
+}
+
+export function createStandaloneTransport(opts: StandaloneTransportOptions): ChatTransport;
+export const TRANSPORT_STATUSES: readonly TransportStatus[];
+/** Validates (dev) that `obj` implements ChatTransport; throws listing missing members. */
+export function assertTransport(obj: unknown): ChatTransport;
+
+/* ------------------------------------------------------------------ */
+/* Connection store                                                    */
+/* ------------------------------------------------------------------ */
+
+export const chatConnectionStore: StoreApi<{ status: TransportStatus | string }>;
+export function setChatConnectionStatus(status: TransportStatus | string): void;
+export function useChatConnectionStatus(): TransportStatus | string;
+
+/* ------------------------------------------------------------------ */
+/* Config                                                              */
+/* ------------------------------------------------------------------ */
+
+export interface ChatUser {
+  id?: string | number;
+  user_id?: string | number;
+  name?: string;
+  [key: string]: any;
+}
+
+export interface ChatGamesFeatures {
+  connect4?: boolean;
+  battleship?: boolean;
+  battleshipPreview?: boolean;
+}
+
+export interface ChatFeatures {
+  reactions?: boolean;
+  editing?: boolean;
+  replies?: boolean;
+  files?: boolean;
+  voice?: boolean;
+  gifs?: boolean;
+  stickers?: boolean;
+  presence?: boolean;
+  groups?: boolean;
+  privateChats?: boolean;
+  games?: ChatGamesFeatures | false;
+  detach?: { path?: string; windowName?: string } | false;
+  install?: boolean;
+}
+
+export interface ChatCustomEmoji {
+  shortcode: string;
+  url?: string;
+  label?: string;
+  keywords?: string[];
+  shortcodes?: string[];
+  [key: string]: any;
+}
+
+export interface ChatStorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface ChatCallbacks {
+  onError?: (error: unknown) => void;
+  onOpenChange?: (open: boolean) => void;
+  onOpenConversation?: (conversation: any) => void;
+  onUnreadChange?: (total: number) => void;
+  onConnectionChange?: (status: TransportStatus) => void;
+}
+
+export interface ChatConfig {
+  websocket?: {
+    url?: string | (() => string | Promise<string>) | null;
+    reconnect?: ReconnectOptions;
+    ping?: false | { action?: string; everyMs: number };
+    legacyRoomIdRouting?: boolean;
+  };
+  auth?: {
+    getToken?: (() => string | null | undefined | Promise<string | null | undefined>) | null;
+    tokenParam?: string;
+  };
+  /** Used as the standalone transport identity provider. */
+  user?: (() => ChatIdentity) | ChatUser | null;
+  scope?: string | null;
+  features?: ChatFeatures | false;
+  theme?: {
+    mode?: 'auto' | 'light' | 'dark';
+    tokens?: Record<string, string>;
+    fontSize?: number;
+  };
+  media?: {
+    klipy?: false | { apiKey: string; locale?: string; categoriesLocale?: string };
+    emoji?: { custom?: ChatCustomEmoji[]; lazy?: boolean };
+    maxAttachmentBytes?: number;
+    trustedMediaHosts?: string[];
+  };
+  notifications?: {
+    desktop?: boolean;
+    previews?: boolean;
+    sound?: boolean;
+    appBadge?: boolean;
+  } | false;
+  assets?: { baseUrl?: string | null };
+  storage?: { prefix?: string; adapter?: ChatStorageAdapter };
+  locale?: string;
+  portalContainer?: HTMLElement | (() => HTMLElement | null) | null;
+  callbacks?: ChatCallbacks;
+  [key: string]: any;
+}
+
+/** Config after `normalizeConfig`: every section present (or `false`) and frozen. */
+export type NormalizedChatConfig = Readonly<ChatConfig> & {
+  readonly callbacks: Readonly<Required<ChatCallbacks>>;
+};
+
+export const DEFAULT_CONFIG: NormalizedChatConfig;
+export function normalizeConfig(config?: ChatConfig): NormalizedChatConfig;
+
+/* ------------------------------------------------------------------ */
+/* Chat domain store                                                   */
+/* ------------------------------------------------------------------ */
+
+/** Anything zustand-like: vanilla store or bound hook. */
+export interface StoreLike<T = any> {
+  getState(): T;
+  subscribe(listener: (state: T, prev: T) => void): () => void;
+  setState?: (partial: Partial<T> | ((state: T) => Partial<T>), replace?: boolean) => void;
+}
+
+export interface ChatState {
+  chatMessages: any[];
+  chatState: Record<string, any>;
+  onlineUsers: any[];
+  presenceStatus: string;
+  userSearchResults: any[];
+  userSearchQuery: string;
+  userSearchStatus: string;
+  privateRooms: Record<string, any>;
+  knownUsers: Record<string, any>;
+  myPresence: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface CreateChatStoreOptions {
+  transport: ChatTransport;
+  /** Defaults to a CHAT_MESSAGE request without attachments (hosts with file relay inject theirs). */
+  sendMessage?: (roomId: string, message: string, attachments?: any[]) => Promise<void>;
+  /** Every id form of the current user (id, user_id, sub). */
+  getOwnIds?: () => string[];
+  /** Desktop notification click (after selectChat). */
+  onOpenChat?: (room: string) => void;
+  maxMessages?: number;
+  games?: StoreLike;
+  unread?: StoreLike<{ counts?: Record<string, number>; [key: string]: any }>;
+  extras?: StoreLike;
+}
+
+export function createChatStore(options: CreateChatStoreOptions): StoreApi<ChatState>;
+
+/* ------------------------------------------------------------------ */
+/* Provider and hooks                                                  */
+/* ------------------------------------------------------------------ */
+
+export interface ChatStores {
+  unread?: StoreLike<{ counts?: Record<string, number>; [key: string]: any }>;
+  [key: string]: StoreLike | undefined;
+}
+
+export interface ChatProviderProps {
+  config?: ChatConfig;
+  /** Injected transport (e.g. LIRA adapter). Never closed by the provider. */
+  transport?: ChatTransport;
+  stores?: ChatStores;
+  /** Pre-built chat domain store; created internally when omitted. */
+  chatStore?: StoreApi<ChatState>;
+  children?: ReactNode;
+}
+
+export interface ChatContextValue {
+  config: NormalizedChatConfig;
+  transport: ChatTransport | null;
+  stores: ChatStores;
+  chatStore?: StoreApi<ChatState>;
+}
+
+export const LiraChatProvider: ComponentType<ChatProviderProps>;
+export const ChatContext: Context<ChatContextValue | null>;
+/** Throws when used outside LiraChatProvider. */
+export function useChatContext(): ChatContextValue;
+export function useChatConfig(): NormalizedChatConfig;
+export function useChatTransport(): ChatTransport | null;
+export function useChatConnection(): { status: TransportStatus; connectionId: string | null };
+export function useChatUnreadTotal(): number;
+
+/* ------------------------------------------------------------------ */
+/* Protocol helpers (frozen wire format)                               */
+/* ------------------------------------------------------------------ */
+
+export const EDIT_PREFIX: 'LIRA_EDIT_V1:';
+export const REACT_PREFIX: 'LIRA_REACT_V1:';
+export const STICKER_NAME_PREFIX: 'sticker:';
+
+export type MessageAction =
+  | { type: 'edit'; targetId: string; text: string }
+  | { type: 'react'; targetId: string; emoji: string; on: boolean };
+
+export function encodeEdit(args: { targetId: string | number; text: string }): string;
+export function encodeReaction(args: { targetId: string | number; emoji: string; on: boolean }): string;
+export function parseMessageAction(text: string): MessageAction | null;
+export function isMessageAction(text: unknown): boolean;
+export function isStickerAttachment(item: unknown): boolean;
+export function groupReactions(
+  byEmoji: Record<string, Array<string | number>> | null | undefined,
+  ownIds?: Array<string | number | null | undefined>,
+): Array<{ emoji: string; count: number; mine: boolean; userIds: Array<string | number> }>;
+
+/* ------------------------------------------------------------------ */
+/* Media / assets configuration                                        */
+/* ------------------------------------------------------------------ */
+
+export function configureKlipy(options?: { apiKey?: string; locale?: string; categoriesLocale?: string }): void;
+/** Base URL of the chat sounds (default `/sounds`). `null` restores the default. */
+export function setChatAssetsBaseUrl(url: string | null | undefined): void;
+export function getChatAssetsBaseUrl(): string;
+
+/* ------------------------------------------------------------------ */
+/* Connected placements                                                */
+/* ------------------------------------------------------------------ */
+
+export interface ChatWindowProps {
+  placement?: 'floating' | 'modal' | 'embedded';
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+  theme?: 'light' | 'dark' | 'auto' | 'black';
+  BattleshipPreviewComponent?: ComponentType<any>;
+}
+export interface ChatPageProps {
+  className?: string;
+}
+export interface ChatButtonProps {
+  className?: string;
+  label?: string;
+  onClick?: () => void;
+  pressed?: boolean;
+  badgeClassName?: string;
+  iconSize?: number;
+}
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ChatNotificationsProps {}
+
+export const ChatWindow: ComponentType<ChatWindowProps>;
+export const ChatPage: ComponentType<ChatPageProps>;
+export const ChatButton: ComponentType<ChatButtonProps>;
+export const ChatNotifications: ComponentType<ChatNotificationsProps>;
+
+/* ------------------------------------------------------------------ */
+/* UI primitives (presentational)                                      */
+/* ------------------------------------------------------------------ */
+
+export interface ChatWindowShellProps {
+  placement?: 'floating' | 'modal' | 'embedded' | 'page' | string;
+  BattleshipPreviewComponent?: ComponentType<any> | null;
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  isOpen?: boolean;
+  isMaximized?: boolean;
+  isMinimized?: boolean;
+  onClose?: () => void;
+  onMinimize?: () => void;
+  onToggleMaximize?: () => void;
+  rooms?: any[];
+  users?: any[];
+  messages?: any[];
+  currentUserId?: string | number | null;
+  currentUserIds?: Array<string | number>;
+  onSelectRoom?: (room: any) => void;
+  onSelectUser?: (user: any) => void;
+  [key: string]: any;
+}
+
+export interface MessageListProps {
+  messages?: any[];
+  currentUserId?: string | number | null;
+  onCopy?: (message: any) => void;
+  onReply?: (message: any) => void;
+  panelGameKey?: string | null;
+  onReact?: (message: any, emoji: string, on: boolean) => void;
+  onEditMessage?: (message: any) => void;
+  editingId?: string | null;
+}
+
+export interface MessageBubbleProps {
+  message: any;
+  isMine?: boolean;
+  senderName?: string;
+  timestamp?: string | number | Date;
+  onCopy?: (message: any) => void;
+  onReply?: (message: any) => void;
+  onJumpQuote?: (id: string) => void;
+  onReact?: (message: any, emoji: string, on: boolean) => void;
+  onEdit?: (message: any) => void;
+  isEditing?: boolean;
+}
+
+export interface MessageComposerProps {
+  value: string;
+  onChange: (value: string) => void;
+  onSend: () => void;
+  disabled?: boolean;
+  attachments?: any[];
+  attachmentError?: string | null;
+  sending?: boolean;
+  onAddAttachment?: (files: File[] | FileList | any) => void;
+  onRemoveAttachment?: (attachment: any) => void;
+  reply?: any;
+  onCancelReply?: () => void;
+  onInviteGame?: (game: string) => void;
+  gameInviteDisabled?: boolean;
+  onOpenBattleshipPreview?: () => void;
+  editing?: any;
+  onStartEditLast?: () => void;
+  onCancelEdit?: () => void;
+}
+
+export interface EmojiPickerProps {
+  onSelect: (emoji: string) => void;
+  isOpen: boolean;
+  onClose: () => void;
+  disabled?: boolean;
+}
+
+export interface MediaPickerProps {
+  onSelect: (item: any) => void;
+  onClose: () => void;
+  disabled?: boolean;
+}
+
+export const ChatWindowShell: ComponentType<ChatWindowShellProps>;
+export const MessageList: ComponentType<MessageListProps>;
+export const MessageBubble: ComponentType<MessageBubbleProps>;
+export const MessageComposer: ComponentType<MessageComposerProps>;
+export const EmojiPicker: ComponentType<EmojiPickerProps>;
+export const GifPicker: ComponentType<MediaPickerProps>;
+export const StickerPicker: ComponentType<MediaPickerProps>;
+
+export interface ChatPeople {
+  /** Ids (string|number) that identify the current user. */
+  ownIds: Array<string | number>;
+  /** Display name for a user id, or null when unknown. */
+  resolveName: (userId: string | number) => string | null;
+}
+export const ChatPeopleContext: Context<ChatPeople>;
+
+// ---------------------------------------------------------------------------
+// Chat store hooks, identity and UI open state
+// ---------------------------------------------------------------------------
+
+export const MAX_CHAT_MESSAGES: number;
+export function useChatStore<T = ChatState>(selector?: (state: ChatState) => T): T;
+export function useChatStoreApi(): StoreApi<ChatState> | null;
+export function useChatIdentity(): { userId: string | null; ids: string[]; name: string | null; scope: string };
+export function normalizeUser(user: unknown): { id: string | null; ids: string[]; name: string | null } | null;
+
+export interface ChatUiState {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+}
+export const chatUiStore: StoreApi<ChatUiState>;
+export function useChatUi<T = ChatUiState>(selector?: (state: ChatUiState) => T): T;
+
+// ---------------------------------------------------------------------------
+// Unread counters
+// ---------------------------------------------------------------------------
+
+export interface ChatUnreadState {
+  counts: Record<string, number>;
+  [key: string]: any;
+}
+export const useChatUnread: (<T>(selector: (state: ChatUnreadState) => T) => T) & StoreApi<ChatUnreadState>;
+export function totalUnread(state: ChatUnreadState): number;
+export function unreadScope(backend: string, userId: string | number | null | undefined): string | null;
+export function startUnreadStorageSync(store?: StoreLike<ChatUnreadState>): () => void;
+
+// ---------------------------------------------------------------------------
+// Host integration: background services (idempotent or ref-counted; return stop())
+// ---------------------------------------------------------------------------
+
+export function startDesktopNotifications(): () => void;
+export function startAppBadge(options?: { store?: StoreLike<ChatUnreadState>; nav?: Navigator; schedule?: (fn: () => void) => void }): () => void;
+export function startChatApp(): () => void;
+export function registerChatWorker(options?: { enabled?: boolean; path?: string; swUrl?: string }): void;
+export function openChatWindow(options?: { path?: string; windowName?: string }): boolean;
+export function useChatInstall(): any;
+export function startGifLibrarySync(): () => void;
+export function startEmojiPreferencesSync(): () => void;
+export function startConnect4Sounds(): () => void;
+export const chatGamesStore: StoreApi<any>;
+export const useChatGames: <T>(selector: (state: any) => T) => T;
+
+/** File relay over a raw WebSocket shared with the host. */
+export function consumeRelayEvent(socket: WebSocket, event: InboundFrame): boolean;
+export function hydrateRelayMessage(socket: WebSocket, message: InboundFrame): InboundFrame;
+export function closeRelay(socket: WebSocket): void;
+export function sendRelayMessage(socket: WebSocket | null, roomId: string, message: string, attachments?: any[]): Promise<void>;
+
+/** Lazily loads the Battleship 3D preview (three.js); use with React.lazy. */
+export function loadBattleshipPreview(): Promise<{ default: ComponentType<any> }>;

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@minicode-dev/chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "description": "LIRA real-time chat (WebSocket, media, games) as a React package.",
+  "author": "Minicode",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/MiniCodeSRL/LIRA-Frontend-backend_tool.git",
+    "directory": "packages/chat"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "@minicode-dev/source": "./src/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": {
+      "@minicode-dev/source": "./src/styles.css",
+      "default": "./dist/styles.css"
+    },
+    "./assets/*": "./assets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepack": "npm run build",
+    "release": "node scripts/release.mjs"
+  },
+  "peerDependencies": {
+    "lucide-react": ">=0.400.0",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "three": ">=0.134.0 <0.138.0",
+    "zustand": "^4.5.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "dayjs": "^1.11.18",
+    "emojibase-data": "^17.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react-swc": "^4.3.3",
+    "vite": "^8.3.5"
+  }
+}