Classes

CommandService

Singleton service for managing and executing commands

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): CommandService

Returns:

CommandService -

registerHandler

registerHandler(commandId: string, handler: CommandHandler<TArgs, TResult>, pluginId: string): () => void

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes	- The command ID to handle
`handler`	`CommandHandler<TArgs, TResult>`	Yes	- The handler function
`pluginId`	`string`	Yes	- The plugin registering this handler

Returns:

() => void -

unregisterHandler

Unregister a command handler

unregisterHandler(commandId: string, pluginId: string): boolean

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes
`pluginId`	`string`	Yes

Returns:

boolean -

Set the navigation fallback callback Called when a command exists but has no handler (app not mounted)

setNavigationFallback(fallback: NavigationFallback): void

Parameters:

Parameter	Type	Required	Description
`fallback`	`NavigationFallback`	Yes

hasHandler

Check if a handler is registered for a command

hasHandler(commandId: string): boolean

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes

Returns:

boolean -

execute

Execute a command

execute(commandId: string, args?: TArgs): Promise<CommandResult<TResult>>

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes	- The command ID to execute
`args`	`TArgs`	No	- Arguments to pass to the handler

Returns:

Promise<CommandResult<TResult>> - Promise resolving to the command result

isEnabled

Check if a command is enabled in the current context

isEnabled(commandId: string): boolean

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes

Returns:

boolean -

getExecutableCommands

Get all executable commands

getExecutableCommands(): ExecutableCommand[]

Returns:

ExecutableCommand[] -

getCommandsByCategory

Get commands grouped by category

getCommandsByCategory(): Map<string, ExecutableCommand[]>

Returns:

Map<string, ExecutableCommand[]> -

setContext

Update the command context

setContext(updates: Partial<CommandContext>): void

Parameters:

Parameter	Type	Required	Description
`updates`	`Partial<CommandContext>`	Yes

getContext

Get the current command context

getContext(): CommandContext

Returns:

CommandContext -

onDidExecute

Subscribe to command execution events

onDidExecute(listener: CommandExecutionListener): () => void

Parameters:

Parameter	Type	Required	Description
`listener`	`CommandExecutionListener`	Yes

Returns:

() => void -

clear

Clear all handlers (for testing)

clear(): void

CommandError

Error thrown when command execution fails

Constructor

constructor(message: string, commandId: string, code: CommandErrorCode, cause?: unknown)

Parameters:

Parameter	Type	Required
`message`	`string`	Yes
`commandId`	`string`	Yes
`code`	`CommandErrorCode`	Yes
`cause`	`unknown`	No

ContributionRegistry

Singleton registry for managing contribution points and plugin contributions

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): ContributionRegistry

Returns:

ContributionRegistry -

registerPoint

registerPoint(point: ContributionPointDefinition<T>): void

Parameters:

Parameter	Type	Required	Description
`point`	`ContributionPointDefinition<T>`	Yes	- The contribution point definition

getPoint

Get a registered contribution point

getPoint(id: string): ContributionPointDefinition<unknown>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

ContributionPointDefinition<unknown> -

getAllPoints

Get all registered contribution points

getAllPoints(): ContributionPointDefinition<unknown>[]

Returns:

ContributionPointDefinition<unknown>[] -

processManifest

Process a plugin manifest and extract contributions

processManifest(manifest: PluginManifest): void

Parameters:

Parameter	Type	Required	Description
`manifest`	`PluginManifest`	Yes	- The plugin manifest to process

getContributions

Get all contributions for a point

getContributions(pointId: string): ProcessedContribution<T>[]

Parameters:

Parameter	Type	Required	Description
`pointId`	`string`	Yes

Returns:

ProcessedContribution<T>[] -

getContributionsFromPlugin

Get contributions from a specific plugin

getContributionsFromPlugin(pointId: string, pluginId: string): ProcessedContribution<T>[]

Parameters:

Parameter	Type	Required	Description
`pointId`	`string`	Yes
`pluginId`	`string`	Yes

Returns:

ProcessedContribution<T>[] -

removePluginContributions

Remove all contributions from a plugin

removePluginContributions(pluginId: string): void

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes

onChange

Subscribe to contribution changes

onChange(listener: ContributionChangeListener): () => void

Parameters:

Parameter	Type	Required	Description
`listener`	`ContributionChangeListener`	Yes

Returns:

() => void -

onEvent

Subscribe to specific events

onEvent(eventType: "added" | "removed" | "updated", listener: (event: ContributionChangeEvent) => void): () => void

Parameters:

Parameter	Type	Required	Description
`eventType`	`"added" \| "removed" \| "updated"`	Yes
`listener`	`(event: ContributionChangeEvent) => void`	Yes

Returns:

() => void -

clear

Clear all contributions (for testing)

clear(): void

reset

Reset registry completely (for testing)

reset(): void

EventBus

Event bus for pub/sub communication between plugins Supports async event handlers

Methods

on

Subscribe to an event

on(event: string, handler: EventHandler<T>): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`EventHandler<T>`	Yes

Returns:

() => void - Unsubscribe function

once

Subscribe to event once (auto-unsubscribe after first call)

once(event: string, handler: EventHandler<T>): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`EventHandler<T>`	Yes

Returns:

() => void -

off

Unsubscribe from event

off(event: string, handler: EventHandler<T>): void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`EventHandler<T>`	Yes

emit

Emit event to all subscribers Supports async handlers

emit(event: string, data?: T): Promise<void>

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`data`	`T`	No

Returns:

Promise<void> -

clear

Clear all handlers for an event

clear(event: string): void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes

clearAll

Clear all handlers for all events

clearAll(): void

getEvents

Get event names with active handlers

getEvents(): string[]

Returns:

string[] -

getHandlerCount

Get handler count for an event

getHandlerCount(event: string): number

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes

Returns:

number -

PluginRegistry

Singleton registry for managing app plugins Handles registration, dependency resolution, and lifecycle management

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): PluginRegistry

Returns:

PluginRegistry -

register

register(plugin: AppPlugin): void

Parameters:

Parameter	Type	Required	Description
`plugin`	`AppPlugin`	Yes

registerMany

registerMany(plugins: AppPlugin[]): void

Parameters:

Parameter	Type	Required	Description
`plugins`	`AppPlugin[]`	Yes

registerFromManifest

registerFromManifest(loadedManifest: LoadedManifest, options?: ManifestAdapterOptions): ManifestBackedPlugin

Parameters:

Parameter	Type	Required	Description
`loadedManifest`	`LoadedManifest`	Yes	- The loaded manifest with path information
`options`	`ManifestAdapterOptions`	No	- Adapter options for customizing the conversion

Returns:

ManifestBackedPlugin - The registered plugin

registerManyFromManifests

registerManyFromManifests(manifests: LoadedManifest[], options?: ManifestAdapterOptions): ManifestBackedPlugin[]

Parameters:

Parameter	Type	Required	Description
`manifests`	`LoadedManifest[]`	Yes	- Array of loaded manifests
`options`	`ManifestAdapterOptions`	No	- Adapter options for customizing the conversion

Returns:

ManifestBackedPlugin[] - Array of registered plugins

getManifest

Get manifest for a plugin by ID

getManifest(id: string): PluginManifest

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

PluginManifest -

getAllManifests

Get all manifests

getAllManifests(): PluginManifest[]

Returns:

PluginManifest[] -

hasManifest

Check if a plugin was loaded from a manifest

hasManifest(id: string): boolean

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

boolean -

getAll

Get all registered plugins

getAll(): AppPlugin[]

Returns:

AppPlugin[] -

get

Get plugin by ID

get(id: string): AppPlugin

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

AppPlugin -

load

Load plugin with dependencies in order

load(id: string, services: ServiceRegistry): Promise<void>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`services`	`ServiceRegistry`	Yes

Returns:

Promise<void> -

unload

Unload plugin (calls onUnload hook)

unload(id: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

Promise<void> -

clear

Clear all plugins (for testing)

clear(): void

KeybindingService

Singleton service for managing keybindings

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): KeybindingService

Returns:

KeybindingService -

resetInstance

Reset the singleton instance (for testing)

resetInstance(): void

initialize

Initialize keybindings from contribution registry

initialize(): void

registerKeybinding

registerKeybinding(commandId: string, keyString: string, options?: { when?: string; pluginId?: string; mac?: string; }): () => void

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes	- The command to execute
`keyString`	`string`	Yes	- The key combination
`options`	`{ when?: string; pluginId?: string; mac?: string; }`	No	- Additional options

Returns:

() => void -

attachListener

Attach the global keyboard listener

attachListener(): void

detachListener

Detach the global keyboard listener

detachListener(): void

matchKeybinding

Match a keyboard event to a keybinding

matchKeybinding(event: KeyboardEvent, context?: ConditionContext): KeybindingMatch

Parameters:

Parameter	Type	Required	Description
`event`	`KeyboardEvent`	Yes	- The keyboard event
`context`	`ConditionContext`	No	- Optional condition context override

Returns:

KeybindingMatch - The matched keybinding or null

setConditionContext

Set the condition context for evaluating 'when' expressions

setConditionContext(context: ConditionContext): void

Parameters:

Parameter	Type	Required	Description
`context`	`ConditionContext`	Yes	- The new condition context

getKeybindingForCommand

Get keybinding for a command

getKeybindingForCommand(commandId: string): ResolvedKeybinding

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes	- The command ID

