conversokit 0.1.0

package/dist/utils/copy.js

@@ -0,0 +1,59 @@
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+const TEXT_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.json',
+    '.md',
+    '.html',
+    '.css',
+    '.yml',
+    '.yaml',
+    '.toml',
+    '.env',
+    '.gitignore',
+    ''
+]);
+function applyReplacements(content, repl) {
+    let out = content;
+    for (const [key, value] of Object.entries(repl)) {
+        out = out.split(`<% ${key} %>`).join(value);
+    }
+    return out;
+}
+export async function copyDir(src, dest, options = {}) {
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    await fs.mkdir(dest, { recursive: true });
+    for (const entry of entries) {
+        const rel = entry.name;
+        if (options.ignore?.includes(rel))
+            continue;
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcPath, destPath, {
+                ...options,
+                ignore: options.ignore?.map((p) => p.startsWith(`${rel}/`) ? p.slice(rel.length + 1) : p)
+            });
+        }
+        else if (entry.isFile()) {
+            await copyFile(srcPath, destPath, options.replacements);
+        }
+    }
+}
+async function copyFile(src, dest, replacements) {
+    const ext = src.slice(src.lastIndexOf('.'));
+    const isText = TEXT_EXTS.has(ext);
+    if (isText && replacements) {
+        const buf = await fs.readFile(src, 'utf8');
+        await fs.writeFile(dest, applyReplacements(buf, replacements));
+    }
+    else {
+        await fs.copyFile(src, dest);
+    }
+}
+export function relativePath(from, to) {
+    return relative(from, to) || '.';
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "conversokit",
+  "version": "0.1.0",
+  "description": "CLI for ConversoKit — scaffold ChatGPT Apps in <30 minutes. Includes `create`, `add`, and `deploy` commands.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xyborg/ConversoKit.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Xyborg/ConversoKit#readme",
+  "bugs": "https://github.com/Xyborg/ConversoKit/issues",
+  "keywords": [
+    "chatgpt",
+    "openai",
+    "apps-sdk",
+    "mcp",
+    "boilerplate",
+    "react",
+    "scaffold",
+    "cli",
+    "conversokit"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/cli.js",
+  "bin": {
+    "conversokit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.2.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json && node ./scripts/postbuild.mjs",
+    "dev": "tsc --project tsconfig.json --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/templates/base/.env.example

@@ -0,0 +1,10 @@
+PORT=3000
+NODE_ENV=development
+
+# CONVERSOKIT_API_KEYS=
+# STRIPE_SECRET_KEY=
+# STRIPE_WEBHOOK_SECRET=
+# HUBSPOT_API_KEY=
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# COOKIE_SECRET=

package/templates/base/README.md

@@ -0,0 +1,36 @@
+# <% projectName %>
+
+A ChatGPT App built with [ConversoKit](https://github.com/Xyborg/ConversoKit).
+Template: **<% template %>**
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+- MCP server → http://localhost:3000
+- Widget UI → http://localhost:5173
+
+## Structure
+
+```
+<% projectName %>/
+├── apps/
+│   ├── mcp-server/   # Express + Zod MCP tool server
+│   └── widget-ui/    # Vite + React widget host
+├── .env.example
+└── package.json
+```
+
+## Customise
+
+- Add tools under `apps/mcp-server/src/tools/`, then register them in
+  `tools/index.ts`.
+- Add or fork widgets in `apps/widget-ui/src/widgets/`.
+- See ConversoKit docs for widget authoring, integrations, and compliance.
+
+## Environment
+
+Copy `.env.example` to `.env` and fill in the keys you need.

package/templates/base/apps/mcp-server/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "<% projectName %>-mcp-server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "build": "tsc --project tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@conversokit/auth": "^0.1.0",
+    "@conversokit/integrations": "^0.1.0",
+    "@conversokit/shared": "^0.1.0",
+    "express": "^4.18.2",
+    "cors": "^2.8.5",
+    "zod": "^3.22.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.2.0"
+  }
+}

package/templates/base/apps/mcp-server/src/index.ts

@@ -0,0 +1,61 @@
+import express from 'express';
+import cors from 'cors';
+import { randomUUID } from 'node:crypto';
+import {
+  apiKeyProvider,
+  createAuthMiddleware,
+  type AuthProvider
+} from '@conversokit/auth';
+import type { Tool, ToolContext } from '@conversokit/shared';
+
+import { tools } from './tools/index.js';
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+const apiKeys = (process.env.CONVERSOKIT_API_KEYS ?? '')
+  .split(',')
+  .map((k) => k.trim())
+  .filter(Boolean);
+
+const providers: AuthProvider[] = [apiKeyProvider({ apiKeys })];
+app.use(
+  createAuthMiddleware({ providers, optional: apiKeys.length === 0 })
+);
+
+function buildContext(req: express.Request): ToolContext {
+  return {
+    sessionId: req.header('x-conversokit-session') ?? randomUUID(),
+    logger: console
+  };
+}
+
+app.get('/tools', (_req, res) => {
+  res.json({
+    tools: tools.map((t: Tool) => ({
+      name: t.name,
+      description: t.description,
+      permissions: t.permissions
+    }))
+  });
+});
+
+app.post('/tools/:name', async (req, res) => {
+  const tool = tools.find((t: Tool) => t.name === req.params.name);
+  if (!tool) return res.status(404).json({ error: 'Tool not found' });
+  try {
+    const input = tool.inputSchema.parse(req.body);
+    const output = await tool.handler(input, buildContext(req));
+    res.json(output);
+  } catch (err) {
+    res.status(400).json({
+      error: err instanceof Error ? err.message : 'Tool execution failed'
+    });
+  }
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`<% projectName %> MCP server listening on :${PORT}`);
+});

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

@@ -0,0 +1,5 @@
+import type { Tool } from '@conversokit/shared';
+
+// Add your tools here. Each tool conforms to Tool<I,O> from @conversokit/shared.
+// See https://github.com/Xyborg/ConversoKit/blob/main/docs/mcp-basics.md
+export const tools: Tool[] = [];

package/templates/base/apps/mcp-server/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "rootDir": "src",
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base/apps/widget-ui/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><% projectName %></title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/base/apps/widget-ui/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "<% projectName %>-widget-ui",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@conversokit/bridge": "^0.1.0",
+    "@conversokit/shared": "^0.1.0",
+    "@conversokit/themes": "^0.1.0",
+    "@conversokit/widgets": "^0.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.28",
+    "@types/react-dom": "^18.0.11",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.2.0",
+    "vite": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { ThemeProvider, lightTheme } from '@conversokit/themes';
+import { BridgeProvider } from '@conversokit/bridge';
+import { CTABanner } from '@conversokit/widgets';
+
+const App: React.FC = () => {
+  return (
+    <BridgeProvider baseUrl="http://localhost:3000">
+      <ThemeProvider
+        theme={lightTheme}
+        style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}
+      >
+        <h1>Welcome to <% projectName %></h1>
+        <p style={{ color: 'var(--ck-muted)' }}>
+          Built with ConversoKit. Edit <code>apps/widget-ui/src/App.tsx</code> to
+          start building.
+        </p>
+        <CTABanner
+          title="Next steps"
+          description="Add MCP tools in apps/mcp-server/src/tools and consume them via useBridge()."
+          variant="info"
+        />
+      </ThemeProvider>
+    </BridgeProvider>
+  );
+};
+
+export default App;

