@magemetrics/core 0.12.2 → 0.14.0

package/README.md

@@ -0,0 +1,220 @@
+# @magemetrics/core
+
+Headless Magemetrics client for custom integrations.
+
+`@magemetrics/core` is designed for customers who want to build their own UI while reusing Magemetrics authentication, flow APIs, chat transport, file uploads, and typed domain models.
+
+## What You Need
+
+- `@magemetrics/core` for auth, flow APIs, chat transport, files, and types
+- The AI SDK for chat state and streaming
+- Your own UI layer in React, Svelte, Vue, or another framework
+
+## Create A Client
+
+```ts
+import { MageMetricsClient } from "@magemetrics/core";
+
+export const client = new MageMetricsClient({
+  apiUrl: "https://your-magemetrics-instance.com",
+  apiKey: "mm_live_...",
+  externalJwt: "customer-session-jwt",
+});
+```
+
+## Start Or Resume A Flow
+
+```ts
+const { flowId } = await client.api.createFlow({
+  query: "Show me revenue by country for the last 90 days",
+});
+
+const existingMessages = await client.api.getChatMessages(flowId);
+const flow = await client.api.getFlow(flowId);
+const reports = await client.api.getFlowDataReports(flowId);
+const visualizations = await client.api.getFlowVisualizations(flowId);
+```
+
+## Connect The AI SDK
+
+The simplest integration is to reuse the Magemetrics transport with an AI SDK `Chat` instance and hydrate it with stored history.
+
+```tsx
+import { Chat, lastAssistantMessageIsCompleteWithToolCalls } from "@ai-sdk/react";
+import { useChat } from "@ai-sdk/react";
+import type { MMChatUIMessage } from "@magemetrics/core";
+import { client } from "./client";
+
+const chat = new Chat<MMChatUIMessage>({
+  id: `chat-${flowId}`,
+  transport: client.api.getChatTransport(flowId),
+  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+});
+
+chat.setMessages(await client.api.getChatMessages(flowId));
+
+const state = useChat({
+  chat,
+});
+```
+
+`sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls` is important to support interactive tools such as `askUserQuestion`.
+
+## Bootstrap The First Assistant Turn
+
+`createFlow(...)` persists the first user message and returns `flowId`. The first assistant response starts when the chat stream is resumed.
+
+After hydrating message history, if there is only one user message, trigger a one-time `regenerate()`:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { hasOnlyInitialUserMessage } from "@magemetrics/core";
+
+const hasStartedRef = useRef(false);
+
+useEffect(() => {
+  if (
+    status === "ready" &&
+    hasOnlyInitialUserMessage(messages) &&
+    !hasStartedRef.current
+  ) {
+    hasStartedRef.current = true;
+    void regenerate();
+  }
+}, [messages, status, regenerate]);
+```
+
+## Handle Frontend Tools
+
+Magemetrics can stream tool parts alongside assistant text. The main frontend-executed tool today is `askUserQuestion`.
+
+**Important:** You must handle `tool-askUserQuestion` and always send a tool output.
+If your UI never calls `chat.addToolOutput(...)`, the conversation can stay blocked waiting for tool completion.
+
+```ts
+import {
+  ASK_USER_QUESTION,
+  type AskUserQuestionInput,
+  type MMChatUIMessagePart,
+} from "@magemetrics/core";
+
+const renderPart = (part: MMChatUIMessagePart) => {
+  if (part.type !== `tool-${ASK_USER_QUESTION}`) {
+    return null;
+  }
+
+  if (part.state === "input-available") {
+    const input: AskUserQuestionInput = part.input;
+
+    return {
+      questions: input.questions,
+      submit: async (answers: Record<string, string>) => {
+        await chat.addToolOutput({
+          tool: ASK_USER_QUESTION,
+          toolCallId: part.toolCallId,
+          output: {
+            tool: ASK_USER_QUESTION,
+            result: { status: "success", answers },
+          },
+        });
+      },
+      cancel: async () => {
+        await chat.addToolOutput({
+          tool: ASK_USER_QUESTION,
+          toolCallId: part.toolCallId,
+          output: {
+            tool: ASK_USER_QUESTION,
+            result: {
+              status: "error",
+              message: "User dismissed the question form.",
+            },
+          },
+        });
+      },
+    };
+  }
+
+  return null;
+};
+```
+
+The transport marks tool submissions correctly and the AI SDK can resume the stream automatically after `chat.addToolOutput(...)`.
+
+Required behavior for frontend tools:
+
+1. Detect `tool-askUserQuestion` parts.
+2. Render the question UI for `state === "input-available"`.
+3. Call `chat.addToolOutput(...)` for every tool call (submit and cancel paths).
+4. Keep `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls` enabled so the stream resumes automatically.
+
+## Read Custom Data Parts
+
+Messages can include custom streamed data parts in addition to text and tool calls.
+
+- `quick-actions`: suggested follow-up prompts
+- `report-status`: inline report generation status
+- `node-added`: a new canvas node created during the run
+
+The exported `MMChatUIMessage`, `MMChatUIMessagePart`, `QuickAction`, and `SignalWithReportId` types are designed for this.
+
+## Send Files
+
+```ts
+import {
+  CHAT_FILE_ACCEPT,
+  toUploadedFileRefUrl,
+  type UploadedFile,
+} from "@magemetrics/core";
+
+const uploaded = await client.api.uploadFile(file);
+
+const filePart = {
+  type: "file" as const,
+  filename: uploaded.filename,
+  mediaType: uploaded.mediaType,
+  url: toUploadedFileRefUrl(uploaded.uploadedFileId),
+};
+```
+
+For the first user request, attach uploaded files during flow creation:
+
+```ts
+const uploaded = await client.api.uploadFile(file);
+
+const { flowId } = await client.api.createFlow({
+  query: "Summarize this PDF",
+  uploadedFileIds: [uploaded.uploadedFileId],
+});
+```
+
+For later requests in an existing conversation, include the file part in the message you send through the AI SDK.
+
+## Typed Domain Data
+
+`@magemetrics/core` also exports the main response types you need to build custom views:
+
+- `FrontendFlow`
+- `FrontendRecentFlows`
+- `FrontendReport`
+- `FrontendReportColumns`
+- `FrontendReportExplainability`
+- `FrontendVisualization`
+- `FrontendVisualizationWithData`
+- `PromptStarter`
+- `FrontendRecommendations`
+
+Use `isFrontendV2VisualizationWithData(...)` if you need to branch on visualization shape at runtime (you will never need to deal with older V1 versions).
+
+## Utilities
+
+- `client.api.getPromptStarters(input?)`
+- `client.api.getRecommendations(count)`
+- `toSearchParams(...)` for report filtering and sorting
+- `getMessageTextContent(...)` to extract plain text from an AI SDK message
+- `hasOnlyInitialUserMessage(...)` to detect when a newly created flow still needs its first assistant turn
+
+## Notes
+
+- `client.api.getChatTransport(flowId)` assumes the AI SDK stream protocol used by Magemetrics chat.
+- `client.api.getChatMessages(flowId)` returns the redacted frontend-safe message history.
+- Tool outputs exposed through chat are already redacted for frontend use. Use the exported `Redacted*` response types when rendering them.