Flowsterix Studio SDK

@flowsterix/studio bridges the open-source Flowsterix library to the proprietary Studio backend. It intercepts analytics events and storage operations, serializes them to JSON-safe payloads, and ships them in batches to a Studio ingest endpoint.

Architecture

TourProvider
  analytics={bridge.analytics}     --> serializer --> transport --> POST /v1/ingest
  storageAdapter={bridge.storage({ inner: localStorage })}
                                       |
                                       +--> inner adapter (read/write)
                                       +--> transport (fire-and-forget sync)

• No React dependency – pure JS, works with any framework
• Dep: @flowsterix/core only (uses FlowAnalyticsHandlers, StorageAdapter types)
• Package: packages/studio/ in the monorepo

Quick Start

import { createStudioBridge } from '@flowsterix/studio'
import { createLocalStorageAdapter } from '@flowsterix/core'

const bridge = createStudioBridge({
  projectId: 'proj_abc',
  apiKey: 'sk_live_xxx',
  // endpoint: 'https://ingest.flowsterix.studio', // default
  // batchSize: 20,        // default
  // flushIntervalMs: 5000, // default
  // debug: false,          // include stack traces in error events
  user: { id: 'user-123', traits: { plan: 'pro' } },
})

// In React:
<TourProvider
  flows={flows}
  analytics={bridge.analytics}
  storageAdapter={bridge.storage({ inner: createLocalStorageAdapter() })}
>

Public API

createStudioBridge(params: StudioBridgeOptions): StudioBridge

interface StudioBridgeOptions {
  projectId: string
  apiKey: string
  endpoint?: string          // default: https://ingest.flowsterix.studio
  user?: UserContext
  debug?: boolean            // include stack traces in error events
  batchSize?: number         // default: 20
  flushIntervalMs?: number   // default: 5000
}

interface UserContext {
  id: string
  traits?: Record<string, unknown>
}

interface StudioBridge {
  analytics: FlowAnalyticsHandlers<unknown>   // pass to TourProvider
  storage: (params: { inner: StorageAdapter }) => StorageAdapter  // wraps an inner adapter
  identify: (params: { user: UserContext }) => void  // update user mid-session
  flush: () => Promise<void>    // force-flush buffered events
  shutdown: () => void          // flush + cleanup listeners
}

Lifecycle

• identify() — update user context after login; enqueues an identify event
• flush() — force-send buffered events (useful before navigation)
• shutdown() — flush remaining via sendBeacon, remove visibilitychange listener, clear interval

Module Overview

Serialization Rules

The serializer strips non-JSON-safe values from FlowDefinition and Step:

Flow: keeps id, version, metadata, autoStart, resumeStrategy, stepCount. Drops steps array, hud, migrate, dialogs.

Step: keeps id, target (selector string or 'screen'), placement, mask, controls, dialogId, route (RegExp .source), advance (drops check fn). Drops content, onEnter, onExit, onResume, waitFor, targetBehavior.

Error events: keeps code, meta, message, name. Stack only if debug: true.

Version mismatch: serializes oldVersion/newVersion as "major.minor" strings.

Transport Details

• Buffer flushes when batchSize reached OR every flushIntervalMs
• On fetch error: events re-added to front of buffer (retry next flush)
• Buffer capped at 500 events to prevent memory leaks
• On visibilitychange → hidden: calls shutdown() which uses sendBeacon
• Shutdown fallback: fetch with keepalive: true
• Auth header: Authorization: Bearer ${apiKey}

Flow Registration

Flows are not registered upfront. The first analytics event for each flow implicitly registers it — every StudioEvent contains a serialized flow field. The backend deduplicates by (projectId, flowId, version).

Key Patterns

Wrapping storage with Studio sync

// The storage wrapper delegates all reads/writes to the inner adapter
// and fire-and-forget enqueues sync events to the transport
const storageAdapter = bridge.storage({
  inner: createLocalStorageAdapter()
})

Identifying users after auth

// Call after login — updates user on all subsequent events
bridge.identify({ user: { id: userId, traits: { plan, role } } })

Cleanup on unmount

useEffect(() => {
  return () => bridge.shutdown()
}, [])