@playcademy/sdk 0.0.1-beta.3 → 0.0.1-beta.5

package/build.ts

@@ -0,0 +1,50 @@
+import { $ } from 'bun'
+import packageJson from './package.json' assert { type: 'json' }
+import yoctoSpinner from 'yocto-spinner'
+
+const startTime = performance.now()
+const spinner = yoctoSpinner({ text: 'Building JavaScript...' }).start()
+
+const buildDir = './dist'
+const entrypoints = ['./src/runtime.ts', './src/types.ts']
+
+try {
+    await $`rm -rf ${buildDir}`
+
+    const external = [
+        // ...Object.keys(packageJson.dependencies), // no deps atm
+        ...Object.keys(packageJson.peerDependencies),
+    ]
+
+    await Bun.build({
+        entrypoints,
+        external,
+        outdir: buildDir,
+        format: 'esm',
+        target: 'node',
+    })
+
+    spinner.text = 'Generating types...'
+
+    const { stderr } =
+        await $`tsc --emitDeclarationOnly --declaration --project tsconfig.types.json --outDir ${buildDir}`
+
+    if (stderr.toString().length) {
+        spinner.error(`Type generation failed:\n${stderr.toString()}`)
+        process.exit(1) // Exit with error code
+    } else {
+        const duration = ((performance.now() - startTime) / 1000).toFixed(2)
+        spinner.success(`Build complete in ${duration}s!`)
+
+        // Log built entrypoints
+        for (const entry of entrypoints) {
+            console.log(`  - ${entry}`)
+        }
+    }
+    process.exit(0)
+} catch (error) {
+    const duration = ((performance.now() - startTime) / 1000).toFixed(2)
+    console.log({ error })
+    spinner.error(`Build failed in ${duration}s: ${error}`)
+    process.exit(1) // Exit with error code
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@playcademy/sdk",
     "type": "module",
-    "version": "0.0.1-beta.3",
+    "version": "0.0.1-beta.5",
     "exports": {
         ".": {
             "import": "./dist/runtime.js",
@@ -16,17 +16,12 @@
     },
     "main": "dist/runtime.js",
     "module": "dist/runtime.js",
-    "files": [
-        "dist"
-    ],
     "scripts": {
         "build": "bun build.js",
-        "pub": "bun run build && bunx bumpp --no-tag --no-push && bun publish --access public"
-    },
-    "dependencies": {
-        "@playcademy/data": "0.0.1"
+        "pub": "bun run build && bunx bumpp --no-tag --no-push -c \"chore(@playcademy/sdk): release v{version}\" && bun publish --access public"
     },
     "devDependencies": {
+        "@playcademy/types": "latest",
         "@types/bun": "latest",
         "typescript": "^5.0.0",
         "yocto-spinner": "^0.2.1"

package/src/bus.ts

@@ -0,0 +1,74 @@
+import type { GameContextPayload } from './types'
+
+export enum BusEvents {
+    // Overworld → Game
+    INIT = 'PLAYCADEMY_INIT',
+    TOKEN_REFRESH = 'PLAYCADEMY_TOKEN_REFRESH',
+    PAUSE = 'PLAYCADEMY_PAUSE',
+    RESUME = 'PLAYCADEMY_RESUME',
+    FORCE_EXIT = 'PLAYCADEMY_FORCE_EXIT',
+    OVERLAY = 'PLAYCADEMY_OVERLAY',
+
+    // Overworld ← Game
+    READY = 'PLAYCADEMY_READY',
+    EXIT = 'PLAYCADEMY_EXIT',
+    TELEMETRY = 'PLAYCADEMY_TELEMETRY',
+}
+
+type BusHandler<T = unknown> = (payload: T) => void
+
+export type BusEventMap = {
+    [BusEvents.INIT]: GameContextPayload
+    [BusEvents.TOKEN_REFRESH]: { token: string; exp: number }
+    [BusEvents.PAUSE]: void
+    [BusEvents.RESUME]: void
+    [BusEvents.FORCE_EXIT]: void
+    [BusEvents.OVERLAY]: boolean
+
+    [BusEvents.READY]: void
+    [BusEvents.EXIT]: void
+    [BusEvents.TELEMETRY]: { fps: number; mem: number }
+    // ...
+}
+
+interface Bus {
+    emit<K extends BusEvents>(type: K, payload: BusEventMap[K]): void
+    on<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void
+    off<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void
+}
+
+const busListeners = new Map<
+    BusEvents,
+    Map<BusHandler, EventListenerOrEventListenerObject>
+>()
+
+export const bus: Bus = {
+    emit<K extends BusEvents>(type: K, payload: BusEventMap[K]) {
+        window.dispatchEvent(new CustomEvent(type, { detail: payload }))
+    },
+    on<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>) {
+        const listener = (event: Event) =>
+            handler((event as CustomEvent).detail)
+
+        if (!busListeners.has(type)) {
+            busListeners.set(type, new Map())
+        }
+        busListeners.get(type)!.set(handler as BusHandler, listener)
+
+        window.addEventListener(type, listener)
+    },
+    off<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>) {
+        const typeListeners = busListeners.get(type)
+        if (!typeListeners || !typeListeners.has(handler as BusHandler)) {
+            return
+        }
+
+        const actualListener = typeListeners.get(handler as BusHandler)!
+        window.removeEventListener(type, actualListener)
+        typeListeners.delete(handler as BusHandler)
+
+        if (typeListeners.size === 0) {
+            busListeners.delete(type)
+        }
+    },
+}

package/src/core/client.ts

@@ -0,0 +1,416 @@
+import {
+    request as instanceRequest,
+    type Method,
+    fetchManifest,
+} from './request'
+import { PlaycademyError } from './errors'
+import { bus, BusEvents } from '../bus'
+
+import type {
+    Game,
+    GameWithManifest,
+    DeveloperKey,
+    DeveloperStatusResponse,
+    UpsertGameMetadataInput,
+    Reward,
+    InsertReward,
+    UpdateReward,
+    MapElement,
+} from '@playcademy/types'
+
+import type {
+    User,
+    GameState,
+    InventoryItemWithReward,
+    ClientConfig,
+    ClientEvents,
+    EventListeners,
+    LoginResponse,
+    GameTokenResponse,
+    StartSessionResponse,
+    InventoryMutationResponse,
+    DeveloperStatusValue,
+} from '../types'
+
+export class PlaycademyClient {
+    private baseUrl: string
+    private token?: string
+    private gameId?: string
+    private listeners: EventListeners = {}
+
+    private internalClientSessionId?: string
+
+    constructor(config: ClientConfig) {
+        this.baseUrl = config.baseUrl
+        this.token = config.token
+        this.gameId = config.gameId
+
+        if (this.gameId) {
+            this._initializeInternalSession().catch(error => {
+                console.error(
+                    '[SDK] Background initialization of auto-session failed:',
+                    error,
+                )
+            })
+        }
+    }
+
+    private async _initializeInternalSession(): Promise<void> {
+        if (!this.gameId || this.internalClientSessionId) {
+            return
+        }
+
+        try {
+            const response = await this.games.startSession(this.gameId)
+            this.internalClientSessionId = response.sessionId
+        } catch (error) {
+            console.error(
+                '[SDK] Auto-starting session failed for game',
+                this.gameId,
+                error,
+            )
+        }
+    }
+
+    // --- Public Accessors ---
+
+    public getBaseUrl(): string {
+        const isRelative = this.baseUrl.startsWith('/')
+        const isBrowser = typeof window !== 'undefined'
+
+        return isRelative && isBrowser
+            ? `${window.location.origin}${this.baseUrl}`
+            : this.baseUrl
+    }
+
+    // --- Event Handling ---
+
+    on<E extends keyof ClientEvents>(
+        event: E,
+        callback: (payload: ClientEvents[E]) => void,
+    ) {
+        this.listeners[event] = this.listeners[event] ?? []
+        this.listeners[event].push(callback)
+    }
+
+    private emit<E extends keyof ClientEvents>(
+        event: E,
+        payload: ClientEvents[E],
+    ) {
+        ;(this.listeners[event] ?? []).forEach(listener => {
+            ;(listener as (arg: ClientEvents[E]) => void)(payload)
+        })
+    }
+
+    // --- State Management ---
+
+    setToken(token: string | null) {
+        this.token = token ?? undefined
+        this.emit('authChange', { token: this.token ?? null })
+    }
+
+    onAuthChange(callback: (token: string | null) => void): void {
+        this.on('authChange', payload => callback(payload.token))
+    }
+
+    // --- Request Wrapper ---
+
+    protected async request<T>(
+        path: string,
+        method: Method,
+        body?: unknown,
+        headers?: Record<string, string>,
+    ) {
+        const effectiveHeaders = { ...headers }
+
+        return instanceRequest<T>({
+            path,
+            method,
+            body,
+            baseUrl: this.baseUrl,
+            token: this.token,
+            extraHeaders: effectiveHeaders,
+        })
+    }
+
+    // --- Private Utilities ---
+
+    private _ensureGameId(): string {
+        if (!this.gameId) {
+            throw new PlaycademyError(
+                'This operation requires a gameId, but none was provided when initializing the client.',
+            )
+        }
+        return this.gameId
+    }
+
+    // --- Namespaced API Methods ---
+
+    auth = {
+        logout: async (): Promise<void> => {
+            await this.request(`/auth/logout`, 'DELETE')
+            this.setToken(null)
+        },
+    }
+
+    runtime = {
+        getGameToken: async (
+            gameId: string,
+            options?: { apply?: boolean },
+        ): Promise<GameTokenResponse> => {
+            const res = await this.request<GameTokenResponse>(
+                `/games/${gameId}/token`,
+                'POST',
+            )
+            if (options?.apply) {
+                this.setToken(res.token)
+            }
+            return res
+        },
+        exit: async (): Promise<void> => {
+            if (this.internalClientSessionId && this.gameId) {
+                try {
+                    await this.games.endSession(
+                        this.internalClientSessionId,
+                        this.gameId,
+                    )
+                } catch (error) {
+                    console.error(
+                        '[SDK] Failed to auto-end session:',
+                        this.internalClientSessionId,
+                        error,
+                    )
+                }
+            }
+            bus.emit(BusEvents.EXIT, undefined)
+        },
+    }
+
+    games = {
+        fetch: async (gameIdOrSlug: string): Promise<GameWithManifest> => {
+            const baseGameData = await this.request<Game>(
+                `/games/${gameIdOrSlug}`,
+                'GET',
+            )
+
+            const manifestData = await fetchManifest(
+                baseGameData.assetBundleBase,
+            )
+
+            return {
+                ...baseGameData,
+                manifest: manifestData,
+            }
+        },
+        list: (): Promise<Array<Game>> =>
+            this.request<Array<Game>>('/games', 'GET'),
+
+        saveState: async (state: Record<string, unknown>) => {
+            const gameId = this._ensureGameId()
+            await this.request<void>(`/games/${gameId}/state`, 'POST', state)
+        },
+        loadState: async () => {
+            const gameId = this._ensureGameId()
+            return this.request<GameState>(`/games/${gameId}/state`, 'GET')
+        },
+        startSession: async (
+            gameId?: string,
+        ): Promise<StartSessionResponse> => {
+            const idToUse = gameId ?? this._ensureGameId()
+            return this.request<StartSessionResponse>(
+                `/games/${idToUse}/sessions`,
+                'POST',
+                {},
+            )
+        },
+        endSession: async (
+            sessionId: string,
+            gameId?: string,
+        ): Promise<void> => {
+            const effectiveGameIdToEnd = gameId ?? this._ensureGameId()
+
+            if (
+                this.internalClientSessionId &&
+                sessionId === this.internalClientSessionId &&
+                effectiveGameIdToEnd === this.gameId
+            ) {
+                this.internalClientSessionId = undefined
+            }
+            await this.request<void>(
+                `/games/${effectiveGameIdToEnd}/sessions/${sessionId}/end`,
+                'POST',
+            )
+        },
+    }
+
+    users = {
+        me: async () => {
+            return this.request<User>('/users/me', 'GET')
+        },
+
+        inventory: {
+            get: async () =>
+                this.request<Array<InventoryItemWithReward>>(
+                    `/inventory`,
+                    'GET',
+                ),
+            add: async (
+                rewardId: string,
+                qty: number,
+            ): Promise<InventoryMutationResponse> => {
+                const res = await this.request<InventoryMutationResponse>(
+                    `/inventory/add`,
+                    'POST',
+                    { rewardId, qty },
+                )
+                this.emit('inventoryChange', {
+                    rewardId,
+                    delta: qty,
+                    newTotal: res.newTotal,
+                })
+                return res
+            },
+            spend: async (
+                rewardId: string,
+                qty: number,
+            ): Promise<InventoryMutationResponse> => {
+                const res = await this.request<InventoryMutationResponse>(
+                    `/inventory/spend`,
+                    'POST',
+                    { rewardId, qty },
+                )
+                this.emit('inventoryChange', {
+                    rewardId,
+                    delta: -qty,
+                    newTotal: res.newTotal,
+                })
+                return res
+            },
+        },
+    }
+
+    dev = {
+        auth: {
+            applyForDeveloper: () => this.request<void>('/dev/apply', 'POST'),
+            getDeveloperStatus: async (): Promise<DeveloperStatusValue> => {
+                const response = await this.request<DeveloperStatusResponse>(
+                    '/dev/status',
+                    'GET',
+                )
+                return response.status
+            },
+        },
+
+        games: {
+            upsert: (
+                slug: string,
+                metadata: UpsertGameMetadataInput,
+                file: File | Blob,
+            ): Promise<Game> => {
+                const form = new FormData()
+                form.append('metadata', JSON.stringify(metadata))
+                form.append('file', file)
+                return this.request<Game>(`/games/${slug}`, 'PUT', form)
+            },
+
+            update: (gameId: string, props: Partial<Game>) =>
+                this.request<void>(`/games/${gameId}`, 'PATCH', props),
+
+            delete: (gameId: string): Promise<void> =>
+                this.request<void>(`/games/${gameId}`, 'DELETE'),
+        },
+
+        keys: {
+            createKey: (gameId: string, label?: string) =>
+                this.request<DeveloperKey>(
+                    `/dev/games/${gameId}/keys`,
+                    'POST',
+                    { label },
+                ),
+
+            listKeys: (gameId: string) =>
+                this.request<Array<DeveloperKey>>(
+                    `/dev/games/${gameId}/keys`,
+                    'GET',
+                ),
+
+            revokeKey: (keyId: string) =>
+                this.request<void>(`/dev/keys/${keyId}`, 'DELETE'),
+        },
+    }
+
+    maps = {
+        elements: (mapId: string) =>
+            this.request<Array<MapElement>>(
+                `/map/elements?mapId=${mapId}`,
+                'GET',
+            ),
+    }
+
+    admin = {
+        games: {
+            pauseGame: (gameId: string) =>
+                this.request<void>(`/admin/games/${gameId}/pause`, 'POST'),
+            resumeGame: (gameId: string) =>
+                this.request<void>(`/admin/games/${gameId}/resume`, 'POST'),
+        },
+        rewards: {
+            createReward: (props: InsertReward) =>
+                this.request<Reward>('/rewards', 'POST', props),
+            getReward: (rewardId: string) =>
+                this.request<Reward>(`/rewards/${rewardId}`, 'GET'),
+            listRewards: () => this.request<Array<Reward>>('/rewards', 'GET'),
+            updateReward: (rewardId: string, props: UpdateReward) =>
+                this.request<Reward>(`/rewards/${rewardId}`, 'PATCH', props),
+            deleteReward: (rewardId: string) =>
+                this.request<void>(`/rewards/${rewardId}`, 'DELETE'),
+        },
+    }
+
+    telemetry = {
+        pushMetrics: (metrics: Record<string, number>) =>
+            this.request<void>(`/telemetry/metrics`, 'POST', metrics),
+    }
+
+    ping(): string {
+        return 'pong'
+    }
+
+    public static async login(
+        baseUrl: string,
+        email: string,
+        password: string,
+    ): Promise<LoginResponse> {
+        let url = baseUrl
+        if (baseUrl.startsWith('/') && typeof window !== 'undefined') {
+            url = window.location.origin + baseUrl
+        }
+        url = url + '/auth/login'
+
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ email, password }),
+        })
+
+        if (!response.ok) {
+            try {
+                const errorData = await response.json()
+                const errorMessage =
+                    errorData && errorData.message
+                        ? String(errorData.message)
+                        : response.statusText
+                throw new PlaycademyError(errorMessage)
+            } catch (error) {
+                console.error(
+                    '[SDK] Failed to parse error response JSON, using status text instead:',
+                    error,
+                )
+                throw new PlaycademyError(response.statusText)
+            }
+        }
+        return response.json() as Promise<LoginResponse>
+    }
+}

