@playcademy/sdk 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -57,6 +57,7 @@ interface ErrorResponseBody {
  * ```
  */
 declare class ApiError extends Error {
+    /** HTTP status code */
     readonly status: number;
     /**
      * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").

package/dist/internal.d.ts

@@ -4519,6 +4519,7 @@ interface ErrorResponseBody {
  * ```
  */
 declare class ApiError extends Error {
+    /** HTTP status code */
     readonly status: number;
     /**
      * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
@@ -6327,6 +6328,36 @@ interface BucketFile {
     uploaded: string;
     contentType?: string;
 }
+/**
+ * KV key entry
+ */
+interface KVKeyEntry {
+    name: string;
+    expiration?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * KV key metadata
+ */
+interface KVKeyMetadata {
+    metadata?: Record<string, unknown>;
+}
+/**
+ * KV statistics
+ */
+interface KVStatsResponse {
+    totalKeys: number;
+    prefixes: Record<string, number>;
+}
+/**
+ * KV seed entry for bulk operations
+ */
+interface KVSeedEntry {
+    key: string;
+    value: string;
+    expiration_ttl?: number;
+    metadata?: Record<string, unknown>;
+}
 type DevUploadEvent = {
     type: 'init';
 } | {
@@ -7028,6 +7059,16 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 put: (slug: string, key: string, content: ArrayBuffer | Blob | Uint8Array<ArrayBufferLike>, contentType?: string | undefined) => Promise<void>;
                 delete: (slug: string, key: string) => Promise<void>;
             };
+            kv: {
+                list: (slug: string, prefix?: string | undefined) => Promise<KVKeyEntry[]>;
+                get: (slug: string, key: string) => Promise<string | null>;
+                set: (slug: string, key: string, value: string) => Promise<void>;
+                delete: (slug: string, key: string) => Promise<void>;
+                inspect: (slug: string, key: string) => Promise<KVKeyMetadata | null>;
+                stats: (slug: string) => Promise<KVStatsResponse>;
+                seed: (slug: string, entries: KVSeedEntry[]) => Promise<number>;
+                clear: (slug: string) => Promise<number>;
+            };
             domains: {
                 add: (slug: string, hostname: string) => Promise<GameCustomHostname>;
                 list: (slug: string) => Promise<GameCustomHostname[]>;
@@ -7575,4 +7616,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, 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, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, 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, 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, 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, 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, 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, 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, XpSummaryResponse };

package/dist/internal.js

@@ -1823,6 +1823,41 @@ function createDevNamespace(client) {
           await client["request"](`/games/${slug}/bucket/${encodeURIComponent(key)}`, "DELETE");
         }
       },
+      kv: {
+        list: async (slug, prefix) => {
+          const params = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+          const result = await client["request"](`/games/${slug}/kv${params}`, "GET");
+          return result.keys;
+        },
+        get: async (slug, key) => {
+          const result = await client["request"](`/games/${slug}/kv/${encodeURIComponent(key)}`, "GET");
+          return result.value;
+        },
+        set: async (slug, key, value) => {
+          await client["request"](`/games/${slug}/kv/${encodeURIComponent(key)}`, "PUT", {
+            body: value,
+            headers: { "Content-Type": "text/plain" }
+          });
+        },
+        delete: async (slug, key) => {
+          await client["request"](`/games/${slug}/kv/${encodeURIComponent(key)}`, "DELETE");
+        },
+        inspect: async (slug, key) => {
+          const result = await client["request"](`/games/${slug}/kv/${encodeURIComponent(key)}/metadata`, "GET");
+          return result.metadata;
+        },
+        stats: async (slug) => {
+          return client["request"](`/games/${slug}/kv/stats`, "GET");
+        },
+        seed: async (slug, entries) => {
+          const result = await client["request"](`/games/${slug}/kv/bulk`, "PUT", { body: { entries } });
+          return result.count;
+        },
+        clear: async (slug) => {
+          const result = await client["request"](`/games/${slug}/kv`, "DELETE");
+          return result.deleted;
+        }
+      },
       domains: {
         add: async (slug, hostname) => {
           return client["request"](`/games/${slug}/domains`, "POST", {

package/dist/server.js

@@ -1,3 +1,23 @@
+// src/server/guards.ts
+var VALID_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var VALID_SUBJECTS = [
+  "Reading",
+  "Language",
+  "Vocabulary",
+  "Social Studies",
+  "Writing",
+  "Science",
+  "FastMath",
+  "Math",
+  "None"
+];
+function isValidGrade(value) {
+  return typeof value === "number" && Number.isInteger(value) && VALID_GRADES.includes(value);
+}
+function isValidSubject(value) {
+  return typeof value === "string" && VALID_SUBJECTS.includes(value);
+}
+
 // src/server/namespaces/timeback.ts
 function createTimebackNamespace(client) {
   function enrichActivityData(data) {
@@ -8,11 +28,11 @@ function createTimebackNamespace(client) {
   }
   return {
     endActivity: async (studentId, payload) => {
-      if (!payload.activityData.grade) {
-        throw new Error("activityData.grade is required for TimeBack integration");
+      if (!isValidGrade(payload.activityData.grade)) {
+        throw new Error("activityData.grade must be a valid grade level (-1 to 13)");
       }
-      if (!payload.activityData.subject) {
-        throw new Error("activityData.subject is required for TimeBack integration");
+      if (!isValidSubject(payload.activityData.subject)) {
+        throw new Error("activityData.subject must be a valid subject");
       }
       const enrichedActivityData = enrichActivityData(payload.activityData);
       return client["request"]("/api/timeback/end-activity", "POST", {

package/dist/types.d.ts

@@ -5438,6 +5438,36 @@ interface BucketFile {
     uploaded: string;
     contentType?: string;
 }
+/**
+ * KV key entry
+ */
+interface KVKeyEntry {
+    name: string;
+    expiration?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * KV key metadata
+ */
+interface KVKeyMetadata {
+    metadata?: Record<string, unknown>;
+}
+/**
+ * KV statistics
+ */
+interface KVStatsResponse {
+    totalKeys: number;
+    prefixes: Record<string, number>;
+}
+/**
+ * KV seed entry for bulk operations
+ */
+interface KVSeedEntry {
+    key: string;
+    value: string;
+    expiration_ttl?: number;
+    metadata?: Record<string, unknown>;
+}
 type DevUploadEvent = {
     type: 'init';
 } | {
@@ -5686,4 +5716,4 @@ interface PlaycademyServerClientState {
 }
 
 export { AchievementCompletionType, NotificationStatus, NotificationType, PlaycademyClient };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, 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, 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, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, 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, 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, XpSummaryResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.2.5",
+    "version": "0.2.7",
     "type": "module",
     "exports": {
         ".": {
@@ -44,12 +44,12 @@
         "@playcademy/data": "0.0.1",
         "@playcademy/logger": "0.0.1",
         "@playcademy/types": "0.0.1",
-        "@playcademy/sandbox": "0.3.9",
+        "@playcademy/sandbox": "0.3.10",
         "@playcademy/test": "0.0.1",
         "@playcademy/timeback": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
-        "playcademy": "0.15.0",
+        "playcademy": "0.15.6",
         "rollup": "^4.50.2",
         "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2"