SDKs

Typed TypeScript, top to bottom

Three packages, layered. Request and response types are generated from the platform's OpenAPI contract, so they never drift from the server. Use as much or as little as you need. In early access. Request the registry auth at info@somvad.com.

Headless

@somvad/sdk-core

Framework-agnostic: typed REST, realtime events, and WebRTC voice. No React.

Jump to →

React

@somvad/sdk-react

One provider + hooks over the core. Re-exports everything: the only dep a React app needs.

Jump to →

Design system

@somvad/sdk-ui

The exact theme, primitives, and wired components the SOMVAD console is built from.

Jump to →

Headless core

@somvad/sdk-core

A typed client (SomvadClient), a realtime stream (SomvadEvents), and a WebRTC helper (connect / Phone). Inject your own fetch for Node or tests; swap the token after login or impersonation with setToken.

install

npm i @somvad/sdk-core

typescript

import { SomvadClient, SomvadEvents, connect } from '@somvad/sdk-core'

const client = new SomvadClient({ baseUrl: 'https://dev.somvad.com', token })
const me     = await client.auth.me()
const call   = await client.calls.place({ callee_user_id })

const events = new SomvadEvents({ baseUrl, token }).connect()
events.on('signal', (s) => s.event === 'incoming_call' && ring(s))

REST domains

Methods are grouped by domain on the client:

Domain	Methods (selected)
`auth`	config · login · me · impersonate · stopImpersonation
`conferences`	list · get · create · join · leave · lock/unlock · barge · members · participants · setRole · topology · events
`calls`	place · list · accept · decline · cancel
`chat`	history · send · openDm
`presence`	snapshot · setAvailability
`browser`	config · testDial
`recordings`	list · start · stop · transcript · audioUrl · uploadEdge · verify
`profiles` · `layouts` · `users` · `metrics`	sound profiles, turret layout, directory, client QoS reporting

Beyond REST

Voice: connect(config, wsUrl) registers SIP-over-WSS on the assigned mixer and returns a Phone (with the raw RTCPeerConnection for getStats). AEC applied; honest failure.
QoS helpers: createQosTracker(), sampleStats(pc), mosEstimate(...); feed the summary to metrics.reportClientQuality.
Ring election: createRingCoordinator() rings exactly one tab across many open windows.
Session: saveSession / loadSession persist sign-in across reloads.
Advanced audio (turret): createLegEngine() runs N independent SIP legs (latch / push-to-talk each, per-leg output routing + VOX) for cockpit UIs.

React bindings

@somvad/sdk-react

Wire the provider once; compose calling UI with hooks. It re-exports all of @somvad/sdk-core, so this is the only dependency a React app needs. The provider owns the single events socket, the live presence map, the signed-in identity, and the multi-tab ring coordinator.

install

npm i @somvad/sdk-react react react-dom

tsx

import { SomvadProvider, useCall, useIncomingCall, useDirectory } from '@somvad/sdk-react'

function Root({ token }) {
  return (
    <SomvadProvider config={{ baseUrl: 'https://dev.somvad.com' }} token={token}>
      <Desk />
    </SomvadProvider>
  )
}

function Desk() {
  const dir  = useDirectory()
  const call = useCall()                         // idle → connecting → active | error
  const { incoming, accept } = useIncomingCall()  // ring-elected across tabs
}

Hooks

Hook	Returns
`useSomvad()`	The REST client: call any domain method.
`useMe()`	Signed-in identity (user_id, role, tenant_id).
`usePresence()`	Live presence map, keyed by subject; updates off the socket.
`useIncomingCall()`	The current ringing call (ring-elected across tabs) + accept/decline.
`useDirectory()` · `useConferences()`	People you can call; rooms on your desk (honest state).
`useChat(id)`	Messages + send; history on open and on every reconnect, deduped.
`useCall()`	One browser audio call: join → SIP/WebRTC → mute → hang-up → QoS, with phase + error.
`useLayout(userId?)`	The turret button matrix.

useCall runs the full path for you and surfaces failures in phase: 'error', never an optimistic "connected".

Design system

@somvad/sdk-ui

The exact OKLCH theme, primitives, and hook-wired components the platform's own console and turret are built from. Compose on-brand UI without re-deriving the design language. Import the tokens once at the app root and everything inherits.

install

npm i @somvad/sdk-ui @somvad/sdk-react react react-dom

tsx

import '@somvad/sdk-ui/tokens.css'   // once, at the app root
import { Button, Panel, IncomingCallOverlay, CallBar, PresenceDot } from '@somvad/sdk-ui'
import { useCall } from '@somvad/sdk-react'

function Desk() {
  const call = useCall()
  return (
    <Panel>
      <PresenceDot userId={id} />
      <Button variant="primary" onClick={() => call.call(id)}>Call</Button>
      <CallBar call={call} />
      <IncomingCallOverlay onAccepted={(cid) => call.join(cid)} />
    </Panel>
  )
}

Primitives (Button, Field, Panel, Badge, Dot, Notice, Empty, Skeleton) render off the token theme. Wired components (PresenceDot, IncomingCallOverlay, CallBar) read the provider's hooks directly, so there's no prop plumbing; the overlay even rings on its own.

Access

Getting the packages (early access)

The @somvad/* packages are in early access on a private registry. The install snippets above show the intended usage; request access at info@somvad.com and we'll send the .npmrc auth and the current versions.