@ziplogger/browser 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahaliav Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @ziplogger/browser
+
+Browser SDK for [ZipLogger](https://ziplogger.dev) — capture uncaught errors,
+unhandled promise rejections, and custom events from web apps, with a first-class React error
+boundary. Zero dependencies.
+
+```bash
+npm install @ziplogger/browser
+```
+
+## Quick start
+
+```js
+import { ZipLoggerBrowser } from '@ziplogger/browser'
+
+export const ziplogger = new ZipLoggerBrowser({
+  endpoint: 'https://app.ziplogger.dev',
+  apiKey: 'zk_...',            // use a key dedicated to browser traffic
+  release: import.meta.env.VITE_APP_VERSION,
+})
+
+ziplogger.captureGlobalErrors()  // window.onerror + unhandledrejection
+
+ziplogger.log({ severity: 'info', message: 'checkout started', fields: { cartValue: 214.9 } })
+try { risky() } catch (err) { ziplogger.captureError(err, { step: 'payment' }) }
+```
+
+Every event carries `url`, `userAgent`, and `environment` fields automatically; `Error` objects
+map to ZipLogger's `stackTrace`. A final `fetch(…, { keepalive: true })` flush fires on
+`pagehide` so events survive navigation and tab closes.
+
+## React
+
+```jsx
+import React from 'react'
+import { createErrorBoundary, createUseZipLogger } from '@ziplogger/browser/react'
+import { ziplogger } from './ziplogger'
+
+const ZipLoggerErrorBoundary = createErrorBoundary(React, ziplogger)
+export const useZipLogger = createUseZipLogger(React, ziplogger)
+
+root.render(
+  <ZipLoggerErrorBoundary fallback={<p>Something went wrong.</p>}>
+    <App />
+  </ZipLoggerErrorBoundary>,
+)
+
+// in any component
+const { captureError } = useZipLogger()
+```
+
+Render errors ship with the component stack; the factory pattern (`createErrorBoundary(React, …)`)
+keeps this package free of a React dependency, so it works with any React ≥ 16.8 — and the core
+client works with Vue, Svelte, Angular, or no framework at all.
+
+## Notes
+
+- Browser API keys are visible to users by design (like every client-side telemetry key). Use a
+  dedicated key so it can be revoked independently, and rely on your plan's rate limits.
+- Batching defaults are browser-tuned: 20 events/request, 3s linger, 2 retries, 1,000-event buffer.

package/index.d.ts

@@ -0,0 +1,88 @@
+export type Severity = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+export interface BrowserOptions {
+  /** Base URL of the ZipLogger server, e.g. "https://logs.yourcompany.com". */
+  endpoint: string
+  /** Tenant ingestion API key (zk_...). Use a key dedicated to browser traffic. */
+  apiKey: string
+  /** Source name. Default: window.location.hostname. */
+  source?: string
+  release?: string
+  commitSha?: string
+  /** Default "production". */
+  environment?: string
+  tags?: string[]
+  /** Attach url + userAgent fields to every event. Default true. */
+  includePageContext?: boolean
+  /** Max buffered events. Default 1000. */
+  queueCapacity?: number
+  /** Max events per request. Default 20. */
+  batchSize?: number
+  /** Linger before flushing a partial batch. Default 3000. */
+  flushIntervalMs?: number
+  /** Retry attempts per batch. Default 2 (browsers should not hammer). */
+  maxRetries?: number
+  retryBaseDelayMs?: number
+}
+
+export interface BrowserLogEntry {
+  message: string
+  severity?: Severity
+  timestamp?: string
+  source?: string
+  release?: string
+  commitSha?: string
+  stackTrace?: string
+  error?: Error
+  fields?: Record<string, unknown>
+  tags?: string[]
+}
+
+export declare class ZipLoggerBrowser {
+  constructor(options: BrowserOptions)
+  /** Events lost to backpressure or exhausted retries. */
+  dropped: number
+  /** Queue an event for background delivery. Never blocks, never throws. */
+  log(entry: BrowserLogEntry): void
+  /** Report a caught error with optional context fields. */
+  captureError(error: unknown, fields?: Record<string, unknown>): void
+  /** Capture window error / unhandledrejection events. Returns a stop function. */
+  captureGlobalErrors(): () => void
+  /**
+   * Wraps window.fetch: adds a W3C traceparent header to same-origin requests (plus any
+   * origins in propagateTo) so browser calls and backend traces share one trace id, and
+   * logs failed requests (HTTP >= 400 / network errors) with that trace id.
+   */
+  instrumentFetch(options?: {
+    propagateTo?: string[]
+    logFailures?: boolean
+    /** Export a browser-side root span per request (default true) so the waterfall starts in the browser. */
+    sendSpans?: boolean
+    /** Service name for browser spans (default "<source>-browser"). */
+    serviceName?: string
+  }): () => void
+  /** Send anything still buffered. keepalive=true during page unload. */
+  flush(keepalive?: boolean): Promise<void>
+  /** Flush and detach global listeners. */
+  close(): Promise<void>
+}
+export default ZipLoggerBrowser
+
+// ./react
+import type * as ReactNamespace from 'react'
+export declare function createErrorBoundary(
+  React: typeof ReactNamespace,
+  client: ZipLoggerBrowser,
+): ReactNamespace.ComponentType<{
+  children?: ReactNamespace.ReactNode
+  fallback?: ReactNamespace.ReactNode
+  name?: string
+  onError?: (error: unknown, info: { componentStack?: string }) => void
+}>
+export declare function createUseZipLogger(
+  React: typeof ReactNamespace,
+  client: ZipLoggerBrowser,
+): () => {
+  captureError: (error: unknown, fields?: Record<string, unknown>) => void
+  log: (entry: BrowserLogEntry) => void
+}

package/index.js

@@ -0,0 +1,327 @@
+/**
+ * ZipLogger browser SDK.
+ *
+ * Same delivery semantics as every ZipLogger SDK — bounded queue, NDJSON batches,
+ * retry with backoff honoring 429 Retry-After, drop-on-backpressure, never throws —
+ * tuned for the browser: smaller defaults, `fetch(..., { keepalive: true })` so a
+ * final flush survives page unload, and automatic page context on every event.
+ *
+ * Zero dependencies. Works in any environment with `fetch` (tests run under Node).
+ */
+
+const SEVERITIES = new Set(['debug', 'info', 'warn', 'error', 'fatal'])
+const HAS_WINDOW = typeof window !== 'undefined'
+
+/** Cryptographically-random lowercase hex, for W3C trace/span ids. */
+function randomHex(bytes) {
+  const buf = new Uint8Array(bytes)
+  globalThis.crypto.getRandomValues(buf)
+  let out = ''
+  for (const b of buf) out += b.toString(16).padStart(2, '0')
+  return out
+}
+
+export class ZipLoggerBrowser {
+  /** @param {import('./index').BrowserOptions} options */
+  constructor(options) {
+    if (!options || !options.endpoint) throw new Error('ZipLogger: endpoint is required')
+    if (!options.apiKey) throw new Error('ZipLogger: apiKey is required')
+
+    const trimmed = String(options.endpoint).replace(/\/+$/, '')
+    this._url = /\/logs$/i.test(trimmed) ? trimmed : trimmed + '/ingest/v1/logs'
+    this._apiKey = options.apiKey
+    this._source = options.source || (HAS_WINDOW ? window.location.hostname : 'browser')
+    this._release = options.release
+    this._commitSha = options.commitSha
+    this._environment = options.environment || 'production'
+    this._tags = Array.isArray(options.tags) && options.tags.length ? options.tags : undefined
+    this._includePageContext = options.includePageContext !== false
+
+    this._queueCapacity = options.queueCapacity ?? 1_000
+    this._batchSize = options.batchSize ?? 20
+    this._flushInterval = options.flushIntervalMs ?? 3_000
+    this._maxRetries = options.maxRetries ?? 2
+    this._retryBaseDelay = options.retryBaseDelayMs ?? 500
+
+    this.dropped = 0
+    this._queue = []
+    this._timer = null
+    this._sending = Promise.resolve()
+    this._detach = []
+
+    if (HAS_WINDOW) {
+      const onHide = () => { void this.flush(true) }
+      window.addEventListener('pagehide', onHide)
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') onHide()
+      })
+      this._detach.push(() => window.removeEventListener('pagehide', onHide))
+    }
+  }
+
+  /**
+   * Queue one event for background delivery. Never blocks, never throws.
+   * @param {import('./index').BrowserLogEntry} entry
+   */
+  log(entry) {
+    if (this._queue.length >= this._queueCapacity) { this.dropped++; return }
+
+    const fields = { environment: this._environment, ...entry.fields }
+    if (this._includePageContext && HAS_WINDOW) {
+      fields.url = window.location.href
+      fields.userAgent = navigator.userAgent
+    }
+    const record = {
+      timestamp: entry.timestamp ?? new Date().toISOString(),
+      severity: SEVERITIES.has(entry.severity) ? entry.severity : 'info',
+      message: entry.message ?? '',
+      source: entry.source ?? this._source,
+      release: entry.release ?? this._release,
+      commitSha: entry.commitSha ?? this._commitSha,
+      stackTrace: entry.stackTrace,
+      fields,
+      tags: entry.tags ?? this._tags,
+    }
+    if (entry.error instanceof Error) {
+      record.stackTrace = record.stackTrace ?? (entry.error.stack || String(entry.error))
+      fields.exceptionType = entry.error.name
+      fields.exceptionMessage = entry.error.message
+    }
+    delete record.error
+
+    this._queue.push(record)
+    this._schedule(this._queue.length >= this._batchSize ? 0 : this._flushInterval)
+  }
+
+  /** Convenience: report a caught error with optional context. */
+  captureError(error, fields) {
+    this.log({
+      severity: 'error',
+      message: error && error.message ? error.message : String(error),
+      error: error instanceof Error ? error : undefined,
+      fields,
+    })
+  }
+
+  /**
+   * Start capturing window `error` and `unhandledrejection` events.
+   * Returns a function that stops capturing.
+   */
+  captureGlobalErrors() {
+    if (!HAS_WINDOW) return () => {}
+    const onError = (event) => {
+      this.log({
+        severity: 'error',
+        message: event.message || 'Uncaught error',
+        error: event.error instanceof Error ? event.error : undefined,
+        fields: { file: event.filename, line: event.lineno, column: event.colno, handler: 'window.onerror' },
+      })
+    }
+    const onRejection = (event) => {
+      const reason = event.reason
+      this.log({
+        severity: 'error',
+        message: reason && reason.message ? `Unhandled rejection: ${reason.message}` : 'Unhandled promise rejection',
+        error: reason instanceof Error ? reason : undefined,
+        fields: { handler: 'unhandledrejection' },
+      })
+    }
+    window.addEventListener('error', onError)
+    window.addEventListener('unhandledrejection', onRejection)
+    const stop = () => {
+      window.removeEventListener('error', onError)
+      window.removeEventListener('unhandledrejection', onRejection)
+    }
+    this._detach.push(stop)
+    return stop
+  }
+
+  /**
+   * Instrument `window.fetch` for distributed tracing: every outgoing request to your own
+   * backend gets a W3C `traceparent` header, so the server continues the SAME trace — a failed
+   * browser call and its backend waterfall share one trace id in ZipLogger. Failed requests
+   * (HTTP >= 400 or network errors) are logged automatically with that trace id, which becomes
+   * a "View trace" link on the server.
+   *
+   * Propagation targets: same-origin requests by default; pass `propagateTo` (array of origin
+   * prefixes, e.g. ["https://api.mycompany.com"]) for cross-origin APIs you control — those
+   * servers must allow the `traceparent` header in CORS. Returns a function that stops
+   * instrumenting.
+   *
+   * @param {{ propagateTo?: string[], logFailures?: boolean }} [options]
+   */
+  instrumentFetch(options = {}) {
+    if (!HAS_WINDOW || typeof window.fetch !== 'function') return () => {}
+    const propagateTo = options.propagateTo || []
+    const logFailures = options.logFailures !== false
+    const sendSpans = options.sendSpans !== false
+    const serviceName = options.serviceName || `${this._source}-browser`
+    const ingestOrigin = this._url.split('/').slice(0, 3).join('/')
+    const original = window.fetch.bind(window)
+    const self = this
+    const spanQueue = []
+    let spanTimer = null
+
+    const shouldPropagate = (url) => {
+      if (url.startsWith(ingestOrigin)) return false // never trace our own telemetry shipping
+      if (url.startsWith(window.location.origin) || url.startsWith('/')) return true
+      return propagateTo.some((origin) => url.startsWith(origin))
+    }
+
+    // Ship the browser-side root spans over OTLP/JSON, so the ZipLogger waterfall shows the
+    // request from the user's browser down through every backend service — one trace.
+    const flushSpans = () => {
+      spanTimer = null
+      if (spanQueue.length === 0) return
+      const spans = spanQueue.splice(0, spanQueue.length)
+      const payload = {
+        resourceSpans: [{
+          resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+          scopeSpans: [{ spans }],
+        }],
+      }
+      void original(`${ingestOrigin}/v1/traces`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Api-Key': self._apiKey },
+        body: JSON.stringify(payload),
+        keepalive: true,
+      }).catch(() => {})
+    }
+    const enqueueSpan = (span) => {
+      if (!sendSpans) return
+      spanQueue.push(span)
+      if (spanTimer === null) spanTimer = setTimeout(flushSpans, self._flushInterval)
+    }
+
+    window.fetch = async function (input, init) {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      if (!shouldPropagate(String(url))) return original(input, init)
+
+      const traceId = randomHex(16)
+      const spanId = randomHex(8)
+      const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined))
+      headers.set('traceparent', `00-${traceId}-${spanId}-01`)
+
+      const method = (init?.method || (input instanceof Request ? input.method : 'GET')).toUpperCase()
+      const path = String(url).replace(/^https?:\/\/[^/]+/, '') || '/'
+      const startNs = String(BigInt(Date.now()) * 1000000n)
+      const finish = (status, errorMessage) => {
+        enqueueSpan({
+          traceId, spanId,
+          name: `${method} ${path.split('?')[0]}`,
+          kind: 'SPAN_KIND_CLIENT',
+          startTimeUnixNano: startNs,
+          endTimeUnixNano: String(BigInt(Date.now()) * 1000000n),
+          attributes: [
+            { key: 'url.full', value: { stringValue: String(url) } },
+            { key: 'http.request.method', value: { stringValue: method } },
+            ...(status ? [{ key: 'http.response.status_code', value: { intValue: String(status) } }] : []),
+          ],
+          ...(errorMessage || (status && status >= 400)
+            ? { status: { code: 'STATUS_CODE_ERROR', message: errorMessage || `HTTP ${status}` } }
+            : {}),
+        })
+      }
+
+      try {
+        const response = await original(input, { ...init, headers })
+        finish(response.status)
+        if (logFailures && response.status >= 400) {
+          self.log({
+            severity: response.status >= 500 ? 'error' : 'warn',
+            message: `${method} ${url} failed with HTTP ${response.status}`,
+            fields: { traceId, spanId, httpStatus: response.status, requestUrl: String(url) },
+          })
+        }
+        return response
+      } catch (error) {
+        const message = error && error.message ? error.message : 'network error'
+        finish(null, message)
+        if (logFailures) {
+          self.log({
+            severity: 'error',
+            message: `${method} ${url} failed: ${message}`,
+            error: error instanceof Error ? error : undefined,
+            fields: { traceId, spanId, requestUrl: String(url) },
+          })
+        }
+        throw error
+      }
+    }
+
+    const stop = () => {
+      window.fetch = original
+      if (spanTimer !== null) { clearTimeout(spanTimer); flushSpans() }
+    }
+    this._detach.push(stop)
+    return stop
+  }
+
+  _schedule(delay) {
+    if (this._timer !== null) {
+      if (delay > 0) return
+      clearTimeout(this._timer)
+    }
+    this._timer = setTimeout(() => {
+      this._timer = null
+      this._sending = this._sending.then(() => this._drain(false)).catch(() => {})
+    }, delay)
+    if (typeof this._timer === 'object' && this._timer.unref) this._timer.unref()
+  }
+
+  async _drain(keepalive) {
+    while (this._queue.length > 0) {
+      const batch = this._queue.splice(0, this._batchSize)
+      await this._send(batch, keepalive)
+    }
+  }
+
+  async _send(batch, keepalive) {
+    const payload = batch.map((e) => JSON.stringify(e)).join('\n')
+
+    for (let attempt = 0; ; attempt++) {
+      let retryAfterMs = null
+      try {
+        const response = await fetch(this._url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-ndjson', 'X-Api-Key': this._apiKey },
+          body: payload,
+          keepalive, // survives page unload (64 KB budget — batches are small)
+        })
+        if (response.ok) return
+        if (response.status !== 429 && response.status !== 408 && response.status < 500) {
+          this.dropped += batch.length
+          return
+        }
+        const header = response.headers.get('retry-after')
+        if (header && !Number.isNaN(Number(header))) retryAfterMs = Number(header) * 1000
+      } catch {
+        // offline / network failure — transient
+      }
+
+      if (keepalive || attempt >= this._maxRetries) {
+        this.dropped += batch.length // unloading pages don't get retries
+        return
+      }
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, Math.min(retryAfterMs ?? this._retryBaseDelay * 2 ** attempt, 10_000))
+        if (typeof timer === 'object' && timer.unref) timer.unref()
+      })
+    }
+  }
+
+  /** Send anything still buffered. Pass keepalive=true during page unload. */
+  async flush(keepalive = false) {
+    if (this._timer !== null) { clearTimeout(this._timer); this._timer = null }
+    this._sending = this._sending.then(() => this._drain(keepalive)).catch(() => {})
+    await this._sending
+  }
+
+  /** Flush and detach all global listeners. */
+  async close() {
+    for (const stop of this._detach.splice(0)) stop()
+    await this.flush()
+  }
+}
+
+export default ZipLoggerBrowser

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ziplogger/browser",
+  "version": "0.3.3",
+  "description": "ZipLogger browser SDK \u2014 capture console errors, unhandled rejections, and custom events from web apps, with a React error boundary. Zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./react": {
+      "types": "./index.d.ts",
+      "default": "./react.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/client.test.mjs"
+  },
+  "keywords": [
+    "ziplogger",
+    "logging",
+    "browser",
+    "react",
+    "error-tracking"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahaliav/ZipLogger_Client.git",
+    "directory": "sdk_browser"
+  },
+  "homepage": "https://ziplogger.dev",
+  "bugs": {
+    "url": "https://github.com/ahaliav/ZipLogger_Client/issues"
+  },
+  "author": "Ahaliav Fox",
+  "files": [
+    "README.md",
+    "index.d.ts",
+    "index.js",
+    "react.js"
+  ]
+}

