@playcademy/sdk 0.0.1-beta.22 → 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.

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) */
@@ -318,7 +320,7 @@ export declare class PlaycademyClient {
             level: number;
             currentXp: number;
             xpToNextLevel: number;
-            totalXpEarned: number;
+            totalXP: number;
         }>;
         addXP: (amount: number) => Promise<import("@playcademy/types").XPAddResult>;
         config: {
@@ -330,6 +332,12 @@ export declare class PlaycademyClient {
     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

@@ -8,3 +8,4 @@ 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

@@ -18,7 +18,7 @@ export declare function createLevelsNamespace(client: PlaycademyClient): {
      * 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)
+     * console.log('Total XP earned:', userLevel.totalXP)
      * ```
      */
     get: () => Promise<UserLevel>;
@@ -38,7 +38,7 @@ export declare function createLevelsNamespace(client: PlaycademyClient): {
         level: number;
         currentXp: number;
         xpToNextLevel: number;
-        totalXpEarned: number;
+        totalXP: number;
     }>;
     /**
      * Adds XP to the current user.

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;
       }
     }
   };
@@ -384,7 +414,7 @@ function createLevelsNamespace(client) {
       const result = await client["request"]("/users/xp/add", "POST", payload);
       client["emit"]("xpGained", {
         amount,
-        totalXpEarned: result.totalXpEarned,
+        totalXP: result.totalXP,
         leveledUp: result.leveledUp
       });
       if (result.leveledUp) {
@@ -407,10 +437,88 @@ function createLevelsNamespace(client) {
   };
 }
 
+// ../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
@@ -609,6 +717,7 @@ var init_client = __esm(() => {
     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, 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;
@@ -20,7 +21,7 @@ export interface ClientEvents {
     };
     xpGained: {
         amount: number;
-        totalXpEarned: number;
+        totalXP: number;
         leveledUp: boolean;
     };
 }

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.22",
+    "version": "0.0.1-beta.23",
     "exports": {
         ".": {
             "import": "./dist/index.js",