@playcademy/sdk 0.0.1-beta.21 → 0.0.1-beta.23

package/README.md

@@ -136,11 +136,17 @@ All methods returning data are strongly typed.
     - `me()`: Fetch current user details.
     - **`inventory`**:
         - `get()`: Get player inventory.
-        - `add(itemId, qty)`: Add item to player inventory.
-        - `spend(itemId, qty)`: Spend item from player inventory.
+        - `add(identifier, qty)`: Add item to player inventory (accepts UUID or internal name).
+        - `remove(identifier, qty)`: Remove item from player inventory (accepts UUID or internal name).
+        - `quantity(identifier)`: Get current quantity of an item (accepts UUID or internal name).
+        - `has(identifier, minQuantity?)`: Check if user has enough of an item (accepts UUID or internal name).
     - **`progress`**: Manages persistent progress data for a game (e.g., levels completed, scores, collectibles).
         - `get(gameId?)`: Get the entire progress state for a game. `gameId` is optional and defaults to the client's current game context.
         - `update(data, gameId?)`: Update the progress state for a game. `gameId` is optional. The `data` object can be structured to hold progress for various internal nodes or aspects of the game.
+- **`credits`**: Convenient methods for working with Playcademy Credits (primary platform currency).
+    - `balance()`: Get current credits balance.
+    - `add(amount)`: Add credits to user.
+    - `spend(amount)`: Spend credits from user.
 - **`games`**: Manages game sessions and transient game state.
     - `fetch(gameIdOrSlug)`: Fetch game details with manifest.
     - `list()`: List all games.
@@ -162,6 +168,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

