@fayz-ai/plugin-conversations 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faya Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @fayz-ai/plugin-conversations
+
+> One omni-channel inbox — SMS, WhatsApp, Instagram, email, and web chat in one thread.
+
+[![npm](https://img.shields.io/npm/v/@fayz-ai/plugin-conversations.svg)](https://www.npmjs.com/package/@fayz-ai/plugin-conversations)
+[![license](https://img.shields.io/npm/l/@fayz-ai/plugin-conversations.svg)](https://github.com/FayaLabs/fayz-sdk/blob/main/LICENSE)
+
+Customers reach out everywhere — a WhatsApp here, an Instagram DM there, an email, a text. Replying across five tabs is how businesses drop conversations. `plugin-conversations` is the GoHighLevel-style unified inbox for the Fayz engine: every channel collapses into one threaded view, so a salon, a restaurant, or an agency answers everyone from a single place.
+
+This is foundational today. The plugin ships a complete inbox UI and a data-provider seam: it runs on a rich mock out of the box, and reads/writes the `conversations` + `conversation_messages` tables (tenant-scoped) when a Supabase client is registered. Real channel connectors — Twilio, WhatsApp Cloud, Meta, IMAP — are the next milestone, but the inbox, the store, the events, and the AI tools are already wired so the rest snaps in behind them.
+
+## What's inside
+- A full-bleed `/conversations` inbox view backed by a Zustand store
+- A `ConversationsProvider` seam: mock provider, or a Supabase provider (tenant-scoped via the active org) when a client is registered
+- Domain events: `conversations.message.received`, `conversations.message.sent`
+- AI tools: `listConversations` (filter by `sms` / `whatsapp` / `instagram` / `email` / `webchat`) and `sendMessage`
+- Configurable navigation and full i18n
+- Exported types (`Conversation`, `Message`, `Channel`) and the Supabase provider factory for custom wiring
+
+## Install
+```bash
+npm install @fayz-ai/plugin-conversations
+```
+Peer deps: `@fayz-ai/core`, `@fayz-ai/ui`, `@fayz-ai/saas`, plus `react` / `react-dom`.
+
+## Usage
+```tsx
+import { defineSaas } from '@fayz-ai/saas'
+import { createConversationsPlugin } from '@fayz-ai/plugin-conversations'
+
+export const app = defineSaas({
+  // ...
+  plugins: [
+    createConversationsPlugin({ navLabel: 'Inbox', navPosition: 1 }),
+  ],
+})
+```
+With no Supabase client registered it runs on the mock inbox; register one and it persists to `conversations` / `conversation_messages` automatically.
+
+## Part of the Fayz SDK
+The conversation layer of the engine. Pairs with `plugin-crm` (who you're talking to), `plugin-marketing` (broadcasts that start the thread), and `plugin-reputation` (turning a happy reply into a review).
+
+## Roadmap & contributing
+Early and foundational — built in the open. See the [Fayz SDK roadmap](../../docs/ROADMAP.md#plugin-conversations) for current gaps, missing features, and good first issues.

package/dist/ConversationsContext.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { type StoreApi } from 'zustand';
+import type { ConversationsUIState } from './store';
+export declare function ConversationsContextProvider({ store, children, }: {
+    store: StoreApi<ConversationsUIState>;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export declare function useConversationsStore<T>(selector: (state: ConversationsUIState) => T): T;
+//# sourceMappingURL=ConversationsContext.d.ts.map

package/dist/ConversationsContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationsContext.d.ts","sourceRoot":"","sources":["../src/ConversationsContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAInD,wBAAgB,4BAA4B,CAAC,EAC3C,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B,qBAEA;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,CAAC,GAAG,CAAC,CAIxF"}

package/dist/ConversationsPage.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { StoreApi } from 'zustand/vanilla';
+import type { ConversationsUIState } from './store';
+export declare function ConversationsPage({ store }: {
+    store: StoreApi<ConversationsUIState>;
+}): React.JSX.Element;
+//# sourceMappingURL=ConversationsPage.d.ts.map

package/dist/ConversationsPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationsPage.d.ts","sourceRoot":"","sources":["../src/ConversationsPage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAGnD,wBAAgB,iBAAiB,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAA;CAAE,qBAWrF"}

package/dist/channel.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import { CHANNEL_LABELS, type Channel } from './types';
+export declare const CHANNEL_ICON: Record<Channel, React.ComponentType<{
+    className?: string;
+}>>;
+export interface ChannelAccent {
+    /** Solid brand color (hex) — bubbles, dots, header chips. */
+    color: string;
+    /** Soft tinted background classes for badges. */
+    badge: string;
+}
+export declare const CHANNEL_ACCENT: Record<Channel, ChannelAccent>;
+export { CHANNEL_LABELS };
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAQtD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAMrF,CAAA;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,aAAa,CAMzD,CAAA;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/data/mock.d.ts

@@ -0,0 +1,3 @@
+import type { ConversationsProvider } from './types';
+export declare function createMockConversationsProvider(): ConversationsProvider;
+//# sourceMappingURL=mock.d.ts.map

package/dist/data/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/data/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAoFpD,wBAAgB,+BAA+B,IAAI,qBAAqB,CAyDvE"}

package/dist/data/supabase.d.ts

@@ -0,0 +1,11 @@
+import type { ConversationsProvider } from './types';
+export interface SupabaseConversationsConfig {
+    /** Supabase client; defaults to the global one registered by createFayzApp. */
+    supabaseClient?: unknown;
+    /** Active tenant id (value or getter) used to scope reads and stamp writes. */
+    tenantId?: string | (() => string | undefined);
+    /** Display name stamped as the author of outbound messages. */
+    selfAuthor?: string;
+}
+export declare function createSupabaseConversationsProvider(config?: SupabaseConversationsConfig): ConversationsProvider;
+//# sourceMappingURL=supabase.d.ts.map

package/dist/data/supabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/data/supabase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAoBpD,MAAM,WAAW,2BAA2B;IAC1C,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAA;IAC9C,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAkCD,wBAAgB,mCAAmC,CACjD,MAAM,CAAC,EAAE,2BAA2B,GACnC,qBAAqB,CAyIvB"}

package/dist/data/types.d.ts

@@ -0,0 +1,9 @@
+import type { Conversation, Message, ListConversationsQuery, SendMessageInput, ConversationStatus } from '../types';
+export interface ConversationsProvider {
+    listConversations(query?: ListConversationsQuery): Promise<Conversation[]>;
+    getMessages(conversationId: string): Promise<Message[]>;
+    sendMessage(input: SendMessageInput): Promise<Message>;
+    markRead(conversationId: string): Promise<void>;
+    setStatus(conversationId: string, status: ConversationStatus): Promise<Conversation>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/data/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/data/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EACP,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAEjB,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,CAAC,KAAK,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IAC1E,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACvD,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACtD,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACrF"}