🔑 Starchild Auth SDK

Integrate Starchild OAuth login into any web application — React, Vue, or plain HTML. The SDK handles the full OAuth popup flow, token management, automatic refresh, and session restoration.

When to Use

Adding Starchild login to a web project
Implementing OAuth authentication with iamstarchild.com
Building a third-party app that needs Starchild user identity
Replacing a custom auth flow with Starchild SSO

Step 1 — Register Your App & Get Client ID

Go to iamstarchild.com → click the More menu (left sidebar) → OAuth Apps
- Direct link:
```
https://iamstarchild.com/oauth-apps
```
Click Create App
Fill in:
- App Name (required): your application name
- Allowed Origin (required): the origin of your website (e.g.
```
https://your-app.com
```
  ). For local development, use
```
http://localhost:3000
```
  . Must be a valid origin — no paths, query params, or hash allowed. Non-localhost origins must use
```
https://
```
  .
- Description (optional): only visible to you
After creation, a dialog will show your Client ID — copy it immediately

⚠️ Keep your Client ID safe. Never commit it directly in source code — use environment variables. Each user can create up to 10 OAuth apps.

Step 2 — Install the SDK

npm / yarn / pnpm

bash

# npm
npm install starchild-auth-sdk

# yarn
yarn add starchild-auth-sdk

# pnpm
pnpm add starchild-auth-sdk

CDN (for plain HTML)

The SDK provides two builds. For plain

<script>

tags, use the UMD build:

html

<!-- unpkg (recommended) -->
<script src="https://unpkg.com/starchild-auth-sdk/dist/starchild-auth.umd.cjs"></script>

<!-- npmmirror (alternative, for China mainland) -->
<script src="https://registry.npmmirror.com/starchild-auth-sdk/latest/files/dist/starchild-auth.umd.cjs"></script>

⚠️ Do NOT use
starchild-auth.js
with a plain
<script>
tag — that file is an ES Module and will fail silently. Use
starchild-auth.umd.cjs
for
<script>
tags, or use
<script type="module">
with the ESM build (see examples below).

💡 CDN 加载失败？ 如果两个 CDN 都无法访问（如在受限网络环境中），可以用
curl
下载到本地后通过相对路径引用：
bash
curl -sL "https://unpkg.com/starchild-auth-sdk/dist/starchild-auth.umd.cjs" -o starchild-auth.umd.cjs
然后
<script src="starchild-auth.umd.cjs"></script>

When loaded via UMD CDN, the class is available directly as

window.StarchildAuth

