@pulseri/js 1.0.2 → 1.0.3

package/README.md

@@ -91,13 +91,17 @@ Without it, anyone who knows a user's id can send events as that user. With it,
 passes the signature along, so Pulseri can check that the call came from your app. `identify()`, `group()`, `track()`
 and `page()` all take an optional `signature`.
 
-On your server, compute an HMAC-SHA256 of the user id, in hex, with the identity verification secret from the Pulseri
-dashboard:
+On your server, compute an HMAC-SHA256 in hex, with the identity verification secret from the Pulseri dashboard, of
+`person:` followed by the user id, or of `group:` followed by the group id. The prefix keeps a person and a group that
+share an id (user 7 and company 7) from sharing a signature; a signature of the bare id is refused.
 
 ```js
 import { createHmac } from 'node:crypto'
 
-const signature = createHmac('sha256', process.env.PULSERI_IDV_SECRET).update(user.id).digest('hex')
+const sign = (kind, id) => createHmac('sha256', process.env.PULSERI_IDV_SECRET).update(`${kind}:${id}`).digest('hex')
+
+const signature = sign('person', user.id) // person:<id>
+const groupSignature = sign('group', company.id) // group:<id>
 ```
 
 Send the signature to the browser with the rest of your page data, then pass it along:
@@ -105,11 +109,13 @@ Send the signature to the browser with the rest of your page data, then pass it
 ```js
 Pulseri.identify(user.id, { plan: 'pro' }, { signature })
 Pulseri.track('checkout_completed', {}, { personId: user.id, signature })
+Pulseri.group(company.id, { seats: 12 }, { signature: groupSignature })
 ```
 
-Sign the same id you send: the user id for `identify()` and for `track()`/`page()` (`personId`), the group id for
-`group()`. For automatic page views, pass `signature` to `init()` next to `personId`, as a string or a function (read on
-every page view). Keep the secret on your server: it must never appear in browser code, a bundle or a public repository.
+Sign the same id you send, with the matching prefix: `person:` and the user id for `identify()` and for
+`track()`/`page()` (`personId`), `group:` and the group id for `group()`. For automatic page views, pass `signature` to
+`init()` next to `personId`, as a string or a function (read on every page view). Keep the secret on your server: it
+must never appear in browser code, a bundle or a public repository.
 
 ## Versioning
 

package/dist/index.d.cts

@@ -6,14 +6,14 @@ declare function init(publicKey: string, options?: {
     personId?: PersonId;
     signature?: PersonId;
 }): void;
-/** Create or update a person. Optional `email`, `name`, `groupId` and `signature` (identity verification). */
+/** Create or update a person. Optional `email`, `name`, `groupId` and `signature` (identity verification: the HMAC of `person:<externalId>`). */
 declare function identify(externalId: string, traits?: Record<string, unknown>, options?: {
     email?: string;
     name?: string;
     groupId?: string;
     signature?: string;
 }): void;
-/** Create or update a group, for example a company. Optional `name` and `signature`. */
+/** Create or update a group, for example a company. Optional `name` and `signature` (identity verification: the HMAC of `group:<externalId>`). */
 declare function group(externalId: string, traits?: Record<string, unknown>, options?: {
     name?: string;
     signature?: string;

package/dist/index.d.ts

@@ -6,14 +6,14 @@ declare function init(publicKey: string, options?: {
     personId?: PersonId;
     signature?: PersonId;
 }): void;
-/** Create or update a person. Optional `email`, `name`, `groupId` and `signature` (identity verification). */
+/** Create or update a person. Optional `email`, `name`, `groupId` and `signature` (identity verification: the HMAC of `person:<externalId>`). */
 declare function identify(externalId: string, traits?: Record<string, unknown>, options?: {
     email?: string;
     name?: string;
     groupId?: string;
     signature?: string;
 }): void;
-/** Create or update a group, for example a company. Optional `name` and `signature`. */
+/** Create or update a group, for example a company. Optional `name` and `signature` (identity verification: the HMAC of `group:<externalId>`). */
 declare function group(externalId: string, traits?: Record<string, unknown>, options?: {
     name?: string;
     signature?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulseri/js",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Pulseri browser SDK: identify, group, track and page for tenant websites, plus the in-app survey widget.",
   "license": "MIT",
   "homepage": "https://github.com/getpulseri/js#readme",