Chokhdocs
GitHub

Events from your server

Send what your server knows, an order paid or a signup completed, and sign who a page says it is.

@chokh/sdk-node needs nothing beyond Node's own library, Node 22 or newer, and works as an ES module or CommonJS. It is not on npm yet: it is published with Chokh's first release.

npm install @chokh/sdk-node

Send events

Make a key for the site with the write:events scope, signed in as an admin of the site, and keep it on the server. The token is shown once, in the answer:

curl -b jar -X POST https://analytics.example.com/api/sites/my_site/keys \
  -H 'content-type: application/json' \
  -d '{"name":"Checkout server","scopes":["write:events"]}'
import { createClient } from '@chokh/sdk-node';

const chokh = createClient({
  url: process.env.CHOKH_URL ?? '', // https://analytics.example.com
  siteId: process.env.CHOKH_SITE ?? '', // my_site
  apiKey: process.env.CHOKH_API_KEY ?? '', // a key with write:events, never in a page
});

// Return at once and never throw: the events go in the background.
chokh.identify('u_42', { plan: 'pro' });
chokh.track('u_42', 'order_paid', { value: 1200, path: '/checkout', props: { currency: 'BDT' } });

// Before the process exits, send what is still queued.
await chokh.shutdown();

track and identify return at once and never throw: the events wait in a queue and go in the background, so analytics is never the reason a request hangs. Delivery is at least once: a batch the network lost after Chokh stored it may be sent again.

Pass the browser's visitor id when you know it, and the event joins the visit that person is in the middle of.

Sign an identify

A page can call identify with any id, and a forged one would be one visitor reading another's history. So a site can refuse an identify that is not signed, and keep the signing secret on its server:

import { signUserId } from '@chokh/sdk-node';

// On your server, where the page reads its own session: a signature the page
// passes to identify, so nobody can claim to be somebody else.
export function identifySignature(userId: string): string {
  return signUserId(process.env.CHOKH_IDENTIFY_SECRET ?? '', 'my_site', userId);
}

The page then passes the signature as the fourth argument: pa('identify', user.id, { plan: 'pro' }, signature). The secret is shown once, when the site is made, and again only when it is changed. It never reaches a browser.

The signature is one line, so a server in any language can make it:

base64url(hmac_sha256(identifySecret, siteId + "\n" + userId))

Edit this page on GitHub

Chokhdocs

Chokh on GitHub