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() 只返回内存副本，应像密码一样处理。userinfo 结构：

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

Access token 有效期 15 分钟，默认每 12 分钟和页面重新可见时刷新。Refresh token 有效期 7 天，保存在 starchild_rt_{clientId}。

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:read。涉及可重试写入时按文档使用 Idempotency-Key。

JSON helper 在非 2xx 时抛出导出的 StarchildAuthError：

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

错误包含 status、code、detail、path、insufficientScope 和 response。403 的 Insufficient scope 表示权限不足，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

Popup 登录只在浏览器可用。服务端先在浏览器获取 token，再用 autoLogin: false 注入 token，并始终调用 /v1/oauth/userinfo 验证。Starchild 主站本地端口可能是 http://localhost:6066，第三方应用应使用自己的端口如 http://localhost:3333 并注册该 origin，不要把 6066 注册为第三方应用。

浏览器会执行 CORS，Node/curl 不执行。若新 origin 仍失败，检查 scheme、端口、approved/active 状态，并等待约 5 分钟的 allowlist 刷新。

• 只申请需要的 Scope。
• 不记录或外传 Refresh token。
• 服务端验证每个受保护请求。
• 为 Guest 账号设置付款和不可逆操作规则。
• 分开处理 insufficientScope 和 401。
• 使用 CSP 并清理用户可控字段。