@omen.foundation/game-sdk 1.0.15 → 1.0.17

package/README.md

@@ -12,6 +12,12 @@ The SDK supports two modes:
 npm install @omen.foundation/game-sdk
 ```
 
+For **real-time updates** (balance & inventory), also install Ably:
+
+```bash
+npm install ably
+```
+
 ## Quick Start
 
 ### Client Mode (OAuth Authentication)
@@ -188,6 +194,51 @@ if (sdk.isAuthenticated()) {
 await sdk.logout();
 ```
 
+### Real-Time Updates (Balance & Inventory)
+
+So your game stays in sync when the user spends or receives OmenX / NFTs on the website or in another client, subscribe to the per-wallet Ably channel. The SDK provides the channel name, event names, and a subscribe helper with idempotency (eventId dedupe).
+
+**Requires:** `ably` installed in your app. Use the same Ably API key as the OmenX frontend (subscribe capability for `wallet:*`).
+
+```typescript
+import { subscribeWalletRealtime, getWalletChannelName, REALTIME_EVENTS } from '@omen.foundation/game-sdk';
+import * as Ably from 'ably';
+
+// After user logs in and you have their wallet address:
+const ably = new Ably.Realtime({ key: 'YOUR_ABLY_API_KEY' });
+
+const unsubscribe = subscribeWalletRealtime(ably, walletAddress, {
+  onBalance: (payload) => {
+    // Refetch balances (e.g. call your backend or GetPlayerBalances)
+    refetchBalances();
+  },
+  onInventory: (payload) => {
+    // Refetch inventory / NFTs (backend cache is source of truth)
+    refetchInventory();
+  },
+});
+
+// When user logs out or wallet changes:
+unsubscribe();
+```
+
+With React and `ably/react`, pass the client from `useAbly()`:
+
+```typescript
+import { useAbly } from 'ably/react';
+import { subscribeWalletRealtime } from '@omen.foundation/game-sdk';
+
+// Inside your component, after wallet is available:
+const ably = useAbly();
+useEffect(() => {
+  if (!walletAddress || !ably) return;
+  return subscribeWalletRealtime(ably, walletAddress, {
+    onBalance: () => refetchBalances(),
+    onInventory: () => refetchInventory(),
+  });
+}, [ably, walletAddress]);
+```
+
 ## API Reference
 
 See the [full documentation](./docs/README.md) for detailed API reference.

package/dist/index.d.mts

@@ -107,6 +107,38 @@ interface ApiCallOptions {
      */
     includeAuth?: boolean;
 }
+interface VipTierInfo {
+    tierIndex: number;
+    tierKey: string;
+    displayName: string;
+    allocationBoundary: number;
+    usdPrice?: number;
+    perksDescription?: string;
+    active?: boolean;
+    /** Structured perks from tiers JSON (e.g. GAME_BONUS_POINTS_LEVEL). */
+    perks?: Record<string, unknown>;
+    tierPerksShortDescription?: string;
+    /** Games read this (1–21) for Game Alpha Access (higher tiers), Game Beta Access (lower tiers), or in-game gifts. */
+    gameBonusPointsLevel?: number;
+}
+interface VipStatus {
+    walletAddress: string;
+    entitlement: number;
+    claimed: number;
+    claimable: number;
+    tier: VipTierInfo;
+    nextTier: VipTierInfo | null;
+    phaseIndex: number;
+    claimingAllowed: boolean;
+    phaseClaimingClosed?: boolean;
+    currentEpoch?: {
+        epochId: string;
+        startAt: string;
+        endAt: string;
+        epochPoolAmount: number;
+        estimatedShare?: number;
+    };
+}
 
 /**
  * OmenX Game SDK
@@ -154,6 +186,16 @@ declare class OmenXGameSDK {
      * Handle auth data from iframe
      */
     private handleAuthData;
