@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/combat.js

@@ -0,0 +1,151 @@
+import { combatNames } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link combatBlueprint} conventions: spawn
+ * combatants, attack (server-side damage formula + death flip), arm status
+ * effects the tick automation applies over time, respawn, and — with
+ * `hostSynced` — persist host-simulated hp. Denials resolve with
+ * `success: false`.
+ *
+ * Obtained via `client.kit(appId).combat`.
+ */
+export class CombatKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = combatNames(options.typePrefix ?? '');
+    }
+    /**
+     * Spawn a combatant with a unique `combat_key` (the status-effect join
+     * key) and the `owner_user_id` mirror.
+     */
+    async spawnCombatant(input) {
+        const combatKey = input.combatKey ?? `ck-${input.ownerUserId}-${Math.random().toString(16).slice(2, 10)}`;
+        const maxHp = input.maxHp ?? 100;
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.combatantType,
+            displayName: input.displayName,
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(input.ownerUserId) },
+                { key: 'combat_key', valueType: 'string', valueJson: JSON.stringify(combatKey) },
+                { key: 'hp', valueType: 'int', valueJson: String(input.hp ?? maxHp) },
+                { key: 'max_hp', valueType: 'int', valueJson: String(maxHp) },
+                { key: 'attack', valueType: 'int', valueJson: String(input.attack ?? 10) },
+                { key: 'defense', valueType: 'int', valueJson: String(input.defense ?? 0) },
+                ...(input.properties ?? []),
+            ],
+        });
+    }
+    /** Read one combatant's state. */
+    async state(combatantId) {
+        const container = await this.gameModel.container({
+            appId: this.appId,
+            containerId: combatantId,
+        });
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), combatantId);
+        return {
+            containerId: container.containerId,
+            displayName: container.displayName,
+            ownerUserId: container.ownerUserId != null ? String(container.ownerUserId) : null,
+            combatKey: String(props.combat_key ?? ''),
+            hp: Number(props.hp ?? 0),
+            maxHp: Number(props.max_hp ?? 0),
+            attack: Number(props.attack ?? 0),
+            defense: Number(props.defense ?? 0),
+            alive: props.alive === true,
+        };
+    }
+    /**
+     * Attack a target with your combatant. The damage formula and the death
+     * flip run server-side. Resolves with the target's remaining hp.
+     */
+    async attack(attackerId, targetId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.attackFn,
+            selfContainerId: attackerId,
+            params: { target_id: targetId },
+        });
+    }
+    /**
+     * Arm a status effect against a target's `combat_key`: creates the
+     * caller's StatusEffect container (when `effectContainerId` is omitted)
+     * and invokes the gated apply function; the interval automation then
+     * ticks it server-side.
+     */
+    async applyEffect(input) {
+        let effectId = input.effectContainerId;
+        if (!effectId) {
+            const created = await this.gameModel.createContainer({
+                appId: this.appId,
+                typeName: this.names.effectType,
+                displayName: `Effect ${input.effectId}`,
+                ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            });
+            effectId = created.containerId;
+        }
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.applyEffectFn,
+            selfContainerId: effectId,
+            params: {
+                target_key: input.targetKey,
+                effect_id: input.effectId,
+                magnitude: input.magnitude,
+                ticks: input.ticks,
+            },
+        });
+    }
+    /** List the active status effects targeting a combat_key. */
+    async effects(targetKey) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.effectType,
+        });
+        const all = 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,
+                effectId: String(props.effect_id ?? ''),
+                targetKey: String(props.target_key ?? ''),
+                magnitude: Number(props.magnitude ?? 0),
+                ticksLeft: Number(props.ticks_left ?? 0),
+            };
+        }));
+        return all.filter((e) => e.ticksLeft > 0 && (targetKey === undefined || e.targetKey === targetKey));
+    }
+    /** Respawn your downed combatant at full hp. */
+    async respawn(combatantId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.respawnFn,
+            selfContainerId: combatantId,
+            params: {},
+        });
+    }
+    /** Revive a downed combatant (blueprint deployed with `reviveGroup`). */
+    async revive(combatantId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.reviveFn,
+            selfContainerId: combatantId,
+            params: {},
+        });
+    }
+    /**
+     * Persist host-simulated hp (blueprint deployed with `hostSynced: true`;
+     * `is_host` enforced server-side). Resolves with the clamped hp.
+     */
+    async syncCombatant(combatantId, hp) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.syncFn,
+            selfContainerId: combatantId,
+            params: { hp },
+        });
+    }
+}

