teckel-ai 0.3.2 → 0.3.5

package/dist/conversation.js

@@ -1,363 +0,0 @@
-"use strict";
-/**
- * Conversation class for teckel-ai SDK v0.3.1
- * Manages a single conversation with fire-and-forget semantics
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Conversation = void 0;
-const schemas_1 = require("./schemas");
-class Conversation {
-    constructor(apiKey, endpoint, options, debug = false, extras = { timeoutMs: 5000 }) {
-        this.turnCount = 0;
-        this.sendQueue = Promise.resolve();
-        this.apiKey = apiKey;
-        this.endpoint = endpoint;
-        this.sessionRef = options.sessionRef;
-        this.userId = options.userId;
-        this.metadata = options.metadata;
-        this.startedAt = new Date();
-        this.debug = debug;
-        this.timeoutMs = extras.timeoutMs;
-        if (this.debug) {
-            console.log('[Teckel] Conversation started:', {
-                sessionRef: this.sessionRef,
-                userId: this.userId
-            });
-        }
-        // Start conversation and store promise
-        this.startPromise = this._startConversation().catch(err => {
-            if (this.debug) {
-                console.warn('[Teckel] Start failed:', err.message);
-            }
-        });
-    }
-    /**
-     * Record a trace (single query-response interaction)
-     * Fire-and-forget by default - never blocks
-     * For serverless, call flush() before function termination
-     */
-    trace(data) {
-        var _a;
-        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
-                : `${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
-                });
-            }
-            const toSend = Object.assign(Object.assign({}, mapped), { traceRef: finalTraceRef });
-            // Fire-and-forget: enqueue and return immediately
-            this.enqueueSend(async () => {
-                try {
-                    await this.startPromise; // ensure conversation exists
-                    await this._sendTrace(toSend);
-                }
-                catch (err) {
-                    if (this.debug) {
-                        console.warn('[Teckel] Trace send failed (non-blocking):', (err === null || err === void 0 ? void 0 : err.message) || err);
-                    }
-                }
-            });
-            return { traceRef: finalTraceRef, turnNumber: localTurn };
-        }
-        catch (err) {
-            // Validation failed - log and continue (never throw to user)
-            if (this.debug) {
-                console.warn('[Teckel] Invalid trace data:', err);
-            }
-        }
-    }
-    /**
-     * 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
-     */
-    async feedback(data) {
-        try {
-            // Validate with Zod
-            const validated = schemas_1.FeedbackDataSchema.parse(data);
-            if (this.debug) {
-                console.log('[Teckel] Sending feedback:', {
-                    sessionRef: this.sessionRef,
-                    type: validated.type
-                });
-            }
-            // Enqueue feedback so flush() covers it in serverless
-            this.enqueueSend(async () => {
-                try {
-                    await this._sendFeedback(validated);
-                }
-                catch (err) {
-                    if (this.debug) {
-                        console.warn('[Teckel] Feedback failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
-                    }
-                }
-            });
-        }
-        catch (err) {
-            // Validation failed - log and continue
-            if (this.debug) {
-                console.warn('[Teckel] Invalid feedback data:', err);
-            }
-        }
-    }
-    /**
-     * End the conversation
-     * Flushes all pending traces before sending end signal
-     * Never throws - gracefully handles errors
-     */
-    async end() {
-        const duration = Date.now() - this.startedAt.getTime();
-        if (this.debug) {
-            console.log('[Teckel] Ending conversation:', {
-                sessionRef: this.sessionRef,
-                durationMs: duration,
-                turnCount: this.turnCount
-            });
-        }
-        // Enqueue end so it occurs after any pending sends
-        this.enqueueSend(async () => {
-            try {
-                await this._endConversation(duration);
-            }
-            catch (err) {
-                if (this.debug) {
-                    console.warn('[Teckel] End failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
-                }
-            }
-        });
-        // Flush queue (serverless-safe)
-        await this.flush();
-    }
-    /**
-     * Read-only properties
-     */
-    get id() {
-        return this.sessionRef;
-    }
-    get turns() {
-        return this.turnCount;
-    }
-    get started() {
-        return this.startedAt;
-    }
-    // Private HTTP methods
-    // Lightweight fetch with a single retry on transient errors (429/5xx or network)
-    async fetchWithRetry(url, init, opts) {
-        var _a, _b;
-        const retries = (_a = opts === null || opts === void 0 ? void 0 : opts.retries) !== null && _a !== void 0 ? _a : 1;
-        const retryDelayMs = (_b = opts === null || opts === void 0 ? void 0 : opts.retryDelayMs) !== null && _b !== void 0 ? _b : 250;
-        let attempt = 0;
-        // Simple jittered delay
-        const sleep = (ms) => new Promise(res => setTimeout(res, ms));
-        // We reuse the same init; AbortSignal.timeout recreates a fresh signal per call
-        while (true) {
-            try {
-                const response = await fetch(url, init);
-                if (!response.ok && (response.status === 429 || (response.status >= 500 && response.status <= 599))) {
-                    if (attempt < retries) {
-                        attempt++;
-                        if (this.debug)
-                            console.warn('[Teckel] HTTP retry', { url, status: response.status, attempt });
-                        await sleep(retryDelayMs + Math.floor(Math.random() * 100));
-                        continue;
-                    }
-                }
-                return response;
-            }
-            catch (err) {
-                if (attempt < retries) {
-                    attempt++;
-                    if (this.debug)
-                        console.warn('[Teckel] Network retry', { url, attempt, error: err instanceof Error ? err.message : String(err) });
-                    await sleep(retryDelayMs + Math.floor(Math.random() * 100));
-                    continue;
-                }
-                throw err;
-            }
-        }
-    }
-    async _startConversation() {
-        const response = await this.fetchWithRetry(`${this.endpoint}/conversations`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json'
-            },
-            keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
-            body: JSON.stringify({
-                sessionRef: this.sessionRef,
-                userId: this.userId,
-                metadata: this.metadata
-            })
-        }, { retries: 1, retryDelayMs: 300 });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-    }
-    async _sendTrace(data, opt) {
-        var _a;
-        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}/traces`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                '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,
-            body: JSON.stringify(data)
-        }, { retries: 1, retryDelayMs: 300 });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-        const result = await response.json();
-        return result;
-    }
-    async _sendFeedback(data) {
-        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}/feedback`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json'
-            },
-            keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
-            body: JSON.stringify(data)
-        }, { retries: 1, retryDelayMs: 300 });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-    }
-    async _endConversation(duration) {
-        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}`, {
-            method: 'PATCH',
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json'
-            },
-            keepalive: true,
-            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
-            body: JSON.stringify({
-                durationMs: duration,
-                turnCount: this.turnCount
-            })
-        }, { retries: 1, retryDelayMs: 300 });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-    }
-    // Utility: append a send task to the queue
-    enqueueSend(task) {
-        this.sendQueue = this.sendQueue.then(() => task()).catch(() => {
-            // Errors are handled where task is defined; keep queue alive
-        });
-    }
-    /**
-     * Flush queued sends with a bounded timeout.
-     * Returns when the queue is empty or the timeout elapses (whichever comes first).
-     */
-    async flush(timeoutMs) {
-        const waitMs = (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 0)
-            ? timeoutMs
-            : this.timeoutMs;
-        // Snapshot current queue to cover all work up to this call
-        const done = this.sendQueue.catch(() => { });
-        let timer;
-        try {
-            await Promise.race([
-                done,
-                new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(new Error('Flush timeout')), waitMs);
-                })
-            ]);
-        }
-        catch (err) {
-            if (this.debug) {
-                console.warn('[Teckel] Flush incomplete:', (err === null || err === void 0 ? void 0 : err.message) || err);
-            }
-            // Surface timeout so callers can react in serverless
-            throw err;
-        }
-        finally {
-            if (timer)
-                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;

package/dist/schemas.js

@@ -1,69 +0,0 @@
-"use strict";
-/**
- * Zod validation schemas for teckel-ai SDK v0.3.1
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TeckelConfigSchema = exports.FeedbackDataSchema = exports.ConversationOptionsSchema = exports.TraceDataSchema = exports.TokenUsageSchema = exports.DocumentSchema = void 0;
-const zod_1 = require("zod");
-/**
- * Document schema
- */
-exports.DocumentSchema = zod_1.z.object({
-    documentRef: zod_1.z.string().min(1, 'documentRef is required'),
-    documentName: zod_1.z.string().min(1, 'documentName is required'),
-    documentText: zod_1.z.string().min(1, 'documentText is required'),
-    documentLastUpdated: zod_1.z.string().optional(),
-    sourceUri: zod_1.z.string().optional(),
-    sourceType: zod_1.z.string().optional(),
-    similarity: zod_1.z.number().min(0).max(1).optional(),
-    rank: zod_1.z.number().int().nonnegative().optional(),
-    ownerEmail: zod_1.z.string().email().optional(),
-    documentType: zod_1.z.string().optional()
-});
-/**
- * Token usage schema
- */
-exports.TokenUsageSchema = zod_1.z.object({
-    prompt: zod_1.z.number().int().nonnegative(),
-    completion: zod_1.z.number().int().nonnegative(),
-    total: zod_1.z.number().int().nonnegative()
-});
-/**
- * Trace data schema
- */
-exports.TraceDataSchema = zod_1.z.object({
-    query: zod_1.z.string().min(1, 'query is required').max(10000, 'query too long (max 10,000 characters)'),
-    response: zod_1.z.string().min(1, 'response is required').max(50000, 'response too long (max 50,000 characters)'),
-    model: zod_1.z.string().optional(),
-    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(),
-    traceRef: zod_1.z.string().min(1).optional()
-});
-/**
- * Conversation options schema
- */
-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()
-});
-/**
- * Feedback data schema
- */
-exports.FeedbackDataSchema = zod_1.z.object({
-    type: zod_1.z.enum(['thumbs_up', 'thumbs_down', 'flag', 'rating']),
-    value: zod_1.z.string().optional(),
-    comment: zod_1.z.string().optional(),
-    traceRef: zod_1.z.string().optional()
-});
-/**
- * Config schema
- */
-exports.TeckelConfigSchema = zod_1.z.object({
-    apiKey: zod_1.z.string().min(1, 'apiKey is required'),
-    endpoint: zod_1.z.string().url().optional(),
-    debug: zod_1.z.boolean().optional(),
-    timeoutMs: zod_1.z.number().int().positive().max(60000).optional()
-});