package/react.js

@@ -0,0 +1,61 @@
+/**
+ * React integration for @ziplogger/browser.
+ *
+ * The factory pattern keeps this package dependency-free — pass your React in:
+ *
+ *   import React from 'react'
+ *   import { ZipLoggerBrowser } from '@ziplogger/browser'
+ *   import { createErrorBoundary } from '@ziplogger/browser/react'
+ *
+ *   const ziplogger = new ZipLoggerBrowser({ endpoint: '...', apiKey: 'zk_...' })
+ *   const ZipLoggerErrorBoundary = createErrorBoundary(React, ziplogger)
+ *
+ *   <ZipLoggerErrorBoundary fallback={<p>Something went wrong.</p>}>
+ *     <App />
+ *   </ZipLoggerErrorBoundary>
+ */
+
+/**
+ * @param {typeof import('react')} React
+ * @param {import('./index').ZipLoggerBrowser} client
+ */
+export function createErrorBoundary(React, client) {
+  return class ZipLoggerErrorBoundary extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { hasError: false }
+    }
+
+    static getDerivedStateFromError() {
+      return { hasError: true }
+    }
+
+    componentDidCatch(error, info) {
+      client.log({
+        severity: 'error',
+        message: `React error boundary: ${error && error.message ? error.message : String(error)}`,
+        error: error instanceof Error ? error : undefined,
+        fields: {
+          componentStack: info && info.componentStack ? String(info.componentStack).trim() : undefined,
+          boundary: this.props.name || 'ZipLoggerErrorBoundary',
+        },
+      })
+      if (this.props.onError) this.props.onError(error, info)
+    }
+
+    render() {
+      if (this.state.hasError) return this.props.fallback ?? null
+      return this.props.children
+    }
+  }
+}
+
+/** Convenience hook factory: returns a stable `captureError(error, fields)` callback. */
+export function createUseZipLogger(React, client) {
+  return function useZipLogger() {
+    return React.useMemo(() => ({
+      captureError: (error, fields) => client.captureError(error, fields),
+      log: (entry) => client.log(entry),
+    }), [])
+  }
+}