TypeScript/JavaScript SDK for fluidsoul — sendEvent, refreshContext, getContext.

SDK Reference

The fluidsoul-js package provides a TypeScript/JavaScript client for the fluidsoul API. Works in any environment with the Fetch API: browsers, Node.js 18+, Electron, VS Code extensions, Figma plugins.

Installation

npm install fluidsoul-js

Configuration

import type { FluidsoulConfig } from "fluidsoul-js"

const config: FluidsoulConfig = {
  apiUrl: process.env.FLUIDSOUL_API_URL!,
  token: process.env.FLUIDSOUL_API_TOKEN!,
  workspaceId: process.env.FLUIDSOUL_WORKSPACE_ID!,
}

Core functions

sendEvent

Record a user action event. Call this whenever a user does something meaningful.

import { sendEvent } from "fluidsoul-js"

await sendEvent(config, {
  userId: "user_123",
  eventType: "report_viewed",
  metadata: { category: "analytics" },
})

refreshContext

Trigger a context recomputation for a user.

import { refreshContext } from "fluidsoul-js"

await refreshContext(config, "user_123")

getContext

Fetch the current computed context for a user. Returns null if no context exists.

import { getContext } from "fluidsoul-js"

const ctx = await getContext(config, "user_123")

if (ctx) {
  console.log(ctx.user_category)       // e.g. "analyst"
  console.log(ctx.preferred_mode)       // e.g. "analyst"
  console.log(ctx.feature_priorities)   // e.g. ["reports", "analytics"]
  console.log(ctx.recommended_defaults) // e.g. { default_view: "reports" }
  console.log(ctx.engagement_level)     // "low" | "moderate" | "high"
  console.log(ctx.user_maturity)        // "new" | "intermediate" | "power_user"
}

Types

FluidsoulConfig

Field	Type	Description
`apiUrl`	string	API server URL
`token`	string	Bearer token
`workspaceId`	string	Workspace UUID

UserContext

Field	Type	Description
`user_category`	string	Classification result
`preferred_mode`	string	Dominant dimension value
`feature_priorities`	string[]	Features ordered by relevance
`recommended_defaults`	Record<string, string>	Suggested default settings
`engagement_level`	string	`"low"` / `"moderate"` / `"high"`
`user_maturity`	string	`"new"` / `"intermediate"` / `"power_user"`
`confidence_scores`	Record<string, number>	Confidence per inference
`explainability`	string[]	Plain-English reasons
`user_narrative`	string \| null	Optional LLM narrative
`inference_source`	string	`"rules"` or `"rules+llm"`

SendEventInput

Field	Type	Required	Description
`userId`	string	Yes	User identifier
`eventType`	string	Yes	What the user did
`metadata`	Record<string, unknown>	No	Extra details

FluidsoulError

Thrown when an API call fails. Includes status, endpoint, and body.

Error handling

import { FluidsoulError } from "fluidsoul-js"

try {
  await sendEvent(config, input)
} catch (err) {
  if (err instanceof FluidsoulError) {
    console.error(`API error ${err.status}: ${err.message}`)
  }
}

SDK Reference

On this page