@ziplogger/browser 0.3.3 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @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.
+Browser SDK for [ZipLogger](https://ziplogger.dev) — product-analytics events,
+uncaught errors, unhandled promise rejections and distributed tracing from web apps, with a
+first-class React error boundary. Zero dependencies.
 
 ```bash
 npm install @ziplogger/browser
@@ -25,6 +25,32 @@ ziplogger.log({ severity: 'info', message: 'checkout started', fields: { cartVal
 try { risky() } catch (err) { ziplogger.captureError(err, { step: 'payment' }) }
 ```
 
+## Events
+
+Events are what people did; logs are what you read when something breaks. They are separate calls
+because ZipLogger answers different questions with each.
+
+```js
+ziplogger.track('checkout_started', { cartValue: 214.9, currency: 'USD' })
+
+// After sign-in. Links everything this browser did anonymously to the account, so the visitor
+// stops being counted as two people.
+ziplogger.identify('user_42')
+
+ziplogger.reset()   // on sign-out: a fresh anonymous identity from here
+```
+
+An un-identified visitor still needs an id, or the server has nobody to attribute the event to. The
+SDK mints one on first use and keeps it in `localStorage` (`zl_anon`), with a per-tab session id in
+`sessionStorage` (`zl_sess`) — that stored anonymous id is exactly what `identify()` later links.
+Both fall back to memory when storage is unavailable, so private mode degrades to per-page
+attribution rather than an error.
+
+Every event carries an `insertId`, so a retry after a timeout cannot count it twice.
+
+**Do not put credentials in properties.** Values that look like tokens, keys or card numbers are
+redacted server-side, but the safe habit is not to send them.
+
 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.

package/index.d.ts

@@ -1,7 +1,8 @@
 export type Severity = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
 
 export interface BrowserOptions {
-  /** Base URL of the ZipLogger server, e.g. "https://logs.yourcompany.com". */
+  /** Your ZipLogger origin, e.g. "https://app.ziplogger.dev" (or your own host if
+   *  you self-host). Paths are appended for you. */
   endpoint: string
   /** Tenant ingestion API key (zk_...). Use a key dedicated to browser traffic. */
   apiKey: string
@@ -12,8 +13,15 @@ export interface BrowserOptions {
   /** Default "production". */
   environment?: string
   tags?: string[]
-  /** Attach url + userAgent fields to every event. Default true. */
+  /** Attach url + userAgent to every log line, and url + page to every event. Default true. */
   includePageContext?: boolean
+  /** Your id for the signed-in user, when the page already knows it. Otherwise call identify(). */
+  userId?: string
+  /** Override the generated anonymous id. Normally left alone: it is minted once and kept in
+   *  localStorage so a visitor's pre-login events can be linked to their account later. */
+  anonymousId?: string
+  /** Override the generated session id (per tab, kept in sessionStorage). */
+  sessionId?: string
   /** Max buffered events. Default 1000. */
   queueCapacity?: number
   /** Max events per request. Default 20. */
@@ -38,16 +46,42 @@ export interface BrowserLogEntry {
   tags?: string[]
 }
 
+export interface Identity {
+  userId: string | null
+  anonymousId: string | null
+  sessionId: string | null
+}
+
 export declare class ZipLoggerBrowser {
   constructor(options: BrowserOptions)
-  /** Events lost to backpressure or exhausted retries. */
+  /** Records lost to backpressure or exhausted retries, logs and events together. */
   dropped: number
+  /** The ids events are currently attributed to. */
+  readonly identity: Identity
   /** 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
+  /**
+   * Record a product-analytics event -- a signup, a checkout, a plan change.
+   *
+   * Distinct from log(): logs are lines you read when something breaks, events are things people
+   * did, and ZipLogger answers different questions with each. Never blocks, never throws.
+   *
+   * Values that look like credentials are redacted server-side; do not send passwords, tokens or
+   * card numbers as properties.
+   */
+  track(name: string, properties?: Record<string, unknown>): void
+  /**
+   * Attach this browser's anonymous history to a real account and use that id from now on.
+   * Call once after sign-in; the server links the ids so pre-login events stop being a separate
+   * person.
+   */
+  identify(userId: string, properties?: Record<string, unknown>): void
+  /** Forget the signed-in user and start a fresh anonymous identity, e.g. on sign-out. */
+  reset(): 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
@@ -61,7 +95,7 @@ export declare class ZipLoggerBrowser {
     /** Service name for browser spans (default "<source>-browser"). */
     serviceName?: string
   }): () => void
-  /** Send anything still buffered. keepalive=true during page unload. */
+  /** Send anything still buffered, logs and events both. keepalive=true during page unload. */
   flush(keepalive?: boolean): Promise<void>
   /** Flush and detach global listeners. */
   close(): Promise<void>
@@ -85,4 +119,6 @@ export declare function createUseZipLogger(
 ): () => {
   captureError: (error: unknown, fields?: Record<string, unknown>) => void
   log: (entry: BrowserLogEntry) => void
+  track: (name: string, properties?: Record<string, unknown>) => void
+  identify: (userId: string, properties?: Record<string, unknown>) => void
 }

package/index.js

@@ -1,5 +1,5 @@
 /**
- * ZipLogger browser SDK.
+ * ZipLogger browser SDK — logs, errors, traces and product-analytics events.
  *
  * Same delivery semantics as every ZipLogger SDK — bounded queue, NDJSON batches,
  * retry with backoff honoring 429 Retry-After, drop-on-backpressure, never throws —
@@ -29,6 +29,9 @@ export class ZipLoggerBrowser {
 
     const trimmed = String(options.endpoint).replace(/\/+$/, '')
     this._url = /\/logs$/i.test(trimmed) ? trimmed : trimmed + '/ingest/v1/logs'
+    // Events are a different endpoint with a different payload, so they get their own URL and
+    // queue rather than being squeezed through the log pipeline.
+    this._eventsUrl = trimmed.replace(/\/ingest\/v1\/logs$/i, '') + '/ingest/v1/events'
     this._apiKey = options.apiKey
     this._source = options.source || (HAS_WINDOW ? window.location.hostname : 'browser')
     this._release = options.release
@@ -49,6 +52,18 @@ export class ZipLoggerBrowser {
     this._sending = Promise.resolve()
     this._detach = []
 
+    this._events = []
+    this._eventTimer = null
+    this._eventSending = Promise.resolve()
+
+    // An event with neither a user id nor an anonymous id is rejected by the server, so a
+    // visitor who has not signed in needs a stable id of their own. It lives in localStorage so
+    // it survives reloads -- that is what lets identify() later attach their pre-login events to
+    // the account. Session id is per-tab and per-visit, so it belongs in sessionStorage.
+    this._userId = options.userId ?? null
+    this._anonymousId = options.anonymousId ?? this._persistedId('local', 'zl_anon', 'anon')
+    this._sessionId = options.sessionId ?? this._persistedId('session', 'zl_sess', 'sess')
+
     if (HAS_WINDOW) {
       const onHide = () => { void this.flush(true) }
       window.addEventListener('pagehide', onHide)
@@ -103,6 +118,91 @@ export class ZipLoggerBrowser {
     })
   }
 
+  /**
+   * Record a product-analytics event: a signup, a checkout, a plan change.
+   *
+   * Separate from `log()` on purpose. Logs are lines you read when something breaks; events are
+   * things people did, and they answer different questions in different places in ZipLogger.
+   * Never blocks, never throws.
+   *
+   * @param {string} name Event name, e.g. "checkout_started". Lower-cased server-side.
+   * @param {Record<string, unknown>} [properties] Your own properties. Values that look like
+   *   credentials are redacted server-side; do not send passwords, tokens or card numbers.
+   */
+  track(name, properties) {
+    if (!name || typeof name !== 'string') return
+    if (this._events.length >= this._queueCapacity) { this.dropped++; return }
+
+    const event = {
+      type: 'track',
+      name,
+      timestamp: new Date().toISOString(),
+      userId: this._userId ?? undefined,
+      anonymousId: this._anonymousId ?? undefined,
+      sessionId: this._sessionId ?? undefined,
+      environment: this._environment,
+      release: this._release,
+      commitSha: this._commitSha,
+      // An idempotency key, so a retry after a timeout cannot count the same event twice.
+      insertId: randomHex(12),
+      properties: properties && typeof properties === 'object' ? properties : undefined,
+    }
+    if (this._includePageContext && HAS_WINDOW) {
+      event.url = window.location.href
+      event.page = window.location.pathname
+    }
+
+    this._events.push(event)
+    this._scheduleEvents(this._events.length >= this._batchSize ? 0 : this._flushInterval)
+  }
+
+  /**
+   * Attach everything this browser has done anonymously to a real account, and use the account
+   * id from now on.
+   *
+   * Call it once after sign-in. The server links the two ids, so the events this visitor sent
+   * before signing in stop being a separate person -- which is the whole point of holding an
+   * anonymous id in the first place.
+   *
+   * @param {string} userId Your own id for the user.
+   * @param {Record<string, unknown>} [properties] Optional properties for the identify event.
+   */
+  identify(userId, properties) {
+    if (!userId || typeof userId !== 'string') return
+    const anonymousId = this._anonymousId
+
+    this._userId = userId
+    if (!anonymousId) return          // nothing to link; later events simply carry the user id
+
+    if (this._events.length >= this._queueCapacity) { this.dropped++; return }
+    this._events.push({
+      type: 'identify',
+      timestamp: new Date().toISOString(),
+      userId,
+      anonymousId,
+      sessionId: this._sessionId ?? undefined,
+      environment: this._environment,
+      insertId: randomHex(12),
+      properties: properties && typeof properties === 'object' ? properties : undefined,
+    })
+    // Linking is what every later event depends on, so it does not wait for a full batch.
+    this._scheduleEvents(0)
+  }
+
+  /** Forget the signed-in user, e.g. on sign-out. Later events are anonymous again. */
+  reset() {
+    this._userId = null
+    this._anonymousId = this._newId('anon')
+    this._sessionId = this._newId('sess')
+    this._store('local', 'zl_anon', this._anonymousId)
+    this._store('session', 'zl_sess', this._sessionId)
+  }
+
+  /** The ids this client is currently attributing events to. Useful in tests and debugging. */
+  get identity() {
+    return { userId: this._userId, anonymousId: this._anonymousId, sessionId: this._sessionId }
+  }
+
   /**
    * Start capturing window `error` and `unhandledrejection` events.
    * Returns a function that stops capturing.
@@ -257,6 +357,51 @@ export class ZipLoggerBrowser {
     return stop
   }
 
+  /** A stable id from web storage, minted on first use. Falls back to memory when storage is
+   *  unavailable (private mode, blocked cookies) -- attribution is then per-page, never an error. */
+  _persistedId(kind, key, prefix) {
+    const existing = this._read(kind, key)
+    if (existing) return existing
+    const id = this._newId(prefix)
+    this._store(kind, key, id)
+    return id
+  }
+
+  _newId(prefix) { return `${prefix}_${randomHex(10)}` }
+
+  _read(kind, key) {
+    try {
+      const store = kind === 'local' ? globalThis.localStorage : globalThis.sessionStorage
+      return store ? store.getItem(key) : null
+    } catch { return null }          // storage disabled: not an error worth surfacing
+  }
+
+  _store(kind, key, value) {
+    try {
+      const store = kind === 'local' ? globalThis.localStorage : globalThis.sessionStorage
+      if (store) store.setItem(key, value)
+    } catch { /* storage disabled; the id stays in memory for this page */ }
+  }
+
+  _scheduleEvents(delay) {
+    if (this._eventTimer !== null) {
+      if (delay > 0) return
+      clearTimeout(this._eventTimer)
+    }
+    this._eventTimer = setTimeout(() => {
+      this._eventTimer = null
+      this._eventSending = this._eventSending.then(() => this._drainEvents(false)).catch(() => {})
+    }, delay)
+    if (typeof this._eventTimer === 'object' && this._eventTimer.unref) this._eventTimer.unref()
+  }
+
+  async _drainEvents(keepalive) {
+    while (this._events.length > 0) {
+      const batch = this._events.splice(0, this._batchSize)
+      await this._post(this._eventsUrl, batch, batch.length, keepalive)
+    }
+  }
+
   _schedule(delay) {
     if (this._timer !== null) {
       if (delay > 0) return
@@ -277,12 +422,21 @@ export class ZipLoggerBrowser {
   }
 
   async _send(batch, keepalive) {
+    await this._post(this._url, batch, batch.length, keepalive)
+  }
+
+  /**
+   * One NDJSON POST with the retry policy both queues share: retry only what retrying can fix
+   * (429, 408, 5xx), honour Retry-After, and never retry during page unload -- an unloading page
+   * has no time, and a duplicate is worse than a loss when the event already carries an insertId.
+   */
+  async _post(url, batch, count, 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, {
+        const response = await fetch(url, {
           method: 'POST',
           headers: { 'Content-Type': 'application/x-ndjson', 'X-Api-Key': this._apiKey },
           body: payload,
@@ -290,7 +444,7 @@ export class ZipLoggerBrowser {
         })
         if (response.ok) return
         if (response.status !== 429 && response.status !== 408 && response.status < 500) {
-          this.dropped += batch.length
+          this.dropped += count
           return
         }
         const header = response.headers.get('retry-after')
@@ -300,7 +454,7 @@ export class ZipLoggerBrowser {
       }
 
       if (keepalive || attempt >= this._maxRetries) {
-        this.dropped += batch.length // unloading pages don't get retries
+        this.dropped += count // unloading pages don't get retries
         return
       }
       await new Promise((resolve) => {
@@ -310,11 +464,13 @@ export class ZipLoggerBrowser {
     }
   }
 
-  /** Send anything still buffered. Pass keepalive=true during page unload. */
+  /** Send anything still buffered, logs and events both. Pass keepalive=true during page unload. */
   async flush(keepalive = false) {
     if (this._timer !== null) { clearTimeout(this._timer); this._timer = null }
+    if (this._eventTimer !== null) { clearTimeout(this._eventTimer); this._eventTimer = null }
     this._sending = this._sending.then(() => this._drain(keepalive)).catch(() => {})
-    await this._sending
+    this._eventSending = this._eventSending.then(() => this._drainEvents(keepalive)).catch(() => {})
+    await Promise.all([this._sending, this._eventSending])
   }
 
   /** Flush and detach all global listeners. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.4.0",
+  "description": "ZipLogger browser SDK \u2014 product-analytics events, console errors, unhandled rejections and distributed tracing from web apps, with a React error boundary. Zero dependencies.",
   "license": "MIT",
   "type": "module",
   "main": "index.js",
@@ -22,19 +22,22 @@
   },
   "keywords": [
     "ziplogger",
+    "analytics",
+    "events",
     "logging",
     "browser",
     "react",
-    "error-tracking"
+    "error-tracking",
+    "opentelemetry"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ahaliav/ZipLogger_Client.git",
+    "url": "git+https://github.com/ziploggerhq/ZipLogger_Client.git",
     "directory": "sdk_browser"
   },
   "homepage": "https://ziplogger.dev",
   "bugs": {
-    "url": "https://github.com/ahaliav/ZipLogger_Client/issues"
+    "url": "https://github.com/ziploggerhq/ZipLogger_Client/issues"
   },
   "author": "Ahaliav Fox",
   "files": [

package/react.js

@@ -50,12 +50,14 @@ export function createErrorBoundary(React, client) {
   }
 }
 
-/** Convenience hook factory: returns a stable `captureError(error, fields)` callback. */
+/** Convenience hook factory: stable callbacks for logging, error capture and events. */
 export function createUseZipLogger(React, client) {
   return function useZipLogger() {
     return React.useMemo(() => ({
       captureError: (error, fields) => client.captureError(error, fields),
       log: (entry) => client.log(entry),
+      track: (name, properties) => client.track(name, properties),
+      identify: (userId, properties) => client.identify(userId, properties),
     }), [])
   }
 }