teckel-ai 0.3.2 → 0.3.3

package/README.md

@@ -1,48 +1,425 @@
 # 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 your users are having. We track what questions users ask, how well your AI answers them, and tell you which areas needs improvement.
+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 MCP referencing AI chat system gives incomplete or incorrect answers because your knowledge base has gaps. Users get frustrated, support tickets increase, and you don't know which areas to focus on.
+**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 (or let you define an area of interest and see related questions), and tell you exactly which AI-retrieved documentation to add or update, prioritized by impact. We write your document templates for you to fill in with info your users need, and give you updates on your AI system's health via Slack.
+**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 (one dependency, 20-minute integration) sends your AI conversations to Teckel for analysis. You get:
+This lightweight SDK (zero dependencies, 20-minute integration) sends your AI conversations to Teckel for analysis:
 
-- **Completeness Scoring** - How well each response answers the user's question (0-100%)
+- **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 your AI needs to better answer user questions
+- **Actionable Feedback** - Specific recommendations on what knowledge to add
 
-Works with any RAG system or AI conversational framework: LangChain, LlamaIndex, Vercel AI SDK, custom implementations using vector database retrieval, or direct OpenAI/Anthropic calls.
+Works with any RAG system or AI framework: LangChain, LlamaIndex, Vercel AI SDK, or custom implementations.
 
-## Getting Started
+## Installation
 
