✦Spectra SDK Docs

Spectra JavaScript SDK

Spectra SDK 문서는 서버 저장소 이름보다 개발자가 하려는 일을 기준으로 읽는다.

기본 SDK UX는 SDK UX Contract v1을 따른다. 기본 문서와 첫 예시는

key별 권한 설정, 기능별 preset, deliveryBaseURL, service token audience, templateId 같은 내부/고급 개념을 요구하지 않는다.

현재 package나 서버가 아직 이 계약과 다르면 소비 앱 workaround가 아니라 SDK/서비스 정렬 작업으로 본다.

설치

GitHub Packages를 사용한다.

npm install @spectra-platform/auth-sdk
npm install @spectra-platform/notification-sdk
npm install @spectra-platform/chat-sdk
npm install @spectra-platform/storage-sdk

소비 프로젝트의 .npmrc에는 Spectra scope registry를 추가한다.

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

Private package 권한이 필요한 환경에서는 GitHub Packages read token이 필요하다.

현재 문서화된 JS SDK

SDK · Package · Version · 역할

Auth JS · @spectra-platform/auth-sdk · 0.1.10 발행·설치 검증 완료 · Google/Apple 로그인, callback relay, session/token, test LAN HTTP opt-in 및 preflight, popup 보강. Backend login verification은 기존 getAccessToken()으로 사용하며 신규 SDK 버전 불필요

Notification JS · @spectra-platform/notification-sdk · 0.1.0 · 이메일 코드 요청/검증, iOS/Android push device registration

Chat JS · @spectra-platform/chat-sdk · registry 0.1.3; source 0.2.0 unpublished · room/message/realtime, 신규 self-leave는 undeployed

Storage JS · @spectra-platform/storage-sdk · 0.1.3 · user-root file upload/list/download/delete, object upload input, safe fileInfo metadata

@spectra-platform/auth-sdk@0.1.10은 2026-09-05 GitHub Packages에 수동 발행됐고 새 캐시 설치까지

검증됐다. Private package 권한이 필요한 환경에서는 GitHub Packages read 권한이 필요하다.

이번 발행은 Actions workflow 성공을 뜻하지 않으며 자동 publish 권한 문제와 구분한다.

SDK API tree

모바일 로컬 HTTP 로그인은 승인된 test 전용 개발 경로를 설명한다.

새 development.allowInsecureHttp 옵션과 preflightSignIn()은 발행·설치 검증된 0.1.10에 포함된다.

배포된 Auth/Console은 활성 Test App Client에 저장한 웹 callback origin을 Auth SDK CORS에 자동 연결한다.

JWT 및 기존 HTTPS 허용·미등록 LAN 거절은 운영 검증됐으며 LAN 저장·등록 후 검증은 가이드의 릴리즈 표를 따른다. SDK 발행만으로 LAN 로그인이

바로 가능해지는 것은 아니다. 소비 앱의 옵션·callback·실행 버전 적용과 실기기 QA도 필요하다.

이미 Auth Test면 기존 구성을 사용하며 Secret Key 환경과 혼동하지 않는다. 기존 live/localhost/HTTPS 주소는 보존한다.

Spectra JavaScript SDK
├─ Auth JS SDK
│  ├─ Client setup
│  │  ├─ new SpectraAuthClient(config)
│  │  ├─ createSpectraAuth(config)
│  │  └─ createLocalStorageSessionStore()
│  ├─ Login
│  │  ├─ signInWithGoogle(options?)
│  │  ├─ signInWithApple(options?)
│  │  └─ relaySpectraAuthCallback()
│  └─ Session and tokens
│     ├─ getSession()
│     ├─ getAccessToken(options?)
│     ├─ backend login verification token: getAccessToken() without service
│     ├─ refresh()
│     └─ logout()
├─ Notification JS SDK
│  ├─ Client setup
│  │  ├─ new SpectraNotificationClient(config)
│  │  └─ createSpectraNotificationClient(config)
│  ├─ Email verification
│  │  ├─ sendEmailCode(options)
│  │  └─ verifyEmailCode(options)
│  └─ Push registration
│     └─ registerForPush(options)
├─ Chat JS SDK
│  ├─ Client setup
│  │  ├─ new SpectraChatClient(config)
│  │  ├─ createSpectraChatClient(config)
│  │  └─ on(event, handler)
│  ├─ Rooms
│  │  ├─ listRooms(options?)
│  │  ├─ createDirectRoom({ userId })
│  │  ├─ createGroupRoom({ title?, userIds })
│  │  ├─ leaveRoom(roomId, options?)  # 0.2.0 unpublished
│  │  └─ getRoomMembership(roomId, options?)  # 0.2.0 unpublished
│  ├─ Messages
│  │  ├─ listMessages(roomId, options?)
│  │  ├─ sendMessage(roomId, options)
│  │  └─ markRead(roomId, { lastReadSequence })
│  └─ Realtime
│     ├─ connect(roomId)
│     ├─ setTyping(roomId, isTyping)
│     └─ disconnect()
└─ Storage JS SDK
   ├─ Client setup
   │  ├─ new SpectraStorageClient(config)
   │  └─ createSpectraStorageClient(config)
   └─ Files
      ├─ listFiles(options?)
      ├─ uploadFile(input)
      ├─ uploadImage(input)
      ├─ getDownloadUrl(path)
      ├─ downloadBlob(path)
      └─ deleteFile(path)

