@voltr-token-studio/web-sdk

Framework-agnostic web runtime for Voltr Token Studio. Apply design-token updates to any web app with conditional fetching, dual-slot caching, and FCM signal integration.

npm install @voltr-token-studio/web-sdk

Quick start

import { VoltrClient } from '@voltr-token-studio/web-sdk'

const client = new VoltrClient({
  brandId: 'brand-a',
  apiUrl: 'https://your-api.example.com',
  autoPromote: true,
})

// On page load
await client.init()
const css = client.getActiveCSS()
if (css) applyCSS(css)

// When FCM message arrives or user triggers refresh
const token = await client.fetchAndStage()
if (token && client.hasNewerStaged()) {
  client.promoteStaged()
  applyCSS(client.getActiveCSS())
}

FCM Integration

The SDK includes a Firebase Cloud Messaging service worker template. See FCM_SETUP.md for full setup instructions.

// In your Firebase service worker (see template in src/)
self.addEventListener('push', async (event) => {
  const data = event.data?.json()
  if (data?.event === 'token-update') {
    const clients = await self.clients.matchAll()
    clients.forEach(client => client.postMessage({ type: 'voltr-update', data }))
  }
})

API

new VoltrClient(config)

| Config | Type | Required | Description | |--------|------|----------|-------------| | brandId | string | Yes | Brand identifier | | apiUrl | string | No | API base URL (default: http://localhost:3001) | | fcm | FCMConfig | No | FCM configuration | | autoPromote | boolean | No | Auto-promote staged tokens on init() |

Methods

| Method | Returns | Description | |--------|---------|-------------| | init() | Promise<void> | Initialize client, optionally auto-promote | | fetchAndStage() | Promise<TokenData \| null> | Fetch CSS with ETag/304, store in staged slot | | getActiveCSS() | string \| null | Get currently active CSS | | getStagedCSS() | string \| null | Get staged (pending) CSS | | hasNewerStaged() | boolean | Check if staged tokens are newer | | promoteStaged() | void | Move staged to active | | clearStaged() | void | Clear staged slot | | clearAll() | void | Clear all cache | | getActiveVersion() | string \| null | Version of active tokens | | getStagedVersion() | string \| null | Version of staged tokens |

DualSlotCache

Separate cache class for direct use:

import { DualSlotCache } from '@voltr-token-studio/web-sdk'

const cache = new DualSlotCache('brand-a')
cache.setStaged({ version: '1.0.0', hash: 'abc', css: ':root {}', timestamp: Date.now() })
cache.promoteStaged()

Architecture

See ARCHITECTURE.md for details on the dual-slot cache pattern, FCM integration, and conditional fetching with ETag/304.

License

MIT