teckel-ai 0.3.3 → 0.3.5

package/README.md

@@ -1,25 +1,6 @@
 # teckel-ai
 
-TypeScript/JavaScript SDK for [Teckel AI](https://teckel.ai) - Monitor and improve your AI chatbot's accuracy and completeness.
-
-## What is Teckel AI?
-
-Teckel AI helps you understand and improve your AI chatbots by analyzing conversations. Track what questions users ask, how well your AI answers them, and identify which areas need improvement.
-
-**Your Problem:** Your RAG or AI chat system gives incomplete or incorrect answers because your knowledge base has gaps.
-
-**Our Service:** We analyze every AI response for accuracy and completeness, cluster similar queries to identify trending topics, and tell you exactly which documentation to add or update.
-
-## What This SDK Does
-
-This lightweight SDK (zero dependencies, 20-minute integration) sends your AI conversations to Teckel for analysis:
-
-- **Completeness Scoring** - How well each response answers the question (0-100%)
-- **Accuracy Analysis** - Whether AI claims are supported by your source documents
-- **Topic Intelligence** - Automatic clustering of queries to reveal documentation gaps
-- **Actionable Feedback** - Specific recommendations on what knowledge to add
-
-Works with any RAG system or AI framework: LangChain, LlamaIndex, Vercel AI SDK, or custom implementations.
+TypeScript/JavaScript SDK for [Teckel AI](https://teckel.ai)- Get insight into your AI systems, track topics of your choosing, and identify and fix knowledge gaps.
 
 ## Installation
 
@@ -27,9 +8,7 @@ Works with any RAG system or AI framework: LangChain, LlamaIndex, Vercel AI SDK,
 npm install teckel-ai
 ```
 
-**Requirements:**
-- Node.js 18+ (or Bun, Deno, serverless runtimes)
-- TypeScript 4.5+ (optional but recommended)
+**Requirements:** Node.js 18+ (or Bun, Deno, serverless runtimes)
 
 ## Quick Start
 
@@ -43,388 +22,40 @@ const tracer = new TeckelTracer({
 
 // In your API handler
 async function handleChat(userQuestion: string, sessionId: string) {
-  // Start conversation
-  const conversation = tracer.start({
-    sessionRef: sessionId,
-    userId: 'user@example.com'
-  });
+  const conversation = tracer.start({ sessionRef: sessionId });
 
   // Your existing RAG logic
   const chunks = await vectorDB.search(userQuestion);
   const answer = await llm.generate(userQuestion, chunks);
 
-  // Map chunks to Teckel format
-  const documents = chunks.map((chunk, index) => ({
-    documentRef: chunk.id,
-    documentName: chunk.title,
-    documentText: chunk.content,
-    documentLastUpdated: chunk.lastModified,
-    sourceUri: chunk.url,
-    similarity: chunk.score,
-    rank: index
-  }));
-
   // Send trace (non-blocking)
   conversation.trace({
     query: userQuestion,
     response: answer,
-    documents: documents,
-    model: 'gpt-5',
-    responseTimeMs: 1200
+    documents: chunks.map((chunk, i) => ({
+      documentRef: chunk.id,
+      documentName: chunk.title,
+      documentText: chunk.content,
+    }))
   });
 
   // For serverless: flush before returning
-  await conversation.flush(5000);
+  await conversation.flush();
 
   return answer;
 }
 ```
 
-## API Reference
-
-### TeckelTracer
-
-Main SDK class.
-
-#### Constructor
-
-```typescript
-new TeckelTracer(config: TeckelConfig)
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `apiKey` | string | Yes | - | Your Teckel API key (starts with `tk_live_`) |
-| `endpoint` | string | No | `"https://app.teckel.ai/api"` | API base URL |
-| `debug` | boolean | No | `false` | Enable debug logging |
-| `timeoutMs` | number | No | `5000` | Network timeout in milliseconds |
-
-#### tracer.start()
-
-Start or continue a conversation.
-
-```typescript
-tracer.start(options: ConversationOptions): Conversation
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `sessionRef` | string | Yes | Your unique conversation identifier |
-| `userId` | string | No | End-user identifier |
-| `metadata` | object | No | Custom context |
-
-### Conversation
-
-#### conversation.trace()
-
-Record a query-response interaction. Fire-and-forget by default.
-
-```typescript
-conversation.trace(data: TraceData): TraceResult
-```
-
-**Returns:** `{ traceRef: string, turnNumber: number }`
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `query` | string | Yes | User's question |
-| `response` | string | Yes | AI-generated answer |
-| `documents` | Document[] | Recommended | Retrieved chunks (for RAG) |
-| `traceRef` | string | No | Your correlation ID |
-| `model` | string | No | LLM model (e.g., "gpt-5") |
-| `responseTimeMs` | number | No | Latency in milliseconds |
-| `tokens` | TokenUsage | No | Token usage |
-| `metadata` | object | No | Custom context |
-
-**Example:**
-
-```typescript
-const result = conversation.trace({
-  query: "How do I reset my password?",
-  response: "Go to Settings > Security...",
-  model: "gpt-5",
-  documents: [
-    {
-      documentRef: "kb-123",
-      documentName: "Password Reset Guide",
-      documentText: "To reset your password...",
-      documentLastUpdated: "2025-01-15T10:00:00Z",
-      sourceUri: "https://kb.example.com/security",
-      similarity: 0.92,
-      rank: 0
-    }
-  ]
-});
-
-console.log(result.traceRef); // "session-123:1"
-```
-
-#### conversation.feedback()
-
-Add user feedback signal.
-
-```typescript
-await conversation.feedback(data: FeedbackData): Promise<void>
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | FeedbackType | Yes | `"thumbs_up"`, `"thumbs_down"`, `"flag"`, or `"rating"` |
-| `value` | string | No | For ratings: `"1"` to `"5"` |
-| `comment` | string | No | User's explanation |
-| `traceRef` | string | No | Link to specific trace |
-
-**Example:**
-
-```typescript
-await conversation.feedback({
-  type: "thumbs_down",
-  comment: "Information was outdated"
-});
-```
-
-#### conversation.flush()
-
-Wait for queued traces to send. **Required for serverless** to prevent data loss.
-
-```typescript
-await conversation.flush(timeoutMs?: number): Promise<void>
-```
-
-**Throws:** Error on timeout
-
-**Example:**
-
-```typescript
-// Serverless: flush before returning
-try {
-  await conversation.flush(5000);
-} catch (err) {
-  logger.warn('Flush timeout', { err });
-}
-```
-
-#### conversation.end()
-
-End conversation and flush pending traces.
-
-```typescript
-await conversation.end(): Promise<void>
-```
-
-#### Read-only Properties
-
-```typescript
-conversation.id          // session reference
-conversation.turns       // number of traces
-conversation.started     // start time
-```
-
-## Type Definitions
-
-### Document
-
-```typescript
-interface Document {
-  // Required
-  documentRef: string;        // Your document ID
-  documentName: string;       // Human-readable name
-  documentText: string;       // Chunk content
-
-  // Recommended
-  documentLastUpdated?: string;   // ISO 8601 timestamp
-  sourceUri?: string;             // URL or path
-
-  // Optional
-  sourceType?: string;        // e.g., 'confluence', 'slack'
-  similarity?: number;        // 0-1 score
-  rank?: number;              // Position (0 = first)
-  ownerEmail?: string;        // Owner email
-  documentType?: string;      // e.g., 'pdf', 'markdown'
-}
-```
-
-### TokenUsage
-
-```typescript
-interface TokenUsage {
-  prompt: number;       // Input tokens
-  completion: number;   // Output tokens
-  total: number;        // Total tokens
-}
-```
-
-### FeedbackType
-
-```typescript
-type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating'
-```
-
-## Usage Patterns
-
-### Serverless (Vercel, Lambda, Cloudflare Workers)
-
-**Must** call `flush()` before returning to prevent data loss.
-
-```typescript
-const tracer = new TeckelTracer({
-  apiKey: process.env.TECKEL_API_KEY
-});
-
-export async function handler(request) {
-  const conversation = tracer.start({
-    sessionRef: request.sessionId
-  });
-
-  const answer = await generateAnswer(request.question);
-
-  conversation.trace({
-    query: request.question,
-    response: answer,
-    documents: retrievedDocs
-  });
-
-  // CRITICAL: Flush before returning (3-5s recommended)
-  await conversation.flush(5000);
-
-  return { statusCode: 200, body: answer };
-}
-```
-
-### Long-Running Servers (Express, Fastify, etc.)
-
-No `flush()` needed - traces send in background.
-
-```typescript
-const tracer = new TeckelTracer({
-  apiKey: process.env.TECKEL_API_KEY
-});
-
-app.post('/chat', async (req, res) => {
-  const conversation = tracer.start({
-    sessionRef: req.session.id
-  });
-
-  const answer = await generateAnswer(req.body.question);
-
-  conversation.trace({
-    query: req.body.question,
-    response: answer,
-    documents: retrievedDocs
-  });
-
-  // No flush needed
-  res.json({ answer });
-});
-```
-
-### Non-RAG Systems
-
-Omit `documents` if not using retrieval.
-
-```typescript
-conversation.trace({
-  query: userQuestion,
-  response: answer,
-  model: 'gpt-5'
-});
-```
-
-## SDK Behavior
-
-### Error Handling
-
-- `trace()`, `feedback()`, `end()` **never throw** - failures logged in debug mode
-- `flush()` **throws on timeout** - catch to monitor potential data loss
-
-### Retry Logic
-
-Automatically retries once on transient errors:
-- HTTP 429 (rate limit)
-- HTTP 5xx (server errors)
-- Network failures
-
-**Retry pattern:**
-1. Initial attempt
-2. Wait 250-350ms (jittered)
-3. Single retry
-4. Log failure (debug mode)
-
-**Total time:** `2 * timeoutMs + ~300ms`
-
-### Timeouts and Flush
-
-- `timeoutMs`: Per-request network timeout for SDK HTTP calls. If a request exceeds this, it is aborted. With one retry, total worst-case send time is approximately `2 * timeoutMs + ~300ms`.
-- `flush(timeoutMs?)`: Bounded wait for the internal send queue to drain. In serverless, call this before returning to avoid data loss. If no argument is passed, it uses the SDK `timeoutMs` value.
-- Recommendation for serverless: `await conversation.flush(3000–5000)` to balance reliability and latency.
-- `end()`: Convenience that flushes pending sends and marks the conversation as ended. It throws on flush timeout just like `flush()`.
-
-### Rate Limits
-
-- **Default:** 1,000 requests/hour per organization
-- **Reset:** Top of each hour
-- **Headers:** `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
-
-Contact support@teckel.ai for increases.
-
-## Runtime Compatibility
-
-Uses standard Web APIs (`fetch`, `AbortSignal`):
-
-- ✅ Node.js 18+
-- ✅ Bun 1.0+
-- ✅ Deno 1.35+ (`npm:teckel-ai`)
-- ✅ Cloudflare Workers
-- ✅ AWS Lambda
-- ✅ Vercel Edge Runtime
-- ✅ Google Cloud Run
-
-**Security:** Never expose API keys in browser code. Always call from server/serverless backend.
-
-## Best Practices
-
-1. Initialize `TeckelTracer` once at startup, reuse across requests
-2. Always call `flush()` in serverless before returning
-3. Include `documentLastUpdated` when available (enables freshness scoring)
-4. Use consistent `sessionRef` and `traceRef` for tracking
-5. Include `model`, `responseTimeMs`, `tokens` for insights
-6. Set `debug: false` in production
-7. Call `conversation.end()` when chat session completes
-
-## Troubleshooting
-
-**Traces not appearing?**
-1. Verify API key starts with `tk_live_`
-2. Check network connectivity to `https://app.teckel.ai/api`
-3. Enable `debug: true` to see errors
-4. Look for validation errors in console
-
-**Serverless traces dropping?**
-1. Ensure `await conversation.flush(5000)` before returning
-2. Monitor flush timeout errors in logs
-3. Increase timeout if needed (up to 5s for slow networks)
-
-**High latency?**
-1. Verify `trace()` is non-blocking (don't await it)
-2. Check `timeoutMs` configuration (default 5000ms)
-3. Review network connectivity
-
 ## Documentation
 
+- **Full SDK Reference:** [docs.teckel.ai/docs/typescript-sdk-reference](https://docs.teckel.ai/docs/typescript-sdk-reference)
 - **Getting Started:** [docs.teckel.ai/docs/getting-started](https://docs.teckel.ai/docs/getting-started)
-- **Complete SDK Reference:** [docs.teckel.ai/docs/typescript-sdk-reference](https://docs.teckel.ai/docs/typescript-sdk-reference)
-- **HTTP API Reference:** [docs.teckel.ai/docs/http-api-reference](https://docs.teckel.ai/docs/http-api-reference)
-- **Dashboard:** [app.teckel.ai](https://app.teckel.ai)
 
 ## Support
 
 - **Email:** support@teckel.ai
-- **Issues:** Report bugs or request features via GitHub issues
+- **Website** [teckel.ai](https://teckel.ai)
 
 ## License
 
 MIT
-
----
-
-Version 0.3.3

package/dist/{schemas.d.ts → index.d.mts}

@@ -1,11 +1,178 @@
+import { z } from 'zod';
+
 /**
- * Zod validation schemas for teckel-ai SDK v0.3.2
+ * Type definitions for teckel-ai SDK v0.3.5
+ * Simple, clean types matching existing database schema
  */
-import { z } from 'zod';
+/**
+ * SDK Configuration
+ */
+interface TeckelConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Conversation options
+ * sessionRef IS the conversation identifier
+ *
+ * Naming convention:
+ * - *Ref = Client-provided identifier (TEXT)
+ * - *Id = Server-generated internal ID (UUID)
+ */
+interface ConversationOptions {
+    sessionRef?: string;
+    userRef?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Document structure for RAG systems
+ * Matches existing documents + chunk_events schema
+ */
+interface Document {
+    documentRef: string;
+    documentName: string;
+    documentText: string;
+    documentLastUpdated?: string;
+    sourceUri?: string;
+    sourceType?: string;
+    similarity?: number;
+    rank?: number;
+    ownerEmail?: string;
+    documentType?: string;
+}
+/**
+ * Token usage tracking
+ */
+interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Trace data for a single query-response interaction
+ * Matches existing traces table schema
+ */
+interface TraceData {
+    query: string;
+    response: string;
+    model?: string;
+    responseTimeMs?: number;
+    documents?: Document[];
+    tokens?: TokenUsage;
+    metadata?: Record<string, unknown>;
+    traceRef?: string;
+    userRef?: string;
+}
+/**
+ * Feedback types
+ */
+type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
+/**
+ * User feedback signal
+ */
+interface FeedbackData {
+    type: FeedbackType;
+    value?: string;
+    comment?: string;
+    traceRef?: string;
+}
+/**
+ * Result returned when a trace is created
+ */
+interface TraceResult {
+    traceRef: string;
+    turnNumber: number;
+}
+
+/**
+ * Conversation class for teckel-ai SDK v0.3.5
+ * Manages a single conversation with fire-and-forget semantics
+ */
+
+/** Internal type - sessionRef is guaranteed by TeckelTracer.start() */
+interface ResolvedConversationOptions extends ConversationOptions {
+    sessionRef: string;
+}
+declare class Conversation {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly sessionRef;
+    private readonly userRef?;
+    private readonly metadata?;
+    private readonly startedAt;
+    private readonly debug;
+    private readonly timeoutMs;
+    private turnCount;
+    private startPromise;
+    private sendQueue;
+    constructor(apiKey: string, endpoint: string, options: ResolvedConversationOptions, debug?: boolean, extras?: {
+        timeoutMs: number;
+    });
+    /**
+     * Record a trace (single query-response interaction)
+     * Fire-and-forget by default - never blocks
+     * For serverless, call flush() before function termination
+     */
+    trace(data: TraceData): TraceResult | void;
+    /**
+     * Add user feedback signal
+     * Never throws - gracefully handles errors
+     */
+    feedback(data: FeedbackData): Promise<void>;
+    /**
+     * End the conversation
+     * Flushes all pending traces before sending end signal
+     * Never throws - gracefully handles errors
+     */
+    end(): Promise<void>;
+    /**
+     * Read-only properties
+     */
+    get id(): string;
+    get turns(): number;
+    get started(): Date;
+    private fetchWithRetry;
+    private _startConversation;
+    private _sendTrace;
+    private _sendFeedback;
+    private _endConversation;
+    private enqueueSend;
+    /**
+     * Flush queued sends with a bounded timeout.
+     * Returns when the queue is empty or the timeout elapses (whichever comes first).
+     */
+    flush(timeoutMs?: number): Promise<void>;
+}
+
+/**
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.5
+ * Simple, lightweight SDK for AI conversation tracking
+ */
+
+declare class TeckelTracer {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly debug;
+    private readonly timeoutMs;
+    constructor(config: TeckelConfig);
+    /**
+     * Start a new conversation
+     * sessionRef IS the public conversation identifier
+     * If not provided, auto-generates one as 'auto:{8-char-uuid}'
+     */
+    start(options?: ConversationOptions): Conversation;
+}
+
+/**
+ * Zod validation schemas for teckel-ai SDK v0.3.5
+ */
+
 /**
  * Document schema
  */
-export declare const DocumentSchema: z.ZodObject<{
+declare const DocumentSchema: z.ZodObject<{
     documentRef: z.ZodString;
     documentName: z.ZodString;
     documentText: z.ZodString;
@@ -42,7 +209,7 @@ export declare const DocumentSchema: z.ZodObject<{
 /**
  * Token usage schema
  */
-export declare const TokenUsageSchema: z.ZodObject<{
+declare const TokenUsageSchema: z.ZodObject<{
     prompt: z.ZodNumber;
     completion: z.ZodNumber;
     total: z.ZodNumber;
@@ -58,7 +225,7 @@ export declare const TokenUsageSchema: z.ZodObject<{
 /**
  * Trace data schema
  */
-export declare const TraceDataSchema: z.ZodObject<{
+declare const TraceDataSchema: z.ZodObject<{
     query: z.ZodString;
     response: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
@@ -112,6 +279,7 @@ export declare const TraceDataSchema: z.ZodObject<{
     }>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     traceRef: z.ZodOptional<z.ZodString>;
+    userRef: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     query: string;
     response: string;
@@ -136,6 +304,7 @@ export declare const TraceDataSchema: z.ZodObject<{
     } | undefined;
     metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
+    userRef?: string | undefined;
 }, {
     query: string;
     response: string;
@@ -160,27 +329,28 @@ export declare const TraceDataSchema: z.ZodObject<{
     } | undefined;
     metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
+    userRef?: string | undefined;
 }>;
 /**
  * Conversation options schema
  */
-export declare const ConversationOptionsSchema: z.ZodObject<{
-    sessionRef: z.ZodString;
-    userId: z.ZodOptional<z.ZodString>;
+declare const ConversationOptionsSchema: z.ZodObject<{
+    sessionRef: z.ZodOptional<z.ZodString>;
+    userRef: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    sessionRef: string;
     metadata?: Record<string, unknown> | undefined;
-    userId?: string | undefined;
+    userRef?: string | undefined;
+    sessionRef?: string | undefined;
 }, {
-    sessionRef: string;
     metadata?: Record<string, unknown> | undefined;
-    userId?: string | undefined;
+    userRef?: string | undefined;
+    sessionRef?: string | undefined;
 }>;
 /**
  * Feedback data schema
  */
-export declare const FeedbackDataSchema: z.ZodObject<{
+declare const FeedbackDataSchema: z.ZodObject<{
     type: z.ZodEnum<["thumbs_up", "thumbs_down", "flag", "rating"]>;
     value: z.ZodOptional<z.ZodString>;
     comment: z.ZodOptional<z.ZodString>;
@@ -199,7 +369,7 @@ export declare const FeedbackDataSchema: z.ZodObject<{
 /**
  * Config schema
  */
-export declare const TeckelConfigSchema: z.ZodObject<{
+declare const TeckelConfigSchema: z.ZodObject<{
     apiKey: z.ZodString;
     endpoint: z.ZodOptional<z.ZodString>;
     debug: z.ZodOptional<z.ZodBoolean>;
@@ -215,3 +385,5 @@ export declare const TeckelConfigSchema: z.ZodObject<{
     debug?: boolean | undefined;
     timeoutMs?: number | undefined;
 }>;
+
+export { Conversation, type ConversationOptions, ConversationOptionsSchema, type Document, DocumentSchema, type FeedbackData, FeedbackDataSchema, type FeedbackType, type TeckelConfig, TeckelConfigSchema, TeckelTracer, type TokenUsage, TokenUsageSchema, type TraceData, TraceDataSchema, type TraceResult };