neatlogs 1.1.20 → 1.1.21

package/dist/browser.cjs

@@ -49,7 +49,11 @@ var Neatlogs = class {
     this.apiKey = opts.apiKey;
     this.project = opts.project;
     const endpoint = opts.endpoint || DEFAULT_INGEST_ENDPOINT;
-    this.baseUrl = safeOrigin(endpoint) || DEFAULT_INGEST_ENDPOINT;
+    const origin = safeOrigin(endpoint);
+    if (origin === null) {
+      throw new Error(`Neatlogs: invalid endpoint ${JSON.stringify(endpoint)}`);
+    }
+    this.baseUrl = origin;
     this.enabled = opts.enabled !== false;
     this.endUserId = opts.endUserId;
     this.endUserMetadata = opts.endUserMetadata;

package/dist/browser.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/browser.ts","../src/constants.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\nimport { DEFAULT_INGEST_ENDPOINT } from './constants.js';\n\n// Canonical identity attribute keys (inlined — this file stays dependency-free).\nconst END_USER_ID_KEY = \"neatlogs.end_user.id\";\nconst END_USER_METADATA_KEY = \"neatlogs.end_user.metadata\";\nconst SESSION_ID_KEY = \"neatlogs.session.id\";\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\";\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   * END-USER this trace belongs to — only meaningful on the ROOT of a trace\n   * (overrides the client default). One end-user per trace; the backend rolls it\n   * up to the trace and its session. Ignored on child spans.\n   */\n  endUserId?: string;\n  /** Arbitrary end-user fields for the trace root (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * SESSION this trace belongs to — the conversation/thread grouping many turns.\n   * Only meaningful on the ROOT of a trace (overrides the client default). Every\n   * trace sharing a `sessionId` is grouped into one session in the dashboard; a new\n   * trace per turn, all with the same `sessionId`, forms a multi-turn conversation.\n   * Ignored on child spans.\n   */\n  sessionId?: string;\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   * Default END-USER identity for every trace this client sends — the user of\n   * your app, not the operator. One end-user per trace; the backend rolls it up\n   * to the trace and its session. A per-call `endUserId` (on trace()/trackAI())\n   * overrides this. Set it once after login, e.g. `new Neatlogs({ apiKey, endUserId })`.\n   */\n  endUserId?: string;\n  /** Default arbitrary end-user fields stored as JSON (e.g. { plan: 'pro' }). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * Default SESSION for every trace this client sends — the conversation/thread\n   * these traces belong to. A per-call `sessionId` (on trace()/trackAI()) overrides\n   * this. Set it once per conversation, e.g. `new Neatlogs({ apiKey, sessionId: convId })`.\n   */\n  sessionId?: string;\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  /** END-USER for this trace (overrides the client default). One per trace. */\n  endUserId?: string;\n  /** Arbitrary end-user fields for this trace (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /** SESSION this trace belongs to (overrides the client default). */\n  sessionId?: 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  private readonly endUserId?: string;\n  private readonly endUserMetadata?: Record<string, unknown>;\n  private readonly sessionId?: string;\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_INGEST_ENDPOINT;\n    this.baseUrl = safeOrigin(endpoint) || DEFAULT_INGEST_ENDPOINT;\n    this.enabled = opts.enabled !== false;\n    this.endUserId = opts.endUserId;\n    this.endUserMetadata = opts.endUserMetadata;\n    this.sessionId = opts.sessionId;\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  /**\n   * Fold identity (end-user + session) onto the trace ROOT as canonical\n   * attributes, and strip the convenience `endUserId`/`endUserMetadata`/`sessionId`\n   * fields so they aren't sent as raw root fields. Per-call values win over the\n   * client defaults; explicit `attributes` win over both. Only the root carries\n   * identity — one end-user per trace, one session per trace.\n   */\n  private applyIdentity(body: NeatlogsTrace): NeatlogsTrace {\n    const { endUserId, endUserMetadata, sessionId, ...rest } = body as NeatlogsTrace & {\n      endUserId?: string;\n      endUserMetadata?: Record<string, unknown>;\n      sessionId?: string;\n    };\n    const id = endUserId ?? this.endUserId;\n    const meta = endUserMetadata ?? this.endUserMetadata;\n    const session = sessionId ?? this.sessionId;\n    if (id === undefined && meta === undefined && session === undefined) {\n      return rest;\n    }\n\n    const attributes: Record<string, unknown> = { ...(rest.attributes ?? {}) };\n    if (id !== undefined && attributes[END_USER_ID_KEY] === undefined) {\n      attributes[END_USER_ID_KEY] = String(id);\n    }\n    if (meta !== undefined && attributes[END_USER_METADATA_KEY] === undefined) {\n      attributes[END_USER_METADATA_KEY] =\n        typeof meta === \"string\" ? meta : JSON.stringify(meta);\n    }\n    if (session !== undefined && attributes[SESSION_ID_KEY] === undefined) {\n      attributes[SESSION_ID_KEY] = String(session);\n    }\n    return { ...rest, attributes };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    const httpKindPath = findHttpKind(body);\n    if (httpKindPath) {\n      const error = `HTTP spans are not supported (${httpKindPath}). Trace the semantic AI operation instead.`;\n      this.onError(new Error(error));\n      return { ok: false, error };\n    }\n    if (!this.enabled) return { ok: true };\n    // Fold identity (end-user + session) onto the root before anything else.\n    body = this.applyIdentity(body);\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\nfunction findHttpKind(span: NeatlogsSpan, path = 'root'): string | null {\n  const kindCandidates = [\n    span.kind,\n    span.attributes?.['neatlogs.span.kind'],\n    span.attributes?.['openinference.span.kind'],\n  ];\n  if (kindCandidates.some((value) => String(value ?? '').trim().toUpperCase() === 'HTTP')) {\n    return path;\n  }\n  for (let index = 0; index < (span.children?.length ?? 0); index += 1) {\n    const childPath = findHttpKind(span.children![index], `${path}.children[${index}]`);\n    if (childPath) return childPath;\n  }\n  return null;\n}\n\nexport default Neatlogs;\n","/** Stable SDK-wide defaults shared by every NeatLogs entry point. */\nexport const DEFAULT_INGEST_ENDPOINT = 'https://ingest.neatlogs.com' as const;\nexport const DEFAULT_MAX_QUEUE_ITEMS = 2048;\nexport const DEFAULT_MAX_SEMANTIC_STREAM_EVENTS = 128;\nexport const DEFAULT_MAX_STREAM_CAPTURE_BYTES = 1024 * 1024;\nexport const DEFAULT_MAX_STREAM_CAPTURE_ITEMS = 1024;\n\n/** UTF-8 byte length without allocating a second buffer for hostile stream chunks. */\nexport function utf8ByteLength(\n  value: string,\n  limit = Number.MAX_SAFE_INTEGER,\n): number {\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {\n      const next = value.charCodeAt(i + 1);\n      if (next >= 0xdc00 && next <= 0xdfff) {\n        bytes += 4;\n        i += 1;\n      } else bytes += 3;\n    } else bytes += 3;\n    if (bytes > limit) return limit + 1;\n  }\n  return bytes;\n}\n\nexport function exportQueueCapacity(batchSize: number): number {\n  return Math.max(DEFAULT_MAX_QUEUE_ITEMS, batchSize * 4);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/browser.ts","../src/constants.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\nimport { DEFAULT_INGEST_ENDPOINT } from './constants.js';\n\n// Canonical identity attribute keys (inlined — this file stays dependency-free).\nconst END_USER_ID_KEY = \"neatlogs.end_user.id\";\nconst END_USER_METADATA_KEY = \"neatlogs.end_user.metadata\";\nconst SESSION_ID_KEY = \"neatlogs.session.id\";\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\";\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   * END-USER this trace belongs to — only meaningful on the ROOT of a trace\n   * (overrides the client default). One end-user per trace; the backend rolls it\n   * up to the trace and its session. Ignored on child spans.\n   */\n  endUserId?: string;\n  /** Arbitrary end-user fields for the trace root (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * SESSION this trace belongs to — the conversation/thread grouping many turns.\n   * Only meaningful on the ROOT of a trace (overrides the client default). Every\n   * trace sharing a `sessionId` is grouped into one session in the dashboard; a new\n   * trace per turn, all with the same `sessionId`, forms a multi-turn conversation.\n   * Ignored on child spans.\n   */\n  sessionId?: string;\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   * Default END-USER identity for every trace this client sends — the user of\n   * your app, not the operator. One end-user per trace; the backend rolls it up\n   * to the trace and its session. A per-call `endUserId` (on trace()/trackAI())\n   * overrides this. Set it once after login, e.g. `new Neatlogs({ apiKey, endUserId })`.\n   */\n  endUserId?: string;\n  /** Default arbitrary end-user fields stored as JSON (e.g. { plan: 'pro' }). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * Default SESSION for every trace this client sends — the conversation/thread\n   * these traces belong to. A per-call `sessionId` (on trace()/trackAI()) overrides\n   * this. Set it once per conversation, e.g. `new Neatlogs({ apiKey, sessionId: convId })`.\n   */\n  sessionId?: string;\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  /** END-USER for this trace (overrides the client default). One per trace. */\n  endUserId?: string;\n  /** Arbitrary end-user fields for this trace (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /** SESSION this trace belongs to (overrides the client default). */\n  sessionId?: 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  private readonly endUserId?: string;\n  private readonly endUserMetadata?: Record<string, unknown>;\n  private readonly sessionId?: string;\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. A malformed\n    // endpoint throws instead of silently falling back to prod ingest, which\n    // would misroute telemetry with no signal to the host app.\n    const endpoint = opts.endpoint || DEFAULT_INGEST_ENDPOINT;\n    const origin = safeOrigin(endpoint);\n    if (origin === null) {\n      throw new Error(`Neatlogs: invalid endpoint ${JSON.stringify(endpoint)}`);\n    }\n    this.baseUrl = origin;\n    this.enabled = opts.enabled !== false;\n    this.endUserId = opts.endUserId;\n    this.endUserMetadata = opts.endUserMetadata;\n    this.sessionId = opts.sessionId;\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  /**\n   * Fold identity (end-user + session) onto the trace ROOT as canonical\n   * attributes, and strip the convenience `endUserId`/`endUserMetadata`/`sessionId`\n   * fields so they aren't sent as raw root fields. Per-call values win over the\n   * client defaults; explicit `attributes` win over both. Only the root carries\n   * identity — one end-user per trace, one session per trace.\n   */\n  private applyIdentity(body: NeatlogsTrace): NeatlogsTrace {\n    const { endUserId, endUserMetadata, sessionId, ...rest } = body as NeatlogsTrace & {\n      endUserId?: string;\n      endUserMetadata?: Record<string, unknown>;\n      sessionId?: string;\n    };\n    const id = endUserId ?? this.endUserId;\n    const meta = endUserMetadata ?? this.endUserMetadata;\n    const session = sessionId ?? this.sessionId;\n    if (id === undefined && meta === undefined && session === undefined) {\n      return rest;\n    }\n\n    const attributes: Record<string, unknown> = { ...(rest.attributes ?? {}) };\n    if (id !== undefined && attributes[END_USER_ID_KEY] === undefined) {\n      attributes[END_USER_ID_KEY] = String(id);\n    }\n    if (meta !== undefined && attributes[END_USER_METADATA_KEY] === undefined) {\n      attributes[END_USER_METADATA_KEY] =\n        typeof meta === \"string\" ? meta : JSON.stringify(meta);\n    }\n    if (session !== undefined && attributes[SESSION_ID_KEY] === undefined) {\n      attributes[SESSION_ID_KEY] = String(session);\n    }\n    return { ...rest, attributes };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    const httpKindPath = findHttpKind(body);\n    if (httpKindPath) {\n      const error = `HTTP spans are not supported (${httpKindPath}). Trace the semantic AI operation instead.`;\n      this.onError(new Error(error));\n      return { ok: false, error };\n    }\n    if (!this.enabled) return { ok: true };\n    // Fold identity (end-user + session) onto the root before anything else.\n    body = this.applyIdentity(body);\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\nfunction findHttpKind(span: NeatlogsSpan, path = 'root'): string | null {\n  const kindCandidates = [\n    span.kind,\n    span.attributes?.['neatlogs.span.kind'],\n    span.attributes?.['openinference.span.kind'],\n  ];\n  if (kindCandidates.some((value) => String(value ?? '').trim().toUpperCase() === 'HTTP')) {\n    return path;\n  }\n  for (let index = 0; index < (span.children?.length ?? 0); index += 1) {\n    const childPath = findHttpKind(span.children![index], `${path}.children[${index}]`);\n    if (childPath) return childPath;\n  }\n  return null;\n}\n\nexport default Neatlogs;\n","/** Stable SDK-wide defaults shared by every NeatLogs entry point. */\nexport const DEFAULT_INGEST_ENDPOINT = 'https://ingest.neatlogs.com' as const;\nexport const DEFAULT_MAX_QUEUE_ITEMS = 2048;\nexport const DEFAULT_MAX_SEMANTIC_STREAM_EVENTS = 128;\nexport const DEFAULT_MAX_STREAM_CAPTURE_BYTES = 1024 * 1024;\nexport const DEFAULT_MAX_STREAM_CAPTURE_ITEMS = 1024;\n\n/** UTF-8 byte length without allocating a second buffer for hostile stream chunks. */\nexport function utf8ByteLength(\n  value: string,\n  limit = Number.MAX_SAFE_INTEGER,\n): number {\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {\n      const next = value.charCodeAt(i + 1);\n      if (next >= 0xdc00 && next <= 0xdfff) {\n        bytes += 4;\n        i += 1;\n      } else bytes += 3;\n    } else bytes += 3;\n    if (bytes > limit) return limit + 1;\n  }\n  return bytes;\n}\n\nexport function exportQueueCapacity(batchSize: number): number {\n  return Math.max(DEFAULT_MAX_QUEUE_ITEMS, batchSize * 4);\n}\n"],"mappings":"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","names":[]}

package/dist/browser.mjs

@@ -22,7 +22,11 @@ var Neatlogs = class {
     this.apiKey = opts.apiKey;
     this.project = opts.project;
     const endpoint = opts.endpoint || DEFAULT_INGEST_ENDPOINT;
-    this.baseUrl = safeOrigin(endpoint) || DEFAULT_INGEST_ENDPOINT;
+    const origin = safeOrigin(endpoint);
+    if (origin === null) {
+      throw new Error(`Neatlogs: invalid endpoint ${JSON.stringify(endpoint)}`);
+    }
+    this.baseUrl = origin;
     this.enabled = opts.enabled !== false;
     this.endUserId = opts.endUserId;
     this.endUserMetadata = opts.endUserMetadata;

package/dist/browser.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts","../src/browser.ts"],"sourcesContent":["/** Stable SDK-wide defaults shared by every NeatLogs entry point. */\nexport const DEFAULT_INGEST_ENDPOINT = 'https://ingest.neatlogs.com' as const;\nexport const DEFAULT_MAX_QUEUE_ITEMS = 2048;\nexport const DEFAULT_MAX_SEMANTIC_STREAM_EVENTS = 128;\nexport const DEFAULT_MAX_STREAM_CAPTURE_BYTES = 1024 * 1024;\nexport const DEFAULT_MAX_STREAM_CAPTURE_ITEMS = 1024;\n\n/** UTF-8 byte length without allocating a second buffer for hostile stream chunks. */\nexport function utf8ByteLength(\n  value: string,\n  limit = Number.MAX_SAFE_INTEGER,\n): number {\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {\n      const next = value.charCodeAt(i + 1);\n      if (next >= 0xdc00 && next <= 0xdfff) {\n        bytes += 4;\n        i += 1;\n      } else bytes += 3;\n    } else bytes += 3;\n    if (bytes > limit) return limit + 1;\n  }\n  return bytes;\n}\n\nexport function exportQueueCapacity(batchSize: number): number {\n  return Math.max(DEFAULT_MAX_QUEUE_ITEMS, batchSize * 4);\n}\n","/**\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\nimport { DEFAULT_INGEST_ENDPOINT } from './constants.js';\n\n// Canonical identity attribute keys (inlined — this file stays dependency-free).\nconst END_USER_ID_KEY = \"neatlogs.end_user.id\";\nconst END_USER_METADATA_KEY = \"neatlogs.end_user.metadata\";\nconst SESSION_ID_KEY = \"neatlogs.session.id\";\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\";\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   * END-USER this trace belongs to — only meaningful on the ROOT of a trace\n   * (overrides the client default). One end-user per trace; the backend rolls it\n   * up to the trace and its session. Ignored on child spans.\n   */\n  endUserId?: string;\n  /** Arbitrary end-user fields for the trace root (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * SESSION this trace belongs to — the conversation/thread grouping many turns.\n   * Only meaningful on the ROOT of a trace (overrides the client default). Every\n   * trace sharing a `sessionId` is grouped into one session in the dashboard; a new\n   * trace per turn, all with the same `sessionId`, forms a multi-turn conversation.\n   * Ignored on child spans.\n   */\n  sessionId?: string;\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   * Default END-USER identity for every trace this client sends — the user of\n   * your app, not the operator. One end-user per trace; the backend rolls it up\n   * to the trace and its session. A per-call `endUserId` (on trace()/trackAI())\n   * overrides this. Set it once after login, e.g. `new Neatlogs({ apiKey, endUserId })`.\n   */\n  endUserId?: string;\n  /** Default arbitrary end-user fields stored as JSON (e.g. { plan: 'pro' }). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * Default SESSION for every trace this client sends — the conversation/thread\n   * these traces belong to. A per-call `sessionId` (on trace()/trackAI()) overrides\n   * this. Set it once per conversation, e.g. `new Neatlogs({ apiKey, sessionId: convId })`.\n   */\n  sessionId?: string;\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  /** END-USER for this trace (overrides the client default). One per trace. */\n  endUserId?: string;\n  /** Arbitrary end-user fields for this trace (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /** SESSION this trace belongs to (overrides the client default). */\n  sessionId?: 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  private readonly endUserId?: string;\n  private readonly endUserMetadata?: Record<string, unknown>;\n  private readonly sessionId?: string;\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_INGEST_ENDPOINT;\n    this.baseUrl = safeOrigin(endpoint) || DEFAULT_INGEST_ENDPOINT;\n    this.enabled = opts.enabled !== false;\n    this.endUserId = opts.endUserId;\n    this.endUserMetadata = opts.endUserMetadata;\n    this.sessionId = opts.sessionId;\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  /**\n   * Fold identity (end-user + session) onto the trace ROOT as canonical\n   * attributes, and strip the convenience `endUserId`/`endUserMetadata`/`sessionId`\n   * fields so they aren't sent as raw root fields. Per-call values win over the\n   * client defaults; explicit `attributes` win over both. Only the root carries\n   * identity — one end-user per trace, one session per trace.\n   */\n  private applyIdentity(body: NeatlogsTrace): NeatlogsTrace {\n    const { endUserId, endUserMetadata, sessionId, ...rest } = body as NeatlogsTrace & {\n      endUserId?: string;\n      endUserMetadata?: Record<string, unknown>;\n      sessionId?: string;\n    };\n    const id = endUserId ?? this.endUserId;\n    const meta = endUserMetadata ?? this.endUserMetadata;\n    const session = sessionId ?? this.sessionId;\n    if (id === undefined && meta === undefined && session === undefined) {\n      return rest;\n    }\n\n    const attributes: Record<string, unknown> = { ...(rest.attributes ?? {}) };\n    if (id !== undefined && attributes[END_USER_ID_KEY] === undefined) {\n      attributes[END_USER_ID_KEY] = String(id);\n    }\n    if (meta !== undefined && attributes[END_USER_METADATA_KEY] === undefined) {\n      attributes[END_USER_METADATA_KEY] =\n        typeof meta === \"string\" ? meta : JSON.stringify(meta);\n    }\n    if (session !== undefined && attributes[SESSION_ID_KEY] === undefined) {\n      attributes[SESSION_ID_KEY] = String(session);\n    }\n    return { ...rest, attributes };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    const httpKindPath = findHttpKind(body);\n    if (httpKindPath) {\n      const error = `HTTP spans are not supported (${httpKindPath}). Trace the semantic AI operation instead.`;\n      this.onError(new Error(error));\n      return { ok: false, error };\n    }\n    if (!this.enabled) return { ok: true };\n    // Fold identity (end-user + session) onto the root before anything else.\n    body = this.applyIdentity(body);\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\nfunction findHttpKind(span: NeatlogsSpan, path = 'root'): string | null {\n  const kindCandidates = [\n    span.kind,\n    span.attributes?.['neatlogs.span.kind'],\n    span.attributes?.['openinference.span.kind'],\n  ];\n  if (kindCandidates.some((value) => String(value ?? '').trim().toUpperCase() === 'HTTP')) {\n    return path;\n  }\n  for (let index = 0; index < (span.children?.length ?? 0); index += 1) {\n    const childPath = findHttpKind(span.children![index], `${path}.children[${index}]`);\n    if (childPath) return childPath;\n  }\n  return null;\n}\n\nexport default Neatlogs;\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/constants.ts","../src/browser.ts"],"sourcesContent":["/** Stable SDK-wide defaults shared by every NeatLogs entry point. */\nexport const DEFAULT_INGEST_ENDPOINT = 'https://ingest.neatlogs.com' as const;\nexport const DEFAULT_MAX_QUEUE_ITEMS = 2048;\nexport const DEFAULT_MAX_SEMANTIC_STREAM_EVENTS = 128;\nexport const DEFAULT_MAX_STREAM_CAPTURE_BYTES = 1024 * 1024;\nexport const DEFAULT_MAX_STREAM_CAPTURE_ITEMS = 1024;\n\n/** UTF-8 byte length without allocating a second buffer for hostile stream chunks. */\nexport function utf8ByteLength(\n  value: string,\n  limit = Number.MAX_SAFE_INTEGER,\n): number {\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {\n      const next = value.charCodeAt(i + 1);\n      if (next >= 0xdc00 && next <= 0xdfff) {\n        bytes += 4;\n        i += 1;\n      } else bytes += 3;\n    } else bytes += 3;\n    if (bytes > limit) return limit + 1;\n  }\n  return bytes;\n}\n\nexport function exportQueueCapacity(batchSize: number): number {\n  return Math.max(DEFAULT_MAX_QUEUE_ITEMS, batchSize * 4);\n}\n","/**\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\nimport { DEFAULT_INGEST_ENDPOINT } from './constants.js';\n\n// Canonical identity attribute keys (inlined — this file stays dependency-free).\nconst END_USER_ID_KEY = \"neatlogs.end_user.id\";\nconst END_USER_METADATA_KEY = \"neatlogs.end_user.metadata\";\nconst SESSION_ID_KEY = \"neatlogs.session.id\";\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\";\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   * END-USER this trace belongs to — only meaningful on the ROOT of a trace\n   * (overrides the client default). One end-user per trace; the backend rolls it\n   * up to the trace and its session. Ignored on child spans.\n   */\n  endUserId?: string;\n  /** Arbitrary end-user fields for the trace root (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * SESSION this trace belongs to — the conversation/thread grouping many turns.\n   * Only meaningful on the ROOT of a trace (overrides the client default). Every\n   * trace sharing a `sessionId` is grouped into one session in the dashboard; a new\n   * trace per turn, all with the same `sessionId`, forms a multi-turn conversation.\n   * Ignored on child spans.\n   */\n  sessionId?: string;\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   * Default END-USER identity for every trace this client sends — the user of\n   * your app, not the operator. One end-user per trace; the backend rolls it up\n   * to the trace and its session. A per-call `endUserId` (on trace()/trackAI())\n   * overrides this. Set it once after login, e.g. `new Neatlogs({ apiKey, endUserId })`.\n   */\n  endUserId?: string;\n  /** Default arbitrary end-user fields stored as JSON (e.g. { plan: 'pro' }). */\n  endUserMetadata?: Record<string, unknown>;\n  /**\n   * Default SESSION for every trace this client sends — the conversation/thread\n   * these traces belong to. A per-call `sessionId` (on trace()/trackAI()) overrides\n   * this. Set it once per conversation, e.g. `new Neatlogs({ apiKey, sessionId: convId })`.\n   */\n  sessionId?: string;\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  /** END-USER for this trace (overrides the client default). One per trace. */\n  endUserId?: string;\n  /** Arbitrary end-user fields for this trace (overrides the client default). */\n  endUserMetadata?: Record<string, unknown>;\n  /** SESSION this trace belongs to (overrides the client default). */\n  sessionId?: 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  private readonly endUserId?: string;\n  private readonly endUserMetadata?: Record<string, unknown>;\n  private readonly sessionId?: string;\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. A malformed\n    // endpoint throws instead of silently falling back to prod ingest, which\n    // would misroute telemetry with no signal to the host app.\n    const endpoint = opts.endpoint || DEFAULT_INGEST_ENDPOINT;\n    const origin = safeOrigin(endpoint);\n    if (origin === null) {\n      throw new Error(`Neatlogs: invalid endpoint ${JSON.stringify(endpoint)}`);\n    }\n    this.baseUrl = origin;\n    this.enabled = opts.enabled !== false;\n    this.endUserId = opts.endUserId;\n    this.endUserMetadata = opts.endUserMetadata;\n    this.sessionId = opts.sessionId;\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  /**\n   * Fold identity (end-user + session) onto the trace ROOT as canonical\n   * attributes, and strip the convenience `endUserId`/`endUserMetadata`/`sessionId`\n   * fields so they aren't sent as raw root fields. Per-call values win over the\n   * client defaults; explicit `attributes` win over both. Only the root carries\n   * identity — one end-user per trace, one session per trace.\n   */\n  private applyIdentity(body: NeatlogsTrace): NeatlogsTrace {\n    const { endUserId, endUserMetadata, sessionId, ...rest } = body as NeatlogsTrace & {\n      endUserId?: string;\n      endUserMetadata?: Record<string, unknown>;\n      sessionId?: string;\n    };\n    const id = endUserId ?? this.endUserId;\n    const meta = endUserMetadata ?? this.endUserMetadata;\n    const session = sessionId ?? this.sessionId;\n    if (id === undefined && meta === undefined && session === undefined) {\n      return rest;\n    }\n\n    const attributes: Record<string, unknown> = { ...(rest.attributes ?? {}) };\n    if (id !== undefined && attributes[END_USER_ID_KEY] === undefined) {\n      attributes[END_USER_ID_KEY] = String(id);\n    }\n    if (meta !== undefined && attributes[END_USER_METADATA_KEY] === undefined) {\n      attributes[END_USER_METADATA_KEY] =\n        typeof meta === \"string\" ? meta : JSON.stringify(meta);\n    }\n    if (session !== undefined && attributes[SESSION_ID_KEY] === undefined) {\n      attributes[SESSION_ID_KEY] = String(session);\n    }\n    return { ...rest, attributes };\n  }\n\n  /** POST the trace JSON to the backend's /v1/trace endpoint. */\n  private async post(body: NeatlogsTrace): Promise<TrackResult> {\n    const httpKindPath = findHttpKind(body);\n    if (httpKindPath) {\n      const error = `HTTP spans are not supported (${httpKindPath}). Trace the semantic AI operation instead.`;\n      this.onError(new Error(error));\n      return { ok: false, error };\n    }\n    if (!this.enabled) return { ok: true };\n    // Fold identity (end-user + session) onto the root before anything else.\n    body = this.applyIdentity(body);\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\nfunction findHttpKind(span: NeatlogsSpan, path = 'root'): string | null {\n  const kindCandidates = [\n    span.kind,\n    span.attributes?.['neatlogs.span.kind'],\n    span.attributes?.['openinference.span.kind'],\n  ];\n  if (kindCandidates.some((value) => String(value ?? '').trim().toUpperCase() === 'HTTP')) {\n    return path;\n  }\n  for (let index = 0; index < (span.children?.length ?? 0); index += 1) {\n    const childPath = findHttpKind(span.children![index], `${path}.children[${index}]`);\n    if (childPath) return childPath;\n  }\n  return null;\n}\n\nexport default Neatlogs;\n"],"mappings":";AACO,IAAM,0BAA0B;AAGhC,IAAM,mCAAmC,OAAO;;;AC4BvD,IAAM,kBAAkB;AACxB,IAAM,wBAAwB;AAC9B,IAAM,iBAAiB;AAuIhB,IAAM,WAAN,MAAe;AAAA,EACH;AAAA,EACA;AAAA,EACA;AAAA,EACA;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;AAKpB,UAAM,WAAW,KAAK,YAAY;AAClC,UAAM,SAAS,WAAW,QAAQ;AAClC,QAAI,WAAW,MAAM;AACnB,YAAM,IAAI,MAAM,8BAA8B,KAAK,UAAU,QAAQ,CAAC,EAAE;AAAA,IAC1E;AACA,SAAK,UAAU;AACf,SAAK,UAAU,KAAK,YAAY;AAChC,SAAK,YAAY,KAAK;AACtB,SAAK,kBAAkB,KAAK;AAC5B,SAAK,YAAY,KAAK;AACtB,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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,cAAc,MAAoC;AACxD,UAAM,EAAE,WAAW,iBAAiB,WAAW,GAAG,KAAK,IAAI;AAK3D,UAAM,KAAK,aAAa,KAAK;AAC7B,UAAM,OAAO,mBAAmB,KAAK;AACrC,UAAM,UAAU,aAAa,KAAK;AAClC,QAAI,OAAO,UAAa,SAAS,UAAa,YAAY,QAAW;AACnE,aAAO;AAAA,IACT;AAEA,UAAM,aAAsC,EAAE,GAAI,KAAK,cAAc,CAAC,EAAG;AACzE,QAAI,OAAO,UAAa,WAAW,eAAe,MAAM,QAAW;AACjE,iBAAW,eAAe,IAAI,OAAO,EAAE;AAAA,IACzC;AACA,QAAI,SAAS,UAAa,WAAW,qBAAqB,MAAM,QAAW;AACzE,iBAAW,qBAAqB,IAC9B,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU,IAAI;AAAA,IACzD;AACA,QAAI,YAAY,UAAa,WAAW,cAAc,MAAM,QAAW;AACrE,iBAAW,cAAc,IAAI,OAAO,OAAO;AAAA,IAC7C;AACA,WAAO,EAAE,GAAG,MAAM,WAAW;AAAA,EAC/B;AAAA;AAAA,EAGA,MAAc,KAAK,MAA2C;AAC5D,UAAM,eAAe,aAAa,IAAI;AACtC,QAAI,cAAc;AAChB,YAAM,QAAQ,iCAAiC,YAAY;AAC3D,WAAK,QAAQ,IAAI,MAAM,KAAK,CAAC;AAC7B,aAAO,EAAE,IAAI,OAAO,MAAM;AAAA,IAC5B;AACA,QAAI,CAAC,KAAK,QAAS,QAAO,EAAE,IAAI,KAAK;AAErC,WAAO,KAAK,cAAc,IAAI;AAG9B,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,SAAS,aAAa,MAAoB,OAAO,QAAuB;AACtE,QAAM,iBAAiB;AAAA,IACrB,KAAK;AAAA,IACL,KAAK,aAAa,oBAAoB;AAAA,IACtC,KAAK,aAAa,yBAAyB;AAAA,EAC7C;AACA,MAAI,eAAe,KAAK,CAAC,UAAU,OAAO,SAAS,EAAE,EAAE,KAAK,EAAE,YAAY,MAAM,MAAM,GAAG;AACvF,WAAO;AAAA,EACT;AACA,WAAS,QAAQ,GAAG,SAAS,KAAK,UAAU,UAAU,IAAI,SAAS,GAAG;AACpE,UAAM,YAAY,aAAa,KAAK,SAAU,KAAK,GAAG,GAAG,IAAI,aAAa,KAAK,GAAG;AAClF,QAAI,UAAW,QAAO;AAAA,EACxB;AACA,SAAO;AACT;AAEA,IAAO,kBAAQ;","names":[]}

package/dist/cli.cjs

@@ -7104,7 +7104,7 @@ var TELEMETRY_CONFLICT_PRECEDENCE = Object.freeze(
 );
 
 // src/version.ts
-var __version__ = "1.1.20";
+var __version__ = "1.1.21";
 
 // src/init.ts
 var path2 = __toESM(require("path"));
@@ -11423,6 +11423,24 @@ var INIT_OPTION_KEYS = /* @__PURE__ */ new Set([
   "piiSpanTypes",
   "uploadAuthority"
 ]);
+function resolveInitEndpoint(endpoint) {
+  const explicit = (endpoint ?? "").trim();
+  if (explicit) return explicit;
+  const fromEnv = (process.env.NEATLOGS_ENDPOINT ?? "").trim();
+  return fromEnv || DEFAULT_INGEST_ENDPOINT;
+}
+function resolveIngestBaseUrl(endpoint) {
+  const parsed = new URL(endpoint.trim());
+  const path3 = parsed.pathname.replace(/\/+$/, "");
+  if (path3 !== "" && path3 !== "/v1/traces") {
+    throw new NeatlogsConfigurationError(
+      "INVALID_ENDPOINT",
+      "endpoint",
+      "endpoint must be a base URL or an OTLP traces URL ending in /v1/traces."
+    );
+  }
+  return parsed.origin;
+}
 function validateInitOptions(options) {
   const raw = options;
   if (Object.prototype.hasOwnProperty.call(raw, "instrumentations")) {
@@ -11506,8 +11524,13 @@ function stableValue(value, ancestors = /* @__PURE__ */ new WeakSet(), location
     ancestors.delete(value);
   }
 }
+function resolveApiKey(apiKey) {
+  const explicit = (apiKey ?? "").trim();
+  if (explicit) return explicit;
+  return (process.env.NEATLOGS_API_KEY ?? "").trim();
+}
 function initIdentity(options) {
-  const apiKey = (options.apiKey ?? process.env.NEATLOGS_API_KEY ?? "").trim();
+  const apiKey = resolveApiKey(options.apiKey);
   const apiKeyDigest = (0, import_node_crypto4.createHash)("sha256").update(apiKey).digest("hex");
   const serialized = stableValue({
     apiKeyDigest,
@@ -11527,7 +11550,7 @@ function initIdentity(options) {
     captureLogs: options.captureLogs ?? false,
     pii: options.pii ?? null,
     version: options.version ?? null,
-    endpoint: options.endpoint ?? DEFAULT_INGEST_ENDPOINT,
+    endpoint: resolveInitEndpoint(options.endpoint),
     batchSize: options.batchSize ?? 100,
     flushInterval: options.flushInterval ?? 5,
     piiEnabled: options.piiEnabled ?? null,
@@ -11607,12 +11630,7 @@ async function _performInit(options) {
     );
   }
   _deliveryDiagnostics = new DeliveryDiagnostics();
-  let resolvedKey;
-  if (options.apiKey && options.apiKey.trim()) {
-    resolvedKey = options.apiKey.trim();
-  } else {
-    resolvedKey = (process.env.NEATLOGS_API_KEY ?? "").trim();
-  }
+  let resolvedKey = resolveApiKey(options.apiKey);
   let disableExportResolved = !!options.disableExport || ["true", "1", "yes"].includes(
     (process.env.NEATLOGS_DISABLE_EXPORT ?? "").toLowerCase()
   );
@@ -11633,8 +11651,8 @@ async function _performInit(options) {
   }
   _debugMode2 = options.debug ?? false;
   const resolvedWorkflowName = _resolveWorkflowName(options.workflowName);
-  const endpoint = options.endpoint ?? DEFAULT_INGEST_ENDPOINT;
-  const baseUrl = new URL(endpoint).origin;
+  const endpoint = resolveInitEndpoint(options.endpoint);
+  const baseUrl = resolveIngestBaseUrl(endpoint);
   const uploadAuthority = disableExportResolved ? new DisabledUploadAuthority("export_disabled") : resolveUploadAuthority(
     options.uploadAuthority,
     process.env.NEATLOGS_UPLOADS_ENABLED,