package/src/core/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+export class PlaycademyError extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = 'PlaycademyError'
+    }
+}
+
+export class ApiError extends Error {
+    constructor(
+        public status: number,
+        message: string,
+        public details: unknown,
+    ) {
+        super(`${status} ${message}`)
+        Object.setPrototypeOf(this, ApiError.prototype)
+    }
+}

package/src/core/request.ts

@@ -0,0 +1,104 @@
+import { ApiError } from './errors'
+import { PlaycademyError } from './errors'
+import type { ManifestV1 } from '@playcademy/types'
+
+/** Permitted HTTP verbs */
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+export interface RequestOptions {
+    path: string
+    baseUrl: string
+    token?: string | null
+    method?: Method
+    body?: unknown
+    extraHeaders?: Record<string, string>
+}
+
+/**
+ * Thin wrapper around `fetch` that:
+ *  • attaches Bearer token if provided
+ *  • stringifies JSON bodies and sets Content‑Type
+ *  • passes FormData untouched so the browser adds multipart boundary
+ *  • normalises non‑2xx responses into ApiError
+ *  • auto‑parses JSON responses, falls back to text/void
+ */
+export async function request<T = unknown>({
+    path,
+    baseUrl,
+    token,
+    method = 'GET',
+    body,
+    extraHeaders = {},
+}: RequestOptions): Promise<T> {
+    const url =
+        baseUrl.replace(/\/$/, '') + (path.startsWith('/') ? path : `/${path}`)
+
+    const headers: Record<string, string> = { ...extraHeaders }
+    let payload: BodyInit | undefined
+
+    if (body instanceof FormData) {
+        payload = body // let browser add multipart headers
+    } else if (body !== undefined && body !== null) {
+        payload = JSON.stringify(body)
+        headers['Content-Type'] = 'application/json'
+    }
+
+    if (token) headers['Authorization'] = `Bearer ${token}`
+
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: payload,
+        credentials: 'omit',
+    })
+
+    if (!res.ok) {
+        const errorBody =
+            (await res
+                .clone() // clone so we can try json then text
+                .json()
+                .catch(() => res.text().catch(() => undefined))) ?? undefined
+
+        throw new ApiError(res.status, res.statusText, errorBody)
+    }
+
+    if (res.status === 204) return undefined as unknown as T
+
+    const contentType = res.headers.get('content-type') ?? ''
+    if (contentType.includes('application/json')) {
+        return (await res.json()) as T
+    }
+
+    // TODO: blob/arrayBuffer behaviour can be added if needed later
+    return (await res.text()) as unknown as T
+}
+
+/**
+ * Fetches, parses, and validates the playcademy.manifest.json file from a given base URL.
+ */
+export async function fetchManifest(
+    assetBundleBase: string,
+): Promise<ManifestV1> {
+    const manifestUrl = `${assetBundleBase.replace(/\/$/, '')}/playcademy.manifest.json`
+    try {
+        const response = await fetch(manifestUrl)
+        if (!response.ok) {
+            console.error(
+                `[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`,
+            )
+            throw new PlaycademyError(
+                `Failed to fetch manifest: ${response.status} ${response.statusText}`,
+            )
+        }
+        return (await response.json()) as ManifestV1
+    } catch (error) {
+        if (error instanceof PlaycademyError) {
+            throw error
+        }
+        console.error(
+            `[fetchManifest] Error fetching or parsing manifest from ${manifestUrl}:`,
+            error,
+        )
+        throw new PlaycademyError('Failed to load or parse game manifest')
+    }
+}