메인 콘텐츠로 건너뛰기

SDK 빠른 시작

Node runtime에서 @sprint-x/sdk로 프로젝트 선택, 첫 event와 artifact 기록, status와 brief 확인까지 진행하는 가이드

이 문서는 CLI를 shell out 하지 않고 Node runtime 안에서 SprintX를 직접 호출하고 싶은 경우를 위한 가이드입니다.

현재 기본 경로는 여전히 CLI-first입니다. 다만 이미 Node runtime을 제어하고 있고 project use, event, artifact, status, brief를 코드에서 직접 다루고 싶다면 SDK가 더 맞습니다.

설치

npm install @sprint-x/sdk

1. access token부터 준비

오늘 가장 단순한 programmable path는 access token을 직접 주입하는 방식입니다.

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

브라우저 승인형 auth를 Node 안에서 처리하고 싶다면 SDK가 runCliAuthFlow도 export 합니다. 다만 지금은 공개 문서에서 CLI를 기본 첫 연결 경로로 두고 있으며, 그 이유는 안정성이 높기 때문입니다.

2. 최소 Node 예시

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("접근 가능한 SprintX 프로젝트를 찾지 못했습니다.")
}

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. 성공 신호

  • client.projectUse()가 성공하고 projectId, receiptId를 돌려줍니다
  • client.eventsIngest()가 status: "accepted"를 돌려줍니다
  • client.artifactsUpload()가 status: "accepted"를 돌려줍니다
  • client.getStatus()가 project 요약을 돌려줍니다
  • client.getBrief()가 다음 요약과 recent tasks를 돌려줍니다

즉, 이것이 SDK에서 보는 연결 확인입니다.

4. CLI와 SDK 중 무엇을 고를까

이 경로를 고르세요이런 경우
CLIOpenClaw를 가장 빠르게 연결하고 싶고, 브라우저 승인형 auth와 기본 명령 사용이 중요할 때
SDK이미 Node runtime을 갖고 있고 shelling out 없이 직접 SprintX 메서드를 호출하고 싶을 때

현재 범위

  • 현재 공개 auth 흐름은 여전히 브라우저 승인형 sx auth
  • 현재 흐름의 핵심은 project use -> event -> artifact
  • 첫 연결 뒤 상태를 다시 읽는 가장 빠른 경로는 status, brief
  • 넓은 API platform packaging과 device-flow fallback은 아직 follow-up work

다음 문서