package/templates/base/apps/widget-ui/src/main.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App.js';
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/templates/base/apps/widget-ui/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base/apps/widget-ui/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 5173 }
+});

package/templates/base/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "<% projectName %>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "ChatGPT App scaffolded with ConversoKit (template: <% template %>)",
+  "scripts": {
+    "dev": "concurrently -k -n mcp,ui -c blue,magenta \"pnpm dev:mcp\" \"pnpm dev:ui\"",
+    "dev:mcp": "cd apps/mcp-server && pnpm dev",
+    "dev:ui": "cd apps/widget-ui && pnpm dev",
+    "build": "pnpm -r build"
+  },
+  "devDependencies": {
+    "concurrently": "^8.2.2"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
+  }
+}

package/templates/base/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "apps/*"

package/templates/booking/apps/mcp-server/src/tools/cancelReservation.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_AVAILABILITY,
+  defineTool,
+  reservationSchema
+} from '@conversokit/shared';
+
+export const cancelReservationTool = defineTool({
+  name: 'cancel_reservation',
+  description: 'Cancel an existing reservation by id.',
+  inputSchema: z.object({ reservationId: z.string() }),
+  outputSchema: z.object({ reservation: reservationSchema }),
+  permissions: { requiresAuth: false },
+  async handler(input) {
+    const slot = EXAMPLE_AVAILABILITY.slots[0];
+    return {
+      reservation: {
+        id: input.reservationId,
+        resourceId: EXAMPLE_AVAILABILITY.resourceId,
+        resourceName: EXAMPLE_AVAILABILITY.resourceName,
+        slotId: slot.id,
+        startsAt: slot.startsAt,
+        endsAt: slot.endsAt,
+        status: 'cancelled' as const
+      }
+    };
+  }
+});

