@sylphx/sdk — TypeScript Platform SDK

First-class external TypeScript client for Sylphx Platform.

| Language | App (runtime) | Management (operators) | | --- | --- | --- | | TypeScript | @sylphx/sdk → Client | @sylphx/sdk → ManagementClient | | Rust | sylphx-sdk | sylphx-sdk-management |

Wire authority: Protobuf under api/proto/sylphx/platform/v1/ (sole).
Not Effect Schema / @sylphx/contract.

SDK namespaces and command groups are generated or observed projections. They do not create Platform primitives, semantic families, lifecycle authorities, or compatibility promises. The target ontology is the four primitives Resource, Operation, Event, and Artifact, with the seven semantic capability families declared by the Platform Constitution.

Install

npm install @sylphx/sdk
# or: bun add @sylphx/sdk

App client (runtime / BaaS)

import { Client } from '@sylphx/sdk'

const client = Client.create(process.env.SYLPHX_SECRET_KEY!, 'my-tenant')
await client.kvSet('user:1', { name: 'Ada' }, 60)
const value = await client.kvGet('user:1')
await client.kvDelete('user:1')
// Typed beyond foundation (Protobuf KvIncr):
await client.kvIncr('visits', 1)
await client.kvExists('visits')
await client.kvExpire('visits', 3600)

Management client

import { ManagementClient } from '@sylphx/sdk'

const mgmt = ManagementClient.create(process.env.SYLPHX_TOKEN!)
await mgmt.health()
const me = await mgmt.whoami()
const projects = await mgmt.listProjects()
const project = await mgmt.getProject('prj_…')
// Typed beyond foundation (Protobuf ListEnvironments):
const envs = await mgmt.listEnvironments('prj_…')
const env = await mgmt.getEnvironment('prj_…', 'env_…')
const deps = await mgmt.listDeployments('prj_…')
// Escape hatch for any Management REST route:
await mgmt.api('GET', '/projects')

Agent Computer contract projection

Agent Computer payloads, HTTP/SSE bindings, validators, and immutable contract identity are generated from the management-rooted Protobuf descriptor graph. These exports are the typed wire boundary; they do not imply that a live Agent Computer runtime is deployed.

The contract is lifecycle-based: a caller must authenticate a ComputerLease, wait for a provider-backed READY result, and use the returned evidence for observe/act/postcondition decisions. Unsupported or not-yet-proven profiles remain typed refusals or non-ready states; the SDK never treats a stale or synthetic readiness value as a live computer.

import {
  AGENT_COMPUTER_BINDINGS,
  AGENT_COMPUTER_CONTRACT_IDENTITY_SHA256,
  AGENT_COMPUTER_CONTRACT_REVISION,
  validateAgentComputerRequest,
  validateAgentComputerResponse,
} from '@sylphx/sdk'

const request = validateAgentComputerRequest('getComputerProfile', {
  profileId: 'profile_…',
})

Contract identity

import { API_TYPES_CONTRACT_PACKAGE, API_TYPES_CONTRACT_REVISION } from '@sylphx/sdk'
// sylphx.platform.v1 @ 0.5.0 — same generated identity as Rust sylphx-api-types

CLI

Operator CLI is the Rust binary sylphx (crate sylphx-cli). Install via either channel — same binary product:

npm install -g @sylphx/cli    # npm channel (native binary optionalDeps)
cargo install sylphx-cli      # crates.io channel

Install (commercial)

# TypeScript library
npm install @sylphx/sdk

# Rust libraries
# Cargo.toml: sylphx-sdk = "0.1", sylphx-sdk-management = "0.1"

# Operator CLI (Rust binary — npm or cargo)
npm install -g @sylphx/cli
# or: cargo install sylphx-cli

Batch Jobs (Workload Fabric)

The current observed SDK surface uses WorkClient → POST /v1/work/container. That namespace and path are projections, not target authority. The constitutional target is a typed BatchJob Work Resource whose create, cancellation, retry, repair, and terminal truth use the common Operation contract.

Legacy RunsClient.run, runDistributed, and compatibility-only worker/task re-exports are predecessor surfaces. They are not final target contracts and must be deleted rather than retained as throwing aliases.