conversokit 0.1.0

package/templates/commerce/apps/widget-ui/src/App.tsx

@@ -0,0 +1,75 @@
+import React, { useEffect, useState } from 'react';
+import {
+  AddToCartPanel,
+  CTABanner,
+  CheckoutSummary,
+  ConsentBanner,
+  ProductCarousel,
+  type ProductCardProps
+} from '@conversokit/widgets';
+import {
+  EXAMPLE_CHECKOUT_SUMMARY,
+  type CartItem
+} from '@conversokit/shared';
+import { ThemeProvider, commerceTheme } from '@conversokit/themes';
+import { BridgeProvider, useBridge } from '@conversokit/bridge';
+
+const Catalog: React.FC = () => {
+  const bridge = useBridge();
+  const [items, setItems] = useState<ProductCardProps[]>([]);
+  const [cart, setCart] = useState<CartItem[]>([]);
+
+  useEffect(() => {
+    bridge
+      .callTool('search_products', { query: '', limit: 10 })
+      .then((r) => setItems((r as { items: ProductCardProps[] }).items))
+      .catch(console.error);
+  }, [bridge]);
+
+  const checkout = async () => {
+    await bridge.callTool('set_cart', { items: cart, currency: 'USD' });
+    const result = (await bridge.callTool('create_checkout', {
+      successUrl: window.location.origin + '/?status=success',
+      cancelUrl: window.location.origin + '/?status=cancelled'
+    })) as { url: string };
+    window.location.href = result.url;
+  };
+
+  return (
+    <>
+      <ProductCarousel items={items} />
+      {items[0] && (
+        <AddToCartPanel
+          product={items[0]}
+          onAdd={(item) => setCart((c) => [...c, item])}
+        />
+      )}
+      {cart.length > 0 && (
+        <CheckoutSummary
+          summary={{ ...EXAMPLE_CHECKOUT_SUMMARY, items: cart }}
+          onCheckout={checkout}
+        />
+      )}
+    </>
+  );
+};
+
+const App: React.FC = () => (
+  <BridgeProvider baseUrl="http://localhost:3000">
+    <ThemeProvider
+      theme={commerceTheme}
+      style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}
+    >
+      <h1>Welcome to <% projectName %></h1>
+      <CTABanner
+        title="Commerce demo"
+        description="Search → add to cart → checkout via Stripe (or MockPaymentProvider in dev)."
+      />
+      <ConsentBanner scopes={['analytics']}>
+        <Catalog />
+      </ConsentBanner>
+    </ThemeProvider>
+  </BridgeProvider>
+);
+
+export default App;

package/templates/dashboard/apps/mcp-server/src/tools/getAlerts.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { EXAMPLE_ALERTS, alertSchema, defineTool } from '@conversokit/shared';
+
+export const getAlertsTool = defineTool({
+  name: 'get_alerts',
+  description: 'Return active operational alerts.',
+  inputSchema: z.object({
+    severity: z.enum(['info', 'warning', 'critical']).optional()
+  }),
+  outputSchema: z.object({ items: z.array(alertSchema) }),
+  permissions: { requiresAuth: false },
+  async handler(input) {
+    const items = input.severity
+      ? EXAMPLE_ALERTS.filter((a) => a.severity === input.severity)
+      : EXAMPLE_ALERTS;
+    return { items };
+  }
+});

package/templates/dashboard/apps/mcp-server/src/tools/getAnalyticsPanel.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_ANALYTICS_PANEL,
+  analyticsPanelSchema,
+  defineTool
+} from '@conversokit/shared';
+
+export const getAnalyticsPanelTool = defineTool({
+  name: 'get_analytics_panel',
+  description: 'Return the assembled analytics panel (KPIs + trend series).',
+  inputSchema: z.object({}),
+  outputSchema: z.object({ panel: analyticsPanelSchema }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { panel: EXAMPLE_ANALYTICS_PANEL };
+  }
+});

package/templates/dashboard/apps/mcp-server/src/tools/getKpis.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { EXAMPLE_KPIS, defineTool, kpiSchema } from '@conversokit/shared';
+
+export const getKpisTool = defineTool({
+  name: 'get_kpis',
+  description: 'Return the headline KPIs for the dashboard.',
+  inputSchema: z.object({}),
+  outputSchema: z.object({ items: z.array(kpiSchema) }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { items: EXAMPLE_KPIS };
+  }
+});

