@letterbook/ai-chat 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# Letterbook AI Chat TypeScript SDK
+
+Capture AI chat turns from your application so conversations can appear in the Letterbook platform when customers need help.
+
+```ts
+import * as letterbook from "@letterbook/ai-chat";
+
+const result = await letterbook.capture({
+  userId: "user123",
+  event: "user_message",
+  model: "gpt_4",
+  input: "The checkout page is broken and I was charged twice.",
+  output: "I am sorry, I cannot fix billing issues from here.",
+  convoId: "conv789",
+  customerEmail: "customer@example.com",
+  debounceSeconds: 300,
+  properties: {
+    system_prompt: "you are a helpful assistant",
+    experiment: "experiment_a",
+  },
+  attachments: [
+    {
+      type: "text",
+      name: "Additional Info",
+      value: "A very long document",
+      role: "input",
+    },
+  ],
+});
+
+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 `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.

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+export type LetterbookPriority = "low" | "medium" | "high" | "urgent";
+export type AttachmentRole = "input" | "output";
+export interface LetterbookAttachment {
+    type: string;
+    name?: string;
+    value: string;
+    role: AttachmentRole;
+}
+export interface LetterbookOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    raiseOnError?: boolean;
+    fetch?: typeof fetch;
+}
+export interface CaptureInput {
+    userId: string;
+    event: string;
+    model: string;
+    input?: string;
+    output?: string;
+    convoId?: string;
+    properties?: Record<string, unknown>;
+    attachments?: LetterbookAttachment[];
+    customerEmail?: string;
+    customerName?: string;
+    ticketEnabled?: boolean;
+    debounceSeconds?: number;
+    subject?: string;
+    priority?: LetterbookPriority;
+}
+export interface CaptureResult {
+    issueDetected?: boolean | null;
+    ticketCreated: boolean;
+    queued?: boolean;
+    status?: string;
+    existingTicket?: boolean;
+    evaluationAfterSeconds?: number;
+    priority?: LetterbookPriority;
+    reason?: string;
+    ticketId?: string;
+    ticketUrl?: string;
+    error?: string;
+}
+export declare class LetterbookError extends Error {
+    constructor(message: string);
+}
+export declare class Letterbook {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly raiseOnError;
+    private readonly fetchFn;
+    constructor(options?: LetterbookOptions);
+    capture(input: CaptureInput): Promise<CaptureResult>;
+    private postJson;
+    private fail;
+}
+export declare function capture(input: CaptureInput, options?: LetterbookOptions): Promise<CaptureResult>;

package/dist/index.js

@@ -0,0 +1,169 @@
+const DEFAULT_BASE_URL = "https://api.letterbook.ai/api";
+export class LetterbookError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LetterbookError";
+    }
+}
+export class Letterbook {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    raiseOnError;
+    fetchFn;
+    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;
+        if (!this.fetchFn) {
+            throw new LetterbookError("A fetch implementation is required.");
+        }
+    }
+    async capture(input) {
+        if (input.input == null && input.output == null) {
+            throw new LetterbookError("letterbook.capture 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");
+        }
+        if (input.ticketEnabled === false) {
+            return {
+                issueDetected: null,
+                ticketCreated: false,
+                queued: false,
+                status: "disabled",
+                reason: "Ticket capture is disabled.",
+            };
+        }
+        if (!this.apiKey) {
+            return this.fail("LETTERBOOK_API_KEY is required to capture AI chat");
+        }
+        const properties = input.properties ?? {};
+        const payload = {
+            user_id: input.userId,
+            event: input.event,
+            model: input.model,
+            input: input.input,
+            output: input.output,
+            convo_id: input.convoId,
+            properties,
+            attachments: normalizeAttachments(input.attachments ?? []),
+            customer_email: resolveCustomerEmail(input.userId, input.customerEmail, properties),
+            customer_name: input.customerName ?? stringOrUndefined(properties.customer_name),
+            ticket_enabled: input.ticketEnabled ?? true,
+            debounce_seconds: input.debounceSeconds,
+            subject: input.subject,
+            priority: input.priority,
+        };
+        try {
+            const data = await this.postJson("/v1/ai-chat/capture", payload);
+            return {
+                issueDetected: boolOrNull(data.issue_detected),
+                ticketCreated: Boolean(data.ticket_created),
+                queued: Boolean(data.queued),
+                status: stringOrUndefined(data.status),
+                existingTicket: Boolean(data.existing_ticket),
+                evaluationAfterSeconds: numberOrUndefined(data.evaluation_after_seconds),
+                priority: normalizePriority(data.priority),
+                reason: stringOrUndefined(data.reason),
+                ticketId: stringOrUndefined(data.ticket_id),
+                ticketUrl: stringOrUndefined(data.ticket_url),
+                error: stringOrUndefined(data.error),
+            };
+        }
+        catch (error) {
+            return this.fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    async postJson(path, payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            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",
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                throw new LetterbookError(`Letterbook API returned ${response.status}: ${text}`);
+            }
+            return text ? JSON.parse(text) : {};
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    fail(message) {
+        if (this.raiseOnError) {
+            throw new LetterbookError(message);
+        }
+        return {
+            issueDetected: null,
+            ticketCreated: false,
+            error: message,
+        };
+    }
+}
+export async function capture(input, options = {}) {
+    return new Letterbook(options).capture(input);
+}
+function normalizeAttachments(attachments) {
+    return attachments.map((attachment) => {
+        if (!attachment.value) {
+            throw new LetterbookError("Each attachment requires a value");
+        }
+        if (attachment.role !== "input" && attachment.role !== "output") {
+            throw new LetterbookError("Attachment role must be 'input' or 'output'");
+        }
+        return {
+            type: attachment.type || "text",
+            name: attachment.name,
+            value: attachment.value,
+            role: attachment.role,
+        };
+    });
+}
+function resolveCustomerEmail(userId, customerEmail, properties) {
+    return (customerEmail ??
+        stringOrUndefined(properties.customer_email) ??
+        stringOrUndefined(properties.email) ??
+        stringOrUndefined(properties.user_email) ??
+        (looksLikeEmail(userId) ? userId : undefined));
+}
+function looksLikeEmail(value) {
+    return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value);
+}
+function normalizePriority(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.toLowerCase();
+    if (["low", "medium", "high", "urgent"].includes(normalized)) {
+        return normalized;
+    }
+    return undefined;
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function boolOrNull(value) {
+    return typeof value === "boolean" ? value : null;
+}
+function numberOrUndefined(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    return undefined;
+}
+function readEnv(name) {
+    const maybeGlobal = globalThis;
+    return maybeGlobal.process?.env?.[name];
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@letterbook/ai-chat",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for capturing AI chat issues in Letterbook.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "letterbook",
+    "ai",
+    "chat",
+    "support",
+    "helpdesk"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3"
+  }
+}