@corva/chat-core 0.0.1 → 0.1.2

package/README.md

@@ -10,13 +10,70 @@ It holds everything that is not UI: the Revolt/Stoat API and socket client, chat
 ## Rules
 
 - **No platform globals.** The type environment is `es2022` only, with no DOM or Node types. The only
-  globals allowed are the timers and `console` declared in `src/platform.d.ts`. `fetch`, `WebSocket`,
+  globals allowed are the timers, `console` and `requestAnimationFrame` declared in
+  `src/platform.d.ts` and `src/raf.d.ts`. `fetch`, `WebSocket`,
   storage, notifications and app-state events are injected by the host app through adapters.
 - **No React.** Stores use `zustand/vanilla`; each app wraps them in its own hooks.
 - **No UI dependencies** (`@corva/ui`, MUI, React Native).
 
+Hosts must provide a global `crypto.getRandomValues` for `uuid`: browsers have it, and the mobile
+app installs it with `polyfillWebCrypto()` from `expo-standard-web-crypto` in its root layout.
+
 Lint and typecheck enforce these rules.
 
+## Setup
+
+Call `configureChat(host)` once at app start, before touching any store, then `ensureChatSession(corvaUser)` to sign in:
+
+```ts
+import { configureChat, ensureChatSession } from '@corva/chat-core';
+
+configureChat({
+  apiUrl, // Revolt REST, e.g. https://stoat.corva.ai/api
+  wsUrl, // Revolt events, e.g. wss://stoat.corva.ai/ws
+  platform, // ChatPlatform, see below
+  storage, // KeyValueStorage: localStorage on web
+  corvaApi, // { get, post } against corva-api with the Corva JWT
+  appState, // { isHidden, isInactive, subscribe, onTerminate? }
+  dates, // { startOfTomorrowAt(hour, now) } in the user's timezone
+  notifier, // optional { showIncomingMessage, onMessageSent, onLogout }
+});
+
+await ensureChatSession(corvaUser);
+```
+
+| Host member | Web                                                        | React Native                            |
+| ----------- | ---------------------------------------------------------- | --------------------------------------- |
+| `storage`   | `localStorage`                                             | MMKV, or a hydrated in-memory map       |
+| `corvaApi`  | `apiCore` / `jsonApi` (`get` repeats array keys)           | the app's `ApiClient`                   |
+| `appState`  | `visibilityState`, `hasFocus()`, `pagehide`                | `AppState` (`background` counts hidden) |
+| `dates`     | `moment` with the user's timezone default                  | `date-fns` in the device timezone       |
+| `notifier`  | browser notification + sound, notification prompt, favicon | push/local notification, badge          |
+
+Stores are `zustand/vanilla` stores (`roomStore`, `messageStore`, …). React apps wrap them:
+
+```ts
+import { useStore } from 'zustand';
+import { roomStore } from '@corva/chat-core';
+
+export const useRoomStore = <T>(selector: (state: ReturnType<typeof roomStore.getState>) => T) =>
+  useStore(roomStore, selector);
+```
+
+## Platform adapter
+
+`ChatPlatform` (`src/platform/types.ts`) is the transport part of the host, also taken directly by
+`createRevoltAPI` and `createRevoltSocket`:
+
+| Member                    | Web                               | React Native                          |
+| ------------------------- | --------------------------------- | ------------------------------------- |
+| `fetch`                   | `(url, init) => fetch(url, init)` | same                                  |
+| `createWebSocket`         | `url => new WebSocket(url)`       | same                                  |
+| `createUploadBody`        | `FormData` with the `File`        | `FormData` with `{ uri, name, type }` |
+| `subscribeReconnectHints` | `online` + `visibilitychange`     | NetInfo + `AppState` `active`         |
+
+`typecheck/browserPlatform.ts` is a compile-only reference web adapter (platform and app state) that proves the browser APIs fit.
+
 ## Development
 
 ```sh