diversion-crumb

Crumb voice assistant SDK. Install in your app, set your API key and adapters, and you get a full bakery-style experience: voice + chat widget, cart proposals, navigation, and discounts. The SDK fetches assistant config from the Crumb IaaS backend; later you can customise tools and system prompts via the provider.

Install

pnpm add diversion-crumb @vapi-ai/web

Env

• NEXT_PUBLIC_CRUMB_API_KEY – Your Crumb API key (from the IaaS provider).
• NEXT_PUBLIC_CRUMB_BACKEND_URL – Crumb backend base URL (e.g. https://api.crumb.example.com or http://localhost:3001 for dev).
• NEXT_PUBLIC_VAPI_PUBLIC_KEY – Your VAPI public key (from the same provider or your own VAPI project).

Quick start (full UI)

Wrap your app with CrumbProvider, pass adapters, and render <CrumbWidget />. You get floating voice + chat buttons, sidebar with messages and cart proposal cards (Yes/No), mic selector, and call controls. No extra UI code.

import { CrumbProvider, CrumbWidget } from "diversion-crumb";
import { useRouter } from "next/navigation";

function App({ children }) {
  const router = useRouter();
  const adapters = {
    navigate: (path) => router.push(path),
    applyDiscount: (percent) => { /* update your cart */ },
    removeFromCart: async (cartItemId) => { /* call your API */ },
    onCartUpdated: () => { /* reload cart */ },
  };

  return (
    <CrumbProvider
      apiKey={process.env.NEXT_PUBLIC_CRUMB_API_KEY!}
      backendUrl={process.env.NEXT_PUBLIC_CRUMB_BACKEND_URL!}
      vapiPublicKey={process.env.NEXT_PUBLIC_VAPI_PUBLIC_KEY!}
      adapters={adapters}
    >
      {children}
      <CrumbWidget assistantName="Crumb" />
    </CrumbProvider>
  );
}

When the assistant calls proposeCartUpdate, the widget shows the proposal cards and Yes/No automatically. Optional: pass onCartProposal if you want to show your own UI and call approveProposal() / rejectProposal() from useCrumb().

Headless (custom UI)

Use useCrumb() and build your own UI:

import { CrumbProvider, useCrumb } from "diversion-crumb";

// Wrap with CrumbProvider and adapters, then:
const { status, startCall, endCall, messages, pendingProposal, approveProposal, rejectProposal } = useCrumb();

Adapters

| Adapter | Required | Description | |--------|----------|-------------| | navigate | Yes | Navigate to a path (e.g. router.push(path)). | | onCartProposal | No | Called when the assistant shows a cart update proposal; show your UI and use approveProposal() / rejectProposal() from useCrumb(). | | applyDiscount | No | Apply a discount percentage to the cart. | | removeFromCart | No | Remove a cart item by ID (async). | | onCartUpdated | No | Called after server-side cart tools run; reload your cart. |

Provider selection and env

Your IaaS provider may give you an env template based on selected providers (STT, TTS, LLM). Set the variables they provide; the SDK only needs NEXT_PUBLIC_CRUMB_API_KEY, NEXT_PUBLIC_CRUMB_BACKEND_URL, and NEXT_PUBLIC_VAPI_PUBLIC_KEY.

Scaffolding a new project

For a new Next.js app from scratch, you can use create-vapi-agent (packages/create-agent in this repo) to scaffold a project with Vapi, shadcn/ui, and a voice agent. For the Crumb IaaS flow (our backend + tools + system prompts), use this SDK instead: install diversion-crumb, add CrumbProvider + CrumbWidget and adapters, and point env at the Crumb backend.