@magemetrics/ai 0.0.52 → 0.0.54-RC2

package/README.md

@@ -0,0 +1,228 @@
+# @magemetrics/ai
+
+This package provides a set of React components and a web component to integrate MageMetrics AI functionalities into your application.
+
+## Installation
+
+To install the package, run the following command:
+
+```bash
+npm install @magemetrics/ai
+```
+
+You also need to include the styles in your application:
+
+```javascript
+import "@magemetrics/ai/styles.css";
+```
+
+## React Usage
+
+### Quick Start: `ManagedModal`
+
+The easiest way to get started is by using the `ManagedModal` component. It provides a fully managed experience, including a launcher button and a conversation view, and it doesn't require a context provider.
+
+```tsx
+import { ManagedModal } from "@magemetrics/ai/react";
+
+const YourComponent = () => {
+  return (
+    <ManagedModal
+      externalJwt={YOUR_EXTERNAL_JWT}
+      apiKey={YOUR_API_KEY}
+      apiUrl={YOUR_API_URL}
+      display="contents"
+      startOptions={{
+        showRecentChats: true,
+        showRecommendations: true,
+        showBackdrop: true,
+      }}
+    />
+  );
+};
+```
+
+**Props:**
+
+- `externalJwt` (string): The external JWT for authentication.
+- `apiKey` (string): Your MageMetrics API key.
+- `apiUrl` (string): The URL of the MageMetrics API.
+- `display` ('string'): The display style of the modal.
+- `startOptions` (object): Options to configure the initial view of the modal.
+- `modal` (object): Options to control the modal visibility and behavior.
+
+### Advanced Usage
+
+For more advanced use cases, you can use the `MageMetricsContextProvider` in combination with the `StandaloneConversationModal` and other components. This gives you more control over the state and behavior of the library.
+
+#### `MageMetricsContextProvider`
+
+This is the main provider that enables all the functionalities of the library. You need to wrap your application with it.
+
+```tsx
+import { MageMetricsContextProvider } from "@magemetrics/ai/react";
+
+const App = () => {
+  return (
+    <MageMetricsContextProvider
+      externalJwt={YOUR_EXTERNAL_JWT}
+      apiKey={YOUR_API_KEY}
+      apiUrl={YOUR_API_URL}
+    >
+      {/* Your application */}
+    </MageMetricsContextProvider>
+  );
+};
+```
+
+**Props:**
+
+- `externalJwt` (string): The external JWT for authentication.
+- `apiKey` (string): Your MageMetrics API key.
+- `apiUrl` (string): The URL of the MageMetrics API.
+- `experimental_components` (Components): An optional object to override the default components.
+
+#### `StandaloneConversationModal`
+
+This component provides a standalone conversation modal that you can control with your own state. It must be used within a `MageMetricsContextProvider`.
+
+```tsx
+import { StandaloneConversationModal } from "@magemetrics/ai/react";
+import { useState } from "react";
+
+const YourComponent = () => {
+  const [isOpened, setIsOpened] = useState(false);
+  const [flowId, setFlowId] = useState<string | null>(null);
+
+  // Logic to get or create a flowId
+
+  return (
+    <div>
+      <button onClick={() => setIsOpened(true)}>Open Modal</button>
+      {flowId && (
+        <StandaloneConversationModal
+          opened={isOpened}
+          onOpenChange={setIsOpened}
+          flowId={flowId}
+        />
+      )}
+    </div>
+  );
+};
+```
+
+**Props:**
+
+- `opened` (boolean): Controls the visibility of the modal.
+- `onOpenChange` (function): A callback function that is called when the modal is closed.
+- `flowId` (string): The ID of the conversation flow to display.
+
+### Other Exports
+
+#### `DataTable`
+
+This component is used to render data tables within the conversation. It's typically used when customizing the `dataReportTable` component.
+
+```tsx
+import { DataTable, type DataReportMessageProps } from "@magemetrics/ai/react";
+
+const CustomDataTable = (props: DataReportMessageProps) => {
+  return <DataTable {...props} />;
+};
+```
+
+#### `ApiService`
+
+This class provides methods to interact with the MageMetrics API. It must be used within a `MageMetricsContextProvider`.
+
+```tsx
+import { ApiService } from "@magemetrics/ai/react";
+
+const client = new ApiService(YOUR_API_URL);
+
+// Get recent flows
+const recentFlows = await client.getRecentFlows({ limit: 10 });
+
+// Start a new flow
+const newFlowId = await client.startFlow("your prompt");
+```
+
+### Customization
+
+You can customize the components by passing an `experimental_components` object to the `MageMetricsContextProvider`.
+
+```tsx
+import {
+  MageMetricsContextProvider,
+  type Components,
+  type DataReportMessageProps,
+  DataTable,
+} from "@magemetrics/ai/react";
+
+const CustomComponent = (props: DataReportMessageProps) => {
+  return <DataTable {...props} />;
+};
+
+const components: Components = {
+  dataTableCells: {
+    empty: () => "N/A",
+    renderTypes: {
+      url: (props: unknown) => {
+        if (typeof props !== "string") return null;
+        return <a href={props}>CUSTOM LINK</a>;
+      },
+    },
+  },
+  dataReportTable: (props) => {
+    return <CustomComponent {...props} />;
+  },
+};
+
+const App = () => {
+  return (
+    <MageMetricsContextProvider
+      // ... other props
+      experimental_components={components}
+    >
+      {/* Your application */}
+    </MageMetricsContextProvider>
+  );
+};
+```
+
+## Web Component Usage
+
+You can also use the library as a web component.
+
+### Registration
+
+First, you need to register the web component in your application:
+
+```javascript
+import { createMagemetrics } from "@magemetrics/ai/web-component";
+
+createMagemetrics();
+```
+
+### Usage
+
+Then, you can use the `magemetrics-ai` custom element in your HTML:
+
+```html
+<magemetrics-ai
+  apiUrl="YOUR_API_URL"
+  apiKey="YOUR_API_KEY"
+  externalJWT="YOUR_EXTERNAL_JWT"
+  startOptions='{"showRecentChats":true,"showRecommendations":true,"showBackdrop":true}'
+></magemetrics-ai>
+```
+
+**Attributes:**
+
+- `apiUrl` (string): The URL of the MageMetrics API.
+- `apiKey` (string): Your MageMetrics API key.
+- `externalJWT` (string): The external JWT for authentication.
+- `display` (string): The display style of the modal.
+- `persist` (string): Persist the state of the component.
+- `modal` (json): Options to control the modal visibility and behavior.
+- `startOptions` (json): Options to configure the initial view of the modal.