1548 lines
55 KiB
Markdown
1548 lines
55 KiB
Markdown
# Messaging UI SDK — Foundation (Plan 1 of 3) Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Build the transport-free core of `@insignia/iios-messaging-ui` — types, the `MessagingAdapter` contract, a shared conformance suite, a mock adapter, and the provider + hooks — proving the seam works with zero network.
|
|
|
|
**Architecture:** The core knows nothing about any transport. Hosts inject a `MessagingAdapter`; the provider holds it in context; hooks (`useConversations`, `useMessages`) call it. `iios-kernel-client` is reachable only from the `./adapters/kernel` subpath (Plan 3), never from core — enforced by a test, not convention. A conformance suite defines "a correct adapter" once, so the mock, kernel, and CRM adapters are all verified against one definition.
|
|
|
|
**Tech Stack:** TypeScript, React 19 (peer), tsup (ESM), vitest 3 + jsdom + @testing-library/react, pnpm workspaces.
|
|
|
|
**Spec:** `lynkeduppro-crm/docs/superpowers/specs/2026-07-17-messaging-sdk-design.md`
|
|
|
|
**Scope of this plan:** Package scaffold, test infra, types, adapter contract + conformance suite, mock adapter, provider, hooks, boundary enforcement. **Out of scope:** UI components and CSS (Plan 2); kernel adapter, CRM adapter, attachments, and the CRM migration (Plan 3).
|
|
|
|
---
|
|
|
|
## Context an engineer needs
|
|
|
|
**Read these first:**
|
|
- `packages/iios-message-web/` — the existing headless package. **This is the anti-pattern**, not the model: 109 lines, narrowed `send` API, no consumers. We are deliberately building the layer it refused to build.
|
|
- `lynkeduppro-crm/src/lib/messenger-api.ts` — the source of the adapter contract. Its `MessengerData`/`ThreadData` interfaces already survived two implementations (live + mock).
|
|
- `scripts/check-import-boundary.mjs` — the repo's dependency law.
|
|
|
|
**Repo facts that will bite you:**
|
|
- Root `vitest.config.ts` includes only `packages/**/src/**/*.{test,spec}.ts` — **`.tsx` is not matched**, and its `globalSetup` provisions a Postgres DB on port 5434 for every run. This package therefore gets its **own** `vitest.config.ts` with `environment: 'jsdom'` and **no** `globalSetup`. Never add a DB dependency to a pure-UI package.
|
|
- `tsconfig.base.json` sets `"module": "commonjs"` — every web package overrides this to `ESNext` + `moduleResolution: bundler` + `jsx: react-jsx`. Copy that override; don't fight the base.
|
|
- Packages are ESM-only (`"type": "module"`).
|
|
|
|
**The bug we are fixing (do not port it):** the CRM infers the current actor id by scanning for a message you sent (`messenger-api.ts:200-203`). Until you have sent in a thread, `myActorId` is `null`, so the REST poll fallback computes `mine: false` for **every** message. Root cause: the kernel's receipt event carries no `threadId`. Our fix is `adapter.currentActorId()` — identity is the adapter's job, stated explicitly. Task 8 has the regression test.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
| File | Responsibility |
|
|
|---|---|
|
|
| `packages/iios-messaging-ui/package.json` | Package manifest, exports map, scripts |
|
|
| `packages/iios-messaging-ui/tsup.config.ts` | ESM build, 3 entries (core, adapters/mock, adapters/kernel) |
|
|
| `packages/iios-messaging-ui/tsconfig.json` | ESNext + jsx override over base |
|
|
| `packages/iios-messaging-ui/vitest.config.ts` | jsdom, includes `.tsx`, **no** globalSetup |
|
|
| `src/types.ts` | Domain types only. Zero imports. |
|
|
| `src/adapter.ts` | The `MessagingAdapter` interface |
|
|
| `src/conformance.ts` | Shared suite defining a correct adapter (shipped, not test-only) |
|
|
| `src/conformance.test.ts` | Runs the suite against the mock adapter |
|
|
| `src/adapters/mock.ts` | In-memory adapter for demos/tests |
|
|
| `src/provider.tsx` | `MessagingProvider` + `useAdapter` |
|
|
| `src/hooks/use-conversations.ts` | Conversation list state |
|
|
| `src/hooks/use-messages.ts` | Thread state, optimistic send, subscribe reconciliation |
|
|
| `src/index.ts` | Public barrel |
|
|
| `src/boundary.test.ts` | Asserts core never imports a transport |
|
|
|
|
Files split by responsibility, not layer. `conformance.ts` ships in `src/` (not a test file) because Plan 3's adapters import it to verify themselves.
|
|
|
|
---
|
|
|
|
### Task 1: Package scaffold + test infrastructure
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/package.json`
|
|
- Create: `packages/iios-messaging-ui/tsconfig.json`
|
|
- Create: `packages/iios-messaging-ui/tsup.config.ts`
|
|
- Create: `packages/iios-messaging-ui/vitest.config.ts`
|
|
- Create: `packages/iios-messaging-ui/src/index.ts`
|
|
- Test: `packages/iios-messaging-ui/src/smoke.test.tsx`
|
|
|
|
- [ ] **Step 1: Create the package manifest**
|
|
|
|
Create `packages/iios-messaging-ui/package.json`:
|
|
|
|
```json
|
|
{
|
|
"name": "@insignia/iios-messaging-ui",
|
|
"version": "0.1.0",
|
|
"type": "module",
|
|
"main": "dist/index.js",
|
|
"module": "dist/index.js",
|
|
"types": "dist/index.d.ts",
|
|
"exports": {
|
|
".": {
|
|
"types": "./dist/index.d.ts",
|
|
"import": "./dist/index.js"
|
|
},
|
|
"./adapters/mock": {
|
|
"types": "./dist/adapters/mock.d.ts",
|
|
"import": "./dist/adapters/mock.js"
|
|
},
|
|
"./conformance": {
|
|
"types": "./dist/conformance.d.ts",
|
|
"import": "./dist/conformance.js"
|
|
},
|
|
"./styles.css": "./dist/styles.css"
|
|
},
|
|
"files": [
|
|
"dist"
|
|
],
|
|
"scripts": {
|
|
"build": "tsup",
|
|
"typecheck": "tsc --noEmit",
|
|
"test": "vitest run"
|
|
},
|
|
"peerDependencies": {
|
|
"react": ">=18"
|
|
},
|
|
"devDependencies": {
|
|
"@testing-library/dom": "^10.4.0",
|
|
"@testing-library/react": "^16.1.0",
|
|
"@types/react": "^19.0.0",
|
|
"jsdom": "^26.0.0",
|
|
"react": "^19.0.0",
|
|
"react-dom": "^19.0.0",
|
|
"tsup": "^8.3.5",
|
|
"typescript": "^5.7.3",
|
|
"vitest": "^3.0.5"
|
|
},
|
|
"publishConfig": {
|
|
"registry": "https://git.lynkedup.cloud/api/packages/insignia/npm/"
|
|
}
|
|
}
|
|
```
|
|
|
|
Note: **no `dependencies`.** The core must stay transport-free. `./adapters/kernel` and its `@insignia/iios-kernel-client` dependency arrive in Plan 3. `./styles.css` is declared now but produced in Plan 2.
|
|
|
|
- [ ] **Step 2: Create tsconfig**
|
|
|
|
Create `packages/iios-messaging-ui/tsconfig.json`:
|
|
|
|
```json
|
|
{
|
|
"extends": "../../tsconfig.base.json",
|
|
"compilerOptions": {
|
|
"outDir": "./dist",
|
|
"rootDir": "./src",
|
|
"module": "ESNext",
|
|
"moduleResolution": "bundler",
|
|
"lib": ["ES2022", "DOM"],
|
|
"jsx": "react-jsx",
|
|
"types": ["react"]
|
|
},
|
|
"include": ["src/**/*.ts", "src/**/*.tsx"],
|
|
"exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Create the build config**
|
|
|
|
Create `packages/iios-messaging-ui/tsup.config.ts`:
|
|
|
|
```ts
|
|
import { defineConfig } from 'tsup';
|
|
|
|
export default defineConfig({
|
|
// `conformance` is its own entry, never reachable from `index`. It imports vitest,
|
|
// and bundling that into the main barrel would drag a test runner into every
|
|
// consumer's production build.
|
|
entry: ['src/index.ts', 'src/adapters/mock.ts', 'src/conformance.ts'],
|
|
format: ['esm'],
|
|
dts: true,
|
|
clean: true,
|
|
external: ['react', 'react-dom', 'vitest'],
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 4: Create the package's own vitest config**
|
|
|
|
Create `packages/iios-messaging-ui/vitest.config.ts`:
|
|
|
|
```ts
|
|
import { defineConfig } from 'vitest/config';
|
|
|
|
// This package owns its vitest config on purpose. The ROOT config includes only
|
|
// `.ts` (never `.tsx`) and provisions a Postgres DB via globalSetup for every run —
|
|
// a pure-UI package must not drag a database along, and its tests are .tsx.
|
|
export default defineConfig({
|
|
test: {
|
|
environment: 'jsdom',
|
|
include: ['src/**/*.{test,spec}.{ts,tsx}'],
|
|
globals: false,
|
|
},
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 5: Create a placeholder barrel**
|
|
|
|
Create `packages/iios-messaging-ui/src/index.ts`:
|
|
|
|
```ts
|
|
export {};
|
|
```
|
|
|
|
- [ ] **Step 6: Write the failing smoke test**
|
|
|
|
Create `packages/iios-messaging-ui/src/smoke.test.tsx`:
|
|
|
|
```tsx
|
|
import { describe, it, expect } from 'vitest';
|
|
import { render, screen } from '@testing-library/react';
|
|
|
|
describe('test infrastructure', () => {
|
|
it('renders React components in jsdom', () => {
|
|
render(<div>messaging-ui</div>);
|
|
expect(screen.getByText('messaging-ui')).toBeDefined();
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 7: Install dependencies**
|
|
|
|
Run from the repo root:
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
Expected: pnpm links the new workspace package; `@testing-library/react`, `jsdom`, `react-dom` resolve.
|
|
|
|
- [ ] **Step 8: Run the test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS, 1 test. If it fails with "document is not defined", `environment: 'jsdom'` did not take effect — check you created `vitest.config.ts` in the package dir, not the root.
|
|
|
|
- [ ] **Step 9: Verify typecheck and build**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui typecheck && pnpm --filter @insignia/iios-messaging-ui build`
|
|
Expected: no type errors; `dist/index.js` + `dist/index.d.ts` produced.
|
|
|
|
- [ ] **Step 10: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui
|
|
git commit -m "chore: scaffold @insignia/iios-messaging-ui with jsdom test setup"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Domain types
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/types.ts`
|
|
- Test: `packages/iios-messaging-ui/src/types.test.ts`
|
|
|
|
These are the SDK's own types — deliberately **not** re-exported from `iios-kernel-client`, because core must not depend on it. Adapters map kernel/CRM DTOs onto these. Shape is taken from the CRM's `UiConversation`/`UiMessage`/`UiPerson`, which are already proven.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/types.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest';
|
|
import { isOwnMessage } from './types';
|
|
import type { Message } from './types';
|
|
|
|
const base: Message = {
|
|
id: 'm1',
|
|
actorId: 'actor_a',
|
|
text: 'hello',
|
|
at: '2026-07-17T10:00:00.000Z',
|
|
};
|
|
|
|
describe('isOwnMessage', () => {
|
|
it('is true when the message actor matches the current actor', () => {
|
|
expect(isOwnMessage(base, 'actor_a')).toBe(true);
|
|
});
|
|
|
|
it('is false when the actors differ', () => {
|
|
expect(isOwnMessage(base, 'actor_b')).toBe(false);
|
|
});
|
|
|
|
it('is false when the current actor is unknown', () => {
|
|
expect(isOwnMessage(base, null)).toBe(false);
|
|
});
|
|
|
|
it('is false when the message has no actor', () => {
|
|
expect(isOwnMessage({ ...base, actorId: null }, 'actor_a')).toBe(false);
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: FAIL — "Failed to resolve import ./types" or "isOwnMessage is not a function".
|
|
|
|
- [ ] **Step 3: Write the implementation**
|
|
|
|
Create `packages/iios-messaging-ui/src/types.ts`:
|
|
|
|
```ts
|
|
// Domain types for the messaging UI. Zero imports on purpose: this file must never
|
|
// reach for a transport package. Adapters map their own DTOs onto these.
|
|
|
|
export type Membership = 'dm' | 'group';
|
|
|
|
export interface Person {
|
|
id: string;
|
|
name: string;
|
|
kind: 'staff' | 'customer';
|
|
}
|
|
|
|
export interface Conversation {
|
|
threadId: string;
|
|
title: string;
|
|
subject: string | null;
|
|
membership: Membership | null;
|
|
participants: string[];
|
|
unread: number;
|
|
lastMessage?: string;
|
|
lastAt?: string;
|
|
}
|
|
|
|
export interface Reaction {
|
|
emoji: string;
|
|
count: number;
|
|
mine: boolean;
|
|
}
|
|
|
|
export interface Attachment {
|
|
url: string;
|
|
mime: string;
|
|
name: string;
|
|
}
|
|
|
|
export interface Message {
|
|
id: string;
|
|
actorId: string | null;
|
|
text: string;
|
|
at: string;
|
|
parentInteractionId?: string | null;
|
|
reactions?: Reaction[];
|
|
attachment?: Attachment;
|
|
/** True only when the transport is optimistic-local and not yet acknowledged. */
|
|
pending?: boolean;
|
|
}
|
|
|
|
export interface SendOpts {
|
|
parentInteractionId?: string;
|
|
attachment?: Attachment;
|
|
}
|
|
|
|
export type MessageEvent =
|
|
| { kind: 'message'; message: Message }
|
|
| { kind: 'typing'; userId: string }
|
|
| { kind: 'receipt'; messageId: string; actorId: string }
|
|
| { kind: 'reaction'; messageId: string; reactions: Reaction[] };
|
|
|
|
export type Unsubscribe = () => void;
|
|
|
|
/** Ownership is a pure function of explicit identity — never inferred from history.
|
|
* See the spec: inferring it is the bug this SDK exists partly to kill. */
|
|
export function isOwnMessage(message: Message, currentActorId: string | null): boolean {
|
|
return currentActorId !== null && message.actorId !== null && message.actorId === currentActorId;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS, 5 tests (4 new + smoke).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/types.ts packages/iios-messaging-ui/src/types.test.ts
|
|
git commit -m "feat: add messaging-ui domain types"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: The MessagingAdapter contract
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/adapter.ts`
|
|
|
|
An interface has no runtime behaviour to test directly; Task 4's conformance suite is its test. This task is type-only, so it is verified by `typecheck`.
|
|
|
|
- [ ] **Step 1: Write the interface**
|
|
|
|
Create `packages/iios-messaging-ui/src/adapter.ts`:
|
|
|
|
```ts
|
|
import type {
|
|
Attachment,
|
|
Conversation,
|
|
Membership,
|
|
Message,
|
|
MessageEvent,
|
|
SendOpts,
|
|
Unsubscribe,
|
|
} from './types';
|
|
|
|
/**
|
|
* The one seam of this SDK. Hosts implement this; the SDK renders it.
|
|
*
|
|
* Lifted from lynkeduppro-crm's MessengerData/ThreadData, which already survived
|
|
* two implementations (live data-door + mock) — the minimum real evidence that a
|
|
* seam is genuine rather than imagined.
|
|
*
|
|
* Optional methods degrade gracefully: the UI hides the reaction picker when
|
|
* `react` is absent, and the attach button when `upload` is absent. That is how one
|
|
* component set serves both a full CRM messenger and a stripped-down widget with no
|
|
* `mode` prop.
|
|
*/
|
|
export interface MessagingAdapter {
|
|
listConversations(): Promise<Conversation[]>;
|
|
|
|
openThread(p: { participantIds: string[]; membership?: Membership; subject?: string }): Promise<{ threadId: string }>;
|
|
|
|
history(threadId: string): Promise<Message[]>;
|
|
|
|
send(threadId: string, content: string, opts?: SendOpts): Promise<Message>;
|
|
|
|
/** Returns an unsubscribe fn. Implementations MUST be idempotent on repeat unsubscribe. */
|
|
subscribe(threadId: string, cb: (e: MessageEvent) => void): Unsubscribe;
|
|
|
|
sendTyping(threadId: string): void;
|
|
|
|
markRead(threadId: string, messageId: string): Promise<void>;
|
|
|
|
/**
|
|
* The current user's actor id, or null if not yet known.
|
|
*
|
|
* MUST NOT be inferred from message history. The CRM's bug was exactly that:
|
|
* scanning for a sent message meant every message read as not-yours until you
|
|
* had spoken. Adapters derive this from auth/session.
|
|
*/
|
|
currentActorId(): string | null;
|
|
|
|
/** Absent => the UI hides reactions entirely. */
|
|
react?(threadId: string, messageId: string, emoji: string): Promise<void>;
|
|
|
|
/** Absent => the UI hides attachments. Storage/auth/limits are the host's concern. */
|
|
upload?(file: File): Promise<Attachment>;
|
|
|
|
/** Absent => treated as always connected (e.g. a pure-REST adapter). */
|
|
isConnected?(): boolean;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Verify it typechecks**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui typecheck`
|
|
Expected: no errors.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/adapter.ts
|
|
git commit -m "feat: define MessagingAdapter contract"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Adapter conformance suite
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/conformance.ts`
|
|
|
|
This ships in `src/` (not as a `.test.ts`) because Plan 3's kernel and CRM adapters import it to verify themselves. One definition of "correct adapter", three implementations checked against it.
|
|
|
|
- [ ] **Step 1: Write the suite**
|
|
|
|
Create `packages/iios-messaging-ui/src/conformance.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest';
|
|
import type { MessagingAdapter } from './adapter';
|
|
import type { MessageEvent } from './types';
|
|
|
|
export interface ConformanceOptions {
|
|
/** Build a fresh, isolated adapter per test. */
|
|
makeAdapter: () => Promise<MessagingAdapter> | MessagingAdapter;
|
|
/** A thread id that exists in the fixture. */
|
|
seededThreadId: string;
|
|
/** Participant ids openThread can legally be called with. */
|
|
openWith: string[];
|
|
}
|
|
|
|
/**
|
|
* The definition of a correct MessagingAdapter. Every adapter runs this.
|
|
*
|
|
* Imports vitest, so it ships from the './conformance' subpath ONLY and is never
|
|
* reachable from the main barrel. Consumers supply their own vitest.
|
|
*
|
|
* Usage from another package:
|
|
* import { runAdapterConformance } from '@insignia/iios-messaging-ui/conformance';
|
|
* runAdapterConformance({ makeAdapter: () => new MockAdapter(), seededThreadId: 'th_1', openWith: ['pp_a'] });
|
|
*/
|
|
export function runAdapterConformance(opts: ConformanceOptions): void {
|
|
const make = async () => await opts.makeAdapter();
|
|
|
|
describe('MessagingAdapter conformance', () => {
|
|
it('lists conversations', async () => {
|
|
const a = await make();
|
|
const list = await a.listConversations();
|
|
expect(Array.isArray(list)).toBe(true);
|
|
});
|
|
|
|
it('returns history for a seeded thread', async () => {
|
|
const a = await make();
|
|
const msgs = await a.history(opts.seededThreadId);
|
|
expect(Array.isArray(msgs)).toBe(true);
|
|
});
|
|
|
|
it('send resolves with a message carrying the sent text and a stable id', async () => {
|
|
const a = await make();
|
|
const m = await a.send(opts.seededThreadId, 'conformance hello');
|
|
expect(m.text).toBe('conformance hello');
|
|
expect(typeof m.id).toBe('string');
|
|
expect(m.id.length).toBeGreaterThan(0);
|
|
});
|
|
|
|
it('a sent message is attributed to the current actor', async () => {
|
|
const a = await make();
|
|
const m = await a.send(opts.seededThreadId, 'whose is this');
|
|
expect(m.actorId).toBe(a.currentActorId());
|
|
});
|
|
|
|
it('currentActorId is known BEFORE any message is sent', async () => {
|
|
// The bug this SDK exists to kill: identity must come from auth, never be
|
|
// inferred from history. A fresh adapter already knows who you are.
|
|
const a = await make();
|
|
expect(a.currentActorId()).not.toBeNull();
|
|
});
|
|
|
|
it('a sent message appears in history', async () => {
|
|
const a = await make();
|
|
await a.send(opts.seededThreadId, 'persist me');
|
|
const msgs = await a.history(opts.seededThreadId);
|
|
expect(msgs.some((m) => m.text === 'persist me')).toBe(true);
|
|
});
|
|
|
|
it('subscribe delivers a message event on send', async () => {
|
|
const a = await make();
|
|
const seen: MessageEvent[] = [];
|
|
const off = a.subscribe(opts.seededThreadId, (e) => seen.push(e));
|
|
await a.send(opts.seededThreadId, 'live one');
|
|
off();
|
|
const msgs = seen.filter((e) => e.kind === 'message');
|
|
expect(msgs.length).toBeGreaterThan(0);
|
|
});
|
|
|
|
it('unsubscribe stops delivery', async () => {
|
|
const a = await make();
|
|
const seen: MessageEvent[] = [];
|
|
const off = a.subscribe(opts.seededThreadId, (e) => seen.push(e));
|
|
off();
|
|
await a.send(opts.seededThreadId, 'should not be heard');
|
|
expect(seen).toHaveLength(0);
|
|
});
|
|
|
|
it('unsubscribe is idempotent', async () => {
|
|
const a = await make();
|
|
const off = a.subscribe(opts.seededThreadId, () => {});
|
|
off();
|
|
expect(() => off()).not.toThrow();
|
|
});
|
|
|
|
it('openThread returns a thread id', async () => {
|
|
const a = await make();
|
|
const { threadId } = await a.openThread({ participantIds: opts.openWith });
|
|
expect(typeof threadId).toBe('string');
|
|
expect(threadId.length).toBeGreaterThan(0);
|
|
});
|
|
|
|
it('markRead resolves', async () => {
|
|
const a = await make();
|
|
const m = await a.send(opts.seededThreadId, 'read me');
|
|
await expect(a.markRead(opts.seededThreadId, m.id)).resolves.toBeUndefined();
|
|
});
|
|
|
|
it('sendTyping does not throw', async () => {
|
|
const a = await make();
|
|
expect(() => a.sendTyping(opts.seededThreadId)).not.toThrow();
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Verify it typechecks**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui typecheck`
|
|
Expected: no errors. (The suite has no adapter to run against yet — that is Task 5.)
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/conformance.ts
|
|
git commit -m "feat: add adapter conformance suite"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Mock adapter
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/adapters/mock.ts`
|
|
- Test: `packages/iios-messaging-ui/src/conformance.test.ts`
|
|
|
|
Ported from the CRM's `MOCK_STORE`, with one deliberate change: **the store is per-instance, not module-level.** The CRM's module-level `Map` leaks state between tests. Fixtures match the CRM's so demo mode looks identical after migration.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/conformance.test.ts`:
|
|
|
|
```ts
|
|
import { runAdapterConformance } from './conformance';
|
|
import { MockAdapter } from './adapters/mock';
|
|
|
|
runAdapterConformance({
|
|
makeAdapter: () => new MockAdapter(),
|
|
seededThreadId: 'th_mock_1',
|
|
openWith: ['pp_sofia'],
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: FAIL — "Failed to resolve import ./adapters/mock".
|
|
|
|
- [ ] **Step 3: Write the implementation**
|
|
|
|
Create `packages/iios-messaging-ui/src/adapters/mock.ts`:
|
|
|
|
```ts
|
|
import type { MessagingAdapter } from '../adapter';
|
|
import type {
|
|
Attachment,
|
|
Conversation,
|
|
Membership,
|
|
Message,
|
|
MessageEvent,
|
|
Person,
|
|
SendOpts,
|
|
Unsubscribe,
|
|
} from '../types';
|
|
|
|
const ME = 'me';
|
|
|
|
export const MOCK_PEOPLE: Person[] = [
|
|
{ id: 'pp_sofia', name: 'Sofia Ramirez', kind: 'staff' },
|
|
{ id: 'pp_dan', name: 'Dan Whitaker', kind: 'staff' },
|
|
{ id: 'pp_priya', name: 'Priya Nair', kind: 'staff' },
|
|
{ id: 'cust_acme', name: 'Acme Roofing (Client)', kind: 'customer' },
|
|
{ id: 'cust_globex', name: 'Globex Homes (Client)', kind: 'customer' },
|
|
];
|
|
|
|
interface MockThread {
|
|
threadId: string;
|
|
membership: Membership;
|
|
subject: string | null;
|
|
participants: string[];
|
|
messages: Message[];
|
|
}
|
|
|
|
const nameById = new Map(MOCK_PEOPLE.map((p) => [p.id, p.name]));
|
|
|
|
/**
|
|
* In-memory adapter for demos and tests. State is PER INSTANCE — the CRM's version
|
|
* used a module-level Map, which leaks between tests. Each `new MockAdapter()` is
|
|
* fully isolated.
|
|
*/
|
|
export class MockAdapter implements MessagingAdapter {
|
|
private seq = 100;
|
|
private threads = new Map<string, MockThread>();
|
|
private listeners = new Map<string, Set<(e: MessageEvent) => void>>();
|
|
|
|
constructor(private readonly now: () => string = () => new Date().toISOString()) {
|
|
this.threads.set('th_mock_1', {
|
|
threadId: 'th_mock_1',
|
|
membership: 'dm',
|
|
subject: null,
|
|
participants: [ME, 'pp_sofia'],
|
|
messages: [
|
|
{
|
|
id: 'm1',
|
|
actorId: 'pp_sofia',
|
|
text: 'Can you review the Henderson estimate?',
|
|
at: this.now(),
|
|
reactions: [],
|
|
},
|
|
],
|
|
});
|
|
this.threads.set('th_mock_2', {
|
|
threadId: 'th_mock_2',
|
|
membership: 'group',
|
|
subject: 'Storm response — East side',
|
|
participants: [ME, 'pp_dan', 'pp_priya'],
|
|
messages: [
|
|
{ id: 'm2', actorId: 'pp_dan', text: 'Crew is rolling out at 7.', at: this.now(), reactions: [] },
|
|
],
|
|
});
|
|
}
|
|
|
|
currentActorId(): string {
|
|
return ME;
|
|
}
|
|
|
|
async listConversations(): Promise<Conversation[]> {
|
|
return [...this.threads.values()].map((t) => {
|
|
const last = t.messages[t.messages.length - 1];
|
|
const others = t.participants.filter((p) => p !== ME);
|
|
return {
|
|
threadId: t.threadId,
|
|
title: t.subject || others.map((id) => nameById.get(id) ?? id).join(', ') || 'Conversation',
|
|
subject: t.subject,
|
|
membership: t.membership,
|
|
participants: t.participants,
|
|
unread: 0,
|
|
...(last ? { lastMessage: last.text, lastAt: last.at } : {}),
|
|
};
|
|
});
|
|
}
|
|
|
|
async openThread(p: { participantIds: string[]; membership?: Membership; subject?: string }): Promise<{ threadId: string }> {
|
|
const membership = p.membership ?? (p.participantIds.length === 1 ? 'dm' : 'group');
|
|
const threadId = `th_mock_${this.seq++}`;
|
|
this.threads.set(threadId, {
|
|
threadId,
|
|
membership,
|
|
subject: p.subject ?? null,
|
|
participants: [ME, ...p.participantIds],
|
|
messages: [],
|
|
});
|
|
return { threadId };
|
|
}
|
|
|
|
async history(threadId: string): Promise<Message[]> {
|
|
return this.threads.get(threadId)?.messages ?? [];
|
|
}
|
|
|
|
async send(threadId: string, content: string, opts?: SendOpts): Promise<Message> {
|
|
const t = this.threads.get(threadId);
|
|
if (!t) throw new Error(`Unknown thread: ${threadId}`);
|
|
const message: Message = {
|
|
id: `m_${this.seq++}`,
|
|
actorId: ME,
|
|
text: content,
|
|
at: this.now(),
|
|
reactions: [],
|
|
...(opts?.parentInteractionId ? { parentInteractionId: opts.parentInteractionId } : {}),
|
|
...(opts?.attachment ? { attachment: opts.attachment } : {}),
|
|
};
|
|
t.messages = [...t.messages, message];
|
|
this.emit(threadId, { kind: 'message', message });
|
|
return message;
|
|
}
|
|
|
|
async react(threadId: string, messageId: string, emoji: string): Promise<void> {
|
|
const t = this.threads.get(threadId);
|
|
if (!t) return;
|
|
let next: Message | undefined;
|
|
t.messages = t.messages.map((m) => {
|
|
if (m.id !== messageId) return m;
|
|
const existing = (m.reactions ?? []).find((r) => r.emoji === emoji);
|
|
const reactions = existing
|
|
? (m.reactions ?? []).filter((r) => r.emoji !== emoji)
|
|
: [...(m.reactions ?? []), { emoji, count: 1, mine: true }];
|
|
next = { ...m, reactions };
|
|
return next;
|
|
});
|
|
if (next) this.emit(threadId, { kind: 'reaction', messageId, reactions: next.reactions ?? [] });
|
|
}
|
|
|
|
async upload(file: File): Promise<Attachment> {
|
|
return { url: `mock://uploads/${file.name}`, mime: file.type, name: file.name };
|
|
}
|
|
|
|
subscribe(threadId: string, cb: (e: MessageEvent) => void): Unsubscribe {
|
|
if (!this.listeners.has(threadId)) this.listeners.set(threadId, new Set());
|
|
this.listeners.get(threadId)!.add(cb);
|
|
return () => {
|
|
this.listeners.get(threadId)?.delete(cb);
|
|
};
|
|
}
|
|
|
|
sendTyping(): void {
|
|
// No-op: nobody is typing back in a mock.
|
|
}
|
|
|
|
async markRead(): Promise<void> {
|
|
// No-op: the mock has no second party to report a read.
|
|
}
|
|
|
|
isConnected(): boolean {
|
|
return true;
|
|
}
|
|
|
|
private emit(threadId: string, e: MessageEvent): void {
|
|
this.listeners.get(threadId)?.forEach((cb) => cb(e));
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS — 12 conformance tests green.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/adapters/mock.ts packages/iios-messaging-ui/src/conformance.test.ts
|
|
git commit -m "feat: add MockAdapter passing the conformance suite"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: MessagingProvider
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/provider.tsx`
|
|
- Test: `packages/iios-messaging-ui/src/provider.test.tsx`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/provider.test.tsx`:
|
|
|
|
```tsx
|
|
import { describe, it, expect } from 'vitest';
|
|
import { render, screen } from '@testing-library/react';
|
|
import { MessagingProvider, useAdapter } from './provider';
|
|
import { MockAdapter } from './adapters/mock';
|
|
|
|
function ShowActor() {
|
|
const adapter = useAdapter();
|
|
return <span>{adapter.currentActorId()}</span>;
|
|
}
|
|
|
|
describe('MessagingProvider', () => {
|
|
it('supplies the injected adapter to descendants', () => {
|
|
render(
|
|
<MessagingProvider adapter={new MockAdapter()}>
|
|
<ShowActor />
|
|
</MessagingProvider>,
|
|
);
|
|
expect(screen.getByText('me')).toBeDefined();
|
|
});
|
|
|
|
it('throws a helpful error when a hook is used outside the provider', () => {
|
|
// React logs the error boundary trace; that noise is expected.
|
|
expect(() => render(<ShowActor />)).toThrow(/useAdapter must be used within a <MessagingProvider>/);
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: FAIL — "Failed to resolve import ./provider".
|
|
|
|
- [ ] **Step 3: Write the implementation**
|
|
|
|
Create `packages/iios-messaging-ui/src/provider.tsx`:
|
|
|
|
```tsx
|
|
import { createContext, useContext, type ReactNode } from 'react';
|
|
import type { MessagingAdapter } from './adapter';
|
|
|
|
const AdapterContext = createContext<MessagingAdapter | null>(null);
|
|
|
|
export function MessagingProvider({
|
|
adapter,
|
|
children,
|
|
}: {
|
|
adapter: MessagingAdapter;
|
|
children: ReactNode;
|
|
}) {
|
|
return <AdapterContext.Provider value={adapter}>{children}</AdapterContext.Provider>;
|
|
}
|
|
|
|
/** Access the host-injected adapter. Throws outside a provider — a missing provider is
|
|
* a wiring bug, and failing loudly beats a confusing null-deref three layers down. */
|
|
export function useAdapter(): MessagingAdapter {
|
|
const adapter = useContext(AdapterContext);
|
|
if (!adapter) throw new Error('useAdapter must be used within a <MessagingProvider>');
|
|
return adapter;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS, 2 new tests.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/provider.tsx packages/iios-messaging-ui/src/provider.test.tsx
|
|
git commit -m "feat: add MessagingProvider and useAdapter"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: useConversations
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/hooks/use-conversations.ts`
|
|
- Test: `packages/iios-messaging-ui/src/hooks/use-conversations.test.tsx`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/hooks/use-conversations.test.tsx`:
|
|
|
|
```tsx
|
|
import { describe, it, expect, vi } from 'vitest';
|
|
import { renderHook, waitFor, act } from '@testing-library/react';
|
|
import type { ReactNode } from 'react';
|
|
import { MessagingProvider } from '../provider';
|
|
import { MockAdapter } from '../adapters/mock';
|
|
import { useConversations } from './use-conversations';
|
|
import type { MessagingAdapter } from '../adapter';
|
|
|
|
const wrap = (adapter: MessagingAdapter) =>
|
|
function Wrapper({ children }: { children: ReactNode }) {
|
|
return <MessagingProvider adapter={adapter}>{children}</MessagingProvider>;
|
|
};
|
|
|
|
describe('useConversations', () => {
|
|
it('starts loading, then resolves the adapter list', async () => {
|
|
const { result } = renderHook(() => useConversations(), { wrapper: wrap(new MockAdapter()) });
|
|
expect(result.current.loading).toBe(true);
|
|
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
expect(result.current.conversations).toHaveLength(2);
|
|
expect(result.current.conversations[0]!.threadId).toBe('th_mock_1');
|
|
expect(result.current.error).toBeNull();
|
|
});
|
|
|
|
it('surfaces adapter failure as error state and never throws', async () => {
|
|
const adapter = new MockAdapter();
|
|
vi.spyOn(adapter, 'listConversations').mockRejectedValue(new Error('data door down'));
|
|
|
|
const { result } = renderHook(() => useConversations(), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
expect(result.current.error).toBe('data door down');
|
|
expect(result.current.conversations).toEqual([]);
|
|
});
|
|
|
|
it('refetch picks up newly opened threads', async () => {
|
|
const adapter = new MockAdapter();
|
|
const { result } = renderHook(() => useConversations(), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.conversations).toHaveLength(2));
|
|
|
|
await act(async () => {
|
|
await adapter.openThread({ participantIds: ['pp_dan'] });
|
|
});
|
|
await act(async () => {
|
|
result.current.refetch();
|
|
});
|
|
|
|
await waitFor(() => expect(result.current.conversations).toHaveLength(3));
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: FAIL — "Failed to resolve import ./use-conversations".
|
|
|
|
- [ ] **Step 3: Write the implementation**
|
|
|
|
Create `packages/iios-messaging-ui/src/hooks/use-conversations.ts`:
|
|
|
|
```ts
|
|
import { useCallback, useEffect, useState } from 'react';
|
|
import { useAdapter } from '../provider';
|
|
import type { Conversation } from '../types';
|
|
|
|
export interface ConversationsState {
|
|
conversations: Conversation[];
|
|
loading: boolean;
|
|
error: string | null;
|
|
refetch: () => void;
|
|
}
|
|
|
|
export function useConversations(): ConversationsState {
|
|
const adapter = useAdapter();
|
|
const [conversations, setConversations] = useState<Conversation[]>([]);
|
|
const [loading, setLoading] = useState(true);
|
|
const [error, setError] = useState<string | null>(null);
|
|
const [nonce, setNonce] = useState(0);
|
|
|
|
useEffect(() => {
|
|
let alive = true;
|
|
setLoading(true);
|
|
adapter
|
|
.listConversations()
|
|
.then((list) => {
|
|
if (!alive) return;
|
|
setConversations(list);
|
|
setError(null);
|
|
})
|
|
.catch((e: unknown) => {
|
|
if (!alive) return;
|
|
setError(e instanceof Error ? e.message : String(e));
|
|
setConversations([]);
|
|
})
|
|
.finally(() => {
|
|
if (alive) setLoading(false);
|
|
});
|
|
return () => {
|
|
alive = false;
|
|
};
|
|
}, [adapter, nonce]);
|
|
|
|
const refetch = useCallback(() => setNonce((n) => n + 1), []);
|
|
|
|
return { conversations, loading, error, refetch };
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS, 3 new tests.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/hooks
|
|
git commit -m "feat: add useConversations hook"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 8: useMessages
|
|
|
|
**Files:**
|
|
- Create: `packages/iios-messaging-ui/src/hooks/use-messages.ts`
|
|
- Test: `packages/iios-messaging-ui/src/hooks/use-messages.test.tsx`
|
|
|
|
The heart of the SDK. Three behaviours matter most: **ownership before you speak** (the CRM bug), **optimistic send with rollback**, and **event reconciliation by id** (no duplicates when the echo arrives).
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/hooks/use-messages.test.tsx`:
|
|
|
|
```tsx
|
|
import { describe, it, expect, vi } from 'vitest';
|
|
import { renderHook, waitFor, act } from '@testing-library/react';
|
|
import type { ReactNode } from 'react';
|
|
import { MessagingProvider } from '../provider';
|
|
import { MockAdapter } from '../adapters/mock';
|
|
import { useMessages } from './use-messages';
|
|
import type { MessagingAdapter } from '../adapter';
|
|
|
|
const wrap = (adapter: MessagingAdapter) =>
|
|
function Wrapper({ children }: { children: ReactNode }) {
|
|
return <MessagingProvider adapter={adapter}>{children}</MessagingProvider>;
|
|
};
|
|
|
|
describe('useMessages', () => {
|
|
it('loads history for the thread', async () => {
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(new MockAdapter()) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
expect(result.current.messages).toHaveLength(1);
|
|
expect(result.current.messages[0]!.text).toBe('Can you review the Henderson estimate?');
|
|
});
|
|
|
|
// REGRESSION: the CRM inferred actor identity by scanning for a sent message, so
|
|
// before you had spoken in a thread EVERY message rendered as not-yours.
|
|
it('marks ownership correctly before the user has sent anything', async () => {
|
|
const adapter = new MockAdapter();
|
|
await adapter.send('th_mock_1', 'an earlier message of mine');
|
|
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.messages).toHaveLength(2));
|
|
|
|
// Never sent anything via the hook — ownership still resolves from currentActorId().
|
|
expect(result.current.messages[0]!.mine).toBe(false); // from pp_sofia
|
|
expect(result.current.messages[1]!.mine).toBe(true); // from me
|
|
});
|
|
|
|
it('appends an optimistic message immediately on send', async () => {
|
|
const adapter = new MockAdapter();
|
|
let release!: () => void;
|
|
vi.spyOn(adapter, 'send').mockImplementation(
|
|
() => new Promise((res) => { release = () => res({ id: 'srv_1', actorId: 'me', text: 'hi', at: '2026-07-17T10:00:00.000Z' }); }),
|
|
);
|
|
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
|
|
act(() => { void result.current.send('hi'); });
|
|
|
|
await waitFor(() => expect(result.current.messages).toHaveLength(2));
|
|
expect(result.current.messages[1]!.pending).toBe(true);
|
|
expect(result.current.messages[1]!.mine).toBe(true);
|
|
|
|
await act(async () => { release(); });
|
|
await waitFor(() => expect(result.current.messages[1]!.pending).toBeFalsy());
|
|
});
|
|
|
|
it('rolls back the optimistic message and reports error when send fails', async () => {
|
|
const adapter = new MockAdapter();
|
|
vi.spyOn(adapter, 'send').mockRejectedValue(new Error('offline'));
|
|
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
|
|
await act(async () => {
|
|
await expect(result.current.send('doomed')).rejects.toThrow('offline');
|
|
});
|
|
|
|
expect(result.current.messages).toHaveLength(1);
|
|
expect(result.current.messages.some((m) => m.text === 'doomed')).toBe(false);
|
|
expect(result.current.error).toBe('offline');
|
|
});
|
|
|
|
it('does not duplicate a message when the transport echoes it back', async () => {
|
|
const adapter = new MockAdapter();
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
|
|
// MockAdapter.send emits a 'message' event AND resolves with the same message.
|
|
await act(async () => { await result.current.send('echo once'); });
|
|
|
|
expect(result.current.messages.filter((m) => m.text === 'echo once')).toHaveLength(1);
|
|
});
|
|
|
|
it('collects typing user ids from subscribe events', async () => {
|
|
const adapter = new MockAdapter();
|
|
let emit!: (userId: string) => void;
|
|
vi.spyOn(adapter, 'subscribe').mockImplementation((_t, cb) => {
|
|
emit = (userId) => cb({ kind: 'typing', userId });
|
|
return () => {};
|
|
});
|
|
|
|
const { result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
|
|
act(() => emit('pp_sofia'));
|
|
expect(result.current.typingUserIds).toEqual(['pp_sofia']);
|
|
});
|
|
|
|
it('unsubscribes on unmount', async () => {
|
|
const adapter = new MockAdapter();
|
|
const off = vi.fn();
|
|
vi.spyOn(adapter, 'subscribe').mockReturnValue(off);
|
|
|
|
const { unmount, result } = renderHook(() => useMessages('th_mock_1'), { wrapper: wrap(adapter) });
|
|
await waitFor(() => expect(result.current.loading).toBe(false));
|
|
unmount();
|
|
|
|
expect(off).toHaveBeenCalled();
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: FAIL — "Failed to resolve import ./use-messages".
|
|
|
|
- [ ] **Step 3: Write the implementation**
|
|
|
|
Create `packages/iios-messaging-ui/src/hooks/use-messages.ts`:
|
|
|
|
```ts
|
|
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
|
|
import { useAdapter } from '../provider';
|
|
import { isOwnMessage } from '../types';
|
|
import type { Message, SendOpts } from '../types';
|
|
|
|
const TYPING_TTL_MS = 3500;
|
|
|
|
export interface UiMessage extends Message {
|
|
mine: boolean;
|
|
}
|
|
|
|
export interface MessagesState {
|
|
messages: UiMessage[];
|
|
loading: boolean;
|
|
error: string | null;
|
|
send: (content: string, opts?: SendOpts) => Promise<void>;
|
|
react: (messageId: string, emoji: string) => Promise<void>;
|
|
typingUserIds: string[];
|
|
seenIds: Set<string>;
|
|
sendTyping: () => void;
|
|
canReact: boolean;
|
|
canUpload: boolean;
|
|
}
|
|
|
|
let optimisticSeq = 0;
|
|
|
|
export function useMessages(threadId: string | null): MessagesState {
|
|
const adapter = useAdapter();
|
|
const [raw, setRaw] = useState<Message[]>([]);
|
|
const [loading, setLoading] = useState(true);
|
|
const [error, setError] = useState<string | null>(null);
|
|
const [typing, setTyping] = useState<Record<string, number>>({});
|
|
const [seenIds, setSeenIds] = useState<Set<string>>(new Set());
|
|
const [, forceTick] = useState(0);
|
|
|
|
const currentActorId = adapter.currentActorId();
|
|
const actorRef = useRef(currentActorId);
|
|
actorRef.current = currentActorId;
|
|
|
|
// Load history, then subscribe. Reconciliation is by message id, so an echoed
|
|
// send never duplicates the optimistic row.
|
|
useEffect(() => {
|
|
if (!threadId) {
|
|
setRaw([]);
|
|
setLoading(false);
|
|
return;
|
|
}
|
|
let alive = true;
|
|
setLoading(true);
|
|
setRaw([]);
|
|
setSeenIds(new Set());
|
|
setTyping({});
|
|
|
|
adapter
|
|
.history(threadId)
|
|
.then((h) => {
|
|
if (alive) {
|
|
setRaw(h);
|
|
setError(null);
|
|
}
|
|
})
|
|
.catch((e: unknown) => {
|
|
if (alive) setError(e instanceof Error ? e.message : String(e));
|
|
})
|
|
.finally(() => {
|
|
if (alive) setLoading(false);
|
|
});
|
|
|
|
const off = adapter.subscribe(threadId, (e) => {
|
|
if (!alive) return;
|
|
switch (e.kind) {
|
|
case 'message':
|
|
setRaw((l) => (l.some((m) => m.id === e.message.id) ? l : [...l, e.message]));
|
|
break;
|
|
case 'typing':
|
|
if (e.userId !== actorRef.current) {
|
|
setTyping((t) => ({ ...t, [e.userId]: Date.now() + TYPING_TTL_MS }));
|
|
}
|
|
break;
|
|
case 'receipt':
|
|
// Only the OTHER side reading my message counts as "seen".
|
|
if (e.actorId !== actorRef.current) {
|
|
setSeenIds((s) => (s.has(e.messageId) ? s : new Set(s).add(e.messageId)));
|
|
}
|
|
break;
|
|
case 'reaction':
|
|
setRaw((l) => l.map((m) => (m.id === e.messageId ? { ...m, reactions: e.reactions } : m)));
|
|
break;
|
|
}
|
|
});
|
|
|
|
return () => {
|
|
alive = false;
|
|
off();
|
|
};
|
|
}, [adapter, threadId]);
|
|
|
|
const messages: UiMessage[] = useMemo(
|
|
() => raw.map((m) => ({ ...m, mine: isOwnMessage(m, currentActorId) })),
|
|
[raw, currentActorId],
|
|
);
|
|
|
|
const send = useCallback(
|
|
async (content: string, opts?: SendOpts) => {
|
|
if (!threadId) return;
|
|
const tempId = `optimistic_${optimisticSeq++}`;
|
|
const optimistic: Message = {
|
|
id: tempId,
|
|
actorId: actorRef.current,
|
|
text: content,
|
|
at: new Date().toISOString(),
|
|
pending: true,
|
|
reactions: [],
|
|
...(opts?.parentInteractionId ? { parentInteractionId: opts.parentInteractionId } : {}),
|
|
...(opts?.attachment ? { attachment: opts.attachment } : {}),
|
|
};
|
|
setRaw((l) => [...l, optimistic]);
|
|
|
|
try {
|
|
const saved = await adapter.send(threadId, content, opts);
|
|
setError(null);
|
|
// Replace the optimistic row with the server's. If the subscribe echo already
|
|
// added the real message, just drop the optimistic one.
|
|
setRaw((l) => {
|
|
const withoutTemp = l.filter((m) => m.id !== tempId);
|
|
return withoutTemp.some((m) => m.id === saved.id) ? withoutTemp : [...withoutTemp, saved];
|
|
});
|
|
} catch (e: unknown) {
|
|
setRaw((l) => l.filter((m) => m.id !== tempId));
|
|
setError(e instanceof Error ? e.message : String(e));
|
|
throw e;
|
|
}
|
|
},
|
|
[adapter, threadId],
|
|
);
|
|
|
|
const react = useCallback(
|
|
async (messageId: string, emoji: string) => {
|
|
if (!threadId || !adapter.react) return;
|
|
await adapter.react(threadId, messageId, emoji);
|
|
},
|
|
[adapter, threadId],
|
|
);
|
|
|
|
const sendTyping = useCallback(() => {
|
|
if (threadId) adapter.sendTyping(threadId);
|
|
}, [adapter, threadId]);
|
|
|
|
// Report my read of the newest message (drives the other side's "seen" tick).
|
|
useEffect(() => {
|
|
if (!threadId || raw.length === 0) return;
|
|
const last = raw[raw.length - 1]!;
|
|
if (last.pending) return;
|
|
void adapter.markRead(threadId, last.id).catch(() => {});
|
|
}, [adapter, threadId, raw]);
|
|
|
|
const typingUserIds = useMemo(() => {
|
|
const now = Date.now();
|
|
return Object.entries(typing)
|
|
.filter(([, exp]) => exp > now)
|
|
.map(([u]) => u);
|
|
}, [typing]);
|
|
|
|
// Expire stale typing entries by re-evaluating after the TTL.
|
|
useEffect(() => {
|
|
if (typingUserIds.length === 0) return;
|
|
const t = setTimeout(() => forceTick((n) => n + 1), TYPING_TTL_MS);
|
|
return () => clearTimeout(t);
|
|
}, [typingUserIds.length, typing]);
|
|
|
|
// Only my messages that the other side has read.
|
|
const seenMine = useMemo(() => {
|
|
const out = new Set<string>();
|
|
for (const id of seenIds) if (messages.some((m) => m.id === id && m.mine)) out.add(id);
|
|
return out;
|
|
}, [seenIds, messages]);
|
|
|
|
return {
|
|
messages,
|
|
loading,
|
|
error,
|
|
send,
|
|
react,
|
|
typingUserIds,
|
|
seenIds: seenMine,
|
|
sendTyping,
|
|
canReact: typeof adapter.react === 'function',
|
|
canUpload: typeof adapter.upload === 'function',
|
|
};
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS, 7 new tests.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/hooks/use-messages.ts packages/iios-messaging-ui/src/hooks/use-messages.test.tsx
|
|
git commit -m "feat: add useMessages hook with explicit ownership and optimistic send"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 9: Public barrel + transport-freedom enforcement
|
|
|
|
**Files:**
|
|
- Modify: `packages/iios-messaging-ui/src/index.ts`
|
|
- Create: `packages/iios-messaging-ui/src/boundary.test.ts`
|
|
- Modify: `scripts/check-import-boundary.mjs:22` (add the new package to `ALLOWED`)
|
|
|
|
The repo's boundary script is **package-level**, so it cannot express "core must not import kernel-client, but `adapters/kernel` may". That distinction is this SDK's core premise, so it gets its own test.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `packages/iios-messaging-ui/src/boundary.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest';
|
|
import { readdirSync, readFileSync, statSync } from 'node:fs';
|
|
import { fileURLToPath } from 'node:url';
|
|
import { join } from 'node:path';
|
|
|
|
// This package is ESM ("type": "module") — __dirname does not exist here.
|
|
const SRC = fileURLToPath(new URL('.', import.meta.url));
|
|
const ADAPTERS = join(SRC, 'adapters');
|
|
|
|
function tsFilesIn(dir: string): string[] {
|
|
const out: string[] = [];
|
|
for (const entry of readdirSync(dir)) {
|
|
const full = join(dir, entry);
|
|
if (statSync(full).isDirectory()) out.push(...tsFilesIn(full));
|
|
else if (/\.tsx?$/.test(full)) out.push(full);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
// The whole premise of this package: core renders, adapters transport. If core ever
|
|
// imports a transport, an app on a different backend pays for socket code it cannot
|
|
// use — which is exactly how iios-message-web welded itself to MessageSocket.
|
|
describe('transport boundary', () => {
|
|
const coreFiles = tsFilesIn(SRC).filter((f) => !f.startsWith(ADAPTERS) && !/\.test\.tsx?$/.test(f));
|
|
|
|
it('has core files to check', () => {
|
|
expect(coreFiles.length).toBeGreaterThan(0);
|
|
});
|
|
|
|
it('core never imports a transport package', () => {
|
|
const offenders: string[] = [];
|
|
for (const file of coreFiles) {
|
|
const content = readFileSync(file, 'utf8');
|
|
if (/@insignia\/iios-kernel-client|socket\.io|@abe-kap\/appshell-sdk/.test(content)) {
|
|
offenders.push(file.replace(SRC, 'src'));
|
|
}
|
|
}
|
|
expect(offenders).toEqual([]);
|
|
});
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it passes**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test`
|
|
Expected: PASS. (This test guards a property that already holds — it fails loudly in Plan 3 if someone imports the kernel from core.)
|
|
|
|
- [ ] **Step 3: Write the public barrel**
|
|
|
|
Replace `packages/iios-messaging-ui/src/index.ts`:
|
|
|
|
```ts
|
|
// Public API. Components land in Plan 2; adapters/kernel in Plan 3.
|
|
//
|
|
// `runAdapterConformance` is deliberately NOT exported here — it imports vitest and
|
|
// ships from the './conformance' subpath so consumers never pull a test runner into
|
|
// their production bundle.
|
|
export { MessagingProvider, useAdapter } from './provider';
|
|
export { useConversations } from './hooks/use-conversations';
|
|
export { useMessages } from './hooks/use-messages';
|
|
export { isOwnMessage } from './types';
|
|
|
|
export type { MessagingAdapter } from './adapter';
|
|
export type { ConversationsState } from './hooks/use-conversations';
|
|
export type { MessagesState, UiMessage } from './hooks/use-messages';
|
|
export type {
|
|
Attachment,
|
|
Conversation,
|
|
Membership,
|
|
Message,
|
|
MessageEvent,
|
|
Person,
|
|
Reaction,
|
|
SendOpts,
|
|
Unsubscribe,
|
|
} from './types';
|
|
```
|
|
|
|
- [ ] **Step 4: Register the package in the repo's import-boundary law**
|
|
|
|
In `scripts/check-import-boundary.mjs`, add this entry to the `ALLOWED` map (after the `'@insignia/iios-message-web'` line):
|
|
|
|
```js
|
|
// Core is transport-free; only ./adapters/kernel may import the kernel client.
|
|
// This map is package-level and cannot express that subpath rule — the finer
|
|
// constraint is enforced by packages/iios-messaging-ui/src/boundary.test.ts.
|
|
'@insignia/iios-messaging-ui': ['@insignia/iios-kernel-client'],
|
|
```
|
|
|
|
- [ ] **Step 5: Verify the boundary law still passes**
|
|
|
|
Run: `pnpm boundary`
|
|
Expected: `✓ import-boundary: OK`
|
|
|
|
- [ ] **Step 6: Verify the full package**
|
|
|
|
Run: `pnpm --filter @insignia/iios-messaging-ui test && pnpm --filter @insignia/iios-messaging-ui typecheck && pnpm --filter @insignia/iios-messaging-ui build`
|
|
Expected: all tests PASS; no type errors; `dist/index.js`, `dist/index.d.ts`, `dist/adapters/mock.js`, `dist/conformance.js` produced.
|
|
|
|
- [ ] **Step 6b: Verify the main entry does not drag in vitest**
|
|
|
|
Run: `grep -c vitest packages/iios-messaging-ui/dist/index.js || echo "clean"`
|
|
Expected: `clean` (grep finds nothing and exits 1). If this prints a number, `conformance.ts` leaked into the main barrel — remove the re-export from `src/index.ts`.
|
|
|
|
Run: `grep -rE "iios-kernel-client|socket\.io" packages/iios-messaging-ui/dist/index.js || echo "transport-free"`
|
|
Expected: `transport-free`.
|
|
|
|
- [ ] **Step 7: Verify the root test suite is unaffected**
|
|
|
|
Run: `pnpm test`
|
|
Expected: the root suite passes exactly as before. Its `include` matches only `.ts`, so this package's `.tsx` tests are not picked up there — intentional, since root provisions Postgres. The package's tests run via its own `test` script.
|
|
|
|
- [ ] **Step 8: Commit**
|
|
|
|
```bash
|
|
git add packages/iios-messaging-ui/src/index.ts packages/iios-messaging-ui/src/boundary.test.ts scripts/check-import-boundary.mjs
|
|
git commit -m "feat: export messaging-ui public API and enforce transport boundary"
|
|
```
|
|
|
|
---
|
|
|
|
## Done criteria
|
|
|
|
- `pnpm --filter @insignia/iios-messaging-ui test` — all green (33 tests as shipped).
|
|
- `pnpm boundary` — OK.
|
|
- `pnpm test` at root — unchanged.
|
|
- The package builds to ESM with types and has **zero runtime dependencies**.
|
|
- A host can already drive messaging headlessly: `MessagingProvider` + `MockAdapter` + hooks.
|
|
|
|
## Post-implementation corrections (2026-07-18)
|
|
|
|
Executed via subagent-driven development on branch `feat/inbox-owner-interest`. Code review during Tasks 5 and 8 caught defects in the code blocks **above** — the shipped code diverges from the plan text in these ways, and Plan 3 should treat the committed source (not the Task 8 listing above) as authoritative:
|
|
|
|
- **`useMessages` typing expiry** — the plan used `forceTick((n) => n + 1)` to expire stale typing entries. That is a no-op: the `typingUserIds` memo is keyed on `[typing]`, so an unrelated state bump returns the cached array and the indicator sticks forever. Shipped code uses `setTimeout(() => setTyping((p) => ({ ...p })), TYPING_TTL_MS)` (a new `typing` reference forces the memo to recompute with a fresh `now`). `forceTick` state removed entirely.
|
|
- **`useMessages` history race** — the plan's `.then((h) => setRaw(h))` clobbers live messages that arrive via `subscribe` while `history()` is still in flight (silent data loss on any async transport; the sync MockAdapter can't show it). Shipped code merges by id: `setRaw((live) => { const histIds = new Set(h.map(m => m.id)); const extras = live.filter(m => !histIds.has(m.id)); return extras.length ? [...h, ...extras] : h; })`. Guarded by the test "keeps a live message that arrives before history resolves" (verified to fail if the merge is reverted).
|
|
- **`useMessages` markRead** — re-keyed from `[adapter, threadId, raw]` (fired on every array churn, incl. reactions) to a derived `lastReadableId` (newest non-pending id), so it fires only when the read frontier actually moves.
|
|
- **`useMessages` error reset** — `setError(null)` added to the thread-switch reset block (plan left a stale error banner across thread switches).
|
|
- **`MockAdapter`** — `history()` and `listConversations().participants` now return copies (plan leaked the live internal arrays); constructor calls `now()` once for both seed messages.
|
|
- **`boundary.test.ts`** — carries a `// @vitest-environment node` directive on line 1. jsdom overrides the global `URL` constructor, which breaks `fileURLToPath(new URL('.', import.meta.url))`; a filesystem test must run in node.
|
|
|
|
**Known limitation deferred to Plan 3 (issue I2):** `useMessages` reads `adapter.currentActorId()` per-render but nothing makes it reactive. If a real adapter's identity resolves from `null` to a value with no intervening React state change, ownership stays wrong until an incidental re-render — and an optimistic message stamped while identity is `null` renders as not-mine. The MockAdapter never has null identity, so this does not manifest in the foundation. Plan 3 must decide how the real adapter exposes identity reactively (e.g. an `onActorIdChange` subscription on the interface, or the host re-rendering the provider when auth resolves) rather than relying on incidental re-renders.
|
|
|
|
## What Plan 2 adds
|
|
|
|
Components (`ConversationList`, `ThreadView`, `Composer`, `MessageBubble`, `Messenger`), the SDK's own internal primitives (the CRM's `Avatar`/`Btn`/`Icon` cannot be imported — they live in `lynkeduppro-crm/src/components/dashboard/ui.tsx`), `styles.css` with the `--msg-*` token contract, and the `classNames` slot map.
|
|
|
|
## What Plan 3 adds
|
|
|
|
`./adapters/kernel` (wrapping `iios-kernel-client`, running the conformance suite), `CrmMessagingAdapter` in the CRM repo (data door + socket + 4s poll fallback, also running conformance), attachments end-to-end, and the CRM migration that deletes `messenger.tsx`.
|
|
|
|
Both adapters verify themselves with `import { runAdapterConformance } from '@insignia/iios-messaging-ui/conformance'`. Plan 3 must add `@insignia/iios-kernel-client` to this package's `dependencies` and to the `tsup` `entry` + `external` lists — and `src/boundary.test.ts` will fail if that import reaches core rather than staying inside `src/adapters/`.
|
|
|
|
**Strengthen the safety nets before writing the kernel adapter** (from the final foundation review — the current versions are adequate for the mock but too weak to catch a broken real adapter):
|
|
|
|
- **Expand `runAdapterConformance`.** Today it only exercises the happy `message` path. It does NOT test the optional methods (`react`/`upload`/`isConnected`), **subscribe thread-isolation** (an adapter that leaks every thread's events to every subscriber would pass yet break the UI), or the `receipt`/`reaction`/`typing` event kinds. Since conformance IS the safety net for the real kernel adapter, add these cases first.
|
|
- **Convert `boundary.test.ts` from a denylist to an allowlist.** It currently greps core for three transport strings (`iios-kernel-client|socket.io|@abe-kap/appshell-sdk`); a core file importing a *different* transport (`ws`, `pusher`, raw WebSocket) would slip through, and the root `pnpm boundary` allowlist only governs at package granularity. Once `adapters/kernel` exists, assert core imports only `react` + relative paths.
|
|
- **Also address the deferred I2 (reactive identity)** noted under Post-implementation corrections above, and resolve the two Plan-2 notes: emit `dist/styles.css` so the exports entry resolves, and decide whether `react()` failures should populate `error` (today only `send()` does).
|
|
|
|
## CI note for whoever wires it
|
|
|
|
Root `pnpm test` does not run this package's tests. CI must also run:
|
|
|
|
```bash
|
|
pnpm --filter @insignia/iios-messaging-ui test
|
|
```
|
|
|
|
The alternative — folding `.tsx` + jsdom into the root config — would make every UI test wait on Postgres provisioning. Not worth it.
|