package/templates/booking/apps/mcp-server/src/tools/createReservation.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_AVAILABILITY,
+  defineTool,
+  reservationSchema
+} from '@conversokit/shared';
+
+export const createReservationTool = defineTool({
+  name: 'create_reservation',
+  description: 'Reserve a time slot. Returns a synthetic Reservation in dev.',
+  inputSchema: z.object({
+    resourceId: z.string(),
+    slotId: z.string(),
+    customer: z.object({
+      name: z.string(),
+      email: z.string().email().optional()
+    })
+  }),
+  outputSchema: z.object({ reservation: reservationSchema }),
+  permissions: { requiresAuth: false, requiresConsent: true },
+  async handler(input) {
+    const slot =
+      EXAMPLE_AVAILABILITY.slots.find((s) => s.id === input.slotId) ??
+      EXAMPLE_AVAILABILITY.slots[0];
+    return {
+      reservation: {
+        id: `res_${Math.random().toString(36).slice(2)}`,
+        resourceId: input.resourceId,
+        resourceName: EXAMPLE_AVAILABILITY.resourceName,
+        slotId: slot.id,
+        startsAt: slot.startsAt,
+        endsAt: slot.endsAt,
+        status: 'confirmed' as const,
+        customer: input.customer
+      }
+    };
+  }
+});

package/templates/booking/apps/mcp-server/src/tools/getAvailability.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import {
+  EXAMPLE_AVAILABILITY,
+  availabilitySchema,
+  defineTool
+} from '@conversokit/shared';
+
+export const getAvailabilityTool = defineTool({
+  name: 'get_availability',
+  description: 'Return available time slots for a resource within a date range.',
+  inputSchema: z.object({
+    resourceId: z.string(),
+    from: z.string(),
+    to: z.string()
+  }),
+  outputSchema: z.object({ days: z.array(availabilitySchema) }),
+  permissions: { requiresAuth: false },
+  async handler() {
+    return { days: [EXAMPLE_AVAILABILITY] };
+  }
+});

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

@@ -0,0 +1,10 @@
+import type { Tool } from '@conversokit/shared';
+import { getAvailabilityTool } from './getAvailability.js';
+import { createReservationTool } from './createReservation.js';
+import { cancelReservationTool } from './cancelReservation.js';
+
+export const tools: Tool[] = [
+  getAvailabilityTool,
+  createReservationTool,
+  cancelReservationTool
+];

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

