@series-inc/rundot-game-sdk 5.0.4 → 5.0.8-beta.0

package/README.md

@@ -1,33 +1,33 @@
-# RUN.game SDK API
-
-Build connected HTML5 games that integrate deeply with the RUN.game platform. This package provides the client SDK used by hosted games as well as the local mock environment for development.
-
-## Highlights
-
-- Typed APIs for RUN.game platform services (simulation, rooms, analytics, ads, and more)
-- Host-aware tooling including lifecycle hooks, safe-area utilities, and asset loading helpers
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install @series-inc/rundot-game-sdk@latest
-```
-
-### Initialize
-
-```typescript
-import { default as RundotGameAPI } from '@series-inc/rundot-game-sdk/api'
-
-// Initialize the API
-await RundotGameAPI.initializeAsync()
-```
-
-## Documentation
-
-The complete RUN.game SDK manuals live on [Run.game Docs](https://series-1.gitbook.io/getreel-docs). Start there for setup guides, API references, tutorials, and best practices.
-
-## Support & Links
-
+# RUN.game SDK API
+
+Build connected HTML5 games that integrate deeply with the RUN.game platform. This package provides the client SDK used by hosted games as well as the local mock environment for development.
+
+## Highlights
+
+- Typed APIs for RUN.game platform services (simulation, rooms, analytics, ads, and more)
+- Host-aware tooling including lifecycle hooks, safe-area utilities, and asset loading helpers
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @series-inc/rundot-game-sdk@latest
+```
+
+### Initialize
+
+```typescript
+import { default as RundotGameAPI } from '@series-inc/rundot-game-sdk/api'
+
+// Initialize the API
+await RundotGameAPI.initializeAsync()
+```
+
+## Documentation
+
+The complete RUN.game SDK manuals live on [Run.game Docs](https://series-1.gitbook.io/getreel-docs). Start there for setup guides, API references, tutorials, and best practices.
+
+## Support & Links
+
 - [Join our Discord!](https://discord.gg/NcjhKQHx)

package/dist/{AdsApi-BMEW7MCB.d.ts → AdsApi-iy2e1cKJ.d.ts}

@@ -7,7 +7,7 @@ interface RpcRequest {
     type: 'rpc-request';
     id: string;
     method: string;
-    args?: any[];
+    args?: unknown;
 }
 
 interface RpcResponse {
@@ -50,9 +50,10 @@ declare class RpcClient {
     start(transport: RpcTransport): void;
     stop(): void;
     onNotification<TPayload>(id: string, callback: (payload: TPayload) => void): Subscription;
-    callT<TArgs, TResult>(method: string, args: TArgs, timeout?: number): Promise<TResult>;
-    call<TResponse>(method: string, args?: any, timeout?: number): Promise<TResponse>;
+    callT<TArgs, TResult>(method: string, args?: TArgs, timeout?: number): Promise<TResult>;
+    call<TResponse>(method: string, args?: unknown, timeout?: number): Promise<TResponse>;
     private hasPendingCall;
+    private safeStringifyArgs;
     private addPendingCall;
     private removePendingCall;
     private getPendingCall;
@@ -433,6 +434,7 @@ interface ExecuteRecipeOptions {
     batchAmount?: number;
     allowPartialBatch?: boolean;
     entity?: string;
+    requestId?: string;
 }
 interface GetActiveRunsOptions {
     roomId?: string;
@@ -447,6 +449,7 @@ interface GetAvailableRecipesOptions {
 interface Recipe {
     recipeId: string;
     entity?: string;
+    requestId?: string;
     batchAmount?: number;
 }
 interface TriggerRecipeChainOptions {
@@ -845,7 +848,8 @@ interface RundotGameMessage {
     type: string;
     direction: string;
     data?: {
-        requestId?: string;
+        /** Internal RPC correlation ID - do not confuse with user-provided requestId for idempotency */
+        _rpcId?: string;
         success?: boolean;
         value?: any;
         data?: any;
@@ -954,10 +958,16 @@ interface LoadEmbeddedAssetsResponse {
 interface SpendCurrencyOptions {
     screenName?: string;
 }
+interface OpenStoreResult {
+    /** Whether a purchase was completed during the store session */
+    purchased: boolean;
+    /** The updated balance after the store closed (saves a refetch) */
+    newBalance: number;
+}
 interface IapApi {
     getHardCurrencyBalance(): Promise<number>;
     spendCurrency(productId: string, amount: number, options?: SpendCurrencyOptions): Promise<void>;
-    openStore(): Promise<void>;
+    openStore(): Promise<OpenStoreResult>;
     getCurrencyIcon(): Promise<LoadEmbeddedAssetsResponse>;
 }
 
@@ -1092,6 +1102,136 @@ interface LeaderboardApi {
     getPodiumScores(options?: GetPodiumScoresOptions): Promise<PodiumScoresResponse>;
 }
 
+/**
+ * UGC (User-Generated Content) API
+ *
+ * Provides CRUD operations for user-generated content within H5 apps.
+ * Content is scoped per-app and persists across game versions.
+ */
+interface UgcEntry {
+    id: string;
+    appId: string;
+    authorId: string;
+    authorName: string;
+    authorAvatarUrl: string | null;
+    contentType: string;
+    data: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    isPublic: boolean;
+    title?: string;
+    tags?: string[];
+    useCount?: number;
+    likeCount?: number;
+}
+interface UgcCreateParams {
+    contentType: string;
+    data: Record<string, unknown>;
+    isPublic?: boolean;
+    title?: string;
+    tags?: string[];
+}
+interface UgcUpdateParams {
+    id: string;
+    data?: Record<string, unknown>;
+    isPublic?: boolean;
+    title?: string;
+    tags?: string[];
+}
+interface UgcListParams {
+    contentType?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface UgcBrowseParams {
+    contentType?: string;
+    cursor?: string;
+    limit?: number;
+    sortBy?: 'recent' | 'mostLiked' | 'mostUsed';
+}
+interface UgcListResponse {
+    entries: UgcEntry[];
+    nextCursor?: string;
+}
+interface UgcBrowseResponse {
+    entries: Array<UgcEntry & {
+        isLikedByMe?: boolean;
+    }>;
+    nextCursor?: string;
+}
+interface UgcReportParams {
+    id: string;
+    reason: 'inappropriate' | 'spam' | 'harassment' | 'other';
+    details?: string;
+}
+interface UgcApi {
+    /**
+     * Create new user-generated content
+     * @param params Content creation parameters
+     * @returns The created entry
+     */
+    create(params: UgcCreateParams): Promise<UgcEntry>;
+    /**
+     * Update existing content (must be author)
+     * @param params Update parameters including entry ID
+     * @returns The updated entry
+     */
+    update(params: UgcUpdateParams): Promise<UgcEntry>;
+    /**
+     * Delete content (must be author)
+     * @param id Entry ID to delete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get a single entry by ID
+     * @param id Entry ID
+     * @returns The entry or null if not found
+     */
+    get(id: string): Promise<UgcEntry | null>;
+    /**
+     * List the current user's content
+     * @param params List parameters (optional filtering and pagination)
+     * @returns Paginated list of entries
+     */
+    listMine(params?: UgcListParams): Promise<UgcListResponse>;
+    /**
+     * Browse community content (public entries only)
+     * @param params Browse parameters (optional filtering, pagination, sorting)
+     * @returns Paginated list of entries with isLikedByMe status
+     */
+    browse(params?: UgcBrowseParams): Promise<UgcBrowseResponse>;
+    /**
+     * Like an entry
+     * @param id Entry ID to like
+     * @returns Updated like count
+     */
+    like(id: string): Promise<{
+        likeCount: number;
+    }>;
+    /**
+     * Unlike an entry
+     * @param id Entry ID to unlike
+     * @returns Updated like count
+     */
+    unlike(id: string): Promise<{
+        likeCount: number;
+    }>;
+    /**
+     * Record a use of an entry (e.g., user imported/used this content)
+     * Rate limited per user per entry per day
+     * @param id Entry ID
+     * @returns Updated use count
+     */
+    recordUse(id: string): Promise<{
+        useCount: number;
+    }>;
+    /**
+     * Report an entry for moderation review
+     * @param params Report parameters
+     */
+    report(params: UgcReportParams): Promise<void>;
+}
+
 interface PreloaderApi {
     showLoadScreen(): Promise<void>;
     hideLoadScreen(): Promise<void>;
@@ -1168,6 +1308,21 @@ interface SocialApi {
     }): Promise<QRCodeResult>;
 }
 
+interface ImageGenParams {
+    prompt: string;
+    negativePrompt?: string;
+    aspectRatio?: '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9';
+    referenceImages?: string[];
+    seed?: number;
+}
+interface ImageGenResult {
+    imageUrl: string;
+    prompt: string;
+}
+interface ImageGenApi {
+    generate(params: ImageGenParams): Promise<ImageGenResult>;
+}
+
 /**
  * Safe area insets representing padding needed to avoid device notches and host UI.
  * Includes toolbar/feedHeader height + device safe areas.
@@ -1222,8 +1377,10 @@ interface Host {
     readonly rooms: RoomsApi;
     readonly logging: LoggingApi;
     readonly leaderboard: LeaderboardApi;
+    readonly ugc: UgcApi;
     readonly preloader: PreloaderApi;
     readonly social: SocialApi;
+    readonly imageGen: ImageGenApi;
     readonly isInitialized: boolean;
     readonly iap: IapApi;
     readonly context?: InitializationContext;
@@ -1532,6 +1689,7 @@ interface RundotGameAPI {
     initializeAsync(options?: InitializationOptions): Promise<InitializationContext>;
     simulation: SimulationApi;
     leaderboard: LeaderboardApi;
+    ugc: UgcApi;
     log(message: string, ...args: any[]): void;
     error(message: string, ...args: any[]): void;
     isAvailable(): boolean;
@@ -1679,6 +1837,7 @@ interface RundotGameAPI {
     notifications: NotificationsApi;
     lifecycles: LifecycleApi;
     social: SocialApi;
+    imageGen: ImageGenApi;
     context: InitializationContext;
 }
 
@@ -1696,4 +1855,4 @@ interface AdsApi {
     showInterstitialAd(options?: ShowInterstitialAdOptions): Promise<boolean>;
 }
 
-export { type AiChatCompletionRequest as $, type AnalyticsApi as A, type BatchRecipeRequirementsResult as B, type ScheduleLocalNotification as C, type ScheduleNotificationOptions as D, type PopupsApi as E, type ShowToastOptions as F, type ShowInterstitialAdOptions as G, type Host as H, type ShowRewardedAdOptions as I, type ProfileApi as J, type DeviceApi as K, type DeviceInfo as L, type EnvironmentApi as M, type NavigationApi as N, type EnvironmentInfo as O, type Profile as P, type QuitOptions as Q, type RundotGameAPI as R, type SimulationRunSummary as S, type SystemApi as T, type SafeArea as U, type CdnApi as V, type FetchFromCdnOptions as W, type TimeApi as X, type ServerTimeData as Y, type GetFutureTimeOptions as Z, type AiApi as _, type RecipeRequirementResult as a, type PlayerRankOptions as a$, type AiChatCompletionData as a0, type HapticsApi as a1, HapticFeedbackStyle as a2, type FeaturesApi as a3, type Experiment as a4, type LifecycleApi as a5, type SleepCallback as a6, type Subscription as a7, type AwakeCallback as a8, type PauseCallback as a9, type RoomMessageEvent as aA, type ProposedMoveEvent as aB, RundotGameTransport as aC, type RoomsApi as aD, type CreateRoomOptions as aE, type JoinOrCreateRoomOptions as aF, type JoinOrCreateResult as aG, type ListRoomsOptions as aH, type UpdateRoomDataOptions as aI, type RoomMessageRequest as aJ, type StartRoomGameOptions as aK, type ProposeMoveRequest as aL, type ProposeMoveResult as aM, type ValidateMoveVerdict as aN, type ValidateMoveResult as aO, type RoomSubscriptionOptions as aP, type LoggingApi as aQ, type IapApi as aR, type SpendCurrencyOptions as aS, type LoadEmbeddedAssetsResponse as aT, type SharedAssetsApi as aU, type LeaderboardApi as aV, type ScoreToken as aW, type SubmitScoreParams as aX, type SubmitScoreResult as aY, type GetPagedScoresOptions as aZ, type PagedScoresResponse as a_, type ResumeCallback as aa, type QuitCallback as ab, type SimulationApi as ac, type SimulationSlotValidationResult as ad, type SimulationBatchOperation as ae, type SimulationBatchOperationsResult as af, type SimulationAvailableItem as ag, type SimulationPowerPreview as ah, type SimulationSlotMutationResult as ai, type SimulationSlotContainer as aj, type SimulationAssignment as ak, type SimulationState as al, type ExecuteRecipeOptions as am, type ExecuteRecipeResponse as an, type CollectRecipeResult as ao, type ResetStateOptions as ap, type ResetStateResult as aq, type GetActiveRunsOptions as ar, type ExecuteScopedRecipeOptions as as, type ExecuteScopedRecipeResult as at, type GetAvailableRecipesOptions as au, type GetAvailableRecipesResult as av, type Recipe as aw, type GetBatchRecipeRequirements as ax, type TriggerRecipeChainOptions as ay, type RoomDataUpdate as az, type RundotGameSimulationStateResponse as b, type PlayerRankResult as b0, type GetPodiumScoresOptions as b1, type PodiumScoresResponse as b2, type PreloaderApi as b3, type SocialApi as b4, type ShareMetadata as b5, type ShareLinkResult as b6, type SocialQRCodeOptions as b7, type QRCodeResult as b8, type Avatar3dApi as b9, type RundotGameRoomCustomMetadata as bA, type RundotGameRoomPayload as bB, type RoomEnvelopeResponse as bC, type RoomsEnvelopeResponse as bD, type JoinOrCreateRoomEnvelopeResponse as bE, type RecipeInfo as bF, type SimulationPersonalState as bG, type SimulationRoomActiveRecipe as bH, type SimulationRoomState as bI, type SimulationBatchOperationAssign as bJ, type SimulationBatchOperationRemove as bK, type SimulationBatchOperationResult as bL, RpcSharedAssetsApi as bM, type LoadEmbeddedAssetsRequest as bN, type LeaderboardModeConfig as bO, type LeaderboardPeriodType as bP, type LeaderboardPeriodConfig as bQ, type LeaderboardAntiCheatConfig as bR, type LeaderboardDisplaySettings as bS, type LeaderboardConfig as bT, type LeaderboardEntry as bU, type PodiumScoresContext as bV, type HudInsets as bW, createHost as bX, type AssetManifest as ba, type Avatar3dConfig as bb, type ShowEditorOptions as bc, type Avatar3dEdits as bd, type AdsApi as be, type InitializationContext as bf, type InitializationOptions as bg, type AiMessage as bh, type Asset as bi, type Category as bj, MockAvatarApi as bk, type SubPath as bl, type TimeIntervalTriggerInput as bm, type NotificationTriggerInput as bn, type OnRequestCallback as bo, type OnResponseCallback as bp, type OnNotificationCallback as bq, type RpcTransport as br, type JoinRoomMatchCriteria as bs, type RoomMessageEventType as bt, type RoomMessagePayload as bu, type ProposedMovePayload as bv, ROOM_GAME_PHASES as bw, type RoomGamePhase as bx, type RundotGameRoomRulesGameState as by, type RundotGameRoomRules as bz, type SimulationUpdateType as c, type SimulationEntityUpdate as d, type SimulationActiveRunsUpdate as e, type SimulationSnapshotUpdate as f, type SimulationUpdateData as g, type SimulationSubscribeOptions as h, type RundotGameSimulationEffect as i, type RundotGameSimulationRecipe as j, type RundotGameSimulationConfig as k, type RecipeRequirementQuery as l, type RundotGameExecuteRecipeOptions as m, type RundotGameExecuteScopedRecipeOptions as n, type RundotGameAvailableRecipe as o, type RundotGameCollectRecipeResult as p, type RundotGameExecuteRecipeResult as q, RundotGameRoom as r, type RpcRequest as s, type RpcResponse as t, type RpcNotification as u, RpcClient as v, type StorageApi as w, type NavigationStackInfo as x, type PushAppOptions as y, type NotificationsApi as z };
+export { type AiChatCompletionRequest as $, type AnalyticsApi as A, type BatchRecipeRequirementsResult as B, type ScheduleLocalNotification as C, type ScheduleNotificationOptions as D, type PopupsApi as E, type ShowToastOptions as F, type ShowInterstitialAdOptions as G, type Host as H, type ShowRewardedAdOptions as I, type ProfileApi as J, type DeviceApi as K, type DeviceInfo as L, type EnvironmentApi as M, type NavigationApi as N, type EnvironmentInfo as O, type Profile as P, type QuitOptions as Q, type RundotGameAPI as R, type SimulationRunSummary as S, type SystemApi as T, type SafeArea as U, type CdnApi as V, type FetchFromCdnOptions as W, type TimeApi as X, type ServerTimeData as Y, type GetFutureTimeOptions as Z, type AiApi as _, type RecipeRequirementResult as a, type PagedScoresResponse as a$, type AiChatCompletionData as a0, type HapticsApi as a1, HapticFeedbackStyle as a2, type FeaturesApi as a3, type Experiment as a4, type LifecycleApi as a5, type SleepCallback as a6, type Subscription as a7, type AwakeCallback as a8, type PauseCallback as a9, type RoomMessageEvent as aA, type ProposedMoveEvent as aB, RundotGameTransport as aC, type RoomsApi as aD, type CreateRoomOptions as aE, type JoinOrCreateRoomOptions as aF, type JoinOrCreateResult as aG, type ListRoomsOptions as aH, type UpdateRoomDataOptions as aI, type RoomMessageRequest as aJ, type StartRoomGameOptions as aK, type ProposeMoveRequest as aL, type ProposeMoveResult as aM, type ValidateMoveVerdict as aN, type ValidateMoveResult as aO, type RoomSubscriptionOptions as aP, type LoggingApi as aQ, type IapApi as aR, type SpendCurrencyOptions as aS, type OpenStoreResult as aT, type LoadEmbeddedAssetsResponse as aU, type SharedAssetsApi as aV, type LeaderboardApi as aW, type ScoreToken as aX, type SubmitScoreParams as aY, type SubmitScoreResult as aZ, type GetPagedScoresOptions as a_, type ResumeCallback as aa, type QuitCallback as ab, type SimulationApi as ac, type SimulationSlotValidationResult as ad, type SimulationBatchOperation as ae, type SimulationBatchOperationsResult as af, type SimulationAvailableItem as ag, type SimulationPowerPreview as ah, type SimulationSlotMutationResult as ai, type SimulationSlotContainer as aj, type SimulationAssignment as ak, type SimulationState as al, type ExecuteRecipeOptions as am, type ExecuteRecipeResponse as an, type CollectRecipeResult as ao, type ResetStateOptions as ap, type ResetStateResult as aq, type GetActiveRunsOptions as ar, type ExecuteScopedRecipeOptions as as, type ExecuteScopedRecipeResult as at, type GetAvailableRecipesOptions as au, type GetAvailableRecipesResult as av, type Recipe as aw, type GetBatchRecipeRequirements as ax, type TriggerRecipeChainOptions as ay, type RoomDataUpdate as az, type RundotGameSimulationStateResponse as b, type HudInsets as b$, type PlayerRankOptions as b0, type PlayerRankResult as b1, type GetPodiumScoresOptions as b2, type PodiumScoresResponse as b3, type PreloaderApi as b4, type SocialApi as b5, type ShareMetadata as b6, type ShareLinkResult as b7, type SocialQRCodeOptions as b8, type QRCodeResult as b9, type ProposedMovePayload as bA, ROOM_GAME_PHASES as bB, type RoomGamePhase as bC, type RundotGameRoomRulesGameState as bD, type RundotGameRoomRules as bE, type RundotGameRoomCustomMetadata as bF, type RundotGameRoomPayload as bG, type RoomEnvelopeResponse as bH, type RoomsEnvelopeResponse as bI, type JoinOrCreateRoomEnvelopeResponse as bJ, type RecipeInfo as bK, type SimulationPersonalState as bL, type SimulationRoomActiveRecipe as bM, type SimulationRoomState as bN, type SimulationBatchOperationAssign as bO, type SimulationBatchOperationRemove as bP, type SimulationBatchOperationResult as bQ, RpcSharedAssetsApi as bR, type LoadEmbeddedAssetsRequest as bS, type LeaderboardModeConfig as bT, type LeaderboardPeriodType as bU, type LeaderboardPeriodConfig as bV, type LeaderboardAntiCheatConfig as bW, type LeaderboardDisplaySettings as bX, type LeaderboardConfig as bY, type LeaderboardEntry as bZ, type PodiumScoresContext as b_, type Avatar3dApi as ba, type AssetManifest as bb, type Avatar3dConfig as bc, type ShowEditorOptions as bd, type Avatar3dEdits as be, type AdsApi as bf, type ImageGenApi as bg, type ImageGenParams as bh, type ImageGenResult as bi, type UgcApi as bj, type InitializationContext as bk, type InitializationOptions as bl, type AiMessage as bm, type Asset as bn, type Category as bo, MockAvatarApi as bp, type SubPath as bq, type TimeIntervalTriggerInput as br, type NotificationTriggerInput as bs, type OnRequestCallback as bt, type OnResponseCallback as bu, type OnNotificationCallback as bv, type RpcTransport as bw, type JoinRoomMatchCriteria as bx, type RoomMessageEventType as by, type RoomMessagePayload as bz, type SimulationUpdateType as c, createHost as c0, type SimulationEntityUpdate as d, type SimulationActiveRunsUpdate as e, type SimulationSnapshotUpdate as f, type SimulationUpdateData as g, type SimulationSubscribeOptions as h, type RundotGameSimulationEffect as i, type RundotGameSimulationRecipe as j, type RundotGameSimulationConfig as k, type RecipeRequirementQuery as l, type RundotGameExecuteRecipeOptions as m, type RundotGameExecuteScopedRecipeOptions as n, type RundotGameAvailableRecipe as o, type RundotGameCollectRecipeResult as p, type RundotGameExecuteRecipeResult as q, RundotGameRoom as r, type RpcRequest as s, type RpcResponse as t, type RpcNotification as u, RpcClient as v, type StorageApi as w, type NavigationStackInfo as x, type PushAppOptions as y, type NotificationsApi as z };