@getmantl/react

React SDK for Mantl — a drop-in AI copilot you can embed into any website. Renders a chat panel docked alongside your app, aware of the signed-in user, with the ability to call functions you expose from the host app.

Install

npm install @getmantl/react

Quickstart

import { MantlProvider, MantlSidebar, type ClientTools } from "@getmantl/react";

// Functions you let the AI call from inside your app.
const tools: ClientTools = {
  openInvoice: {
    description: "Open an invoice by its ID.",
    parameters: {
      type: "object",
      properties: { id: { type: "string" } },
      required: ["id"],
    },
    execute: ({ id }) => {
      window.location.href = `/invoices/${id}`;
      return { success: true };
    },
  },
};

export function App() {
  return (
    <MantlProvider
      // Fetch a project-scoped JWT from your own backend.
      // The backend signs it with your project's secret key.
      getToken={async () => {
        const res = await fetch("/api/mantl-token");
        const { token } = await res.json();
        return token;
      }}
      tools={tools}
    >
      <YourApp />
      <MantlSidebar position="right" />
    </MantlProvider>
  );
}

You'll need:

1. A project on getmantl.com — gives you a project ID and secret key.
2. A small endpoint on your backend that signs a JWT with that secret key (one HMAC-SHA256 call — payload: { sub: userId, proj: projectId }).

Model selection, system prompt, knowledge base articles, MCP servers, and per-user rate limits are all configured from the Mantl admin dashboard — no code changes needed on your end.

What you get

• <MantlProvider> — sets up the chat session and auth.
• <MantlSidebar> — pre-built dockable chat panel. Replace with your own UI using useMantl / useMantlChat if you want.
• useMantlTools(tools) — register clientTools dynamically (e.g. per-page) so the AI can call functions in your app.
• Hooks: useMantl, useMantlChat, useMantlContext for building custom UIs.

Handling auth failures

If getToken fails (network blip, expired JWT, revoked key), the built-in <MantlSidebar> hides itself automatically — end-users won't see API errors. Developers see a [Mantl] Authentication failed: ... message in the console.

Two extra hooks for handling the broken state yourself:

// 1. Get notified when auth fails (e.g. to show your own banner)
<MantlProvider
  getToken={...}
  onTokenError={(err) => showBanner(`Please sign in again`)}
/>

// 2. If you built a custom launcher button, gate it on `isReady`
function MyLauncher() {
  const { isReady, openSidebar } = useMantl();
  if (!isReady) return null;
  return <button onClick={openSidebar}>Ask AI</button>;
}

Roadmap

Angular and Vue SDKs are planned and will share the same backend.

License

MIT