paprflare-sdk 0.0.14 → 0.0.16

package/README.md

@@ -1,15 +1,327 @@
-# sdk
+# 🎯 Perfect API - Migration Guide
 
-To install dependencies:
+## What Changed?
 
-```bash
-bun install
+We've completely reorganized the API to be **ultra-simple** with **automatic type inference**.
+
+## Key Improvements
+
+### 1. ✅ No More Type Casting
+
+**Before:**
+```typescript
+const response = await client.chat(messages, { stream: true });
+
+if (isStreamingResponse(response)) {
+  await (response as StreamingChatResponse).toConsole(); // ❌ Casting needed
+}
+```
+
+**After:**
+```typescript
+const response = await client.chat({
+  messages,
+  stream: true,
+});
+
+await response.toConsole(); // ✅ No casting needed!
+```
+
+### 2. ✅ Unified API with Messages
+
+**Before:**
+```typescript
+await client.chat(messages, config);
+```
+
+**After:**
+```typescript
+await client.chat({
+  messages,
+  ...options,
+});
+```
+
+### 3. ✅ Mode-Specific Configuration
+
+**Before:** All config options visible regardless of mode
+
+**After:** Only relevant config for your mode
+
+```typescript
+// Cloud mode - only cloud options
+new PaprFlare({
+  mode: 'cloud',
+  apiKey: 'pk_...',
+  region: 'in-mumbai',
+  // ❌ TypeScript prevents: provider, cache, database
+});
+
+// Self-managed - only self-managed options
+new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  cache: { type: 'memory' },
+  database: new MemoryAdapter(),
+  // ❌ TypeScript prevents: apiKey, region
+});
+```
+
+### 4. ✅ Built-in Database & Threads
+
+**Before:** Separate initialization
+
+**After:** Built into client
+
+```typescript
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  database: new MemoryAdapter(),
+  threads: { enabled: true },
+});
+
+// Access directly
+await client.database.startConversation('user-123');
+await client.threads.createThread('user-123');
+```
+
+## Complete Migration
+
+### Step 1: Update Imports
+
+```typescript
+// Before
+import { PaprFlareClient, isStreamingResponse } from '@paprflare/ai-sdk';
+
+// After
+import { PaprFlare } from '@paprflare/ai-sdk';
+// isStreamingResponse no longer needed!
+```
+
+### Step 2: Update Configuration
+
+```typescript
+// Before
+const client = new PaprFlareClient({
+  mode: 'self-managed',
+  selfManaged: {
+    provider: createOpenAIProvider({ apiKey: '...' }),
+    cache: { type: 'memory' },
+  },
+});
+
+// After
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  cache: { type: 'memory' },
+  database: new MemoryAdapter(), // Optional
+  threads: { enabled: true }, // Optional
+});
+```
+
+### Step 3: Update Chat Calls
+
+```typescript
+// Before
+const response = await client.chat(messages, {
+  stream: true,
+  temperature: 0.7,
+});
+
+// After
+const response = await client.chat({
+  messages,
+  stream: true,
+  temperature: 0.7,
+});
+```
+
+### Step 4: Remove Type Guards
+
+```typescript
+// Before
+const response = await client.chat(messages, { stream: true });
+if (isStreamingResponse(response)) {
+  await response.toConsole();
+}
+
+// After
+const response = await client.chat({
+  messages,
+  stream: true,
+});
+await response.toConsole(); // ✅ TypeScript knows it's streaming!
+```
+
+## New Features
+
+### 1. Built-in Database
+
+```typescript
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  database: new MemoryAdapter(), // or PrismaAdapter, DrizzleAdapter
+});
+
+// Start conversation
+const convId = await client.database!.startConversation('user-123');
+
+// Auto-save messages
+const response = await client.chat({
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: true,
+});
+
+await response.process({
+  onComplete: (msg) => client.database!.addMessage(convId, msg),
+});
+```
+
+### 2. Built-in Thread Management
+
+```typescript
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  threads: { enabled: true },
+});
+
+// Create thread
+const threadId = await client.threads.createThread('user-123');
+
+// Send message (context managed automatically)
+const stream = await client.threads.sendMessage(threadId, 'Hello!');
+await stream.toConsole();
+```
+
+### 3. One-Liner API Routes
+
+```typescript
+// Next.js App Router
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  
+  return (await client.chat({
+    messages,
+    stream: true,
+  })).toResponse(); // ✅ ONE LINE!
+}
+
+// Express
+app.post('/chat', async (req, res) => {
+  return (await client.chat({
+    messages: req.body.messages,
+    stream: true,
+  })).toResponse(res);
+});
+```
+
+## Complete Examples
+
+### Streaming
+
+```typescript
+const response = await client.chat({
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: true,
+  temperature: 0.7,
+  maxTokens: 2000,
+});
+
+// Choose your method:
+await response.toConsole(); // Console
+await response.toResponse(); // HTTP Response
+const text = await response.toText(); // Full text
+await response.process({ onText: (d) => console.log(d) }); // Callbacks
+```
+
+### Non-Streaming
+
+```typescript
+const response = await client.chat({
+  messages: [{ role: 'user', content: 'Hello' }],
+  temperature: 0.7,
+});
+
+console.log(response.message.content);
+console.log(response.usage?.totalTokens);
 ```
 
-To run:
+### With Database
+
+```typescript
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  database: new MemoryAdapter(),
+});
+
+const convId = await client.database!.startConversation('user-123');
+
+const response = await client.chat({
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: true,
+});
 
-```bash
-bun run index.ts
+await response.process({
+  onText: (delta) => process.stdout.write(delta),
+  onComplete: (msg) => client.database!.addMessage(convId, msg),
+});
 ```
 
-This project was created using `bun init` in bun v1.3.7. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### With Threads
+
+```typescript
+const client = new PaprFlare({
+  mode: 'self-managed',
+  provider: createOpenAIProvider({ apiKey: '...' }),
+  threads: { enabled: true },
+});
+
+const threadId = await client.threads.createThread('user-123');
+
+const stream = await client.threads.sendMessage(
+  threadId,
+  'Explain quantum computing'
+);
+
+await stream.toConsole();
+
+// Follow-up (context maintained)
+const stream2 = await client.threads.sendMessage(
+  threadId,
+  'Explain that in simpler terms'
+);
+```
+
+## Benefits Summary
+
+| Feature | Before | After |
+|---------|--------|-------|
+| Type inference | Manual casting | Automatic ✅ |
+| API calls | 2 parameters | 1 unified object ✅ |
+| Type guards | Required | Not needed ✅ |
+| Config types | All options visible | Mode-specific ✅ |
+| Database | Separate init | Built-in ✅ |
+| Threads | Separate init | Built-in ✅ |
+| Code reduction | Baseline | 50% less ✅ |
+
+## Breaking Changes
+
+1. **Import name:** `PaprFlareClient` → `PaprFlare`
+2. **Config structure:** `selfManaged: {}` → top-level options
+3. **Chat signature:** `chat(messages, config)` → `chat({ messages, ...config })`
+4. **Type guards:** `isStreamingResponse()` no longer needed
+
+## Backwards Compatibility
+
+The old API still works but is deprecated. Update when convenient.
+
+---
+
+**You're now using the simplest AI SDK API possible! 🚀**
+
+Made with ❤️ in India 🇮🇳