+    /**
+     * Get current VIP status for the authenticated user (tier, allocation, claimable, perks).
+     * Games can read tier.gameBonusPointsLevel (1–21) for Alpha/Beta access or in-game gifts.
+     */
+    getVipStatus(): Promise<VipStatus | null>;
+    /**
+     * Get the current user's game bonus points level (1–21) from their VIP tier.
+     * Use for Game Alpha Access (e.g. level >= 6), Game Beta Access (e.g. level >= 1), or in-game gifts.
+     */
+    getGameBonusPointsLevel(): Promise<number | null>;
     /**
      * Refresh access token using refresh token
      */
@@ -234,13 +276,15 @@ declare class OmenXServerSDK {
      * NFT Template Operations
      */
     /**
-     * Get all NFT templates for a game
+     * Get all NFT templates for the authenticated game (game is derived from API key).
+     * gameId is optional and ignored by the API; included for backward compatibility.
      */
-    getNftTemplates(gameId: string): Promise<any>;
+    getNftTemplates(_gameId?: string): Promise<any>;
     /**
-     * Get NFT contract address for a game
+     * Get NFT contract address for the authenticated game (game is derived from API key).
+     * gameId is optional and ignored by the API; included for backward compatibility.
      */
-    getNftContract(gameId: string): Promise<any>;
+    getNftContract(_gameId?: string): Promise<any>;
     /**
      * Mint NFTs (single or batch)
      */
@@ -281,6 +325,150 @@ declare class OmenXServerSDK {
         dropTableId: string;
         recipientAddress: string;
     }): Promise<any>;
+    /**
+     * VIP Points (Developer pool)
+     * Requires scope: vip_points:write.
+     * Grants VIP points to a player from this game's allocated pool. Enforces total allocation and max per quest.
+     * Call from your game backend only (API key auth); not for client-side use.
+     */
+    grantVipPoints(params: {
+        /** Player wallet address (0x-prefixed, 40 hex chars). */
+        wallet: string;
+        /** Points to grant (positive integer). Capped by pool remaining and max per quest. */
+        amount: number;
+        /** Optional quest/activity id for idempotency or auditing. */
+        questId?: string;
+    }): Promise<{
+        success: boolean;
+        data?: {
+            wallet: string;
+            amount: number;
+            phaseIndex?: number;
+        };
+    }>;
+    /**
+     * Quests API (game quests only).
+     * Requires scope: quests:read for getQuestsForPlayer; quests:write for assign, progress, complete, claim.
+     */
+    /** Get assigned quests for a player. Optional questType filter. */
+    getQuestsForPlayer(wallet: string, options?: {
+        questType?: 'daily' | 'weekly' | 'monthly' | 'oneTime';
+    }): Promise<{
+        success: boolean;
+        data: {
+            quests: any[];
+        };
+    }>;
+    /** Assign quests of a type to a player. Use idempotencyKey for safe retries. */
+    assignQuests(wallet: string, questType: 'daily' | 'weekly' | 'monthly' | 'oneTime', count: number, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        data: {
+            assigned: number;
+            assignmentIds?: string[];
+        };
+    }>;
+    /** Report progress for a quest step. Quest auto-completes when all steps meet targets. */
+    reportQuestProgress(wallet: string, questKey: string, value: number, options?: {
+        stepKey?: string;
+    }): Promise<{
+        success: boolean;
+        data?: object;
+    }>;
+    /** Mark a quest complete (all steps set to targets). */
+    completeQuest(wallet: string, questKey: string): Promise<{
+        success: boolean;
+        data?: object;
+    }>;
+    /** Claim VIP reward for a completed quest (from game pool). Use idempotencyKey for safe retries. */
+    claimQuestReward(wallet: string, questKey: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        data?: {
+            pointsGranted?: number;
+        };
+    }>;
+    /**
+     * Reset or wipe a player's quest state for this game. Requires quests:write.
+     * - wipe: delete all quest assignments for this game for the player.
+     * - reset: delete assignments for the specified questKey only (questKey required).
+     */
+    resetPlayerQuests(wallet: string, action: 'wipe' | 'reset', questKey?: string): Promise<{
+        success: boolean;
+        data: {
+            action: string;
+            deleted: number;
+            questKey?: string;
+        };
+    }>;
 }
 