package/dist/kit/decks.d.ts

@@ -0,0 +1,123 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link DecksKit}. Must match the deployed decks blueprint. */
+export interface DecksKitOptions {
+    /** The `typePrefix` the decks blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one card instance, as visible to the CALLER. */
+export interface KitCard {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    /**
+     * The hidden identity — non-empty only when the caller may see it (their
+     * own cards, or any revealed card via `revealedCardId`).
+     */
+    cardId: string;
+    /** The public identity (empty until played/discarded). */
+    revealedCardId: string;
+    zone: string;
+    position: number;
+}
+/**
+ * Runtime helpers for the {@link decksBlueprint} conventions: deal
+ * session-scoped cards, shuffle by dealing random positions (admin-run
+ * automation), and draw/play/discard through the zone-guarded functions.
+ * Hidden information is enforced by property visibility server-side: reads
+ * go through `containerState`, which strips other players' `card_id`.
+ *
+ * Obtained via `client.kit(appId).decks`.
+ */
+export declare class DecksKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: DecksKitOptions);
+    /**
+     * Deal a deck to a player: creates one CardInstance per card id (zone
+     * `deck`), owned by the player. Run {@link shuffle} afterwards to deal
+     * random positions.
+     */
+    deal(input: {
+        ownerUserId: Scalars['BigInt']['input'];
+        cardIds: 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;
+    }[]>;
+    /**
+     * Shuffle every deck-zone card by running the manual `assign_position`
+     * automation (admin): each card gets a fresh `rand_int` position
+     * server-side.
+     */
+    shuffle(): Promise<{
+        __typename?: "GmAutomationRun";
+        runId: string;
+        appId: string;
+        automationId: string;
+        automationName: string;
+        triggerSource: string;
+        parentRunId: string | null;
+        cascadeDepth: number;
+        startedAt: string;
+        finishedAt: string | null;
+        durationUs: number;
+        targets: number;
+        invocations: number;
+        mutations: number;
+        fnCalls: number;
+        gasUsed: number;
+        success: boolean;
+        errorMessage: string | null;
+        circuitAction: string | null;
+        computeUnits: number;
+    }>;
+    /** A player's cards in one zone, as visible to the caller. */
+    cards(ownerUserId: Scalars['BigInt']['input'] | null, options?: {
+        zone?: string;
+        sessionId?: string;
+    }): Promise<KitCard[]>;
+    /** Your hand (owner-visible card ids included by the server). */
+    myHand(ownerUserId: Scalars['BigInt']['input'], options?: {
+        sessionId?: string;
+    }): Promise<KitCard[]>;
+    /** Every card on the board (public: revealed ids). */
+    board(options?: {
+        sessionId?: string;
+    }): Promise<KitCard[]>;
+    /**
+     * Draw the top of your deck (lowest position — positions were dealt by
+     * the shuffle automation). The server enforces ownership, turn (when
+     * `turnBased`), and the deck→hand zone transition.
+     */
+    draw(ownerUserId: Scalars['BigInt']['input'], options?: {
+        sessionId?: string;
+    }): Promise<KitInvokeResult<string>>;
+    /** Draw one specific deck card (prefer {@link draw} for top-of-deck). */
+    drawCard(cardInstanceId: string, options?: {
+        sessionId?: string;
+    }): Promise<KitInvokeResult<string>>;
+    /**
+     * Play a card from your hand: the zone flip and the public reveal commit
+     * together. Resolves with the revealed card id.
+     */
+    play(cardInstanceId: string, options?: {
+        sessionId?: string;
+    }): Promise<KitInvokeResult<string>>;
+    /** Discard a card face-up. */
+    discard(cardInstanceId: string, options?: {
+        sessionId?: string;
+    }): Promise<KitInvokeResult<string>>;
+    private toCard;
+}
+//# sourceMappingURL=decks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decks.d.ts","sourceRoot":"","sources":["../../src/kit/decks.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,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oEAAoE;AACpE,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAGhB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,eAAoB;IAK/B;;;;OAIG;IACG,IAAI,CAAC,KAAK,EAAE;QAChB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAwBD;;;;OAIG;IACG,OAAO;;;;;;;;;;;;;;;;;;;;;;IAOb,8DAA8D;IACxD,KAAK,CACT,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,EAC9C,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAClD,OAAO,CAAC,OAAO,EAAE,CAAC;IA2BrB,iEAAiE;IAC3D,MAAM,CACV,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,OAAO,EAAE,CAAC;IAIrB,sDAAsD;IAChD,KAAK,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAIrE;;;;OAIG;IACG,IAAI,CACR,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IASnC,yEAAyE;IACnE,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAUnC;;;OAGG;IACG,IAAI,CACR,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAUnC,8BAA8B;IACxB,OAAO,CACX,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YAUrB,MAAM;CAsBrB"}