Returns:

ResolvedKeybinding - The resolved keybinding or null

getKeybindingsForCommand

Get all keybindings for a command

getKeybindingsForCommand(commandId: string): ResolvedKeybinding[]

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes	- The command ID

Returns:

ResolvedKeybinding[] - Array of resolved keybindings

getAllKeybindings

Get all registered keybindings

getAllKeybindings(): ParsedKeybinding[]

Returns:

ParsedKeybinding[] - Array of all parsed keybindings

onChange

Subscribe to keybinding changes

onChange(listener: () => void): () => void

Parameters:

Parameter	Type	Required	Description
`listener`	`() => void`	Yes	- Callback when keybindings change

Returns:

() => void - Unsubscribe function

dispose

Dispose the service

dispose(): void

GlobalLoadingService

Singleton service for managing global loading indicators. Supports multiple loading types with delay and minimum duration.

Constructor

constructor(config?: Partial<GlobalLoadingConfig>)

Parameters:

Parameter	Type	Required	Description
`config`	`Partial<GlobalLoadingConfig>`	No

Methods

getInstance

Get singleton instance

getInstance(config?: Partial<GlobalLoadingConfig>): GlobalLoadingService

Parameters:

Parameter	Type	Required	Description
`config`	`Partial<GlobalLoadingConfig>`	No

Returns:

GlobalLoadingService -

resetInstance

Reset singleton (for testing)

resetInstance(): void

start

Start a loading operation

start(id: string, options?: LoadingOptions): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`options`	`LoadingOptions`	No

progress

Update progress for a loading operation

progress(id: string, value: number): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`value`	`number`	Yes

complete

Complete a loading operation

complete(id: string): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

fail

Fail a loading operation

fail(id: string, error?: string): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`error`	`string`	No

isLoading

Check if any loading is active

isLoading(type?: LoadingType): boolean

Parameters:

Parameter	Type	Required	Description
`type`	`LoadingType`	No

Returns:

boolean -

getState$

Get observable of global loading state

getState$(): Observable<GlobalLoadingState>

Returns:

Observable<GlobalLoadingState> -

on

Subscribe to loading events

on(event: string, handler: (data: T) => void): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`(data: T) => void`	Yes

Returns:

() => void -

once

Subscribe to loading event once

once(event: string, handler: (data: T) => void): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`(data: T) => void`	Yes

Returns:

() => void -

destroy

Destroy the service

destroy(): void

ManifestDiscovery

ManifestDiscovery - Singleton service for discovering and watching plugin manifests

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): ManifestDiscovery

Returns:

ManifestDiscovery -

resetInstance

Reset singleton instance (for testing)

resetInstance(): void

discover

Discover all manifests in the given paths

discover(options: DiscoveryOptions): Promise<DiscoveryResult>

Parameters:

Parameter	Type	Required	Description
`options`	`DiscoveryOptions`	Yes	- Discovery options

Returns:

Promise<DiscoveryResult> - Promise resolving to discovery result

watch

Start watching for manifest changes

watch(options?: Partial<DiscoveryOptions>): () => void

Parameters:

Parameter	Type	Required	Description
`options`	`Partial<DiscoveryOptions>`	No	- Discovery options (must match previous discover() call)

Returns:

() => void - Cleanup function to stop watching

onChange

Subscribe to manifest changes

onChange(listener: (manifest: LoadedManifest, type: "add" | "change" | "unlink") => void): () => void

Parameters:

Parameter	Type	Required	Description
`listener`	`(manifest: LoadedManifest, type: "add" \| "change" \| "unlink") => void`	Yes	- Callback for changes

Returns:

() => void - Unsubscribe function

getManifests

Get all discovered manifests

getManifests(): LoadedManifest[]

Returns:

LoadedManifest[] -

getManifest

Get a specific manifest by plugin ID

getManifest(pluginId: string): LoadedManifest

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes

Returns:

LoadedManifest -

dispose

Dispose the discovery service

dispose(): void

ManifestLoadError

Error thrown when manifest loading fails

Constructor

constructor(message: string, manifestPath: string, cause?: unknown)

Parameters:

Parameter	Type	Required
`message`	`string`	Yes
`manifestPath`	`string`	Yes
`cause`	`unknown`	No

ManifestRegistry

Singleton registry for plugin manifests

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): ManifestRegistry

Returns:

ManifestRegistry -

resetInstance

Reset instance (for testing)

resetInstance(): void

registerManifest

registerManifest(loaded: LoadedManifest): void

Parameters:

Parameter	Type	Required	Description
`loaded`	`LoadedManifest`	Yes

registerManifests

registerManifests(manifests: LoadedManifest[]): void

Parameters:

Parameter	Type	Required	Description
`manifests`	`LoadedManifest[]`	Yes

unregisterManifest

Unregister a manifest

unregisterManifest(pluginId: string): boolean

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes

Returns:

boolean -

getManifest

Get a manifest by plugin ID

getManifest(pluginId: string): LoadedManifest

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes

Returns:

LoadedManifest -

getAllManifests

Get all loaded manifests

getAllManifests(): LoadedManifest[]

Returns:

LoadedManifest[] -

getRegisteredApps

Get all registered apps (derived from manifests with routes) Excludes the home/launcher route ("/") since it's shown via the Home button Sorted by order (ascending), then by name for apps with same order

getRegisteredApps(): RegisteredApp[]

Returns:

RegisteredApp[] -

onChange

Subscribe to changes

onChange(listener: () => void): () => void

Parameters:

Parameter	Type	Required	Description
`listener`	`() => void`	Yes

Returns:

() => void -

Singleton service for managing menus

Constructor

constructor()

Methods

getInstance

Get singleton instance

getInstance(): MenuService

Returns:

MenuService -

Get resolved menu items for a location

getMenuItems(location: MenuLocation, context?: ConditionContext): ResolvedMenuItem[]

Parameters:

Parameter	Type	Required	Description
`location`	`MenuLocation`	Yes	- The menu location
`context`	`ConditionContext`	No	- Current condition context

Returns:

ResolvedMenuItem[] - Array of resolved menu items

Get menu items grouped by group field

getGroupedMenuItems(location: MenuLocation, context?: ConditionContext): MenuGroup[]

Parameters:

Parameter	Type	Required	Description
`location`	`MenuLocation`	Yes	- The menu location
`context`	`ConditionContext`	No	- Current condition context

Returns:

MenuGroup[] - Array of menu groups with items

getLocations

Get all available menu locations

getLocations(): MenuLocation[]

Returns:

MenuLocation[] -

EntityRouteRegistry

Entity Route Registry - singleton for managing entity route configurations

Constructor

constructor()

Methods

getInstance

Get the singleton instance

getInstance(): EntityRouteRegistry

Returns:

EntityRouteRegistry -

resetInstance

Reset the singleton (for testing)

resetInstance(): void

setEventBus

Set the EventBus for emitting events

setEventBus(eventBus: EventBus): void

Parameters:

Parameter	Type	Required	Description
`eventBus`	`EventBus`	Yes

register

register(config: EntityRouteConfig, upsert?: boolean): () => void

Parameters:

Parameter	Type	Required	Description
`config`	`EntityRouteConfig`	Yes	- Entity route configuration
`upsert`	`boolean`	No	- If true, replace existing route from same plugin (default: false)

Returns:

() => void - Unregister function

registerFromManifest

registerFromManifest(pluginId: string, basePath: string, entityRoutes: Partial<Record<NavigableEntityType, string>>): () => void

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes	- Plugin ID
`basePath`	`string`	Yes	- Base path for the plugin
`entityRoutes`	`Partial<Record<NavigableEntityType, string>>`	Yes	- Map of entity type to route pattern

Returns:

() => void - Unregister function for all routes

getRoute

Get route configuration for an entity type

getRoute(entityType: NavigableEntityType, preferredPluginId?: string): EntityRouteConfig

Parameters:

Parameter	Type	Required	Description
`entityType`	`NavigableEntityType`	Yes	- Entity type to look up
`preferredPluginId`	`string`	No	- Optional plugin ID to prefer

Returns:

EntityRouteConfig - Route configuration or null

getAllRoutes

Get all route configurations for an entity type

getAllRoutes(entityType: NavigableEntityType): EntityRouteConfig[]

Parameters:

Parameter	Type	Required	Description
`entityType`	`NavigableEntityType`	Yes

Returns:

EntityRouteConfig[] -

resolveEntityUrl

Resolve an entity ID to a full URL path

resolveEntityUrl(entityType: NavigableEntityType, entityId: string, preferredPluginId?: string): string

Parameters:

Parameter	Type	Required	Description
`entityType`	`NavigableEntityType`	Yes	- Entity type
`entityId`	`string`	Yes	- Entity ID
`preferredPluginId`	`string`	No	- Optional plugin ID to prefer

Returns:

string - Full URL path or null if no route registered

hasRoute

Check if a route exists for an entity type

hasRoute(entityType: NavigableEntityType): boolean

Parameters:

Parameter	Type	Required	Description
`entityType`	`NavigableEntityType`	Yes

Returns:

boolean -

getRegisteredEntityTypes

Get all registered entity types

getRegisteredEntityTypes(): NavigableEntityType[]

Returns:

NavigableEntityType[] -

clear

Clear all registered routes (for testing)

clear(): void

Navigation Service - orchestrates navigation with event-driven architecture

