@playcademy/sdk 0.5.0 → 0.6.0-beta.1

package/dist/index.js

@@ -25,6 +25,7 @@ var MessageEvents;
   MessageEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
   MessageEvents2["KEY_EVENT"] = "PLAYCADEMY_KEY_EVENT";
   MessageEvents2["DISPLAY_ALERT"] = "PLAYCADEMY_DISPLAY_ALERT";
+  MessageEvents2["DEMO_END"] = "PLAYCADEMY_DEMO_END";
   MessageEvents2["AUTH_STATE_CHANGE"] = "PLAYCADEMY_AUTH_STATE_CHANGE";
   MessageEvents2["AUTH_CALLBACK"] = "PLAYCADEMY_AUTH_CALLBACK";
 })(MessageEvents ||= {});
@@ -84,7 +85,8 @@ class PlaycademyMessaging {
       "PLAYCADEMY_EXIT" /* EXIT */,
       "PLAYCADEMY_TELEMETRY" /* TELEMETRY */,
       "PLAYCADEMY_KEY_EVENT" /* KEY_EVENT */,
-      "PLAYCADEMY_DISPLAY_ALERT" /* DISPLAY_ALERT */
+      "PLAYCADEMY_DISPLAY_ALERT" /* DISPLAY_ALERT */,
+      "PLAYCADEMY_DEMO_END" /* DEMO_END */
     ];
     const shouldUsePostMessage = isIframe && iframeToParentEvents.includes(eventType);
     return {
@@ -185,7 +187,8 @@ function createStandaloneConfig() {
     gameUrl: globalThis.location.origin,
     token: "mock-game-token-for-local-dev",
     gameId: "mock-game-id-from-template",
-    realtimeUrl: undefined
+    realtimeUrl: undefined,
+    mode: "standalone"
   };
   globalThis.PLAYCADEMY = mockConfig;
   return mockConfig;
@@ -203,6 +206,7 @@ async function init(options) {
     gameUrl: config.gameUrl,
     token: config.token,
     gameId: config.gameId,
+    mode: config.mode,
     autoStartSession: globalThis.self !== window.top,
     onDisconnect: options?.onDisconnect,
     enableConnectionMonitoring: options?.enableConnectionMonitoring
@@ -850,7 +854,12 @@ async function login2(client, options) {
 // src/namespaces/game/identity.ts
 function createIdentityNamespace(client) {
   return {
-    connect: (options) => login2(client, options),
+    connect: (options) => {
+      if (client.mode === "demo") {
+        throw new PlaycademyError("identity.connect() is not available in demo mode. Use platform or standalone mode for OAuth flows.");
+      }
+      return login2(client, options);
+    },
     _getContext: () => ({
       isInIframe: client["authContext"]?.isInIframe ?? false
     })
@@ -1050,6 +1059,42 @@ function createBackendNamespace(client) {
     }
   };
 }
+// src/namespaces/game/guard.ts
+function assertPlatformMode(client, operation) {
+  if (client.mode !== "platform") {
+    throw new PlaycademyError(`${operation} requires platform mode (current: ${client.mode}). Check client.mode before calling.`);
+  }
+}
+function assertDemoMode(client, operation) {
+  if (client.mode !== "demo") {
+    throw new PlaycademyError(`${operation} requires demo mode (current: ${client.mode}). Check client.mode before calling.`);
+  }
+}
+
+// src/namespaces/game/demo.ts
+function createDemoNamespace(client) {
+  return {
+    profile: {
+      get: async () => {
+        assertDemoMode(client, "demo.profile.get()");
+        return client["request"]("/users/demo-profile", "GET");
+      },
+      update: async (updates) => {
+        assertDemoMode(client, "demo.profile.update()");
+        return client["request"]("/users/demo-profile", "PATCH", {
+          body: updates
+        });
+      }
+    },
+    end: (score, options) => {
+      assertDemoMode(client, "demo.end()");
+      messaging.send("PLAYCADEMY_DEMO_END" /* DEMO_END */, {
+        score,
+        ...options
+      });
+    }
+  };
+}
 // src/core/cache/permanent-cache.ts
 function createPermanentCache(keyPrefix) {
   const cache = new Map;
@@ -1112,10 +1157,17 @@ function createUsersNamespace(client) {
     });
   }
   return {
-    me: async () => client["request"]("/users/me", "GET"),
+    me: async () => {
+      assertPlatformMode(client, "users.me()");
+      return client["request"]("/users/me", "GET");
+    },
     inventory: {
-      get: async () => client["request"](`/inventory`, "GET"),
+      get: async () => {
+        assertPlatformMode(client, "users.inventory.get()");
+        return client["request"](`/inventory`, "GET");
+      },
       add: async (identifier, qty) => {
+        assertPlatformMode(client, "users.inventory.add()");
         const itemId = await resolveItemId(identifier);
         const res = await client["request"](`/inventory/add`, "POST", { body: { itemId, qty } });
         client["emit"]("inventoryChange", {
@@ -1126,6 +1178,7 @@ function createUsersNamespace(client) {
         return res;
       },
       remove: async (identifier, qty) => {
+        assertPlatformMode(client, "users.inventory.remove()");
         const itemId = await resolveItemId(identifier);
         const res = await client["request"](`/inventory/remove`, "POST", { body: { itemId, qty } });
         client["emit"]("inventoryChange", {
@@ -1136,12 +1189,14 @@ function createUsersNamespace(client) {
         return res;
       },
       quantity: async (identifier) => {
+        assertPlatformMode(client, "users.inventory.quantity()");
         const itemId = await resolveItemId(identifier);
         const inventory = await client["request"](`/inventory`, "GET");
         const item = inventory.find((inv) => inv.item?.id === itemId);
         return item?.quantity ?? 0;
       },
       has: async (identifier, minQuantity = 1) => {
+        assertPlatformMode(client, "users.inventory.has()");
         const itemId = await resolveItemId(identifier);
         const inventory = await client["request"](`/inventory`, "GET");
         const item = inventory.find((inv) => inv.item?.id === itemId);
@@ -1315,11 +1370,13 @@ function createCreditsNamespace(client) {
   }
   return {
     balance: async () => {
+      assertPlatformMode(client, "credits.balance()");
       const inventory = await client["request"]("/inventory", "GET");
       const primaryCurrencyInventoryItem = inventory.find((item) => item.item?.slug === CURRENCIES.PRIMARY);
       return primaryCurrencyInventoryItem?.quantity ?? 0;
     },
     add: async (amount) => {
+      assertPlatformMode(client, "credits.add()");
       if (amount <= 0) {
         throw new Error("Amount must be positive");
       }
@@ -1338,6 +1395,7 @@ function createCreditsNamespace(client) {
       return result.newTotal;
     },
     spend: async (amount) => {
+      assertPlatformMode(client, "credits.spend()");
       if (amount <= 0) {
         throw new Error("Amount must be positive");
       }
@@ -1360,12 +1418,15 @@ function createCreditsNamespace(client) {
 // src/namespaces/game/scores.ts
 function createScoresNamespace(client) {
   return {
-    submit: async (gameId, score, metadata) => client["request"](`/games/${gameId}/scores`, "POST", {
-      body: {
-        score,
-        metadata
-      }
-    })
+    submit: async (score, metadata) => {
+      const gameId = client["_ensureGameId"]();
+      return client["request"](`/games/${gameId}/scores`, "POST", {
+        body: {
+          score,
+          metadata
+        }
+      });
+    }
   };
 }
 // src/namespaces/game/realtime.ts
@@ -1373,6 +1434,7 @@ function createRealtimeNamespace(client) {
   return {
     token: {
       get: async () => {
+        assertPlatformMode(client, "realtime.token.get()");
         const endpoint = client["gameId"] ? `/games/${client["gameId"]}/realtime/token` : "/realtime/token";
         return client["request"](endpoint, "POST");
       }
@@ -1826,6 +1888,7 @@ function createTimebackNamespace(client) {
   }
   return {
     get user() {
+      assertPlatformMode(client, "timeback.user");
       return {
         get id() {
           return getTimeback()?.id;
@@ -1898,17 +1961,56 @@ function createTimebackNamespace(client) {
       };
     },
     startActivity: (metadata, options) => {
+      assertPlatformMode(client, "timeback.startActivity()");
       activityTracker.startActivity(metadata, options);
     },
     pauseActivity: () => {
+      assertPlatformMode(client, "timeback.pauseActivity()");
       activityTracker.pauseActivity();
     },
     resumeActivity: () => {
+      assertPlatformMode(client, "timeback.resumeActivity()");
       activityTracker.resumeActivity();
     },
-    endActivity: async (data) => activityTracker.endActivity(data)
+    endActivity: async (data) => {
+      assertPlatformMode(client, "timeback.endActivity()");
+      return activityTracker.endActivity(data);
+    }
+  };
+}
+// src/namespaces/platform/leaderboard.ts
+async function fetchInternalLeaderboardEntries(client, options) {
+  const params = new URLSearchParams({
+    timeframe: options?.timeframe || "all_time",
+    limit: String(options?.limit || 10),
+    offset: String(options?.offset || 0)
+  });
+  if (options?.gameId) {
+    params.append("gameId", options.gameId);
+  }
+  return client["request"](`/leaderboard?${params}`, "GET");
+}
+async function fetchPublicLeaderboardEntries(client, options) {
+  const params = new URLSearchParams({
+    timeframe: options?.timeframe || "all_time",
+    limit: String(options?.limit || 10),
+    offset: String(options?.offset || 0)
+  });
+  params.append("gameId", options?.gameId || client["_ensureGameId"]());
+  return client["request"](`/leaderboard?${params}`, "GET");
+}
+function createLeaderboardNamespace(client) {
+  return {
+    fetch: async (options) => fetchInternalLeaderboardEntries(client, options),
+    getUserRank: async (gameId, userId) => client["request"](`/games/${gameId}/users/${userId}/rank`, "GET")
   };
 }
+function createLeaderboardFetchNamespace(client) {
+  return {
+    fetch: async (options) => fetchPublicLeaderboardEntries(client, options)
+  };
+}
+
 // src/core/auth/strategies.ts
 class ApiKeyAuth {
   apiKey;
@@ -2357,6 +2459,7 @@ async function request({
 class PlaycademyBaseClient {
   baseUrl;
   gameUrl;
+  mode;
   authStrategy;
   gameId;
   config;
@@ -2373,6 +2476,7 @@ class PlaycademyBaseClient {
   constructor(config) {
     this.baseUrl = config?.baseUrl?.endsWith("/api") ? config.baseUrl : `${config?.baseUrl}/api`;
     this.gameUrl = config?.gameUrl;
+    this.mode = config?.mode ?? "platform";
     this.gameId = config?.gameId;
     this.launchId = config?.launchId ?? undefined;
     this.config = config || {};
@@ -2551,6 +2655,8 @@ class PlaycademyClient extends PlaycademyBaseClient {
   timeback = createTimebackNamespace(this);
   credits = createCreditsNamespace(this);
   scores = createScoresNamespace(this);
+  leaderboard = createLeaderboardFetchNamespace(this);
+  demo = createDemoNamespace(this);
   realtime = createRealtimeNamespace(this);
   backend = createBackendNamespace(this);
   static init = init;

package/dist/internal.d.ts

@@ -1150,6 +1150,23 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        isAnonymous: drizzle_orm_pg_core.PgColumn<{
+            name: "is_anonymous";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         timebackId: drizzle_orm_pg_core.PgColumn<{
             name: "timeback_id";
             tableName: "user";
@@ -5050,6 +5067,7 @@ interface AuthStrategy {
 declare abstract class PlaycademyBaseClient {
     baseUrl: string;
     gameUrl?: string;
+    mode: PlaycademyMode;
     protected authStrategy: AuthStrategy;
     protected gameId?: string;
     protected config: Partial<ClientConfig>;
@@ -5454,6 +5472,15 @@ declare enum MessageEvents {
      * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
      */
     DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    /**
+     * Game signals that demo mode has ended.
+     * Sent when a demo experience reaches its CTA/upgrade boundary.
+     * Payload:
+     * - `score?`: number
+     * - `durationMs?`: number
+     * - `metadata?`: `Record<string, unknown>`
+     */
+    DEMO_END = "PLAYCADEMY_DEMO_END",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -5521,6 +5548,8 @@ interface MessageEventMap {
     [MessageEvents.KEY_EVENT]: KeyEventPayload;
     /** Display alert request from game */
     [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
+    /** Demo end signal from game */
+    [MessageEvents.DEMO_END]: DemoEndPayload;
     /** Authentication state change notification */
     [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
     /** OAuth callback data from popup/new-tab windows */
@@ -6097,6 +6126,20 @@ interface XpResponse {
  */
 
 type TokenType = 'session' | 'apiKey' | 'gameJwt';
+/**
+ * Runtime mode for a Playcademy game client.
+ *
+ * - `'platform'` — game is embedded in the platform (e.g. the cademy hub)
+ *   with a real authenticated user and full access to SDK namespaces.
+ * - `'demo'` — game is embedded in the landing page demo shell with an
+ *   anonymous user; platform-only namespaces throw, and `client.demo.*`
+ *   is the supported surface for signaling demo lifecycle events and
+ *   reading/updating the anonymous profile.
+ * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
+ *   or direct-deploy preview) with a mock token and no real platform
+ *   context. API calls will not succeed; use this to branch UX locally.
+ */
+type PlaycademyMode = 'platform' | 'demo' | 'standalone';
 interface ClientConfig {
     baseUrl: string;
     gameUrl?: string;
@@ -6107,6 +6150,7 @@ interface ClientConfig {
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;
+    mode?: PlaycademyMode;
 }
 /**
  * Handler called when connection state changes to offline or degraded.
@@ -6142,6 +6186,8 @@ interface InitPayload {
     realtimeUrl?: string;
     /** Timeback context (if user has a Timeback account) */
     timeback?: TimebackInitContext;
+    /** Runtime mode for the game client */
+    mode?: PlaycademyMode;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -6170,6 +6216,7 @@ interface GameContextPayload {
     realtimeUrl: string;
     gameId: string;
     forwardKeys?: string[];
+    mode?: PlaycademyMode;
 }
 type EventListeners = {
     [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
@@ -6292,6 +6339,26 @@ interface ConnectionStatePayload {
     state: 'online' | 'offline' | 'degraded';
     reason: string;
 }
+/**
+ * Options for `client.demo.end(score, options?)`.
+ *
+ * All optional. The landing-page demo shell can render a meaningful CTA
+ * from `score` alone, but `durationMs` enables a nicer summary and
+ * `metadata` lets games pass any extra context they want to surface.
+ */
+interface DemoEndOptions {
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wire payload for the `PLAYCADEMY_DEMO_END` message.
+ *
+ * `score` is required — the demo shell always needs something to display
+ * when the round ends. `durationMs` and `metadata` are optional.
+ */
+interface DemoEndPayload extends DemoEndOptions {
+    score: number;
+}
 
 /**
  * SDK-specific API response types
@@ -7803,4 +7870,4 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
 }
 
 export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, NotificationStatus, NotificationType, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };