@spawnco/sdk-types 0.0.21 → 0.0.23

package/dist/index.d.mts

@@ -41,11 +41,11 @@ interface SpawnClientSDK__V1<TConfig = any> {
     inventory: {
         currencies: {
             get(): Promise<Record<string, number>>;
-            on(event: 'update', handler: (balances: Record<string, number>) => void): void;
+            on(event: 'update', handler: (balances: Record<string, number>) => void): () => void;
         };
         items: {
-            list(): Promise<Item[]>;
-            on(event: 'update', handler: (items: Item[]) => void): void;
+            list(): Promise<InventoryItem[]>;
+            on(event: 'update', handler: (items: InventoryItem[]) => void): () => void;
         };
     };
     storage: {
@@ -58,6 +58,23 @@ interface SpawnClientSDK__V1<TConfig = any> {
     analytics: {
         track(event: string, data: Record<string, any>): Promise<void>;
     };
+    leaderboard: {
+        submit(leaderboardId: string, score: number): Promise<{
+            rank: number;
+            improved: boolean;
+        }>;
+        top(leaderboardId: string, options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            limit?: number;
+        }): Promise<LeaderboardEntry[]>;
+        around(leaderboardId: string, options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            range?: number;
+        }): Promise<{
+            entries: LeaderboardEntry[];
+            myRank: number;
+        }>;
+    };
 }
 interface SpawnServerSDK__V1<TConfig = any> {
     user: {
@@ -87,16 +104,44 @@ interface SpawnServerSDK__V1<TConfig = any> {
     };
     inventory: {
         currencies: {
-            credit(userId: string, currency: string, amount: number): Promise<void>;
-            debit(userId: string, currency: string, amount: number): Promise<boolean>;
+            credit(userId: string, currency: string, amount: number, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                newBalance: number;
+            }>;
+            debit(userId: string, currency: string, amount: number, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                success: boolean;
+                newBalance?: number;
+            }>;
             exchange(userId: string, tx: {
                 debit: Record<string, number>;
                 credit: Record<string, number>;
-            }): Promise<boolean>;
+            }, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                success: boolean;
+                balances?: Record<string, number>;
+            }>;
+            get(userId: string): Promise<Record<string, number>>;
         };
         items: {
-            grant(userId: string, items: Item[]): Promise<void>;
-            consume(userId: string, itemId: string): Promise<boolean>;
+            grant(userId: string, items: Array<{
+                itemId: string;
+                data?: any;
+            }>, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<string[]>;
+            consume(userId: string, instanceId: string, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<boolean>;
+            list(userId: string): Promise<InventoryItem[]>;
         };
     };
     storage: {
@@ -116,6 +161,13 @@ interface SpawnServerSDK__V1<TConfig = any> {
             delete(key: string): Promise<void>;
         };
     };
+    leaderboard: {
+        submit(userId: string, leaderboardId: string, score: number): Promise<void>;
+        getMultiple(leaderboardIds: string[], options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            limit?: number;
+        }): Promise<Record<string, LeaderboardEntry[]>>;
+    };
 }
 interface TokenPayload {
     sub: string;
@@ -154,7 +206,20 @@ interface Item {
     id: string;
     data?: Record<string, any>;
 }
+interface InventoryItem {
+    id: string;
+    itemId: string;
+    data?: any;
+}
+interface LeaderboardEntry {
+    rank: number;
+    username: string;
+    avatarUrl?: string;
+    score: number;
+    isMe?: boolean;
+    timestamp: number;
+}
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy' | 'inventory'>;
 type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'inventory' | 'room'>;
 
-export type { Item, Room, RoomInfo, RoomVisibility, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, User };
+export type { InventoryItem, Item, LeaderboardEntry, Room, RoomInfo, RoomVisibility, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, User };

package/dist/index.d.ts

@@ -41,11 +41,11 @@ interface SpawnClientSDK__V1<TConfig = any> {
     inventory: {
         currencies: {
             get(): Promise<Record<string, number>>;
-            on(event: 'update', handler: (balances: Record<string, number>) => void): void;
+            on(event: 'update', handler: (balances: Record<string, number>) => void): () => void;
         };
         items: {
-            list(): Promise<Item[]>;
-            on(event: 'update', handler: (items: Item[]) => void): void;
+            list(): Promise<InventoryItem[]>;
+            on(event: 'update', handler: (items: InventoryItem[]) => void): () => void;
         };
     };
     storage: {
@@ -58,6 +58,23 @@ interface SpawnClientSDK__V1<TConfig = any> {
     analytics: {
         track(event: string, data: Record<string, any>): Promise<void>;
     };
+    leaderboard: {
+        submit(leaderboardId: string, score: number): Promise<{
+            rank: number;
+            improved: boolean;
+        }>;
+        top(leaderboardId: string, options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            limit?: number;
+        }): Promise<LeaderboardEntry[]>;
+        around(leaderboardId: string, options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            range?: number;
+        }): Promise<{
+            entries: LeaderboardEntry[];
+            myRank: number;
+        }>;
+    };
 }
 interface SpawnServerSDK__V1<TConfig = any> {
     user: {
@@ -87,16 +104,44 @@ interface SpawnServerSDK__V1<TConfig = any> {
     };
     inventory: {
         currencies: {
-            credit(userId: string, currency: string, amount: number): Promise<void>;
-            debit(userId: string, currency: string, amount: number): Promise<boolean>;
+            credit(userId: string, currency: string, amount: number, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                newBalance: number;
+            }>;
+            debit(userId: string, currency: string, amount: number, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                success: boolean;
+                newBalance?: number;
+            }>;
             exchange(userId: string, tx: {
                 debit: Record<string, number>;
                 credit: Record<string, number>;
-            }): Promise<boolean>;
+            }, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<{
+                success: boolean;
+                balances?: Record<string, number>;
+            }>;
+            get(userId: string): Promise<Record<string, number>>;
         };
         items: {
-            grant(userId: string, items: Item[]): Promise<void>;
-            consume(userId: string, itemId: string): Promise<boolean>;
+            grant(userId: string, items: Array<{
+                itemId: string;
+                data?: any;
+            }>, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<string[]>;
+            consume(userId: string, instanceId: string, options?: {
+                idempotencyKey?: string;
+                reason?: string;
+            }): Promise<boolean>;
+            list(userId: string): Promise<InventoryItem[]>;
         };
     };
     storage: {
@@ -116,6 +161,13 @@ interface SpawnServerSDK__V1<TConfig = any> {
             delete(key: string): Promise<void>;
         };
     };
+    leaderboard: {
+        submit(userId: string, leaderboardId: string, score: number): Promise<void>;
+        getMultiple(leaderboardIds: string[], options?: {
+            period?: 'today' | 'week' | 'month' | 'all';
+            limit?: number;
+        }): Promise<Record<string, LeaderboardEntry[]>>;
+    };
 }
 interface TokenPayload {
     sub: string;
@@ -154,7 +206,20 @@ interface Item {
     id: string;
     data?: Record<string, any>;
 }
+interface InventoryItem {
+    id: string;
+    itemId: string;
+    data?: any;
+}
+interface LeaderboardEntry {
+    rank: number;
+    username: string;
+    avatarUrl?: string;
+    score: number;
+    isMe?: boolean;
+    timestamp: number;
+}
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy' | 'inventory'>;
 type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'inventory' | 'room'>;
 
-export type { Item, Room, RoomInfo, RoomVisibility, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, User };
+export type { InventoryItem, Item, LeaderboardEntry, Room, RoomInfo, RoomVisibility, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, User };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spawnco/sdk-types",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "TypeScript type definitions for Spawn SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/v1.ts

@@ -40,12 +40,12 @@ export interface SpawnClientSDK__V1<TConfig = any> {
   inventory: {
     currencies: {
       get(): Promise<Record<string, number>>;
-      on(event: 'update', handler: (balances: Record<string, number>) => void): void;
+      on(event: 'update', handler: (balances: Record<string, number>) => void): () => void;
     };
 
     items: {
-      list(): Promise<Item[]>;
-      on(event: 'update', handler: (items: Item[]) => void): void;
+      list(): Promise<InventoryItem[]>;
+      on(event: 'update', handler: (items: InventoryItem[]) => void): () => void;
     };
   };
 
@@ -60,6 +60,35 @@ export interface SpawnClientSDK__V1<TConfig = any> {
   analytics: {
     track(event: string, data: Record<string, any>): Promise<void>;
   };
+
+  leaderboard: {
+    submit(
+      leaderboardId: string,
+      score: number
+    ): Promise<{
+      rank: number;
+      improved: boolean;
+    }>;
+
+    top(
+      leaderboardId: string,
+      options?: {
+        period?: 'today' | 'week' | 'month' | 'all';
+        limit?: number;
+      }
+    ): Promise<LeaderboardEntry[]>;
+
+    around(
+      leaderboardId: string,
+      options?: {
+        period?: 'today' | 'week' | 'month' | 'all';
+        range?: number;
+      }
+    ): Promise<{
+      entries: LeaderboardEntry[];
+      myRank: number;
+    }>;
+  };
 }
 
 // Server SDK - available in Durable Objects
@@ -87,22 +116,50 @@ export interface SpawnServerSDK__V1<TConfig = any> {
   };
 
   inventory: {
-    // Game currencies only (not SBX)
     currencies: {
-      credit(userId: string, currency: string, amount: number): Promise<void>;
-      debit(userId: string, currency: string, amount: number): Promise<boolean>;
-      exchange(
-        userId: string,
-        tx: {
-          debit: Record<string, number>;
-          credit: Record<string, number>;
-        }
-      ): Promise<boolean>;
+      // Credit currency (creates if doesn't exist)
+      credit(userId: string, currency: string, amount: number, options?: {
+        idempotencyKey?: string;
+        reason?: string;
+      }): Promise<{ newBalance: number }>;
+      
+      // Debit currency (returns false if insufficient)
+      debit(userId: string, currency: string, amount: number, options?: {
+        idempotencyKey?: string;
+        reason?: string;
+      }): Promise<{ success: boolean; newBalance?: number }>;
+      
+      // Atomic multi-currency exchange
+      exchange(userId: string, tx: {
+        debit: Record<string, number>;
+        credit: Record<string, number>;
+      }, options?: {
+        idempotencyKey?: string;
+        reason?: string;
+      }): Promise<{ success: boolean; balances?: Record<string, number> }>;
+      
+      // Get user's balances
+      get(userId: string): Promise<Record<string, number>>;
     };
 
     items: {
-      grant(userId: string, items: Item[]): Promise<void>;
-      consume(userId: string, itemId: string): Promise<boolean>;
+      // Grant items to user (returns instance IDs)
+      grant(userId: string, items: Array<{
+        itemId: string;
+        data?: any;
+      }>, options?: {
+        idempotencyKey?: string;
+        reason?: string;
+      }): Promise<string[]>;
+      
+      // Consume an item by instance ID
+      consume(userId: string, instanceId: string, options?: {
+        idempotencyKey?: string;
+        reason?: string;
+      }): Promise<boolean>;
+      
+      // Get user's inventory
+      list(userId: string): Promise<InventoryItem[]>;
     };
   };
 
@@ -123,6 +180,18 @@ export interface SpawnServerSDK__V1<TConfig = any> {
       delete(key: string): Promise<void>;
     };
   };
+
+  leaderboard: {
+    submit(userId: string, leaderboardId: string, score: number): Promise<void>;
+
+    getMultiple(
+      leaderboardIds: string[],
+      options?: {
+        period?: 'today' | 'week' | 'month' | 'all';
+        limit?: number;
+      }
+    ): Promise<Record<string, LeaderboardEntry[]>>;
+  };
 }
 
 // Token types
@@ -170,6 +239,21 @@ export interface Item {
   data?: Record<string, any>;
 }
 
+export interface InventoryItem {
+  id: string; // Instance ID
+  itemId: string; // Item type
+  data?: any; // Item-specific data
+}
+
+export interface LeaderboardEntry {
+  rank: number;
+  username: string;
+  avatarUrl?: string;
+  score: number;
+  isMe?: boolean;
+  timestamp: number;
+}
+
 // v0 sdk types for testing
 
 export type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy' | 'inventory'>;