@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/kit.d.ts

@@ -1,17 +1,51 @@
+import type { ChannelsAPI } from '../domains/channels.js';
 import type { GameAppsAPI } from '../domains/gameApps.js';
 import type { GameModelAPI } from '../domains/gameModel.js';
+import type { TeamsAPI } from '../domains/teams.js';
+import type { UdpAPI } from '../domains/udp.js';
 import type { GameModelSeedMutation, GameModelUpsertAutomationMutation, GameModelUpsertAutomationTriggerMutation, Scalars } from '../generated/graphql.js';
-import { type KitBlueprint } from './blueprints.js';
+import { type KitBlueprint } from './blueprints/index.js';
+import { CombatKit, type CombatKitOptions } from './combat.js';
+import { DecksKit, type DecksKitOptions } from './decks.js';
+import { EconomyKit, type EconomyKitOptions } from './economy.js';
+import { FeaturesKit } from './features.js';
 import { InventoryKit, type InventoryKitOptions } from './inventory.js';
+import { LeaderboardsKit, type LeaderboardsKitOptions } from './leaderboards.js';
+import { LootKit, type LootKitOptions } from './loot.js';
 import { NpcsKit, type NpcsKitOptions } from './npcs.js';
 import { ObjectsKit, type ObjectsKitOptions } from './objects.js';
 import { PlotsKit, type PlotsKitOptions } from './plots.js';
