@chatinfra/client 0.0.5 → 0.0.6

package/README.md

@@ -0,0 +1,299 @@
+# ChatInfra SDK - Installation Guide
+
+This guide shows how to install and use the ChatInfra client SDK in:
+- React Native / Expo
+- Web (Browser)
+
+> Recommended: **do NOT ship your org secret key in mobile apps**. For production, mint tokens on your backend and return them to the app.
+> If you're prototyping, client-side token minting can work (as shown below).
+
+---
+
+## 1) Install (React Native / Expo)
+
+### A. Install dependencies
+
+```bash
+pnpm add @chatinfra/client
+pnpm add crypto-js
+pnpm add @pusher/pusher-websocket-react-native
+expo install expo-secure-store
+```
+
+### B. If you're using TypeScript
+```bash
+pnpm add -D @types/crypto-js
+```
+
+### C. Create a client wrapper (drop-in style)
+
+Create `src/services/chat/ChatInfraClient.ts`:
+
+```ts
+import CryptoJS from "crypto-js";
+import * as SecureStore from "expo-secure-store";
+
+import {
+  createChatClient,
+  PusherReactNativeTransport,
+  type Page,
+  type Message,
+  type Conversation,
+  type Identity,
+  type TokenStorage,
+} from "@chatinfra/client";
+
+export type { Identity, Conversation, Message, Page };
+
+type RealtimeCfg = { key: string; cluster: string; force_tls: boolean };
+
+type InitTokenPayload = {
+  widget_slug: string;
+  identity: {
+    external_id: string;
+    type_key: string;
+    fullname?: string | null;
+    email?: string | null;
+  };
+  ttl?: number;
+};
+
+type ClientOpts = {
+  apiBase: string;
+  widgetSlug: string;
+
+  // optional cached token
+  token?: string | null;
+
+  // client-side minting keys (prototype only)
+  orgPublicKey: string;
+  orgSecretKey: string;
+
+  // identity
+  identity: InitTokenPayload["identity"];
+
+  // optional
+  ttl?: number;
+  realtime?: RealtimeCfg | null;
+  tokenStorageKey?: string; // must be SecureStore-safe
+};
+
+function trimSlash(s: string) {
+  return (s || "").replace(/\/+$/, "");
+}
+
+// NOTE: SecureStore keys must be alphanumeric + dot + dash + underscore.
+// Avoid ":" in key names.
+function createExpoTokenStorage(prefix = "chatinfra_"): TokenStorage {
+  const keyOf = (k: string) => `${prefix}${k}`;
+  return {
+    async get(key: string) { return await SecureStore.getItemAsync(keyOf(key)); },
+    async set(key: string, value: string) { await SecureStore.setItemAsync(keyOf(key), value); },
+    async del(key: string) { await SecureStore.deleteItemAsync(keyOf(key)); },
+  };
+}
+
+async function safeJson(res: Response) {
+  const text = await res.text();
+  try { return JSON.parse(text); }
+  catch { throw new Error(`Non-JSON response (status ${res.status}): ${text}`); }
+}
+
+async function mintTokenWithOrgSecret(params: {
+  apiBase: string;
+  widgetSlug: string;
+  identity: InitTokenPayload["identity"];
+  ttl: number;
+  orgPublicKey: string;
+  orgSecretKey: string;
+}): Promise<string> {
+  const payload: InitTokenPayload = {
+    widget_slug: params.widgetSlug,
+    identity: params.identity,
+    ttl: params.ttl,
+  };
+
+  const raw = JSON.stringify(payload);
+  const ts = Math.floor(Date.now() / 1000);
+  const sig = CryptoJS.HmacSHA256(raw, params.orgSecretKey).toString(CryptoJS.enc.Hex);
+
+  const res = await fetch(params.apiBase + "/api/v1/widget/init", {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "X-ORG-KEY": params.orgPublicKey,
+      "X-TIMESTAMP": String(ts),
+      "X-SIGNATURE": sig,
+    },
+    body: raw,
+  });
+
+  const json = await safeJson(res);
+  if (!json?.ok) throw new Error(json?.message || "Failed to mint token");
+
+  const t = json?.data?.token || json?.data?.access_token;
+  if (!t) throw new Error("Token missing in response");
+  return String(t);
+}
+
+export class ChatInfraClient {
+  private sdk: ReturnType<typeof createChatClient>;
+  private me: Identity | null = null;
+  private rt: RealtimeCfg | null = null;
+
+  private storage: TokenStorage;
+  private tokenStorageKey: string;
+  private apiBase: string;
+
+  constructor(private opts: ClientOpts) {
+    this.apiBase = trimSlash(opts.apiBase);
+    this.storage = createExpoTokenStorage();
+    this.tokenStorageKey = opts.tokenStorageKey || "chatinfra_token"; // must be SecureStore-safe
+
+    this.sdk = createChatClient({
+      baseUrl: this.apiBase,
+      widgetSlug: opts.widgetSlug,
+
+      identity: {
+        externalId: opts.identity.external_id,
+        typeKey: opts.identity.type_key,
+        fullname: opts.identity.fullname ?? undefined,
+        email: opts.identity.email ?? undefined,
+      },
+
+      storage: this.storage,
+      tokenStorageKey: this.tokenStorageKey,
+
+      realtimeTransport: new PusherReactNativeTransport(),
+
+      tokenProvider: async () => {
+        if (opts.token) return String(opts.token);
+
+        const cached = await this.storage.get(this.tokenStorageKey);
+        if (cached) return cached;
+
+        const token = await mintTokenWithOrgSecret({
+          apiBase: this.apiBase,
+          widgetSlug: opts.widgetSlug,
+          identity: opts.identity,
+          ttl: typeof opts.ttl === "number" ? opts.ttl : 3600,
+          orgPublicKey: opts.orgPublicKey,
+          orgSecretKey: opts.orgSecretKey,
+        });
+
+        await this.storage.set(this.tokenStorageKey, token);
+        return token;
+      },
+    });
+
+    if (opts.realtime) {
+      this.sdk.setRealtimeConfig({
+        key: opts.realtime.key,
+        cluster: opts.realtime.cluster,
+        force_tls: !!opts.realtime.force_tls,
+      });
+      this.rt = opts.realtime;
+    }
+  }
+
+  async init() {
+    const info = await this.sdk.init();
+    this.me = info.me;
+
+    this.rt = info.realtime
+      ? ({ key: info.realtime.key, cluster: info.realtime.cluster, force_tls: !!info.realtime.force_tls } as any)
+      : (this.opts.realtime ?? null);
+
+    return { me: this.me!, realtime: this.rt, token: info.token };
+  }
+
+  async listConversations(cursor?: string | null) { return await this.sdk.listConversations(cursor ?? null); }
+  async listMessages(conversationId: number, cursor?: string | null) { return await this.sdk.listMessages(conversationId, cursor ?? null); }
+  async sendMessage(conversationId: number, body: string) { return await this.sdk.sendMessage(conversationId, body); }
+  async subscribeConversation(conversationId: number, handlers: any) { return await this.sdk.subscribeConversation(conversationId, handlers); }
+  async triggerTyping(conversationId: number, payload: any) { return await this.sdk.triggerTyping(conversationId, payload); }
+  async disconnect() { await this.sdk.disconnect(); }
+  getMe() { return this.me; }
+}
+```
+
+### D. Use it in your screen (same constructor shape)
+
+```ts
+const client = new ChatInfraClient({
+  apiBase: "https://your-chatinfra-domain.com",
+  widgetSlug: "drivon_customer",
+  token: cachedToken,
+
+  orgPublicKey: "pk_...",
+  orgSecretKey: "sk_...",
+
+  identity: {
+    external_id: "customer_123",
+    type_key: "customer",
+    fullname: "Ebuka Mbanusi",
+    email: "frankemmanuel249@gmail.com",
+  },
+});
+```
+
+---
+
+## 2) Install (Web)
+
+### A. Install dependencies
+
+```bash
+pnpm add @chatinfra/client
+pnpm add pusher-js
+```
+
+### B. If you ever see `@react-native-community/netinfo` in the import stack
+That means the **React Native build accidentally imported the web Pusher transport** (which uses `pusher-js/dist/react-native`).
+
+Fix:
+- In React Native, only use `PusherReactNativeTransport` and ensure you're importing from the RN entry (or from `@chatinfra/client` if it already exports the RN transport).
+- Remove `@chatinfra/realtime-pusher-web` from your RN dependency graph.
+
+---
+
+## 3) Troubleshooting
+
+### SecureStore: "Invalid key provided..."
+Expo SecureStore only accepts keys containing:
+- letters and numbers
+- `.`, `-`, `_`
+
+So these are invalid:
+- `chatinfra:token`  (contains `:`)
+
+Use safe keys like:
+- `chatinfra_token`
+- `chatinfra.token`
+- `chatinfra-token`
+
+In the wrapper above we use a safe prefix `chatinfra_`.
+
+### Conversations not listing but no error
+- Log your network calls:
+  - `/api/v1/widget/init` (token mint)
+  - `/api/v1/me`
+  - `/api/v1/conversations`
+- If `/api/v1/sdk/config` does not exist, pass `realtime` config in the constructor OR add that endpoint in your backend.
+
+---
+
+## 4) Minimal backend endpoints expected by the SDK
+
+- `POST /api/v1/widget/init` (if minting in client)
+- `GET /api/v1/me`
+- `GET /api/v1/conversations`
+- `GET /api/v1/conversations/{id}/messages`
+- `POST /api/v1/conversations/{id}/messages`
+- `POST /api/v1/broadcast/auth` (Pusher channel auth)
+
+---
+
+## License / Notes
+For production mobile apps, move token minting to your backend to avoid exposing org secrets.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@chatinfra/client",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "exports": {
     ".": {