Constructor

constructor()

Methods

getInstance

Get the singleton instance

getInstance(): NavigationService

Returns:

NavigationService -

resetInstance

Reset the singleton (for testing)

resetInstance(): void

initialize

Initialize the navigation service with React Router navigate function

initialize(navigate: NavigateFunction, basePath?: string, contextSwitchers?: ContextSwitchers): void

Parameters:

Parameter	Type	Required
`navigate`	`NavigateFunction`	Yes
`basePath`	`string`	No
`contextSwitchers`	`ContextSwitchers`	No

setContextSwitchers

Set context switchers (can be set separately from initialize)

setContextSwitchers(contextSwitchers: ContextSwitchers): void

Parameters:

Parameter	Type	Required	Description
`contextSwitchers`	`ContextSwitchers`	Yes

setDefaultPluginId

Set the default plugin ID for entity resolution

setDefaultPluginId(pluginId: string): void

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes

getEventBus

Get the EventBus for subscribing to navigation events

getEventBus(): EventBus

Returns:

EventBus -

getRouteRegistry

Get the Entity Route Registry

getRouteRegistry(): EntityRouteRegistry

Returns:

EntityRouteRegistry -

toEntity

Navigate to an entity by type and ID

toEntity(entityType: NavigableEntityType, entityId: string, options?: NavigationOptions): Promise<void>

Parameters:

Parameter	Type	Required	Description
`entityType`	`NavigableEntityType`	Yes	- Type of entity (task, project, milestone, etc.)
`entityId`	`string`	Yes	- Entity ID
`options`	`NavigationOptions`	No	- Navigation options (orgId, workspaceId, etc.)

Returns:

Promise<void> -

toEntityById

Navigate to an entity by ID (auto-detects entity type from ID prefix)

toEntityById(entityId: string, options?: NavigationOptions): Promise<void>

Parameters:

Parameter	Type	Required	Description
`entityId`	`string`	Yes	- Entity ID (e.g., 'task_xxx', 'proj_xxx', 'mile_xxx')
`options`	`NavigationOptions`	No	- Navigation options

Returns:

Promise<void> -

toRoute

Navigate to a route path

toRoute(path: string, options?: NavigationOptions): Promise<void>

Parameters:

Parameter	Type	Required	Description
`path`	`string`	Yes	- Route path (e.g., '/tasks', '/projects/new')
`options`	`NavigationOptions`	No	- Navigation options

Returns:

Promise<void> -

toApp

Navigate to an app by plugin ID

toApp(pluginId: string, subPath?: string, options?: NavigationOptions): Promise<void>

Parameters:

Parameter	Type	Required	Description
`pluginId`	`string`	Yes	- Plugin/app ID (e.g., 'projects', 'chat')
`subPath`	`string`	No	- Optional sub-path within the app
`options`	`NavigationOptions`	No	- Navigation options

Returns:

Promise<void> -

back

Go back in browser history

back(): void

forward

Go forward in browser history

forward(): void

on

Subscribe to navigation events

on(event: string, handler: (data?: T) => void | Promise<void>): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes	- Event name from NAVIGATION_EVENTS
`handler`	`(data?: T) => void \| Promise<void>`	Yes	- Event handler

Returns:

() => void - Unsubscribe function

once

Subscribe to navigation event once

once(event: string, handler: (data?: T) => void | Promise<void>): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`(data?: T) => void \| Promise<void>`	Yes

Returns:

() => void -

ErrorBoundary

React Error Boundary with optional observability integration Catches React component errors. When

Constructor

constructor(props: ErrorBoundaryProps)

Parameters:

Parameter	Type	Required	Description
`props`	`ErrorBoundaryProps`	Yes

Properties

Property	Type	Required	Description
`reset`	`() => void`	Yes

Methods

getDerivedStateFromError

getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>

Parameters:

Parameter	Type	Required	Description
`error`	`Error`	Yes

Returns:

Partial<ErrorBoundaryState> -

componentDidCatch

componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void

Parameters:

Parameter	Type	Required	Description
`error`	`Error`	Yes
`errorInfo`	`React.ErrorInfo`	Yes

render

render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode>> | import("/Users/sthornock/code/epic/epic-flowstate/node_modules/@types/react/jsx-runtime").JSX.Element

Returns:

RecentCommandsManager

Manage recent commands with localStorage persistence

Constructor

constructor(maxCommands?: number)

Parameters:

Parameter	Type	Required	Description
`maxCommands`	`number`	No

Methods

getRecent

Get all recent commands

getRecent(): RecentCommand[]

Returns:

RecentCommand[] -

addRecent

Add a command to recent list

addRecent(commandId: string): void

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes

removeRecent

Remove a command from recent list

removeRecent(commandId: string): void

Parameters:

Parameter	Type	Required	Description
`commandId`	`string`	Yes

clearRecent

Clear all recent commands

clearRecent(): void

getRecentIds

Get recent command IDs in order

getRecentIds(): string[]

Returns:

string[] -

FlowstateRuntime

Properties

Property	Type	Required
`plugins`	`Map<string, FlowstatePlugin>`	Yes
`contexts`	`Map<string, React.Context<any>>`	Yes
`components`	`Map<string, React.ComponentType<any>>`	Yes
`hooks`	`Map<string, Function>`	Yes
`services`	`Map<string, any>`	Yes

Methods

registerPlugin

registerPlugin(plugin: FlowstatePlugin): Promise<void>

Parameters:

Parameter	Type	Required	Description
`plugin`	`FlowstatePlugin`	Yes

Returns:

Promise<void> -

registerContext

registerContext(name: string, context: React.Context<any>): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`context`	`React.Context<any>`	Yes

registerComponent

registerComponent(name: string, component: React.ComponentType<any>): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`component`	`React.ComponentType<any>`	Yes

registerHook

registerHook(name: string, hook: Function): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`hook`	`Function`	Yes

registerService

registerService(name: string, service: any): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`service`	`any`	Yes

mountPlugins

mountPlugins(): Promise<void>

Returns:

Promise<void> -

unmountPlugins

unmountPlugins(): Promise<void>

Returns:

Promise<void> -

AuthPlugin

Constructor

