Starchild Auth SDK API 레퍼런스

import { StarchildAuth, StarchildAuthError } from 'starchild-auth-sdk'
const auth = new StarchildAuth({
  clientId: 'YOUR-CLIENT-ID',
  scope: 'profile chat',
  autoLogin: true,
})

login() · logout() · isLoggedIn() · getToken() · getRefreshToken() · getUserInfo() · fetchUserInfo() · isGuest() · getBindAccountUrl() · bindAccount() · refreshToken() · destroy().

login()은 실제 브라우저의 사용자 제스처에서 호출해야 합니다. getRefreshToken() 결과는 비밀번호처럼 처리하세요. 사용자 정보 타입은 다음과 같습니다.

type UserInfo = {
  userInfoId: string
  agentName: string
  agentAvatar: string
  isGuest: boolean
}

Access token은 15분, Refresh token은 7일 동안 유효합니다. 기본 갱신은 12분마다와 페이지가 다시 표시될 때 수행됩니다.

Flat 메서드도 계속 사용할 수 있습니다. 그룹별 별칭은 auth.profile, auth.chat, auth.threads, auth.messages, auth.containers, auth.skills, auth.media, auth.shares, auth.feedback, auth.jobs, auth.wallet, auth.credit입니다.

auth.chat.send('hello')는 auth.sendMessage('hello')와 같습니다. 스레드, 메시지, 컨테이너, 스킬, 미디어, 공유, 피드백, 예약 작업, 지갑과 Credits 기능을 그룹으로 제공합니다.

sendMessage()와 reconnectStream()은 원시 Response를 반환하므로 .ok를 직접 확인해야 합니다. SSE 이벤트는 agent_start, text_delta, tool_use, tool_output, agent_end, error, agent:interrupted입니다. 스트림이 끊기면 reconnectStream(sessionKey), 실행 취소에는 cancelRun(threadId)를 사용합니다.

Clawd 요청에는 fly-force-instance-id가 필요합니다. SDK는 자동으로 주입하지만 curl에서는 직접 지정해야 합니다. OAuth token의 컨테이너 삭제는 항상 403입니다.

credit:read는 잔액과 기록을, credit:write는 충전, 기프트 카드, Points 교환을 제공합니다. credit:write에는 credit:read가 포함됩니다. 재시도 가능한 쓰기에는 문서에 따라 Idempotency-Key를 사용하세요.

JSON helper는 2xx가 아니면 내보낸 StarchildAuthError를 throw합니다.

try {
  await auth.credit.getBalance()
} catch (error) {
  if (error instanceof StarchildAuthError && error.insufficientScope) {
    await auth.login()
  }
}

오류에는 status, code, detail, path, insufficientScope, response가 있습니다. Insufficient scope가 포함된 403은 권한 부족이고 401은 token 만료 또는 무효입니다.

• Auth/token: https://go-api.iamstarchild.com/v1
• Userinfo/Agent REST: https://ai-api.iamstarchild.com
• Clawd: https://preview.iamstarchild.com
• Credits: https://credit.iamstarchild.com

팝업 로그인은 브라우저에서만 사용할 수 있습니다. 서버에서는 브라우저에서 받은 token을 주입하고 /v1/oauth/userinfo로 항상 검증하세요. Starchild 웹 앱은 http://localhost:6066을 사용할 수 있지만, 서드파티 앱은 http://localhost:3333처럼 자신의 Origin을 등록해야 합니다. 6066을 서드파티 앱으로 등록하지 마세요.

브라우저는 CORS를 적용하지만 Node/curl은 적용하지 않습니다. 새 Origin에서 CORS 오류가 계속되면 scheme, 포트, approved/active 상태를 확인하고 약 5분간 allowlist 갱신을 기다리세요.

• 필요한 Scope만 요청합니다.
• Refresh token을 기록하거나 외부로 보내지 않습니다.
• 모든 보호 요청을 서버에서 검증합니다.
• Guest의 결제와 되돌릴 수 없는 작업을 정책으로 제한합니다.
• insufficientScope와 401을 구분합니다.
• CSP를 사용하고 사용자 입력을 정제합니다.