ape-im-sdk-react 1.0.0

package/README.md

@@ -0,0 +1,245 @@
+# ape-im-sdk-react
+
+React SDK for **Ape Instant Messenger** - Add nostalgic AOL-style chat functionality to your ApeChain dApp with a single line of code.
+
+## Features
+
+- 💬 **Popup Chat Widget** - Floating chat bubble with full messenger interface
+- 🔐 **Wallet Authentication** - Connect via MetaMask, WalletConnect, or any injected wallet
+- 🎨 **Retro AIM Aesthetic** - Classic 90s AOL Instant Messenger design
+- 🖼️ **NFT Profile Pictures** - Use your ApeChain NFTs as avatars
+- 💰 **Crypto Tipping** - Send APE tokens directly in chat
+- 🔒 **Token-Gated Chats** - Create exclusive group chats for token holders
+- 📱 **Real-time Messaging** - WebSocket-powered instant delivery
+- 🎭 **Rich Content** - Emoji reactions, GIFs, stickers, voice messages
+- 🌙 **Dark Mode** - Full light/dark theme support
+
+## Installation
+
+```bash
+npm install ape-im-sdk-react
+# or
+yarn add ape-im-sdk-react
+# or
+pnpm add ape-im-sdk-react
+```
+
+## Requirements
+
+- **React 18+**
+- **MetaMask** or any compatible injected Web3 wallet (window.ethereum)
+- Ape IM API endpoint (defaults to `https://www.apeinstantmessenger.com`)
+
+> **Note:** The SDK currently requires MetaMask or a compatible injected wallet. WalletConnect support is planned for a future release.
+
+## Quick Start
+
+Add the chat widget to your app with just a few lines:
+
+```tsx
+import { ApeIMProvider, ChatWidget } from 'ape-im-sdk-react';
+import 'ape-im-sdk-react/styles.css';
+
+function App() {
+  return (
+    <ApeIMProvider>
+      <YourApp />
+      <ChatWidget position="bottom-right" />
+    </ApeIMProvider>
+  );
+}
+```
+
+That's it! Your users can now click the floating chat bubble to open the messenger.
+
+## Configuration
+
+### ApeIMProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | `https://www.apeinstantmessenger.com` | API endpoint |
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Color theme |
+| `onConnect` | `(user: User) => void` | - | Callback when user connects |
+| `onDisconnect` | `() => void` | - | Callback when user disconnects |
+
+### ChatWidget Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Widget position |
+| `offset` | `{ x: number, y: number }` | `{ x: 20, y: 20 }` | Offset from corner |
+| `defaultOpen` | `boolean` | `false` | Start with widget open |
+| `bubbleSize` | `number` | `60` | Size of the chat bubble |
+| `zIndex` | `number` | `9999` | CSS z-index |
+
+## Hooks
+
+### useApeIM
+
+Access authentication state and methods:
+
+```tsx
+import { useApeIM } from 'ape-im-sdk-react';
+
+function MyComponent() {
+  const { 
+    user,           // Current user object
+    isConnected,    // Boolean connection state
+    isLoading,      // Loading state
+    connect,        // Connect wallet function
+    disconnect,     // Disconnect function
+    openWidget,     // Open the chat widget
+    closeWidget,    // Close the chat widget
+  } = useApeIM();
+
+  return (
+    <button onClick={connect}>
+      {isConnected ? user.username : 'Connect'}
+    </button>
+  );
+}
+```
+
+### useConversations
+
+Access user's conversations:
+
+```tsx
+import { useConversations } from 'ape-im-sdk-react';
+
+function ConversationList() {
+  const { 
+    conversations,  // Array of conversations
+    isLoading,
+    startConversation,  // Start new DM
+    createGroup,        // Create group chat
+  } = useConversations();
+
+  return (
+    <ul>
+      {conversations.map(conv => (
+        <li key={conv.id}>{conv.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### useChat
+
+Access chat functionality for a specific conversation:
+
+```tsx
+import { useChat } from 'ape-im-sdk-react';
+
+function ChatRoom({ conversationId }) {
+  const {
+    messages,
+    sendMessage,
+    isTyping,
+    participants,
+  } = useChat(conversationId);
+
+  return (
+    <div>
+      {messages.map(msg => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Styling
+
+The SDK includes default retro AIM styling. Import the CSS:
+
+```tsx
+import 'ape-im-sdk-react/styles.css';
+```
+
+### Custom Theming
+
+Override CSS variables to customize:
+
+```css
+:root {
+  --ape-im-primary: #1D3FE7;
+  --ape-im-primary-dark: #142B99;
+  --ape-im-accent: #E8EDFF;
+  --ape-im-bubble-user: #1D3FE7;
+  --ape-im-bubble-other: #e5e5e5;
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { 
+  User, 
+  Message, 
+  Conversation,
+  ChatWidgetProps,
+  ApeIMProviderProps,
+} from 'ape-im-sdk-react';
+```
+
+## API Documentation
+
+For complete API documentation, visit: https://ape-im.replit.app/docs
+
+## Publishing to npm
+
+To publish the SDK to npm:
+
+```bash
+# Navigate to the SDK package
+cd packages/sdk-react
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Login to npm (if not already)
+npm login
+
+# Publish to npm
+npm publish --access public
+```
+
+### Versioning
+
+Before publishing a new version, update the version in `package.json`:
+
+```bash
+# Patch release (1.0.0 -> 1.0.1)
+npm version patch
+
+# Minor release (1.0.0 -> 1.1.0)
+npm version minor
+
+# Major release (1.0.0 -> 2.0.0)
+npm version major
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build with watch mode for development
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## License
+
+MIT © Ape IM Team

package/dist/index.d.mts

@@ -0,0 +1,150 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface User {
+    id: string;
+    walletAddress: string;
+    username: string | null;
+    profilePicture: string | null;
+    status: 'online' | 'away' | 'offline';
+    awayMessage: string | null;
+    isProfileComplete: boolean;
+    readReceiptsEnabled: boolean;
+    twitterHandle: string | null;
+    discordHandle: string | null;
+    createdAt: Date;
+}
+interface Message {
+    id: string;
+    conversationId: string;
+    senderId: string;
+    content: string;
+    formatting: MessageFormatting | null;
+    messageType: 'text' | 'gif' | 'image' | 'sticker' | 'voice' | 'poll';
+    isEphemeral: boolean;
+    ephemeralExpiresAt: Date | null;
+    readAt: Date | null;
+    createdAt: Date;
+    parentMessageId: string | null;
+    replyCount: number;
+    sender: User;
+    reactions?: Reaction[];
+    tips?: Tip[];
+}
+interface MessageFormatting {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    fontSize?: string;
+}
+interface Conversation {
+    id: string;
+    name: string | null;
+    isGroup: boolean;
+    createdAt: Date;
+    lastMessageAt: Date | null;
+    participants: ConversationParticipant[];
+    lastMessage?: Message;
+    unreadCount?: number;
+}
+interface ConversationParticipant {
+    userId: string;
+    conversationId: string;
+    joinedAt: Date;
+    user: User;
+}
+interface Reaction {
+    id: string;
+    messageId: string;
+    userId: string;
+    emoji: string;
+    createdAt: Date;
+    user: User;
+}
+interface Tip {
+    id: string;
+    messageId: string | null;
+    senderId: string;
+    recipientId: string;
+    amount: string;
+    transactionHash: string;
+    createdAt: Date;
+}
+interface ApeIMProviderProps$1 {
+    children: React.ReactNode;
+    apiUrl: string;
+    theme?: 'light' | 'dark' | 'system';
+    onConnect?: (user: User) => void;
+    onDisconnect?: () => void;
+}
+interface ChatWidgetProps {
+    position?: 'bottom-right' | 'bottom-left';
+    offset?: {
+        x: number;
+        y: number;
+    };
+    defaultOpen?: boolean;
+    bubbleSize?: number;
+    zIndex?: number;
+}
+interface ApeIMContextValue {
+    user: User | null;
+    isConnected: boolean;
+    isLoading: boolean;
+    sessionToken: string | null;
+    apiUrl: string;
+    theme: 'light' | 'dark' | 'system';
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    openWidget: () => void;
+    closeWidget: () => void;
+    isWidgetOpen: boolean;
+}
+interface ConversationsContextValue {
+    conversations: Conversation[];
+    isLoading: boolean;
+    error: Error | null;
+    startConversation: (userId: string) => Promise<Conversation>;
+    createGroup: (name: string, participantIds: string[]) => Promise<Conversation>;
+    refetch: () => void;
+}
+interface ChatContextValue {
+    messages: Message[];
+    isLoading: boolean;
+    sendMessage: (content: string, formatting?: MessageFormatting) => Promise<void>;
+    sendReaction: (messageId: string, emoji: string) => Promise<void>;
+    isTyping: User[];
+    participants: User[];
+    markAsRead: () => void;
+}
+
+interface ApeIMProviderProps {
+    children: ReactNode;
+    apiUrl?: string;
+    theme?: 'light' | 'dark' | 'system';
+    onConnect?: (user: User) => void;
+    onDisconnect?: () => void;
+}
+declare function ApeIMProvider({ children, apiUrl, theme, onConnect, onDisconnect, }: ApeIMProviderProps): react_jsx_runtime.JSX.Element;
+declare function useApeIM(): ApeIMContextValue;
+declare global {
+    interface Window {
+        ethereum?: {
+            request: (args: {
+                method: string;
+                params?: unknown[];
+            }) => Promise<string[]>;
+            on: (event: string, callback: (...args: unknown[]) => void) => void;
+            removeListener: (event: string, callback: (...args: unknown[]) => void) => void;
+        };
+    }
+}
+
+declare function ChatWidget({ position, offset, defaultOpen, bubbleSize, zIndex, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+
+declare function useConversations(): ConversationsContextValue;
+
+declare function useChat(conversationId: string | null): ChatContextValue;
+
+export { type ApeIMContextValue, ApeIMProvider, type ApeIMProviderProps$1 as ApeIMProviderProps, type ChatContextValue, ChatWidget, type ChatWidgetProps, type Conversation, type ConversationParticipant, type ConversationsContextValue, type Message, type MessageFormatting, type Reaction, type Tip, type User, useApeIM, useChat, useConversations };

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface User {
+    id: string;
+    walletAddress: string;
+    username: string | null;
+    profilePicture: string | null;
+    status: 'online' | 'away' | 'offline';
+    awayMessage: string | null;
+    isProfileComplete: boolean;
+    readReceiptsEnabled: boolean;
+    twitterHandle: string | null;
+    discordHandle: string | null;
+    createdAt: Date;
+}
+interface Message {
+    id: string;
+    conversationId: string;
+    senderId: string;
+    content: string;
+    formatting: MessageFormatting | null;
+    messageType: 'text' | 'gif' | 'image' | 'sticker' | 'voice' | 'poll';
+    isEphemeral: boolean;
+    ephemeralExpiresAt: Date | null;
+    readAt: Date | null;
+    createdAt: Date;
+    parentMessageId: string | null;
+    replyCount: number;
+    sender: User;
+    reactions?: Reaction[];
+    tips?: Tip[];
+}
+interface MessageFormatting {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    fontSize?: string;
+}
+interface Conversation {
+    id: string;
+    name: string | null;
+    isGroup: boolean;
+    createdAt: Date;
+    lastMessageAt: Date | null;
+    participants: ConversationParticipant[];
+    lastMessage?: Message;
+    unreadCount?: number;
+}
+interface ConversationParticipant {
+    userId: string;
+    conversationId: string;
+    joinedAt: Date;
+    user: User;
+}
+interface Reaction {
+    id: string;
+    messageId: string;
+    userId: string;
+    emoji: string;
+    createdAt: Date;
+    user: User;
+}
+interface Tip {
+    id: string;
+    messageId: string | null;
+    senderId: string;
+    recipientId: string;
+    amount: string;
+    transactionHash: string;
+    createdAt: Date;
+}
+interface ApeIMProviderProps$1 {
+    children: React.ReactNode;
+    apiUrl: string;
+    theme?: 'light' | 'dark' | 'system';
+    onConnect?: (user: User) => void;
+    onDisconnect?: () => void;
+}
+interface ChatWidgetProps {
+    position?: 'bottom-right' | 'bottom-left';
+    offset?: {
+        x: number;
+        y: number;
+    };
+    defaultOpen?: boolean;
+    bubbleSize?: number;
+    zIndex?: number;
+}
+interface ApeIMContextValue {
+    user: User | null;
+    isConnected: boolean;
+    isLoading: boolean;
+    sessionToken: string | null;
+    apiUrl: string;
+    theme: 'light' | 'dark' | 'system';
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    openWidget: () => void;
+    closeWidget: () => void;
+    isWidgetOpen: boolean;
+}
+interface ConversationsContextValue {
+    conversations: Conversation[];
+    isLoading: boolean;
+    error: Error | null;
+    startConversation: (userId: string) => Promise<Conversation>;
+    createGroup: (name: string, participantIds: string[]) => Promise<Conversation>;
+    refetch: () => void;
+}
+interface ChatContextValue {
+    messages: Message[];
+    isLoading: boolean;
+    sendMessage: (content: string, formatting?: MessageFormatting) => Promise<void>;
+    sendReaction: (messageId: string, emoji: string) => Promise<void>;
+    isTyping: User[];
+    participants: User[];
+    markAsRead: () => void;
+}
+
+interface ApeIMProviderProps {
+    children: ReactNode;
+    apiUrl?: string;
+    theme?: 'light' | 'dark' | 'system';
+    onConnect?: (user: User) => void;
+    onDisconnect?: () => void;
+}
+declare function ApeIMProvider({ children, apiUrl, theme, onConnect, onDisconnect, }: ApeIMProviderProps): react_jsx_runtime.JSX.Element;
+declare function useApeIM(): ApeIMContextValue;
+declare global {
+    interface Window {
+        ethereum?: {
+            request: (args: {
+                method: string;
+                params?: unknown[];
+            }) => Promise<string[]>;
+            on: (event: string, callback: (...args: unknown[]) => void) => void;
+            removeListener: (event: string, callback: (...args: unknown[]) => void) => void;
+        };
+    }
+}
+
+declare function ChatWidget({ position, offset, defaultOpen, bubbleSize, zIndex, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+
+declare function useConversations(): ConversationsContextValue;
+
+declare function useChat(conversationId: string | null): ChatContextValue;
+
+export { type ApeIMContextValue, ApeIMProvider, type ApeIMProviderProps$1 as ApeIMProviderProps, type ChatContextValue, ChatWidget, type ChatWidgetProps, type Conversation, type ConversationParticipant, type ConversationsContextValue, type Message, type MessageFormatting, type Reaction, type Tip, type User, useApeIM, useChat, useConversations };