@@ -118,8 +118,10 @@ export declare class PlaycademyClient {
         }>;
         inventory: {
             get: () => Promise<import("@playcademy/types").InventoryItemWithItem[]>;
-            add: (itemId: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
-            spend: (itemId: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
+            add: (identifier: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
+            remove: (identifier: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
+            quantity: (identifier: string) => Promise<number>;
+            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
         };
     };
     /** Developer tools (auth, games, keys management) */
@@ -311,10 +313,31 @@ 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;
+            totalXP: 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>;
     };
+    /** Credits methods (credits management) */
+    credits: {
+        balance: () => Promise<number>;
+        add: (amount: number) => Promise<number>;
+        spend: (amount: number) => Promise<number>;
+    };
     /** Auto-initializes a PlaycademyClient with context from the environment */
     static init: typeof init;
     /** Authenticates a user with email and password */

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

@@ -0,0 +1,51 @@
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the credits namespace for the PlaycademyClient.
+ * Provides convenient methods for working with Playcademy Credits (the primary platform currency).
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Credits namespace with balance and transaction methods
+ */
+export declare function createCreditsNamespace(client: PlaycademyClient): {
+    /**
+     * Gets the current balance of Playcademy Credits for the authenticated user.
+     * This is a convenience method that finds the primary currency in the user's inventory.
+     *
+     * @returns Promise resolving to the current credits balance
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.credits.balance()
+     * console.log('Current credits:', balance)
+     * ```
+     */
+    balance: () => Promise<number>;
+    /**
+     * Adds Playcademy Credits to the user's inventory.
+     * This is a convenience method that automatically finds the credits item ID.
+     *
+     * @param amount - The amount of credits to add (must be positive)
+     * @returns Promise resolving to the new total balance
+     *
+     * @example
+     * ```typescript
+     * const newBalance = await client.credits.add(100)
+     * console.log('New balance after adding 100 credits:', newBalance)
+     * ```
+     */
+    add: (amount: number) => Promise<number>;
+    /**
+     * Spends (removes) Playcademy Credits from the user's inventory.
+     * This is a convenience method that automatically finds the credits item ID.
+     *
+     * @param amount - The amount of credits to spend (must be positive)
+     * @returns Promise resolving to the new total balance
+     *
+     * @example
+     * ```typescript
+     * const newBalance = await client.credits.spend(50)
+     * console.log('New balance after spending 50 credits:', newBalance)
+     * ```
+     */
+    spend: (amount: number) => Promise<number>;
+};

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

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

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.totalXP)
+     * ```
+     */
+    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;
+        totalXP: 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/core/namespaces/users.d.ts

@@ -52,33 +52,80 @@ export declare function createUsersNamespace(client: PlaycademyClient): {
         get: () => Promise<InventoryItemWithItem[]>;
         /**
          * Adds items to the user's inventory.
+         * Accepts either an item UUID or internal name.
          * Emits an 'inventoryChange' event when successful.
          *
-         * @param itemId - The ID of the item to add
+         * @param identifier - The item UUID or internal name
          * @param qty - The quantity to add (must be positive)
          * @returns Promise resolving to mutation response with new total
          *
          * @example
          * ```typescript
-         * const result = await client.users.inventory.add('gold-coin', 100)
+         * // Using internal name
+         * const result = await client.users.inventory.add('GOLD_COIN', 100)
+         *
+         * // Using UUID
+         * const result = await client.users.inventory.add('550e8400-e29b-41d4-a716-446655440000', 100)
+         *
          * console.log('New total:', result.newTotal)
          * ```
          */
-        add: (itemId: string, qty: number) => Promise<InventoryMutationResponse>;
+        add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
         /**
-         * Spends (removes) items from the user's inventory.
+         * Removes items from the user's inventory.
+         * Accepts either an item UUID or internal name.
          * Emits an 'inventoryChange' event when successful.
          *
-         * @param itemId - The ID of the item to spend
-         * @param qty - The quantity to spend (must be positive)
+         * @param identifier - The item UUID or internal name
+         * @param qty - The quantity to remove (must be positive)
          * @returns Promise resolving to mutation response with new total
          *
          * @example
          * ```typescript
-         * const result = await client.users.inventory.spend('health-potion', 1)
-         * console.log('Remaining potions:', result.newTotal)
+         * // Using internal name
+         * const result = await client.users.inventory.remove('HEALTH_POTION', 1)
+         *
+         * // Using UUID
+         * const result = await client.users.inventory.remove('uuid-456-789', 1)
+         *
+         * console.log('Remaining:', result.newTotal)
+         * ```
+         */
+        remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+        /**
+         * Gets the current quantity of an item.
+         * Accepts either an item UUID or internal name.
+         *
+         * @param identifier - The item UUID or internal name
+         * @returns Promise resolving to the current quantity (0 if not owned)
+         *
+         * @example
+         * ```typescript
+         * const qty = await client.users.inventory.quantity('HEALTH_POTION')
+         * const qty2 = await client.users.inventory.quantity('uuid-123-456')
+         * console.log('Health potions:', qty)
+         * ```
+         */
+        quantity: (identifier: string) => Promise<number>;
+        /**
+         * Checks if the user has at least the specified quantity of an item.
+         * Accepts either an item UUID or internal name.
+         *
+         * @param identifier - The item UUID or internal name
+         * @param minQuantity - Minimum quantity required (defaults to 1)
+         * @returns Promise resolving to true if user has enough of the item
+         *
+         * @example
+         * ```typescript
+         * const hasKey = await client.users.inventory.has('DUNGEON_KEY')
+         * const hasEnoughGold = await client.users.inventory.has('GOLD_COIN', 100)
+         * const hasPotion = await client.users.inventory.has('uuid-123-456', 5)
+         *
+         * if (hasKey && hasEnoughGold) {
+         *   console.log('Can enter premium dungeon!')
+         * }
          * ```
          */
-        spend: (itemId: string, qty: number) => Promise<InventoryMutationResponse>;
+        has: (identifier: string, minQuantity?: number) => Promise<boolean>;
     };
 };

package/dist/index.js

@@ -258,13 +258,29 @@ var init_games = __esm(() => {
 
 // src/core/namespaces/users.ts
 function createUsersNamespace(client) {
+  const itemIdCache = new Map;
+  const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  const resolveItemId = async (identifier) => {
+    if (UUID_REGEX.test(identifier))
+      return identifier;
+    if (itemIdCache.has(identifier))
+      return itemIdCache.get(identifier);
+    const inventory = await client.users.inventory.get();
+    const item = inventory.find((inv) => inv.item?.internalName === identifier);
+    if (!item) {
+      throw new Error(`Item with internal name '${identifier}' not found in inventory`);
+    }
+    itemIdCache.set(identifier, item.item.id);
+    return item.item.id;
+  };
   return {
     me: async () => {
       return client["request"]("/users/me", "GET");
     },
     inventory: {
       get: async () => client["request"](`/inventory`, "GET"),
-      add: async (itemId, qty) => {
+      add: async (identifier, qty) => {
+        const itemId = await resolveItemId(identifier);
         const res = await client["request"](`/inventory/add`, "POST", { itemId, qty });
         client["emit"]("inventoryChange", {
           itemId,
@@ -273,7 +289,8 @@ function createUsersNamespace(client) {
         });
         return res;
       },
-      spend: async (itemId, qty) => {
+      remove: async (identifier, qty) => {
+        const itemId = await resolveItemId(identifier);
         const res = await client["request"](`/inventory/spend`, "POST", { itemId, qty });
         client["emit"]("inventoryChange", {
           itemId,
@@ -281,6 +298,19 @@ function createUsersNamespace(client) {
           newTotal: res.newTotal
         });
         return res;
+      },
+      quantity: async (identifier) => {
+        const inventory = await client.users.inventory.get();
+        if (UUID_REGEX.test(identifier)) {
+          const item2 = inventory.find((inv) => inv.item?.id === identifier);
+          return item2?.quantity ?? 0;
+        }
+        const item = inventory.find((inv) => inv.item?.internalName === identifier);
+        return item?.quantity ?? 0;
+      },
+      has: async (identifier, minQuantity = 1) => {
+        const qty = await client.users.inventory.quantity(identifier);
+        return qty >= minQuantity;
       }
     }
   };
@@ -368,10 +398,127 @@ 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,
+        totalXP: result.totalXP,
+        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");
+      }
+    }
+  };
+}
+
+// ../data/src/constants.ts
+var ITEM_INTERNAL_NAMES, CURRENCIES, BADGES;
+var init_constants = __esm(() => {
+  ITEM_INTERNAL_NAMES = {
+    PLAYCADEMY_CREDITS: "PLAYCADEMY_CREDITS",
+    PLAYCADEMY_XP: "PLAYCADEMY_XP",
+    FOUNDING_MEMBER_BADGE: "FOUNDING_MEMBER_BADGE",
+    EARLY_ADOPTER_BADGE: "EARLY_ADOPTER_BADGE",
+    FIRST_GAME_BADGE: "FIRST_GAME_BADGE",
+    COMMON_SWORD: "COMMON_SWORD",
+    SMALL_HEALTH_POTION: "SMALL_HEALTH_POTION",
+    SMALL_BACKPACK: "SMALL_BACKPACK"
+  };
+  CURRENCIES = {
+    PRIMARY: ITEM_INTERNAL_NAMES.PLAYCADEMY_CREDITS,
+    XP: ITEM_INTERNAL_NAMES.PLAYCADEMY_XP
+  };
+  BADGES = {
+    FOUNDING_MEMBER: ITEM_INTERNAL_NAMES.FOUNDING_MEMBER_BADGE,
+    EARLY_ADOPTER: ITEM_INTERNAL_NAMES.EARLY_ADOPTER_BADGE,
+    FIRST_GAME: ITEM_INTERNAL_NAMES.FIRST_GAME_BADGE
+  };
+});
+
+// src/core/namespaces/credits.ts
+function createCreditsNamespace(client) {
+  let cachedCreditsItemId = null;
+  const getCreditsItemId = async () => {
+    if (cachedCreditsItemId) {
+      return cachedCreditsItemId;
+    }
+    const items = await client.admin.items.list();
+    const creditsItem = items.find((item) => item.internalName === CURRENCIES.PRIMARY);
+    if (!creditsItem) {
+      throw new Error("Playcademy Credits item not found in catalog");
+    }
+    cachedCreditsItemId = creditsItem.id;
+    return creditsItem.id;
+  };
+  return {
+    balance: async () => {
+      const inventory = await client.users.inventory.get();
+      const creditsItem = inventory.find((item) => item.item?.internalName === CURRENCIES.PRIMARY);
+      return creditsItem?.quantity ?? 0;
+    },
+    add: async (amount) => {
+      if (amount <= 0) {
+        throw new Error("Amount must be positive");
+      }
+      const creditsItemId = await getCreditsItemId();
+      const result = await client.users.inventory.add(creditsItemId, amount);
+      client["emit"]("inventoryChange", {
+        itemId: creditsItemId,
+        delta: amount,
+        newTotal: result.newTotal
+      });
+      return result.newTotal;
+    },
+    spend: async (amount) => {
+      if (amount <= 0) {
+        throw new Error("Amount must be positive");
+      }
+      const creditsItemId = await getCreditsItemId();
+      const result = await client.users.inventory.remove(creditsItemId, amount);
+      client["emit"]("inventoryChange", {
+        itemId: creditsItemId,
+        delta: -amount,
+        newTotal: result.newTotal
+      });
+      return result.newTotal;
+    }
+  };
+}
+var init_credits = __esm(() => {
+  init_constants();
+});
+
 // src/core/namespaces/index.ts
 var init_namespaces = __esm(() => {
   init_runtime();
   init_games();
+  init_credits();
 });
 
 // src/core/static/init.ts
@@ -568,7 +715,9 @@ var init_client = __esm(() => {
     maps = createMapsNamespace(this);
     admin = createAdminNamespace(this);
     shop = createShopNamespace(this);
+    levels = createLevelsNamespace(this);
     telemetry = createTelemetryNamespace(this);
+    credits = createCreditsNamespace(this);
     static init = init;
     static login = login;
   };

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-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 { ITEM_INTERNAL_NAMES, CURRENCIES, BADGES, } from '@playcademy/data/constants';
 export interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -13,6 +14,16 @@ export interface ClientEvents {
         delta: number;
         newTotal: number;
     };
+    levelUp: {
+        oldLevel: number;
+        newLevel: number;
+        creditsAwarded: number;
+    };
+    xpGained: {
+        amount: number;
+        totalXP: number;
+        leveledUp: boolean;
+    };
 }
 export type GameContextPayload = {
     token: string;
@@ -68,4 +79,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/dist/types.js

@@ -0,0 +1,43 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// ../data/src/constants.ts
+var ITEM_INTERNAL_NAMES, CURRENCIES, BADGES;
+var init_constants = __esm(() => {
+  ITEM_INTERNAL_NAMES = {
+    PLAYCADEMY_CREDITS: "PLAYCADEMY_CREDITS",
+    PLAYCADEMY_XP: "PLAYCADEMY_XP",
+    FOUNDING_MEMBER_BADGE: "FOUNDING_MEMBER_BADGE",
+    EARLY_ADOPTER_BADGE: "EARLY_ADOPTER_BADGE",
+    FIRST_GAME_BADGE: "FIRST_GAME_BADGE",
+    COMMON_SWORD: "COMMON_SWORD",
+    SMALL_HEALTH_POTION: "SMALL_HEALTH_POTION",
+    SMALL_BACKPACK: "SMALL_BACKPACK"
+  };
+  CURRENCIES = {
+    PRIMARY: ITEM_INTERNAL_NAMES.PLAYCADEMY_CREDITS,
+    XP: ITEM_INTERNAL_NAMES.PLAYCADEMY_XP
+  };
+  BADGES = {
+    FOUNDING_MEMBER: ITEM_INTERNAL_NAMES.FOUNDING_MEMBER_BADGE,
+    EARLY_ADOPTER: ITEM_INTERNAL_NAMES.EARLY_ADOPTER_BADGE,
+    FIRST_GAME: ITEM_INTERNAL_NAMES.FIRST_GAME_BADGE
+  };
+});
+
+// src/types.ts
+init_constants();
+export {
+  ITEM_INTERNAL_NAMES,
+  CURRENCIES,
+  BADGES
+};

package/package.json

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