@snapie/chat-client 0.1.0

package/README.md

@@ -0,0 +1,313 @@
+# @snapie/chat-client
+
+Hive-authenticated chat SDK for [Snapie](https://snapie.io). Supports DMs, channels, groups, real-time subscriptions (polling + FCM), and typing indicators.
+
+Works in any JavaScript/TypeScript environment. React hooks available as a separate entry point.
+
+---
+
+## Installation
+
+```bash
+npm install @snapie/chat-client
+# or
+pnpm add @snapie/chat-client
+```
+
+---
+
+## Quick start
+
+```typescript
+import { ChatClient } from '@snapie/chat-client';
+
+const client = new ChatClient({ baseUrl: 'https://snapie.io' });
+
+// Authenticate with a Hive account (posting key challenge/response)
+await client.authenticate(username, async (challenge) => {
+  // Use Hive Keychain, Aioha, or any signing library
+  return await keychain.signBuffer(username, challenge, 'Posting');
+});
+
+// Get all conversations
+const conversations = await client.getConversations();
+
+// Subscribe to live messages (polls every 15s, merges new ones)
+const unsub = client.subscribeToMessages(conversationId, 'dm', (messages) => {
+  console.log(messages);
+});
+
+// Send a message
+await client.sendMessage(conversationId, 'dm', 'Hello from 3speak!');
+
+// Stop subscribing
+unsub();
+
+// Clean up everything when done
+client.destroy();
+```
+
+---
+
+## Configuration
+
+```typescript
+const client = new ChatClient({
+  baseUrl: 'https://snapie.io',   // required — Snapie instance URL
+  pollInterval: 15000,             // optional — ms between polls (default: 15000)
+  storage: customStorage,          // optional — custom StorageAdapter (see below)
+});
+```
+
+### Custom storage (React Native / Node)
+
+By default the client uses `localStorage`. Override it with any object that implements `getItem`, `setItem`, `removeItem`:
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const client = new ChatClient({
+  baseUrl: 'https://snapie.io',
+  storage: {
+    getItem: (key) => AsyncStorage.getItem(key),      // note: sync wrapper needed
+    setItem: (key, val) => AsyncStorage.setItem(key, val),
+    removeItem: (key) => AsyncStorage.removeItem(key),
+  },
+});
+```
+
+---
+
+## Authentication
+
+The auth flow uses Hive's posting key signature — no passwords, no OAuth.
+
+```typescript
+// 1. Authenticate
+await client.authenticate(username, async (challenge) => {
+  return await signingLibrary.sign(challenge);
+});
+
+// 2. Check status
+client.isAuthenticated(); // boolean
+client.getUsername();     // string | null
+
+// 3. Logout
+client.logout();
+```
+
+---
+
+## Conversations
+
+```typescript
+// List all conversations (DMs + channels + groups)
+const conversations = await client.getConversations();
+// Conversation { _id, name, type: 'dm'|'channel'|'group', lastMessage, unread, ... }
+
+// Open or resume a DM with another Hive user
+const conv = await client.openDm('alice');
+```
+
+---
+
+## Messages
+
+```typescript
+// Fetch messages (one-time)
+const { messages } = await client.getMessages(conversationId, 'dm');
+const { messages } = await client.getMessages(channelId, 'channel', { limit: 50 });
+
+// Send
+const { message } = await client.sendMessage(conversationId, 'dm', 'Hey!');
+
+// Reply
+const { message } = await client.sendMessage(conversationId, 'dm', 'Got it', replyToMessageId);
+
+// Edit
+const updated = await client.editMessage(conversationId, 'dm', messageId, 'Edited text');
+```
+
+---
+
+## Real-time subscriptions
+
+All `subscribe*` methods return an **unsubscribe function**. They fire immediately with current data, then refresh on every poll tick.
+
+```typescript
+// Messages
+const unsub = client.subscribeToMessages(conv._id, conv.type, (messages) => {
+  setMessages(messages); // always the full ordered list
+});
+
+// Conversations list
+const unsub = client.subscribeToConversations((conversations) => {
+  setConversations(conversations);
+});
+
+// Unread badge count
+const unsub = client.subscribeToUnreadCount((count) => {
+  setBadge(count);
+});
+
+// Stop any subscription
+unsub();
+```
+
+### FCM foreground integration
+
+When a Firebase Cloud Messaging push arrives while the app is open, trigger an immediate refresh instead of waiting for the next poll tick:
+
+```typescript
+import { onMessage } from 'firebase/messaging';
+
+onMessage(messaging, () => {
+  client.onForegroundPush();
+});
+```
+
+---
+
+## Channels & groups
+
+```typescript
+// List public channels
+const channels = await client.getChannels();
+
+// Join / leave
+await client.joinChannel(channelId);
+await client.leaveChannel(channelId);
+
+// Create a group
+const group = await client.createGroup({
+  name: 'My Group',
+  description: 'Optional',
+  isPublic: false,
+  members: ['alice', 'bob'],
+});
+
+await client.addGroupMember(group._id, 'charlie');
+await client.removeGroupMember(group._id, 'charlie');
+```
+
+---
+
+## Typing indicators
+
+```typescript
+// Signal that the current user is typing
+await client.setTyping(conversationId, true);
+await client.setTyping(conversationId, false);
+
+// Poll who else is typing
+const { users } = await client.getTyping(conversationId);
+// users: string[] — list of usernames currently typing
+```
+
+---
+
+## Preferences
+
+```typescript
+await client.muteUser('spammer');
+await client.unmuteUser('spammer');
+await client.blockUser('troll');
+await client.unblockUser('troll');
+
+const prefs = await client.getPreferences();
+// { mutedUsers: string[], blockedUsers: string[] }
+```
+
+---
+
+## Push notifications (FCM)
+
+```typescript
+// Register a device token so this user receives push notifications
+await client.registerDevice(fcmToken);
+```
+
+---
+
+## React hooks
+
+```tsx
+import { ChatProvider, useConversations, useChatMessages, useUnreadCount, useTyping } from '@snapie/chat-client/react';
+
+// Wrap once at the top level
+<ChatProvider client={client}>
+  <App />
+</ChatProvider>
+```
+
+### `useConversations`
+
+```tsx
+function ConversationList() {
+  const { conversations, loading } = useConversations();
+  if (loading) return <Spinner />;
+  return conversations.map(conv => <ConvRow key={conv._id} conv={conv} />);
+}
+```
+
+### `useChatMessages`
+
+```tsx
+function MessageView({ conv }) {
+  const { messages, loading, sendMessage, editMessage } = useChatMessages(conv._id, conv.type);
+
+  return (
+    <>
+      {messages.map(m => <Bubble key={m._id} message={m} />)}
+      <Input onSend={sendMessage} />
+    </>
+  );
+}
+```
+
+### `useUnreadCount`
+
+```tsx
+function ChatButton() {
+  const { unreadCount } = useUnreadCount();
+  return <Button badge={unreadCount}>Chat</Button>;
+}
+```
+
+### `useTyping`
+
+```tsx
+function TypingIndicator({ convId }) {
+  const { typingUsers, setTyping } = useTyping(convId);
+  // setTyping(true) when user starts typing — auto-clears after 5s
+  return typingUsers.length > 0 ? <Text>{typingUsers.join(', ')} is typing...</Text> : null;
+}
+```
+
+---
+
+## TypeScript types
+
+All types are exported from the main entry point:
+
+```typescript
+import type {
+  ChatClient,
+  ChatClientOptions,
+  Conversation,
+  Message,
+  Channel,
+  MessagesResult,
+  DmDeliveryInfo,
+  DmStatusInfo,
+  TypingStatusInfo,
+  ChatPreferences,
+  StorageAdapter,
+} from '@snapie/chat-client';
+```
+
+---
+
+## Backend
+
+The SDK communicates with the Snapie chat API at `{baseUrl}/api/chat/*`. The backend is hosted at `https://snapie.io`. Auth tokens are JWTs issued after Hive posting-key signature verification and are stored in the configured storage adapter.

package/dist/client-Bztyx_3e.d.mts

@@ -0,0 +1,220 @@
+interface Channel {
+    _id: string;
+    name: string;
+    description?: string;
+    type: string;
+    conversationKind?: 'channel' | 'group';
+    owner?: string;
+    members?: string[];
+    memberCount: number;
+    isPublic: boolean;
+}
+interface Message {
+    _id: string;
+    sender: string;
+    content: string;
+    replyTo?: string | null;
+    editedAt?: string | null;
+    createdAt: string;
+}
+interface Conversation {
+    _id: string;
+    name: string;
+    description?: string;
+    type: 'channel' | 'group' | 'dm';
+    isPublic: boolean;
+    owner?: string;
+    members?: string[];
+    memberCount?: number;
+    peer?: string;
+    lastMessage?: Message | null;
+    unread?: boolean;
+}
+interface DmDeliveryInfo {
+    hasFcm: boolean;
+    memoSuggested: boolean;
+    cooldownMs: number;
+}
+interface DmStatusInfo {
+    meSeenAt: string;
+    peerSeenAt: string | null;
+    peerLastSeenAt: string | null;
+    peerOnline: boolean;
+}
+interface TypingStatusInfo {
+    users: string[];
+    ttlMs: number;
+}
+interface ChatPreferences {
+    mutedUsers: string[];
+    blockedUsers: string[];
+}
+interface MessagesResult {
+    messages: Message[];
+    status?: DmStatusInfo | null;
+}
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface ChatClientOptions {
+    /** Base URL of the Snapie instance, e.g. "https://snapie.io" */
+    baseUrl: string;
+    /** Override default localStorage — useful for React Native or Node */
+    storage?: StorageAdapter;
+    /** How often to poll for new messages when FCM is not available (ms, default 15000) */
+    pollInterval?: number;
+}
+
+declare class ChatService {
+    private token;
+    private tokenUsername;
+    private base;
+    private storage;
+    constructor(baseUrl: string, storage: StorageAdapter);
+    isAuthenticated(): boolean;
+    getTokenUsername(): string | null;
+    authenticate(username: string, signMessage: (msg: string) => Promise<string>): Promise<void>;
+    logout(): void;
+    getChannels(): Promise<Channel[]>;
+    getConversations(): Promise<Conversation[]>;
+    getChannelMessages(channelId: string, opts?: {
+        before?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<Message[]>;
+    sendChannelMessage(channelId: string, content: string, replyTo?: string): Promise<Message>;
+    editChannelMessage(channelId: string, messageId: string, content: string): Promise<Message>;
+    joinChannel(channelId: string): Promise<void>;
+    leaveChannel(channelId: string): Promise<void>;
+    getDmMessages(conversationId: string, opts?: {
+        before?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<MessagesResult>;
+    sendDmMessage(conversationId: string, content: string, replyTo?: string): Promise<{
+        message: Message;
+        delivery?: DmDeliveryInfo;
+    }>;
+    editDmMessage(conversationId: string, messageId: string, content: string): Promise<Message>;
+    openDm(targetUser: string): Promise<Conversation>;
+    createGroup(payload: {
+        name: string;
+        description?: string;
+        isPublic?: boolean;
+        members?: string[];
+    }): Promise<Channel>;
+    getGroups(): Promise<Channel[]>;
+    addGroupMember(groupId: string, member: string): Promise<Channel>;
+    removeGroupMember(groupId: string, member: string): Promise<Channel>;
+    getUnreadCount(): Promise<number>;
+    setTyping(conversationId: string, isTyping: boolean): Promise<void>;
+    getTyping(conversationId: string): Promise<TypingStatusInfo>;
+    getPreferences(): Promise<ChatPreferences>;
+    muteUser(username: string): Promise<void>;
+    unmuteUser(username: string): Promise<void>;
+    blockUser(username: string): Promise<void>;
+    unblockUser(username: string): Promise<void>;
+    registerDevice(fcmToken: string): Promise<void>;
+    markDmMemoFallbackSent(conversationId: string): Promise<void>;
+    private buildQS;
+    private get;
+    private post;
+    request<T>(url: string, opts: RequestInit, auth: boolean): Promise<T>;
+}
+
+type ConversationsCallback = (conversations: Conversation[]) => void;
+type MessagesCallback = (messages: Message[]) => void;
+type UnreadCallback = (count: number) => void;
+/**
+ * High-level Snapie chat client.
+ *
+ * Usage:
+ *   const client = new ChatClient({ baseUrl: 'https://snapie.io' });
+ *   await client.authenticate(username, msg => keychain.sign(msg));
+ *   const conversations = await client.getConversations();
+ *   const unsub = client.subscribeToMessages(convId, 'dm', msgs => setMessages(msgs));
+ */
+declare class ChatClient {
+    readonly service: ChatService;
+    private poller;
+    /** Cache of messages per conversationId — avoids re-rendering unchanged data */
+    private messageCache;
+    constructor(options: ChatClientOptions);
+    isAuthenticated(): boolean;
+    getUsername(): string | null;
+    /**
+     * Authenticate with a Hive account.
+     * `signMessage` should call Hive Keychain or equivalent with the posting key.
+     */
+    authenticate(username: string, signMessage: (challenge: string) => Promise<string>): Promise<void>;
+    logout(): void;
+    getConversations(): Promise<Conversation[]>;
+    openDm(targetUser: string): Promise<Conversation>;
+    getChannels(): Promise<Channel[]>;
+    getGroups(): Promise<Channel[]>;
+    joinChannel(channelId: string): Promise<void>;
+    leaveChannel(channelId: string): Promise<void>;
+    createGroup(payload: {
+        name: string;
+        description?: string;
+        isPublic?: boolean;
+        members?: string[];
+    }): Promise<Channel>;
+    addGroupMember(groupId: string, member: string): Promise<Channel>;
+    removeGroupMember(groupId: string, member: string): Promise<Channel>;
+    getMessages(conversationId: string, type: 'channel' | 'dm' | 'group', opts?: {
+        before?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<MessagesResult>;
+    sendMessage(conversationId: string, type: 'channel' | 'dm' | 'group', content: string, replyTo?: string): Promise<{
+        message: Message;
+        delivery?: DmDeliveryInfo;
+    }>;
+    editMessage(conversationId: string, type: 'channel' | 'dm' | 'group', messageId: string, content: string): Promise<Message>;
+    /**
+     * Subscribe to live updates for a conversation's message list.
+     * Calls `callback` immediately with the current messages, then again on every poll tick.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = client.subscribeToMessages(conv._id, conv.type, msgs => setMessages(msgs));
+     * // later:
+     * unsub();
+     */
+    subscribeToMessages(conversationId: string, type: 'channel' | 'dm' | 'group', callback: MessagesCallback): () => void;
+    /**
+     * Subscribe to the full conversations list, refreshed on every poll tick.
+     * Returns an unsubscribe function.
+     */
+    subscribeToConversations(callback: ConversationsCallback): () => void;
+    /**
+     * Subscribe to the unread message count, refreshed on every poll tick.
+     * Returns an unsubscribe function.
+     */
+    subscribeToUnreadCount(callback: UnreadCallback): () => void;
+    /**
+     * Notify the client of an incoming FCM foreground message.
+     * Call this from your FCM `onMessage` handler to trigger an immediate refresh
+     * rather than waiting for the next poll tick.
+     *
+     * @example
+     * onMessage(messaging, () => client.onForegroundPush());
+     */
+    onForegroundPush(): void;
+    setTyping(conversationId: string, isTyping: boolean): Promise<void>;
+    getTyping(conversationId: string): Promise<TypingStatusInfo>;
+    getUnreadCount(): Promise<number>;
+    getPreferences(): Promise<ChatPreferences>;
+    muteUser(username: string): Promise<void>;
+    unmuteUser(username: string): Promise<void>;
+    blockUser(username: string): Promise<void>;
+    unblockUser(username: string): Promise<void>;
+    registerDevice(fcmToken: string): Promise<void>;
+    markDmMemoFallbackSent(conversationId: string): Promise<void>;
+    destroy(): void;
+}
+
+export { ChatClient as C, type DmDeliveryInfo as D, type Message as M, type StorageAdapter as S, type TypingStatusInfo as T, ChatService as a, type ChatClientOptions as b, type Channel as c, type Conversation as d, type MessagesResult as e, type DmStatusInfo as f, type ChatPreferences as g };