package/dist/tracer.d.ts

@@ -1,18 +0,0 @@
-/**
- * TeckelTracer - Main SDK class for teckel-ai v0.3.1
- * Simple, lightweight SDK for AI conversation tracking
- */
-import { Conversation } from './conversation';
-import type { TeckelConfig, ConversationOptions } from './types';
-export 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 (sessionId is legacy alias)
-     */
-    start(options: ConversationOptions): Conversation;
-}

package/dist/tracer.js

@@ -1,45 +0,0 @@
-"use strict";
-/**
- * TeckelTracer - Main SDK class for teckel-ai v0.3.1
- * Simple, lightweight SDK for AI conversation tracking
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TeckelTracer = void 0;
-const conversation_1 = require("./conversation");
-const schemas_1 = require("./schemas");
-class TeckelTracer {
-    constructor(config) {
-        // Validate config with Zod
-        const validated = schemas_1.TeckelConfigSchema.parse(config);
-        // API key format warning
-        if (!validated.apiKey.startsWith('tk_live_')) {
-            console.warn('[Teckel] API key should start with "tk_live_". ' +
-                'Current key: ' + validated.apiKey.substring(0, 10) + '...');
-        }
-        this.apiKey = validated.apiKey;
-        this.endpoint = validated.endpoint || 'https://app.teckel.ai/api';
-        this.debug = validated.debug || false;
-        // Default timeout mirrors common telemetry SDKs (3–5s) to tolerate cold starts
-        this.timeoutMs = typeof validated.timeoutMs === 'number' ? validated.timeoutMs : 5000;
-        if (this.debug) {
-            console.log('[Teckel] SDK initialized:', {
-                endpoint: this.endpoint,
-                version: '0.3.1',
-                timeoutMs: this.timeoutMs
-            });
-        }
-    }
-    /**
-     * Start a new conversation
-     * sessionRef IS the public conversation identifier (sessionId is legacy alias)
-     */
-    start(options) {
-        // Validate options with Zod
-        const validated = schemas_1.ConversationOptionsSchema.parse(options);
-        // Create and return conversation instance
-        return new conversation_1.Conversation(this.apiKey, this.endpoint, validated, this.debug, {
-            timeoutMs: this.timeoutMs
-        });
-    }
-}
-exports.TeckelTracer = TeckelTracer;