-export { type ApiCallOptions, type AuthData, type OAuthOptions, OmenXGameSDK, type OmenXGameSDKConfig, OmenXServerSDK, type UserInfo };
+/**
+ * Real-time wallet updates (balance & inventory) for game clients.
+ * Subscribe to the per-wallet Ably channel so the game stays in sync when the user
+ * spends or receives OmenX / NFTs on the website or in another client.
+ *
+ * Requires the app to install `ably` and pass an Ably Realtime instance.
+ */
+/** Payload for balance and inventory events. Use eventId for idempotency (ignore if already processed). */
+interface RealtimeWalletPayload {
+    eventId: string;
+    timestamp: number;
+    reason?: string;
+}
+/** Ably channel name prefix. Full channel = "wallet:" + normalized wallet address. */
+declare const WALLET_CHANNEL_PREFIX = "wallet:";
+/** Event names published by the OmenX backend on the wallet channel. */
+declare const REALTIME_EVENTS: {
+    /** Currency balance changed. Refetch via GetPlayerBalances or your balance API. */
+    readonly balance: "balance";
+    /** NFT/inventory changed. Refetch via GetPlayerNfts or your inventory API (cache is source of truth). */
+    readonly inventory: "inventory";
+};
+/**
+ * Get the Ably channel name for a wallet. Use this when subscribing with your Ably client.
+ */
+declare function getWalletChannelName(walletAddress: string): string;
+/**
+ * Minimal Ably Realtime interface so the SDK works with any Ably.Realtime instance.
+ * The app provides the real Ably client from AblyProvider or new Ably.Realtime({ key }).
+ */
+interface AblyRealtimeLike {
+    channels: {
+        get(name: string): {
+            subscribe(eventOrCallback: string | ((message: {
+                name: string;
+                data: unknown;
+            }) => void), callback?: (message: {
+                name: string;
+                data: unknown;
+            }) => void): void;
+            unsubscribe(eventOrCallback?: string | ((message: {
+                name: string;
+                data: unknown;
+            }) => void), callback?: (message: {
+                name: string;
+                data: unknown;
+            }) => void): void;
+        };
+    };
+}
+/**
+ * Subscribe to real-time balance and inventory events for a wallet.
+ * Call when the user logs in; call the returned unsubscribe when they log out or wallet changes.
+ *
+ * Uses eventId to dedupe (ignores already-seen events). Refetch in your app on each callback.
+ *
+ * @param ably - Ably Realtime instance (e.g. from useAbly() or new Ably.Realtime({ key }))
+ * @param walletAddress - Current player wallet (0x...)
+ * @param callbacks - onBalance and/or onInventory; each receives the payload (eventId, timestamp, reason?)
+ * @returns Unsubscribe function
+ */
+declare function subscribeWalletRealtime(ably: AblyRealtimeLike, walletAddress: string, callbacks: {
+    onBalance?: (payload: RealtimeWalletPayload) => void;
+    onInventory?: (payload: RealtimeWalletPayload) => void;
+}): () => void;
+
+export { type AblyRealtimeLike, type ApiCallOptions, type AuthData, type OAuthOptions, OmenXGameSDK, type OmenXGameSDKConfig, OmenXServerSDK, REALTIME_EVENTS, type RealtimeWalletPayload, type UserInfo, type VipStatus, type VipTierInfo, WALLET_CHANNEL_PREFIX, getWalletChannelName, subscribeWalletRealtime };

package/dist/index.d.ts

@@ -107,6 +107,38 @@ interface ApiCallOptions {
      */
     includeAuth?: boolean;
 }
+interface VipTierInfo {
+    tierIndex: number;
+    tierKey: string;
+    displayName: string;
+    allocationBoundary: number;
+    usdPrice?: number;
+    perksDescription?: string;
+    active?: boolean;
+    /** Structured perks from tiers JSON (e.g. GAME_BONUS_POINTS_LEVEL). */
+    perks?: Record<string, unknown>;
+    tierPerksShortDescription?: string;
+    /** Games read this (1–21) for Game Alpha Access (higher tiers), Game Beta Access (lower tiers), or in-game gifts. */
+    gameBonusPointsLevel?: number;
+}
+interface VipStatus {
+    walletAddress: string;
+    entitlement: number;
+    claimed: number;
+    claimable: number;
+    tier: VipTierInfo;
+    nextTier: VipTierInfo | null;
+    phaseIndex: number;
+    claimingAllowed: boolean;
+    phaseClaimingClosed?: boolean;
+    currentEpoch?: {
+        epochId: string;
+        startAt: string;
+        endAt: string;
+        epochPoolAmount: number;
+        estimatedShare?: number;
+    };
+}
 
 /**
  * OmenX Game SDK
@@ -154,6 +186,16 @@ declare class OmenXGameSDK {
      * Handle auth data from iframe
      */
     private handleAuthData;