package/dist/kit/decks.js

@@ -0,0 +1,138 @@
+import { decksNames } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link decksBlueprint} conventions: deal
+ * session-scoped cards, shuffle by dealing random positions (admin-run
+ * automation), and draw/play/discard through the zone-guarded functions.
+ * Hidden information is enforced by property visibility server-side: reads
+ * go through `containerState`, which strips other players' `card_id`.
+ *
+ * Obtained via `client.kit(appId).decks`.
+ */
+export class DecksKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = decksNames(options.typePrefix ?? '');
+    }
+    /**
+     * Deal a deck to a player: creates one CardInstance per card id (zone
+     * `deck`), owned by the player. Run {@link shuffle} afterwards to deal
+     * random positions.
+     */
+    async deal(input) {
+        const created = [];
+        for (const [index, cardId] of input.cardIds.entries()) {
+            created.push(await this.gameModel.createContainer({
+                appId: this.appId,
+                typeName: this.names.cardType,
+                displayName: `Card ${index + 1}`,
+                ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+                properties: [
+                    {
+                        key: 'owner_user_id',
+                        valueType: 'int',
+                        valueJson: String(input.ownerUserId),
+                    },
+                    { key: 'card_id', valueType: 'string', valueJson: JSON.stringify(cardId) },
+                    { key: 'position', valueType: 'int', valueJson: String(index) },
+                ],
+            }));
+        }
+        return created;
+    }
+    /**
+     * Shuffle every deck-zone card by running the manual `assign_position`
+     * automation (admin): each card gets a fresh `rand_int` position
+     * server-side.
+     */
+    async shuffle() {
+        return this.gameModel.runAutomation({
+            appId: this.appId,
+            name: this.names.shuffleAutomation,
+        });
+    }
+    /** A player's cards in one zone, as visible to the caller. */
+    async cards(ownerUserId, options = {}) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.cardType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+        const filtered = ownerUserId === null
+            ? containers
+            : containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        const cards = await Promise.all(filtered.map((c) => this.toCard(c.containerId, c.displayName, c.ownerUserId != null ? String(c.ownerUserId) : null)));
+        return options.zone !== undefined
+            ? cards.filter((c) => c.zone === options.zone)
+            : cards;
+    }
+    /** Your hand (owner-visible card ids included by the server). */
+    async myHand(ownerUserId, options = {}) {
+        return this.cards(ownerUserId, { ...options, zone: 'hand' });
+    }
+    /** Every card on the board (public: revealed ids). */
+    async board(options = {}) {
+        return this.cards(null, { ...options, zone: 'board' });
+    }
+    /**
+     * Draw the top of your deck (lowest position — positions were dealt by
+     * the shuffle automation). The server enforces ownership, turn (when
+     * `turnBased`), and the deck→hand zone transition.
+     */
+    async draw(ownerUserId, options = {}) {
+        const deck = await this.cards(ownerUserId, { ...options, zone: 'deck' });
+        if (deck.length === 0) {
+            throw new Error('Deck is empty — nothing to draw');
+        }
+        const top = deck.reduce((a, b) => (b.position < a.position ? b : a));
+        return this.drawCard(top.containerId, options);
+    }
+    /** Draw one specific deck card (prefer {@link draw} for top-of-deck). */
+    async drawCard(cardInstanceId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.drawFn,
+            selfContainerId: cardInstanceId,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            params: {},
+        });
+    }
+    /**
+     * Play a card from your hand: the zone flip and the public reveal commit
+     * together. Resolves with the revealed card id.
+     */
+    async play(cardInstanceId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.playFn,
+            selfContainerId: cardInstanceId,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            params: {},
+        });
+    }
+    /** Discard a card face-up. */
+    async discard(cardInstanceId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.discardFn,
+            selfContainerId: cardInstanceId,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            params: {},
+        });
+    }
+    async toCard(containerId, displayName, ownerUserId) {
+        // containerState filters properties by visibility: other players' hands
+        // come back WITHOUT card_id — the hidden-info guarantee is server-side.
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), containerId);
+        return {
+            containerId,
+            displayName,
+            ownerUserId,
+            cardId: String(props.card_id ?? ''),
+            revealedCardId: String(props.revealed_card_id ?? ''),
+            zone: String(props.zone ?? ''),
+            position: Number(props.position ?? 0),
+        };
+    }
+}

