@userz-ai/node

Server-side SDK for Userz. Two responsibilities, both small:

1. Mint private-mode user tokens so the widget can prove an end-user is authorized to submit feedback for your App.
2. Verify outbound webhook signatures so your handler can trust events we POST to it.

Install

pnpm add @userz-ai/node

Requires Node 18+. Pure ESM. Built on jose for JWT signing.

mintUserToken(input, options?)

Sign an HS256 JWT proving an end-user is authorized to submit feedback for a given App. Pass it back to the browser (e.g. via your /me endpoint) and configure the widget with getUserToken.

import { mintUserToken } from '@userz-ai/node';

const token = await mintUserToken(
  {
    appId: process.env.USERZ_APP_ID!,
    signingSecret: process.env.USERZ_APP_SIGNING_SECRET!,
    sub: user.id,
    ctx: { email: user.email, plan: user.plan }, // optional
  },
  { expiresInSeconds: 60 * 60 }, // default 1 hour, max 24 hours
);

Input

| Field | Type | Required | Notes | |---|---|---|---| | appId | string | yes | The 24-char hex App id from the dashboard. Stamped into the JWT's app claim. | | signingSecret | string \| Uint8Array | yes | The App's per-App signing secret. Hex / base64 / raw string accepted. Server-only. | | sub | string | yes | The end-user's id in your system. | | ctx | Record<string, unknown> | no | Surfaces in the feedback row's submitter.claims. ≤ 2 KB JSON. |

Options

| Field | Type | Notes | |---|---|---| | expiresInSeconds | number | TTL in seconds. Default 3600. Max 86400. Min 60. |

The signing secret is a bearer credential — anyone with it can mint tokens that pose as any user in your App. Never commit it. Never expose it to the browser. Rotate via the App settings page if it leaks.

verifyWebhookSignature(input)

For customers subscribing to outbound webhooks. Verifies the X-Userz-Signature header in the format t=<ms>,v1=<hex-hmac> with replay protection.

import { verifyWebhookSignature } from '@userz-ai/node';
import express from 'express';

const app = express();

// Use raw body so the signature includes the exact bytes we sent.
app.post(
  '/userz-webhook',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const ok = verifyWebhookSignature({
      signingSecret: process.env.USERZ_WEBHOOK_SECRET!,
      body: req.body,
      signatureHeader: req.header('x-userz-signature') ?? '',
      // toleranceMs defaults to 5 minutes
    });
    if (!ok) return res.status(400).send('bad signature');
    // …handle event
    res.sendStatus(200);
  },
);

body may be a Buffer, Uint8Array, or string. Constant-time compare; no exception is thrown on bad signatures — you get false.

Express recipe — issue tokens on /me

The common pattern is to piggyback on whatever endpoint your SPA already calls to fetch the current user:

app.get('/me', requireAuth, async (req, res) => {
  const userzToken = await mintUserToken({
    appId: env.USERZ_APP_ID,
    signingSecret: env.USERZ_APP_SIGNING_SECRET,
    sub: req.user.id,
    ctx: { email: req.user.email },
  });
  res.json({ user: req.user, userzToken });
});

// In your React app:
const { data } = useSWR('/me');
<UserzProvider
  publicKey="pub_..."
  apiUrl="https://api.userz.ai"
  getUserToken={() => data?.userzToken}
>...

Docs

Full reference at userz.ai/docs/sdk/node. Source on GitHub.

License

MIT