@userz-ai/api

Typed REST client for the Userz API. Server-side use with an sk_ key.

This is the typed counterpart to hand-rolling fetch calls against https://api.userz.ai/v1/*. Types are stable per major version; the underlying spec is published at https://api.userz.ai/openapi.json.

Install

pnpm add @userz-ai/api

Zero runtime deps. Pure ESM. Works on Node 18+, Bun, Deno, and Cloudflare Workers — anywhere fetch is available.

Quick start

import { createUserzApi } from '@userz-ai/api';

const userz = createUserzApi({
  apiKey: process.env.USERZ_API_KEY!, // sk_...
});

// List feedback for the authenticated Org
const { data, nextCursor } = await userz.feedback.list({ limit: 50 });

// Drill into one
const fb = await userz.feedback.get(data[0].id);

// Move a sanitized item into the agent queue (manual mode)
await userz.feedback.update(fb.id, { status: 'queued' });

Reference

| Namespace | Method | Endpoint | |---|---|---| | apps | list() | GET /v1/apps | | feedback | list(query?) | GET /v1/feedback | | feedback | get(id) | GET /v1/feedback/:id | | feedback | update(id, body) | PATCH /v1/feedback/:id | | agentRuns | get(id) | GET /v1/agent-runs/:id | | tokens | mint({ appId, body }) | POST /v1/tokens/mint?appId=… | | raw | raw({ method, path, query?, body? }) | escape hatch |

Inputs and outputs are typed end-to-end. See src/types.ts for the wire shapes (FeedbackFull, AgentRun, App, MintTokenBody, etc.).

Errors

Non-2xx responses throw UserzApiError. The HTTP status, the server's stable error code, and the optional details bag are all on the thrown error:

import { UserzApiError } from '@userz-ai/api';

try {
  await userz.feedback.get(id);
} catch (err) {
  if (err instanceof UserzApiError) {
    if (err.code === 'rate_limited') {
      await sleep(err.body.retryAfterMs ?? 1000);
      return retry();
    }
    if (err.code === 'not_found') {
      return null;
    }
    console.error(`Userz API ${err.status} ${err.code} (request id ${err.requestId})`);
  }
  throw err;
}

The full set of stable error codes is exported as the ApiErrorCode union.

Options

createUserzApi({
  apiKey: '…',
  baseUrl: 'https://api.userz.ai',  // override for self-hosted / staging
  fetch: customFetch,                // inject for tests, edge runtimes
  timeoutMs: 30_000,                 // 0 disables
  userAgent: 'my-app/1.0.0',
});

Minting widget tokens (private mode)

For private-mode submissions, mint a per-user JWT on your server and pass it to the widget. You can do that two ways:

1. In-process with @userz-ai/node — no network call, signs locally with the App's signing secret.
2. Via the REST endpoint — call userz.tokens.mint(...) here. The server signs with the App's secret (so your sk_ key never sees the secret).

The REST path is the right choice if your backend runs in many languages or you don't want each service to hold the App signing secret:

const { token, expiresInSeconds } = await userz.tokens.mint({
  appId: process.env.USERZ_APP_ID!,
  body: { sub: user.id, ctx: { email: user.email } },
});
return res.json({ user, userzToken: token, userzExpiresIn: expiresInSeconds });

Type definitions

Everything in src/types.ts is exported from the package root. You can use the types independently of the client:

import type { FeedbackStatus, AgentRun } from '@userz-ai/api';

Versioning

Semver. Breaking changes ship in major versions; additive (new endpoints, new optional fields) ships in minors. The runtime client and the published types track the underlying API on the same major-version line — @userz-ai/[email protected] follows /v1/*, @userz-ai/[email protected] will follow /v2/* when that lands.

License

MIT