package/templates/dashboard/apps/mcp-server/src/tools/getTrendSeries.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_TREND_SERIES,
+  defineTool,
+  trendSeriesSchema
+} from '@conversokit/shared';
+
+export const getTrendSeriesTool = defineTool({
+  name: 'get_trend_series',
+  description: 'Return a time-series trend for a given metric.',
+  inputSchema: z.object({
+    metric: z.string().optional(),
+    range: z.enum(['7d', '30d', '12w', '12m']).optional()
+  }),
+  outputSchema: z.object({ series: trendSeriesSchema }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { series: EXAMPLE_TREND_SERIES };
+  }
+});

package/templates/dashboard/apps/mcp-server/src/tools/index.ts

@@ -0,0 +1,14 @@
+import type { Tool } from '@conversokit/shared';
+import { getKpisTool } from './getKpis.js';
+import { getTrendSeriesTool } from './getTrendSeries.js';
+import { getAnalyticsPanelTool } from './getAnalyticsPanel.js';
+import { getAlertsTool } from './getAlerts.js';
+
+// Starter overlay: dashboard tools are unauthenticated for the demo.
+// In production, set permissions.requiresAuth = true on each and wire JWT/Clerk.
+export const tools: Tool[] = [
+  getKpisTool,
+  getTrendSeriesTool,
+  getAnalyticsPanelTool,
+  getAlertsTool
+];

package/templates/dashboard/apps/widget-ui/src/App.tsx

@@ -0,0 +1,66 @@
+import React, { useEffect, useState } from 'react';
+import {
+  AlertFeed,
+  AnalyticsPanel,
+  CTABanner
+} from '@conversokit/widgets';
+import {
+  type Alert,
+  type AnalyticsPanel as AnalyticsPanelData
+} from '@conversokit/shared';
+import { ThemeProvider, enterpriseTheme } from '@conversokit/themes';
+import { BridgeProvider, useBridge } from '@conversokit/bridge';
+
+const Dashboard: React.FC = () => {
+  const bridge = useBridge();
+  const [panel, setPanel] = useState<AnalyticsPanelData | null>(null);
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+
+  useEffect(() => {
+    Promise.all([
+      bridge.callTool('get_analytics_panel', {}) as Promise<{
+        panel: AnalyticsPanelData;
+      }>,
+      bridge.callTool('get_alerts', {}) as Promise<{ items: Alert[] }>
+    ])
+      .then(([p, a]) => {
+        setPanel(p.panel);
+        setAlerts(a.items);
+      })
+      .catch(console.error);
+  }, [bridge]);
+
+  return (
+    <>
+      {panel && <AnalyticsPanel panel={panel} />}
+      <h3>Alerts</h3>
+      <AlertFeed
+        alerts={alerts}
+        onAcknowledge={(a) =>
+          setAlerts((current) => current.filter((x) => x.id !== a.id))
+        }
+      />
+    </>
+  );
+};
+
+const App: React.FC = () => {
+  const apiKey = (import.meta.env?.VITE_CONVERSOKIT_API_KEY as string) || undefined;
+  return (
+    <BridgeProvider baseUrl="http://localhost:3000" apiKey={apiKey}>
+      <ThemeProvider
+        theme={enterpriseTheme}
+        style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}
+      >
+        <h1>Welcome to <% projectName %></h1>
+        <CTABanner
+          title="Internal dashboard"
+          description="Set CONVERSOKIT_API_KEYS in apps/mcp-server/.env and pass it via VITE_CONVERSOKIT_API_KEY."
+        />
+        <Dashboard />
+      </ThemeProvider>
+    </BridgeProvider>
+  );
+};
+
+export default App;

package/templates/deploy/docker/.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+**/node_modules
+**/dist
+.git
+.env
+.env.local
+.turbo
+**/.turbo
+*.log
+.DS_Store

package/templates/deploy/docker/Dockerfile

