@playcademy/sdk 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.0.5",
+    "version": "0.0.7",
     "type": "module",
     "exports": {
         ".": {
@@ -8,6 +8,11 @@
             "require": "./dist/index.js",
             "types": "./dist/index.d.ts"
         },
+        "./server": {
+            "import": "./dist/server.js",
+            "require": "./dist/server.js",
+            "types": "./dist/server.d.ts"
+        },
         "./types": {
             "import": "./dist/types.js",
             "require": "./dist/types.js",
@@ -30,12 +35,14 @@
     },
     "devDependencies": {
         "@playcademy/data": "0.0.1",
+        "@playcademy/logger": "0.0.1",
         "@playcademy/sandbox": "0.1.0-beta.18",
         "@playcademy/test": "0.0.1",
         "@types/bun": "latest",
+        "rollup": "^4.50.2",
+        "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2",
-        "yocto-spinner": "^0.2.2",
-        "@playcademy/logger": "0.0.1"
+        "yocto-spinner": "^0.2.2"
     },
     "peerDependencies": {
         "drizzle-orm": "^0.42.0",

package/dist/core/auth/flows/popup.d.ts

@@ -1,14 +0,0 @@
-import type { AuthOptions, AuthResult } from '../../../types';
-/**
- * Popup-based OAuth flow implementation.
- * Used primarily for iframe contexts where redirects don't work.
- * With server-first architecture, the server handles token exchange.
- */
-/**
- * Initiates a popup-based OAuth flow.
- * Opens auth URL in popup and waits for server callback message.
- *
- * @param options - Authentication options
- * @returns Promise resolving to the authentication result
- */
-export declare function initiatePopupFlow(options: AuthOptions): Promise<AuthResult>;

package/dist/core/auth/flows/redirect.d.ts

@@ -1,15 +0,0 @@
-import type { AuthOptions, AuthResult } from '../../../types';
-/**
- * Redirect-based OAuth flow implementation.
- * Used for standalone applications where traditional OAuth redirects work.
- * With server-first architecture, the server handles token exchange.
- */
-/**
- * Initiates a redirect-based OAuth flow.
- * This will navigate away from the current page to the IdP.
- * The server callback will handle token exchange and redirect back.
- *
- * @param options - Authentication options
- * @returns Promise that never resolves (page navigates away)
- */
-export declare function initiateRedirectFlow(options: AuthOptions): Promise<AuthResult>;

package/dist/core/auth/flows/unified.d.ts

@@ -1,11 +0,0 @@
-/**
- * Unified authentication flow router for server-first architecture.
- * Routes to appropriate flow implementation based on mode.
- */
-import type { AuthOptions, AuthResult } from '../../../types';
-/**
- * Routes authentication request to the appropriate flow.
- * With server-first architecture, all flows end up at the same
- * server callback which handles token exchange.
- */
-export declare function initiateUnifiedFlow(options: AuthOptions): Promise<AuthResult>;

package/dist/core/auth/login.d.ts

@@ -1,20 +0,0 @@
-/**
- * Main login implementation for the Playcademy SDK.
- * Uses server-first architecture where the server handles token exchange.
- */
-import type { AuthOptions, AuthResult, PlaycademyClient } from '../../types';
-/**
- * Performs OAuth login with the specified provider.
- *
- * With server-first architecture:
- * 1. SDK initiates OAuth flow (popup or redirect)
- * 2. IdP redirects to your server callback URL
- * 3. Your server exchanges code for tokens
- * 4. Your server returns HTML that completes the flow
- * 5. SDK receives the user data via postMessage (popup) or cookie (redirect)
- *
- * @param client - The PlaycademyClient instance
- * @param options - Authentication options including callback URL
- * @returns Promise resolving to the authentication result
- */
-export declare function login(client: PlaycademyClient, options: AuthOptions): Promise<AuthResult>;

package/dist/core/auth/oauth.d.ts

@@ -1,115 +0,0 @@
-/**
- * OAuth 2.0 implementation for the Playcademy SDK
- */
-import type { AuthProviderType } from '../../types';
-/**
- * OAuth provider configuration
- */
-export interface OAuthConfig {
-    authorizationEndpoint: string;
-    tokenEndpoint: string;
-    clientId: string;
-    scope?: string;
-}
-/**
- * OAuth configuration for different providers
- */
-export declare const OAUTH_CONFIGS: Record<string, () => Partial<OAuthConfig>>;
-/**
- * OAuth state that needs to be maintained during the flow
- */
-export interface OAuthState {
-    /** Random state parameter for CSRF protection */
-    state: string;
-    /** PKCE code verifier */
-    codeVerifier?: string;
-    /** Timestamp when the state was created */
-    createdAt: number;
-}
-/**
- * OAuth callback parameters from the authorization server
- */
-export interface OAuthCallbackParams {
-    code?: string;
-    state?: string;
-    error?: string;
-    error_description?: string;
-}
-/**
- * Generates a cryptographically secure random state parameter for OAuth.
- * Used to prevent CSRF attacks during the OAuth flow.
- * Can optionally include encoded data like user ID for server-side association.
- *
- * @param data - Optional data to encode (e.g., { playcademy_user_id: "123" })
- * @returns A random state string, optionally with encoded data
- */
-export declare function generateOAuthState(data?: Record<string, string>): Promise<string>;
-/**
- * Parses an OAuth state parameter to extract CSRF token and any encoded data.
- *
- * @param state - The OAuth state parameter to parse
- * @returns Object containing CSRF token and optional decoded data
- */
-export declare function parseOAuthState(state: string): {
-    csrfToken: string;
-    data?: Record<string, string>;
-};
-/**
- * Generates a code verifier for PKCE (Proof Key for Code Exchange).
- *
- * @returns A random code verifier string
- */
-export declare function generateCodeVerifier(): string;
-/**
- * Generates a code challenge from a code verifier for PKCE.
- *
- * @param verifier - The code verifier
- * @returns Promise resolving to the code challenge
- */
-export declare function generateCodeChallenge(verifier: string): Promise<string>;
-/**
- * Builds the OAuth authorization URL with all required parameters.
- *
- * @param params - OAuth parameters
- * @returns The complete authorization URL
- */
-export declare function buildAuthorizationUrl(params: {
-    authorizationEndpoint: string;
-    clientId: string;
-    redirectUri: string;
-    state: string;
-    codeChallenge?: string;
-    scope?: string;
-    responseType?: string;
-}): string;
-/**
- * Parses OAuth callback parameters from a URL.
- *
- * @param url - The callback URL
- * @returns The parsed parameters
- */
-export declare function parseCallbackUrl(url: string): OAuthCallbackParams;
-/**
- * Validates OAuth callback parameters against the expected state.
- *
- * @param params - The callback parameters
- * @param expectedState - The expected state value
- * @returns True if valid, throws otherwise
- */
-export declare function validateCallbackParams(params: OAuthCallbackParams, expectedState: string): boolean;
-/**
- * Gets the default OAuth configuration for a provider.
- *
- * @param provider - The auth provider
- * @returns The partial OAuth configuration (may not include clientId)
- * @throws Error if provider is unknown
- */
-export declare function getOAuthConfig(provider: AuthProviderType): Partial<OAuthConfig>;
-/**
- * Gets the redirect URI for OAuth callback.
- *
- * @param customUri - Custom redirect URI provided by the user
- * @param isPopup - Whether this is for a popup flow (only used if no custom URI)
- * @returns The redirect URI
- */
-export declare function getRedirectUri(customUri?: string, isPopup?: boolean): string;

package/dist/core/auth/utils.d.ts

@@ -1,23 +0,0 @@
-/**
- * Opens a popup window with specific dimensions and features.
- *
- * @param url - The URL to open
- * @param name - The window name
- * @returns The opened window or null if blocked
- */
-export declare function openPopupWindow(url: string, name?: string, width?: number, height?: number): Window | null;
-/**
- * Detects if we're running in an iframe context.
- * Safe to call in any environment (browser or Node.js).
- *
- * @returns True if in iframe, false if standalone or not in browser
- */
-export declare function isInIframe(): boolean;
-/**
- * Creates a promise that resolves when a message is received from a window.
- *
- * @param targetWindow - The window to listen for messages from
- * @param timeout - Timeout in milliseconds
- * @returns Promise that resolves with the message data
- */
-export declare function waitForWindowMessage<T>(targetWindow: Window, timeout?: number): Promise<T>;

package/dist/core/cache/cooldown-cache.d.ts

@@ -1,31 +0,0 @@
-import type { CooldownCacheConfig } from './types';
-/**
- * Creates a cooldown-based cache that prevents rapid repeated calls.
- * Unlike TTL cache, this always fetches fresh data but enforces a minimum
- * time between requests. Cooldown can be configured both at creation time
- * (default) and at runtime (per-call).
- *
- * @param defaultCooldownMs - Default minimum milliseconds between requests
- * @returns Cache instance with get and clear methods
- *
- * @example
- * ```typescript
- * const cache = createCooldownCache<LevelProgress>(5000) // Default: 5 second cooldown
- *
- * // Use default cooldown
- * const progress1 = await cache.get('user-progress', () => fetchProgress())
- *
- * // Override with custom cooldown for this call
- * const progress2 = await cache.get('user-progress', () => fetchProgress(), { cooldown: 1000 })
- *
- * // Force refresh bypassing cooldown
- * const fresh = await cache.get('user-progress', () => fetchProgress(), { force: true })
- *
- * // Disable cooldown for this call (cooldown: 0)
- * const immediate = await cache.get('user-progress', () => fetchProgress(), { cooldown: 0 })
- * ```
- */
-export declare function createCooldownCache<T>(defaultCooldownMs: number): {
-    get: (key: string, loader: () => Promise<T>, config?: CooldownCacheConfig) => Promise<T>;
-    clear: (key?: string) => void;
-};

package/dist/core/cache/index.d.ts

@@ -1,14 +0,0 @@
-/**
- * Cache utilities for the Playcademy SDK
- *
- * Available cache types:
- * - TTL Cache: Time-based expiration with management capabilities (e.g., 60 seconds for games list)
- * - Cooldown Cache: Minimum time between requests (e.g., 5 seconds for level progress)
- * - Singleton Cache: Single value, no keys (e.g., THE credits item ID)
- * - Permanent Cache: Multiple values with keys, never expire (e.g., item ID resolutions)
- */
-export { createTTLCache } from './ttl-cache';
-export type { TTLCacheOptions } from './ttl-cache';
-export { createCooldownCache } from './cooldown-cache';
-export { createSingletonCache } from './singleton-cache';
-export { createPermanentCache } from './permanent-cache';

package/dist/core/cache/permanent-cache.d.ts

@@ -1,39 +0,0 @@
-/**
- * Creates a permanent KV cache that stores multiple values indefinitely.
- * Values are cached by key until explicitly cleared.
- *
- * This is a key-value cache - it can store many different values accessed by keys.
- * If you only need to cache ONE value total, use SingletonCache instead.
- *
- * @param keyPrefix - Optional prefix for cache keys
- * @returns Cache instance with get, clear, has, and size methods
- *
- * @example
- * ```typescript
- * // Perfect for caching multiple ID resolutions
- * const itemIdCache = createPermanentCache<string>('items')
- *
- * // Cache different item ID resolutions with different keys
- * const swordId = await itemIdCache.get('sword-of-power', async () => {
- *   const item = await resolveItem('sword-of-power')
- *   return item.id
- * })
- *
- * const potionId = await itemIdCache.get('health-potion', async () => {
- *   const item = await resolveItem('health-potion')
- *   return item.id
- * })
- *
- * // Check if specific item is cached
- * if (itemIdCache.has('sword-of-power')) {
- *   // Use cached value
- * }
- * ```
- */
-export declare function createPermanentCache<T>(keyPrefix?: string): {
-    get: (key: string, loader: () => Promise<T>) => Promise<T>;
-    clear: (key?: string) => void;
-    has: (key: string) => boolean;
-    size: () => number;
-    keys: () => string[];
-};

package/dist/core/cache/singleton-cache.d.ts

@@ -1,29 +0,0 @@
-/**
- * Creates a singleton cache that stores a SINGLE value permanently.
- * Once set, the value is cached for the lifetime of the application.
- *
- * This is NOT a key-value cache - it stores exactly one value total.
- * If you need to cache multiple values with keys, use PermanentCache instead.
- *
- * @returns Cache instance with get and clear methods
- *
- * @example
- * ```typescript
- * // Perfect for single values that are resolved once
- * const creditsIdCache = createSingletonCache<string>()
- *
- * // First call fetches and caches THE value
- * const id = await creditsIdCache.get(async () => {
- *   const item = await fetchCreditsItem()
- *   return item.id
- * })
- *
- * // Subsequent calls return THE cached value (no key needed)
- * const cachedId = await creditsIdCache.get(() => fetchCreditsItem())
- * ```
- */
-export declare function createSingletonCache<T>(): {
-    get: (loader: () => Promise<T>) => Promise<T>;
-    clear: () => void;
-    has: () => boolean;
-};

package/dist/core/cache/ttl-cache.d.ts

@@ -1,54 +0,0 @@
-import type { TTLCacheConfig } from './types';
-export interface TTLCacheOptions {
-    /** Default time-to-live in milliseconds */
-    ttl: number;
-    /** Optional key prefix for debugging */
-    keyPrefix?: string;
-    /** Optional callback when cache is cleared */
-    onClear?: () => void;
-}
-export interface CachedValue<T> {
-    value: T;
-    expiresAt: number;
-}
-/**
- * Creates a TTL (Time-To-Live) cache for async operations with management capabilities.
- * Caches results for a specified duration and allows force refresh.
- * TTL can be configured both at creation time (default) and at runtime (per-call).
- *
- * @param options - Cache configuration with default TTL
- * @returns Cache instance with get, clear, size, prune, getKeys, and has methods
- *
- * @example
- * ```typescript
- * const cache = createTTLCache<Game[]>({
- *   ttl: 60 * 1000, // Default: 60 seconds
- *   keyPrefix: 'games.list'
- * })
- *
- * // Use default TTL
- * const games = await cache.get('all', () => fetchGames())
- *
- * // Override with custom TTL for this call
- * const shortLived = await cache.get('all', () => fetchGames(), { ttl: 5000 })
- *
- * // Force refresh regardless of TTL
- * const fresh = await cache.get('all', () => fetchGames(), { force: true })
- *
- * // Disable caching for this call (ttl: 0)
- * const uncached = await cache.get('all', () => fetchGames(), { ttl: 0 })
- *
- * // Inspect cache
- * const keys = cache.getKeys() // ['all']
- * const hasAll = cache.has('all') // true
- * cache.clear('all') // Clear specific key
- * ```
- */
-export declare function createTTLCache<T>(options: TTLCacheOptions): {
-    get: (key: string, loader: () => Promise<T>, config?: TTLCacheConfig) => Promise<T>;
-    clear: (key?: string) => void;
-    size: () => number;
-    prune: () => void;
-    getKeys: () => string[];
-    has: (key: string) => boolean;
-};

package/dist/core/cache/types.d.ts

@@ -1,23 +0,0 @@
-/**
- * Cache configuration types for runtime customization
- */
-/**
- * Runtime configuration for TTL cache behavior
- */
-export interface TTLCacheConfig {
-    /** Time-to-live in milliseconds. Set to 0 to disable caching for this call. */
-    ttl?: number;
-    /** Force refresh, bypassing cache */
-    force?: boolean;
-    /** Skip cache and fetch fresh data (alias for force) */
-    skipCache?: boolean;
-}
-/**
- * Runtime configuration for cooldown cache behavior
- */
-export interface CooldownCacheConfig {
-    /** Cooldown period in milliseconds. Set to 0 to disable cooldown for this call. */
-    cooldown?: number;
-    /** Force refresh, bypassing cooldown */
-    force?: boolean;
-}