SDK quickstart

Use @sprint-x/sdk from a Node runtime to select a project, send the first event and artifact, and read back status and brief.

This guide is for runtimes that already need direct Node access to SprintX instead of shelling out to the CLI.

The default path is still CLI-first. Use the SDK when you already control a Node runtime and want the same project selection, event, artifact, status, and brief flow in code.

Install

npm install @sprint-x/sdk

1. Start with an access token

The easiest programmable path today is to provide an access token directly.

export SX_ACCESS_TOKEN="<access-token>"
export SX_API_URL="https://www.sprintx.co.kr"

If you need browser-based approval inside Node, the SDK also exports runCliAuthFlow. The public docs still treat the CLI as the default first-connection route because it is the most stable path.

2. Minimal Node example

import { SprintXClient } from "@sprint-x/sdk"

const client = new SprintXClient({
  baseUrl: process.env.SX_API_URL ?? "https://www.sprintx.co.kr",
  accessToken: process.env.SX_ACCESS_TOKEN ?? null,
})

const { projects } = await client.listProjects()
const projectId = process.env.SX_PROJECT_ID ?? projects[0]?.id

if (!projectId) {
  throw new Error("No accessible SprintX project found.")
}

await client.projectUse({ projectId })

const event = await client.eventsIngest({
  projectId,
  eventType: "runtime.started",
  idempotencyKey: "sdk-quickstart-event-1",
  summary: "SDK handoff started",
  metadata: { source: "sdk-quickstart" },
})

const artifact = await client.artifactsUpload({
  projectId,
  title: "sdk-log",
  referenceUri: "https://example.com/logs/1",
  contentType: "text/plain",
  idempotencyKey: "sdk-quickstart-artifact-1",
  summary: "First SDK artifact",
  metadata: { kind: "log" },
})

const status = await client.getStatus({ projectId })
const brief = await client.getBrief({ projectId })

console.log({
  eventStatus: event.status,
  artifactStatus: artifact.status,
  project: status.project.name,
  openTasks: brief.openTaskCount,
  activeRuns: brief.activeRunCount,
})

3. What success looks like

client.projectUse() succeeds and returns projectId plus a receiptId
client.eventsIngest() returns status: "accepted"
client.artifactsUpload() returns status: "accepted"
client.getStatus() returns the bounded project summary
client.getBrief() returns the next summary and recent tasks

That is the SDK equivalent of the CLI connection check.

4. Choose CLI vs SDK

Choose this	When
CLI	You want the quickest OpenClaw connection today, browser-based approval, and core command usage
SDK	You already own a Node runtime and want direct programmable control without shelling out

Current scope

the public auth flow still starts with browser-based sx auth
current flow still starts with project use -> event -> artifact
status and brief are the quickest way to check the result after the first flow
broader API platform packaging and device-flow fallback are still follow-up work