@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-alpine AS base
+RUN corepack enable && corepack prepare pnpm@9 --activate
+WORKDIR /app
+
+FROM base AS deps
+COPY pnpm-lock.yaml package.json pnpm-workspace.yaml turbo.json ./
+COPY apps/mcp-server/package.json ./apps/mcp-server/
+COPY packages ./packages
+RUN pnpm install --frozen-lockfile --prod=false
+
+FROM deps AS build
+COPY . .
+RUN pnpm -w build
+
+FROM base AS runtime
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/packages ./packages
+COPY --from=build /app/apps/mcp-server/dist ./apps/mcp-server/dist
+COPY --from=build /app/apps/mcp-server/package.json ./apps/mcp-server/
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD wget -q -O - http://localhost:3000/health || exit 1
+CMD ["node", "apps/mcp-server/dist/index.js"]

package/templates/deploy/docker/docker-compose.yml

@@ -0,0 +1,31 @@
+services:
+  mcp-server:
+    build: .
+    image: <% projectName %>:latest
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    environment:
+      NODE_ENV: production
+      PORT: 3000
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "-", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+  # Uncomment to add a Postgres for users not on Supabase.
+  # postgres:
+  #   image: postgres:16-alpine
+  #   environment:
+  #     POSTGRES_USER: conversokit
+  #     POSTGRES_PASSWORD: conversokit
+  #     POSTGRES_DB: conversokit
+  #   ports:
+  #     - "5432:5432"
+  #   volumes:
+  #     - postgres_data:/var/lib/postgresql/data
+
+# volumes:
+#   postgres_data:

package/templates/deploy/railway/Procfile

@@ -0,0 +1 @@
+web: pnpm --filter mcp-server start

package/templates/deploy/railway/railway.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://railway.app/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS",
+    "buildCommand": "pnpm install --frozen-lockfile && pnpm -w build"
+  },
+  "deploy": {
+    "startCommand": "pnpm --filter mcp-server start",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 30,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

package/templates/deploy/vercel/api/mcp.ts

@@ -0,0 +1,10 @@
+// Vercel serverless adapter for the ConversoKit MCP server.
+// Re-exports the express app from `apps/mcp-server` so all routes (/tools,
+// /auth, /webhooks, /userdata, /admin, /health) are answered by one function.
+//
+// Make sure `apps/mcp-server/src/index.ts` exports the app:
+//   export { app };
+// then this file imports it as `app`.
+import app from '../apps/mcp-server/dist/index.js';
+
+export default app;

package/templates/deploy/vercel/vercel.json

@@ -0,0 +1,19 @@
+{
+  "version": 2,
+  "buildCommand": "pnpm -w build",
+  "installCommand": "pnpm -w install --frozen-lockfile",
+  "outputDirectory": "apps/widget-ui/dist",
+  "rewrites": [
+    { "source": "/tools/:path*", "destination": "/api/mcp" },
+    { "source": "/auth/:path*", "destination": "/api/mcp" },
+    { "source": "/userdata/:path*", "destination": "/api/mcp" },
+    { "source": "/webhooks/:path*", "destination": "/api/mcp" },
+    { "source": "/admin/:path*", "destination": "/api/mcp" },
+    { "source": "/health", "destination": "/api/mcp" }
+  ],
+  "functions": {
+    "api/mcp.ts": {
+      "runtime": "nodejs20.x"
+    }
+  }
+}

package/templates/saas-onboarding/apps/mcp-server/src/tools/index.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '@conversokit/shared';
+import { submitLeadTool } from './submitLead.js';
+
+export const tools: Tool[] = [submitLeadTool];

package/templates/saas-onboarding/apps/mcp-server/src/tools/submitLead.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { defineTool, leadSubmissionSchema } from '@conversokit/shared';
+
+export const submitLeadTool = defineTool({
+  name: 'submit_lead',
+  description:
+    'Submit a qualified lead. Replace this stub with a CRM upsert (HubSpot, Salesforce, etc.) when wiring real persistence.',
+  inputSchema: leadSubmissionSchema,
+  outputSchema: z.object({
+    leadId: z.string(),
+    provider: z.string()
+  }),
+  permissions: { requiresAuth: false, requiresConsent: true },
+  async handler() {
+    return {
+      leadId: `lead_${Math.random().toString(36).slice(2)}`,
+      provider: 'mock'
+    };
+  }
+});

package/templates/saas-onboarding/apps/widget-ui/src/App.tsx

@@ -0,0 +1,56 @@
+import React, { useState } from 'react';
+import {
+  CTABanner,
+  ConsentBanner,
+  MultiStepForm
+} from '@conversokit/widgets';
+import { EXAMPLE_LEAD_FORM } from '@conversokit/shared';
+import { ThemeProvider, modernSaasTheme } from '@conversokit/themes';
+import { BridgeProvider, useBridge } from '@conversokit/bridge';
+
+const Onboarding: React.FC = () => {
+  const bridge = useBridge();
+  const [done, setDone] = useState<{ leadId: string; provider: string } | null>(
+    null
+  );
+
+  if (done) {
+    return (
+      <CTABanner
+        title="Thanks!"
+        description={`Lead ${done.leadId} synced via ${done.provider}.`}
+        variant="success"
+      />
+    );
+  }
+
+  return (
+    <MultiStepForm
+      form={EXAMPLE_LEAD_FORM}
+      onComplete={async (values) => {
+        const r = (await bridge.callTool('submit_lead', {
+          formId: EXAMPLE_LEAD_FORM.id,
+          values,
+          submittedAt: new Date().toISOString()
+        })) as { leadId: string; provider: string };
+        setDone(r);
+      }}
+    />
+  );
+};
+
+const App: React.FC = () => (
+  <BridgeProvider baseUrl="http://localhost:3000">
+    <ThemeProvider
+      theme={modernSaasTheme}
+      style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}
+    >
+      <h1>Welcome to <% projectName %></h1>
+      <ConsentBanner scopes={['personalData', 'marketing']}>
+        <Onboarding />
+      </ConsentBanner>
+    </ThemeProvider>
+  </BridgeProvider>
+);
+
+export default App;