package/dist/kit/economy.d.ts

@@ -0,0 +1,244 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link EconomyKit}. Must match the deployed economy blueprint. */
+export interface EconomyKitOptions {
+    /** The `typePrefix` the economy blueprint was deployed with. */
+    typePrefix?: string;
+    /** The `currencies` the blueprint was deployed with. Defaults to `['gold']`. */
+    currencies?: string[];
+}
+/** A parsed view of one wallet. */
+export interface KitWallet {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    /** Balance per currency property. */
+    balances: Record<string, number>;
+}
+/** A parsed view of one shop listing. */
+export interface KitShopListing {
+    containerId: string;
+    displayName: string;
+    itemId: string;
+    price: number;
+    stock: number;
+    maxStock: number;
+}
+/** A parsed view of one escrow trade offer. */
+export interface KitTradeOffer {
+    containerId: string;
+    displayName: string;
+    /** The offer creator (server-assigned container owner). */
+    fromUserId: string | null;
+    toUserId: number;
+    giveStackId: string;
+    receiveStackId: string;
+    giveItemId: string;
+    giveQty: number;
+    wantItemId: string;
+    wantQty: number;
+    status: string;
+}
+/** A parsed view of one market listing. */
+export interface KitMarketListing {
+    containerId: string;
+    displayName: string;
+    /** The seller (server-assigned container owner). */
+    sellerUserId: string | null;
+    stackId: string;
+    itemId: string;
+    quantity: number;
+    price: number;
+    active: boolean;
+}
+/**
+ * Runtime helpers for the {@link economyBlueprint} conventions: wallets with
+ * per-currency balances, shop purchases, escrow trades, and player market
+ * listings. Every movement of currency or items is a single gated invoke —
+ * balances, stock, item identity, and ownership are all verified
+ * server-side, and a denial resolves with `success: false` (never an
+ * exception).
+ *
+ * `earn` is a trusted grant: with the default blueprint authority
+ * (`'server'`) it succeeds only for app admins — call it from studio/backend
+ * code, or drive grants through automations instead.
+ *
+ * Obtained via `client.kit(appId).economy`.
+ */
+export declare class EconomyKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    private readonly typePrefix;
+    private readonly currencies;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: EconomyKitOptions);
+    private get defaultCurrency();
+    /**
+     * Find the player's wallet, creating it when absent (member-instantiable;
+     * the server assigns ownership to the caller). Sets the `owner_user_id`
+     * mirror property the blueprint's guards read.
+     *
+     * @param ownerUserId - The calling player's user id (decimal string).
+     */
+    ensureWallet(ownerUserId: Scalars['BigInt']['input'], options?: {
+        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;
+    }>;
+    /** Read one currency balance (default: the blueprint's first currency). */
+    balance(walletId: string, currency?: string): Promise<number>;
+    /** Read a wallet with every configured currency balance parsed. */
+    wallet(walletId: string): Promise<KitWallet>;
+    /**
+     * Mint currency into a wallet — a **trusted** grant (default blueprint
+     * authority: app admins only). Resolves with the new balance.
+     */
+    earn(walletId: string, amount: number, currency?: string): Promise<KitInvokeResult<number>>;
+    /**
+     * Spend currency from the caller's own wallet. The server refuses to
+     * overdraw. Resolves with the new balance.
+     */
+    spend(walletId: string, amount: number, currency?: string): Promise<KitInvokeResult<number>>;
+    /** Shop (admin-priced listings; atomic buys). */
+    readonly shop: {
+        /**
+         * Create a shop listing (admin — the type is admin-instantiable).
+         * `maxStock` feeds the optional restock automation.
+         */
+        create: (input: {
+            displayName: string;
+            itemId: string;
+            price: number;
+            stock?: number;
+            maxStock?: number;
+            properties?: SeedPropertyInput[];
+        }) => Promise<{
+            __typename?: "GmContainer";
+            containerId: string;
+            appId: string;
+            sessionId: string | null;
+            typeName: string;
+            displayName: string;
+            description: string | null;
+            ownerUserId: string | null;
+            metadataJson: string;
+        }>;
+        /** List shop listings with parsed state. */
+        list: () => Promise<KitShopListing[]>;
+        /**
+         * Buy one unit: wallet debit + stock decrement + item grant into
+         * `toStackId` (a stack of the listed item), all in one transaction.
+         * Resolves with the wallet's remaining balance.
+         */
+        buy: (input: {
+            listingId: string;
+            walletId: string;
+            toStackId: string;
+        }) => Promise<KitInvokeResult<number>>;
+    };
+    /** Escrow trades (player↔player item swaps, atomic on accept). */
+    readonly trades: {
+        /**
+         * Create a trade offer to another player. The stacks named here are the
+         * OFFERER's: `giveStackId` is the escrowed source, `receiveStackId`
+         * receives the wanted items when the trade is accepted. The offer's
+         * container ownership (server-assigned to the caller) is what the accept
+         * guards trust — a forged offer over someone else's stacks can never be
+         * accepted.
+         */
+        offer: (input: {
+            toUserId: Scalars["BigInt"]["input"];
+            giveStackId: string;
+            giveItemId: string;
+            giveQty: number;
+            wantItemId: string;
+            wantQty: number;
+            receiveStackId: 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;
+        }>;
+        /**
+         * Accept a trade as the invited player, supplying YOUR two stacks: the
+         * one paying the wanted items and the one receiving the given items. The
+         * offerer's stacks come from the offer record. All four quantity writes
+         * commit atomically or not at all.
+         */
+        accept: (input: {
+            offerId: string;
+            wantStackId: string;
+            toGiveStackId: string;
+        }) => Promise<KitInvokeResult<string>>;
+        /** Cancel an open trade (either party may). */
+        cancel: (offerId: string) => Promise<KitInvokeResult<string>>;
+        /** Read one trade offer with parsed state. */
+        get: (offerId: string) => Promise<KitTradeOffer>;
+        /** List trades the user created or was invited to (open ones first). */
+        listMine: (userId: Scalars["BigInt"]["input"]) => Promise<KitTradeOffer[]>;
+    };
+    /** Player market (list a stack for currency; atomic purchases). */
+    readonly market: {
+        /**
+         * List items for sale: names YOUR escrowed source stack and the ask
+         * price. Payment lands straight in your wallet when someone buys.
+         */
+        list: (input: {
+            stackId: string;
+            itemId: string;
+            quantity: number;
+            price: number;
+            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;
+        }>;
+        /** Browse market listings (active ones only by default). */
+        browse: (options?: {
+            includeInactive?: boolean;
+        }) => Promise<KitMarketListing[]>;
+        /**
+         * Buy a market listing: pays the seller's wallet and transfers the items
+         * into `toStackId` in one transaction. The seller's wallet and source
+         * stack are resolved from the listing. Resolves with the buyer wallet's
+         * remaining balance.
+         */
+        buy: (input: {
+            listingId: string;
+            walletId: string;
+            toStackId: string;
+        }) => Promise<KitInvokeResult<number>>;
+        /** Take a listing down (seller only). */
+        cancel: (listingId: string) => Promise<KitInvokeResult<boolean>>;
+    };
+    /** Find an existing wallet container id for a user (no creation). */
+    private ensureSellerWallet;
+    private toTrade;
+}
+//# sourceMappingURL=economy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"economy.d.ts","sourceRoot":"","sources":["../../src/kit/economy.ts"],"names":[],"mappings":"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"}