neatlogs 1.0.6 → 1.0.9

package/dist/browser.cjs

@@ -0,0 +1,121 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser.ts
+var browser_exports = {};
+__export(browser_exports, {
+  Neatlogs: () => Neatlogs,
+  default: () => browser_default
+});
+module.exports = __toCommonJS(browser_exports);
+var DEFAULT_ENDPOINT = "https://staging-cloud.neatlogs.com";
+var Neatlogs = class {
+  apiKey;
+  project;
+  baseUrl;
+  enabled;
+  onError;
+  constructor(opts) {
+    if (!opts || !opts.apiKey) {
+      throw new Error("Neatlogs: apiKey is required");
+    }
+    this.apiKey = opts.apiKey;
+    this.project = opts.project;
+    const endpoint = opts.endpoint || DEFAULT_ENDPOINT;
+    this.baseUrl = safeOrigin(endpoint) || DEFAULT_ENDPOINT;
+    this.enabled = opts.enabled !== false;
+    this.onError = opts.onError || ((err) => {
+      if (typeof console !== "undefined") console.warn("[neatlogs] send failed:", err);
+    });
+  }
+  /** Send a full (optionally nested) trace. Returns the backend's result. */
+  async trace(trace) {
+    return this.post(trace);
+  }
+  /** Send a single AI interaction as a one-span trace (kind defaults to LLM). */
+  async trackAI(ai) {
+    const { name, kind, ...rest } = ai;
+    return this.post({ name, kind: kind ?? "LLM", ...rest });
+  }
+  /**
+   * Begin a trace you'll complete later (e.g. streaming). Buffers the partial
+   * input; call `.finish()` with the final output/tokens to send it. Nothing is
+   * sent until `finish()`.
+   */
+  startTrace(initial) {
+    const startedAt = nowIso();
+    return {
+      finish: (final) => {
+        const merged = { ...initial, ...final ?? {} };
+        const { name, kind, ...rest } = merged;
+        return this.post({
+          name,
+          kind: kind ?? "LLM",
+          start: startedAt,
+          end: nowIso(),
+          ...rest
+        });
+      }
+    };
+  }
+  /** POST the trace JSON to the backend's /v1/trace endpoint. */
+  async post(body) {
+    if (!this.enabled) return { ok: true };
+    const payload = this.project && body.project === void 0 ? { ...body, project: this.project } : body;
+    try {
+      const res = await fetch(`${this.baseUrl}/v1/trace`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(payload),
+        // keepalive lets the request survive a page unload (e.g. on navigation).
+        keepalive: true
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const result = { ok: false, error: `HTTP ${res.status}${text ? `: ${text}` : ""}` };
+        this.onError(new Error(result.error));
+        return result;
+      }
+      const data = await res.json().catch(() => ({}));
+      return { ok: true, trace_id: data.trace_id, spans: data.spans };
+    } catch (err) {
+      this.onError(err);
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+};
+function safeOrigin(endpoint) {
+  try {
+    return new URL(endpoint).origin;
+  } catch {
+    return null;
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var browser_default = Neatlogs;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Neatlogs
+});
+//# sourceMappingURL=browser.cjs.map

package/dist/browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["/**\n * Neatlogs Browser SDK — `neatlogs/browser`\n *\n * A minimal, browser-safe client for sending traces to Neatlogs from web apps.\n * It has ZERO dependencies (no OpenTelemetry, no Node APIs) — only `fetch` — so\n * it bundles cleanly into front-end apps. It POSTs plain JSON to the backend's\n * simple trace endpoint (`/v1/trace`); the backend generates trace/span ids,\n * builds the hierarchy from nesting, infers cost from model+tokens, and pushes\n * through the normal pipeline. Nothing here streams OTLP.\n *\n * Usage:\n *   import { Neatlogs } from 'neatlogs/browser';\n *   const nl = new Neatlogs({ apiKey: 'nl_...' });\n *\n *   // one-shot AI interaction\n *   await nl.trackAI({ name: 'chat', model: 'gpt-4o', input, output,\n *                      tokens: { prompt: 10, completion: 5 } });\n *\n *   // a full nested trace (same shape the backend's POST /v1/trace accepts)\n *   await nl.trace({ name: 'support-chat', children: [\n *     { name: 'retrieve', query, documents },\n *     { name: 'answer', model: 'gpt-4o', input, output },\n *   ]});\n *\n *   // streaming: open, accumulate, finish\n *   const t = nl.startTrace({ name: 'chat', model: 'gpt-4o', input });\n *   t.finish({ output: full, tokens: { prompt, completion } });\n */\n\nconst DEFAULT_ENDPOINT = \"https://staging-cloud.neatlogs.com\";\n\n// --- the simple trace shape the backend (/v1/trace) accepts --------------------\n// Mirrors the server-side SimpleSpan; kept local so this file has no imports.\n\nexport interface NeatlogsLog {\n  level?: string;\n  message: string;\n  timestamp?: string;\n}\n\n/**\n * Span kinds the backend accepts (the canonical set). `kind` is optional — when\n * omitted the backend infers it from the fields present.\n */\nexport type NeatlogsKind =\n  | \"WORKFLOW\" | \"AGENT\" | \"CHAIN\" | \"TOOL\" | \"RETRIEVER\" | \"RERANKER\"\n  | \"EMBEDDING\" | \"LLM\" | \"GUARDRAIL\" | \"MCP_TOOL\" | \"TASK\"\n  | \"VECTOR_STORE\" | \"EVALUATOR\" | \"HTTP\";\n\nexport interface NeatlogsSpan {\n  name: string;\n  /** Optional — the backend infers the kind from fields when omitted. */\n  kind?: NeatlogsKind | string;\n  input?: unknown;\n  output?: unknown;\n  model?: string;\n  tokens?: { prompt?: number; completion?: number; total?: number };\n  query?: unknown;\n  documents?: unknown;\n  tool_name?: string;\n  passed?: boolean;\n  score?: number;\n  metadata?: Record<string, unknown>;\n  status?: string;\n  error?: string;\n  start?: string;\n  end?: string;\n  /** Simplest way to record latency — the backend derives end from start + this. */\n  duration_ms?: number;\n  /**\n   * Full canonical-attribute escape hatch. Send ANY neatlogs.* attribute the SDK\n   * supports — e.g. { \"neatlogs.llm.temperature\": 0.7, \"neatlogs.agent.role\":\n   * \"researcher\", \"neatlogs.tool.parameters\": {...} }. Non-canonical keys are\n   * dropped server-side. The fields above (model/tokens/query/...) are shortcuts\n   * for the common ones; explicit `attributes` win on conflict.\n   */\n  attributes?: Record<string, unknown>;\n  children?: NeatlogsSpan[];\n  logs?: NeatlogsLog[];\n}\n\n/** The root of a trace = a span node (its `name` becomes the workflow name). */\nexport type NeatlogsTrace = NeatlogsSpan;\n\nexport interface NeatlogsOptions {\n  /**\n   * Your Neatlogs WRITE key (`nlw_…`) — an ingest-only credential safe to embed in\n   * browser code. (A full project key also works but should not be exposed client-side,\n   * since it can read data.)\n   */\n  apiKey: string;\n  /**\n   * Project NAME to ingest into. REQUIRED when using a write key (the key identifies\n   * you, not a project). Sent as the root `project` field on every trace. Ignored for\n   * a full project key (already project-scoped).\n   */\n  project?: string;\n  /** Backend base URL. Defaults to the same host the SDKs use. */\n  endpoint?: string;\n  /** Set false to validate calls without sending (default true). */\n  enabled?: boolean;\n  /** Called on transport errors instead of throwing (default: console.warn). */\n  onError?: (err: unknown) => void;\n}\n\nexport interface TrackResult {\n  ok: boolean;\n  trace_id?: string;\n  spans?: number;\n  error?: string;\n}\n\n/** Shorthand for a single AI interaction → a one-span trace. */\nexport interface TrackAIInput {\n  name: string;\n  input?: unknown;\n  output?: unknown;\n  model?: string;\n  tokens?: { prompt?: number; completion?: number; total?: number };\n  metadata?: Record<string, unknown>;\n  duration_ms?: number;\n  /** Any canonical neatlogs.* attributes (see NeatlogsSpan.attributes). */\n  attributes?: Record<string, unknown>;\n  /** Override the inferred kind (defaults to LLM for trackAI). */\n  kind?: NeatlogsKind | string;\n}\n\nexport class Neatlogs {\n  private readonly apiKey: string;\n  private readonly project?: string;\n  private readonly baseUrl: string;\n  private readonly enabled: boolean;\n  private readonly onError: (err: unknown) => void;\n\n  constructor(opts: NeatlogsOptions) {\n    if (!opts || !opts.apiKey) {\n      throw new Error(\"Neatlogs: apiKey is required\");\n    }\n    this.apiKey = opts.apiKey;\n    this.project = opts.project;\n    // Use the origin of the configured endpoint (same convention as the Node SDK),\n    // so passing a full /v1/traces URL or a bare host both work.\n    const endpoint = opts.endpoint || DEFAULT_ENDPOINT;\n    this.baseUrl = safeOrigin(endpoint) || DEFAULT_ENDPOINT;\n    this.enabled = opts.enabled !== false;\n    this.onError =\n      opts.onError ||\n      ((err) => {\n        // eslint-disable-next-line no-console\n        if (typeof console !== \"undefined\") console.warn(\"[neatlogs] send failed:\", err);\n      });\n  }\n\n  /** Send a full (optionally nested) trace. Returns the backend's result. */\n  async trace(trace: NeatlogsTrace): Promise<TrackResult> {\n    return this.post(trace);\n  }\n\n  /** Send a single AI interaction as a one-span trace (kind defaults to LLM). */\n  async trackAI(ai: TrackAIInput): Promise<TrackResult> {\n    const { name, kind, ...rest } = ai;\n    return this.post({ name, kind: kind ?? \"LLM\", ...rest });\n  }\n\n  /**\n   * Begin a trace you'll complete later (e.g. streaming). Buffers the partial\n   * input; call `.finish()` with the final output/tokens to send it. Nothing is\n   * sent until `finish()`.\n   */\n  startTrace(initial: TrackAIInput): {\n    finish: (final?: Partial<TrackAIInput>) => Promise<TrackResult>;\n  } {\n    const startedAt = nowIso();\n    return {\n      finish: (final?: Partial<TrackAIInput>) => {\n        const merged: TrackAIInput = { ...initial, ...(final ?? {}) };\n        const { name, kind, ...rest } = merged;\n        return this.post({\n          name,\n          kind: kind ?? \"LLM\",\n          start: startedAt,\n          end: nowIso(),\n          ...rest,\n        });\n      },\n    };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    if (!this.enabled) return { ok: true };\n    // Inject the configured project name into the root (required for write keys;\n    // ignored server-side for full project keys). A `project` already on the body wins.\n    const payload =\n      this.project && (body as any).project === undefined\n        ? { ...body, project: this.project }\n        : body;\n    try {\n      const res = await fetch(`${this.baseUrl}/v1/trace`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: `Bearer ${this.apiKey}`,\n        },\n        body: JSON.stringify(payload),\n        // keepalive lets the request survive a page unload (e.g. on navigation).\n        keepalive: true,\n      });\n      if (!res.ok) {\n        const text = await res.text().catch(() => \"\");\n        const result = { ok: false, error: `HTTP ${res.status}${text ? `: ${text}` : \"\"}` };\n        this.onError(new Error(result.error));\n        return result;\n      }\n      const data = (await res.json().catch(() => ({}))) as Partial<TrackResult>;\n      return { ok: true, trace_id: data.trace_id, spans: data.spans };\n    } catch (err) {\n      // Never throw into the host app over telemetry.\n      this.onError(err);\n      return { ok: false, error: err instanceof Error ? err.message : String(err) };\n    }\n  }\n}\n\n// --- helpers (kept local, no imports) -----------------------------------------\n\nfunction safeOrigin(endpoint: string): string | null {\n  try {\n    return new URL(endpoint).origin;\n  } catch {\n    return null;\n  }\n}\n\nfunction nowIso(): string {\n  return new Date().toISOString();\n}\n\nexport default Neatlogs;\n"],"mappings":"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","names":[]}

package/dist/browser.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Neatlogs Browser SDK — `neatlogs/browser`
+ *
+ * A minimal, browser-safe client for sending traces to Neatlogs from web apps.
+ * It has ZERO dependencies (no OpenTelemetry, no Node APIs) — only `fetch` — so
+ * it bundles cleanly into front-end apps. It POSTs plain JSON to the backend's
+ * simple trace endpoint (`/v1/trace`); the backend generates trace/span ids,
+ * builds the hierarchy from nesting, infers cost from model+tokens, and pushes
+ * through the normal pipeline. Nothing here streams OTLP.
+ *
+ * Usage:
+ *   import { Neatlogs } from 'neatlogs/browser';
+ *   const nl = new Neatlogs({ apiKey: 'nl_...' });
+ *
+ *   // one-shot AI interaction
+ *   await nl.trackAI({ name: 'chat', model: 'gpt-4o', input, output,
+ *                      tokens: { prompt: 10, completion: 5 } });
+ *
+ *   // a full nested trace (same shape the backend's POST /v1/trace accepts)
+ *   await nl.trace({ name: 'support-chat', children: [
+ *     { name: 'retrieve', query, documents },
+ *     { name: 'answer', model: 'gpt-4o', input, output },
+ *   ]});
+ *
+ *   // streaming: open, accumulate, finish
+ *   const t = nl.startTrace({ name: 'chat', model: 'gpt-4o', input });
+ *   t.finish({ output: full, tokens: { prompt, completion } });
+ */
+interface NeatlogsLog {
+    level?: string;
+    message: string;
+    timestamp?: string;
+}
+/**
+ * Span kinds the backend accepts (the canonical set). `kind` is optional — when
+ * omitted the backend infers it from the fields present.
+ */
+type NeatlogsKind = "WORKFLOW" | "AGENT" | "CHAIN" | "TOOL" | "RETRIEVER" | "RERANKER" | "EMBEDDING" | "LLM" | "GUARDRAIL" | "MCP_TOOL" | "TASK" | "VECTOR_STORE" | "EVALUATOR" | "HTTP";
+interface NeatlogsSpan {
+    name: string;
+    /** Optional — the backend infers the kind from fields when omitted. */
+    kind?: NeatlogsKind | string;
+    input?: unknown;
+    output?: unknown;
+    model?: string;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+        total?: number;
+    };
+    query?: unknown;
+    documents?: unknown;
+    tool_name?: string;
+    passed?: boolean;
+    score?: number;
+    metadata?: Record<string, unknown>;
+    status?: string;
+    error?: string;
+    start?: string;
+    end?: string;
+    /** Simplest way to record latency — the backend derives end from start + this. */
+    duration_ms?: number;
+    /**
+     * Full canonical-attribute escape hatch. Send ANY neatlogs.* attribute the SDK
+     * supports — e.g. { "neatlogs.llm.temperature": 0.7, "neatlogs.agent.role":
+     * "researcher", "neatlogs.tool.parameters": {...} }. Non-canonical keys are
+     * dropped server-side. The fields above (model/tokens/query/...) are shortcuts
+     * for the common ones; explicit `attributes` win on conflict.
+     */
+    attributes?: Record<string, unknown>;
+    children?: NeatlogsSpan[];
+    logs?: NeatlogsLog[];
+}
+/** The root of a trace = a span node (its `name` becomes the workflow name). */
+type NeatlogsTrace = NeatlogsSpan;
+interface NeatlogsOptions {
+    /**
+     * Your Neatlogs WRITE key (`nlw_…`) — an ingest-only credential safe to embed in
+     * browser code. (A full project key also works but should not be exposed client-side,
+     * since it can read data.)
+     */
+    apiKey: string;
+    /**
+     * Project NAME to ingest into. REQUIRED when using a write key (the key identifies
+     * you, not a project). Sent as the root `project` field on every trace. Ignored for
+     * a full project key (already project-scoped).
+     */
+    project?: string;
+    /** Backend base URL. Defaults to the same host the SDKs use. */
+    endpoint?: string;
+    /** Set false to validate calls without sending (default true). */
+    enabled?: boolean;
+    /** Called on transport errors instead of throwing (default: console.warn). */
+    onError?: (err: unknown) => void;
+}
+interface TrackResult {
+    ok: boolean;
+    trace_id?: string;
+    spans?: number;
+    error?: string;
+}
+/** Shorthand for a single AI interaction → a one-span trace. */
+interface TrackAIInput {
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    model?: string;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+        total?: number;
+    };
+    metadata?: Record<string, unknown>;
+    duration_ms?: number;
+    /** Any canonical neatlogs.* attributes (see NeatlogsSpan.attributes). */
+    attributes?: Record<string, unknown>;
+    /** Override the inferred kind (defaults to LLM for trackAI). */
+    kind?: NeatlogsKind | string;
+}
+declare class Neatlogs {
+    private readonly apiKey;
+    private readonly project?;
+    private readonly baseUrl;
+    private readonly enabled;
+    private readonly onError;
+    constructor(opts: NeatlogsOptions);
+    /** Send a full (optionally nested) trace. Returns the backend's result. */
+    trace(trace: NeatlogsTrace): Promise<TrackResult>;
+    /** Send a single AI interaction as a one-span trace (kind defaults to LLM). */
+    trackAI(ai: TrackAIInput): Promise<TrackResult>;
+    /**
+     * Begin a trace you'll complete later (e.g. streaming). Buffers the partial
+     * input; call `.finish()` with the final output/tokens to send it. Nothing is
+     * sent until `finish()`.
+     */
+    startTrace(initial: TrackAIInput): {
+        finish: (final?: Partial<TrackAIInput>) => Promise<TrackResult>;
+    };
+    /** POST the trace JSON to the backend's /v1/trace endpoint. */
+    private post;
+}
+
+export { Neatlogs, type NeatlogsKind, type NeatlogsLog, type NeatlogsOptions, type NeatlogsSpan, type NeatlogsTrace, type TrackAIInput, type TrackResult, Neatlogs as default };

