@sylphx/management

Pure-FP Promise client for the Sylphx Platform Management API — contract-first capability namespaces, zero classes.

The SDK is a thin, stateless transport over api.sylphx.com/v1. No classes, no mutable state, no business logic — consumers create an immutable Client and pass it to free functions grouped by capability namespace. Every request / response type is imported from @sylphx/contract — the Effect Schema single source of truth (ADR-084).

Scope: Management plane only (ADR-083). This SDK covers platform-owner operations (project / deployment / environment / secret / domain / audit / billing / SAML / OIDC / webhooks / privacy / analytics admin, …) on api.sylphx.com/v1 with Bearer tokens (svc_... service tokens or OAuth access JWTs). For app-runtime data-plane operations (auth, KV, transactional email, push, realtime, flags.evaluate, search, analytics.track, AI, storage uploads, end-user session replay) use @sylphx/sdk — one package, Firebase-pattern with ./, ./react, ./server, ./nextjs, ./web-analytics, ./health peer-dep-gated entry points. Mixing planes (wrong hostname + wrong auth scheme) returns 401 plane_mismatch.

Requirements

• Node.js >= 20 (uses built-in fetch) — or Bun >= 1.3
• A Sylphx API token:
  • OAuth access token (eyJ...) — minted by the OAuth/device flow and suitable for user-scoped automation
  • Service token (svc_...) — for CI / server-side automation, created through the Management API / CLI token flow

Installation

bun add @sylphx/management
# or
npm install @sylphx/management
# or
pnpm add @sylphx/management

Quick Start

import { createClient, projects, deployments, envVars } from '@sylphx/management'

const client = createClient({
  token: process.env.SYLPHX_TOKEN!,
  // baseUrl defaults to 'https://api.sylphx.com'
})

// List projects (ids are TypeIDs — `proj_xxx`)
const list = await projects.list(client)

// Trigger a deployment
await deployments.trigger(client, 'proj_abc', 'production')

// List env vars for a project + environment
const vars = await envVars.list(client, 'proj_abc', 'production')

Workspace subtree cleanup is exposed as a separate fail-closed operation:

import { createClient, workspaces } from '@sylphx/management'

const client = createClient({ token: process.env.SYLPHX_TOKEN! })

await workspaces.reclaimSubpath(client, 'proj_abc', 'wksp_abc', {
  subPath: 'workspaces/session-a',
  reason: 'retention-expired',
})

Use workspaces.reclaim for whole-workspace archive/delete semantics only. workspaces.reclaimSubpath calls /subpath-reclaims, so older Platform versions fail closed with 404 instead of ignoring subPath.

Tree-shakable subpath imports

Bundlers that support subpath exports can import a single capability namespace for better tree-shaking:

import { createClient } from '@sylphx/management'
import * as projects from '@sylphx/management/projects'

const client = createClient({ token: process.env.SYLPHX_TOKEN! })
await projects.list(client)

Project preview capacity

Project updates are contract-first through projects.update. The previewMaxActive field is the project-level active PR preview override:

import { createClient, projects } from '@sylphx/management'

const client = createClient({ token: process.env.SYLPHX_TOKEN! })

await projects.update(client, 'proj_abc', { previewMaxActive: 10 })
await projects.update(client, 'proj_abc', { previewMaxActive: null }) // follow org plan

The field is intentionally scoped to the project, not an environment variable or service setting. It tunes preview admission for a project while the platform continues to own runner scheduling, queueing, and placement internals.

Capabilities

Every module exports free functions that take client as the first argument. The root entry point exports 70 capability namespaces; key ones:

