@anakin824/prdg-chat-ui 0.1.0

package/NEXTJS-INTEGRATION.md

@@ -0,0 +1,196 @@
+# Embedding `@anakin824/prdg-chat-ui` in a Next.js app
+
+Use the **App Router** (`app/`) and **React 18+**. Chat components use client hooks and must live under a **client** boundary.
+
+## Install
+
+```bash
+npm install @anakin824/prdg-chat-ui @tanstack/react-query date-fns framer-motion wavesurfer.js yet-another-react-lightbox react-intersection-observer
+```
+
+Optional (browser NATS realtime):
+
+```bash
+npm install nats.ws
+```
+
+## Global styles
+
+Import once in the root layout (or any layout that wraps chat):
+
+```tsx
+// app/layout.tsx
+import "@anakin824/prdg-chat-ui/styles";
+```
+
+If the subpath is not resolved, use:
+
+```tsx
+import "@anakin824/prdg-chat-ui/dist/index.css";
+```
+
+## Provider (required)
+
+`ChatProvider` wraps **React Query** (`QueryClientProvider`) and chat context — use **one** provider around the UI that needs chat.
+
+Create a small client file:
+
+```tsx
+// app/chat-providers.tsx
+"use client";
+
+import { ChatProvider } from "@anakin824/prdg-chat-ui";
+import type { ReactNode } from "react";
+
+export function ChatProviders({
+  children,
+  apiUrl,
+  token,
+  userId,
+  tenantId,
+}: {
+  children: ReactNode;
+  apiUrl: string;
+  token: string;
+  userId: string;
+  tenantId: string;
+}) {
+  return (
+    <ChatProvider
+      apiUrl={apiUrl}
+      token={token}
+      userId={userId}
+      tenantId={tenantId}
+      natsWsUrl={process.env.NEXT_PUBLIC_NATS_WS_URL}
+      conduitlyTenantId={process.env.NEXT_PUBLIC_CONDUITLY_TENANT_ID}
+    >
+      {children}
+    </ChatProvider>
+  );
+}
+```
+
+### `ChatProvider` props (common)
+
+| Prop | Purpose |
+|------|---------|
+| `apiUrl` | prdg-chat HTTP API base URL (no trailing slash) |
+| `token` | Bearer JWT for the current user |
+| `userId` | prdg-chat **user** UUID |
+| `tenantId` | prdg-chat **tenant** UUID |
+| `natsWsUrl` | Optional `wss://` NATS URL (disables REST polling when connected) |
+| `conduitlyTenantId` | Conduitly tenant id for NATS subjects (if using NATS + Conduitly) |
+| `theme` | Optional `ChatTheme` overrides |
+| `onTokenRefresh` | Optional callback when the API returns 401 |
+| `callEnabled` | Show Calls UI in standalone layout |
+
+Do **not** wrap `ChatProvider` in a second `QueryClientProvider` unless you intentionally want two React Query trees.
+
+## `next.config` (optional)
+
+If you `npm link` the package or consume TypeScript source, add:
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: ["@anakin824/prdg-chat-ui"],
+};
+
+export default nextConfig;
+```
+
+Published `dist/` builds often work without this.
+
+## Full inbox page (`StandaloneChatPage`)
+
+Sidebar + main thread + composer + new-chat modal:
+
+```tsx
+// app/messages/page.tsx
+"use client";
+
+import { StandaloneChatPage } from "@anakin824/prdg-chat-ui";
+import { ChatProviders } from "../chat-providers";
+
+export default function MessagesPage() {
+  return (
+    <ChatProviders
+      apiUrl={process.env.NEXT_PUBLIC_CHAT_API_URL!}
+      token={/* your session JWT */}
+      userId={/* prdg-chat user id */}
+      tenantId={/* tenant id */}
+    >
+      <div style={{ flex: 1, minHeight: 0, display: "flex", flexDirection: "column" }}>
+        <StandaloneChatPage showNewChat />
+      </div>
+    </ChatProviders>
+  );
+}
+```
+
+Give the parent a bounded height (e.g. `height: 100vh` on a wrapper) so the thread scrolls correctly.
+
+Use `StandaloneChatPage` props (`conversationId`, `entityContext`, `peerUserId`, …) from `ChatPanelProps` / `StandaloneChatPageProps` for deep links or entity chats.
+
+## Entity / order chat (thread + composer only)
+
+Use `useChatPanelController` to resolve or create the entity conversation, then `ChatConversationView`:
+
+```tsx
+"use client";
+
+import { ChatConversationView, useChatPanelController } from "@anakin824/prdg-chat-ui";
+
+export function OrderChat({ orderUuid }: { orderUuid: string }) {
+  const { selectedId } = useChatPanelController({
+    entityContext: {
+      entity_ref: "order",
+      entity_uuid: orderUuid,
+      title: `Order ${orderUuid}`,
+    },
+  });
+
+  if (!selectedId) return <p>Preparing chat…</p>;
+
+  return (
+    <ChatConversationView
+      conversationId={selectedId}
+      header={<h2 style={{ margin: "0 0 8px", fontSize: 16 }}>Order discussion</h2>}
+    />
+  );
+}
+```
+
+Place `OrderChat` under `ChatProviders` (or any tree wrapped by `ChatProvider`).
+
+## Composable pieces
+
+Import and arrange your own layout:
+
+- `ChatInboxSidebar`, `ChatMainColumn` — split sidebar vs main (same building blocks as `StandaloneChatPage`).
+- `MessageThread`, `MessageInput` / `ChatComposer`, `TypingIndicator`, `ConversationList` — lower-level.
+
+See package exports in `src/chat/index.ts` (published types in `dist/index.d.ts`).
+
+## Environment variables
+
+| Variable | Role |
+|----------|------|
+| `NEXT_PUBLIC_CHAT_API_URL` | API base for `apiUrl` |
+| `NEXT_PUBLIC_NATS_WS_URL` | Optional NATS WebSocket URL |
+| `NEXT_PUBLIC_CONDUITLY_TENANT_ID` | Optional; aligns NATS subjects with Conduitly |
+
+Never expose long-lived secrets in `NEXT_PUBLIC_*`. Pass `token` from your session (server component or secure client session).
+
+## Publish to npm (maintainers)
+
+```bash
+cd web
+npm run build:lib
+npm login
+npm publish --access public
+```
+
+If you see **`ENEEDAUTH`**, run `npm login` (or set `NPM_TOKEN` and `.npmrc` as in [NPM-TOKEN-SETUP.md](./NPM-TOKEN-SETUP.md)).

package/NPM-TOKEN-SETUP.md

@@ -0,0 +1,79 @@
+# NPM access for `@anakin824/*` (FinPod-style)
+
+This mirrors the workflow used for `@anakin824/finpod-embedding` in ERP-POD: scoped package on the public npm registry, token-based auth, no committed secrets.
+
+## 1. Create an access token
+
+1. Open [npmjs.com](https://www.npmjs.com/) and sign in.
+2. Profile → **Access Tokens** → **Generate New Token** (Granular or Automation for CI).
+3. Copy the token once; store it in a password manager or CI secrets.
+
+## 2. Login locally
+
+**Option A — interactive**
+
+```bash
+npm login
+```
+
+**Option B — token as password (legacy)**
+
+```bash
+npm login --auth-type=legacy
+```
+
+Use your npm username, paste the **token** as the password, and your email.
+
+## 3. Scoped registry for `@anakin824` (recommended)
+
+Create or edit **`.npmrc`** in your user home directory or in `web/` (do **not** commit real tokens):
+
+```ini
+@anakin824:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+Then:
+
+```bash
+export NPM_TOKEN=npm_xxxxx   # Windows PowerShell: $env:NPM_TOKEN="npm_xxxxx"
+cd web
+npm whoami
+```
+
+## 4. Two-factor authentication (required for publish)
+
+npm **requires** one of the following before `npm publish` will succeed (you may see **`E403`** with a message about 2FA otherwise):
+
+1. **Enable 2FA on your npm account**  
+   [npmjs.com](https://www.npmjs.com/) → profile → **Account** → **Enable Two-Factor Authentication** (auth app or security keys).
+
+2. **Or** use a **granular access token** that is allowed to publish and satisfies npm’s policy:  
+   Profile → **Access Tokens** → **Generate New Token** → **Granular Access Token** →  
+   set **Packages and scopes** to the `@anakin824` scope (or the package), permission **Read and write**, and enable **“Bypass two-factor authentication for writes”** (or equivalent) if you publish from CI/automation without interactive OTP.
+
+After enabling 2FA, sign out and **`npm login`** again so your local session is upgraded.
+
+## 5. Publish
+
+Ensure the library builds:
+
+```bash
+cd web
+npm run build:lib
+npm publish --access public
+```
+
+`package.json` already includes `"publishConfig": { "access": "public" }` for scoped packages.
+
+**Do not** commit `.npmrc` with a literal `_authToken`. Use environment variables in CI (e.g. GitHub Actions `secrets.NPM_TOKEN`).
+
+### If you see `E403` / “Two-factor authentication … is required”
+
+That is **not** a bug in this repo — npm is enforcing account security. Fix it by enabling **2FA** on the publishing account and/or using a **granular token** with publish rights to `@anakin824/prdg-chat-ui`, then retry `npm publish`.
+
+## 6. Verify
+
+```bash
+npm view @anakin824/prdg-chat-ui version
+```

package/README.md

@@ -0,0 +1,39 @@
+# `@anakin824/prdg-chat-ui`
+
+Embeddable chat UI (React) for Prodigee / prdg-chat: provider, inbox sidebar, main column, entity thread + composer, and hooks.
+
+## Install
+
+```bash
+npm install @anakin824/prdg-chat-ui
+```
+
+Peer dependencies (install in your app): `react`, `react-dom`, `@tanstack/react-query`, `date-fns`, `framer-motion`, `wavesurfer.js`, `yet-another-react-lightbox`, `react-intersection-observer`. Optional: `nats.ws` for realtime.
+
+## Styles
+
+Import the bundled CSS once near your app root (FinPod-style subpath export):
+
+```ts
+import "@anakin824/prdg-chat-ui/styles";
+```
+
+## Library build (publish)
+
+Same pattern as FinPod embedding: **`npm run build:lib`** runs **`tsup`** and writes **`dist/`** (`index.js`, `index.mjs`, `index.d.ts`, `index.css`). **`prepublishOnly`** runs that automatically before **`npm publish`**.
+
+## Next.js embedding
+
+See **[NEXTJS-INTEGRATION.md](./NEXTJS-INTEGRATION.md)** for App Router setup, `ChatProvider`, `StandaloneChatPage`, and entity chat.
+
+## Auth / publish to npm
+
+See [NPM-TOKEN-SETUP.md](./NPM-TOKEN-SETUP.md) for scoped registry (`@anakin824`) and token-based login.
+
+## Develop this repo
+
+```bash
+npm run dev      # Next.js app
+npm run build:lib
+npm run build    # Next production build
+```