(it's the constructor itself, not a namespace object).

Step 3 — Initialize the SDK

typescript

import { StarchildAuth } from 'starchild-auth-sdk'

const auth = new StarchildAuth({
  clientId: 'your-client-id',

  // Called after successful login (popup or auto-login session restore)
  onLogin: ({ accessToken, refreshToken, expiresIn, userInfo }) => {
    console.log('Logged in:', userInfo.agentName)
    console.log('Avatar:', userInfo.agentAvatar)
  },

  // Called after logout
  onLogout: () => {
    console.log('Logged out')
  },

  // Token auto-refreshes every 12 minutes
  onTokenRefresh: (newAccessToken) => {
    console.log('Token refreshed')
  },

  // Called when refresh fails (session expired)
  onTokenRefreshFailed: () => {
    console.log('Session expired, please log in again')
  },
})

Auto-login: By default (
autoLogin: true
), the SDK checks localStorage for a stored refresh token on initialization and automatically restores the session. This means
onLogin
may fire immediately after construction without calling
login()
.

Step 4 — Login / Logout / Status

typescript

// Trigger login (opens Starchild OAuth popup)
const { accessToken, refreshToken, expiresIn, userInfo } = await auth.login()

// Logout (clears tokens, revokes refresh token via API)
await auth.logout()

// Check login status
const isLoggedIn: boolean = auth.isLoggedIn()

// Get current access token (null if not logged in)
const token: string | null = auth.getToken()

// Get current user info (null if not logged in)
const user: UserInfo | null = auth.getUserInfo()
// user = { userInfoId: string, agentName: string, agentAvatar: string }

// Manually trigger token refresh (normally automatic every 12 min)
const newToken: string = await auth.refreshToken()

// Destroy instance (remove listeners, clear timers, clear tokens)
auth.destroy()

Framework Examples

React

tsx

// src/hooks/useStarchildAuth.ts
import { useState, useEffect, useRef, useCallback } from 'react'
import { StarchildAuth } from 'starchild-auth-sdk'
import type { UserInfo, LoginResult } from 'starchild-auth-sdk'

export function useStarchildAuth() {
  const [user, setUser] = useState<UserInfo | null>(null)
  const [token, setToken] = useState<string | null>(null)
  const [loading, setLoading] = useState(true)
  const authRef = useRef<StarchildAuth | null>(null)

  useEffect(() => {
    const auth = new StarchildAuth({
      clientId: import.meta.env.VITE_STARCHILD_CLIENT_ID,
      onLogin: ({ accessToken, userInfo }: LoginResult) => {
        setUser(userInfo)
        setToken(accessToken)
        setLoading(false)
      },
      onLogout: () => {
        setUser(null)
        setToken(null)
      },
      onTokenRefresh: (newToken: string) => {
        setToken(newToken)
      },
      onTokenRefreshFailed: () => {
        setUser(null)
        setToken(null)
      },
      // autoLogin: true (default) — will restore session from localStorage
    })

    authRef.current = auth

    // If auto-login doesn't fire onLogin (no stored session), stop loading
    const timeout = setTimeout(() => setLoading(false), 1500)

    return () => {
      clearTimeout(timeout)
      auth.destroy()
    }
  }, [])

  const login = useCallback(async () => {
    if (!authRef.current) return
    return await authRef.current.login()
  }, [])

  const logout = useCallback(async () => {
    if (!authRef.current) return
    await authRef.current.logout()
  }, [])

  return { user, token, loading, login, logout, isLoggedIn: !!user }
}

tsx

// src/App.tsx
import { useStarchildAuth } from './hooks/useStarchildAuth'

function App() {
  const { user, loading, login, logout, isLoggedIn } = useStarchildAuth()

  if (loading) return <div>Loading...</div>

  return (
    <div>
      {isLoggedIn ? (
        <div>
          <p>Welcome, {user?.agentName}</p>
          <img src={user?.agentAvatar} alt="avatar" width={40} />
          <button onClick={logout}>Logout</button>
        </div>
      ) : (
        <button onClick={login}>Login with Starchild</button>
      )}
    </div>
  )
}

export default App

Vue 3 (Composition API)

typescript

// src/composables/useStarchildAuth.ts
import { ref, onMounted, onUnmounted } from 'vue'
import { StarchildAuth } from 'starchild-auth-sdk'
import type { UserInfo, LoginResult } from 'starchild-auth-sdk'

export function useStarchildAuth() {
  const user = ref<UserInfo | null>(null)
  const token = ref<string | null>(null)
  const loading = ref(true)
  let authInstance: StarchildAuth | null = null

  onMounted(() => {
    authInstance = new StarchildAuth({
      clientId: import.meta.env.VITE_STARCHILD_CLIENT_ID,
      onLogin: ({ accessToken, userInfo }: LoginResult) => {
        user.value = userInfo
        token.value = accessToken
        loading.value = false
      },
      onLogout: () => {
        user.value = null
        token.value = null
      },
      onTokenRefresh: (newToken: string) => {
        token.value = newToken
      },
      onTokenRefreshFailed: () => {
        user.value = null
        token.value = null
      },
    })

    // If no stored session, stop loading after timeout
    setTimeout(() => { loading.value = false }, 1500)
  })

  onUnmounted(() => {
    authInstance?.destroy()
  })

  const login = async () => {
    if (!authInstance) return
    return await authInstance.login()
  }

  const logout = async () => {
    if (!authInstance) return
    await authInstance.logout()
  }

  const isLoggedIn = () => !!user.value

  return { user, token, loading, login, logout, isLoggedIn }
}

vue

<!-- src/App.vue -->
<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="user">
    <p>Welcome, {{ user.agentName }}</p>
    <img :src="user.agentAvatar" alt="avatar" width="40" />
    <button @click="logout">Logout</button>
  </div>
  <div v-else>
    <button @click="login">Login with Starchild</button>
  </div>
</template>

<script setup lang="ts">
import { useStarchildAuth } from './composables/useStarchildAuth'

const { user, loading, login, logout } = useStarchildAuth()
</script>

Plain HTML — UMD (recommended for

<script>

tags)

💡 如果 CDN 加载失败，参考上方 Step 2 中的 CDN 备选源和本地下载方案。

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Starchild Auth Demo</title>
  <!-- UMD build: works with plain <script> tags -->
  <!-- If CDN is blocked, download the file locally and use a relative path instead -->
  <script src="https://unpkg.com/starchild-auth-sdk/dist/starchild-auth.umd.cjs"></script>
</head>
<body>
  <div id="app">
    <div id="logged-out">
      <button id="login-btn">Login with Starchild</button>
    </div>
    <div id="logged-in" style="display: none">
      <p>Welcome, <span id="user-name"></span></p>
      <img id="user-avatar" width="40" />
      <button id="logout-btn">Logout</button>
    </div>
  </div>

  <script>
    // UMD exposes window.StarchildAuth as the constructor directly
    if (typeof window.StarchildAuth !== 'function') {
      document.getElementById('logged-out').innerHTML =
        '<p style="color:red">SDK failed to load. Check if the CDN script loaded correctly.</p>'
      throw new Error('StarchildAuth SDK not loaded')
    }

    var auth = new StarchildAuth({
      clientId: 'your-client-id',
      onLogin: function (result) {
        showLoggedIn(result.userInfo)
      },
      onLogout: function () {
        showLoggedOut()
      },
      onTokenRefresh: function (newToken) {
        console.log('Token refreshed')
      },
      onTokenRefreshFailed: function () {
        showLoggedOut()
      },
      // autoLogin: true (default) — restores session automatically
    })

    document.getElementById('login-btn').addEventListener('click', async function () {
      try {
        await auth.login()
      } catch (err) {
        console.error('Login failed:', err.message)
      }
    })

    document.getElementById('logout-btn').addEventListener('click', async function () {
      await auth.logout()
    })

    function showLoggedIn(user) {
      document.getElementById('logged-out').style.display = 'none'
      document.getElementById('logged-in').style.display = 'block'
      document.getElementById('user-name').textContent = user.agentName
      if (user.agentAvatar) {
        document.getElementById('user-avatar').src = user.agentAvatar
      }
    }

    function showLoggedOut() {
      document.getElementById('logged-out').style.display = 'block'
      document.getElementById('logged-in').style.display = 'none'
    }
  </script>
</body>
</html>

Plain HTML — ES Module (alternative)

If you prefer ES Module syntax, use

<script type="module">

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Starchild Auth Demo (ESM)</title>
</head>
<body>
  <button id="login-btn">Login with Starchild</button>
  <div id="logged-in" style="display: none">
    <p>Welcome, <span id="user-name"></span></p>
    <button id="logout-btn">Logout</button>
  </div>

  <script type="module">
    import { StarchildAuth } from 'https://unpkg.com/starchild-auth-sdk/dist/starchild-auth.js'

    const auth = new StarchildAuth({
      clientId: 'your-client-id',
      onLogin: ({ userInfo }) => {
        document.getElementById('login-btn').style.display = 'none'
        document.getElementById('logged-in').style.display = 'block'
        document.getElementById('user-name').textContent = userInfo.agentName
      },
      onLogout: () => {
        document.getElementById('login-btn').style.display = 'block'
        document.getElementById('logged-in').style.display = 'none'
      },
    })

    document.getElementById('login-btn').addEventListener('click', () => auth.login())
    document.getElementById('logout-btn').addEventListener('click', () => auth.logout())
  </script>
</body>
</html>

API Reference

StarchildAuthOptions

(Constructor Options)

Option	Type	Default	Description
`clientId`	`string`	(required)	OAuth Client ID from iamstarchild.com
`onLogin`	`(result: LoginResult) => void`	—	Called after successful login (popup or auto-login)
`onLogout`	`() => void`	—	Called after logout
`onTokenRefresh`	`(accessToken: string) => void`	—	Called when token is auto-refreshed
`onTokenRefreshFailed`	`() => void`	—	Called when token refresh fails (session expired)
`autoLogin`	`boolean`	`true`	Attempt to restore session from localStorage on init
`origin`	`string`	`'https://iamstarchild.com'`	Starchild origin URL (for popup login page)
`apiBase`	`string`	`'https://go-api.iamstarchild.com/v1'`	Go API base URL (for token refresh & logout)
`chatApiBase`	`string`	`'https://ai-api.iamstarchild.com'`	AI API base URL (for `/v1/oauth/userinfo` )
`popupWidth`	`number`	`480`	Login popup width in pixels
`popupHeight`	`number`	`640`	Login popup height in pixels
`refreshInterval`	`number`	`720000`	Auto-refresh interval in ms (default: 12 minutes)

Methods

Method	Returns	Description
`login()`	`Promise<LoginResult>`	Opens OAuth popup and returns credentials on success
`logout()`	`Promise<void>`	Clears session, revokes refresh token via API
`isLoggedIn()`	`boolean`	Whether user is currently authenticated
`getToken()`	`string \| null`	Current access token, or `null`
`getUserInfo()`	`UserInfo \| null`	Current user info, or `null`
`refreshToken()`	`Promise<string>`	Manually trigger token refresh, returns new access token
`destroy()`	`void`	Remove listeners, clear timers, clear tokens. Instance cannot be reused.

LoginResult

Type

typescript

interface LoginResult {
  accessToken: string
  refreshToken: string
  expiresIn: number
  userInfo: UserInfo
}

UserInfo

Type

typescript

interface UserInfo {
  /** Unique user ID */
  userInfoId: string
  /** Display name (agent name) */
  agentName: string
  /** Avatar URL */
  agentAvatar: string
}

Token Lifecycle

Access tokens are short-lived and auto-refresh every 12 minutes (configurable via
```
refreshInterval
```
)
The SDK stores the refresh token in
```
localStorage
```
(key:
```
starchild_rt_{clientId}
```
)
On page reload, if
```
autoLogin
```
is
```
true
```
(default), the SDK uses the stored refresh token to restore the session automatically —
```
onLogin
```
fires again with fresh tokens
When the page returns from background (visibility change), the SDK automatically refreshes the token
If refresh fails (e.g. user revoked access, token expired),
```
onTokenRefreshFailed
```
fires and the stored refresh token is cleared

Sending Authenticated API Requests

Once logged in, include the access token in your API requests:

typescript

const response = await fetch('https://api.your-app.com/data', {
  headers: {
    Authorization: `Bearer ${auth.getToken()}`,
  },
})

For React / Vue, use the

token

from the hook/composable:

typescript

// React example
const { token } = useStarchildAuth()

const fetchData = async () => {
  const res = await fetch('/api/data', {
    headers: { Authorization: `Bearer ${token}` },
  })
  return res.json()
}

Important Notes

CDN Build Selection

Build	File	Usage
UMD	`starchild-auth.umd.cjs`	`<script>` tags — exposes `window.StarchildAuth` (constructor)
ESM	`starchild-auth.js`	`<script type="module">` or bundlers (Vite, webpack, etc.)

Common mistake: Using
starchild-auth.js
with a plain
<script>
tag. This will fail silently because the ESM file uses
export
syntax which is invalid in non-module scripts. Always use the
.umd.cjs
build for plain
<script>
tags.

Session Persistence

The SDK stores the refresh token in

localStorage

under the key

starchild_rt_{clientId}

. This enables:

Auto-login on page reload — no need to call
```
login()
```
again
Cross-tab session sharing — all tabs with the same
```
clientId
```
share the session

To fully clear a user's session, call

auth.logout()

which removes the stored token and revokes it server-side.

Troubleshooting

Issue	Solution
Popup blocked	Ensure `login()` is called from a user gesture (click handler). Browsers block popups not triggered by user interaction.
Origin mismatch	Verify the Allowed Origin in OAuth Apps settings matches your site's origin exactly (e.g. `https://your-app.com` ). No trailing slash, no path.
`StarchildAuth is not defined` (CDN)	You're using the ESM build ( `starchild-auth.js` ) with a plain `<script>` tag. Switch to the UMD build ( `starchild-auth.umd.cjs` ), or use `<script type="module">` with `import` .
Token refresh failing	Check that the app hasn't been revoked in user's Starchild settings. Also check browser console for network errors.
`onLogin` fires on page load	This is expected behavior — `autoLogin: true` (default) restores the session from localStorage. Set `autoLogin: false` to disable.
CDN blocked	unpkg.com may be slow/blocked in some environments. Use `npmmirror` as alternative ( `https://registry.npmmirror.com/starchild-auth-sdk/latest/files/dist/starchild-auth.umd.cjs` ), or download the SDK file locally and serve it from your own domain.

starchild-auth

NPX Install

Tags

SKILL.md Content

🔑 Starchild Auth SDK

When to Use

Step 1 — Register Your App & Get Client ID

Step 2 — Install the SDK

npm / yarn / pnpm

CDN (for plain HTML)

Step 3 — Initialize the SDK

Step 4 — Login / Logout / Status

Framework Examples

React

Vue 3 (Composition API)

Plain HTML — UMD (recommended for
`<script>`
tags)

Plain HTML — ES Module (alternative)

API Reference

`StarchildAuthOptions`
(Constructor Options)

Methods

`LoginResult`
Type

`UserInfo`
Type

Token Lifecycle

Sending Authenticated API Requests

Important Notes

CDN Build Selection

Session Persistence

Troubleshooting