@@ -0,0 +1,79 @@
+import React, { useState } from 'react';
+import {
+  AvailabilityCalendar,
+  BookingCard,
+  CTABanner,
+  ConsentBanner,
+  TimeSlotSelector
+} from '@conversokit/widgets';
+import {
+  EXAMPLE_AVAILABILITY,
+  type Reservation,
+  type TimeSlot
+} from '@conversokit/shared';
+import { ThemeProvider, lightTheme } from '@conversokit/themes';
+import { BridgeProvider, useBridge } from '@conversokit/bridge';
+
+const Booking: React.FC = () => {
+  const bridge = useBridge();
+  const [date, setDate] = useState<string | undefined>();
+  const [slot, setSlot] = useState<TimeSlot | undefined>();
+  const [reservation, setReservation] = useState<Reservation | null>(null);
+
+  const confirm = async () => {
+    if (!slot) return;
+    const r = (await bridge.callTool('create_reservation', {
+      resourceId: EXAMPLE_AVAILABILITY.resourceId,
+      slotId: slot.id,
+      customer: { name: 'Demo User' }
+    })) as { reservation: Reservation };
+    setReservation(r.reservation);
+  };
+
+  if (reservation) {
+    return (
+      <BookingCard
+        reservation={reservation}
+        onCancel={async () => {
+          const r = (await bridge.callTool('cancel_reservation', {
+            reservationId: reservation.id
+          })) as { reservation: Reservation };
+          setReservation(r.reservation);
+        }}
+      />
+    );
+  }
+
+  return (
+    <>
+      <AvailabilityCalendar
+        availableDates={[EXAMPLE_AVAILABILITY.date]}
+        selectedDate={date}
+        onSelect={setDate}
+      />
+      {date && (
+        <TimeSlotSelector
+          slots={EXAMPLE_AVAILABILITY.slots}
+          selectedSlotId={slot?.id}
+          onSelect={setSlot}
+        />
+      )}
+      {slot && (
+        <CTABanner title="Confirm reservation" primaryLabel="Confirm" onPrimary={confirm} />
+      )}
+    </>
+  );
+};
+
+const App: React.FC = () => (
+  <BridgeProvider baseUrl="http://localhost:3000">
+    <ThemeProvider theme={lightTheme} style={{ minHeight: '100vh', padding: 'var(--ck-spacing-4)' }}>
+      <h1>Welcome to <% projectName %></h1>
+      <ConsentBanner scopes={['personalData']}>
+        <Booking />
+      </ConsentBanner>
+    </ThemeProvider>
+  </BridgeProvider>
+);
+
+export default App;

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

@@ -0,0 +1,5 @@
+import type { Tool } from '@conversokit/shared';
+import { searchProductsTool } from './searchProducts.js';
+
+// Generated commerce template. Wire your additional tools here.
+export const tools: Tool[] = [searchProductsTool];

package/templates/commerce/apps/mcp-server/src/tools/searchProducts.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import {
+  productSchema,
+  EXAMPLE_PRODUCTS,
+  defineTool
+} from '@conversokit/shared';
+
+export const searchProductsTool = defineTool({
+  name: 'search_products',
+  description: 'Free-text search over the product catalog.',
+  inputSchema: z.object({
+    query: z.string(),
+    limit: z.number().int().min(1).max(50).optional()
+  }),
+  outputSchema: z.object({ items: z.array(productSchema) }),
+  permissions: { requiresAuth: false },
+  async handler(input) {
+    const { query, limit = 10 } = input;
+    const lower = query.toLowerCase();
+    const matches = lower
+      ? EXAMPLE_PRODUCTS.filter(
+          (p) =>
+            p.title.toLowerCase().includes(lower) ||
+            (p.subtitle && p.subtitle.toLowerCase().includes(lower))
+        )
+      : EXAMPLE_PRODUCTS;
+    return { items: matches.slice(0, limit) };
+  }
+});