+import { MatchesKit, type MatchesKitOptions } from './matches.js';
+import { ProgressionKit, type ProgressionKitOptions } from './progression.js';
+import { QuestsKit, type QuestsKitOptions } from './quests.js';
+import { SocialKit, type SocialKitOptions } from './social.js';
+import { WorldsimKit, type WorldsimKitOptions } from './worldsim.js';
 /** Options for {@link GameKitClient}, configuring the runtime helpers to match your deployed blueprints. */
 export interface GameKitOptions {
     inventory?: InventoryKitOptions;
     objects?: ObjectsKitOptions;
     npcs?: NpcsKitOptions;
     plots?: PlotsKitOptions;
+    economy?: EconomyKitOptions;
+    progression?: ProgressionKitOptions;
+    loot?: LootKitOptions;
+    quests?: QuestsKitOptions;
+    combat?: CombatKitOptions;
+    matches?: MatchesKitOptions;
+    decks?: DecksKitOptions;
+    worldsim?: WorldsimKitOptions;
+    social?: SocialKitOptions;
+    leaderboards?: LeaderboardsKitOptions;
+}
+/**
+ * The extra (non-model) domains some kit helpers compose: channels + udp for
+ * matches (notify-to-pull) and social chat, teams for parties/guilds.
+ * `client.kit(appId)` wires them automatically.
+ */
+export interface GameKitDomains {
+    channels?: ChannelsAPI;
+    teams?: TeamsAPI;
+    udp?: UdpAPI;
 }
 /** The result of {@link GameKitClient.deploy}: the seed outcome plus each automation/trigger upserted. */
 export interface KitDeployResult {
@@ -70,7 +104,29 @@ export declare class GameKitClient {
     readonly npcs: NpcsKit;
     /** Plot helpers (buy/rent land with transactional, enforced grid grants). */
     readonly plots: PlotsKit;
-    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, gameApps: GameAppsAPI, options?: GameKitOptions);
+    /** Economy helpers (wallets, shops, escrow trades, player market). */
+    readonly economy: EconomyKit;
+    /** Progression helpers (xp/levels, skills, achievements, rating). */
+    readonly progression: ProgressionKit;
+    /** Loot helpers (server-rolled weighted tables, atomic claims). */
+    readonly loot: LootKit;
+    /** Quest helpers (catalog, progress, atomic reward turn-in, daily resets). */
+    readonly quests: QuestsKit;
+    /** Combat helpers (server-authoritative attacks, status effects, respawn). */
+    readonly combat: CombatKit;
+    /** Match helpers (lobbies, rounds, turns, scores, notify-to-pull channels). */
+    readonly matches: MatchesKit;
+    /** Deck helpers (hidden hands via owner visibility, server-dealt shuffles). */
+    readonly decks: DecksKit;
+    /** World simulation helpers (clock/weather, nodes, crops, wave counters). */
+    readonly worldsim: WorldsimKit;
+    /** Social helpers (parties, guilds, chat over teams + channels). */
+    readonly social: SocialKit;
+    /** Leaderboard helpers (trusted submits, client-side ranking, seasons). */
+    readonly leaderboards: LeaderboardsKit;
+    /** Monetization helpers (feature keys, tier grants, featureGate policies). */
+    readonly features: FeaturesKit;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, gameApps: GameAppsAPI, options?: GameKitOptions, domains?: GameKitDomains);
     /**
      * Helpers for an additional lockable object type deployed under a different
      * type name (e.g. both `Door` and `Chest` lock blueprints in one app).

package/dist/kit/kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/kit/kit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EACV,qBAAqB,EACrB,iCAAiC,EACjC,wCAAwC,EACxC,OAAO,EACR,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5D,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,0GAA0G;AAC1G,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAC7C,WAAW,EAAE,iCAAiC,CAAC,2BAA2B,CAAC,EAAE,CAAC;IAC9E,kBAAkB,EAAE,wCAAwC,CAAC,kCAAkC,CAAC,EAAE,CAAC;IACnG,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,aAAa;IAWtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAGN,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAQ9B;;;OAGG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU;IAOpE;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,UAAU,EAAE,YAAY,GAAG,YAAY,EAAE,EACzC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC;CAsB5B"}
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/kit/kit.ts"],"names":[],"mappings":"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"}

package/dist/kit/kit.js

@@ -1,8 +1,19 @@
-import { mergeBlueprints } from './blueprints.js';
+import { mergeBlueprints } from './blueprints/index.js';
+import { CombatKit } from './combat.js';
+import { DecksKit } from './decks.js';
+import { EconomyKit } from './economy.js';
+import { FeaturesKit } from './features.js';
 import { InventoryKit } from './inventory.js';
+import { LeaderboardsKit } from './leaderboards.js';
+import { LootKit } from './loot.js';
 import { NpcsKit } from './npcs.js';
 import { ObjectsKit } from './objects.js';
 import { PlotsKit } from './plots.js';
+import { MatchesKit } from './matches.js';
+import { ProgressionKit } from './progression.js';
+import { QuestsKit } from './quests.js';
+import { SocialKit } from './social.js';
+import { WorldsimKit } from './worldsim.js';
 /**
  * App-scoped **Game Kit** facade returned by `client.kit(appId)` — high-level
  * building blocks that map traditional game concepts (inventory, lockable
@@ -42,13 +53,24 @@ import { PlotsKit } from './plots.js';
  * ```
  */
 export class GameKitClient {
-    constructor(appId, gameModel, gameApps, options = {}) {
+    constructor(appId, gameModel, gameApps, options = {}, domains = {}) {
         this.appId = appId;
         this.gameModel = gameModel;
         this.inventory = new InventoryKit(appId, gameModel, options.inventory);
         this.objects = new ObjectsKit(appId, gameModel, options.objects);
         this.npcs = new NpcsKit(appId, gameModel, options.npcs);
         this.plots = new PlotsKit(appId, gameModel, gameApps, options.plots);
+        this.economy = new EconomyKit(appId, gameModel, options.economy);
+        this.progression = new ProgressionKit(appId, gameModel, options.progression);
+        this.loot = new LootKit(appId, gameModel, options.loot);
+        this.quests = new QuestsKit(appId, gameModel, options.quests);
+        this.combat = new CombatKit(appId, gameModel, options.combat);
+        this.matches = new MatchesKit(appId, gameModel, domains.channels, domains.udp, options.matches);
+        this.decks = new DecksKit(appId, gameModel, options.decks);
+        this.worldsim = new WorldsimKit(appId, gameModel, options.worldsim);
+        this.social = new SocialKit(appId, domains.teams, domains.channels, domains.udp, gameApps, options.social);
+        this.leaderboards = new LeaderboardsKit(appId, gameModel, options.leaderboards);
+        this.features = new FeaturesKit(appId, gameModel);
     }
     /**
      * Helpers for an additional lockable object type deployed under a different

package/dist/kit/leaderboards.d.ts

@@ -0,0 +1,66 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link LeaderboardsKit}. Must match the deployed blueprint. */
+export interface LeaderboardsKitOptions {
+    /** The `typePrefix` the leaderboards blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one leaderboard entry. */
+export interface KitLeaderboardEntry {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    boardId: string;
+    score: number;
+    season: number;
+    /** 1-based position AFTER client-side sorting (not the stamped `rank` property). */
+    position: number;
+}
+/**
+ * Runtime helpers for the {@link leaderboardsBlueprint} conventions: ensure
+ * per-player entries, submit scores (trusted — host by default), and rank.
+ * There is no server-side ORDER BY on container lists, so reads fetch a
+ * board's entries and sort client-side — fine for the few hundred entries a
+ * per-app board holds.
+ *
+ * Obtained via `client.kit(appId).leaderboards`.
+ */
+export declare class LeaderboardsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LeaderboardsKitOptions);
+    /** Find-or-create a player's entry on a board. */
+    ensureEntry(ownerUserId: Scalars['BigInt']['input'], boardId: string, options?: {
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Submit a score — a **trusted** call (host by default per the blueprint's
+     * `submitAuthority`). Resolves with the entry's (possibly kept-best)
+     * score.
+     */
+    submit(entryId: string, points: number): Promise<KitInvokeResult<number>>;
+    /** All entries of one board, sorted best-first with 1-based positions. */
+    board(boardId: string): Promise<KitLeaderboardEntry[]>;
+    /** The top `n` of a board (client-side ranking). */
+    top(boardId: string, n?: number): Promise<KitLeaderboardEntry[]>;
+    /**
+     * The entries around one player on a board (`radius` above and below),
+     * for "your neighborhood" widgets.
+     */
+    around(boardId: string, userId: Scalars['BigInt']['input'], radius?: number): Promise<KitLeaderboardEntry[]>;
+    /** The board's current season (max season across its entries; 1 when empty). */
+    season(boardId: string): Promise<number>;
+}
+//# sourceMappingURL=leaderboards.d.ts.map

package/dist/kit/leaderboards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaderboards.d.ts","sourceRoot":"","sources":["../../src/kit/leaderboards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAKvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAGvB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,sBAA2B;IAKtC,kDAAkD;IAC5C,WAAW,CACf,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAqBxC;;;;OAIG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS/E,0EAA0E;IACpE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA6B5D,oDAAoD;IAC9C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,SAAK,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAIlE;;;OAGG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAClC,MAAM,SAAI,GACT,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAOjC,gFAAgF;IAC1E,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAI/C"}

package/dist/kit/leaderboards.js

@@ -0,0 +1,94 @@
+import { leaderboardsNames, } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link leaderboardsBlueprint} conventions: ensure
+ * per-player entries, submit scores (trusted — host by default), and rank.
+ * There is no server-side ORDER BY on container lists, so reads fetch a
+ * board's entries and sort client-side — fine for the few hundred entries a
+ * per-app board holds.
+ *
+ * Obtained via `client.kit(appId).leaderboards`.
+ */
+export class LeaderboardsKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = leaderboardsNames(options.typePrefix ?? '');
+    }
+    /** Find-or-create a player's entry on a board. */
+    async ensureEntry(ownerUserId, boardId, options = {}) {
+        const entries = await this.board(boardId);
+        const mine = entries.find((e) => e.ownerUserId === String(ownerUserId));
+        if (mine) {
+            return this.gameModel.container({
+                appId: this.appId,
+                containerId: mine.containerId,
+            });
+        }
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.entryType,
+            displayName: options.displayName ?? `${boardId} ${ownerUserId}`,
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(ownerUserId) },
+                { key: 'board_id', valueType: 'string', valueJson: JSON.stringify(boardId) },
+            ],
+        });
+    }
+    /**
+     * Submit a score — a **trusted** call (host by default per the blueprint's
+     * `submitAuthority`). Resolves with the entry's (possibly kept-best)
+     * score.
+     */
+    async submit(entryId, points) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.submitFn,
+            selfContainerId: entryId,
+            params: { points },
+        });
+    }
+    /** All entries of one board, sorted best-first with 1-based positions. */
+    async board(boardId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.entryType,
+        });
+        const rows = await Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                boardId: String(props.board_id ?? ''),
+                score: Number(props.score ?? 0),
+                season: Number(props.season ?? 1),
+                position: 0,
+            };
+        }));
+        return rows
+            .filter((r) => r.boardId === boardId)
+            .sort((a, b) => b.score - a.score)
+            .map((r, i) => ({ ...r, position: i + 1 }));
+    }
+    /** The top `n` of a board (client-side ranking). */
+    async top(boardId, n = 10) {
+        return (await this.board(boardId)).slice(0, n);
+    }
+    /**
+     * The entries around one player on a board (`radius` above and below),
+     * for "your neighborhood" widgets.
+     */
+    async around(boardId, userId, radius = 2) {
+        const entries = await this.board(boardId);
+        const index = entries.findIndex((e) => e.ownerUserId === String(userId));
+        if (index === -1)
+            return [];
+        return entries.slice(Math.max(0, index - radius), index + radius + 1);
+    }
+    /** The board's current season (max season across its entries; 1 when empty). */
+    async season(boardId) {
+        const entries = await this.board(boardId);
+        return entries.reduce((max, e) => Math.max(max, e.season), 1);
+    }
+}