기본 사용 흐름

앱에는 공개 가능한 설정만 넣는다.

제품 계약에서 사용자가 관리해야 하는 주요 값은 Project ID + Secret Key다. Secret Key는 최초 발급 또는

재발급 직후 한 번만 보여주며, Project마다 활성 key는 하나만 존재한다. 최초 발급 전과 재발급 시 새

Secret Key의 test 또는 live 환경을 선택할 수 있고, 재발급 뒤 이전 key는 더 이상 usable하지 않다.

Secret Key 자체에는 기능 권한을 담지 않고, 만료일도 두지 않는다. 사용자-facing 기본 문서는 Secret Key

만료일 입력/표시를 노출하지 않는다. Email/Push/Storage/Chat/Call 사용 가능 여부는 Project dashboard service

toggle로 결정하며, Secret Key 접근 제어는 재발급, 폐기, service 비활성화로 수행한다.

서버 발송, Storage 관리, 운영성 Push 같은 backend 작업은 앱 Backend나 secret manager에 보관한 Secret Key로

Project를 확인한 뒤 해당 service toggle이 켜져 있을 때만 수행한다. 현재 SDK/API field에 남아 있는

publicClientId는 current package compatibility로만 다루며, 서버 권한이나 사용자가 관리해야 할 주요 key로

설명하지 않는다.

기본 예시에 endpoint override를 넣지 않는다. 로컬 producer 테스트나 Platform CS 진단에서만 고급 설정으로 다룬다.

Secret과 provider credential은 다음처럼 다룬다.

import {
  SpectraAuthClient,
  createLocalStorageSessionStore,
} from "@spectra-platform/auth-sdk";
import { SpectraStorageClient } from "@spectra-platform/storage-sdk";

const auth = new SpectraAuthClient({
  projectId: "proj_...",
  // Current Auth SDK compatibility field. It is not a primary product key.
  publicClientId: "app_...",
  environment: "test",
  redirectUri: "https://myapp.example.com/auth/callback",
  sessionStore: createLocalStorageSessionStore(),
});

await auth.signInWithGoogle();

const storage = new SpectraStorageClient({
  projectId: "proj_...",
  auth,
});

await storage.uploadFile({
  file,
  path: "/reviews/photo.jpg",
  visibility: "private",
  context: "review",
  fileInfo: {
    originalName: file.name,
    lastModified: file.lastModified,
  },
});

로컬 SDK 로그인 테스트

로컬 앱도 공개 Auth 서버를 그대로 사용할 수 있다. 이때 핵심은 앱의 redirectUri와 브라우저 origin이

Spectra Auth 서버에 허용되어 있어야 한다는 점이다.

const auth = new SpectraAuthClient({
  baseUrl: "https://auth.spectra.kr",
  projectId: "proj_...",
  // Current Auth SDK compatibility field. It is not a primary product key.
  publicClientId: "app_...",
  environment: "test",
  redirectUri: "http://127.0.0.1:5174/auth/callback",
});

SDK별 기능 요약

Auth JS SDK

GET /platform/v1/auth/sessions/current 응답의 Project/client/environment/app-user를 대조한다.

AUTH_SESSION_SCOPE_FORBIDDEN으로 거절한다.

Notification JS SDK

Chat JS SDK

Storage JS SDK

문서 구분

에이전트가 읽을 때는 Agent-readable SDK index를 우선 사용한다.