API reference

// Initialize the SDK. Starts pageview, session, and engagement tracking.
function init<E extends EventMap = AnyEvents>(
  projectId: string,
  opts?: { endpoint?: string; debug?: boolean; extensions?: ExtensionsConfig }
): void

// Track a custom event. Pro plan. Properties are flat string → string
// (or Money objects for revenue).
function track<K extends keyof E & string>(
  name: K,
  properties?: Record<string, string | Money>
): void

// Get the current visitor's anonymous ID (or null before init()).
function getAnonymousId(): string | null

interface AnalyticsProps {
  projectId: string
  endpoint?: string
  debug?: boolean
  extensions?: ExtensionsConfig
}

// Drop-in component. Calls init() in useEffect, renders null.
function Analytics(props: AnalyticsProps): JSX.Element | null

// Initialize the server SDK. Call once at startup.
function init<E extends EventMap = AnyEvents>(config: {
  projectId: string
  apiKey: string
  endpoint?: string
}): void

// Send a custom event. Pro plan. Resolves once the request completes.
function track<K extends keyof E & string>(
  name: K,
  opts?: {
    anonymousId?: string
    properties?: Record<string, string | Money>
    timestamp?: string   // ISO 8601, defaults to now
  }
): Promise<{ ok: boolean }>

// ISO 4217 currency code ("USD", "EUR", "JPY"). Three uppercase letters.
type CurrencyCode = string

// A monetary value. Attach to any event property for revenue tracking.
interface Money {
  amount: number        // major units — 29.00, not 2900
  currency: CurrencyCode
}

// Allowed property value types.
type EventPropertyValue = string | Money

// Per-event property shapes, keyed by event name. Use as a generic parameter.
type EventMap = Record<string, Record<string, EventPropertyValue> | undefined>

// Fallback when no EventMap is supplied. All event names accepted.
type AnyEvents = Record<string, Record<string, EventPropertyValue> | undefined>

<script src="https://cdn.jsdelivr.net/npm/@clamp-sh/analytics/dist/cdn.global.js"></script>
<script>
  clamp.init("proj_xxx")
</script>