@moderta/mint-ai-assistant 0.1.4 → 0.1.6

package/README.md

@@ -1,85 +1,100 @@
-# @moderta/mint-ai-assistant
-
-Embeddable **Mint AI** assistant — a floating chat widget shared across Moderta apps.
-React component, Tailwind-styled, distributed as an npm package.
-
-## Why this exists
-
-The same architecture as the main `frontend` (RTK Query `api-details` → `base-slice`
-registry, scoped store), but packaged as a **library** you can drop into any React app
-without it touching the host's styles.
-
-- **Isolation:** Tailwind preflight is disabled and every utility is `mint-` prefixed, so
-  embedding never resets or restyles the host app. The compiled CSS is auto-injected.
-- **Config via props**, not env vars (the package runs inside someone else's bundle).
-- **React + ReactDOM are peer dependencies** — the host provides them.
-
-## Install
-
-```bash
-npm install @moderta/mint-ai-assistant
-```
-
-## Usage
-
-```tsx
-import { MintAIAssistant } from '@moderta/mint-ai-assistant';
-
-export function App() {
-  return (
-    <MintAIAssistant
-      baseUrl="https://api.moderta.io/ai"
-      getToken={() => localStorage.getItem('token') ?? undefined}
+# @moderta/mint-ai-assistant
+
+Embeddable **Mint AI** assistant — a floating chat widget shared across Moderta apps.
+React component, Tailwind-styled, distributed as an npm package.
+
+## Why this exists
+
+The same architecture as the main `frontend` (RTK Query `api-details` → `base-slice`
+registry, scoped store), but packaged as a **library** you can drop into any React app
+without it touching the host's styles.
+
+- **Isolation:** Tailwind preflight is disabled and every utility is `mint-` prefixed, so
+  embedding never resets or restyles the host app. The compiled CSS is auto-injected.
+- **Config via props**, not env vars (the package runs inside someone else's bundle).
+- **React + ReactDOM are peer dependencies** — the host provides them.
+
+## Install
+
+```bash
+npm install @moderta/mint-ai-assistant
+```
+
+## Usage
+
+```tsx
+import { MintAIAssistant } from '@moderta/mint-ai-assistant';
+
+export function App() {
+  return (
+    <MintAIAssistant
+      baseUrl="https://context-engine.moderta.io"
+      getToken={() => sessionStorage.getItem('jwt_access_token') ?? undefined}
+      tenantId={user.companyId}
       title="Mint AI"
       placement="bottom-right"
       enableExpandMode={false}
-      context={{ orgId: 'org_123' }}
-    />
-  );
-}
-```
-
-### Props (`MintAIConfig`)
-
-| Prop             | Type                          | Default          | Notes                                   |
-| ---------------- | ----------------------------- | ---------------- | --------------------------------------- |
-| `baseUrl`        | `string`                      | —                | Required. Base URL of the assistant API |
-| `getToken`       | `() => string \| Promise<…>`  | —                | Bearer token for requests               |
-| `placement`      | `bottom-right \| …`           | `bottom-right`   | Launcher corner                         |
-| `title`          | `string`                      | `Mint AI`        | Panel header title                      |
-| `welcomeMessage` | `string`                      | greeting         | Shown when there's no history           |
-| `defaultOpen`    | `boolean`                     | `false`          | Open the panel on mount                 |
-| `context`        | `Record<string, unknown>`     | —                | Forwarded with every chat request       |
-
-## API contract
-
-The widget talks to a small API (`src/api/api-details`):
-
-- `POST {baseUrl}/chat/messages` → `{ conversationId, reply }`
-- `GET  {baseUrl}/chat/conversations/:id` → `{ conversationId, messages }`
-- `POST {baseUrl}/chat/feedback` → `{ success }`
-
-## Develop
-
-```bash
-npm install
-npm run dev      # playground host app at / (see dev/main.tsx)
-npm run build    # emits dist/ (ESM + CJS + types)
-```
-
-## Project structure
-
-```
-src/
-  index.ts                 public API
-  mint-ai-assistant.tsx    root component (provider + widget)
-  config/                  props-based config (replaces global-config)
-  providers/               scoped provider stack
-  store/                   widget-scoped Redux + chat UI slice
-  api/                     RTK Query: api-details registry → base-slice
-  sections/assistant/      the chat UI (launcher, panel, list, composer)
-  components/iconify/      shared UI primitives
-  hooks/                   useChat
-  types/                   shared types
-  utils/                   cn(), uid()
-```
+    />
+  );
+}
+```
+
+### Props (`MintAIConfig`)
+
+| Prop             | Type                          | Default          | Notes                                   |
+| ---------------- | ----------------------------- | ---------------- | --------------------------------------- |
+| `baseUrl`        | `string`                      | —                | Required. Base URL of the assistant API |
+| `getToken`       | `() => string \| Promise<…>`  | —                | Supabase bearer token for requests      |
+| `tenantId`       | `string`                      | —                | Sent as `tenant_id`; the caller's company id |
+| `user`           | `{ name?: string; email?: string }` | —          | Signed-in identity shown in the expanded-mode sidebar |
+| `placement`      | `bottom-right \| …`           | `bottom-right`   | Launcher corner                         |
+| `title`          | `string`                      | `Mint AI`        | Panel header title                      |
+| `welcomeMessage` | `string`                      | greeting         | Shown when there's no history           |
+| `defaultOpen`    | `boolean`                     | `false`          | Open the panel on mount                 |
+
+## API contract
+
+The widget talks to the Mint AI Context Engine (`src/api/api-details`):
+
+- `POST {baseUrl}/query` — body `{ tenant_id, question }`, header
+  `Authorization: Bearer <token>` → `{ answer, sources: [{ chunk_id, text }], source_type }`
+
+There is no conversation-history or feedback endpoint; conversation
+continuity is client-side only.
+
+## Develop
+
+```bash
+npm install
+npm run dev      # playground host app at / (see dev/main.tsx)
+npm run build    # emits dist/ (ESM + CJS + types)
+```
+
+## Project structure
+
+```
+src/
+  index.ts                 public API
+  mint-ai-assistant.tsx    root component (provider + widget)
+  config/                  props-based config (replaces global-config)
+  providers/               scoped provider stack
+  store/                   widget-scoped Redux + chat UI slice
+  api/                     RTK Query: api-details registry → base-slice
+  sections/assistant/      the chat UI (launcher, panel, list, composer)
+  components/iconify/      shared UI primitives
+  hooks/                   useChat
+  types/                   shared types
+  utils/                   cn(), uid()
+```
+
+## AI-assisted development
+
+Repository-specific AI guidance lives in [AGENTS.md](AGENTS.md). Detailed architecture, security, testing, database, specifications, prompts and project knowledge are under [`.ai/`](.ai/); reusable Claude skills and permissions are under [`.claude/`](.claude/). Treat executable code and tests as authoritative when documentation becomes stale.
+
+## Current architecture snapshot
+
+Embeddable `@moderta/mint-ai-assistant` React widget/library. `src/index.ts` defines the package public API. `MintAIAssistant` wraps the UI in `AssistantProvider`; `dev/main.tsx` is a local integration harness, not a production entry point.
+
+A host passes API base URL, optional token getter/context/placement. The provider creates configuration and Redux context; `useChat` adds an optimistic user message, calls the chat endpoint, stores the returned conversation/assistant message, and emits a system error on failure.
+
+For implementation rules and the complete source-derived map, read [AGENTS.md](AGENTS.md) and [the architecture instructions](.ai/instructions/architecture.md).

package/dist/index.d.ts

@@ -1,12 +1,21 @@
-import { ChatMessage } from '@moderta/api-contracts';
-import { ChatMessageStatus } from '@moderta/api-contracts';
-import { ChatRole } from '@moderta/api-contracts';
+import { BaseQueryApi } from '@reduxjs/toolkit/query';
+import { ChatMessage } from '@moderta/api-contracts/chat';
+import { ChatMessageStatus } from '@moderta/api-contracts/chat';
+import { ChatRole } from '@moderta/api-contracts/chat';
+import { FetchArgs } from '@reduxjs/toolkit/query';
+import { FetchBaseQueryError } from '@reduxjs/toolkit/query';
+import { FetchBaseQueryMeta } from '@reduxjs/toolkit/query';
+import { InfiniteQueryActionCreatorResult } from '@reduxjs/toolkit/query';
+import { InfiniteQueryDefinition } from '@reduxjs/toolkit/query';
 import { JSX as JSX_2 } from 'react';
+import { QueryReturnValue } from '@reduxjs/toolkit/query';
 import { ReactNode } from 'react';
+import { SessionSummary } from '@moderta/api-contracts/chat';
+import { SubscriptionOptions } from '@reduxjs/toolkit/query';
 
 export declare type AssistantFormRenderer = () => ReactNode;
 
-export declare type AssistantPlacement = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+export declare type AssistantPlacement = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 
 export { ChatMessage }
 
@@ -24,8 +33,21 @@ export declare interface MintAIAssistantProps extends MintAIConfig {
 export declare interface MintAIConfig {
     /** Base URL of the assistant API, e.g. `https://api.moderta.io`. */
     baseUrl: string;
+    /** Optional stable user identifier forwarded to the chat backend. */
+    userId?: string;
     /** Returns the bearer token for the current user (sync or async). */
     getToken?: TokenGetter;
+    /**
+     * Tenant identifier sent as `tenant_id` with every `/query` request.
+     * In ESM this is the caller's company id. The Context Engine still
+     * re-derives it from the bearer token and rejects a mismatch.
+     */
+    tenantId?: string;
+    /** Signed-in user's display identity, shown in the assistant UI. */
+    user?: {
+        name?: string;
+        email?: string;
+    };
     /** Where the floating launcher sits. Default: `bottom-right`. */
     placement?: AssistantPlacement;
     /** Greeting shown when the chat opens with no history. */
@@ -46,34 +68,68 @@ export declare interface MintAIConfig {
 
 declare type ResolvedConfig = MintAIConfig & Required<Pick<MintAIConfig, 'placement' | 'title' | 'welcomeMessage' | 'defaultOpen' | 'enableExpandMode'>>;
 
-export declare function SampleConversationPanel({ onClose }: {
-    onClose?: () => void;
-}): JSX_2.Element;
-
-export declare function SampleEmptyPanel({ onClose }: {
-    onClose?: () => void;
-}): JSX_2.Element;
-
-export declare function SampleExpandedMode({ onCollapse, onClose, }: Readonly<{
-    onCollapse?: () => void;
-    onClose?: () => void;
-}>): JSX_2.Element;
-
-export declare function SampleShowcase({ initial }: {
-    initial?: Screen_2;
-}): JSX_2.Element;
-
-declare type Screen_2 = 'empty' | 'conversation' | 'expanded';
+export { SessionSummary }
 
 export declare type TokenGetter = () => string | undefined | Promise<string | undefined>;
 
 export declare function useChat(): {
     messages: ChatMessage[];
-    draft: string;
-    isLoading: any;
+    notice: string | null;
+    isLoading: boolean;
     send: (raw?: string) => Promise<void>;
+    loadOlder: () => void;
+    hasOlder: boolean;
+    isLoadingOlder: boolean;
 };
 
 export declare function useConfig(): ResolvedConfig;
 
+/**
+ * The Past Chats list for the expanded sidebar. Backed by the getSessions
+ * infinite query — one flat list, keyset-paginated, filtered by `search`
+ * (debounced). Re-sorts when sendMessage invalidates SessionList.
+ */
+export declare function useSessions(search: string): {
+    sessions: {
+        sessionId: string;
+        title: string | null;
+        status: "active" | "expired";
+        createdAt: string;
+        lastActivityAt: string;
+        expiresAt: string;
+    }[];
+    activeSessionId: string | null;
+    isLoading: boolean;
+    /** A fetch is in flight that isn't "load next page" — initial load or a new search. */
+    isReloading: boolean;
+    isError: boolean;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    loadMore: () => void;
+    openSession: (sessionId: string) => {
+        payload: string | null;
+        type: "chatUi/setActiveSessionId";
+    };
+    newChat: () => {
+        payload: undefined;
+        type: "chatUi/startNewChat";
+    };
+    refetch: (options?: Pick<SubscriptionOptions & {
+        skip?: boolean;
+        refetchOnMountOrArgChange?: boolean | number;
+        initialPageParam?: string | undefined;
+        refetchCachedPages?: boolean;
+    }, "refetchCachedPages"> | undefined) => InfiniteQueryActionCreatorResult<InfiniteQueryDefinition<string, string | undefined, (args: string | FetchArgs, api: BaseQueryApi, extraOptions: {}) => Promise<QueryReturnValue<unknown, FetchBaseQueryError, FetchBaseQueryMeta>>, "SessionList", {
+    items: {
+    sessionId: string;
+    title: string | null;
+    status: "active" | "expired";
+    createdAt: string;
+    lastActivityAt: string;
+    expiresAt: string;
+    }[];
+    nextCursor: string | null;
+    }, "chatApi", unknown>>;
+};
+
 export { }