package/templates/travel/apps/mcp-server/src/tools/getItinerary.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_ITINERARY,
+  defineTool,
+  itinerarySchema
+} from '@conversokit/shared';
+
+export const getItineraryTool = defineTool({
+  name: 'get_itinerary',
+  description: 'Return a saved travel itinerary by id.',
+  inputSchema: z.object({ itineraryId: z.string() }),
+  outputSchema: z.object({ itinerary: itinerarySchema }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { itinerary: EXAMPLE_ITINERARY };
+  }
+});

package/templates/travel/apps/mcp-server/src/tools/index.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '@conversokit/shared';
+import { listDestinationsTool } from './listDestinations.js';
+import { searchHotelsTool } from './searchHotels.js';
+import { searchFlightsTool } from './searchFlights.js';
+import { getItineraryTool } from './getItinerary.js';
+
+export const tools: Tool[] = [
+  listDestinationsTool,
+  searchHotelsTool,
+  searchFlightsTool,
+  getItineraryTool
+];

package/templates/travel/apps/mcp-server/src/tools/listDestinations.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_DESTINATIONS,
+  defineTool,
+  destinationSchema
+} from '@conversokit/shared';
+
+export const listDestinationsTool = defineTool({
+  name: 'list_destinations',
+  description: 'Return curated destination recommendations.',
+  inputSchema: z.object({
+    query: z.string().optional(),
+    limit: z.number().int().min(1).max(50).optional()
+  }),
+  outputSchema: z.object({ items: z.array(destinationSchema) }),
+  permissions: { requiresAuth: false },
+  async handler(input) {
+    const lower = input.query?.toLowerCase();
+    const matches = lower
+      ? EXAMPLE_DESTINATIONS.filter(
+          (d) =>
+            d.name.toLowerCase().includes(lower) ||
+            (d.country?.toLowerCase().includes(lower) ?? false)
+        )
+      : EXAMPLE_DESTINATIONS;
+    return { items: matches.slice(0, input.limit ?? 20) };
+  }
+});

package/templates/travel/apps/mcp-server/src/tools/searchFlights.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_FLIGHT,
+  defineTool,
+  flightSummarySchema
+} from '@conversokit/shared';
+
+export const searchFlightsTool = defineTool({
+  name: 'search_flights',
+  description: 'Search flights by IATA origin and destination.',
+  inputSchema: z.object({
+    origin: z.string(),
+    destination: z.string(),
+    departDate: z.string().optional(),
+    returnDate: z.string().optional()
+  }),
+  outputSchema: z.object({ items: z.array(flightSummarySchema) }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { items: [EXAMPLE_FLIGHT] };
+  }
+});