package/dist/types.d.ts

@@ -1,88 +0,0 @@
-/**
- * Type definitions for teckel-ai SDK v0.3.1
- * Simple, clean types matching existing database schema
- */
-/**
- * SDK Configuration
- */
-export interface TeckelConfig {
-    apiKey: string;
-    endpoint?: string;
-    debug?: boolean;
-    timeoutMs?: number;
-}
-/**
- * Conversation options
- * sessionId IS the conversation identifier
- */
-export interface ConversationOptions {
-    sessionRef: string;
-    userId?: string;
-    metadata?: Record<string, any>;
-}
-/**
- * Document structure for RAG systems
- * Matches existing documents + chunk_events schema
- */
-export 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
- */
-export interface TokenUsage {
-    prompt: number;
-    completion: number;
-    total: number;
-}
-/**
- * Trace data for a single query-response interaction
- * Matches existing traces table schema
- */
-export interface TraceData {
-    query: string;
-    response: string;
-    model?: string;
-    responseTimeMs?: number;
-    documents?: Document[];
-    tokens?: TokenUsage;
-    metadata?: Record<string, any>;
-    traceRef?: string;
-}
-/**
- * Feedback types
- */
-export type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
-/**
- * User feedback signal
- */
-export interface FeedbackData {
-    type: FeedbackType;
-    value?: string;
-    comment?: string;
-    traceRef?: string;
-}
-/**
- * Result returned when a trace is created
- */
-export interface TraceResult {
-    traceRef: string;
-    turnNumber: number;
-}
-/**
- * Validation result structure
- */
-export interface ValidationResult {
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-}

package/dist/types.js

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