@playcademy/sdk 0.0.1-beta.20 → 0.0.1-beta.22

package/README.md

@@ -162,6 +162,13 @@ All methods returning data are strongly typed.
 - **`admin.shopListings`**: CRUD operations for shop listings.
 - **`shop`**: Player-facing shop operations.
     - `view()`: Get shop items and currency information.
+- **`levels`**: Player level and experience point management.
+    - `get()`: Get current user level information.
+    - `progress()`: Get level progress with XP to next level.
+    - `addXP(amount)`: Add XP to user.
+    - **`config`**:
+        - `list()`: Get all level configurations (full XP curve).
+        - `get(level)`: Get configuration for a specific level.
 - **`telemetry`**: Push metrics.
 
 ## Contributing

package/dist/core/client.d.ts

@@ -311,6 +311,21 @@ export declare class PlaycademyClient {
     shop: {
         view: () => Promise<import("..").ShopViewResponse>;
     };
+    /** Level methods (levels) */
+    levels: {
+        get: () => Promise<import("@playcademy/types").UserLevel>;
+        progress: () => Promise<{
+            level: number;
+            currentXp: number;
+            xpToNextLevel: number;
+            totalXpEarned: number;
+        }>;
+        addXP: (amount: number) => Promise<import("@playcademy/types").XPAddResult>;
+        config: {
+            list: () => Promise<import("@playcademy/types").LevelConfig[]>;
+            get: (level: number) => Promise<import("@playcademy/types").LevelConfig | null>;
+        };
+    };
     /** Telemetry methods (pushMetrics) */
     telemetry: {
         pushMetrics: (metrics: Record<string, number>) => Promise<void>;

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

@@ -7,3 +7,4 @@ export { createMapsNamespace } from './maps';
 export { createAdminNamespace } from './admin';
 export { createShopNamespace } from './shop';
 export { createTelemetryNamespace } from './telemetry';
+export { createLevelsNamespace } from './levels';

package/dist/core/namespaces/levels.d.ts

@@ -0,0 +1,93 @@
+import type { UserLevel, LevelConfig, XPAddResult } from '../../types';
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the levels namespace for the PlaycademyClient.
+ * Provides methods for managing user levels and experience points.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Levels namespace with level and XP methods
+ */
+export declare function createLevelsNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves the current user's level information.
+     *
+     * @returns Promise resolving to user level data
+     *
+     * @example
+     * ```typescript
+     * const userLevel = await client.levels.get()
+     * console.log('Current level:', userLevel.currentLevel)
+     * console.log('Current XP:', userLevel.currentXp)
+     * console.log('Total XP earned:', userLevel.totalXpEarned)
+     * ```
+     */
+    get: () => Promise<UserLevel>;
+    /**
+     * Retrieves the current user's level progress information.
+     *
+     * @returns Promise resolving to level progress data
+     *
+     * @example
+     * ```typescript
+     * const progress = await client.levels.progress()
+     * console.log('Level:', progress.level)
+     * console.log('XP to next level:', progress.xpToNextLevel)
+     * ```
+     */
+    progress: () => Promise<{
+        level: number;
+        currentXp: number;
+        xpToNextLevel: number;
+        totalXpEarned: number;
+    }>;
+    /**
+     * Adds XP to the current user.
+     * Emits 'xpGained' and 'levelUp' events when successful.
+     *
+     * @param amount - The amount of XP to add (must be positive)
+     * @returns Promise resolving to XP addition result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.levels.addXP(100)
+     * console.log('New level:', result.newLevel)
+     * console.log('Leveled up:', result.leveledUp)
+     * console.log('Credits awarded:', result.creditsAwarded)
+     * ```
+     */
+    addXP: (amount: number) => Promise<XPAddResult>;
+    /**
+     * Configuration methods for level system.
+     */
+    config: {
+        /**
+         * Retrieves all level configurations (full XP curve).
+         *
+         * @returns Promise resolving to array of level configurations
+         *
+         * @example
+         * ```typescript
+         * const configs = await client.levels.config.list()
+         * configs.forEach(config => {
+         *   console.log(`Level ${config.level}: ${config.xpRequired} XP, ${config.creditsReward} credits`)
+         * })
+         * ```
+         */
+        list: () => Promise<LevelConfig[]>;
+        /**
+         * Retrieves configuration for a specific level.
+         *
+         * @param level - The level number to get configuration for
+         * @returns Promise resolving to level configuration or null if not found
+         *
+         * @example
+         * ```typescript
+         * const config = await client.levels.config.get(10)
+         * if (config) {
+         *   console.log(`Level 10 requires ${config.xpRequired} XP`)
+         * }
+         * ```
+         */
+        get: (level: number) => Promise<LevelConfig | null>;
+    };
+};

package/dist/index.js

@@ -167,10 +167,8 @@ class PlaycademyMessaging {
     };
   }
   sendViaPostMessage(type, payload, target = window.parent, origin = "*") {
-    let messageData = { type };
-    if (payload !== undefined && typeof payload === "object" && payload !== null) {
-      messageData = { ...messageData, ...payload };
-    } else if (payload !== undefined) {
+    const messageData = { type };
+    if (payload !== undefined) {
       messageData.payload = payload;
     }
     target.postMessage(messageData, origin);
@@ -370,6 +368,45 @@ function createTelemetryNamespace(client) {
   };
 }
 
+// src/core/namespaces/levels.ts
+function createLevelsNamespace(client) {
+  return {
+    get: async () => {
+      return client["request"]("/users/level", "GET");
+    },
+    progress: async () => {
+      return client["request"]("/users/level/progress", "GET");
+    },
+    addXP: async (amount) => {
+      const currentUserLevel = await client["request"]("/users/level", "GET");
+      const oldLevel = currentUserLevel.currentLevel;
+      const payload = { amount };
+      const result = await client["request"]("/users/xp/add", "POST", payload);
+      client["emit"]("xpGained", {
+        amount,
+        totalXpEarned: result.totalXpEarned,
+        leveledUp: result.leveledUp
+      });
+      if (result.leveledUp) {
+        client["emit"]("levelUp", {
+          oldLevel,
+          newLevel: result.newLevel,
+          creditsAwarded: result.creditsAwarded
+        });
+      }
+      return result;
+    },
+    config: {
+      list: async () => {
+        return client["request"]("/levels/config", "GET");
+      },
+      get: async (level) => {
+        return client["request"](`/levels/config/${level}`, "GET");
+      }
+    }
+  };
+}
+
 // src/core/namespaces/index.ts
 var init_namespaces = __esm(() => {
   init_runtime();
@@ -570,6 +607,7 @@ var init_client = __esm(() => {
     maps = createMapsNamespace(this);
     admin = createAdminNamespace(this);
     shop = createShopNamespace(this);
+    levels = createLevelsNamespace(this);
     telemetry = createTelemetryNamespace(this);
     static init = init;
     static login = login;

package/dist/messaging.d.ts

@@ -377,11 +377,10 @@ declare class PlaycademyMessaging {
      * **Message Structure**:
      * The method creates a message object with the following structure:
      * - `type`: The message event type (e.g., 'PLAYCADEMY_READY')
-     * - Payload data: Either spread into the object or in a `payload` property
+     * - `payload`: The message data (if any)
      *
      * **Payload Handling**:
-     * - **Object payloads**: Spread directly into the message (e.g., { type, token, exp })
-     * - **Primitive payloads**: Wrapped in a `payload` property (e.g., { type, payload: true })
+     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
      * - **Undefined payloads**: Only the type is sent (e.g., { type })
      *
      * **Security**:
@@ -402,7 +401,7 @@ declare class PlaycademyMessaging {
      *
      * // Send telemetry data (object payload)
      * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
-     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', fps: 60, mem: 128 }
+     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', payload: { fps: 60, mem: 128 } }
      *
      * // Send overlay state (primitive payload)
      * sendViaPostMessage(MessageEvents.OVERLAY, true)

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { User, InventoryItemWithItem, Game, DeveloperKey, DeveloperStatusResponse, MapElement, Item, InsertItem, ManifestV1, UpdateItem, Currency, InsertCurrency, UpdateCurrency, ShopListing, InsertShopListing, UpdateShopListing } from '@playcademy/types';
+import type { User, InventoryItemWithItem, Game, DeveloperKey, DeveloperStatusResponse, MapElement, Item, InsertItem, ManifestV1, UpdateItem, Currency, InsertCurrency, UpdateCurrency, ShopListing, InsertShopListing, UpdateShopListing, UserLevel, LevelConfig, XPAddResult, UserLevelWithConfig, XPActionInput } from '@playcademy/types';
 export interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -13,6 +13,16 @@ export interface ClientEvents {
         delta: number;
         newTotal: number;
     };
+    levelUp: {
+        oldLevel: number;
+        newLevel: number;
+        creditsAwarded: number;
+    };
+    xpGained: {
+        amount: number;
+        totalXpEarned: number;
+        leveledUp: boolean;
+    };
 }
 export type GameContextPayload = {
     token: string;
@@ -68,4 +78,4 @@ export interface ShopViewResponse {
     shopItems: ShopDisplayItem[];
     currencies: CurrencyInfo[];
 }
-export type { User, InventoryItemWithItem, Game, ManifestV1, DeveloperKey, DeveloperStatusResponse, MapElement, Item, InsertItem, UpdateItem, Currency, InsertCurrency, UpdateCurrency, ShopListing, InsertShopListing, UpdateShopListing, };
+export type { User, InventoryItemWithItem, Game, ManifestV1, DeveloperKey, DeveloperStatusResponse, MapElement, Item, InsertItem, UpdateItem, Currency, InsertCurrency, UpdateCurrency, ShopListing, InsertShopListing, UpdateShopListing, UserLevel, LevelConfig, XPAddResult, UserLevelWithConfig, XPActionInput, };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@playcademy/sdk",
     "type": "module",
-    "version": "0.0.1-beta.20",
+    "version": "0.0.1-beta.22",
     "exports": {
         ".": {
             "import": "./dist/index.js",