@verdigris/client

Typed oRPC client for the Verdigris API. Exposes the API contract tree and a createClient(options) factory that wraps oRPC's OpenAPILink for use in browsers and Node 18+.

Contract barrel generator, createClient factory, and Vite ESM build are implemented. Type declarations are bundled into a single self-contained dist/index.d.ts with no workspace-relative paths.

Install

pnpm add @verdigris/client zod

Usage

The API uses JWT authorization issued via OAuth 2.0. Pass an auth option (or a headers function) to supply a bearer token on every request.

Machine-to-machine (client credentials)

For server-side / Node.js applications. Tokens are cached and refreshed automatically.

[!CAUTION] Security: clientSecret is a confidential credential.

Server/Node only — never ship in browser-delivered code.

import {
  createClient,
  createClientCredentialsTokenProvider,
} from "@verdigris/client";

const provider = createClientCredentialsTokenProvider({
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!, // server-only
});

const client = createClient({
  url: "https://api.verdigris.co/v3",
  auth: provider,
});

const buildings = await client.buildings.list({ query: {} });

Interactive login — PKCE (recommended for SPAs)

For single-page applications. Uses authorization_code + PKCE — the recommended browser flow. Include offline_access in scope to receive a refresh token for silent token renewal.

import { createClient, createPkceAuth } from "@verdigris/client";

// ── Step 1: initiate login (redirect to Auth0) ────────────────────────────
const pkce = createPkceAuth({
  clientId: "your-auth0-client-id",
  redirectUri: `${location.origin}/auth/callback`,
  scope: "openid profile offline_access",
});

// On your login button click:
await pkce.login(); // redirects browser to Auth0

// ── Step 2: handle the callback ────────────────────────────────────────────
// Re-construct with the same options on the callback page:
const pkce = createPkceAuth({
  clientId: "your-auth0-client-id",
  redirectUri: `${location.origin}/auth/callback`,
});
await pkce.handleRedirectCallback(); // exchanges code → token

// ── Step 3: use the client ─────────────────────────────────────────────────
const client = createClient({
  url: "https://api.verdigris.co/v3",
  auth: pkce.provider, // refreshes silently via refresh_token
});

Interactive login — implicit (legacy SPAs)

[!WARNING] Deprecated: Prefer createPkceAuth for new applications. The implicit flow exposes the access token in the URL fragment (browser history / Referer leakage) and does not support refresh tokens.

import { createClient, createImplicitAuth } from "@verdigris/client";

// ── Step 1: initiate login ─────────────────────────────────────────────────
const implicit = createImplicitAuth({
  clientId: "your-auth0-client-id",
  redirectUri: `${location.origin}/auth/callback`,
});
await implicit.login(); // redirects browser to Auth0

// ── Step 2: handle the callback (Auth0 delivers token in the URL fragment) ─
const implicit = createImplicitAuth({
  clientId: "your-auth0-client-id",
  redirectUri: `${location.origin}/auth/callback`,
});
await implicit.handleRedirectCallback(); // parses #access_token=...

// ── Step 3: use the client ─────────────────────────────────────────────────
const client = createClient({
  url: "https://api.verdigris.co/v3",
  auth: implicit.provider, // no refresh — must re-login when token expires
});

Static token

If you already hold a bearer token obtained out-of-band (e.g. a long-lived service token for development):

const client = createClient({
  url: "https://api.verdigris.co/v3",
  headers: { Authorization: `Bearer ${accessToken}` },
});

Or supply a function that returns a fresh token per request:

const client = createClient({
  url: "https://api.verdigris.co/v3",
  headers: async () => {
    const token = await getAccessToken(); // your own token retrieval
    return { Authorization: `Bearer ${token}` };
  },
});

Specifying another token issuer

Override issuer to test against another auth server.

const provider = createClientCredentialsTokenProvider({
  clientId: "...",
  clientSecret: "...",
  issuer: "https://example.com",
});

The same issuer override works for createPkceAuth and createImplicitAuth.