constructor(config?: AuthPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`AuthPluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

getOnboardingSteps

getOnboardingSteps(): OnboardingStep[]

Returns:

OnboardingStep[] -

ComponentPlugin

Constructor

constructor(config: ComponentPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`ComponentPluginConfig`	Yes

Properties

Property	Type	Required	Description
`name`	`string`	Yes
`version`	`string`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

DatabasePlugin

Constructor

constructor(config: DatabasePluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`DatabasePluginConfig`	Yes

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

GlobalLoadingPlugin

Integrates the global loading system into the FlowstateRuntime. Provides loading indicators for overlay and top nav styles.

Constructor

constructor(config?: GlobalLoadingPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`GlobalLoadingPluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<unknown>[]

Returns:

React.Context<unknown>[] -

providesServices

providesServices(): ServiceRegistry

Returns:

ServiceRegistry -

getProvider

Get the provider component for this plugin. Returns a memoized React component that wraps children with GlobalLoadingProvider.

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

Examples:

const loadingPlugin = new GlobalLoadingPlugin({
  showOverlay: true,
  showTopNav: true,
  topNavHeight: 3,
});

runtime.registerPlugin(loadingPlugin);

LoaderPlugin

Integrates the LoaderService into the FlowstateRuntime. Automatically tracks plugin registration and mounting. Provides global loading UI for application initialization.

Constructor

constructor(config?: LoaderPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`LoaderPluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesServices

providesServices(): { loaderService: import("/Users/sthornock/code/epic/epic-flowstate/packages/flowstate-app-framework/src/services/LoaderService").LoaderService; }

Returns:

{ loaderService: import("/Users/sthornock/code/epic/epic-flowstate/packages/flowstate-app-framework/src/services/LoaderService").LoaderService; } -

MemoryDatabaseAdapter

Constructor

constructor(databaseName?: string, collectionNames?: string[])

Parameters:

Parameter	Type	Required	Description
`databaseName`	`string`	No
`collectionNames`	`string[]`	No

Methods

initialize

initialize(): Promise<RxDatabase>

Returns:

Promise<RxDatabase> -

destroy

destroy(): Promise<void>

Returns:

Promise<void> -

_resetInstancesForTesting

_resetInstancesForTesting(): void

OrgWorkspacePlugin

Constructor

constructor(config?: OrgWorkspacePluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`OrgWorkspacePluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

getOnboardingSteps

getOnboardingSteps(): OnboardingStep[]

Returns:

OnboardingStep[] -

ReplicationManager

Core class for managing RxDB replication across collections

Constructor

constructor(database: RxDatabase, serverConfig: ServerInfo, config: ReplicationPluginConfig, authToken?: string)

Parameters:

Parameter	Type	Required
`database`	`RxDatabase`	Yes
`serverConfig`	`ServerInfo`	Yes
`config`	`ReplicationPluginConfig`	Yes
`authToken`	`string`	No

Methods

initialize

Initialize replication for all configured collections

initialize(): Promise<void>

Returns:

Promise<void> -

cleanup

Clean up all replication states and timers

cleanup(): Promise<void>

Returns:

Promise<void> -

awaitPendingPushes

Wait for pending push operations to complete Uses a simple timeout-based implementation with periodic checks

awaitPendingPushes(timeout?: number): Promise<void>

Parameters:

Parameter	Type	Required	Description
`timeout`	`number`	No	- Optional timeout in milliseconds (default: 5000)

Returns:

Promise<void> -

forceSync

Triggers synchronization for all replicated collections by calling reSync on each replication state. Handles errors gracefully by logging them; does not throw. Safe to call at any time. This is a public method that can be used to manually trigger synchronization for all collections.

forceSync(): Promise<void>

Returns:

Promise<void> -

getReplicationState

Get replication state for a specific collection

getReplicationState(collection: string): RxReplicationState<any, any>

Parameters:

Parameter	Type	Required	Description
`collection`	`string`	Yes

Returns:

RxReplicationState<any, any> -

isReplicating

Check if any replication is currently active

isReplicating(): boolean

Returns:

boolean -

getReplicationStatus

Get status information for all replicated collections

getReplicationStatus(): ReplicationStatus[]

Returns:

ReplicationStatus[] - Array of ReplicationStatus objects

restartWithNewToken

Restart replication with a new auth token. Cancels all existing replication states and reinitializes with the new token.

restartWithNewToken(newToken: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`newToken`	`string`	Yes	- The new authentication token

Returns:

Promise<void> -

isTokenRefreshInProgress

Check if a token refresh is currently in progress

isTokenRefreshInProgress(): boolean

Returns:

boolean -

ReplicationPlugin

Plugin for managing RxDB replication across collections

Constructor

constructor(config: ReplicationPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`ReplicationPluginConfig`	Yes

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

Validate that required dependencies are registered

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

Mount the plugin (ReplicationManager will be created by Provider)

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

Cleanup is handled by ReplicationProvider's useEffect cleanup

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

Provide the ReplicationContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

Get the provider component that wraps children with ReplicationProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

ServerConfigPlugin

Constructor

constructor(config: ServerConfigPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`ServerConfigPluginConfig`	Yes

Properties

Property	Type	Required	Description
`name`	`string`	Yes
`version`	`string`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

StandaloneDatabasePlugin

Constructor

constructor(config?: StandaloneDatabasePluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`StandaloneDatabasePluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

ThemePlugin

Integrates the theming system into the FlowstateRuntime. Provides theme context, CSS variables, and branding support.

Constructor

constructor(config?: ThemePluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`ThemePluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

onRegister

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(_runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

providesContext(): React.Context<unknown>[]

Returns:

React.Context<unknown>[] -

providesServices

providesServices(): ServiceRegistry

Returns:

ServiceRegistry -

getProvider

Get the provider component for this plugin. Returns a memoized React component that wraps children with ThemeProvider.

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

Examples:

const themePlugin = new ThemePlugin({
  defaultMode: 'dark',
});

runtime.registerPlugin(themePlugin);

QuickNavService

QuickNavService - handles search and path building for global navigation

Methods

initialize

Initialize the service with a database connection

initialize(db: RxDatabase): Promise<void>

Parameters:

Parameter	Type	Required	Description
`db`	`RxDatabase`	Yes

Returns:

Promise<void> -

isReady

Check if service is ready

isReady(): boolean

Returns:

boolean -

registerSearchConfig

registerSearchConfig(config: SearchIndexConfig): void

Parameters:

Parameter	Type	Required	Description
`config`	`SearchIndexConfig`	Yes

search

Search across all collections

search(query: string, config?: Partial<QuickNavConfig>): Promise<QuickNavItem[]>

Parameters:

Parameter	Type	Required	Description
`query`	`string`	Yes
`config`	`Partial<QuickNavConfig>`	No

Returns:

Promise<QuickNavItem[]> -

getRecentItems

Get recent items (placeholder - would use localStorage or IndexedDB)

getRecentItems(limit?: number): Promise<QuickNavItem[]>

Parameters:

Parameter	Type	Required	Description
`limit`	`number`	No

Returns:

Promise<QuickNavItem[]> -

Track a navigation for recent items

trackNavigation(item: QuickNavItem): void

Parameters:

Parameter	Type	Required	Description
`item`	`QuickNavItem`	Yes

destroy

Destroy the service

destroy(): void

ServerConfigStorage

Methods

getAllServers

getAllServers(): ServersData

Returns:

ServersData -

getServerNames

getServerNames(): string[]

Returns:

string[] -

getServerConfig

getServerConfig(serverName: string): ServerConfig

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes

Returns:

ServerConfig -

saveServerConfig

saveServerConfig(serverName: string, config: ServerConfig): void

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes
`config`	`ServerConfig`	Yes

getAuthToken

getAuthToken(serverName: string): string

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes

Returns:

string -

saveAuthToken

saveAuthToken(serverName: string, token: string): void

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes
`token`	`string`	Yes

getLastOrg

getLastOrg(serverName: string): string

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes

Returns:

string -

saveLastOrg

saveLastOrg(serverName: string, orgId: string): void

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes
`orgId`	`string`	Yes

getLastWorkspace

getLastWorkspace(serverName: string): string

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes

Returns:

string -

saveLastWorkspace

saveLastWorkspace(serverName: string, workspaceId: string): void

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes
`workspaceId`	`string`	Yes

removeServer

removeServer(serverName: string): void

Parameters:

Parameter	Type	Required	Description
`serverName`	`string`	Yes

AttributeSeedService

Service for seeding default attributes

Methods

seedDefaults

Seed default categories and tags for a scope. Skips individual attributes that already exist (by name/type/entityType).

seedDefaults(collection: RxCollection<AttributeModel>, options: SeedOptions): Promise<SeedResult>

Parameters:

Parameter	Type	Required	Description
`collection`	`RxCollection<AttributeModel>`	Yes	- RxDB attributes collection
`options`	`SeedOptions`	Yes	- Seeding options

Returns:

Promise<SeedResult> - SeedResult with counts

seedFromPresets

Seed attributes from multiple presets. Useful for combining attributes from different project types. Skips individual attributes that already exist (by name/type/entityType).

seedFromPresets(collection: RxCollection<AttributeModel>, options: Omit<SeedOptions, "preset">, presets: PresetType[]): Promise<SeedResult>

Parameters:

Parameter	Type	Required	Description
`collection`	`RxCollection<AttributeModel>`	Yes	- RxDB attributes collection
`options`	`Omit<SeedOptions, "preset">`	Yes	- Base seeding options (preset field is ignored)
`presets`	`PresetType[]`	Yes	- Array of preset types to seed

Returns:

Promise<SeedResult> - Combined SeedResult with total counts

hasAttributes

Check if attributes exist for a given scope.

hasAttributes(collection: RxCollection<AttributeModel>, orgId: string, workspaceId: string, projectId?: string): Promise<boolean>

Parameters:

Parameter	Type	Required	Description
`collection`	`RxCollection<AttributeModel>`	Yes	- RxDB attributes collection
`orgId`	`string`	Yes	- Organization ID
`workspaceId`	`string`	Yes	- Workspace ID
`projectId`	`string`	No	- Optional project ID for project-scoped check

Returns:

Promise<boolean> - true if attributes exist

getAttributeCount

Get count of attributes for a scope.

getAttributeCount(collection: RxCollection<AttributeModel>, orgId: string, workspaceId: string, type?: "tag" | "category" | "meta", projectId?: string): Promise<number>

Parameters:

Parameter	Type	Required	Description
`collection`	`RxCollection<AttributeModel>`	Yes	- RxDB attributes collection
`orgId`	`string`	Yes	- Organization ID
`workspaceId`	`string`	Yes	- Workspace ID
`type`	`"tag" \| "category" \| "meta"`	No	- Optional filter by type
`projectId`	`string`	No	- Optional project ID for project-scoped count

Returns:

Promise<number> - Count of attributes

getAvailablePresets

Get available preset types with their metadata. Useful for UI preset selection.

getAvailablePresets(): { name: PresetType; title: string; description: string; categoryCount: number; tagCount: number; }[]

Returns:

{ name: PresetType; title: string; description: string; categoryCount: number; tagCount: number; }[] - Array of preset info objects

AttributeService

AttributeService provides business logic for unified attribute management Handles CRUD operations, validation, and uniqueness checks for categories, tags, and meta attributes

Methods

createAttribute

Create a new attribute with comprehensive validation

createAttribute(attributeCollection: RxCollection, data: AttributeFormData, userId: string, orgId: string, workspaceId: string): Promise<AttributeResult>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`data`	`AttributeFormData`	Yes
`userId`	`string`	Yes
`orgId`	`string`	Yes
`workspaceId`	`string`	Yes

Returns:

Promise<AttributeResult> -

updateAttribute

Update an existing attribute with validation

updateAttribute(attributeCollection: RxCollection, attributeId: string, updates: Partial<AttributeFormData>, userId: string, orgId: string): Promise<AttributeResult>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`attributeId`	`string`	Yes
`updates`	`Partial<AttributeFormData>`	Yes
`userId`	`string`	Yes
`orgId`	`string`	Yes

Returns:

Promise<AttributeResult> -

deleteAttribute

Delete an attribute permanently

deleteAttribute(attributeCollection: RxCollection, attributeId: string, userId: string, orgId: string): Promise<{ success: boolean; errors: AttributeValidationErrors; }>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`attributeId`	`string`	Yes
`userId`	`string`	Yes
`orgId`	`string`	Yes

Returns:

Promise<{ success: boolean; errors: AttributeValidationErrors; }> -

archiveAttribute

Archive an attribute (soft delete)

archiveAttribute(attributeCollection: RxCollection, attributeId: string, userId: string, orgId: string): Promise<{ success: boolean; errors: AttributeValidationErrors; }>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`attributeId`	`string`	Yes
`userId`	`string`	Yes
`orgId`	`string`	Yes

Returns:

Promise<{ success: boolean; errors: AttributeValidationErrors; }> -

getAttributesByEntity

Get attributes by entity type and optional filters

getAttributesByEntity(attributeCollection: RxCollection, entityType: string, orgId: string, userId?: string, filters?: Partial<AttributeFilters>): Promise<AttributeModel[]>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`entityType`	`string`	Yes
`orgId`	`string`	Yes
`userId`	`string`	No
`filters`	`Partial<AttributeFilters>`	No

Returns:

Promise<AttributeModel[]> -

searchAttributes

Search attributes with flexible filtering

searchAttributes(attributeCollection: RxCollection, query: string, orgId: string, userId?: string, filters?: AttributeFilters): Promise<AttributeModel[]>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`query`	`string`	Yes
`orgId`	`string`	Yes
`userId`	`string`	No
`filters`	`AttributeFilters`	No

Returns:

Promise<AttributeModel[]> -

getCategoriesForEntity

Legacy compatibility method - get categories for entity

getCategoriesForEntity(attributeCollection: RxCollection, entityType: string, orgId: string, userId?: string): Promise<AttributeModel[]>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`entityType`	`string`	Yes
`orgId`	`string`	Yes
`userId`	`string`	No

Returns:

Promise<AttributeModel[]> -

getTagsForEntity

Legacy compatibility method - get tags for entity

getTagsForEntity(attributeCollection: RxCollection, entityType: string, orgId: string, userId?: string): Promise<AttributeModel[]>

Parameters:

Parameter	Type	Required
`attributeCollection`	`RxCollection`	Yes
`entityType`	`string`	Yes
`orgId`	`string`	Yes
`userId`	`string`	No

Returns:

Promise<AttributeModel[]> -

incrementPopularity

Increment popularity counter for an attribute

incrementPopularity(attributeCollection: RxCollection, attributeId: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`attributeCollection`	`RxCollection`	Yes
`attributeId`	`string`	Yes

Returns:

Promise<void> -

FlowstateAuthService

Constructor

constructor(config: FlowstateAuthServiceConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`FlowstateAuthServiceConfig`	Yes

Methods

sendVerificationCode

Send verification code to email

sendVerificationCode(email: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes

Returns:

Promise<void> -

login(email: string, code: string): Promise<AuthUser>

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes
`code`	`string`	Yes

Returns:

Promise<AuthUser> -

refresh

Refresh the access token

refresh(): Promise<void>

Returns:

Promise<void> -

logout

Logout and clear authentication

logout(): void

getAccessToken

Get the current access token

getAccessToken(): string

Returns:

string -

getRefreshToken

Get the current refresh token

getRefreshToken(): string

Returns:

string -

getUser

Get the current user

getUser(): AuthUser

Returns:

AuthUser -

isAuthenticated

Check if the user is authenticated

isAuthenticated(): boolean

Returns:

boolean -

getAuthHeaders

Get authentication headers for API requests

getAuthHeaders(): Record<string, string>

Returns:

Record<string, string> -

onAuthStateChange

Subscribe to authentication state changes

onAuthStateChange(callback: AuthStateChangeCallback): () => void

Parameters:

Parameter	Type	Required	Description
`callback`	`AuthStateChangeCallback`	Yes

Returns:

() => void -

onTokenRefresh

Subscribe to token refresh events. Called when tokens are stored or refreshed, with the new access token. Use this to sync auth tokens to external systems (e.g., ServerConfigService).

onTokenRefresh(callback: TokenRefreshCallback): () => void

Parameters:

Parameter	Type	Required	Description
`callback`	`TokenRefreshCallback`	Yes

Returns:

() => void -

destroy

Cleanup resources

destroy(): void

LoaderService

Manages loading state for global application loader system. Follows TimerService pattern with RxJS observables.

Constructor

constructor(config?: Partial<LoaderConfig>)

Parameters:

Parameter	Type	Required	Description
`config`	`Partial<LoaderConfig>`	No

Methods

getShouldHide$

Get observable of should hide state

getShouldHide$(): Observable<boolean>

Returns:

Observable<boolean> -

setShouldHide

Set should hide flag

setShouldHide(value: boolean): void

Parameters:

Parameter	Type	Required	Description
`value`	`boolean`	Yes

registerItem

registerItem(id: string, label: string, category?: string): void

Parameters:

Parameter	Type	Required
`id`	`string`	Yes
`label`	`string`	Yes
`category`	`string`	No

startItem

Start loading an item

startItem(id: string): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

updateProgress

Update progress for an item (0-100)

updateProgress(id: string, progress: number): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`progress`	`number`	Yes

completeItem

Mark an item as complete

completeItem(id: string): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

failItem

Mark an item as failed

failItem(id: string, error: string): void

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`error`	`string`	Yes

getState$

Get observable of loader state

getState$(): Observable<LoaderState>

Returns:

Observable<LoaderState> -

canHide

Check if minimum display time has elapsed

canHide(): boolean

Returns:

boolean -

waitForComplete

Wait for all items to complete + minimum display time, with optional timeout

waitForComplete(timeoutMs?: number): Promise<void>

Parameters:

Parameter	Type	Required	Description
`timeoutMs`	`number`	No	Maximum time to wait in milliseconds (default: 30000)

Returns:

Promise<void> -

reset

Reset loader state

reset(): void

instrumentRuntime

Instrument FlowstateRuntime to automatically track plugin loading

instrumentRuntime(runtime: FlowstateRuntime): void

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

destroy

Cleanup

destroy(): void

ServerConfigService

Server configuration service

Provides CRUD operations for server configurations with localForage persistence. Each instance can be isolated by namespace, allowing multiple apps to maintain separate server configurations.

Constructor

constructor(namespace?: string)

Parameters:

Parameter	Type	Required	Description
`namespace`	`string`	No	- Storage namespace for isolation (default: 'epic-flow')

Methods

getAll

Get all server configurations

getAll(): Promise<ServerConfig[]>

Returns:

Promise<ServerConfig[]> - Promise<ServerConfig[]> - Array of server configurations

Examples:

const servers = await service.getAll();
console.log(`Found ${servers.length} servers`);

getById

Get server configuration by ID

getById(id: string): Promise<ServerConfig>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	- Server configuration ID

Returns:

Promise<ServerConfig> - Promise<ServerConfig | null> - Server configuration or null if not found

Examples:

const server = await service.getById('server-123');
if (server) {
  console.log(`Found server: ${server.name}`);
}

create

Create new server configuration

Automatically generates ID and sets createdAt timestamp. If this is the first server, it's automatically set as active.

create(config: Omit<ServerConfig, "id" | "createdAt">): Promise<ServerConfig>

Parameters:

Parameter	Type	Required	Description
`config`	`Omit<ServerConfig, "id" \| "createdAt">`	Yes	- Server configuration (without id and createdAt)

Returns:

Promise<ServerConfig> - Promise<ServerConfig> - Created server configuration

Examples:

const server = await service.create({
  name: 'Production',
  url: 'https://api.example.com',
  databaseName: 'flowstate-prod',
  authToken: 'prod-token',
  domainId: 'prod',
  userId: 'user-1',
  orgId: 'org-1',
  isActive: false
});

update

Update existing server configuration

Supports partial updates. Automatically sets updatedAt timestamp. ID and createdAt cannot be changed.

update(id: string, updates: Partial<ServerConfig>): Promise<ServerConfig>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	- Server configuration ID
`updates`	`Partial<ServerConfig>`	Yes	- Partial server configuration updates

Returns:

Promise<ServerConfig> - Promise<ServerConfig> - Updated server configuration

Examples:

const updated = await service.update('server-123', {
  name: 'Production (Updated)',
  replicationEnabled: false
});

delete

Delete server configuration

delete(id: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	- Server configuration ID

Returns:

Promise<void> - Promise<void>

Examples:

await service.delete('server-123');

getActiveServer

Get active server configuration

getActiveServer(): Promise<ServerConfig>

Returns:

Promise<ServerConfig> - Promise<ServerConfig | null> - Active server configuration or null if none set

Examples:

const activeServer = await service.getActiveServer();
if (activeServer) {
  console.log(`Active server: ${activeServer.name}`);
}

setActiveServer

Set active server

Updates the lastConnected timestamp for the server.

setActiveServer(id: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	- Server configuration ID

Returns:

Promise<void> - Promise<void>

Examples:

await service.setActiveServer('server-123');

clearActiveServer

Clear active server

clearActiveServer(): Promise<void>

Returns:

Promise<void> - Promise<void>

Examples:

await service.clearActiveServer();

clearAll

Clear all server configurations

WARNING: This will delete all server data

clearAll(): Promise<void>

Returns:

Promise<void> - Promise<void>

Examples:

await service.clearAll();

initializeDefaultServer

Initialize default server configuration if no servers exist

initializeDefaultServer(): Promise<ServerConfig>

Returns:

Promise<ServerConfig> - Promise<ServerConfig | null> - Created default server or null if servers already exist

Examples:

const defaultServer = await service.initializeDefaultServer();
if (defaultServer) {
  console.log('Default server created');
}

exportToJSON

Export all server configurations as JSON

Includes metadata about the export for versioning and validation.

exportToJSON(): Promise<string>

Returns:

Promise<string> - Promise<string> - JSON string of all server configurations

Examples:

const json = await service.exportToJSON();
// Save to file or clipboard
navigator.clipboard.writeText(json);

importFromJSON

Import server configurations from JSON

WARNING: This will overwrite existing configurations

importFromJSON(json: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`json`	`string`	Yes	- JSON string of server configurations

Returns:

Promise<void> - Promise<void>

Examples:

const json = '{"servers": [...], "activeServerId": "server-123"}';
await service.importFromJSON(json);

testConnection

Test connection to a server

Attempts to connect to the server's health endpoint with a 5-second timeout. Verifies the server is reachable and returns a 200 OK response.

testConnection(config: ServerConfig, timeoutMs?: number): Promise<boolean>

Parameters:

Parameter	Type	Required	Description
`config`	`ServerConfig`	Yes	- Server configuration to test
`timeoutMs`	`number`	No	- Connection timeout in milliseconds (default: 5000)

Returns:

Promise<boolean> - Promise<boolean> - True if connection successful, false otherwise

Examples:

const isConnected = await service.testConnection(serverConfig);
if (isConnected) {
  console.log('Server is reachable');
} else {
  console.log('Server is unreachable');
}

Examples:

// Use default namespace
const service = new ServerConfigService();

// Use custom namespace for app isolation
const service = new ServerConfigService('my-custom-app');

// Create a server config
const server = await service.create({
  name: 'Development',
  url: 'http://localhost:7002',
  databaseName: 'flowstate-dev',
  authToken: 'dev-token',
  domainId: 'dev',
  userId: 'user-1',
  orgId: 'org-1',
  isActive: false
});

ServiceRegistry

Service registry for dependency injection Supports instance, factory, and singleton patterns

Methods

register

register(name: string, instance: T): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`instance`	`T`	Yes

registerFactory

registerFactory(name: string, factory: ServiceFactory<T>): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`factory`	`ServiceFactory<T>`	Yes

registerSingleton

registerSingleton(name: string, factory: ServiceFactory<T>): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes
`factory`	`ServiceFactory<T>`	Yes

get

Get service by name with type-safe return

get(name: string): T

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes

Returns:

T -

has

Check if service exists

has(name: string): boolean

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes

Returns:

boolean -

unregister

Unregister service

unregister(name: string): void

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes

getServiceNames

Get all service names

getServiceNames(): string[]

Returns:

string[] -

clear

Clear all services (for testing)

clear(): void

BaseSyncProvider

Abstract base class that implements common functionality for sync providers.

Concrete providers should extend this class and implement:

metadata - Provider metadata describing capabilities
doSync() - The actual sync logic
doTestConnection() - The actual connection test logic

Properties

Property	Type	Required	Description
`metadata`	`SyncProviderMetadata`	Yes	Provider metadata describing capabilities and configuration.
Must be implemented by concrete providers.
`state`	`SyncState`	Yes	Current state of the sync provider
`eventHandlers`	`Set<SyncEventHandler>`	Yes	Set of event handlers for sync events
`abortController`	`AbortController`	Yes	Abort controller for canceling in-progress syncs

Methods

initialize

Initialize the provider with the given configuration. Default no-op implementation. Override if initialization is needed.

initialize(_config: SyncProviderConfig): Promise<void>

Parameters:

Parameter	Type	Required	Description
`_config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<void> -

sync

Perform a sync operation. Wraps doSync with state management, event emission, and error handling.

sync(config: SyncProviderConfig): Promise<SyncResult>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<SyncResult> - Sync result with statistics and any errors

doSync

Abstract method - concrete providers implement the actual sync logic.

doSync(config: SyncProviderConfig): Promise<SyncResult>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<SyncResult> - Sync result with statistics

testConnection

Test the connection to the external service. Wraps doTestConnection with error handling.

testConnection(config: SyncProviderConfig): Promise<{ success: boolean; error?: string; }>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<{ success: boolean; error?: string; }> - Success status and optional error message

doTestConnection

Abstract method - concrete providers implement the actual connection test.

doTestConnection(config: SyncProviderConfig): Promise<{ success: boolean; error?: string; }>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<{ success: boolean; error?: string; }> - Success status and optional error message

getState

Get the current sync state. Returns a copy to prevent external mutation.

getState(): SyncState

Returns:

SyncState - Current sync state

Subscribe to sync events.

subscribe(handler: SyncEventHandler): () => void

Parameters:

Parameter	Type	Required	Description
`handler`	`SyncEventHandler`	Yes	- Event handler function

Returns:

() => void - Unsubscribe function

dispose

Dispose of provider resources. Cancels any in-progress sync, clears handlers, and resets state.

dispose(): Promise<void>

Returns:

Promise<void> -

updateState

Update the internal state with partial updates.

updateState(updates: Partial<SyncState>): void

Parameters:

Parameter	Type	Required	Description
`updates`	`Partial<SyncState>`	Yes	- Partial state updates to apply

emitEvent

Emit an event to all subscribers.

emitEvent(event: SyncEvent): void

Parameters:

Parameter	Type	Required	Description
`event`	`SyncEvent`	Yes	- The sync event to emit

isAborted

Check if the current sync has been aborted.

isAborted(): boolean

Returns:

boolean - True if the sync has been aborted

getAbortSignal

Get the abort signal for the current sync. Useful for passing to fetch requests or other abortable operations.

getAbortSignal(): AbortSignal

Returns:

AbortSignal - AbortSignal if syncing, undefined otherwise

Examples:

class GitHubSyncProvider extends BaseSyncProvider {
  readonly metadata: SyncProviderMetadata = {
    id: 'github',
    name: 'GitHub',
    // ...
  };

  protected async doSync(config: SyncProviderConfig): Promise<SyncResult> {
    // Implement GitHub-specific sync logic
  }

  protected async doTestConnection(config: SyncProviderConfig): Promise<{ success: boolean; error?: string }> {
    // Implement GitHub-specific connection test
  }
}

SyncConfigService

Service for managing sync configurations

Constructor

constructor(db: RxDatabase)

Parameters:

Parameter	Type	Required	Description
`db`	`RxDatabase`	Yes

Methods

create

Create a new sync configuration

create(input: CreateSyncConfigInput): Promise<DeserializedSyncConfig>

Parameters:

Parameter	Type	Required	Description
`input`	`CreateSyncConfigInput`	Yes

Returns:

Promise<DeserializedSyncConfig> -

getByWorkspace

Get all sync configurations for a workspace

getByWorkspace(workspaceId: string): Promise<DeserializedSyncConfig[]>

Parameters:

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes

Returns:

Promise<DeserializedSyncConfig[]> -

getByProvider

Get sync configurations for a workspace filtered by provider

getByProvider(workspaceId: string, providerId: string): Promise<DeserializedSyncConfig[]>

Parameters:

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes
`providerId`	`string`	Yes

Returns:

Promise<DeserializedSyncConfig[]> -

getById

Get a single sync configuration by ID

getById(id: string): Promise<DeserializedSyncConfig>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

Promise<DeserializedSyncConfig> -

update

Update a sync configuration

update(id: string, updates: UpdateSyncConfigInput): Promise<DeserializedSyncConfig>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`updates`	`UpdateSyncConfigInput`	Yes

Returns:

Promise<DeserializedSyncConfig> -

delete

Soft delete a sync configuration (archive)

delete(id: string): Promise<boolean>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

Promise<boolean> -

updateSyncStatus

Update sync status after a sync operation

updateSyncStatus(id: string, status: SyncStatusUpdate): Promise<boolean>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`status`	`SyncStatusUpdate`	Yes

Returns:

Promise<boolean> -

getEnabled

Get enabled sync configurations for a workspace

getEnabled(workspaceId: string): Promise<DeserializedSyncConfig[]>

Parameters:

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes

Returns:

Promise<DeserializedSyncConfig[]> -

deserializeConfig

Deserialize a sync config document by parsing JSON fields

deserializeConfig(doc: SyncConfigModel): DeserializedSyncConfig

Parameters:

Parameter	Type	Required	Description
`doc`	`SyncConfigModel`	Yes

Returns:

DeserializedSyncConfig -

toProviderConfig

Convert a deserialized config to SyncProviderConfig format for use with sync providers

toProviderConfig(config: DeserializedSyncConfig): SyncProviderConfig

Parameters:

Parameter	Type	Required	Description
`config`	`DeserializedSyncConfig`	Yes

Returns:

SyncProviderConfig -

SyncProviderRegistry

Singleton registry for managing sync provider registrations and instances.

Features:

Lazy instantiation: Providers are created only when first accessed
Singleton pattern: Single registry instance across the application
Metadata access: Get provider metadata without full instantiation
Disposal support: Properly clean up provider resources

Constructor

constructor()

Methods

getInstance

Get the singleton instance of the registry

getInstance(): SyncProviderRegistry

Returns:

SyncProviderRegistry -

register

The factory will be called lazily on first access via get(). Warns if a provider with the same ID is already registered.

register(providerId: string, factory: SyncProviderFactory): void

Parameters:

Parameter	Type	Required	Description
`providerId`	`string`	Yes	- Unique identifier for the provider
`factory`	`SyncProviderFactory`	Yes	- Factory function to create the provider instance

get

Get a provider instance by ID.

Uses lazy instantiation - the provider is created on first access and cached for subsequent calls.

get(providerId: string): SyncProvider

Parameters:

Parameter	Type	Required	Description
`providerId`	`string`	Yes	- The provider ID to retrieve

Returns:

SyncProvider - The provider instance

has

Check if a provider is registered.

has(providerId: string): boolean

Parameters:

Parameter	Type	Required	Description
`providerId`	`string`	Yes	- The provider ID to check

Returns:

boolean - True if the provider is registered

getMetadata

Get metadata for a registered provider.

Note: This will instantiate the provider if not already instantiated.

getMetadata(providerId: string): SyncProviderMetadata

Parameters:

Parameter	Type	Required	Description
`providerId`	`string`	Yes	- The provider ID

Returns:

SyncProviderMetadata - The provider metadata, or undefined if not registered

getAllProviders

Get all registered provider instances.

This will instantiate all providers that haven't been instantiated yet.

getAllProviders(): SyncProvider[]

Returns:

SyncProvider[] - Array of all provider instances

getAllMetadata

Get metadata for all registered providers.

This will instantiate all providers that haven't been instantiated yet.

getAllMetadata(): SyncProviderMetadata[]

Returns:

SyncProviderMetadata[] - Array of all provider metadata

getProviderIds

Get all registered provider IDs.

Does not instantiate providers.

getProviderIds(): string[]

Returns:

string[] - Array of all registered provider IDs

unregister

Unregister a provider.

If the provider was instantiated, it will be disposed before removal.

unregister(providerId: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`providerId`	`string`	Yes	- The provider ID to unregister

Returns:

Promise<void> -

disposeAll

Dispose all instantiated providers.

Clears all instances but keeps factory registrations. This should be called during application shutdown.

disposeAll(): Promise<void>

Returns:

Promise<void> -

reset

Reset the registry completely.

Clears all registrations and instances. Primarily used for testing. Note: This does NOT dispose instances - call disposeAll() first if needed.

reset(): void

Examples:

const registry = getSyncProviderRegistry();

// Register a provider factory
registry.register('github', () => new GitHubSyncProvider());

// Get provider instance (lazy instantiation)
const provider = registry.get('github');

// Get all available providers
const allProviders = registry.getAllProviders();

// Clean up on shutdown
await registry.disposeAll();

OrgThemeLoader

Manages organization-scoped themes. Each organization can have its own theme that applies to all users within that organization.

Supports two modes:

Mock mode (default): Uses in-memory storage for development/testing
Database mode: Uses RxDB for persistence

Constructor

constructor(config?: OrgThemeLoaderConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`OrgThemeLoaderConfig`	No	- Optional configuration for storage mode

Methods

loadOrgTheme

Load theme for an organization

loadOrgTheme(orgId: string): Promise<Theme>

Parameters:

Parameter	Type	Required	Description
`orgId`	`string`	Yes	- Organization ID to load theme for

Returns:

Promise<Theme> - Promise resolving to Theme if found, null otherwise

Examples:

const loader = new OrgThemeLoader();
const theme = await loader.loadOrgTheme('org-123');
if (theme) {
  console.log(`Loaded theme: ${theme.name}`);
}

saveOrgTheme

Save theme for an organization

Sets the theme for a specific organization. The orgId is automatically added to the theme and the updatedAt timestamp is refreshed.

saveOrgTheme(orgId: string, theme: Theme): Promise<void>

Parameters:

Parameter	Type	Required	Description
`orgId`	`string`	Yes	- Organization ID to save theme for
`theme`	`Theme`	Yes	- Theme to save (orgId will be set automatically)

Returns:

Promise<void> -

Examples:

const loader = new OrgThemeLoader();
const theme = createTheme({
  name: 'Acme Corp Theme',
  colors: { light: { primary: 'oklch(0.6 0.18 120)' } }
});
await loader.saveOrgTheme('org-123', theme);

deleteOrgTheme

Delete theme for an organization

Removes the organization's custom theme. After deletion, the organization will fall back to the default theme.

deleteOrgTheme(orgId: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`orgId`	`string`	Yes	- Organization ID to delete theme for

Returns:

Promise<void> -

Examples:

const loader = new OrgThemeLoader();
await loader.deleteOrgTheme('org-123');
// Organization will now use default theme

setMockTheme

Set mock theme (for testing)

Directly sets a theme in the mock storage. Useful for setting up test fixtures.

setMockTheme(orgId: string, theme: Theme): void

Parameters:

Parameter	Type	Required	Description
`orgId`	`string`	Yes	- Organization ID
`theme`	`Theme`	Yes	- Theme to set (orgId will be added)

clearMockThemes

Clear all mock themes (for testing)

Removes all themes from mock storage. Useful for cleaning up between tests.

clearMockThemes(): void

Examples:

// Mock mode (default)
const loader = new OrgThemeLoader();

// Database mode
const loader = new OrgThemeLoader({
  useMock: false,
  database: myRxDatabase,
});

// Save a theme for an organization
await loader.saveOrgTheme('org-123', myTheme);

// Load the theme later
const theme = await loader.loadOrgTheme('org-123');
if (theme) {
  themeService.setTheme(theme);
}

ThemeService

Singleton service for managing global theming state. Supports light/dark/system modes with localStorage persistence.

Constructor

constructor(config?: Partial<ThemeConfig>)

Parameters:

Parameter	Type	Required	Description
`config`	`Partial<ThemeConfig>`	No

Methods

getInstance

Get singleton instance

getInstance(config?: Partial<ThemeConfig>): ThemeService

Parameters:

Parameter	Type	Required	Description
`config`	`Partial<ThemeConfig>`	No

Returns:

ThemeService -

resetInstance

Reset singleton (for testing)

resetInstance(): void

getState

Get current state snapshot

getState(): ThemeState

Returns:

ThemeState -

getState$

Get observable of theme state

getState$(): Observable<ThemeState>

Returns:

Observable<ThemeState> -

setMode

Set theme mode (light, dark, or system)

setMode(mode: ThemeMode): void

Parameters:

Parameter	Type	Required	Description
`mode`	`ThemeMode`	Yes

setTheme

Set the current theme

setTheme(theme: Theme): void

Parameters:

Parameter	Type	Required	Description
`theme`	`Theme`	Yes

loadOrgTheme

Load and apply organization theme

Asynchronously loads the theme for a specific organization using the provided OrgThemeLoader. If a theme is found, it is automatically applied via setTheme().

loadOrgTheme(orgId: string, loader: OrgThemeLoader): Promise<void>

Parameters:

Parameter	Type	Required	Description
`orgId`	`string`	Yes	- Organization ID to load theme for
`loader`	`OrgThemeLoader`	Yes	- OrgThemeLoader instance for fetching the theme

Returns:

Promise<void> -

Examples:

const loader = new OrgThemeLoader();
const service = ThemeService.getInstance();
await service.loadOrgTheme('org-123', loader);

setBranding

Update branding configuration

setBranding(branding: Partial<ThemeBranding>): void

Parameters:

Parameter	Type	Required	Description
`branding`	`Partial<ThemeBranding>`	Yes

getCSSVariables

Generate CSS variables string for the current theme

getCSSVariables(): string

Returns:

string -

on

Subscribe to theme events

on(event: string, handler: (data: T) => void): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`(data: T) => void`	Yes

Returns:

() => void -

once

Subscribe to theme event once

once(event: string, handler: (data: T) => void): () => void

Parameters:

Parameter	Type	Required	Description
`event`	`string`	Yes
`handler`	`(data: T) => void`	Yes

Returns:

() => void -

applyTheme

Apply current theme to the document

This method:

Toggles the 'dark' class on the document root element
Injects/updates CSS variables via a style element

applyTheme(): void

destroy

Destroy the service and clean up resources

destroy(): void

OnboardingPlugin

Orchestrates multi-step onboarding flows by:

Collecting onboarding steps from other plugins
Sorting steps by dependencies
Providing OnboardingContext for state management
Managing onboarding flow lifecycle

Features:

Plugin-based step registration
Dependency-based step ordering
Progress persistence via localStorage
Configurable behavior (auto-start, skip, etc.)

Constructor

constructor(config?: OnboardingPluginConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`OnboardingPluginConfig`	No

Properties

Property	Type	Required
`name`	`string`	Yes
`version`	`string`	Yes
`dependencies`	`string[]`	Yes

Methods

getOnboardingSteps

Returns the built-in onboarding steps for this plugin Implements OnboardingCapablePlugin interface

getOnboardingSteps(): OnboardingStep[]

Returns:

OnboardingStep[] -

onRegister

Called during plugin registration Collects onboarding steps from all registered plugins

onRegister(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onMount

onMount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

onUnmount

onUnmount(runtime: FlowstateRuntime): Promise<void>

Parameters:

Parameter	Type	Required	Description
`runtime`	`FlowstateRuntime`	Yes

Returns:

Promise<void> -

providesContext

Provides the OnboardingContext to the application

providesContext(): React.Context<any>[]

Returns:

React.Context<any>[] -

getProvider

Returns the provider component that wraps the application

getProvider(): React.ComponentType<{ children: React.ReactNode; }>

Returns:

React.ComponentType<{ children: React.ReactNode; }> -

getSteps

Get all registered onboarding steps Useful for debugging or external access

getSteps(): OnboardingStep[]

Returns:

OnboardingStep[] -

registerSteps

Manually register additional steps after initialization Useful for dynamic step registration

registerSteps(steps: OnboardingStep[]): void

Parameters:

Parameter	Type	Required	Description
`steps`	`OnboardingStep[]`	Yes

Examples:

const Container = createFlowstateContainer({
  plugins: [
    new DatabasePlugin({ adapter: createAdapter() }),
    new AuthPlugin(), // Registers user creation step
    new OrgWorkspacePlugin({ mode: 'global' }), // Registers org/workspace steps
    new OnboardingPlugin({
      autoStart: true,
      allowSkip: false,
      onComplete: (data) => console.log('Onboarding complete:', data),
    }),
  ],
});

CustomApiClient

Custom API client for executing configured requests

Constructor

constructor(config: CustomApiProviderConfig, credentials: Record<string, string>, abortSignal?: AbortSignal)

Parameters:

Parameter	Type	Required
`config`	`CustomApiProviderConfig`	Yes
`credentials`	`Record<string, string>`	Yes
`abortSignal`	`AbortSignal`	No

Methods

listItems

List all items

listItems(params?: Record<string, any>): Promise<any[]>

Parameters:

Parameter	Type	Required	Description
`params`	`Record<string, any>`	No

Returns:

Promise<any[]> -

getItem

Get a single item

getItem(id: string): Promise<any>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

Promise<any> -

createItem

Create an item

createItem(data: Record<string, any>): Promise<any>

Parameters:

Parameter	Type	Required	Description
`data`	`Record<string, any>`	Yes

Returns:

Promise<any> -

updateItem

Update an item

updateItem(id: string, data: Record<string, any>): Promise<any>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes
`data`	`Record<string, any>`	Yes

Returns:

Promise<any> -

deleteItem

Delete an item

deleteItem(id: string): Promise<void>

Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes

Returns:

Promise<void> -

testConnection

Test connection

testConnection(): Promise<{ success: boolean; error?: string; }>

Returns:

Promise<{ success: boolean; error?: string; }> -

CustomApiSyncProvider

Properties

Property	Type	Required	Description
`metadata`	`SyncProviderMetadata`	Yes

Methods

setDatabase

setDatabase(db: any): void

Parameters:

Parameter	Type	Required	Description
`db`	`any`	Yes

doSync

doSync(config: SyncProviderConfig): Promise<SyncResult>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes

Returns:

Promise<SyncResult> -

doTestConnection

doTestConnection(config: SyncProviderConfig): Promise<{ success: boolean; error?: string; }>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes

Returns:

Promise<{ success: boolean; error?: string; }> -

GitHubApiError

Error thrown when GitHub API request fails

Constructor

constructor(message: string, status: number, response?: unknown)

Parameters:

Parameter	Type	Required
`message`	`string`	Yes
`status`	`number`	Yes
`response`	`unknown`	No

GitHubApiClient

Client for interacting with the GitHub REST API.

Provides methods for:

User operations (get authenticated user)
Repository operations (get repo, list repos)
Issue operations (list, get, create, update)
Connection testing

Constructor

constructor(accessToken: string, abortSignal?: AbortSignal)

Parameters:

Parameter	Type	Required	Description
`accessToken`	`string`	Yes	- GitHub OAuth access token
`abortSignal`	`AbortSignal`	No	- Optional AbortSignal for canceling requests

Methods

getUser

Get the authenticated user

getUser(): Promise<GitHubUser>

Returns:

Promise<GitHubUser> - The authenticated user's information

Examples:

const user = await client.getUser();
console.log(`Logged in as ${user.login}`);

getRepository

Get repository information

getRepository(owner: string, repo: string): Promise<GitHubRepository>

Parameters:

Parameter	Type	Required	Description
`owner`	`string`	Yes	- Repository owner (user or organization)
`repo`	`string`	Yes	- Repository name

Returns:

Promise<GitHubRepository> - Repository information

Examples:

const repo = await client.getRepository('octocat', 'Hello-World');
console.log(`${repo.full_name} has ${repo.open_issues_count} open issues`);

listRepositories

List repositories for the authenticated user

listRepositories(options?: { visibility?: "all" | "public" | "private"; affiliation?: string; sort?: "created" | "updated" | "pushed" | "full_name"; direction?: "asc" | "desc"; per_page?: number; page?: number; }): Promise<GitHubRepository[]>

Parameters:

Parameter	Type	Required	Description
`options`	`{ visibility?: "all" \| "public" \| "private"; affiliation?: string; sort?: "created" \| "updated" \| "pushed" \| "full_name"; direction?: "asc" \| "desc"; per_page?: number; page?: number; }`	No	- List options

Returns:

Promise<GitHubRepository[]> - Array of repositories

Examples:

const repos = await client.listRepositories();
for (const repo of repos) {
  console.log(repo.full_name);
}

listIssues

List issues for a repository

listIssues(owner: string, repo: string, options?: ListIssuesOptions): Promise<GitHubIssue[]>

Parameters:

Parameter	Type	Required	Description
`owner`	`string`	Yes	- Repository owner
`repo`	`string`	Yes	- Repository name
`options`	`ListIssuesOptions`	No	- Filter and pagination options

Returns:

Promise<GitHubIssue[]> - Array of issues

Examples:

const issues = await client.listIssues('octocat', 'Hello-World', {
  state: 'open',
  labels: 'bug',
  per_page: 100,
});

getIssue

Get a single issue by number

getIssue(owner: string, repo: string, issueNumber: number): Promise<GitHubIssue>

Parameters:

Parameter	Type	Required	Description
`owner`	`string`	Yes	- Repository owner
`repo`	`string`	Yes	- Repository name
`issueNumber`	`number`	Yes	- Issue number

Returns:

Promise<GitHubIssue> - Issue details

Examples:

const issue = await client.getIssue('octocat', 'Hello-World', 123);
console.log(`#${issue.number}: ${issue.title}`);

createIssue

Create a new issue

createIssue(owner: string, repo: string, data: CreateIssueData): Promise<GitHubIssue>

Parameters:

Parameter	Type	Required	Description
`owner`	`string`	Yes	- Repository owner
`repo`	`string`	Yes	- Repository name
`data`	`CreateIssueData`	Yes	- Issue data

Returns:

Promise<GitHubIssue> - The created issue

Examples:

const issue = await client.createIssue('octocat', 'Hello-World', {
  title: 'New feature request',
  body: 'It would be great if...',
  labels: ['enhancement'],
});

updateIssue

Update an existing issue

updateIssue(owner: string, repo: string, issueNumber: number, data: UpdateIssueData): Promise<GitHubIssue>

Parameters:

Parameter	Type	Required	Description
`owner`	`string`	Yes	- Repository owner
`repo`	`string`	Yes	- Repository name
`issueNumber`	`number`	Yes	- Issue number to update
`data`	`UpdateIssueData`	Yes	- Fields to update

Returns:

Promise<GitHubIssue> - The updated issue

Examples:

const issue = await client.updateIssue('octocat', 'Hello-World', 123, {
  state: 'closed',
  state_reason: 'completed',
});

testConnection

Test the API connection and authentication

testConnection(): Promise<{ success: boolean; user?: GitHubUser; error?: string; }>

Returns:

Promise<{ success: boolean; user?: GitHubUser; error?: string; }> - Object with success status and optional user/error info

Examples:

const result = await client.testConnection();
if (result.success) {
  console.log(`Connected as ${result.user?.login}`);
} else {
  console.error(`Connection failed: ${result.error}`);
}

Examples:

const client = new GitHubApiClient(accessToken);

// Get authenticated user
const user = await client.getUser();

// List issues from a repository
const issues = await client.listIssues('owner', 'repo', { state: 'open' });

// Create a new issue
const newIssue = await client.createIssue('owner', 'repo', {
  title: 'New Issue',
  body: 'Issue description',
});

GitHubSyncProvider

Sync provider for GitHub Issues.

Syncs GitHub issues to FlowState tasks with support for:

Pull: Import issues as tasks
Push: Create/update issues from tasks
Bidirectional: Both pull and push

Properties

Property	Type	Required	Description
`metadata`	`SyncProviderMetadata`	Yes	Provider metadata describing GitHub sync capabilities

Methods

setDatabase

Set the database instance for the provider

setDatabase(db: RxDatabase): void

Parameters:

Parameter	Type	Required	Description
`db`	`RxDatabase`	Yes	- RxDB database instance

doSync

Perform the actual sync operation

doSync(config: SyncProviderConfig): Promise<SyncResult>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<SyncResult> - Sync result with statistics

doTestConnection

Test the connection to GitHub

doTestConnection(config: SyncProviderConfig): Promise<{ success: boolean; error?: string; }>

Parameters:

Parameter	Type	Required	Description
`config`	`SyncProviderConfig`	Yes	- Provider configuration

Returns:

Promise<{ success: boolean; error?: string; }> - Success status and optional error

Examples:

const provider = new GitHubSyncProvider();
provider.setDatabase(db);

const result = await provider.sync({
  id: 'config-1',
  providerId: 'github',
  credentials: { accessToken: 'ghp_xxx' },
  providerConfig: { repository: 'owner/repo' },
  direction: 'bidirectional',
  // ...
});