@orbitconnect/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to `@orbitconnect/react` will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2025-04-27
+
+Initial public release.
+
+### Added
+
+**Core**
+- `OrbitProvider` — root context provider with WebSocket lifecycle, token refresh (`onTokenExpired`), and theming
+- `useOrbit` — access `apiClient`, `appUserId`, `clientId`, `baseUrl`, `appConfig` from any child
+- `useAppConfig` — resolved feature flags and icon overrides from `AppConfig`
+
+**Widgets**
+- `Chat` — full-featured chat UI: conversation list, message bubbles, composer, reactions, reply/quote, file/image/video/audio attachments, voice recording, emoji & sticker picker, message search, pin, batch select/delete/forward, presence, call history
+- `VideoCall` — floating WebRTC call overlay, renders automatically when a call is active
+- `MeetingWidget` — full video-conferencing room with participant grid, screen share, reactions, and hand-raise
+
+**Hooks**
+- `useMessages` — real-time messages with typing indicators, pinned messages, read receipts, reactions, recall, edit
+- `useConversations` — conversation list with live presence, typing, and delivery status
+- `useCall` — full call lifecycle: initiate, accept, reject, end, mute, camera toggle
+- `useMeeting` — meeting lifecycle: join, leave, mute, screen share, raise hand, reactions
+- `useMedia` — file upload with `upload()` and `getUrl()`
+- `useNotifications` — in-app notification feed with unread count, mark read, mark all read, clear
+- `usePresence` — real-time presence status per user (`online` / `away` / `offline`)
+- `useCallHistory` — call records with caller/callee info
+- `useRealtime` — session lifecycle with transitions (chat → call → meeting) and custom event emission
+- `useOrbitEvent` — subscribe to any raw WebSocket event
+- `useOrbitListener` — access the raw socket and connection status
+
+**Meeting context**
+- `MeetingProvider`, `MeetingContext`, `useMeetingContext` — standalone meeting context for custom meeting UIs
+
+**Theme**
+- `ThemeProvider`, `useTheme`, `darkTheme`, `lightTheme`
+- Full CSS variable token set: backgrounds, foregrounds, bubbles, composer, borders, radii, fonts
+- `PartialTheme` type for partial overrides via `OrbitProvider`
+
+**Stylesheet**
+- `dist/index.css` — pre-built Tailwind CSS stylesheet, import once via `import '@orbitconnect/react/index.css'`
+
+**Build**
+- Vite library build (ESM only) with React Compiler (babel-plugin-react-compiler)
+- TypeScript declarations emitted to `dist/` via `tsc -p tsconfig.build.json`
+- Tailwind CSS minified and bundled to `dist/index.css`
+
+---
+
+[0.1.0]: https://github.com/core-dynamics/orbitconnect-sdk/releases/tag/react-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OrbitConnect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# @orbitconnect/react
+
+React SDK for OrbitConnect — drop in real-time chat, voice/video calls, and meetings into any React app.
+
+> The SDK connects exclusively to `https://orbitxyz.muvle.org/api/v1`. This base URL is fixed and cannot be overridden.
+
+## Install
+
+```bash
+npm install @orbitconnect/react
+```
+
+Also import the stylesheet once in your entry file:
+
+```ts
+import '@orbitconnect/react/index.css'
+```
+
+## Quick start
+
+### 1. Backend — issue a user token
+
+```ts
+// Express / Next.js API route
+import { OrbitServer } from '@orbitconnect/server'
+
+const orbit = new OrbitServer({ secretKey: process.env.ORBIT_SECRET_KEY! })
+
+app.post('/auth/token', async (req, res) => {
+  const user = await orbit.users.create({
+    external_id:  req.user.id,
+    display_name: req.user.name,
+  })
+  const { token } = await orbit.users.createToken(user.id)
+  res.json({ token, userId: user.id, clientId: process.env.ORBIT_CLIENT_ID })
+})
+```
+
+### 2. Frontend — wrap with OrbitProvider
+
+```tsx
+import { OrbitProvider, Chat } from '@orbitconnect/react'
+import '@orbitconnect/react/index.css'
+
+export function App() {
+  const [auth, setAuth] = useState(null)
+
+  async function login() {
+    const data = await fetch('/auth/token', { method: 'POST' }).then(r => r.json())
+    setAuth(data)
+  }
+
+  if (!auth) return <button onClick={login}>Sign in</button>
+
+  return (
+    <OrbitProvider
+      clientId={auth.clientId}
+      userToken={auth.token}
+      appUserId={auth.userId}
+    >
+      <Chat />
+    </OrbitProvider>
+  )
+}
+```
+
+That's it — you now have a fully functional chat with real-time messaging, presence, reactions, file attachments, and voice/video calls.
+
+---
+
+## OrbitProvider
+
+The root context provider. Wrap your app (or the section that uses OrbitConnect) with it once.
+
+```tsx
+<OrbitProvider
+  clientId="pk_live_..."
+  userToken={token}
+  appUserId={userId}
+  baseTheme={darkTheme}
+  theme={{ primary: '#7c3aed', bubbleSender: '#7c3aed' }}
+  appConfig={{ name: 'MyApp', showPoweredBy: false }}
+  onTokenExpired={async () => fetchFreshToken()}
+>
+  <App />
+</OrbitProvider>
+```
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `clientId` | `string` | ✓ | Publishable key (`pk_live_…` or `pk_test_…`) |
+| `userToken` | `string` | ✓ | Short-lived token from `orbit.users.createToken()` |
+| `appUserId` | `string` | ✓ | The authenticated app user ID |
+| `theme` | `PartialTheme` | | CSS variable overrides — see [Theming](#theming) |
+| `baseTheme` | `OrbitTheme` | | Base theme object (default: `darkTheme`) |
+| `appConfig` | `AppConfig` | | Branding, icons, sounds — see [AppConfig](#appconfig) |
+| `onTokenExpired` | `() => Promise<string>` | | Called on WS close 4001 — return a fresh token to reconnect |
+
+---
+
+## Widgets
+
+Drop-in components that work out of the box inside `OrbitProvider`.
+
+### Chat
+
+Full-featured chat UI — conversation list, message bubbles, composer, reactions, file attachments, voice messages, call buttons, and more.
+
+```tsx
+import { Chat } from '@orbitconnect/react'
+
+<Chat
+  onCallRequest={(userId, type) => initiateCall(userId, type)}
+  chatBanner={<div>Support hours: Mon–Fri 9am–5pm</div>}
+  defaultQuickMessages={[
+    { id: '1', label: 'Greeting', text: 'Hi! How can I help?' },
+  ]}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `conversationId` | `string` | Open directly to a specific conversation |
+| `onCallRequest` | `(userId, type) => void` | Called when the user taps the call/video button |
+| `renderHeader` | `(info: ChatHeaderInfo) => ReactNode` | Replace the default header |
+| `chatBanner` | `ReactNode` | Rendered above the message list |
+| `defaultQuickMessages` | `QuickMessage[]` | Seed the quick-message picker |
+
+Included out of the box: real-time messaging, typing indicators, read receipts, reactions, reply/quote, file/image/video/audio attachments, voice recording, sticker & GIF picker, message search, pin messages, batch select/delete/forward, presence, call history.
+
+### VideoCall
+
+Floating WebRTC call overlay — renders automatically when a call is active.
+
+```tsx
+import { VideoCall, useCall } from '@orbitconnect/react'
+
+function App() {
+  const { initiateCall } = useCall()
+  return (
+    <>
+      <button onClick={() => initiateCall(userId, 'video')}>Start call</button>
+      <VideoCall />  {/* place once at the root */}
+    </>
+  )
+}
+```
+
+### MeetingWidget
+
+Full video-conferencing room with participant grid, screen share, reactions, and hand-raise.
+
+```tsx
+import { MeetingWidget } from '@orbitconnect/react'
+
+<MeetingWidget
+  meetingId={activeMeetingId}
+  title="Team Standup"
+  onEnd={() => setScreen('lobby')}
+/>
+```
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `meetingId` | `string` | ✓ | The meeting ID to join |
+| `title` | `string` | | Display title (default: `"Meeting"`) |
+| `onEnd` | `() => void` | | Called when the meeting ends or the user leaves |
+
+---
+
+## Hooks
+
+All hooks must be used inside `OrbitProvider`.
+
+### useMessages(conversationId)
+
+```ts
+const {
+  messages,           // MessageBubbleProps[]
+  loading,
+  typingUsers,        // string[] — display names of typing users
+  pinnedMessages,
+  sendMessage,        // (text, mediaId?, meta?) => Promise<void>
+  sendTyping,
+  markRead,
+  editMessageLocally,
+} = useMessages(conversationId)
+```
+
+### useConversations()
+
+```ts
+const {
+  conversations,  // Conversation[]
+  loading,
+  createDirect,   // (participantId: string) => Promise<string>
+  refresh,
+} = useConversations()
+```
+
+### useCall()
+
+```ts
+const {
+  call,           // ActiveCall | null
+  localStream,    // MediaStream | null
+  remoteStream,   // MediaStream | null
+  initiateCall,   // (userId, type, conversationId?) => void
+  acceptCall,
+  rejectCall,
+  endCall,
+  toggleMute,     // (muted: boolean) => void
+  toggleCamera,   // (enabled: boolean) => void
+  dismissEnded,
+} = useCall()
+```
+
+### useNotifications()
+
+```ts
+const {
+  notifications,  // OrbitNotification[]
+  unreadCount,
+  markRead,       // (id: string) => void
+  markAllRead,
+  clearAll,
+} = useNotifications()
+```
+
+### usePresence(userId)
+
+```ts
+const status = usePresence(userId)  // 'online' | 'away' | 'offline'
+```
+
+### useMedia()
+
+```ts
+const {
+  upload,   // (file: File) => Promise<MediaObject>
+  getUrl,   // (mediaId: string) => Promise<string>
+} = useMedia()
+```
+
+### useRealtime()
+
+```ts
+const {
+  session,
+  createSession,  // (input: CreateSessionInput) => Promise<void>
+  endSession,
+  transition,     // (type: TransitionType, contextId?: string) => Promise<void>
+  emitEvent,      // (eventType: string, payload: object) => Promise<void>
+} = useRealtime()
+```
+
+### useOrbitEvent(eventType, handler)
+
+Subscribe to any raw WebSocket event.
+
+```ts
+import { useOrbitEvent } from '@orbitconnect/react'
+
+useOrbitEvent('message:new', ({ conversation_id, message }) => {
+  console.log('New message:', message)
+})
+
+useOrbitEvent('notification:received', ({ payload }) => {
+  toast(payload.title as string)
+})
+```
+
+### useCallHistory()
+
+```ts
+const { records } = useCallHistory()  // CallRecord[]
+```
+
+### useOrbit()
+
+Access the raw context from any child component.
+
+```ts
+const { apiClient, appUserId, clientId, baseUrl, appConfig } = useOrbit()
+```
+
+---
+
+## Theming
+
+Every colour, radius, and font is a CSS variable you can override.
+
+```tsx
+import { OrbitProvider, darkTheme, lightTheme } from '@orbitconnect/react'
+import type { PartialTheme } from '@orbitconnect/react'
+
+const myTheme: PartialTheme = {
+  primary:                '#7c3aed',
+  bubbleSender:           '#7c3aed',
+  bubbleSenderForeground: '#fff',
+}
+
+<OrbitProvider baseTheme={darkTheme} theme={myTheme} ...>
+```
+
+Key token groups: `background`, `foreground`, `card`, `border`, `primary`, `bubbleSender`, `bubbleReceiver`, `composerBg`, `radiusSm/Md/Lg/Xl`, `fontBody`.
+
+---
+
+## AppConfig
+
+White-label every aspect of the UI — name, logo, icons, sounds, and feature flags.
+
+```tsx
+<OrbitProvider
+  appConfig={{
+    name:          'MyApp',
+    logo:          <MyLogo />,
+    showPoweredBy: false,
+
+    // feature flags
+    showAudioIcon:          true,
+    showVideoIcon:          true,
+    showSearchIcon:         true,
+    showAttachMentButton:   true,
+    showQuickMessageButton: true,
+    useRichTextEditor:      true,
+    enableMeetingUi:        true,
+
+    // icon overrides (any ReactNode)
+    sendIcon:        <IoPaperPlaneOutline />,
+    callIcon:        <IoCallOutline />,
+    VideoCallIcon:   <IoVideocamOutline />,
+
+    // custom sounds
+    sounds: {
+      messageSent:     '/sounds/sent.mp3',
+      messageReceived: '/sounds/received.mp3',
+      incomingCall:    '/sounds/ring.mp3',
+    },
+  }}
+>
+```
+
+---
+
+## Token refresh
+
+When the server closes the WebSocket with code `4001` (token expired), the SDK calls `onTokenExpired`. Return a fresh token to reconnect automatically.
+
+```tsx
+<OrbitProvider
+  onTokenExpired={async () => {
+    const res  = await fetch('/auth/refresh', { method: 'POST' })
+    const data = await res.json()
+    return data.token
+  }}
+  ...
+>
+```
+
+---
+
+## Build
+
+```bash
+npm run build    # tsc + vite build + tailwind CSS
+npm run dev      # vite dev server (for SDK development)
+npm run lint     # eslint
+```
+
+## License
+
+MIT

package/dist/OrbitContext.d.ts

@@ -0,0 +1,87 @@
+import { type ReactNode } from 'react';
+import type { ApiClient } from './api/client';
+/** Sound asset URLs for SDK events */
+export interface SoundConfig {
+    /** Played when the user sends a message */
+    messageSent?: string;
+    /** Played when a new message is received */
+    messageReceived?: string;
+    /** Played when the remote user is typing */
+    typing?: string;
+    /** Played when a reaction is added to a message */
+    messageReaction?: string;
+    /** Played when an incoming call arrives */
+    incomingCall?: string;
+    /** Played when a call ends */
+    callEnded?: string;
+    /** Played when a meeting reaction burst fires */
+    meetingReaction?: string;
+}
+/** Branding / white-label config passed to OrbitProvider */
+export interface AppConfig {
+    /** Your app name — replaces "OrbitConnect" everywhere */
+    name?: string;
+    /** A React component rendered as the logo */
+    logo?: ReactNode;
+    /** Show both name and logo (default when both are provided) */
+    showNameAndLogo?: boolean;
+    /** Show name only, even if logo is provided */
+    showNameOnly?: boolean;
+    /** Show logo only, even if name is provided */
+    showLogoOnly?: boolean;
+    /** Custom sound assets */
+    sounds?: SoundConfig;
+    /** Show the chat header bar (default: true) */
+    showChatHeader?: boolean;
+    /** Show the quick-message button in the composer (default: true) */
+    showQuickMessageButton?: boolean;
+    /** Use the rich-text (contentEditable) editor; false = plain textarea (default: true) */
+    useRichTextEditor?: boolean;
+    /** Show the attachment button in the composer (default: true) */
+    showAttachMentButton?: boolean;
+    /** Show the search icon in the chat header (default: true) */
+    showSearchIcon?: boolean;
+    /** Show the audio-call icon in the chat header (default: true) */
+    showAudioIcon?: boolean;
+    /** Show the video-call icon in the chat header (default: true) */
+    showVideoIcon?: boolean;
+    /** Show the meeting tab / meeting UI (default: true) */
+    enableMeetingUi?: boolean;
+    /** Show "Powered by OrbitConnect" footer in Chat and Meeting widgets (default: true) */
+    showPoweredBy?: boolean;
+    /** Custom attachment button icon */
+    attachmentIcon?: ReactNode;
+    /** Custom voice-record button icon */
+    recordIcon?: ReactNode;
+    /** Custom quick-message button icon */
+    QuickmessageIcon?: ReactNode;
+    /** Custom emoji button icon */
+    emojIcon?: ReactNode;
+    /** Custom sticker button icon */
+    stickerIcon?: ReactNode;
+    /** Custom send button icon */
+    sendIcon?: ReactNode;
+    /** Custom "delivered" status icon */
+    deliveredIcon?: ReactNode;
+    /** Custom "sent" status icon */
+    sentIcon?: ReactNode;
+    /** Custom "read" status icon */
+    readIcon?: ReactNode;
+    /** Custom audio-call icon (header) */
+    callIcon?: ReactNode;
+    /** Custom video-call icon (header) */
+    VideoCallIcon?: ReactNode;
+}
+export interface OrbitContextValue {
+    apiClient: ApiClient;
+    /** The authenticated app_user ID */
+    appUserId: string;
+    clientId: string;
+    baseUrl: string;
+    /** Optional branding config */
+    appConfig?: AppConfig;
+}
+export declare const OrbitContext: import("react").Context<OrbitContextValue | null>;
+export declare function useOrbit(): OrbitContextValue;
+/** Convenience hook — returns appConfig with safe defaults applied */
+export declare function useAppConfig(): Required<Pick<AppConfig, 'showChatHeader' | 'showQuickMessageButton' | 'useRichTextEditor' | 'showAttachMentButton' | 'showSearchIcon' | 'showAudioIcon' | 'showVideoIcon' | 'enableMeetingUi' | 'showPoweredBy'>> & Pick<AppConfig, 'attachmentIcon' | 'recordIcon' | 'QuickmessageIcon' | 'emojIcon' | 'stickerIcon' | 'sendIcon' | 'deliveredIcon' | 'sentIcon' | 'readIcon' | 'callIcon' | 'VideoCallIcon'>;

package/dist/OrbitProvider.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import { type AppConfig } from './OrbitContext';
+import type { PartialTheme, OrbitTheme } from './theme/types';
+export interface OrbitProviderProps {
+    /**
+     * Your publishable client ID — safe for the browser.
+     * Format: "pk_live_..." or "pk_test_..."
+     */
+    clientId: string;
+    /** Short-lived user token from orbit.users.createToken() on your backend */
+    userToken: string;
+    /** The authenticated app_user's ID */
+    appUserId: string;
+    /** Theme overrides */
+    theme?: PartialTheme;
+    /** Base theme. Defaults to darkTheme */
+    baseTheme?: OrbitTheme;
+    /** Called when the WS connection closes with code 4001 (token expired). Should return a fresh token. */
+    onTokenExpired?: () => Promise<string>;
+    /** Branding / white-label config — replaces "OrbitConnect" with your app name/logo */
+    appConfig?: AppConfig;
+    children: ReactNode;
+}
+export declare function OrbitProvider({ clientId, userToken, appUserId, theme, baseTheme, onTokenExpired, appConfig, children, }: OrbitProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/api/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Lightweight fetch client for the client SDK.
+ * Uses the user token + client ID — never the secret API key.
+ */
+export interface ApiClientOptions {
+    baseUrl: string;
+    userToken: string;
+    clientId: string;
+    /** The authenticated app_user ID — forwarded as X-App-User-Id for per-user rate limiting */
+    appUserId: string;
+}
+export declare class ApiClient {
+    private readonly opts;
+    constructor(opts: ApiClientOptions);
+    get baseUrl(): string;
+    get userToken(): string;
+    get clientId(): string;
+    private headers;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    /** Register a device push token so the backend can send FCM/APNs wakeup pushes */
+    registerPushToken(token: string, platform: 'android' | 'ios'): Promise<void>;
+    /** Send a test notification to yourself (dev/demo use) */
+    sendTestNotification(opts?: {
+        type?: string;
+        title?: string;
+        body?: string;
+        icon?: string;
+        channel?: string;
+        actions?: Array<{
+            id: string;
+            label: string;
+            url?: string;
+        }>;
+    }): Promise<void>;
+}
+export declare class OrbitClientError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export { ApiClient, OrbitClientError } from './client';
+export type { ApiClientOptions } from './client';