-1. **Sign up** at [app.teckel.ai](https://app.teckel.ai) with a 14 day free trial
-2. **Generate an API key** from your dashboard (Admin Panel > API Keys)
-3. **Install the SDK**: `npm install teckel-ai`
-4. **Follow the integration guide** at [docs.teckel.ai/docs/getting-started](https://docs.teckel.ai/docs/getting-started)
+```bash
+npm install teckel-ai
+```
 
-## Documentation
+**Requirements:**
+- Node.js 18+ (or Bun, Deno, serverless runtimes)
+- TypeScript 4.5+ (optional but recommended)
 
-- [Getting Started Guide](https://docs.teckel.ai/docs/getting-started) - Step-by-step integration
-- [API & SDK Reference](https://docs.teckel.ai/docs/api-sdk-reference) - Complete field documentation and framework examples
-- [Troubleshooting](https://docs.teckel.ai/docs/troubleshooting) - Common issues and solutions
+## Quick Start
 
-## Requirements
+```typescript
+import { TeckelTracer } from 'teckel-ai';
 
-- Node.js 18+ (or Bun, Deno, serverless runtimes)
-- A Teckel AI account with API key
-- An LLM-based application (RAG system, chatbot, AI agent)
+// Initialize once at startup
+const tracer = new TeckelTracer({
+  apiKey: process.env.TECKEL_API_KEY
+});
+
+// In your API handler
+async function handleChat(userQuestion: string, sessionId: string) {
+  // Start conversation
+  const conversation = tracer.start({
+    sessionRef: sessionId,
+    userId: 'user@example.com'
+  });
+
+  // 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
+  });
+
+  // For serverless: flush before returning
+  await conversation.flush(5000);
+
+  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
+
+- **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
 
-- **Documentation**: [docs.teckel.ai](https://docs.teckel.ai)
-- **Dashboard**: [app.teckel.ai](https://app.teckel.ai)
-- **Email**: support@teckel.ai
+- **Email:** support@teckel.ai
+- **Issues:** Report bugs or request features via GitHub issues
 
 ## License
 
@@ -50,4 +427,4 @@ MIT
 
 ---
 
-Version 0.3.2
+Version 0.3.3

package/dist/conversation.d.ts

@@ -1,5 +1,5 @@
 /**
- * Conversation class for teckel-ai SDK v0.3.1
+ * Conversation class for teckel-ai SDK v0.3.2
  * Manages a single conversation with fire-and-forget semantics
  */
 import type { TraceData, FeedbackData, ConversationOptions, TraceResult } from './types';
@@ -24,14 +24,6 @@ export declare class Conversation {
      * For serverless, call flush() before function termination
      */
     trace(data: TraceData): TraceResult | void;
-    /**
-     * Synchronous trace: waits for HTTP send to complete.
-     * Throws on network/validation errors.
-     * Respects send queue to maintain trace ordering.
-     */
-    traceSync(data: TraceData, opt?: {
-        timeoutMs?: number;
-    }): Promise<TraceResult>;
     /**
      * Add user feedback signal
      * Never throws - gracefully handles errors
@@ -60,5 +52,4 @@ export declare class Conversation {
      * Returns when the queue is empty or the timeout elapses (whichever comes first).
      */
     flush(timeoutMs?: number): Promise<void>;
-    private mapOTelAliases;
 }

package/dist/conversation.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Conversation class for teckel-ai SDK v0.3.1
+ * Conversation class for teckel-ai SDK v0.3.2
  * Manages a single conversation with fire-and-forget semantics
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -41,24 +41,22 @@ class Conversation {
         try {
             // Validate with Zod
             const validated = schemas_1.TraceDataSchema.parse(data);
-            // Apply OTel alias mapping (beta): infer canonical fields from metadata if missing
-            const mapped = this.mapOTelAliases(validated);
             // Increment local turn number immediately (client-side counter)
             const localTurn = ++this.turnCount;
             // Ensure we have a client-provided traceRef; if missing, generate a deterministic one
-            const finalTraceRef = mapped.traceRef && mapped.traceRef.length > 0
-                ? mapped.traceRef
+            const finalTraceRef = validated.traceRef && validated.traceRef.length > 0
+                ? validated.traceRef
                 : `${this.sessionRef}:${localTurn}`;
             if (this.debug) {
                 console.log('[Teckel] Queueing trace (fire-and-forget):', {
                     sessionRef: this.sessionRef,
                     turnNumber: localTurn,
-                    queryLength: mapped.query.length,
-                    responseLength: mapped.response.length,
-                    documentCount: ((_a = mapped.documents) === null || _a === void 0 ? void 0 : _a.length) || 0
+                    queryLength: validated.query.length,
+                    responseLength: validated.response.length,
+                    documentCount: ((_a = validated.documents) === null || _a === void 0 ? void 0 : _a.length) || 0
                 });
             }
-            const toSend = Object.assign(Object.assign({}, mapped), { traceRef: finalTraceRef });
+            const toSend = Object.assign(Object.assign({}, validated), { traceRef: finalTraceRef });
             // Fire-and-forget: enqueue and return immediately
             this.enqueueSend(async () => {
                 try {
@@ -67,7 +65,8 @@ class Conversation {
                 }
                 catch (err) {
                     if (this.debug) {
-                        console.warn('[Teckel] Trace send failed (non-blocking):', (err === null || err === void 0 ? void 0 : err.message) || err);
+                        const msg = err instanceof Error ? err.message : String(err);
+                        console.warn('[Teckel] Trace send failed (non-blocking):', msg);
                     }
                 }
             });
@@ -80,36 +79,6 @@ class Conversation {
             }
         }
     }
-    /**
-     * Synchronous trace: waits for HTTP send to complete.
-     * Throws on network/validation errors.
-     * Respects send queue to maintain trace ordering.
-     */
-    async traceSync(data, opt) {
-        // Validate with Zod
-        const validated = schemas_1.TraceDataSchema.parse(data);
-        // Apply OTel alias mapping
-        const mapped = this.mapOTelAliases(validated);
-        // Increment local turn and compute final traceRef
-        const localTurn = ++this.turnCount;
-        const finalTraceRef = mapped.traceRef && mapped.traceRef.length > 0
-            ? mapped.traceRef
-            : `${this.sessionRef}:${localTurn}`;
-        const toSend = Object.assign(Object.assign({}, mapped), { traceRef: finalTraceRef });
-        try {
-            await this.startPromise;
-            // Wait for any queued operations to complete first (maintains ordering)
-            await this.sendQueue.catch(() => { });
-            await this._sendTrace(toSend, { timeoutMs: opt === null || opt === void 0 ? void 0 : opt.timeoutMs });
-            return { traceRef: finalTraceRef, turnNumber: localTurn };
-        }
-        catch (err) {
-            if (this.debug) {
-                console.warn('[Teckel] Sync trace failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
-            }
-            throw err;
-        }
-    }
     /**
      * Add user feedback signal
      * Never throws - gracefully handles errors
@@ -131,7 +100,8 @@ class Conversation {
                 }
                 catch (err) {
                     if (this.debug) {
-                        console.warn('[Teckel] Feedback failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
+                        const msg = err instanceof Error ? err.message : String(err);
+                        console.warn('[Teckel] Feedback failed:', msg);
                     }
                 }
             });
@@ -164,7 +134,8 @@ class Conversation {
             }
             catch (err) {
                 if (this.debug) {
-                    console.warn('[Teckel] End failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.warn('[Teckel] End failed:', msg);
                 }
             }
         });
@@ -227,7 +198,7 @@ class Conversation {
                 'Content-Type': 'application/json'
             },
             keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            signal: getTimeoutSignal(this.timeoutMs),
             body: JSON.stringify({
                 sessionRef: this.sessionRef,
                 userId: this.userId,
@@ -247,7 +218,7 @@ class Conversation {
                 'Content-Type': 'application/json'
             },
             keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout((_a = opt === null || opt === void 0 ? void 0 : opt.timeoutMs) !== null && _a !== void 0 ? _a : this.timeoutMs) : undefined,
+            signal: getTimeoutSignal((_a = opt === null || opt === void 0 ? void 0 : opt.timeoutMs) !== null && _a !== void 0 ? _a : this.timeoutMs),
             body: JSON.stringify(data)
         }, { retries: 1, retryDelayMs: 300 });
         if (!response.ok) {
@@ -264,7 +235,7 @@ class Conversation {
                 'Content-Type': 'application/json'
             },
             keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            signal: getTimeoutSignal(this.timeoutMs),
             body: JSON.stringify(data)
         }, { retries: 1, retryDelayMs: 300 });
         if (!response.ok) {
@@ -279,7 +250,7 @@ class Conversation {
                 'Content-Type': 'application/json'
             },
             keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            signal: getTimeoutSignal(this.timeoutMs),
             body: JSON.stringify({
                 durationMs: duration,
                 turnCount: this.turnCount
@@ -316,7 +287,8 @@ class Conversation {
         }
         catch (err) {
             if (this.debug) {
-                console.warn('[Teckel] Flush incomplete:', (err === null || err === void 0 ? void 0 : err.message) || err);
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn('[Teckel] Flush incomplete:', msg);
             }
             // Surface timeout so callers can react in serverless
             throw err;
@@ -326,38 +298,13 @@ class Conversation {
                 clearTimeout(timer);
         }
     }
-    // Utility: map OpenTelemetry-like metadata to canonical fields (beta)
-    mapOTelAliases(data) {
-        try {
-            const meta = data.metadata;
-            if (!meta)
-                return data;
-            const mapped = Object.assign({}, data);
-            // Model
-            if (!mapped.model && typeof meta['gen_ai.request.model'] === 'string') {
-                mapped.model = meta['gen_ai.request.model'];
-            }
-            // Tokens
-            const inTok = meta['gen_ai.usage.input_tokens'];
-            const outTok = meta['gen_ai.usage.output_tokens'];
-            const totTok = meta['gen_ai.usage.total_tokens'];
-            if (!mapped.tokens && (typeof inTok === 'number' || typeof outTok === 'number')) {
-                mapped.tokens = {
-                    prompt: typeof inTok === 'number' ? inTok : 0,
-                    completion: typeof outTok === 'number' ? outTok : 0,
-                    total: typeof totTok === 'number' ? totTok : ((typeof inTok === 'number' ? inTok : 0) + (typeof outTok === 'number' ? outTok : 0))
-                };
-            }
-            // Latency
-            const latency = meta['gen_ai.response.latency'];
-            if (!mapped.responseTimeMs && typeof latency === 'number') {
-                mapped.responseTimeMs = latency;
-            }
-            return mapped;
-        }
-        catch (_a) {
-            return data;
-        }
-    }
 }
 exports.Conversation = Conversation;
+// Helper: get AbortSignal.timeout if available
+function getTimeoutSignal(ms) {
+    const timeout = AbortSignal.timeout;
+    if (typeof timeout === 'function' && typeof ms === 'number') {
+        return timeout(ms);
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * teckel-ai v0.3.1
+ * teckel-ai v0.3.3
  * Simple SDK for AI conversation tracking and RAG observability
  *
  * @packageDocumentation

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * teckel-ai v0.3.1
+ * teckel-ai v0.3.3
  * Simple SDK for AI conversation tracking and RAG observability
  *
  * @packageDocumentation

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 /**
- * Zod validation schemas for teckel-ai SDK v0.3.1
+ * Zod validation schemas for teckel-ai SDK v0.3.2
  */
 import { z } from 'zod';
 /**
@@ -110,7 +110,7 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     traceRef: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     query: string;
@@ -134,7 +134,7 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
 }, {
     query: string;
@@ -158,7 +158,7 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
 }>;
 /**
@@ -167,14 +167,14 @@ export declare const TraceDataSchema: z.ZodObject<{
 export declare const ConversationOptionsSchema: z.ZodObject<{
     sessionRef: z.ZodString;
     userId: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     sessionRef: string;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     userId?: string | undefined;
 }, {
     sessionRef: string;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     userId?: string | undefined;
 }>;
 /**

package/dist/schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Zod validation schemas for teckel-ai SDK v0.3.1
+ * Zod validation schemas for teckel-ai SDK v0.3.2
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TeckelConfigSchema = exports.FeedbackDataSchema = exports.ConversationOptionsSchema = exports.TraceDataSchema = exports.TokenUsageSchema = exports.DocumentSchema = void 0;
@@ -38,7 +38,7 @@ exports.TraceDataSchema = zod_1.z.object({
     responseTimeMs: zod_1.z.number().positive().optional(),
     documents: zod_1.z.array(exports.DocumentSchema).max(50, 'Too many documents (max 50)').optional(),
     tokens: exports.TokenUsageSchema.optional(),
-    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
     traceRef: zod_1.z.string().min(1).optional()
 });
 /**
@@ -47,7 +47,7 @@ exports.TraceDataSchema = zod_1.z.object({
 exports.ConversationOptionsSchema = zod_1.z.object({
     sessionRef: zod_1.z.string().min(1, 'sessionRef is required'),
     userId: zod_1.z.string().optional(),
-    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional()
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional()
 });
 /**
  * Feedback data schema

package/dist/tracer.d.ts

@@ -1,5 +1,5 @@
 /**
- * TeckelTracer - Main SDK class for teckel-ai v0.3.1
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.2
  * Simple, lightweight SDK for AI conversation tracking
  */
 import { Conversation } from './conversation';
@@ -12,7 +12,7 @@ export declare class TeckelTracer {
     constructor(config: TeckelConfig);
     /**
      * Start a new conversation
-     * sessionRef IS the public conversation identifier (sessionId is legacy alias)
+     * sessionRef IS the public conversation identifier
      */
     start(options: ConversationOptions): Conversation;
 }

package/dist/tracer.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * TeckelTracer - Main SDK class for teckel-ai v0.3.1
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.2
  * Simple, lightweight SDK for AI conversation tracking
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -24,14 +24,14 @@ class TeckelTracer {
         if (this.debug) {
             console.log('[Teckel] SDK initialized:', {
                 endpoint: this.endpoint,
-                version: '0.3.1',
+                version: '0.3.2',
                 timeoutMs: this.timeoutMs
             });
         }
     }
     /**
      * Start a new conversation
-     * sessionRef IS the public conversation identifier (sessionId is legacy alias)
+     * sessionRef IS the public conversation identifier
      */
     start(options) {
         // Validate options with Zod

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type definitions for teckel-ai SDK v0.3.1
+ * Type definitions for teckel-ai SDK v0.3.2
  * Simple, clean types matching existing database schema
  */
 /**
@@ -18,7 +18,7 @@ export interface TeckelConfig {
 export interface ConversationOptions {
     sessionRef: string;
     userId?: string;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Document structure for RAG systems
@@ -55,7 +55,7 @@ export interface TraceData {
     responseTimeMs?: number;
     documents?: Document[];
     tokens?: TokenUsage;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
     traceRef?: string;
 }
 /**

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Type definitions for teckel-ai SDK v0.3.1
+ * Type definitions for teckel-ai SDK v0.3.2
  * Simple, clean types matching existing database schema
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teckel-ai",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Simple SDK for AI conversation tracking and RAG observability",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",