VVEREID Docs
Search docsGitHub
sdks

SDK — JavaScript / TypeScript

@vereid/js — the universal isomorphic SDK for VEREID Social, Auth, and Identity.

Last updated 2026-05-20

@vereid/js is the universal SDK. It runs in Node ≥18, every modern browser (via the /browser entry), Bun, Deno, and edge runtimes (Vercel Edge, Cloudflare Workers). It is the dependency that powers @vereid/react, the CLI, and the official Auth/Identity reference apps.

Install

npm install @vereid/js
# or
pnpm add @vereid/js
# or
yarn add @vereid/js

The package ships ESM and CJS entry points, full TypeScript types, and a slim browser build.

Quickstart

import { Vereid } from "@vereid/js";
 
const vereid = new Vereid({ apiKey: process.env.VEREID_API_KEY });
 
// Social
const profile = await vereid.social.profiles.get("@mina");
 
// Auth — server-side authorization code exchange
const tokens = await vereid.auth.exchangeCode({
  code,
  codeVerifier,
  redirectUri: "https://yourapp.com/auth/callback",
});
 
// Identity
const session = await vereid.verify.sessions.create({
  tiers: ["T1", "T2"],
  reference: "user_42",
});

Configuration

const vereid = new Vereid({
  apiKey: process.env.VEREID_API_KEY, // required, server-side
  baseUrl: "https://api.vereid.com", // default
  timeoutMs: 10_000, // per-request
  retry: { maxAttempts: 5, baseMs: 250 }, // honours retry-after
  userAgent: "myapp/1.4.2",
  fetch: globalThis.fetch, // injectable for testing
});

Promise vs streaming

All list endpoints return both a thenable page and an async iterator over every page. Iterate with for await:

for await (const post of vereid.social.timeline.iterate("@mina")) {
  console.log(post.body);
}

The iterator transparently follows next_cursor and stops when the timeline is exhausted.

Webhook verification helper

A first-class helper bundled with the SDK — same algorithm as the Webhooks page, but you do not need to copy it:

import { verifyWebhook } from "@vereid/js/webhooks";
 
app.post("/webhooks/vereid", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verifyWebhook(req.body, req.header("vereid-signature"), SECRET);
  if (!ok) return res.status(400).end();
  // ... handle event
  res.status(204).end();
});

Browser build

The @vereid/js/browser entry exposes only the safe subset — public read endpoints, OIDC PKCE helpers, hosted-flow redirectors. It refuses to accept an API key, so accidental client-side key exposure is impossible.

import { VereidBrowser } from "@vereid/js/browser";
 
const vereid = new VereidBrowser({ clientId: "app_••••" });
const challenge = await vereid.auth.beginPkce({
  redirectUri: window.location.origin + "/callback",
  scope: "openid email profile vereid:verification",
});
window.location.href = challenge.authorizationUrl;

Error handling

Every error thrown by the SDK is a subclass of VereidError and carries the RFC 9457 problem document plus the request ID for support tickets:

try {
  await vereid.verify.sessions.create({ tiers: ["T7"] });
} catch (e) {
  if (e instanceof VereidValidationError) {
    console.error(e.detail, "request_id:", e.requestId);
  }
}

Testing

@vereid/js/test exports a MockVereid you can swap in for the real client. It records every call and lets you script responses without an HTTP server:

import { MockVereid } from "@vereid/js/test";
 
const vereid = new MockVereid();
vereid.verify.sessions.create.mockResolvedValueOnce({
  id: "vs_test",
  status: "pending",
  hosted_url: "https://id.vereid.com/s/test",
});

Compatibility

  • Node 18, 20, 22, 24
  • Bun 1.x
  • Deno 1.x with --allow-net=api.vereid.com
  • Cloudflare Workers / Vercel Edge runtime
  • Chrome, Firefox, Safari ≥ 16, Edge

Versioning

Semver. Breaking changes only on major bumps. The full changelog ships at npm/@vereid/js and is mirrored on the docs changelog.