| Namespace | Representative functions | | -------------------- | ------------------------------------------------------------------------------------------ | | users | whoami | | auth, authSettings | getOAuthProviders, updateOAuthProviders, getAuthSettings, updateAuthSettings, getAuthStats | | projects | list, create, delete | | agentResources | get | | deployments | status, trigger, history, rollback | | environments | list, resolveId, logs, create, update, delete, promote | | envVars | list, resolve, set, setMany, delete | | domains | list, create, addHostname, removeHostname, checkHostname, enableEmail, checkEmail, disableEmail | | databases | list, create, get, delete, branch | | services | list, get, deploy, delete | | volumes | list, create, delete | | storage | list, create, delete | | secrets | list, get, create, update, rollback, delete | | remoteConfig | list, get, set, delete | | tasks | list, create, get, update, delete | | resourceBindings | list, create, delete | | organizations | current, listMembers, inviteMember, removeMember | | sandboxes | create, list, get, terminate | | logs | stream (returns { url, token } for SSE) | | email | listLogs, getSettings, updateSettings (admin only — send lives in @sylphx/sdk) | | notifications | listInbox (admin only — send lives in @sylphx/sdk) | | billing | account / plan / invoice endpoints | | saml, oidc | SSO configuration admin | | webhooks | outbound webhook endpoint CRUD | | analytics | admin queries (runtime analytics.track lives in @sylphx/sdk) | | flags | flag admin CRUD (runtime flags.evaluate lives in @sylphx/sdk) | | experiments | A/B test admin CRUD | | ai | model / completion admin | | backups | managed-data backup + restore | | certs | TLS cert inspection | | consent, privacy | GDPR / CCPA admin |

envVars.resolve(client, projectId, envType, { serviceId? }) is the service-token-protected runtime resolver used by the CLI for local smoke and agent commands. It returns the decrypted customer-authored env values for one environment, optionally narrowed to one environment service. The masked envVars.list call remains the default read surface for UI and inventory. | engagement, newsletter, referrals | marketing admin | | runners | self-hosted runner admin | | sessionReplay | session-replay admin (runtime capture lives in @sylphx/sdk/web-analytics) | | monitoring | metric / alert admin | | realtime | channel admin (runtime pub/sub lives in @sylphx/sdk) | | search | index admin (runtime queries live in @sylphx/sdk) | | serviceTokens | service-token issuance + revocation |

Full, IDE-autocompleted surface is available on the re-exported namespaces from the root @sylphx/management entry point.

Serverless function lifecycle is intentionally absent from the Management SDK until the Management API owns /projects/:projectId/functions/*. Runtime function execution remains on @sylphx/sdk.

Plane discipline (ADR-083). Runtime BaaS verbs — kv.*, email.send, notifications.send, MFA challenge.*, flags.evaluate, analytics.track — are not part of @sylphx/management. Deployed applications (both server-side and browser-side) use @sylphx/sdk with its peer-dep-gated entry points (@sylphx/sdk, @sylphx/sdk/react, @sylphx/sdk/server, @sylphx/sdk/nextjs, @sylphx/sdk/web-analytics, @sylphx/sdk/health).

Error Handling

Every non-2xx response throws a single error type. Consumers discriminate on status or match on body shape.

import { ApiError } from '@sylphx/management'
import * as projects from '@sylphx/management/projects'

try {
  await projects.delete(client, 'non-existent')
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`API Error ${err.status}: ${err.message}`)
  }
}

Architecture

• Contract-first (ADR-084). Every type in this SDK — Project, Deployment, EnvVar, request / response envelopes — is imported from @sylphx/contract. Hand-written type shims are a bug. Adding a new capability starts with a contract entry, not this package.
• Promise-first, Effect-free public surface. The server uses Effect-TS internally (ADR-058), but no Effect types leak through the published .d.ts — consumers see plain Promise<T>.
• Immutable value type Client. Cheap to construct, safe to share across parallel calls. No hidden globals, no singletons.
• ESM-only, tree-shakable. "type": "module", sideEffects: false, per-namespace subpath exports.
• See ADR-077 (Trio Completeness) for the design rationale, ADR-083 (Two-Plane SDK Architecture) for the management / BaaS split, and ADR-084 (Effect Schema Contract) for the contract SSOT. (ADRs live in the Sylphx-internal architecture records.)

Agent integration

The sylphx CLI (built on top of this SDK) is the first-class agent surface for Claude Code / Cursor / ChatGPT Apps. Sylphx does not ship a standalone stdio MCP binary; if you want a bespoke MCP for your own workflows, compose one directly on top of @sylphx/management — every method is a pure Promise<T> and fully typed from @sylphx/contract.

Related packages

• @sylphx/contract — Effect Schema SSOT this SDK derives its types from (peer).
• @sylphx/sdk — runtime BaaS SDK for deployed apps (different plane).
• @sylphx/cli — interactive CLI built on this SDK.

License

MIT — see LICENSE.