@guava-ai/guava-sdk 0.2.0 → 0.4.0

package/src/telemetry.ts

@@ -0,0 +1,125 @@
+import { getDefaultLogger, type Logger } from "./logging.ts";
+import { getBaseUrl, fetchOrThrow } from "./utils.ts";
+
+const QUEUE_MAX_SIZE = 100;
+const UPLOAD_INTERVAL_MS = 10_000;
+
+const debugEnabled = ["yes", "true"].includes(
+  (process.env.GUAVA_DEBUG_TELEMETRY ?? "false").toLowerCase().trim(),
+);
+const logger: Logger = debugEnabled
+  ? getDefaultLogger()
+  : { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+
+export const TelemetryEvent = {
+  METHOD_CALL: "method-call",
+  EXCEPTION_RAISED: "exception-raised",
+} as const;
+
+export type TelemetryEvent = (typeof TelemetryEvent)[keyof typeof TelemetryEvent];
+
+interface QueuedEvent {
+  timestamp_ms: number;
+  event_type: TelemetryEvent;
+  data: Record<string, unknown>;
+}
+
+export abstract class BaseTelemetryClient {
+  protected sdkHeaders: Record<string, string> = {};
+
+  abstract sendEvent(event: TelemetryEvent, data?: Record<string, unknown>): void;
+
+  setSdkHeaders(headers: Record<string, string>) {
+    this.sdkHeaders = headers;
+  }
+
+  trackClass(onlyExceptions = new Set<string>()) {
+    const client = this;
+    return <T extends abstract new (...args: unknown[]) => object>(
+      target: T,
+      _context: ClassDecoratorContext<T>,
+    ): T => {
+      // TODO: Wrap public methods.
+
+      // Wrap the constructor
+      const trackConstructorCalls = !onlyExceptions.has("constructor");
+      class Wrapped extends (target as unknown as new (...args: unknown[]) => object) {
+        constructor(...args: unknown[]) {
+          try {
+            if (trackConstructorCalls) {
+              client.sendEvent(TelemetryEvent.METHOD_CALL, {
+                function_name: `${target.name}.constructor`,
+              });
+            }
+            super(...args);
+          } catch (e) {
+            client.sendEvent(TelemetryEvent.EXCEPTION_RAISED, {
+              function_name: `${target.name}.constructor`,
+              exception: String(e),
+            });
+            throw e;
+          }
+        }
+      }
+      Object.defineProperty(Wrapped, "name", { value: target.name });
+      return Wrapped as unknown as T;
+    };
+  }
+}
+
+export class TelemetryClient extends BaseTelemetryClient {
+  private queue: QueuedEvent[] = [];
+  private timer: ReturnType<typeof setInterval>;
+  private readonly baseUrl: string;
+
+  constructor() {
+    super();
+    this.baseUrl = getBaseUrl();
+    this.timer = setInterval(() => {
+      void this.uploadEvents();
+    }, UPLOAD_INTERVAL_MS);
+    // Don't prevent the process from exiting naturally
+    this.timer.unref();
+
+    // Trigger an immediate upload on uncaught exception.
+    process.on("uncaughtExceptionMonitor", async () => {
+      await this.uploadEvents();
+    });
+  }
+
+  sendEvent(event: TelemetryEvent, data: Record<string, unknown> = {}) {
+    logger.debug(`Sending telemetry event ${event}, ${JSON.stringify(data)}`);
+    if (this.queue.length >= QUEUE_MAX_SIZE) return;
+    this.queue.push({ timestamp_ms: Date.now(), event_type: event, data });
+  }
+
+  private async uploadEvents() {
+    const payload = this.queue.splice(0);
+    if (!payload.length) {
+      logger.debug("No events to upload.");
+      return;
+    }
+    logger.debug(`Uploading ${payload.length} telemetry events.`);
+    try {
+      const url = new URL("v1/upload-telemetry", this.baseUrl);
+      await fetchOrThrow(url, {
+        method: "POST",
+        headers: { ...this.sdkHeaders, "Content-Type": "application/json" },
+        body: JSON.stringify({ events: payload }),
+      });
+    } catch (e) {
+      logger.error(`Telemetry upload failed: ${String(e)}`);
+    }
+  }
+}
+
+export class NoOpTelemetryClient extends BaseTelemetryClient {
+  sendEvent(_event: TelemetryEvent, _data?: Record<string, unknown>) {}
+}
+
+const isDisabled = ["yes", "true"].includes(
+  (process.env.GUAVA_DISABLE_TELEMETRY ?? "false").toLowerCase().trim(),
+);
+export const telemetryClient: BaseTelemetryClient = isDisabled
+  ? new NoOpTelemetryClient()
+  : new TelemetryClient();

package/src/utils.ts

@@ -0,0 +1,32 @@
+export const DEFAULT_BASE_URL = "https://guava-dev.gridspace.com/";
+
+export function getBaseUrl(): string {
+  return process.env.GUAVA_BASE_URL ?? DEFAULT_BASE_URL;
+}
+
+class HttpStatusError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: string,
+    public readonly response: Response,
+  ) {
+    super(`HTTP ${status} ${statusText}${body ? ` — ${body}` : ""}`);
+    this.name = "HttpStatusError";
+  }
+}
+
+export async function fetchOrThrow(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  // biome-ignore lint: The wrapper must call fetch.
+  const res = await fetch(input, init);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new HttpStatusError(res.status, res.statusText, body, res);
+  }
+
+  return res;
+}

