@letterbook/ai-chat 0.1.0 → 1.0.0

package/README.md

@@ -1,11 +1,13 @@
 # Letterbook AI Chat TypeScript SDK
 
-Capture AI chat turns from your application so conversations can appear in the Letterbook platform when customers need help.
+Send AI chat turns to Letterbook so customer issues can be detected from the full conversation.
+
+Each call captures one turn in the conversation. It does not create a ticket by itself. Letterbook queues the turns, waits for the conversation to go quiet, scans the transcript on the backend with an LLM, and creates a ticket only when it finds a relevant customer issue.
 
 ```ts
 import * as letterbook from "@letterbook/ai-chat";
 
-const result = await letterbook.capture({
+const result = await letterbook.recordTurn({
   userId: "user123",
   event: "user_message",
   model: "gpt_4",
@@ -33,6 +35,9 @@ console.log(result.queued, result.evaluationAfterSeconds);
 
 Set `LETTERBOOK_API_KEY`, or instantiate `new letterbook.Letterbook({ apiKey })` for explicit configuration.
 Set `debounceSeconds` to control how long Letterbook waits after the last message before evaluating the conversation.
+If OpenTelemetry is configured in your app, the SDK automatically propagates the active trace context with each capture request.
 
 If `customerEmail` is omitted, the SDK looks for `properties.customer_email`, `properties.email`, or an email-shaped `userId`.
 Email is only required if Letterbook promotes the capture to a ticket.
+
+`letterbook.captureTurn(...)` and `letterbook.capture(...)` are deprecated compatibility aliases for `letterbook.recordTurn(...)`.

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export interface LetterbookOptions {
     timeoutMs?: number;
     raiseOnError?: boolean;
     fetch?: typeof fetch;
+    otelEnabled?: boolean;
 }
 export interface CaptureInput {
     userId: string;
@@ -51,9 +52,26 @@ export declare class Letterbook {
     private readonly timeoutMs;
     private readonly raiseOnError;
     private readonly fetchFn;
+    private readonly otelEnabled;
     constructor(options?: LetterbookOptions);
+    recordTurn(input: CaptureInput): Promise<CaptureResult>;
+    /**
+     * @deprecated Use recordTurn instead. captureTurn remains as a compatibility alias.
+     */
+    captureTurn(input: CaptureInput): Promise<CaptureResult>;
+    /**
+     * @deprecated Use recordTurn instead. capture remains as a compatibility alias.
+     */
     capture(input: CaptureInput): Promise<CaptureResult>;
     private postJson;
     private fail;
 }
+/**
+ * @deprecated Use recordTurn instead. capture remains as a compatibility alias.
+ */
 export declare function capture(input: CaptureInput, options?: LetterbookOptions): Promise<CaptureResult>;
+/**
+ * @deprecated Use recordTurn instead. captureTurn remains as a compatibility alias.
+ */
+export declare function captureTurn(input: CaptureInput, options?: LetterbookOptions): Promise<CaptureResult>;
+export declare function recordTurn(input: CaptureInput, options?: LetterbookOptions): Promise<CaptureResult>;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { context, propagation } from "@opentelemetry/api";
 const DEFAULT_BASE_URL = "https://api.letterbook.ai/api";
 export class LetterbookError extends Error {
     constructor(message) {
@@ -11,22 +12,24 @@ export class Letterbook {
     timeoutMs;
     raiseOnError;
     fetchFn;
+    otelEnabled;
     constructor(options = {}) {
         this.apiKey = options.apiKey ?? readEnv("LETTERBOOK_API_KEY");
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.timeoutMs = options.timeoutMs ?? 10_000;
         this.raiseOnError = options.raiseOnError ?? false;
         this.fetchFn = options.fetch ?? globalThis.fetch;
+        this.otelEnabled = options.otelEnabled ?? true;
         if (!this.fetchFn) {
             throw new LetterbookError("A fetch implementation is required.");
         }
     }
-    async capture(input) {
+    async recordTurn(input) {
         if (input.input == null && input.output == null) {
-            throw new LetterbookError("letterbook.capture requires at least one of input or output");
+            throw new LetterbookError("letterbook.recordTurn requires at least one of input or output");
         }
         if (input.debounceSeconds != null && input.debounceSeconds < 1) {
-            throw new LetterbookError("letterbook.capture debounceSeconds must be at least 1");
+            throw new LetterbookError("letterbook.recordTurn debounceSeconds must be at least 1");
         }
         if (input.ticketEnabled === false) {
             return {
@@ -77,17 +80,33 @@ export class Letterbook {
             return this.fail(error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * @deprecated Use recordTurn instead. captureTurn remains as a compatibility alias.
+     */
+    async captureTurn(input) {
+        return this.recordTurn(input);
+    }
+    /**
+     * @deprecated Use recordTurn instead. capture remains as a compatibility alias.
+     */
+    async capture(input) {
+        return this.recordTurn(input);
+    }
     async postJson(path, payload) {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
+            const headers = {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "User-Agent": "@letterbook/ai-chat/1.0.0",
+            };
+            if (this.otelEnabled) {
+                propagation.inject(context.active(), headers);
+            }
             const response = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${this.apiKey}`,
-                    "Content-Type": "application/json",
-                    "User-Agent": "@letterbook/ai-chat/0.1.0",
-                },
+                headers,
                 body: JSON.stringify(payload),
                 signal: controller.signal,
             });
@@ -112,8 +131,20 @@ export class Letterbook {
         };
     }
 }
+/**
+ * @deprecated Use recordTurn instead. capture remains as a compatibility alias.
+ */
 export async function capture(input, options = {}) {
-    return new Letterbook(options).capture(input);
+    return recordTurn(input, options);
+}
+/**
+ * @deprecated Use recordTurn instead. captureTurn remains as a compatibility alias.
+ */
+export async function captureTurn(input, options = {}) {
+    return recordTurn(input, options);
+}
+export async function recordTurn(input, options = {}) {
+    return new Letterbook(options).recordTurn(input);
 }
 function normalizeAttachments(attachments) {
     return attachments.map((attachment) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@letterbook/ai-chat",
-  "version": "0.1.0",
-  "description": "TypeScript SDK for capturing AI chat issues in Letterbook.",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for sending AI chat turns to Letterbook for issue detection.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,5 +32,8 @@
   },
   "devDependencies": {
     "typescript": "~5.8.3"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0"
   }
 }