Documentation · GitHub · Changelog

Overview

@bpmn-sdk/profiles is the shared layer that connects the casen CLI with the local proxy server. It handles profile CRUD (read/write to ~/.config/casen/config.json), creates typed CamundaClient instances from stored profiles, and resolves Authorization headers for any supported auth type.

You do not need this package if you are connecting directly to Camunda using @bpmn-sdk/api. It is intended for tooling that needs to share authentication state with the CLI.

Features

• Profile CRUD — list, get, save, delete, and activate named profiles stored in ~/.config/casen/config.json
• Client factory — createClientFromProfile(name?) creates a ready-to-use CamundaClient from the active or named profile
• Auth header resolution — getAuthHeader(config) returns the correct Authorization header string for Bearer, Basic, and OAuth2 auth types
• OAuth2 token caching — tokens are cached in memory and refreshed 60 seconds before expiry; no extra files written
• XDG-aware — profile file path resolves to the correct platform directory (Linux XDG, macOS, Windows AppData)
• Zero UI dependencies — no TUI or CLI dependencies; plain Node.js

Installation

npm install @bpmn-sdk/profiles

Quick Start

Create a CamundaClient from the active profile

import { createClientFromProfile } from "@bpmn-sdk/profiles"

// Uses the currently active profile from ~/.config/casen/config.json
const client = createClientFromProfile()

const instances = await client.processInstance.searchProcessInstances({})
console.log(instances.page.totalItems)

Use a named profile

const client = createClientFromProfile("production")

Resolve an auth header directly

import { getActiveProfile, getAuthHeader } from "@bpmn-sdk/profiles"

const profile = getActiveProfile()
if (profile) {
  const header = await getAuthHeader(profile.config)
  // "Bearer eyJ..." or "Basic dXNlcjpwYXNz" or ""
}

Manage profiles programmatically

import { listProfiles, saveProfile, useProfile, deleteProfile } from "@bpmn-sdk/profiles"

// List all profiles
const profiles = listProfiles()

// Save a new profile
saveProfile({
  name: "local",
  apiType: "self-managed",
  config: {
    baseUrl: "http://localhost:8080/v2",
    auth: { type: "basic", username: "admin", password: "admin" },
  },
})

// Activate a profile
useProfile("local")

// Delete a profile
deleteProfile("old-profile")

API Reference

Profile Management

| Export | Description | |--------|-------------| | listProfiles() | Returns all stored profiles | | getProfile(name) | Returns a profile by name, or undefined | | getActiveProfile() | Returns the currently active profile | | getActiveName() | Returns the active profile name | | saveProfile(profile) | Create or update a profile | | deleteProfile(name) | Remove a profile | | useProfile(name) | Set the active profile | | getConfigFilePath() | Returns the full path to the config file |

Client Factories

| Export | Description | |--------|-------------| | createClientFromProfile(name?) | CamundaClient from the active or named profile | | createAdminClientFromProfile(name?) | AdminApiClient from the active or named profile |

Auth

| Export | Description | |--------|-------------| | getAuthHeader(config) | Resolves an Authorization header string for any auth type |

Related Packages

| Package | Description | |---------|-------------| | @bpmn-sdk/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmn-sdk/canvas | Zero-dependency SVG BPMN viewer | | @bpmn-sdk/editor | Full-featured interactive BPMN editor | | @bpmn-sdk/engine | Lightweight BPMN process execution engine | | @bpmn-sdk/feel | FEEL expression language parser & evaluator | | @bpmn-sdk/plugins | 22 composable canvas plugins | | @bpmn-sdk/api | Camunda 8 REST API TypeScript client | | @bpmn-sdk/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmn-sdk/operate | Monitoring & operations frontend for Camunda clusters |

License

MIT © bpmn-sdk