+    /**
+     * Get current VIP status for the authenticated user (tier, allocation, claimable, perks).
+     * Games can read tier.gameBonusPointsLevel (1–21) for Alpha/Beta access or in-game gifts.
+     */
+    getVipStatus(): Promise<VipStatus | null>;
+    /**
+     * Get the current user's game bonus points level (1–21) from their VIP tier.
+     * Use for Game Alpha Access (e.g. level >= 6), Game Beta Access (e.g. level >= 1), or in-game gifts.
+     */
+    getGameBonusPointsLevel(): Promise<number | null>;
     /**
      * Refresh access token using refresh token
      */
@@ -234,13 +276,15 @@ declare class OmenXServerSDK {
      * NFT Template Operations
      */
     /**
-     * Get all NFT templates for a game
+     * Get all NFT templates for the authenticated game (game is derived from API key).
+     * gameId is optional and ignored by the API; included for backward compatibility.
      */
-    getNftTemplates(gameId: string): Promise<any>;
+    getNftTemplates(_gameId?: string): Promise<any>;
     /**
-     * Get NFT contract address for a game
+     * Get NFT contract address for the authenticated game (game is derived from API key).
+     * gameId is optional and ignored by the API; included for backward compatibility.
      */
-    getNftContract(gameId: string): Promise<any>;
+    getNftContract(_gameId?: string): Promise<any>;
     /**
      * Mint NFTs (single or batch)
      */
@@ -281,6 +325,150 @@ declare class OmenXServerSDK {
         dropTableId: string;
         recipientAddress: string;
     }): Promise<any>;
+    /**
+     * VIP Points (Developer pool)
+     * Requires scope: vip_points:write.
+     * Grants VIP points to a player from this game's allocated pool. Enforces total allocation and max per quest.
+     * Call from your game backend only (API key auth); not for client-side use.
+     */
+    grantVipPoints(params: {
+        /** Player wallet address (0x-prefixed, 40 hex chars). */
+        wallet: string;
+        /** Points to grant (positive integer). Capped by pool remaining and max per quest. */
+        amount: number;
+        /** Optional quest/activity id for idempotency or auditing. */
+        questId?: string;
+    }): Promise<{
+        success: boolean;
+        data?: {
+            wallet: string;
+            amount: number;
+            phaseIndex?: number;
+        };
+    }>;
+    /**
+     * Quests API (game quests only).
+     * Requires scope: quests:read for getQuestsForPlayer; quests:write for assign, progress, complete, claim.
+     */
+    /** Get assigned quests for a player. Optional questType filter. */
+    getQuestsForPlayer(wallet: string, options?: {
+        questType?: 'daily' | 'weekly' | 'monthly' | 'oneTime';
+    }): Promise<{
+        success: boolean;
+        data: {
+            quests: any[];
+        };
+    }>;
+    /** Assign quests of a type to a player. Use idempotencyKey for safe retries. */
+    assignQuests(wallet: string, questType: 'daily' | 'weekly' | 'monthly' | 'oneTime', count: number, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        data: {
+            assigned: number;
+            assignmentIds?: string[];
+        };
+    }>;
+    /** Report progress for a quest step. Quest auto-completes when all steps meet targets. */
+    reportQuestProgress(wallet: string, questKey: string, value: number, options?: {
+        stepKey?: string;
+    }): Promise<{
+        success: boolean;
+        data?: object;
+    }>;
+    /** Mark a quest complete (all steps set to targets). */
+    completeQuest(wallet: string, questKey: string): Promise<{
+        success: boolean;
+        data?: object;
+    }>;
+    /** Claim VIP reward for a completed quest (from game pool). Use idempotencyKey for safe retries. */
+    claimQuestReward(wallet: string, questKey: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        data?: {
+            pointsGranted?: number;
+        };
+    }>;
+    /**
+     * Reset or wipe a player's quest state for this game. Requires quests:write.
+     * - wipe: delete all quest assignments for this game for the player.
+     * - reset: delete assignments for the specified questKey only (questKey required).
+     */
+    resetPlayerQuests(wallet: string, action: 'wipe' | 'reset', questKey?: string): Promise<{
+        success: boolean;
+        data: {
+            action: string;
+            deleted: number;
+            questKey?: string;
+        };
+    }>;
 }
 