package/dist/browser.mjs

@@ -0,0 +1,96 @@
+// src/browser.ts
+var DEFAULT_ENDPOINT = "https://staging-cloud.neatlogs.com";
+var Neatlogs = class {
+  apiKey;
+  project;
+  baseUrl;
+  enabled;
+  onError;
+  constructor(opts) {
+    if (!opts || !opts.apiKey) {
+      throw new Error("Neatlogs: apiKey is required");
+    }
+    this.apiKey = opts.apiKey;
+    this.project = opts.project;
+    const endpoint = opts.endpoint || DEFAULT_ENDPOINT;
+    this.baseUrl = safeOrigin(endpoint) || DEFAULT_ENDPOINT;
+    this.enabled = opts.enabled !== false;
+    this.onError = opts.onError || ((err) => {
+      if (typeof console !== "undefined") console.warn("[neatlogs] send failed:", err);
+    });
+  }
+  /** Send a full (optionally nested) trace. Returns the backend's result. */
+  async trace(trace) {
+    return this.post(trace);
+  }
+  /** Send a single AI interaction as a one-span trace (kind defaults to LLM). */
+  async trackAI(ai) {
+    const { name, kind, ...rest } = ai;
+    return this.post({ name, kind: kind ?? "LLM", ...rest });
+  }
+  /**
+   * Begin a trace you'll complete later (e.g. streaming). Buffers the partial
+   * input; call `.finish()` with the final output/tokens to send it. Nothing is
+   * sent until `finish()`.
+   */
+  startTrace(initial) {
+    const startedAt = nowIso();
+    return {
+      finish: (final) => {
+        const merged = { ...initial, ...final ?? {} };
+        const { name, kind, ...rest } = merged;
+        return this.post({
+          name,
+          kind: kind ?? "LLM",
+          start: startedAt,
+          end: nowIso(),
+          ...rest
+        });
+      }
+    };
+  }
+  /** POST the trace JSON to the backend's /v1/trace endpoint. */
+  async post(body) {
+    if (!this.enabled) return { ok: true };
+    const payload = this.project && body.project === void 0 ? { ...body, project: this.project } : body;
+    try {
+      const res = await fetch(`${this.baseUrl}/v1/trace`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(payload),
+        // keepalive lets the request survive a page unload (e.g. on navigation).
+        keepalive: true
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const result = { ok: false, error: `HTTP ${res.status}${text ? `: ${text}` : ""}` };
+        this.onError(new Error(result.error));
+        return result;
+      }
+      const data = await res.json().catch(() => ({}));
+      return { ok: true, trace_id: data.trace_id, spans: data.spans };
+    } catch (err) {
+      this.onError(err);
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+};
+function safeOrigin(endpoint) {
+  try {
+    return new URL(endpoint).origin;
+  } catch {
+    return null;
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var browser_default = Neatlogs;
+export {
+  Neatlogs,
+  browser_default as default
+};
+//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["/**\n * Neatlogs Browser SDK — `neatlogs/browser`\n *\n * A minimal, browser-safe client for sending traces to Neatlogs from web apps.\n * It has ZERO dependencies (no OpenTelemetry, no Node APIs) — only `fetch` — so\n * it bundles cleanly into front-end apps. It POSTs plain JSON to the backend's\n * simple trace endpoint (`/v1/trace`); the backend generates trace/span ids,\n * builds the hierarchy from nesting, infers cost from model+tokens, and pushes\n * through the normal pipeline. Nothing here streams OTLP.\n *\n * Usage:\n *   import { Neatlogs } from 'neatlogs/browser';\n *   const nl = new Neatlogs({ apiKey: 'nl_...' });\n *\n *   // one-shot AI interaction\n *   await nl.trackAI({ name: 'chat', model: 'gpt-4o', input, output,\n *                      tokens: { prompt: 10, completion: 5 } });\n *\n *   // a full nested trace (same shape the backend's POST /v1/trace accepts)\n *   await nl.trace({ name: 'support-chat', children: [\n *     { name: 'retrieve', query, documents },\n *     { name: 'answer', model: 'gpt-4o', input, output },\n *   ]});\n *\n *   // streaming: open, accumulate, finish\n *   const t = nl.startTrace({ name: 'chat', model: 'gpt-4o', input });\n *   t.finish({ output: full, tokens: { prompt, completion } });\n */\n\nconst DEFAULT_ENDPOINT = \"https://staging-cloud.neatlogs.com\";\n\n// --- the simple trace shape the backend (/v1/trace) accepts --------------------\n// Mirrors the server-side SimpleSpan; kept local so this file has no imports.\n\nexport interface NeatlogsLog {\n  level?: string;\n  message: string;\n  timestamp?: string;\n}\n\n/**\n * Span kinds the backend accepts (the canonical set). `kind` is optional — when\n * omitted the backend infers it from the fields present.\n */\nexport type NeatlogsKind =\n  | \"WORKFLOW\" | \"AGENT\" | \"CHAIN\" | \"TOOL\" | \"RETRIEVER\" | \"RERANKER\"\n  | \"EMBEDDING\" | \"LLM\" | \"GUARDRAIL\" | \"MCP_TOOL\" | \"TASK\"\n  | \"VECTOR_STORE\" | \"EVALUATOR\" | \"HTTP\";\n\nexport interface NeatlogsSpan {\n  name: string;\n  /** Optional — the backend infers the kind from fields when omitted. */\n  kind?: NeatlogsKind | string;\n  input?: unknown;\n  output?: unknown;\n  model?: string;\n  tokens?: { prompt?: number; completion?: number; total?: number };\n  query?: unknown;\n  documents?: unknown;\n  tool_name?: string;\n  passed?: boolean;\n  score?: number;\n  metadata?: Record<string, unknown>;\n  status?: string;\n  error?: string;\n  start?: string;\n  end?: string;\n  /** Simplest way to record latency — the backend derives end from start + this. */\n  duration_ms?: number;\n  /**\n   * Full canonical-attribute escape hatch. Send ANY neatlogs.* attribute the SDK\n   * supports — e.g. { \"neatlogs.llm.temperature\": 0.7, \"neatlogs.agent.role\":\n   * \"researcher\", \"neatlogs.tool.parameters\": {...} }. Non-canonical keys are\n   * dropped server-side. The fields above (model/tokens/query/...) are shortcuts\n   * for the common ones; explicit `attributes` win on conflict.\n   */\n  attributes?: Record<string, unknown>;\n  children?: NeatlogsSpan[];\n  logs?: NeatlogsLog[];\n}\n\n/** The root of a trace = a span node (its `name` becomes the workflow name). */\nexport type NeatlogsTrace = NeatlogsSpan;\n\nexport interface NeatlogsOptions {\n  /**\n   * Your Neatlogs WRITE key (`nlw_…`) — an ingest-only credential safe to embed in\n   * browser code. (A full project key also works but should not be exposed client-side,\n   * since it can read data.)\n   */\n  apiKey: string;\n  /**\n   * Project NAME to ingest into. REQUIRED when using a write key (the key identifies\n   * you, not a project). Sent as the root `project` field on every trace. Ignored for\n   * a full project key (already project-scoped).\n   */\n  project?: string;\n  /** Backend base URL. Defaults to the same host the SDKs use. */\n  endpoint?: string;\n  /** Set false to validate calls without sending (default true). */\n  enabled?: boolean;\n  /** Called on transport errors instead of throwing (default: console.warn). */\n  onError?: (err: unknown) => void;\n}\n\nexport interface TrackResult {\n  ok: boolean;\n  trace_id?: string;\n  spans?: number;\n  error?: string;\n}\n\n/** Shorthand for a single AI interaction → a one-span trace. */\nexport interface TrackAIInput {\n  name: string;\n  input?: unknown;\n  output?: unknown;\n  model?: string;\n  tokens?: { prompt?: number; completion?: number; total?: number };\n  metadata?: Record<string, unknown>;\n  duration_ms?: number;\n  /** Any canonical neatlogs.* attributes (see NeatlogsSpan.attributes). */\n  attributes?: Record<string, unknown>;\n  /** Override the inferred kind (defaults to LLM for trackAI). */\n  kind?: NeatlogsKind | string;\n}\n\nexport class Neatlogs {\n  private readonly apiKey: string;\n  private readonly project?: string;\n  private readonly baseUrl: string;\n  private readonly enabled: boolean;\n  private readonly onError: (err: unknown) => void;\n\n  constructor(opts: NeatlogsOptions) {\n    if (!opts || !opts.apiKey) {\n      throw new Error(\"Neatlogs: apiKey is required\");\n    }\n    this.apiKey = opts.apiKey;\n    this.project = opts.project;\n    // Use the origin of the configured endpoint (same convention as the Node SDK),\n    // so passing a full /v1/traces URL or a bare host both work.\n    const endpoint = opts.endpoint || DEFAULT_ENDPOINT;\n    this.baseUrl = safeOrigin(endpoint) || DEFAULT_ENDPOINT;\n    this.enabled = opts.enabled !== false;\n    this.onError =\n      opts.onError ||\n      ((err) => {\n        // eslint-disable-next-line no-console\n        if (typeof console !== \"undefined\") console.warn(\"[neatlogs] send failed:\", err);\n      });\n  }\n\n  /** Send a full (optionally nested) trace. Returns the backend's result. */\n  async trace(trace: NeatlogsTrace): Promise<TrackResult> {\n    return this.post(trace);\n  }\n\n  /** Send a single AI interaction as a one-span trace (kind defaults to LLM). */\n  async trackAI(ai: TrackAIInput): Promise<TrackResult> {\n    const { name, kind, ...rest } = ai;\n    return this.post({ name, kind: kind ?? \"LLM\", ...rest });\n  }\n\n  /**\n   * Begin a trace you'll complete later (e.g. streaming). Buffers the partial\n   * input; call `.finish()` with the final output/tokens to send it. Nothing is\n   * sent until `finish()`.\n   */\n  startTrace(initial: TrackAIInput): {\n    finish: (final?: Partial<TrackAIInput>) => Promise<TrackResult>;\n  } {\n    const startedAt = nowIso();\n    return {\n      finish: (final?: Partial<TrackAIInput>) => {\n        const merged: TrackAIInput = { ...initial, ...(final ?? {}) };\n        const { name, kind, ...rest } = merged;\n        return this.post({\n          name,\n          kind: kind ?? \"LLM\",\n          start: startedAt,\n          end: nowIso(),\n          ...rest,\n        });\n      },\n    };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    if (!this.enabled) return { ok: true };\n    // Inject the configured project name into the root (required for write keys;\n    // ignored server-side for full project keys). A `project` already on the body wins.\n    const payload =\n      this.project && (body as any).project === undefined\n        ? { ...body, project: this.project }\n        : body;\n    try {\n      const res = await fetch(`${this.baseUrl}/v1/trace`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: `Bearer ${this.apiKey}`,\n        },\n        body: JSON.stringify(payload),\n        // keepalive lets the request survive a page unload (e.g. on navigation).\n        keepalive: true,\n      });\n      if (!res.ok) {\n        const text = await res.text().catch(() => \"\");\n        const result = { ok: false, error: `HTTP ${res.status}${text ? `: ${text}` : \"\"}` };\n        this.onError(new Error(result.error));\n        return result;\n      }\n      const data = (await res.json().catch(() => ({}))) as Partial<TrackResult>;\n      return { ok: true, trace_id: data.trace_id, spans: data.spans };\n    } catch (err) {\n      // Never throw into the host app over telemetry.\n      this.onError(err);\n      return { ok: false, error: err instanceof Error ? err.message : String(err) };\n    }\n  }\n}\n\n// --- helpers (kept local, no imports) -----------------------------------------\n\nfunction safeOrigin(endpoint: string): string | null {\n  try {\n    return new URL(endpoint).origin;\n  } catch {\n    return null;\n  }\n}\n\nfunction nowIso(): string {\n  return new Date().toISOString();\n}\n\nexport default Neatlogs;\n"],"mappings":";AA6BA,IAAM,mBAAmB;AAkGlB,IAAM,WAAN,MAAe;AAAA,EACH;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAuB;AACjC,QAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ;AACzB,YAAM,IAAI,MAAM,8BAA8B;AAAA,IAChD;AACA,SAAK,SAAS,KAAK;AACnB,SAAK,UAAU,KAAK;AAGpB,UAAM,WAAW,KAAK,YAAY;AAClC,SAAK,UAAU,WAAW,QAAQ,KAAK;AACvC,SAAK,UAAU,KAAK,YAAY;AAChC,SAAK,UACH,KAAK,YACJ,CAAC,QAAQ;AAER,UAAI,OAAO,YAAY,YAAa,SAAQ,KAAK,2BAA2B,GAAG;AAAA,IACjF;AAAA,EACJ;AAAA;AAAA,EAGA,MAAM,MAAM,OAA4C;AACtD,WAAO,KAAK,KAAK,KAAK;AAAA,EACxB;AAAA;AAAA,EAGA,MAAM,QAAQ,IAAwC;AACpD,UAAM,EAAE,MAAM,MAAM,GAAG,KAAK,IAAI;AAChC,WAAO,KAAK,KAAK,EAAE,MAAM,MAAM,QAAQ,OAAO,GAAG,KAAK,CAAC;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,WAAW,SAET;AACA,UAAM,YAAY,OAAO;AACzB,WAAO;AAAA,MACL,QAAQ,CAAC,UAAkC;AACzC,cAAM,SAAuB,EAAE,GAAG,SAAS,GAAI,SAAS,CAAC,EAAG;AAC5D,cAAM,EAAE,MAAM,MAAM,GAAG,KAAK,IAAI;AAChC,eAAO,KAAK,KAAK;AAAA,UACf;AAAA,UACA,MAAM,QAAQ;AAAA,UACd,OAAO;AAAA,UACP,KAAK,OAAO;AAAA,UACZ,GAAG;AAAA,QACL,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAAA;AAAA,EAGA,MAAc,KAAK,MAA2C;AAC5D,QAAI,CAAC,KAAK,QAAS,QAAO,EAAE,IAAI,KAAK;AAGrC,UAAM,UACJ,KAAK,WAAY,KAAa,YAAY,SACtC,EAAE,GAAG,MAAM,SAAS,KAAK,QAAQ,IACjC;AACN,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,GAAG,KAAK,OAAO,aAAa;AAAA,QAClD,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACtC;AAAA,QACA,MAAM,KAAK,UAAU,OAAO;AAAA;AAAA,QAE5B,WAAW;AAAA,MACb,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,cAAM,SAAS,EAAE,IAAI,OAAO,OAAO,QAAQ,IAAI,MAAM,GAAG,OAAO,KAAK,IAAI,KAAK,EAAE,GAAG;AAClF,aAAK,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AACpC,eAAO;AAAA,MACT;AACA,YAAM,OAAQ,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC/C,aAAO,EAAE,IAAI,MAAM,UAAU,KAAK,UAAU,OAAO,KAAK,MAAM;AAAA,IAChE,SAAS,KAAK;AAEZ,WAAK,QAAQ,GAAG;AAChB,aAAO,EAAE,IAAI,OAAO,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EAAE;AAAA,IAC9E;AAAA,EACF;AACF;AAIA,SAAS,WAAW,UAAiC;AACnD,MAAI;AACF,WAAO,IAAI,IAAI,QAAQ,EAAE;AAAA,EAC3B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,SAAiB;AACxB,UAAO,oBAAI,KAAK,GAAE,YAAY;AAChC;AAEA,IAAO,kBAAQ;","names":[]}