SDK reference

Four published packages cover every integration shape, pick by what your app already looks like, not by ours.

Packages

@userz-ai/browser

Framework-free core. Bubble + panel UI in shadow DOM, console & error capture, screenshot via modern-screenshot, presigned-upload + submit pipeline. Use directly for non-React apps.

@userz-ai/react

~3 KB gzip (peers @userz-ai/browser)

React bindings: <UserzProvider>, useUserz(), <UserzTarget> wrapper for component-targeted feedback. React 18 and 19.

@userz-ai/node

~3 KB gzip

Server SDK: mintUserToken() for private-mode JWTs, verifyWebhookSignature() for outbound webhooks. Works on Node 18+, Bun, Deno, Cloudflare Workers.

@userz-ai/api

~3.3 KB gzip

Typed REST client. apps.list(), feedback.{list,get,update}, agentRuns.get, tokens.mint, server-side use with an sk_ key. Same runtime targets as @userz-ai/node.

Which package do I want?

React app, you control the build → @userz-ai/react + @userz-ai/browser (peer).
Vue / Svelte / Solid / vanilla, you control the build → @userz-ai/browser directly. See its docs for the framework-specific recipes.
No build, no React, drop a script tag in HTML → use the IIFE bundle at https://cdn.userz.ai/v1/userz.js.
You need to mint per-user tokens or verify our outbound webhooks on a server → @userz-ai/node (works on Node, Bun, Deno, Workers).
You're calling our REST API from a backend (read feedback, list apps, fetch agent runs, mint tokens over HTTP) → @userz-ai/api: a typed client with sk_-key auth. Same runtime targets as @userz-ai/node.

The five-minute integration

A typical Next.js app (with any auth library), end-to-end. You add three things: (1) an env var, (2) a server endpoint that mints the user token, (3) a client provider.

Bash

# .env.local
USERZ_APP_ID=65fa1f3e8a1e5f2d9c1a5c01
USERZ_APP_SIGNING_SECRET=<from-dashboard, base64>
NEXT_PUBLIC_USERZ_PUBLIC_KEY=pub_GLLHdYCLb2A2d9ieY2LmmwRJ

TypeScript

// app/api/me/route.ts, mints a fresh Userz token alongside the user
import { NextResponse } from 'next/server';
import { mintUserToken } from '@userz-ai/node';
import { getSession } from '@/lib/auth';

export async function GET() {
  const session = await getSession();
  if (!session) return NextResponse.json({ user: null });
  const userzToken = await mintUserToken({
    appId: process.env.USERZ_APP_ID!,
    signingSecret: process.env.USERZ_APP_SIGNING_SECRET!,
    sub: session.user.id,
    ctx: { email: session.user.email },
  });
  return NextResponse.json({ user: session.user, userzToken });
}

TSX

// app/Userz.tsx, wraps the app with the widget
'use client';
import useSWR from 'swr';
import { UserzProvider } from '@userz-ai/react';

export function Userz({ children }: { children: React.ReactNode }) {
  const { data } = useSWR('/api/me', (u) => fetch(u).then((r) => r.json()));
  return (
    <UserzProvider
      publicKey={process.env.NEXT_PUBLIC_USERZ_PUBLIC_KEY!}
      getUserToken={() => data?.userzToken}
    >
      {children}
    </UserzProvider>
  );
}

// app/layout.tsx
import { Userz } from './Userz';
export default function Layout({ children }: { children: React.ReactNode }) {
  return <html><body><Userz>{children}</Userz></body></html>;
}

That's the full integration. The widget renders its own bubble, opens a panel on click, captures console + screenshot, hits our presigned-upload + submit pipeline, and ships the report into your dashboard. No custom UI required.

Versioning + stability

All three packages follow semver. Breaking changes ship in major versions; additive changes (new methods, new optional fields) ship in minors. We publish with npm provenance attestation on, so npm shows a verified build link on every release. Subscribe to the changelog for what landed when.