API Reference

Complete function reference for @poluruprvn/pug-web.

Package: @poluruprvn/pug-web
Source: cotton-web-sdk

Functions

Function	Signature	Description
`init`	`init(projectId: string, options: InitOptions): void`	Initialize the SDK. Must be called first.
`destroy`	`destroy(): void`	Tear down trackers, flush queue, remove listeners
`reset`	`reset(): void`	Clear identity; start fresh anonymous session
`rotate`	`rotate(): void`	Force new session ID without clearing identity
`track`	`track(event: string, props?: object, options?: TrackOptions): void`	Track an event. Never throws.
`identify`	`identify(externalId: string, traits?: object): void`	Link anonymous activity to a known user

`InitOptions`

Option	Type	Default	Description
`apiKey`	`string`	required	Project SDK API key
`endpoint`	`string`	—	Pug API base URL
`samplingRate`	`number`	`1`	Event sampling fraction (0–1)
`batch.maxSize`	`number`	`20`	Events per batch before flush
`batch.flushIntervalMs`	`number`	`5000`	Max ms between flushes
`session.timeoutMs`	`number`	`1800000`	Session inactivity timeout (30 min)
`autoTrack.pageView`	`boolean`	`true`	Auto page view tracking
`autoTrack.click`	`boolean`	`true`	Auto click tracking
`autoTrack.scroll`	`boolean`	`true`	Auto scroll depth tracking
`autoTrack.form`	`boolean`	`true`	Auto form interaction tracking
`autoTrack.frustration`	`boolean`	`true`	Rage/dead click detection
`dryRun`	`boolean`	`false`	Log events without sending

See Initialization for examples of each option.

`TrackOptions`

Option	Type	Description
`immediate`	`boolean`	Flush immediately, skip batch queue
`timestamp`	`Date`	Override event timestamp (for offline replay)


track('purchase', { revenue: 99, currency: 'USD' }, {
  immediate: true,
  timestamp: new Date('2026-01-15T10:00:00Z')
})

Error behavior

Function	On failure
`track()`	Silent — logs to console, never throws
`identify()`	Silent — logs to console, never throws
`init()`	Throws if called without required options

Analytics should never break your app.

Event queue internals


track() called
  → event added to in-memory queue
  → queue persisted to localStorage
  → flush triggered when:
      - queue reaches batch.maxSize (default 20)
      - batch.flushIntervalMs elapsed (default 5s)
      - immediate: true
      - page unload (beforeunload)
  → EventsService.BatchCreate via Connect RPC
  → on failure: retry with backoff

Well-known event types

TypeScript types for well-known event properties are generated from protobuf schemas:


import type { PurchaseEvent } from '@poluruprvn/pug-web'
 
track('purchase', {
  revenue: 29.99,
  currency: 'USD',
  order_id: 'ord-456'
} satisfies PurchaseEvent)

Regenerate types when protos change:


node gen-well-known-events.mjs

See Well-known events for the full schema list.