@holostaff/sdk

Lifetime identity, stage detection, custom signal probes, and the intervention widget for the Holostaff runtime.

Install

npm install @holostaff/sdk

Usage

import { holostaff } from '@holostaff/sdk'

// Once at app startup — the deploy PR adds this for you.
holostaff.init({
  sourceId: 'cli-source-abc',
  tenantId: 'your-tenant-id',
})

// At journey-stage boundaries (placed by the deploy PR's agent).
holostaff.markStageEntry('adoption')

// On sign-in completion.
holostaff.identify(user.id)

// On logout.
holostaff.clearIdentity()

// On host-app events the scan detected as worth observing.
holostaff.emitSignal('first_resource_created', { kind: 'project' })

// Only needed if you render interventions yourself — the built-in
// widget reports outcomes automatically.
holostaff.reportOutcome(interventionId, 'engaged')

Calls made before init() queue and replay once it runs, so import order is not load-bearing. All methods are fail-soft — they never throw into your code. Errors route to the optional onError callback you pass to init().

What this SDK does (and doesn't)

Does

• Mint and persist a lifetime device id (localStorage + first-party cookie).
• Open / close a session bound to page lifecycle.
• POST identity / stage / signal / outcome events to the Holostaff runtime.
• Track the current SPA route and last-user-activity time, and forward them to the runtime on route changes plus a low-frequency heartbeat.
• Record the session with rrweb (DOM, canvas at ~2 fps, media playback state, inlined images/fonts) and batch it to the runtime, where the vision pipeline watches the session and decides when the copilot should step in. Password / email / tel inputs are always masked; mark rendered PII with the holostaff-mask (text) or holostaff-block (region) CSS classes; opt out entirely with init({ observe: { enabled: false } }).
• Hold a server-sent-events channel open and render text interventions as a shadow-DOM pill (dismiss / engage / 30s auto-ignore), reporting outcomes back automatically.

Does not (yet)

• Render non-text modalities (voice / email / sms / phone / screen automation) — those events are surfaced to onError and skipped.

References

• docs.holostaff.ai