@playcademy/sdk 0.0.1-beta.8 → 0.0.1

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,115 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+/**
+ * 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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,39 @@
+/**
+ * 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

@@ -0,0 +1,29 @@
+/**
+ * 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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,23 @@
+/**
+ * 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;
+}