@guckdev/browser 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# Guck (Browser SDK)
+
+Browser SDK for emitting Guck telemetry to a local MCP HTTP ingest endpoint.
+
+## Usage
+
+Start the MCP server with HTTP ingest enabled:
+
+```sh
+guck mcp --http-port 7331
+```
+
+Create a client and emit events:
+
+```ts
+import { createBrowserClient } from "@guckdev/browser";
+
+const client = createBrowserClient({
+  endpoint: "http://localhost:7331/guck/emit",
+  service: "web-ui",
+  sessionId: "dev-1",
+});
+
+await client.emit({ message: "hello from the browser" });
+```
+
+## Auto-capture console + errors
+
+```ts
+const { stop } = client.installAutoCapture();
+
+console.error("boom");
+
+// call stop() to restore console and listeners
+stop();
+```
+
+Notes:
+- The HTTP ingest endpoint is CORS-enabled by default.
+- If your page is served over HTTPS, posting to an HTTP localhost endpoint may be blocked by mixed-content rules.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+type GuckLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+type GuckSource = {
+    kind: "sdk";
+    file?: string;
+    line?: number;
+};
+type GuckEvent = {
+    id: string;
+    ts: string;
+    level: GuckLevel;
+    type: string;
+    service: string;
+    run_id: string;
+    session_id?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    trace_id?: string;
+    span_id?: string;
+    source?: GuckSource;
+};
+type BrowserClientOptions = {
+    endpoint: string;
+    service?: string;
+    sessionId?: string;
+    runId?: string;
+    tags?: Record<string, string>;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+    keepalive?: boolean;
+    fetch?: typeof fetch;
+    onError?: (error: unknown) => void;
+};
+type AutoCaptureOptions = {
+    captureConsole?: boolean;
+    captureErrors?: boolean;
+};
+type BrowserClient = {
+    emit: (event: Partial<GuckEvent>) => Promise<void>;
+    installAutoCapture: (opts?: AutoCaptureOptions) => {
+        stop: () => void;
+    };
+};
+export declare const createBrowserClient: (options: BrowserClientOptions) => BrowserClient;
+export type { GuckEvent, GuckLevel, BrowserClientOptions, AutoCaptureOptions, BrowserClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,KAAK,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzE,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,kBAAkB,EAAE,CAAC,IAAI,CAAC,EAAE,kBAAkB,KAAK;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACzE,CAAC;AAgIF,eAAO,MAAM,mBAAmB,YAAa,oBAAoB,KAAG,aAoJnE,CAAC;AAEF,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,246 @@
+const normalizeLevel = (level) => {
+    if (!level) {
+        return "info";
+    }
+    const lower = level.toLowerCase();
+    if (lower === "trace" ||
+        lower === "debug" ||
+        lower === "info" ||
+        lower === "warn" ||
+        lower === "error" ||
+        lower === "fatal") {
+        return lower;
+    }
+    return "info";
+};
+const randomId = () => {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return crypto.randomUUID();
+    }
+    return `guck-${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+};
+const serializeError = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            stack: value.stack,
+        };
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return {
+            name: typeof record.name === "string" ? record.name : undefined,
+            message: typeof record.message === "string" ? record.message : undefined,
+            stack: typeof record.stack === "string" ? record.stack : undefined,
+        };
+    }
+    return { message: String(value) };
+};
+const toSerializable = (value, seen) => {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (value instanceof Error) {
+        return serializeError(value);
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (typeof value === "function") {
+        return `[Function${value.name ? ` ${value.name}` : ""}]`;
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (seen.has(value)) {
+        return "[Circular]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((entry) => toSerializable(entry, seen));
+    }
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        output[key] = toSerializable(entry, seen);
+    }
+    return output;
+};
+const formatArg = (value) => {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value.stack ?? value.message;
+    }
+    try {
+        return JSON.stringify(toSerializable(value, new WeakSet())) ?? "";
+    }
+    catch {
+        return String(value);
+    }
+};
+const formatArgs = (args) => {
+    if (!args.length) {
+        return "";
+    }
+    return args.map((arg) => formatArg(arg)).join(" ");
+};
+const mapConsoleLevel = (method) => {
+    switch (method) {
+        case "trace":
+            return "trace";
+        case "debug":
+            return "debug";
+        case "warn":
+            return "warn";
+        case "error":
+            return "error";
+        case "info":
+        case "log":
+        default:
+            return "info";
+    }
+};
+export const createBrowserClient = (options) => {
+    if (!options?.endpoint) {
+        throw new Error("[guck] endpoint is required");
+    }
+    const endpoint = options.endpoint;
+    const service = options.service ?? "guck";
+    const sessionId = options.sessionId;
+    const runId = options.runId ?? randomId();
+    const tags = options.tags;
+    const headers = options.headers ?? {};
+    const enabled = options.enabled ?? true;
+    const keepalive = options.keepalive ?? true;
+    const fetcher = options.fetch ?? fetch;
+    const onError = options.onError;
+    const emit = async (input) => {
+        if (!enabled) {
+            return;
+        }
+        const event = {
+            id: input.id ?? randomId(),
+            ts: input.ts ?? new Date().toISOString(),
+            level: normalizeLevel(input.level),
+            type: input.type ?? "log",
+            service: input.service ?? service,
+            run_id: input.run_id ?? runId,
+            session_id: input.session_id ?? sessionId,
+            message: input.message,
+            data: input.data,
+            tags: input.tags ?? tags,
+            trace_id: input.trace_id,
+            span_id: input.span_id,
+            source: input.source ?? { kind: "sdk" },
+        };
+        const response = await fetcher(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...headers,
+            },
+            body: JSON.stringify(event),
+            keepalive,
+        });
+        if (!response.ok) {
+            throw new Error(`[guck] HTTP ${response.status} ${response.statusText}`);
+        }
+    };
+    const installAutoCapture = (opts = {}) => {
+        const captureConsole = opts.captureConsole ?? true;
+        const captureErrors = opts.captureErrors ?? true;
+        const targetWindow = typeof window === "undefined" ? undefined : window;
+        if (!captureConsole && !captureErrors) {
+            return { stop: () => { } };
+        }
+        const originals = {};
+        const listeners = [];
+        const safeEmit = (payload) => {
+            void emit(payload).catch((error) => {
+                if (onError) {
+                    onError(error);
+                }
+            });
+        };
+        if (captureConsole) {
+            const methods = ["log", "info", "warn", "error", "debug", "trace"];
+            for (const method of methods) {
+                const original = console[method];
+                originals[method] = original;
+                console[method] = (...args) => {
+                    original.apply(console, args);
+                    safeEmit({
+                        type: "console",
+                        level: mapConsoleLevel(method),
+                        message: formatArgs(args),
+                        data: { args: args.map((arg) => toSerializable(arg, new WeakSet())) },
+                    });
+                };
+            }
+        }
+        if (captureErrors && targetWindow) {
+            const errorListener = (event) => {
+                const message = event.message || event.error?.message || "";
+                const source = {
+                    kind: "sdk",
+                    file: event.filename || undefined,
+                    line: typeof event.lineno === "number" ? event.lineno : undefined,
+                };
+                safeEmit({
+                    type: "window.error",
+                    level: "error",
+                    message,
+                    source,
+                    data: {
+                        filename: event.filename || undefined,
+                        lineno: typeof event.lineno === "number" ? event.lineno : undefined,
+                        colno: typeof event.colno === "number" ? event.colno : undefined,
+                        error: serializeError(event.error),
+                    },
+                });
+            };
+            targetWindow.addEventListener("error", errorListener);
+            listeners.push(() => targetWindow.removeEventListener("error", errorListener));
+            const rejectionListener = (event) => {
+                const reason = event.reason;
+                const message = typeof reason === "string"
+                    ? reason
+                    : reason instanceof Error
+                        ? reason.message
+                        : formatArg(reason);
+                safeEmit({
+                    type: "unhandledrejection",
+                    level: "error",
+                    message,
+                    data: {
+                        reason: toSerializable(reason, new WeakSet()),
+                    },
+                });
+            };
+            targetWindow.addEventListener("unhandledrejection", rejectionListener);
+            listeners.push(() => targetWindow.removeEventListener("unhandledrejection", rejectionListener));
+        }
+        const stop = () => {
+            for (const method of Object.keys(originals)) {
+                const original = originals[method];
+                if (original) {
+                    console[method] = original;
+                }
+            }
+            for (const remove of listeners) {
+                remove();
+            }
+        };
+        return { stop };
+    };
+    return { emit, installAutoCapture };
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@guckdev/browser",
+  "version": "0.1.0",
+  "description": "Guck browser SDK",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tillkolter/guck-mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "test": "pnpm run build && node --test test/*.test.js",
+    "prepare": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,324 @@
+type GuckLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+type GuckSource = {
+  kind: "sdk";
+  file?: string;
+  line?: number;
+};
+
+type GuckEvent = {
+  id: string;
+  ts: string;
+  level: GuckLevel;
+  type: string;
+  service: string;
+  run_id: string;
+  session_id?: string;
+  message?: string;
+  data?: Record<string, unknown>;
+  tags?: Record<string, string>;
+  trace_id?: string;
+  span_id?: string;
+  source?: GuckSource;
+};
+
+type BrowserClientOptions = {
+  endpoint: string;
+  service?: string;
+  sessionId?: string;
+  runId?: string;
+  tags?: Record<string, string>;
+  headers?: Record<string, string>;
+  enabled?: boolean;
+  keepalive?: boolean;
+  fetch?: typeof fetch;
+  onError?: (error: unknown) => void;
+};
+
+type AutoCaptureOptions = {
+  captureConsole?: boolean;
+  captureErrors?: boolean;
+};
+
+type BrowserClient = {
+  emit: (event: Partial<GuckEvent>) => Promise<void>;
+  installAutoCapture: (opts?: AutoCaptureOptions) => { stop: () => void };
+};
+
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug" | "trace";
+
+type ErrorPayload = {
+  name?: string;
+  message?: string;
+  stack?: string;
+};
+
+const normalizeLevel = (level?: string): GuckLevel => {
+  if (!level) {
+    return "info";
+  }
+  const lower = level.toLowerCase();
+  if (
+    lower === "trace" ||
+    lower === "debug" ||
+    lower === "info" ||
+    lower === "warn" ||
+    lower === "error" ||
+    lower === "fatal"
+  ) {
+    return lower;
+  }
+  return "info";
+};
+
+const randomId = (): string => {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+  return `guck-${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+};
+
+const serializeError = (value: unknown): ErrorPayload | undefined => {
+  if (!value) {
+    return undefined;
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return {
+      name: typeof record.name === "string" ? record.name : undefined,
+      message: typeof record.message === "string" ? record.message : undefined,
+      stack: typeof record.stack === "string" ? record.stack : undefined,
+    };
+  }
+  return { message: String(value) };
+};
+
+const toSerializable = (value: unknown, seen: WeakSet<object>): unknown => {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (value instanceof Error) {
+    return serializeError(value);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (typeof value === "function") {
+    return `[Function${value.name ? ` ${value.name}` : ""}]`;
+  }
+  if (typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return "[Circular]";
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((entry) => toSerializable(entry, seen));
+  }
+  const output: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    output[key] = toSerializable(entry, seen);
+  }
+  return output;
+};
+
+const formatArg = (value: unknown): string => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Error) {
+    return value.stack ?? value.message;
+  }
+  try {
+    return JSON.stringify(toSerializable(value, new WeakSet<object>())) ?? "";
+  } catch {
+    return String(value);
+  }
+};
+
+const formatArgs = (args: unknown[]): string => {
+  if (!args.length) {
+    return "";
+  }
+  return args.map((arg) => formatArg(arg)).join(" ");
+};
+
+const mapConsoleLevel = (method: ConsoleMethod): GuckLevel => {
+  switch (method) {
+    case "trace":
+      return "trace";
+    case "debug":
+      return "debug";
+    case "warn":
+      return "warn";
+    case "error":
+      return "error";
+    case "info":
+    case "log":
+    default:
+      return "info";
+  }
+};
+
+export const createBrowserClient = (options: BrowserClientOptions): BrowserClient => {
+  if (!options?.endpoint) {
+    throw new Error("[guck] endpoint is required");
+  }
+  const endpoint = options.endpoint;
+  const service = options.service ?? "guck";
+  const sessionId = options.sessionId;
+  const runId = options.runId ?? randomId();
+  const tags = options.tags;
+  const headers = options.headers ?? {};
+  const enabled = options.enabled ?? true;
+  const keepalive = options.keepalive ?? true;
+  const fetcher = options.fetch ?? fetch;
+  const onError = options.onError;
+
+  const emit = async (input: Partial<GuckEvent>): Promise<void> => {
+    if (!enabled) {
+      return;
+    }
+    const event: GuckEvent = {
+      id: input.id ?? randomId(),
+      ts: input.ts ?? new Date().toISOString(),
+      level: normalizeLevel(input.level),
+      type: input.type ?? "log",
+      service: input.service ?? service,
+      run_id: input.run_id ?? runId,
+      session_id: input.session_id ?? sessionId,
+      message: input.message,
+      data: input.data,
+      tags: input.tags ?? tags,
+      trace_id: input.trace_id,
+      span_id: input.span_id,
+      source: input.source ?? { kind: "sdk" },
+    };
+
+    const response = await fetcher(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(event),
+      keepalive,
+    });
+
+    if (!response.ok) {
+      throw new Error(`[guck] HTTP ${response.status} ${response.statusText}`);
+    }
+  };
+
+  const installAutoCapture = (opts: AutoCaptureOptions = {}): { stop: () => void } => {
+    const captureConsole = opts.captureConsole ?? true;
+    const captureErrors = opts.captureErrors ?? true;
+    const targetWindow = typeof window === "undefined" ? undefined : window;
+
+    if (!captureConsole && !captureErrors) {
+      return { stop: () => {} };
+    }
+
+    const originals: Partial<Record<ConsoleMethod, (...args: unknown[]) => void>> = {};
+    const listeners: Array<() => void> = [];
+
+    const safeEmit = (payload: Partial<GuckEvent>) => {
+      void emit(payload).catch((error) => {
+        if (onError) {
+          onError(error);
+        }
+      });
+    };
+
+    if (captureConsole) {
+      const methods: ConsoleMethod[] = ["log", "info", "warn", "error", "debug", "trace"];
+      for (const method of methods) {
+        const original = console[method];
+        originals[method] = original;
+        console[method] = (...args: unknown[]) => {
+          original.apply(console, args);
+          safeEmit({
+            type: "console",
+            level: mapConsoleLevel(method),
+            message: formatArgs(args),
+            data: { args: args.map((arg) => toSerializable(arg, new WeakSet<object>())) },
+          });
+        };
+      }
+    }
+
+    if (captureErrors && targetWindow) {
+      const errorListener = (event: ErrorEvent) => {
+        const message = event.message || event.error?.message || "";
+        const source: GuckSource = {
+          kind: "sdk",
+          file: event.filename || undefined,
+          line: typeof event.lineno === "number" ? event.lineno : undefined,
+        };
+        safeEmit({
+          type: "window.error",
+          level: "error",
+          message,
+          source,
+          data: {
+            filename: event.filename || undefined,
+            lineno: typeof event.lineno === "number" ? event.lineno : undefined,
+            colno: typeof event.colno === "number" ? event.colno : undefined,
+            error: serializeError(event.error),
+          },
+        });
+      };
+      targetWindow.addEventListener("error", errorListener);
+      listeners.push(() => targetWindow.removeEventListener("error", errorListener));
+
+      const rejectionListener = (event: PromiseRejectionEvent) => {
+        const reason = event.reason;
+        const message =
+          typeof reason === "string"
+            ? reason
+            : reason instanceof Error
+              ? reason.message
+              : formatArg(reason);
+        safeEmit({
+          type: "unhandledrejection",
+          level: "error",
+          message,
+          data: {
+            reason: toSerializable(reason, new WeakSet<object>()),
+          },
+        });
+      };
+      targetWindow.addEventListener("unhandledrejection", rejectionListener);
+      listeners.push(() => targetWindow.removeEventListener("unhandledrejection", rejectionListener));
+    }
+
+    const stop = () => {
+      for (const method of Object.keys(originals) as ConsoleMethod[]) {
+        const original = originals[method];
+        if (original) {
+          console[method] = original;
+        }
+      }
+      for (const remove of listeners) {
+        remove();
+      }
+    };
+
+    return { stop };
+  };
+
+  return { emit, installAutoCapture };
+};
+
+export type { GuckEvent, GuckLevel, BrowserClientOptions, AutoCaptureOptions, BrowserClient };

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "lib": ["DOM", "ES2022"],
+    "types": []
+  },
+  "include": ["src/**/*.ts"]
+}