@strand-js/openai 0.1.3 → 0.1.5

package/README.md

@@ -34,7 +34,53 @@ export const POST = createStrandRoute({
 })
 ```
 
-### Switching from Anthropic
+## Production security checklist
+
+Before going live, configure these options:
+
+```ts
+createStrandHandler({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o',
+
+  // 1. REQUIRED: authenticate every request
+  // Without this, anyone can hit your endpoint and burn your API credits.
+  authorize: async (request) => {
+    const token = request.headers.get('authorization')?.replace('Bearer ', '')
+    const user = await verifyToken(token)
+    if (!user) throw new Error('Unauthorized') // returns 401, no LLM call is made
+  },
+
+  // 2. RECOMMENDED: built-in rate limiting by IP
+  rateLimit: {
+    windowMs: 60_000,   // 1 minute window
+    maxRequests: 20,    // max 20 requests per IP per minute
+  },
+
+  // 3. RECOMMENDED: limit message size
+  maxMessages: 50,
+  maxMessageLength: 10_000,
+})
+```
+
+**Also configure on your server (outside Strand):**
+- **CORS** — restrict which origins can call your endpoint
+- **HTTPS** — never run in production over HTTP
+
+## What `authorize` is
+
+`authorize` runs before any LLM call. If it throws, the request is rejected with a 401 and no API credits are used.
+
+```ts
+// JWT example
+authorize: async (request) => {
+  const token = request.headers.get('authorization')?.replace('Bearer ', '')
+  const user = await verifyJWT(token)
+  if (!user) throw new Error('Unauthorized')
+}
+```
+
+## Switching providers
 
 Only the server changes — the React hooks are identical:
 
@@ -50,4 +96,19 @@ Only the server changes — the React hooks are identical:
   })
 ```
 
+## Config reference
+
+| Option | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Your OpenAI API key |
+| `model` | `string` | Model ID, e.g. `'gpt-4o'` |
+| `system` | `string \| (req) => string` | System prompt |
+| `tools` | `ToolDefinition[]` | Tools available to the model |
+| `onToolCall` | `async (name, args, ctx) => result` | Server-side tool execution |
+| `authorize` | `async (req) => void` | Throw to reject with 401 |
+| `rateLimit` | `{ windowMs, maxRequests }` | Built-in IP rate limiting |
+| `maxMessages` | `number` | Max messages per request (default: 100) |
+| `maxMessageLength` | `number` | Max chars per message (default: 50,000) |
+| `maxSteps` | `number` | Max tool call rounds (default: 10) |
+
 [Full documentation →](https://github.com/strand-js/strand)

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ToolDefinition, Session } from '@strand-js/core';
+import { ToolDefinition, RateLimitConfig, Session } from '@strand-js/core';
 
 interface StrandHandlerConfig {
     apiKey: string;
@@ -9,6 +9,7 @@ interface StrandHandlerConfig {
         request: Request;
     }) => Promise<unknown>;
     authorize?: (request: Request) => Promise<unknown> | unknown;
+    rateLimit?: RateLimitConfig;
     maxMessages?: number;
     maxMessageLength?: number;
     maxSteps?: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ToolDefinition, Session } from '@strand-js/core';
+import { ToolDefinition, RateLimitConfig, Session } from '@strand-js/core';
 
 interface StrandHandlerConfig {
     apiKey: string;
@@ -9,6 +9,7 @@ interface StrandHandlerConfig {
         request: Request;
     }) => Promise<unknown>;
     authorize?: (request: Request) => Promise<unknown> | unknown;
+    rateLimit?: RateLimitConfig;
     maxMessages?: number;
     maxMessageLength?: number;
     maxSteps?: number;

package/dist/index.js

@@ -64,8 +64,17 @@ function createStrandHandler(config) {
   const client = new import_openai.default({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new import_core2.RateLimiter(config.rateLimit) : null;
   return async (req, res) => {
     const body = req.body;
+    if (rateLimiter) {
+      const ip = req.ip ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        res.status(429).json({ error: "Too many requests", retryAfter: limited.retryAfter });
+        return;
+      }
+    }
     const validation = (0, import_core2.validateMessages)(body?.messages, {
       maxMessages: config.maxMessages,
       maxMessageLength: config.maxMessageLength
@@ -192,7 +201,18 @@ function createStrandRoute(config) {
   const client = new import_openai2.default({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new import_core3.RateLimiter(config.rateLimit) : null;
   return async (req) => {
+    if (rateLimiter) {
+      const ip = req.headers.get("x-forwarded-for") ?? req.headers.get("x-real-ip") ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        return new Response(JSON.stringify({ error: "Too many requests", retryAfter: limited.retryAfter }), {
+          status: 429,
+          headers: { "Content-Type": "application/json", "Retry-After": String(limited.retryAfter) }
+        });
+      }
+    }
     const body = await req.json();
     const validation = (0, import_core3.validateMessages)(body?.messages, {
       maxMessages: config.maxMessages,

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/handler.ts
 import OpenAI from "openai";
-import { generateId, validateMessages } from "@strand-js/core";
+import { generateId, validateMessages, RateLimiter } from "@strand-js/core";
 
 // src/format.ts
 import { toolToJsonSchema } from "@strand-js/core";
@@ -27,8 +27,17 @@ function createStrandHandler(config) {
   const client = new OpenAI({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new RateLimiter(config.rateLimit) : null;
   return async (req, res) => {
     const body = req.body;
+    if (rateLimiter) {
+      const ip = req.ip ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        res.status(429).json({ error: "Too many requests", retryAfter: limited.retryAfter });
+        return;
+      }
+    }
     const validation = validateMessages(body?.messages, {
       maxMessages: config.maxMessages,
       maxMessageLength: config.maxMessageLength
@@ -144,7 +153,7 @@ function createStrandHandler(config) {
 
 // src/route.ts
 import OpenAI2 from "openai";
-import { generateId as generateId2, validateMessages as validateMessages2 } from "@strand-js/core";
+import { generateId as generateId2, validateMessages as validateMessages2, RateLimiter as RateLimiter2 } from "@strand-js/core";
 function sseChunk(eventType, data) {
   return new TextEncoder().encode(`event: ${eventType}
 data: ${JSON.stringify(data)}
@@ -155,7 +164,18 @@ function createStrandRoute(config) {
   const client = new OpenAI2({ apiKey: config.apiKey });
   const openAITools = (config.tools ?? []).map(toolToOpenAITool);
   const maxSteps = config.maxSteps ?? 10;
+  const rateLimiter = config.rateLimit ? new RateLimiter2(config.rateLimit) : null;
   return async (req) => {
+    if (rateLimiter) {
+      const ip = req.headers.get("x-forwarded-for") ?? req.headers.get("x-real-ip") ?? "unknown";
+      const limited = rateLimiter.check(ip);
+      if (limited) {
+        return new Response(JSON.stringify({ error: "Too many requests", retryAfter: limited.retryAfter }), {
+          status: 429,
+          headers: { "Content-Type": "application/json", "Retry-After": String(limited.retryAfter) }
+        });
+      }
+    }
     const body = await req.json();
     const validation = validateMessages2(body?.messages, {
       maxMessages: config.maxMessages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strand-js/openai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "MIT",
   "description": "OpenAI provider adapter for Strand",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "openai": "^4.77.0",
-    "@strand-js/core": "0.1.3"
+    "@strand-js/core": "0.1.5"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",