-export { type ApiCallOptions, type AuthData, type OAuthOptions, OmenXGameSDK, type OmenXGameSDKConfig, OmenXServerSDK, type UserInfo };
+/**
+ * Real-time wallet updates (balance & inventory) for game clients.
+ * Subscribe to the per-wallet Ably channel so the game stays in sync when the user
+ * spends or receives OmenX / NFTs on the website or in another client.
+ *
+ * Requires the app to install `ably` and pass an Ably Realtime instance.
+ */
+/** Payload for balance and inventory events. Use eventId for idempotency (ignore if already processed). */
+interface RealtimeWalletPayload {
+    eventId: string;
+    timestamp: number;
+    reason?: string;
+}
+/** Ably channel name prefix. Full channel = "wallet:" + normalized wallet address. */
+declare const WALLET_CHANNEL_PREFIX = "wallet:";
+/** Event names published by the OmenX backend on the wallet channel. */
+declare const REALTIME_EVENTS: {
+    /** Currency balance changed. Refetch via GetPlayerBalances or your balance API. */
+    readonly balance: "balance";
+    /** NFT/inventory changed. Refetch via GetPlayerNfts or your inventory API (cache is source of truth). */
+    readonly inventory: "inventory";
+};
+/**
+ * Get the Ably channel name for a wallet. Use this when subscribing with your Ably client.
+ */
+declare function getWalletChannelName(walletAddress: string): string;
+/**
+ * Minimal Ably Realtime interface so the SDK works with any Ably.Realtime instance.
+ * The app provides the real Ably client from AblyProvider or new Ably.Realtime({ key }).
+ */
+interface AblyRealtimeLike {
+    channels: {
+        get(name: string): {
+            subscribe(eventOrCallback: string | ((message: {
+                name: string;
+                data: unknown;
+            }) => void), callback?: (message: {
+                name: string;
+                data: unknown;
+            }) => void): void;
+            unsubscribe(eventOrCallback?: string | ((message: {
+                name: string;
+                data: unknown;
+            }) => void), callback?: (message: {
+                name: string;
+                data: unknown;
+            }) => void): void;
+        };
+    };
+}
+/**
+ * Subscribe to real-time balance and inventory events for a wallet.
+ * Call when the user logs in; call the returned unsubscribe when they log out or wallet changes.
+ *
+ * Uses eventId to dedupe (ignores already-seen events). Refetch in your app on each callback.
+ *
+ * @param ably - Ably Realtime instance (e.g. from useAbly() or new Ably.Realtime({ key }))
+ * @param walletAddress - Current player wallet (0x...)
+ * @param callbacks - onBalance and/or onInventory; each receives the payload (eventId, timestamp, reason?)
+ * @returns Unsubscribe function
+ */
+declare function subscribeWalletRealtime(ably: AblyRealtimeLike, walletAddress: string, callbacks: {
+    onBalance?: (payload: RealtimeWalletPayload) => void;
+    onInventory?: (payload: RealtimeWalletPayload) => void;
+}): () => void;
+
+export { type AblyRealtimeLike, type ApiCallOptions, type AuthData, type OAuthOptions, OmenXGameSDK, type OmenXGameSDKConfig, OmenXServerSDK, REALTIME_EVENTS, type RealtimeWalletPayload, type UserInfo, type VipStatus, type VipTierInfo, WALLET_CHANNEL_PREFIX, getWalletChannelName, subscribeWalletRealtime };