Usage

import Watchmen, { Context } from '@watchmen/js'

const ctx = new Context({
    userId: 'xxxx',
    userName: 'Ray-D-Song'
})

// The ctx is reactive(by alien-signals)
// So you can change the value anytime

ctx.value.userName = 'Jenny'

const wm = new Watchmen({
    key: 'xxx',
    endpoint: 'https://watchmen.com',
    // any json payload
    context: ctx,
    options: {
        recordDuration: true,
        batchSend: false // default true
    }
})

await wm.send({
    // any json payload
    type: 'page_view'
})

const userWm = wm.createGroup(['user'])

await userWm.send({
    // any json payload
    action: 'click_login'
})

Event shape

send() posts JSON to ${endpoint}/api/v1/events by default.

The SDK key is sent with the X-Watchmen-Key request header.

When batchSend is false, the SDK sends a single event:

{
  "payload": {},
  "context": {},
  "group": ["user"],
  "timestamp": "2026-06-04T00:00:00.000Z",
  "durationMs": 1234,
  "sdk": {
    "name": "@watchmen/js",
    "version": "0.1.0"
  },
  "runtime": {
    "url": "https://app.example.com",
    "userAgent": "..."
  }
}

When batchSend is true, the SDK queues events and sends:

{
  "events": []
}

Call await wm.flush() to send queued events immediately.

Build

This package uses Microsoft's TypeScript-Go preview compiler.

pnpm install
pnpm build

Build output:

• dist/index.js
• dist/index.d.ts