package/dist/kit/loot.d.ts

@@ -0,0 +1,106 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link LootKit}. Must match the deployed loot blueprint. */
+export interface LootKitOptions {
+    /** The `typePrefix` the loot blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one loot roll. */
+export interface KitLootRoll {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    tableId: string;
+    /** Empty until rolled. */
+    rolledItemId: string;
+    rolledQty: number;
+    claimed: boolean;
+}
+/**
+ * Runtime helpers for the {@link lootBlueprint} conventions: create durable
+ * `LootRoll` containers, roll them (trusted — app admins by default, or the
+ * blueprint's event-drop automations), and claim results atomically into an
+ * item stack. The weighted selection runs entirely server-side from a stored
+ * seed, so clients can neither pick their loot nor claim it twice.
+ *
+ * Obtained via `client.kit(appId).loot`.
+ */
+export declare class LootKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    private readonly typePrefix;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LootKitOptions);
+    /**
+     * Create an unrolled `LootRoll` for a table, owned by `ownerUserId` (who
+     * will claim it). Event-drop automations pick from the pool of unrolled
+     * rolls — create a few ahead of time for tables wired to `drops`.
+     */
+    createRoll(input: {
+        ownerUserId: Scalars['BigInt']['input'];
+        tableId: string;
+        displayName?: string;
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Roll a table on an unrolled `LootRoll` — a **trusted** call (default
+     * blueprint authority: app admins). Resolves with the rolled item id.
+     *
+     * @param tableId - The roll container's table (derives the function name);
+     *   read from the container when omitted.
+     */
+    roll(rollId: string, tableId?: string): Promise<KitInvokeResult<string>>;
+    /**
+     * Claim a rolled loot into a caller-owned stack of the rolled item. The
+     * claimed flag and the grant commit atomically. Resolves with the granted
+     * quantity.
+     */
+    claim(rollId: string, toStackId: string): Promise<KitInvokeResult<number>>;
+    /** Read one roll's state. */
+    state(rollId: string): Promise<KitLootRoll>;
+    /**
+     * List a player's rolls, optionally filtered to one table and/or to
+     * unclaimed rolled loot (the "your drops" screen).
+     */
+    rolls(ownerUserId: Scalars['BigInt']['input'], options?: {
+        tableId?: string;
+        unclaimedOnly?: boolean;
+    }): Promise<KitLootRoll[]>;
+    /**
+     * Roll/claim audit history from the model event log (each roll records its
+     * seed, item, and quantity as applied mutations).
+     */
+    history(options?: {
+        tableId?: string;
+        limit?: number;
+    }): Promise<{
+        __typename?: "GmEvent";
+        eventId: string;
+        sessionId: string | null;
+        functionName: string;
+        selfContainerId: string | null;
+        callerUserId: string | null;
+        callerKind: string;
+        automationId: string | null;
+        paramsJson: string;
+        mutationsAppliedJson: string;
+        permissionEffectsAppliedJson: string;
+        returnValueJson: string | null;
+        success: boolean;
+        errorMessage: string | null;
+        executedAt: string;
+    }[]>;
+    private toRoll;
+}
+//# sourceMappingURL=loot.d.ts.map

package/dist/kit/loot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loot.d.ts","sourceRoot":"","sources":["../../src/kit/loot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,cAAmB;IAM9B;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAqBD;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAU9E;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAShF,6BAA6B;IACvB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYjD;;;OAGG;IACG,KAAK,CACT,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1D,OAAO,CAAC,WAAW,EAAE,CAAC;IAwBzB;;;OAGG;IACG,OAAO,CACX,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;;;;;;;YAYtC,MAAM;CAoBrB"}

package/dist/kit/loot.js

@@ -0,0 +1,120 @@
+import { lootNames, lootRollFn } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link lootBlueprint} conventions: create durable
+ * `LootRoll` containers, roll them (trusted — app admins by default, or the
+ * blueprint's event-drop automations), and claim results atomically into an
+ * item stack. The weighted selection runs entirely server-side from a stored
+ * seed, so clients can neither pick their loot nor claim it twice.
+ *
+ * Obtained via `client.kit(appId).loot`.
+ */
+export class LootKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.typePrefix = options.typePrefix ?? '';
+        this.names = lootNames(this.typePrefix);
+    }
+    /**
+     * Create an unrolled `LootRoll` for a table, owned by `ownerUserId` (who
+     * will claim it). Event-drop automations pick from the pool of unrolled
+     * rolls — create a few ahead of time for tables wired to `drops`.
+     */
+    async createRoll(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.rollType,
+            displayName: input.displayName ?? `Roll ${input.tableId}`,
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties: [
+                {
+                    key: 'owner_user_id',
+                    valueType: 'int',
+                    valueJson: String(input.ownerUserId),
+                },
+                {
+                    key: 'table_id',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(input.tableId),
+                },
+            ],
+        });
+    }
+    /**
+     * Roll a table on an unrolled `LootRoll` — a **trusted** call (default
+     * blueprint authority: app admins). Resolves with the rolled item id.
+     *
+     * @param tableId - The roll container's table (derives the function name);
+     *   read from the container when omitted.
+     */
+    async roll(rollId, tableId) {
+        const table = tableId ?? (await this.state(rollId)).tableId;
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: lootRollFn(table, this.typePrefix),
+            selfContainerId: rollId,
+            params: {},
+        });
+    }
+    /**
+     * Claim a rolled loot into a caller-owned stack of the rolled item. The
+     * claimed flag and the grant commit atomically. Resolves with the granted
+     * quantity.
+     */
+    async claim(rollId, toStackId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.claimFn,
+            selfContainerId: rollId,
+            params: { to_stack_id: toStackId },
+        });
+    }
+    /** Read one roll's state. */
+    async state(rollId) {
+        const container = await this.gameModel.container({
+            appId: this.appId,
+            containerId: rollId,
+        });
+        return this.toRoll(container.containerId, container.displayName, container.ownerUserId != null ? String(container.ownerUserId) : null);
+    }
+    /**
+     * List a player's rolls, optionally filtered to one table and/or to
+     * unclaimed rolled loot (the "your drops" screen).
+     */
+    async rolls(ownerUserId, options = {}) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.rollType,
+        });
+        const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        const rolls = await Promise.all(mine.map((c) => this.toRoll(c.containerId, c.displayName, c.ownerUserId != null ? String(c.ownerUserId) : null)));
+        return rolls.filter((r) => (options.tableId === undefined || r.tableId === options.tableId) &&
+            (!options.unclaimedOnly || (!r.claimed && r.rolledItemId !== '')));
+    }
+    /**
+     * Roll/claim audit history from the model event log (each roll records its
+     * seed, item, and quantity as applied mutations).
+     */
+    async history(options = {}) {
+        return this.gameModel.events({
+            appId: this.appId,
+            functionName: options.tableId !== undefined
+                ? lootRollFn(options.tableId, this.typePrefix)
+                : this.names.claimFn,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        });
+    }
+    async toRoll(containerId, displayName, ownerUserId) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), containerId);
+        return {
+            containerId,
+            displayName,
+            ownerUserId,
+            tableId: String(props.table_id ?? ''),
+            rolledItemId: String(props.rolled_item_id ?? ''),
+            rolledQty: Number(props.rolled_qty ?? 0),
+            claimed: props.claimed === true,
+        };
+    }
+}