@convokit/server 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @convokit/server
+
+> **ConvoKit is currently in early access.** The waitlist is live — [join at convokit.dev](https://convokit.dev) to get early access.
+
+Server SDK for [ConvoKit](https://convokit.dev) — send AI chat messages from your server using your **secret API key**. The key never leaves your backend, making this more secure than using a public key in the browser.
+
+**Website:** [convokit.dev](https://convokit.dev)
+
+---
+
+## Installation
+
+```bash
+npm install @convokit/server
+```
+
+---
+
+## Usage
+
+```js
+const { createClient } = require('@convokit/server');
+
+const client = createClient(process.env.CONVOKIT_SECRET_KEY); // sk_live_...
+
+// New conversation
+const { reply, conversation_id } = await client.chat({
+  message: 'What are your support hours?',
+});
+console.log(reply);
+
+// Follow-up in the same thread
+const { reply: reply2 } = await client.chat({
+  message: 'And on weekends?',
+  conversationId: conversation_id,
+});
+console.log(reply2);
+```
+
+---
+
+## TypeScript
+
+```ts
+import { createClient, type ChatOptions, type ChatResponse } from '@convokit/server';
+
+const client = createClient({ apiKey: process.env.CONVOKIT_SECRET_KEY! });
+
+const res: ChatResponse = await client.chat({
+  message: 'Hello',
+  widgetId: 'my-bot',
+  chatHistory: [],
+});
+```
+
+---
+
+## Conversation history
+
+Pass previous messages so the AI has context:
+
+```js
+const { reply } = await client.chat({
+  message: 'What did I just ask?',
+  chatHistory: [
+    { role: 'user', content: 'What are your support hours?' },
+    { role: 'assistant', content: 'We are open 9am–5pm Monday to Friday.' },
+  ],
+});
+```
+
+Format: `{ role: 'user' | 'assistant' | 'system', content: string }`.
+
+When you have a `conversationId`, you can omit `chatHistory` — the backend already has the thread.
+
+---
+
+## Options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `message` | Yes | The user message to send |
+| `conversationId` | No | Use for follow-up messages in the same thread |
+| `widgetId` | No | Identifier for grouping (e.g. bot name, channel) |
+| `chatHistory` | No | Previous messages for context |
+
+## Response
+
+| Field | Description |
+|-------|-------------|
+| `reply` | AI reply text |
+| `conversation_id` | Pass this in the next message to continue the thread |
+| `usage` | Token usage — `prompt_tokens`, `completion_tokens`, `total_tokens` |
+
+---
+
+## Security
+
+- Use a **secret key** (`sk_live_...`) on your server only. Never expose it in browser or client-side code.
+- For browser / widget use, use a **public key** (`pk_live_...`) with the [`@convokit/widget`](https://www.npmjs.com/package/@convokit/widget) package.
+
+---
+
+## Early access
+
+ConvoKit is in early access. Get your API keys and configure your AI at **[convokit.dev](https://convokit.dev)**.
+
+The waitlist is live — join now to get early access.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ConvoKit Server SDK
+ * Use your secret API key (sk_live_...) for secure server-to-server chat.
+ * Never expose the secret key in the browser — use the widget with a public key instead.
+ */
+/** ConvoKit API URL. */
+export declare const DEFAULT_API_URL = "https://api.convokit.com";
+/**
+ * One message in the conversation history.
+ * Format: { role: 'user' | 'assistant' | 'system', content: string }
+ * Example: user: "What are your hours?", assistant: "We're open 9–5."
+ */
+export interface ChatHistoryItem {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+export interface ChatOptions {
+    /** User message to send */
+    message: string;
+    /** Existing conversation ID for follow-up messages; omit for a new conversation */
+    conversationId?: string;
+    /** Optional widget/session identifier for grouping */
+    widgetId?: string;
+    /**
+     * Previous messages in the thread (for context).
+     * Format: array of { role: 'user' | 'assistant' | 'system', content: string }
+     * Example: [ { role: 'user', content: 'Hi' }, { role: 'assistant', content: 'Hello!' } ]
+     */
+    chatHistory?: ChatHistoryItem[];
+}
+export interface ChatResponse {
+    /** AI reply text */
+    reply: string;
+    /** Conversation ID (use for follow-up messages) */
+    conversation_id: string;
+    /** Token usage from the model */
+    usage: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+}
+export interface ConvoKitServerConfig {
+    /** Secret API key (sk_live_...). Never use in the browser. */
+    apiKey: string;
+}
+/**
+ * ConvoKit Server client for server-to-server chat.
+ * Authenticate with your secret key; the key never leaves your server.
+ */
+export declare class ConvoKitServerClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(config: ConvoKitServerConfig | string);
+    /**
+     * Send a message and get an AI reply.
+     * Use conversationId for follow-up messages in the same thread.
+     */
+    chat(options: ChatOptions): Promise<ChatResponse>;
+}
+/**
+ * Create a ConvoKit server client. Uses the ConvoKit API at https://api.convokit.com.
+ * @param apiKey - Secret API key (sk_live_...) — or pass { apiKey }
+ */
+export declare function createClient(apiKey: string): ConvoKitServerClient;
+export declare function createClient(config: ConvoKitServerConfig): ConvoKitServerClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAwB;AACxB,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,KAAK,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,oBAAoB,GAAG,MAAM;IAajD;;;OAGG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAwCxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAAC;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * ConvoKit Server SDK
+ * Use your secret API key (sk_live_...) for secure server-to-server chat.
+ * Never expose the secret key in the browser — use the widget with a public key instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConvoKitServerClient = exports.DEFAULT_API_URL = void 0;
+exports.createClient = createClient;
+/** ConvoKit API URL. */
+exports.DEFAULT_API_URL = 'https://api.convokit.com';
+/**
+ * ConvoKit Server client for server-to-server chat.
+ * Authenticate with your secret key; the key never leaves your server.
+ */
+class ConvoKitServerClient {
+    constructor(config) {
+        if (typeof config === 'string') {
+            this.apiKey = config;
+            this.baseUrl = exports.DEFAULT_API_URL;
+        }
+        else {
+            this.apiKey = config.apiKey;
+            this.baseUrl = exports.DEFAULT_API_URL;
+        }
+        if (!this.apiKey) {
+            throw new Error('ConvoKit server client requires an API key (sk_live_...)');
+        }
+    }
+    /**
+     * Send a message and get an AI reply.
+     * Use conversationId for follow-up messages in the same thread.
+     */
+    async chat(options) {
+        const { message, conversationId, widgetId, chatHistory = [] } = options;
+        const url = `${this.baseUrl}/api/server/chat`;
+        const body = {
+            message,
+            chat_history: chatHistory,
+        };
+        if (conversationId)
+            body.conversation_id = conversationId;
+        if (widgetId)
+            body.widget_id = widgetId;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = {};
+        }
+        if (!res.ok) {
+            const err = data?.error ?? res.statusText ?? 'Request failed';
+            throw new Error(typeof err === 'string' ? err : JSON.stringify(err));
+        }
+        const out = data;
+        if (out == null || typeof out.reply !== 'string') {
+            throw new Error('Invalid response format from ConvoKit API');
+        }
+        return {
+            reply: out.reply,
+            conversation_id: String(out.conversation_id ?? ''),
+            usage: out.usage,
+        };
+    }
+}
+exports.ConvoKitServerClient = ConvoKitServerClient;
+function createClient(configOrApiKey) {
+    if (typeof configOrApiKey === 'string') {
+        return new ConvoKitServerClient(configOrApiKey);
+    }
+    return new ConvoKitServerClient(configOrApiKey);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAyHH,oCAKC;AA5HD,wBAAwB;AACX,QAAA,eAAe,GAAG,0BAA0B,CAAC;AA6C1D;;;GAGG;AACH,MAAa,oBAAoB;IAI/B,YAAY,MAAqC;QAC/C,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,uBAAe,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC5B,IAAI,CAAC,OAAO,GAAG,uBAAe,CAAC;QACjC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC7B,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;QACxE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,kBAAkB,CAAC;QAC9C,MAAM,IAAI,GAA4B;YACpC,OAAO;YACP,YAAY,EAAE,WAAW;SAC1B,CAAC;QACF,IAAI,cAAc;YAAE,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QAC1D,IAAI,QAAQ;YAAE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAExC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,GAAG,GAAI,IAAgC,EAAE,KAAK,IAAI,GAAG,CAAC,UAAU,IAAI,gBAAgB,CAAC;YAC3F,MAAM,IAAI,KAAK,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO;YACL,KAAK,EAAE,GAAG,CAAC,KAAe;YAC1B,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC;YAClD,KAAK,EAAE,GAAG,CAAC,KAA8B;SAC1C,CAAC;IACJ,CAAC;CACF;AA7DD,oDA6DC;AAQD,SAAgB,YAAY,CAAC,cAA6C;IACxE,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,IAAI,oBAAoB,CAAC,cAAc,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,IAAI,oBAAoB,CAAC,cAAc,CAAC,CAAC;AAClD,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@convokit/server",
+  "version": "0.1.0",
+  "description": "ConvoKit server SDK — secure server-to-server chat using your secret API key",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "convokit",
+    "chat",
+    "ai",
+    "server",
+    "sdk",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}