@eleverh/sdk

Headless TypeScript SDK for the public Eleve Edge API. It has no runtime dependencies and can be used by browser applications, Node services, CLIs, and workers without bringing React or application-specific state management.

npm install @eleverh/sdk

Browser

import { createBrowserEleveClient } from "@eleverh/sdk/browser"

const eleve = createBrowserEleveClient()
const session = await eleve.session.get()

const pending = await eleve.userProfile.requestEmailChange({
  email: "[email protected]",
})
await eleve.userProfile.confirmEmailChange({
  requestId: pending.requestId,
  code: "123456",
})

The browser client uses the current origin by default and sends the Eleve session cookie. Pass baseUrl when the application and API use different origins.

Server

import {
  createClientCredentialsTokenProvider,
  createServerEleveClient,
} from "@eleverh/sdk/server"

const accessToken = createClientCredentialsTokenProvider({
  tokenUrl: "https://issuer.example/oauth/token",
  clientId: process.env.ELEVE_CLIENT_ID!,
  clientSecret: process.env.ELEVE_CLIENT_SECRET!,
  resource: "https://api.eleverh.com",
  scopes: ["eleve:integrations:read"],
})

const eleve = createServerEleveClient({
  baseUrl: "https://acme.eleverh.com",
  accessToken,
})

const principal = await eleve.integrations.getPrincipal()

The Client Credentials provider sends the client secret only to the configured token endpoint, coalesces concurrent refreshes, and caches access tokens until shortly before expiration. The Edge accepts machine tokens only on operations that explicitly declare machine security and scopes; browser/user operations remain cookie-authenticated.

Errors and cancellation

Non-successful API responses throw EleveApiError, preserving the HTTP status, stable problem code, and X-Request-ID. Network failures and deadlines throw EleveNetworkError and EleveTimeoutError. Every operation accepts signal, timeoutMs, headers, and request tracing metadata as its final argument.

Streaming and uploads

streamNdjson(response) incrementally parses NDJSON without buffering the whole response. uploadToSignedTarget(...) uploads directly to an HTTP(S) signed URL with credentials omitted, keeping object bytes outside the Eleve Edge.

The general transport only accepts /api paths. Rate limits and authorization remain Edge responsibilities; changing the hostname or using the SDK is not a supported bypass.

Contract generation

The Edge owns the public contract. openapi/eleve-public.yaml is its automated, versioned mirror in this repository, and the committed TypeScript types are generated from it:

npm run generate
npm run verify

verify checks the generated contract, TypeScript declarations, runtime tests, and the package contents that would be published.