package/dist/examples/thai_palace.js

@@ -1,79 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import * as guava from "../src/index.js";
-import { getConsoleLogger } from "../src/logging.js";
-import { IntentRecognizer } from "../src/helpers/openai.js";
-class ThaiPalaceCallController extends guava.CallController {
-    constructor(logger) {
-        super(logger);
-        this.choices = ["restaurant waitlist", "anything else"];
-        this.intentRecognizer = new IntentRecognizer(this.choices, logger);
-        this.setPersona({
-            organizationName: "Thai Palace",
-        });
-    }
-    onIncomingCall(from_number) {
-        const _super = Object.create(null, {
-            onIncomingCall: { get: () => super.onIncomingCall }
-        });
-        return __awaiter(this, void 0, void 0, function* () {
-            yield _super.onIncomingCall.call(this, from_number);
-            this.acceptCall();
-            this.setThaiPalaceTask();
-        });
-    }
-    setThaiPalaceTask() {
-        this.setTask({
-            objective: `You are a virtual assistant for a restaurant called Thai Palace.
- Your job is to add callers to the waitlist.`,
-            checklist: [
-                {
-                    item_type: "field",
-                    key: "caller_name",
-                    field_type: "text",
-                    description: "The name to be added to the waitlist",
-                },
-                {
-                    item_type: "field",
-                    key: "party_size",
-                    field_type: "integer",
-                    description: "The number of people attending",
-                },
-                {
-                    item_type: "field",
-                    key: "phone_number",
-                    field_type: "text",
-                    description: "phone number to text when table is ready",
-                },
-                "Read the phone number back to the caller to make sure you got it right",
-            ],
-        }, () => this.hangup());
-    }
-    onIntent(intent) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const choice = yield this.intentRecognizer.classify(intent);
-            this.logger.info(`Chosen intent: ${choice}`);
-            if (choice == "restaurant waitlist") {
-                this.setThaiPalaceTask();
-                return null;
-            }
-            else {
-                return "Tell them we only handle waitlist additions at this number.";
-            }
-        });
-    }
-}
-export function run(_args) {
-    new guava.Client().listenInbound({ agent_number: process.env.GUAVA_AGENT_NUMBER }, (logger) => new ThaiPalaceCallController(getConsoleLogger("debug")));
-}
-if (import.meta.main) {
-    run([]);
-}
-//# sourceMappingURL=thai_palace.js.map

package/dist/examples/thai_palace.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"thai_palace.js","sourceRoot":"","sources":["../../examples/thai_palace.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,wBAAyB,SAAQ,KAAK,CAAC,cAAc;IAGzD,YAAY,MAAc;QACxB,KAAK,CAAC,MAAM,CAAC,CAAC;QAHR,YAAO,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAU,CAAC;QAIlE,IAAI,CAAC,gBAAgB,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACnE,IAAI,CAAC,UAAU,CAAC;YACd,gBAAgB,EAAE,aAAa;SAChC,CAAC,CAAC;IACL,CAAC;IAEc,cAAc,CAAC,WAAoB;;;;;YAChD,MAAM,OAAM,cAAc,YAAC,WAAW,CAAC,CAAC;YACxC,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;KAAA;IAED,iBAAiB;QACf,IAAI,CAAC,OAAO,CACV;YACE,SAAS,EAAE;6CAC0B;YACrC,SAAS,EAAE;gBACT;oBACE,SAAS,EAAE,OAAO;oBAClB,GAAG,EAAE,aAAa;oBAClB,UAAU,EAAE,MAAM;oBAClB,WAAW,EAAE,sCAAsC;iBACpD;gBACD;oBACE,SAAS,EAAE,OAAO;oBAClB,GAAG,EAAE,YAAY;oBACjB,UAAU,EAAE,SAAS;oBACrB,WAAW,EAAE,gCAAgC;iBAC9C;gBACD;oBACE,SAAS,EAAE,OAAO;oBAClB,GAAG,EAAE,cAAc;oBACnB,UAAU,EAAE,MAAM;oBAClB,WAAW,EAAE,0CAA0C;iBACxD;gBACD,wEAAwE;aACzE;SACF,EACD,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CACpB,CAAC;IACJ,CAAC;IAEc,QAAQ,CAAC,MAAc;;YACpC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;YAC7C,IAAI,MAAM,IAAI,qBAAqB,EAAE,CAAC;gBACpC,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACzB,OAAO,IAAI,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,OAAO,6DAA6D,CAAC;YACvE,CAAC;QACH,CAAC;KAAA;CACF;AAED,MAAM,UAAU,GAAG,CAAC,KAAe;IACjC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,aAAa,CAC9B,EAAE,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAmB,EAAE,EACjD,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,wBAAwB,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CACpE,CAAC;AACJ,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,CAAC;AACV,CAAC"}