package/templates/travel/apps/mcp-server/src/tools/searchHotels.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_HOTELS,
+  defineTool,
+  hotelSchema
+} from '@conversokit/shared';
+
+export const searchHotelsTool = defineTool({
+  name: 'search_hotels',
+  description: 'Search hotels by free-text query (matches city or hotel name).',
+  inputSchema: z.object({
+    query: z.string(),
+    limit: z.number().int().min(1).max(50).optional()
+  }),
+  outputSchema: z.object({ items: z.array(hotelSchema) }),
+  permissions: { requiresAuth: false },
+  async handler(input) {
+    const lower = input.query.toLowerCase();
+    const matches = lower
+      ? EXAMPLE_HOTELS.filter(
+          (h) =>
+            h.name.toLowerCase().includes(lower) ||
+            h.city.toLowerCase().includes(lower) ||
+            (h.country?.toLowerCase().includes(lower) ?? false)
+        )
+      : EXAMPLE_HOTELS;
+    return { items: matches.slice(0, input.limit ?? 10) };
+  }
+});

package/templates/travel/apps/widget-ui/src/App.tsx

@@ -0,0 +1,89 @@
+import React, { useEffect, useState } from 'react';
+import {
+  CTABanner,
+  ConsentBanner,
+  DestinationRecommendations,
+  FlightSummary,
+  HotelCard,
+  ItineraryTimeline
+} from '@conversokit/widgets';
+import {
+  type Destination,
+  type FlightSummary as FlightSummaryData,
+  type Hotel,
+  type Itinerary
+} from '@conversokit/shared';
+import { ThemeProvider, travelTheme } from '@conversokit/themes';
+import { BridgeProvider, useBridge } from '@conversokit/bridge';
+
+const TravelPlanner: React.FC = () => {
+  const bridge = useBridge();
+  const [destinations, setDestinations] = useState<Destination[]>([]);
+  const [hotels, setHotels] = useState<Hotel[]>([]);
+  const [flight, setFlight] = useState<FlightSummaryData | null>(null);
+  const [itinerary, setItinerary] = useState<Itinerary | null>(null);
+  const [picked, setPicked] = useState<Destination | null>(null);
+
+  useEffect(() => {
+    bridge
+      .callTool('list_destinations', {})
+      .then((r) => setDestinations((r as { items: Destination[] }).items))
+      .catch(console.error);
+  }, [bridge]);
+
+  const pick = async (dest: Destination) => {
+    setPicked(dest);
+    const [h, f] = await Promise.all([
+      bridge.callTool('search_hotels', { query: dest.name }) as Promise<{
+        items: Hotel[];
+      }>,
+      bridge.callTool('search_flights', {
+        origin: 'BER',
+        destination: dest.name.slice(0, 3).toUpperCase()
+      }) as Promise<{ items: FlightSummaryData[] }>
+    ]);
+    setHotels(h.items);
+    setFlight(f.items[0] ?? null);
+  };
+
+  const buildItinerary = async () => {
+    const r = (await bridge.callTool('get_itinerary', {
+      itineraryId: 'demo'
+    })) as { itinerary: Itinerary };
+    setItinerary(r.itinerary);
+  };
+
+  return (
+    <>
+      <DestinationRecommendations destinations={destinations} onSelect={pick} />
+      {picked && (
+        <CTABanner
+          title={`Plan a trip to ${picked.name}`}
+          primaryLabel="Build itinerary"
+          onPrimary={buildItinerary}
+        />
+      )}
+      {hotels.map((h) => (
+        <HotelCard key={h.id} hotel={h} />
+      ))}
+      {flight && <FlightSummary flight={flight} />}
+      {itinerary && <ItineraryTimeline itinerary={itinerary} />}
+    </>
+  );
+};
+
+const App: React.FC = () => (
+  <BridgeProvider baseUrl="http://localhost:3000">
+    <ThemeProvider
+      theme={travelTheme}
+      style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}
+    >
+      <h1>Welcome to <% projectName %></h1>
+      <ConsentBanner scopes={['analytics']}>
+        <TravelPlanner />
+      </ConsentBanner>
+    </ThemeProvider>
+  </BridgeProvider>
+);
+
+export default App;