@maintainer-pro/ai-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,181 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ClientContext, ToolCall, ChatUser } from '@maintainer-pro/ai-cli';
+export { ChatAttachment, ChatSenderType, ChatUser, ClientContext, ToolCall } from '@maintainer-pro/ai-cli';
+
+interface AiChatProps {
+    apiUrl?: string;
+    /**
+     * Live client context for each turn. Defaults to browser route + page title
+     * via `buildBrowserClientContext()`.
+     */
+    buildContext?: () => ClientContext;
+    onToolCalls?: (toolCalls: ToolCall[]) => void | Promise<void>;
+    /**
+     * Snapshot app state at the start of a turn so an interrupted turn can be
+     * reverted when the user sends another message mid-run.
+     */
+    captureState?: () => unknown;
+    /** Restore a snapshot previously returned by captureState. */
+    restoreState?: (snapshot: unknown) => void;
+    conversationId?: string;
+    /**
+     * @deprecated Ignored — sessions are shared via the server store.
+     * Kept so existing call sites keep type-checking.
+     */
+    conversationStorageKey?: string;
+    title?: string;
+    emptyState?: ReactNode;
+    className?: string;
+    /**
+     * People in this chat. Prefer omitting this when Maintainer Pro is configured
+     * so accounts load from `/api/v1/client/chat-users` (roles included).
+     * Client messages go to the AI; developer messages are human replies only.
+     * Include `{ type: "ai", name }` to label AI replies for @mentions.
+     */
+    users?: ChatUser[];
+    /**
+     * When set, chat history and users (if `users` omitted) load from Maintainer
+     * Pro using a client-scoped API key. AI turns still use `apiUrl`.
+     */
+    maintainerProUrl?: string;
+    maintainerProApiKey?: string;
+}
+declare function AiChat({ apiUrl, buildContext, onToolCalls, captureState, restoreState, conversationId: conversationIdProp, title, emptyState, className, users, maintainerProUrl, maintainerProApiKey, }: AiChatProps): react.JSX.Element;
+
+/**
+ * Chat panel open/closed state persisted in `localStorage`.
+ * Starts from `defaultOpen` on the server / first paint, then hydrates from storage.
+ */
+declare function usePersistedChatOpen(storageKey?: string, defaultOpen?: boolean): [boolean, (value: boolean | ((prev: boolean) => boolean)) => void];
+
+type ChatUnreadSourceOptions = {
+    apiUrl?: string;
+    maintainerProUrl?: string;
+    maintainerProApiKey?: string;
+    conversationId?: string;
+    /** localStorage key for last-read watermark (default derived from conversation). */
+    storageKey?: string;
+};
+type StoredChatMessage = {
+    id?: string;
+    role: string;
+    content: string;
+    provider?: string | null;
+    senderType?: string | null;
+    senderName?: string | null;
+    createdAt?: string;
+};
+declare function rememberConversationId(baseUrl: string, apiKey: string, conversationId: string): void;
+/** Full stored messages for live thread sync (messages endpoint only). */
+declare function fetchChatMessages(options: ChatUnreadSourceOptions): Promise<StoredChatMessage[]>;
+/**
+ * Lightweight timestamps for unread badges.
+ * Prefer conversation summaries (one call) when Maintainer Pro is configured.
+ */
+declare function fetchChatMessageTimestamps(options: ChatUnreadSourceOptions): Promise<string[]>;
+declare function countUnreadSince(timestamps: string[], lastReadAt: string | null): number;
+type ChatUnreadPoller = {
+    stop: () => void;
+    /** Refresh unread count immediately. */
+    refresh: () => Promise<void>;
+    /** Mark everything currently known as read. */
+    markRead: () => Promise<void>;
+};
+/**
+ * Poll for new chat messages while the panel is closed. First successful fetch
+ * seeds the read watermark so existing history is not treated as unread.
+ */
+declare function startChatUnreadPoller(options: ChatUnreadSourceOptions & {
+    isOpen: () => boolean;
+    onChange: (unreadCount: number) => void;
+    pollIntervalMs?: number;
+}): ChatUnreadPoller;
+
+type UseChatUnreadOptions = ChatUnreadSourceOptions & {
+    /** When true, unread clears and new messages while open are marked read. */
+    chatOpen: boolean;
+    pollIntervalMs?: number;
+};
+/**
+ * Tracks unread chat messages for a closed FAB / drawer.
+ * Polls Maintainer Pro (or `/api/chat`) while the panel is closed.
+ */
+declare function useChatUnread(options: UseChatUnreadOptions): {
+    unreadCount: number;
+    hasUnread: boolean;
+};
+
+type BuildClientContextInput = {
+    route?: string;
+    pageTitle?: string;
+    visiblePanels?: string[];
+    relevantFiles?: string[];
+    data?: Record<string, unknown>;
+};
+/** Helper to assemble a ClientContext from browser + host data. */
+declare function buildBrowserClientContext(input?: BuildClientContextInput): ClientContext;
+declare function useClientContextBuilder(getInput: () => BuildClientContextInput): () => ClientContext;
+
+type MaintainerProClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+};
+type MaintainerProApplication = {
+    id: string;
+    name: string;
+    clientId: string;
+    clientName: string;
+    /** @deprecated Use clientId */
+    companyId?: string;
+    /** @deprecated Use clientName */
+    companyName?: string;
+    partnerId: string;
+    sandboxId?: string;
+    sandboxName?: string;
+};
+type MaintainerProStoredMessage = {
+    id: string;
+    conversationId: string;
+    role: string;
+    content: string;
+    provider?: string | null;
+    senderType?: string | null;
+    senderName?: string | null;
+    createdAt?: string;
+    attachmentPaths?: string[];
+    attachmentIds?: string[];
+};
+type MaintainerProConversationSummary = {
+    id: string;
+    updatedAt: string;
+    messages: Array<{
+        role: string;
+        content: string;
+        createdAt?: string;
+    }>;
+};
+type MaintainerProChatUser = {
+    name: string;
+    type: "client" | "developer" | "ai";
+    default?: boolean;
+    email?: string;
+    role?: string;
+};
+declare function createMaintainerProClient(options: MaintainerProClientOptions): {
+    getApplication(): Promise<MaintainerProApplication>;
+    listConversations(): Promise<MaintainerProConversationSummary[]>;
+    listChatUsers(): Promise<MaintainerProChatUser[]>;
+    loginChatUser(email: string, password: string): Promise<{
+        name: string;
+        email: string;
+        type: "client" | "developer";
+        role?: string;
+    }>;
+    listMessages(conversationId: string): Promise<MaintainerProStoredMessage[]>;
+    attachmentUrl(attachmentId: string): string;
+};
+type MaintainerProClient = ReturnType<typeof createMaintainerProClient>;
+
+export { AiChat, type AiChatProps, type BuildClientContextInput, type ChatUnreadPoller, type ChatUnreadSourceOptions, type MaintainerProApplication, type MaintainerProChatUser, type MaintainerProClient, type MaintainerProClientOptions, type MaintainerProConversationSummary, type MaintainerProStoredMessage, type StoredChatMessage, type UseChatUnreadOptions, buildBrowserClientContext, countUnreadSince, createMaintainerProClient, fetchChatMessageTimestamps, fetchChatMessages, rememberConversationId, startChatUnreadPoller, useChatUnread, useClientContextBuilder, usePersistedChatOpen };

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ClientContext, ToolCall, ChatUser } from '@maintainer-pro/ai-cli';
+export { ChatAttachment, ChatSenderType, ChatUser, ClientContext, ToolCall } from '@maintainer-pro/ai-cli';
+
+interface AiChatProps {
+    apiUrl?: string;
+    /**
+     * Live client context for each turn. Defaults to browser route + page title
+     * via `buildBrowserClientContext()`.
+     */
+    buildContext?: () => ClientContext;
+    onToolCalls?: (toolCalls: ToolCall[]) => void | Promise<void>;
+    /**
+     * Snapshot app state at the start of a turn so an interrupted turn can be
+     * reverted when the user sends another message mid-run.
+     */
+    captureState?: () => unknown;
+    /** Restore a snapshot previously returned by captureState. */
+    restoreState?: (snapshot: unknown) => void;
+    conversationId?: string;
+    /**
+     * @deprecated Ignored — sessions are shared via the server store.
+     * Kept so existing call sites keep type-checking.
+     */
+    conversationStorageKey?: string;
+    title?: string;
+    emptyState?: ReactNode;
+    className?: string;
+    /**
+     * People in this chat. Prefer omitting this when Maintainer Pro is configured
+     * so accounts load from `/api/v1/client/chat-users` (roles included).
+     * Client messages go to the AI; developer messages are human replies only.
+     * Include `{ type: "ai", name }` to label AI replies for @mentions.
+     */
+    users?: ChatUser[];
+    /**
+     * When set, chat history and users (if `users` omitted) load from Maintainer
+     * Pro using a client-scoped API key. AI turns still use `apiUrl`.
+     */
+    maintainerProUrl?: string;
+    maintainerProApiKey?: string;
+}
+declare function AiChat({ apiUrl, buildContext, onToolCalls, captureState, restoreState, conversationId: conversationIdProp, title, emptyState, className, users, maintainerProUrl, maintainerProApiKey, }: AiChatProps): react.JSX.Element;
+
+/**
+ * Chat panel open/closed state persisted in `localStorage`.
+ * Starts from `defaultOpen` on the server / first paint, then hydrates from storage.
+ */
+declare function usePersistedChatOpen(storageKey?: string, defaultOpen?: boolean): [boolean, (value: boolean | ((prev: boolean) => boolean)) => void];
+
+type ChatUnreadSourceOptions = {
+    apiUrl?: string;
+    maintainerProUrl?: string;
+    maintainerProApiKey?: string;
+    conversationId?: string;
+    /** localStorage key for last-read watermark (default derived from conversation). */
+    storageKey?: string;
+};
+type StoredChatMessage = {
+    id?: string;
+    role: string;
+    content: string;
+    provider?: string | null;
+    senderType?: string | null;
+    senderName?: string | null;
+    createdAt?: string;
+};
+declare function rememberConversationId(baseUrl: string, apiKey: string, conversationId: string): void;
+/** Full stored messages for live thread sync (messages endpoint only). */
+declare function fetchChatMessages(options: ChatUnreadSourceOptions): Promise<StoredChatMessage[]>;
+/**
+ * Lightweight timestamps for unread badges.
+ * Prefer conversation summaries (one call) when Maintainer Pro is configured.
+ */
+declare function fetchChatMessageTimestamps(options: ChatUnreadSourceOptions): Promise<string[]>;
+declare function countUnreadSince(timestamps: string[], lastReadAt: string | null): number;
+type ChatUnreadPoller = {
+    stop: () => void;
+    /** Refresh unread count immediately. */
+    refresh: () => Promise<void>;
+    /** Mark everything currently known as read. */
+    markRead: () => Promise<void>;
+};
+/**
+ * Poll for new chat messages while the panel is closed. First successful fetch
+ * seeds the read watermark so existing history is not treated as unread.
+ */
+declare function startChatUnreadPoller(options: ChatUnreadSourceOptions & {
+    isOpen: () => boolean;
+    onChange: (unreadCount: number) => void;
+    pollIntervalMs?: number;
+}): ChatUnreadPoller;
+
+type UseChatUnreadOptions = ChatUnreadSourceOptions & {
+    /** When true, unread clears and new messages while open are marked read. */
+    chatOpen: boolean;
+    pollIntervalMs?: number;
+};
+/**
+ * Tracks unread chat messages for a closed FAB / drawer.
+ * Polls Maintainer Pro (or `/api/chat`) while the panel is closed.
+ */
+declare function useChatUnread(options: UseChatUnreadOptions): {
+    unreadCount: number;
+    hasUnread: boolean;
+};
+
+type BuildClientContextInput = {
+    route?: string;
+    pageTitle?: string;
+    visiblePanels?: string[];
+    relevantFiles?: string[];
+    data?: Record<string, unknown>;
+};
+/** Helper to assemble a ClientContext from browser + host data. */
+declare function buildBrowserClientContext(input?: BuildClientContextInput): ClientContext;
+declare function useClientContextBuilder(getInput: () => BuildClientContextInput): () => ClientContext;
+
+type MaintainerProClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+};
+type MaintainerProApplication = {
+    id: string;
+    name: string;
+    clientId: string;
+    clientName: string;
+    /** @deprecated Use clientId */
+    companyId?: string;
+    /** @deprecated Use clientName */
+    companyName?: string;
+    partnerId: string;
+    sandboxId?: string;
+    sandboxName?: string;
+};
+type MaintainerProStoredMessage = {
+    id: string;
+    conversationId: string;
+    role: string;
+    content: string;
+    provider?: string | null;
+    senderType?: string | null;
+    senderName?: string | null;
+    createdAt?: string;
+    attachmentPaths?: string[];
+    attachmentIds?: string[];
+};
+type MaintainerProConversationSummary = {
+    id: string;
+    updatedAt: string;
+    messages: Array<{
+        role: string;
+        content: string;
+        createdAt?: string;
+    }>;
+};
+type MaintainerProChatUser = {
+    name: string;
+    type: "client" | "developer" | "ai";
+    default?: boolean;
+    email?: string;
+    role?: string;
+};
+declare function createMaintainerProClient(options: MaintainerProClientOptions): {
+    getApplication(): Promise<MaintainerProApplication>;
+    listConversations(): Promise<MaintainerProConversationSummary[]>;
+    listChatUsers(): Promise<MaintainerProChatUser[]>;
+    loginChatUser(email: string, password: string): Promise<{
+        name: string;
+        email: string;
+        type: "client" | "developer";
+        role?: string;
+    }>;
+    listMessages(conversationId: string): Promise<MaintainerProStoredMessage[]>;
+    attachmentUrl(attachmentId: string): string;
+};
+type MaintainerProClient = ReturnType<typeof createMaintainerProClient>;
+
+export { AiChat, type AiChatProps, type BuildClientContextInput, type ChatUnreadPoller, type ChatUnreadSourceOptions, type MaintainerProApplication, type MaintainerProChatUser, type MaintainerProClient, type MaintainerProClientOptions, type MaintainerProConversationSummary, type MaintainerProStoredMessage, type StoredChatMessage, type UseChatUnreadOptions, buildBrowserClientContext, countUnreadSince, createMaintainerProClient, fetchChatMessageTimestamps, fetchChatMessages, rememberConversationId, startChatUnreadPoller, useChatUnread, useClientContextBuilder, usePersistedChatOpen };