@chatcops/server 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CoderCops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @chatcops/server
+
+Server-side handler and platform adapters for ChatCops. Handles streaming responses, rate limiting, webhooks, and analytics.
+
+## Install
+
+```bash
+npm install @chatcops/server @chatcops/core
+```
+
+## Quick Start
+
+### Express
+
+```typescript
+import express from 'express';
+import { chatcopsMiddleware } from '@chatcops/server';
+
+const app = express();
+app.use(express.json());
+
+app.post('/chat', chatcopsMiddleware({
+  provider: {
+    type: 'claude',
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  },
+  systemPrompt: 'You are a helpful assistant for our website.',
+  cors: '*',
+}));
+
+app.listen(3001);
+```
+
+### Vercel Edge
+
+```typescript
+import { chatcopsVercelHandler } from '@chatcops/server';
+
+const handler = chatcopsVercelHandler({
+  provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
+  systemPrompt: 'You are a helpful assistant.',
+  cors: '*',
+});
+
+export const POST = (req: Request) => handler(req);
+export const OPTIONS = (req: Request) => handler(req);
+export const config = { runtime: 'edge' };
+```
+
+### Cloudflare Workers
+
+```typescript
+import { chatcopsCloudflareHandler } from '@chatcops/server';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const handler = chatcopsCloudflareHandler({
+      provider: { type: 'claude', apiKey: env.ANTHROPIC_API_KEY },
+      systemPrompt: 'You are a helpful assistant.',
+      cors: '*',
+    });
+    return handler(request);
+  },
+};
+```
+
+## Configuration
+
+```typescript
+import { createChatHandler } from '@chatcops/server';
+import { LeadCaptureTool, FAQKnowledgeSource } from '@chatcops/core';
+
+const handler = createChatHandler({
+  // AI provider (required)
+  provider: {
+    type: 'claude',          // 'claude' | 'openai' | 'gemini'
+    apiKey: 'sk-...',
+    model: 'claude-haiku-4-5-20251001',
+  },
+
+  // System prompt (required)
+  systemPrompt: 'You are a helpful support assistant.',
+
+  // Tools (optional)
+  tools: [
+    new LeadCaptureTool((lead) => {
+      console.log('New lead:', lead.email);
+    }),
+  ],
+
+  // Knowledge base (optional)
+  knowledge: [
+    new FAQKnowledgeSource([
+      { question: 'What do you do?', answer: 'We build software.' },
+    ]),
+  ],
+
+  // Rate limiting (optional, default: 30 req/60s)
+  rateLimit: { maxRequests: 10, windowMs: 60_000 },
+
+  // Webhooks (optional)
+  webhooks: [
+    { url: 'https://hooks.example.com/leads', events: ['lead:captured'] },
+  ],
+
+  // Analytics (optional)
+  analytics: true,
+
+  // CORS origin (required)
+  cors: '*',
+});
+```
+
+## SSE Stream Format
+
+All adapters produce identical Server-Sent Events:
+
+```
+data: {"content":"Hello"}
+data: {"content":" there!"}
+data: {"done":true}
+data: [DONE]
+```
+
+On error:
+
+```
+data: {"error":"rate_limit","retryAfter":42}
+data: [DONE]
+```
+
+Error codes: `invalid_request`, `rate_limit`, `provider_error`, `internal_error`.
+
+## Rate Limiting
+
+In-memory, per-IP. Suitable for single-instance deployments.
+
+```typescript
+import { RateLimiter } from '@chatcops/server';
+
+const limiter = new RateLimiter({ maxRequests: 30, windowMs: 60_000 });
+const result = limiter.check('127.0.0.1');
+// { allowed: true } or { allowed: false, retryAfter: 42 }
+```
+
+## Webhooks
+
+HMAC-SHA256 signed, with exponential backoff retries (up to 3 attempts).
+
+```typescript
+import { WebhookDispatcher } from '@chatcops/server';
+
+const dispatcher = new WebhookDispatcher([
+  { url: 'https://hooks.example.com/chat', events: ['*'], secret: 'my-secret' },
+]);
+
+await dispatcher.dispatch('lead:captured', { email: 'user@example.com' });
+```
+
+Signature sent via `X-ChatCops-Signature` header.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatcops/server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Server-side handler and adapters for ChatCops",
   "type": "module",
   "main": "dist/index.js",
@@ -26,16 +26,9 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist *.tsbuildinfo"
-  },
   "dependencies": {
-    "@chatcops/core": "workspace:*",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@chatcops/core": "0.2.1"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"
@@ -50,8 +43,20 @@
     "vitest": "^3.0.0",
     "@types/express": "^5.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codercops/chatcops",
+    "directory": "packages/server"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}