@deplois/session 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @deplois/session
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deplois API 규격을 사용하는 Nuxt 4 세션 플러그인입니다. 버전은 `major.minor.fetch` 순서이며 시작 버전은 `1.0.0`입니다. 현재 백엔드 버전 비교는 하지 않습니다.
+
+## 설치
+
+배포 전에는 로컬 패키지 경로로 설치합니다.
+
+```sh
+npm install ../session
+```
+
+npm 배포 후에는 `npm install @deplois/session`으로 설치합니다.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+    modules: ['@deplois/session']
+})
+```
+
+```dotenv
+API_ENDPOINT=http://localhost:4002
+```
+
+`API_ENDPOINT`는 Nuxt 개발/빌드 시 읽습니다. 빌드된 서버 실행 시 변경하려면 `NUXT_PUBLIC_API_ENDPOINT`를 사용합니다. 공개 API 주소이므로 비밀키를 넣지 않습니다.
+
+기존 `$session`, `$api` 제공 플러그인과 중복 등록하지 않습니다. 디자인 패키지 `@deplois/template`와는 독립적입니다.
+
+## 사용
+
+```ts
+const { $api, $session } = useNuxtApp()
+
+onMounted(async () => {
+    const result = await $api.get('/v1/user/me')
+    if (result.success == false) {
+        console.error(result.error)
+        return
+    }
+    console.log(result.data)
+})
+```
+
+`$api.get/post/put/patch/delete`는 Axios와 같은 인자를 받습니다. 첫 요청에서 세션을 자동 생성하거나 복원합니다. 응답의 `data`는 서버의 `response.data.data`, 오류는 서버의 `response.data.error`입니다. 서버의 오류 객체와 추가 필드는 그대로 유지합니다. `status`, `raw`도 반환합니다.
+
+```ts
+const session = $session().data
+await session.initialize() // 명시적으로 준비할 때 (실패 시 throw)
+await session.initialize(true) // 서버에 다시 확인
+session.state.ready
+session.state.record?.id
+session.state.error
+await session.revoke() // DELETE /session 후 로컬 상태 삭제
+session.clear() // 로컬 상태만 삭제, 서버 세션 철회 아님
+```
+
+세션 요청은 브라우저에서 실행합니다. SSR에서 호출하면 `CLIENT_SESSION_REQUIRED` 오류 결과를 반환합니다. 세션 토큰을 SSR HTML/payload에 직렬화하지 않습니다. 초기화는 지연 실행되며 페이지 이동은 앱에서 관리합니다.
+
+## API 규격
+
+- `PUT /session`: `{ success: true, data: { id, token, expires_in }, error: null }`
+- `GET /session`: `{ success: true, data: { expires_in }, error: null }`
+- `DELETE /session`: 세션 철회
+- 인증 헤더: `Authorization: Bearer <session token>`
+- 실패: `{ success: false, data: null, error: { code, message } }`
+- `expires_in` 단위는 초입니다. 세션 사용 시 연장은 서버가 담당합니다.
+
+저장은 API 주소별 localStorage 키로 분리합니다. 같은 탭의 초기화 요청은 합치며, 지원 브라우저에서는 Web Locks로 탭 간 생성도 직렬화합니다. 다른 탭의 저장 변경을 감지합니다. 저장소 접근이 불가능하면 현재 탭 메모리만 사용합니다.
+
+저장된 세션이 `EXPIRED_SESSION`, `WRONG_SESSION`, `REQUIRED_SESSION`이면 초기화 시 새 세션을 생성합니다. 일반 API 요청 중 세션 오류가 발생하면 상태를 초기화하고 오류를 반환합니다. 결제 같은 요청이 중복 실행되지 않도록 실패한 요청을 자동 재전송하지 않습니다. 다음 요청부터 새 세션을 생성합니다.
+
+## 검증
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+## Access token
+
+세션 인증은 `$api.get/post/put/patch/delete`, access token 인증은 `$api.access.get/post/put/patch/delete`로 구분합니다. 인자와 응답 형식은 같습니다.
+
+```ts
+const { $api } = useNuxtApp()
+
+// OAuth callback 등에서 전달받은 토큰 저장
+$api.access.setToken(accessToken)
+$api.access.hasToken()
+
+const result = await $api.access.get('/v1/user/me')
+
+// 로그아웃할 때 로컬 토큰 삭제
+$api.access.clearToken()
+```
+
+Access token은 API 주소별 `sessionStorage`에 보관하여 같은 탭에서 새로고침해도 복원됩니다. 저장소 접근이 불가능하면 메모리만 사용합니다. `Bearer ` 접두어를 포함한 토큰도 받을 수 있습니다.
+
+Access 요청은 세션 생성 없이 `Authorization: Bearer <access token>`을 보냅니다. 토큰이 없으면 `REQUIRED_ACCESS_TOKEN`, SSR에서 호출하면 `CLIENT_ACCESS_REQUIRED` 오류를 반환합니다. 서버가 401을 반환하면 해당 요청에 사용한 토큰이 현재 토큰인 경우에만 삭제합니다. 토큰 발급·refresh·서버 철회는 앱의 OAuth 흐름에서 처리합니다.
+
+
+## 로컬 배포 명령
+
+```sh
+npm run publish -- 1.2.3 "커밋 메시지" --deploy
+npm run publish -- major "커밋 메시지" --deploy
+npm run publish -- minor "커밋 메시지" --deploy
+npm run publish -- fetch "커밋 메시지" --deploy
+```
+
+현재 버전이 `1.2.3`일 때 `major`는 `2.0.0`, `minor`는 `1.3.0`, `fetch`는 `1.2.4`가 됩니다. 상위 버전을 올리면 하위 버전은 0으로 초기화합니다.
+
+`--deploy`를 빼면 버전 변경·커밋·Git push까지만 진행합니다. `npm run deploy`는 현재 버전을 npm에만 배포합니다.
+
+`scripts/publish.mjs`는 로컬 전용으로 Git 추적과 npm 패키지에서 제외합니다. 새로 clone한 환경에서 배포 명령을 쓰려면 이 파일을 별도로 복사해야 합니다.

package/module.mjs

@@ -0,0 +1,10 @@
+import { defineNuxtModule, createResolver, addPlugin } from '@nuxt/kit'
+
+export default defineNuxtModule({
+    meta: { name: '@deplois/session', configKey: 'session' },
+    setup(options, nuxt) {
+        const resolve = createResolver(import.meta.url)
+        nuxt.options.runtimeConfig.public.apiEndpoint ||= process.env.API_ENDPOINT || ''
+        addPlugin(resolve.resolve('./runtime/plugin'))
+    }
+})

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@deplois/session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./module.mjs",
+  "exports": {
+    ".": "./module.mjs",
+    "./runtime": "./runtime/session.ts"
+  },
+  "files": [
+    "module.mjs",
+    "runtime",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pack": "npm pack",
+    "check": "npm test",
+    "publish": "node scripts/publish.mjs",
+    "deploy": "node scripts/publish.mjs"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.1.2",
+    "axios": "^1.13.1"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.1.2",
+    "vue": "^3.5.21"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vue": "^3.5.21"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "UNLICENSED"
+}

package/runtime/plugin.ts

@@ -0,0 +1,55 @@
+import { defineNuxtPlugin, useRuntimeConfig } from '#app'
+import { APIClientError, AccessAPI, Session } from './session'
+
+export default defineNuxtPlugin({
+    name: 'deplois-session',
+    setup() {
+        const config = useRuntimeConfig()
+        const baseURL = String(config.public.apiEndpoint || '').replace(/\/+$/, '')
+        if (!/^https?:\/\//.test(baseURL)) {
+            throw new APIClientError('INVALID_API_ENDPOINT', 'Set API_ENDPOINT to an absolute HTTP or HTTPS URL.')
+        }
+        const key = `deplois.session:${baseURL}`
+        const access = new AccessAPI({
+            baseURL: baseURL,
+            key: `deplois.access:${baseURL}`,
+            storage: {
+                getItem: name => import.meta.client ? window.sessionStorage.getItem(name) : null,
+                setItem: (name, value) => { if (import.meta.client) window.sessionStorage.setItem(name, value) },
+                removeItem: name => { if (import.meta.client) window.sessionStorage.removeItem(name) }
+            },
+            beforeRequest: () => {
+                if (import.meta.server) throw new APIClientError('CLIENT_ACCESS_REQUIRED', 'Access token requests must run in the browser.')
+            }
+        })
+        const session = new Session({
+            baseURL: baseURL,
+            key: key,
+            storage: {
+                getItem: name => import.meta.client ? window.localStorage.getItem(name) : null,
+                setItem: (name, value) => { if (import.meta.client) window.localStorage.setItem(name, value) },
+                removeItem: name => { if (import.meta.client) window.localStorage.removeItem(name) }
+            },
+            lock: async <T>(work: () => Promise<T>): Promise<T> => {
+                if (import.meta.server) throw new APIClientError('CLIENT_SESSION_REQUIRED', 'Session requests must run in the browser.')
+                if (navigator.locks) return await navigator.locks.request(key, work)
+                return await work()
+            }
+        })
+
+        if (import.meta.client) {
+            const listener = (event: StorageEvent) => {
+                if (event.key === key || event.key === null) session.sync()
+            }
+            window.addEventListener('storage', listener)
+            if (import.meta.hot) import.meta.hot.dispose(() => window.removeEventListener('storage', listener))
+        }
+
+        return {
+            provide: {
+                session: () => ({ success: true, data: session }),
+                api: { ...session.api, access: access.api }
+            }
+        }
+    }
+})

package/runtime/session.ts

@@ -0,0 +1,389 @@
+import axios, { type AxiosRequestConfig, type AxiosAdapter, type AxiosInstance, type AxiosResponse, type InternalAxiosRequestConfig } from 'axios'
+import { reactive } from 'vue'
+
+export interface SessionRecord {
+    id: string
+    token: string
+}
+
+export interface SessionState {
+    record: SessionRecord | null
+    ready: boolean
+    expiresAt: number | null
+    error: string | null
+}
+
+export interface ApiEnvelope<T = unknown> {
+    success: boolean
+    data: T
+    error: { code: string, message: string } | null
+}
+
+export type APIResult<T> = {
+    success: true
+    data: T
+    status: number
+    raw: AxiosResponse<ApiEnvelope<T>>
+} | {
+    success: false
+    error: string | NonNullable<ApiEnvelope<unknown>['error']>
+    status: number
+    raw: unknown
+}
+
+export class APIClientError extends Error {
+    public readonly response: { status: number, data: { error: string } }
+
+    constructor(public code: string, message: string, public status = 0, public raw?: unknown) {
+        super(message)
+        this.name = 'APIClientError'
+        this.response = { status, data: { error: message } }
+    }
+}
+
+export class AccessAPI {
+    private axios: AxiosInstance
+    private token: string | null = null
+
+    public api = {
+        get: <T = any>(url: string, config?: AxiosRequestConfig) => this.response(this.axios.get<ApiEnvelope<T>>(url, config)),
+        post: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.post<ApiEnvelope<T>>(url, data, config)),
+        put: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.put<ApiEnvelope<T>>(url, data, config)),
+        patch: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.patch<ApiEnvelope<T>>(url, data, config)),
+        delete: <T = any>(url: string, config?: AxiosRequestConfig) => this.response(this.axios.delete<ApiEnvelope<T>>(url, config)),
+        setToken: (token: string) => this.setToken(token),
+        clearToken: () => this.clearToken(),
+        hasToken: () => this.token != null || this.read() != null
+    }
+
+    constructor(private options: Pick<SessionOptions, 'baseURL' | 'adapter'> & {
+        key: string
+        storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+        beforeRequest?: () => void
+    }) {
+        this.axios = axios.create({ baseURL: options.baseURL, timeout: 15000, adapter: options.adapter })
+        this.token = this.read()
+        this.axios.interceptors.request.use(config => {
+            this.options.beforeRequest?.()
+            const base = new URL(this.options.baseURL)
+            const target = new URL(this.axios.getUri(config), `${this.options.baseURL}/`)
+            const path = base.pathname.replace(/\/+$/, '')
+            if (target.origin !== base.origin || target.username || target.password
+                || (path && target.pathname !== path && !target.pathname.startsWith(`${path}/`))) {
+                throw new APIClientError('INVALID_URL', 'Invalid API path.')
+            }
+            const token = this.token ?? this.read()
+            if (!token) throw new APIClientError('REQUIRED_ACCESS_TOKEN', 'Required access token.', 401)
+            this.token = token
+            config.headers.set('Authorization', `Bearer ${token}`, true)
+            return config
+        })
+    }
+
+    private read(): string | null {
+        try {
+            const token = this.options.storage.getItem(this.options.key)
+            return typeof token === 'string' && token.trim() ? token.replace(/^Bearer\s+/i, '').trim() : null
+        } catch {
+            return null
+        }
+    }
+
+    private setToken(token: string): void {
+        const value = token.replace(/^Bearer\s+/i, '').trim()
+        this.token = value || null
+        try {
+            if (this.token) this.options.storage.setItem(this.options.key, this.token)
+            else this.options.storage.removeItem(this.options.key)
+        } catch { }
+    }
+
+    private clearToken(): void {
+        this.token = null
+        try { this.options.storage.removeItem(this.options.key) } catch { }
+    }
+
+    private async response<T>(request: Promise<AxiosResponse<ApiEnvelope<T>>>): Promise<APIResult<T>> {
+        try {
+            const response = await request
+            if (response.data?.success !== true) {
+                throw new APIClientError(
+                    response.data?.error?.code ?? 'INVALID_RESPONSE',
+                    response.data?.error?.message ?? 'Invalid server response.',
+                    response.status,
+                    response
+                )
+            }
+            return { success: true, data: response.data.data, status: response.status, raw: response }
+        } catch (error) {
+            const result = this.error(error)
+            const raw = result.raw ?? error
+            const config = axios.isAxiosError(raw) ? raw.config
+                : raw && typeof raw === 'object' && 'config' in raw ? (raw as AxiosResponse).config : null
+            if (result.status === 401 && this.token && config?.headers.get('Authorization') === `Bearer ${this.token}`) {
+                this.clearToken()
+            }
+            const body = axios.isAxiosError(raw) ? raw.response?.data
+                : raw && typeof raw === 'object' && 'data' in raw ? (raw as AxiosResponse<ApiEnvelope<unknown>>).data : null
+            return { success: false, error: body?.error ?? { code: result.code, message: result.message }, status: result.status, raw }
+        }
+    }
+
+    private error(error: unknown): APIClientError {
+        if (error instanceof APIClientError) return error
+        if (axios.isAxiosError(error)) {
+            const detail = error.response?.data?.error
+            return new APIClientError(
+                detail?.code ?? (error.response ? 'HTTP_ERROR' : 'NETWORK_ERROR'),
+                detail?.message ?? error.response?.data?.message ?? (error.response ? 'The request failed.' : 'Unable to connect to the server.'),
+                error.response?.status ?? 0,
+                error
+            )
+        }
+        return new APIClientError('REQUEST_FAILED', error instanceof Error ? error.message : 'The request failed.')
+    }
+}
+
+export interface SessionOptions {
+    baseURL: string
+    key: string
+    storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+    state?: SessionState
+    adapter?: AxiosAdapter
+    lock?: <T>(work: () => Promise<T>) => Promise<T>
+    onInvalidated?: () => void
+}
+
+const sessionErrors = new Set(['EXPIRED_SESSION', 'WRONG_SESSION', 'REQUIRED_SESSION'])
+
+export class Session {
+    public state: SessionState
+    public axios: AxiosInstance
+
+    public api = {
+        get: <T = any>(url: string, config?: AxiosRequestConfig) => this.response(this.axios.get<ApiEnvelope<T>>(url, config)),
+        post: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.post<ApiEnvelope<T>>(url, data, config)),
+        put: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.put<ApiEnvelope<T>>(url, data, config)),
+        patch: <T = any>(url: string, data?: unknown, config?: AxiosRequestConfig) => this.response(this.axios.patch<ApiEnvelope<T>>(url, data, config)),
+        delete: <T = any>(url: string, config?: AxiosRequestConfig) => this.response(this.axios.delete<ApiEnvelope<T>>(url, config))
+    }
+
+    private async response<T>(request: Promise<AxiosResponse<ApiEnvelope<T>>>): Promise<APIResult<T>> {
+        try {
+            const response = await request
+            return { success: true, data: response.data.data, status: response.status, raw: response }
+        } catch (error) {
+            const result = this.error(error)
+            const raw = result.raw ?? error
+            const body = axios.isAxiosError(raw) ? raw.response?.data
+                : raw && typeof raw === 'object' && 'data' in raw ? (raw as AxiosResponse<ApiEnvelope<unknown>>).data : null
+            return { success: false, error: body?.error ?? { code: result.code, message: result.message }, status: result.status, raw }
+        }
+    }
+
+    private message(value: unknown, fallback: string): string {
+        if (typeof value === 'string' && value.trim()) return value
+        if (Array.isArray(value)) {
+            const messages = value.filter((item): item is string => typeof item === 'string' && !!item.trim())
+            if (messages.length) return messages.join('\n')
+        }
+        return fallback
+    }
+
+    private transport: AxiosInstance
+    private pending: Promise<void> | null = null
+    private revision: number = 0
+    private duration: number = 86400
+
+    constructor(private options: SessionOptions) {
+        this.state = options.state ?? reactive({ record: null, ready: false, expiresAt: null, error: null })
+        const config = { baseURL: options.baseURL, timeout: 15000, adapter: options.adapter }
+        this.transport = axios.create(config)
+        this.axios = axios.create(config)
+
+        this.axios.interceptors.request.use(async config => {
+            this.validateURL(config)
+            await this.initialize()
+            const token = this.state.record?.token
+            if (!token) throw new APIClientError('SESSION_CHANGED', 'The session has changed. Please try again.')
+            config.headers.set('Authorization', `Bearer ${token}`, true)
+            return config
+        })
+
+        this.axios.interceptors.response.use(response => {
+            try {
+                this.check(response)
+                if (response.config.headers.get('Authorization') !== `Bearer ${this.state.record?.token}`) {
+                    throw new APIClientError('SESSION_CHANGED', 'The session has changed. Please try again.')
+                }
+                this.state.expiresAt = Date.now() + this.duration * 1000
+                return response
+            } catch (error) {
+                throw this.error(error, response.config)
+            }
+        }, error => {
+            throw this.error(error, error?.config)
+        })
+    }
+
+    public get isInitialized(): boolean {
+        return this.state.ready
+    }
+
+    private read(): SessionRecord | null {
+        try {
+            const record = JSON.parse(this.options.storage.getItem(this.options.key) ?? 'null')
+            if (typeof record?.id !== 'string' || !record.id) return null
+            if (typeof record?.token !== 'string' || !record.token) return null
+            return { id: record.id, token: record.token }
+        } catch {
+            return null
+        }
+    }
+
+    private write(record: SessionRecord | null): void {
+        try {
+            if (record) this.options.storage.setItem(this.options.key, JSON.stringify(record))
+            else this.options.storage.removeItem(this.options.key)
+        } catch {
+            // Keep the in-memory session when browser storage is unavailable.
+        }
+    }
+
+    private error(error: unknown, config?: InternalAxiosRequestConfig): APIClientError {
+        let result: APIClientError
+        if (error instanceof APIClientError) result = error
+        else if (axios.isAxiosError(error)) {
+            const detail = error.response?.data?.error
+            result = new APIClientError(
+                detail?.code ?? (error.response ? 'HTTP_ERROR' : 'NETWORK_ERROR'),
+                this.message(typeof detail === 'string' ? detail : detail?.message ?? error.response?.data?.message,
+                    error.response ? 'The request failed.' : 'Unable to connect to the server. Please try again later.'),
+                error.response?.status ?? 0,
+                error
+            )
+        } else {
+            result = new APIClientError('REQUEST_FAILED', error instanceof Error ? error.message : 'The request failed.')
+        }
+        const token = this.state.record?.token
+        if (token && config?.headers.get('Authorization') === `Bearer ${token}` && sessionErrors.has(result.code)) {
+            this.revision++
+            Object.assign(this.state, { record: null, ready: false, expiresAt: null })
+            if (this.read()?.token === token) this.write(null)
+            this.options.onInvalidated?.()
+        }
+        return result
+    }
+
+    private check<T>(response: AxiosResponse<ApiEnvelope<T>>): ApiEnvelope<T> {
+        if (response.data?.success !== true) {
+            throw new APIClientError(
+                response.data?.error?.code ?? 'INVALID_RESPONSE',
+                this.message(typeof response.data?.error === 'string' ? response.data.error : response.data?.error?.message, 'Invalid server response.'),
+                response.status,
+                response
+            )
+        }
+        return response.data
+    }
+
+    private validateURL(config: InternalAxiosRequestConfig): void {
+        const base = new URL(this.options.baseURL)
+        const url = this.axios.getUri(config)
+        const target = new URL(url, `${this.options.baseURL}/`)
+        const path = base.pathname.replace(/\/+$/, '')
+        if (target.origin !== base.origin || target.username || target.password
+            || (path && target.pathname !== path && !target.pathname.startsWith(`${path}/`))) {
+            throw new APIClientError('INVALID_URL', 'Invalid API path.')
+        }
+    }
+
+    public sync(): void {
+        const record = this.read()
+        if (record?.token === this.state.record?.token) return
+        this.revision++
+        this.state.record = record
+        this.state.ready = false
+        this.state.expiresAt = null
+    }
+
+    public initialize(force = false): Promise<void> {
+        if (this.pending) return this.pending
+        if (this.state.ready && this.state.expiresAt !== null && this.state.expiresAt > Date.now() && !force) return Promise.resolve()
+        const work = () => this.load()
+        this.pending = (this.options.lock ? this.options.lock(work) : work())
+            .catch(error => {
+                const result = this.error(error)
+                this.state.error = result.message
+                throw result
+            })
+            .finally(() => { this.pending = null })
+        return this.pending
+    }
+
+    private async load(): Promise<void> {
+        const revision = this.revision
+        const assertCurrent = () => {
+            if (revision !== this.revision) throw new APIClientError('SESSION_CHANGED', 'The session has changed. Please try again.')
+        }
+        this.state.error = null
+        this.state.ready = false
+        let record = this.read() ?? this.state.record
+        const saved = record
+        let expires: unknown
+
+        if (record) {
+            try {
+                const response = await this.transport.get<ApiEnvelope<{ expires_in: number }>>('/session', {
+                    headers: { Authorization: `Bearer ${record.token}` }
+                })
+                const data = this.check(response).data
+                expires = data?.expires_in
+            } catch (error) {
+                const result = this.error(error)
+                if (!sessionErrors.has(result.code)) throw result
+                assertCurrent()
+                // An expired response must not delete a session created by another tab.
+                if (this.read()?.token === record.token) this.write(null)
+                this.state.record = null
+                record = null
+            }
+        }
+
+        assertCurrent()
+        if (!record) {
+            const response = await this.transport.put<ApiEnvelope<SessionRecord & { expires_in: number }>>('/session', {}, { headers: { Authorization: false } })
+            assertCurrent()
+            const data = this.check(response).data
+            if (typeof data?.id !== 'string' || !data.id || typeof data?.token !== 'string' || !data.token) {
+                throw new APIClientError('INVALID_RESPONSE', 'Invalid session creation response.')
+            }
+            record = { id: data.id, token: data.token }
+            expires = data.expires_in
+        }
+
+        if (typeof expires !== 'number' || !Number.isFinite(expires) || expires < 0) {
+            throw new APIClientError('INVALID_RESPONSE', 'Invalid session expiration information.')
+        }
+        this.duration = expires
+        Object.assign(this.state, { record: record, ready: true, expiresAt: Date.now() + expires * 1000 })
+        if (record !== saved) this.write(record)
+    }
+
+    public clear(): void {
+        this.revision++
+        this.write(null)
+        Object.assign(this.state, { record: null, ready: false, expiresAt: null, error: null })
+    }
+
+    public async revoke(): Promise<APIResult<null>> {
+        const result = await this.api.delete<null>('/session')
+        if (result.success) this.clear()
+        return result
+    }
+
+    public async request<T = unknown>(method: string, path: string, data?: unknown): Promise<ApiEnvelope<T>> {
+        return (await this.axios.request<ApiEnvelope<T>>({ method: method, url: path, data: data })).data
+    }
+}
+