✦Spectra SDK Docs

Agent-readable SDK index

이 문서는 에이전트가 Spectra SDK 사용법을 빠르게 파악하기 위한 진입점이다.

기본 Docs(/) 자체가 사람이 읽는 SDK 문서다. 이 docs/agents/* 영역은 사람용 문서의 대체본이 아니라,

에이전트가 소비 앱에 SDK를 붙일 때 필요한 계약·판단 규칙만 빠르게 읽기 위한 특수 문서다.

따라서 사람용 UX 설명보다 정확한 계약, 공개 패키지, 필요한 설정, 금지값, 현재 미검증 항목을 우선한다.

How agents should read these docs

1. Start here at docs/agents/README.md.

2. Identify the SDK packages required by the consuming app.

3. Open only the matching SDK-specific agent specs in docs/agents/*.

4. Use the package tree below to understand dependency direction before writing code.

5. Create and verify the Auth SDK object first.

6. Inject the same Auth object into Notification, Chat, Storage, or future SDK clients.

7. Use the human Docs(/) only for UX wording and short examples, not as the source of secret handling or integration policy.

8. If a browser/mobile SDK implementation requires an internal URL, provider secret, undocumented exchange step, or Secret Key without an explicit consuming-project architecture decision, stop and escalate to Platform CS.

Agent pages should stay agent-only:

Package tree

Spectra JS SDK packages
├─ @spectra-platform/auth-sdk@0.1.10
│  ├─ login: signInWithGoogle, signInWithApple, relaySpectraAuthCallback
│  ├─ session: getSession, getAccessToken, refresh, logout
│  ├─ error: SpectraAuthError, isSpectraAuthError, retryAfterSeconds, requestId
│  └─ service token provider for email, notification, storage, chat, call
├─ @spectra-platform/notification-sdk@0.1.0
│  ├─ email: sendEmailCode, verifyEmailCode
│  └─ push: registerForPush
├─ @spectra-platform/chat-sdk@0.2.0 (unpublished; registry 0.1.3)
│  ├─ rooms: listRooms, createDirectRoom, createGroupRoom, leaveRoom, getRoomMembership
│  ├─ messages: listMessages, sendMessage, markRead
│  └─ realtime: on, connect, setTyping, disconnect
└─ @spectra-platform/storage-sdk@0.1.3
   └─ files: listFiles, uploadFile, uploadImage, getDownloadUrl, downloadBlob, deleteFile

Packages

SDK · Package · Version · Agent doc

Auth JS · @spectra-platform/auth-sdk · 0.1.10, published / install-verified · auth-sdk-js

Notification JS · @spectra-platform/notification-sdk · 0.1.0 · notification-sdk-js

Chat JS · @spectra-platform/chat-sdk · registry 0.1.3; source 0.2.0 unpublished / undeployed · chat-sdk-js

Storage JS · @spectra-platform/storage-sdk · 0.1.3 · storage-sdk-js

Common installation

@spectra-platform:registry=https://npm.pkg.github.com

Private GitHub Packages access may require a read token in the consuming environment.

source means repository package metadata. Before requiring that exact package version from a consuming app, confirm that

GitHub Packages publish for the same version succeeded.

Common client boundary

Allowed in browser/mobile SDK configuration:

Never put these in browser/mobile SDK configuration:

Agent execution contract

When an agent integrates Spectra JS SDKs into a consuming app, use this order:

1. Read this index.

2. Read the SDK-specific agent doc for each package in scope.

3. Read the matching human SDK doc only for examples and user-facing flow wording.

4. Create the Auth SDK object first.

5. Inject the Auth object into Notification, Chat, and Storage clients.

6. Verify session/token behavior before testing downstream SDKs.

7. Record any mismatch between docs and runtime as a Platform CS question instead of hiding it with app-local workaround code.

Required public app configuration:

Field · Owner · Public in app · Notes

projectId · Spectra Console project · yes · Required by all SDK clients

publicClientId · Auth app client compatibility field · yes · Current Auth JS SDK field; not a primary user-managed product key

environment · Spectra environment · yes · Use documented values such as test or live

redirectUri · Consuming app · yes · Must match the app callback route

baseUrl · Spectra public API endpoint · yes, optional · Override only when docs or Platform CS says so

auth · Auth SDK object · yes · Pass object reference, not a raw long-lived secret

Auth/token boundary:

Local browser login QA

For a consuming app such as modo-camp, local SDK login can use the public Auth server. Do not switch to a local Auth server

unless the task explicitly asks for producer-local testing.

Checklist:

1. Open the app on the exact local origin that will be used during QA.

2. Set redirectUri to the same origin plus the app callback path.

- Example: http://127.0.0.1:5174/auth/callback

- Example: http://localhost:5174/auth/callback

3. Remember that localhost and 127.0.0.1 are different browser origins.

4. Confirm CORS for the exact origin. Auth 63cf46f is deployed and automatically includes eligible active Test callback origins; existing static/loopback grants remain. Registered HTTPS and unregistered LAN rejection passed public checks; actual LAN registration remains pending. Follow the mobile Auth guide for eligibility, Console steps and release status.

5. Confirm the Console App/Web Callback stores the exact callback URL.

6. Implement the callback route with relaySpectraAuthCallback().

7. Start with Google if Apple credentials are not issued for the consuming project.

8. Click signInWithGoogle() and verify the popup reaches Google account chooser before asking the user for credentials.

9. After callback, verify getSession() and getAccessToken().

The earlier 2026-08-02 public-test record includes these SDK origins: https://console.spectra.kr, http://localhost:5173,

http://localhost:5174, http://127.0.0.1:5173, and http://127.0.0.1:5174.

Observed evidence on 2026-08-02:

Unsupported, planned, or separately verified

Keep these out of completion criteria unless the task explicitly asks for separate provider/server E2E:

Internal words to avoid in public examples

Do not expose these as first-class public SDK concepts unless a lower-level reference page explicitly needs them:

Verification boundary

Package publication and SDK unit tests do not automatically mean each server producer or provider integration is production-verified. Docs must keep these separate:

Escalate to Platform CS when

Platform CS questions should include: