@crowdedkingdoms/crowdyjs 8.1.0 → 8.3.0

package/dist/kit/progression.d.ts

@@ -0,0 +1,181 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link ProgressionKit}. Must match the deployed blueprint. */
+export interface ProgressionKitOptions {
+    /** The `typePrefix` the progression blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one player's progression. */
+export interface KitProgress {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    xp: number;
+    level: number;
+    skillPoints: number;
+    rating: number;
+}
+/** A parsed view of one skill catalog row. */
+export interface KitSkillDef {
+    containerId: string;
+    displayName: string;
+    skillId: string;
+    cost: number;
+    requiresSkillId: string;
+    maxRank: number;
+}
+/** A parsed view of one player skill rank. */
+export interface KitSkillRank {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    skillId: string;
+    rank: number;
+}
+/** A parsed view of one achievement definition. */
+export interface KitAchievementDef {
+    containerId: string;
+    displayName: string;
+    achievementId: string;
+    threshold: number;
+}
+/** A parsed view of one player achievement unlock. */
+export interface KitAchievementUnlock {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    achievementId: string;
+    unlocked: boolean;
+}
+/**
+ * Runtime helpers for the {@link progressionBlueprint} conventions: ensure a
+ * player's `Progress`, grant XP (trusted — app admins by default), buy
+ * skills against the catalog's costs and prerequisites, unlock threshold
+ * achievements, and apply match rating results. Everything is
+ * authority-checked server-side; denials resolve with `success: false`.
+ *
+ * Obtained via `client.kit(appId).progression`.
+ */
+export declare class ProgressionKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: ProgressionKitOptions);
+    /**
+     * Find the player's Progress container, creating it when absent (with the
+     * `owner_user_id` mirror the guards read).
+     */
+    ensure(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 player's progression state. */
+    state(progressId: string): Promise<KitProgress>;
+    /**
+     * Grant XP — a **trusted** call (default blueprint authority: app admins
+     * via server scope; or drive it from an event automation). Awards skill
+     * points and levels up when the curve is crossed. Resolves with the new
+     * level.
+     */
+    grantXp(progressId: string, amount: number): Promise<KitInvokeResult<number>>;
+    /** List the skill catalog (admin-seeded SkillDef containers). */
+    skillCatalog(): Promise<KitSkillDef[]>;
+    /** Define a skill (admin — the catalog type is admin-instantiable). */
+    defineSkill(input: {
+        skillId: string;
+        cost?: number;
+        requiresSkillId?: string;
+        maxRank?: number;
+        displayName?: string;
+        properties?: SeedPropertyInput[];
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Find-or-create the caller's SkillRank row for a skill (rank 0 until
+     * bought).
+     */
+    ensureSkillRank(ownerUserId: Scalars['BigInt']['input'], skillId: 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;
+    }>;
+    /**
+     * Buy one rank of a skill. `prereqRankId` is the caller's SkillRank for
+     * the prerequisite skill; omit it for skills without one (the rank row
+     * itself is passed to satisfy the required param — the condition ignores
+     * it when the def declares no prerequisite).
+     */
+    buySkill(input: {
+        skillRankId: string;
+        progressId: string;
+        skillDefId: string;
+        prereqRankId?: string;
+    }): Promise<KitInvokeResult<number>>;
+    /** List a player's skill ranks. */
+    skills(ownerUserId: Scalars['BigInt']['input']): Promise<KitSkillRank[]>;
+    /** List the achievement catalog (admin-seeded AchievementDef containers). */
+    achievementCatalog(): Promise<KitAchievementDef[]>;
+    /** Define an achievement (admin). */
+    defineAchievement(input: {
+        achievementId: string;
+        threshold: number;
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List a player's achievement unlocks. */
+    achievements(ownerUserId: Scalars['BigInt']['input']): Promise<KitAchievementUnlock[]>;
+    /**
+     * Unlock an achievement once its xp threshold is met. Creates the caller's
+     * unlock row when absent, then invokes the gated function (idempotent).
+     */
+    unlockAchievement(input: {
+        ownerUserId: Scalars['BigInt']['input'];
+        progressId: string;
+        achievementDefId: string;
+        achievementId: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /**
+     * Apply a match result as a rating delta (trusted — host-gated by
+     * default; `kit.matches` computes the delta). Resolves with the new
+     * rating.
+     */
+    applyMatchResult(progressId: string, delta: number): Promise<KitInvokeResult<number>>;
+}
+//# sourceMappingURL=progression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progression.d.ts","sourceRoot":"","sources":["../../src/kit/progression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAK1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;gBAGtB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,qBAA0B;IAKrC;;;OAGG;IACG,MAAM,CACV,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAsB5D,2CAA2C;IACrC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAqBrD;;;;;OAKG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IASnF,iEAAiE;IAC3D,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAwB5C,uEAAuE;IACjE,WAAW,CAAC,KAAK,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAClC;;;;;;;;;;;IAmBD;;;OAGG;IACG,eAAe,CACnB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAqBxC;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAapC,mCAAmC;IAC7B,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA0B9E,6EAA6E;IACvE,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsBxD,qCAAqC;IAC/B,iBAAiB,CAAC,KAAK,EAAE;QAC7B,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IAgBD,2CAA2C;IACrC,YAAY,CAChB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GACtC,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA0BlC;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAC7B,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IA+BrC;;;;OAIG;IACG,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CAQpC"}

package/dist/kit/progression.js

@@ -0,0 +1,265 @@
+import { progressionNames, } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link progressionBlueprint} conventions: ensure a
+ * player's `Progress`, grant XP (trusted — app admins by default), buy
+ * skills against the catalog's costs and prerequisites, unlock threshold
+ * achievements, and apply match rating results. Everything is
+ * authority-checked server-side; denials resolve with `success: false`.
+ *
+ * Obtained via `client.kit(appId).progression`.
+ */
+export class ProgressionKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = progressionNames(options.typePrefix ?? '');
+    }
+    /**
+     * Find the player's Progress container, creating it when absent (with the
+     * `owner_user_id` mirror the guards read).
+     */
+    async ensure(ownerUserId, options = {}) {
+        const existing = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.progressType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+        const mine = existing.find((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        if (mine)
+            return mine;
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.progressType,
+            displayName: options.displayName ?? `Progress ${ownerUserId}`,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(ownerUserId) },
+            ],
+        });
+    }
+    /** Read one player's progression state. */
+    async state(progressId) {
+        const container = await this.gameModel.container({
+            appId: this.appId,
+            containerId: progressId,
+        });
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), progressId);
+        return {
+            containerId: container.containerId,
+            displayName: container.displayName,
+            ownerUserId: container.ownerUserId != null ? String(container.ownerUserId) : null,
+            xp: Number(props.xp ?? 0),
+            level: Number(props.level ?? 1),
+            skillPoints: Number(props.skill_points ?? 0),
+            rating: Number(props.rating ?? 0),
+        };
+    }
+    /**
+     * Grant XP — a **trusted** call (default blueprint authority: app admins
+     * via server scope; or drive it from an event automation). Awards skill
+     * points and levels up when the curve is crossed. Resolves with the new
+     * level.
+     */
+    async grantXp(progressId, amount) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.grantXpFn,
+            selfContainerId: progressId,
+            params: { amount },
+        });
+    }
+    /** List the skill catalog (admin-seeded SkillDef containers). */
+    async skillCatalog() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.skillDefType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                skillId: String(props.skill_id ?? ''),
+                cost: Number(props.cost ?? 1),
+                requiresSkillId: String(props.requires_skill_id ?? ''),
+                maxRank: Number(props.max_rank ?? 1),
+            };
+        }));
+    }
+    /** Define a skill (admin — the catalog type is admin-instantiable). */
+    async defineSkill(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.skillDefType,
+            displayName: input.displayName ?? `Skill ${input.skillId}`,
+            properties: [
+                { key: 'skill_id', valueType: 'string', valueJson: JSON.stringify(input.skillId) },
+                { key: 'cost', valueType: 'int', valueJson: String(input.cost ?? 1) },
+                {
+                    key: 'requires_skill_id',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(input.requiresSkillId ?? ''),
+                },
+                { key: 'max_rank', valueType: 'int', valueJson: String(input.maxRank ?? 1) },
+                ...(input.properties ?? []),
+            ],
+        });
+    }
+    /**
+     * Find-or-create the caller's SkillRank row for a skill (rank 0 until
+     * bought).
+     */
+    async ensureSkillRank(ownerUserId, skillId, options = {}) {
+        const mine = await this.skills(ownerUserId);
+        const existing = mine.find((s) => s.skillId === skillId);
+        if (existing) {
+            return this.gameModel.container({
+                appId: this.appId,
+                containerId: existing.containerId,
+            });
+        }
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.skillRankType,
+            displayName: options.displayName ?? `Skill ${skillId} ${ownerUserId}`,
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(ownerUserId) },
+                { key: 'skill_id', valueType: 'string', valueJson: JSON.stringify(skillId) },
+            ],
+        });
+    }
+    /**
+     * Buy one rank of a skill. `prereqRankId` is the caller's SkillRank for
+     * the prerequisite skill; omit it for skills without one (the rank row
+     * itself is passed to satisfy the required param — the condition ignores
+     * it when the def declares no prerequisite).
+     */
+    async buySkill(input) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.buySkillFn,
+            selfContainerId: input.skillRankId,
+            params: {
+                progress_id: input.progressId,
+                def_id: input.skillDefId,
+                prereq_id: input.prereqRankId ?? input.skillRankId,
+            },
+        });
+    }
+    /** List a player's skill ranks. */
+    async skills(ownerUserId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.skillRankType,
+        });
+        const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        return Promise.all(mine.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,
+                skillId: String(props.skill_id ?? ''),
+                rank: Number(props.rank ?? 0),
+            };
+        }));
+    }
+    /** List the achievement catalog (admin-seeded AchievementDef containers). */
+    async achievementCatalog() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.achievementDefType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                achievementId: String(props.achievement_id ?? ''),
+                threshold: Number(props.threshold ?? 0),
+            };
+        }));
+    }
+    /** Define an achievement (admin). */
+    async defineAchievement(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.achievementDefType,
+            displayName: input.displayName ?? `Achievement ${input.achievementId}`,
+            properties: [
+                {
+                    key: 'achievement_id',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(input.achievementId),
+                },
+                { key: 'threshold', valueType: 'int', valueJson: String(input.threshold) },
+            ],
+        });
+    }
+    /** List a player's achievement unlocks. */
+    async achievements(ownerUserId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.achievementUnlockType,
+        });
+        const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        return Promise.all(mine.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,
+                achievementId: String(props.achievement_id ?? ''),
+                unlocked: props.unlocked === true,
+            };
+        }));
+    }
+    /**
+     * Unlock an achievement once its xp threshold is met. Creates the caller's
+     * unlock row when absent, then invokes the gated function (idempotent).
+     */
+    async unlockAchievement(input) {
+        const mine = await this.achievements(input.ownerUserId);
+        let unlockId = mine.find((a) => a.achievementId === input.achievementId)?.containerId;
+        if (!unlockId) {
+            const created = await this.gameModel.createContainer({
+                appId: this.appId,
+                typeName: this.names.achievementUnlockType,
+                displayName: `Achievement ${input.achievementId} ${input.ownerUserId}`,
+                properties: [
+                    {
+                        key: 'owner_user_id',
+                        valueType: 'int',
+                        valueJson: String(input.ownerUserId),
+                    },
+                    {
+                        key: 'achievement_id',
+                        valueType: 'string',
+                        valueJson: JSON.stringify(input.achievementId),
+                    },
+                ],
+            });
+            unlockId = created.containerId;
+        }
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.unlockAchievementFn,
+            selfContainerId: unlockId,
+            params: { progress_id: input.progressId, def_id: input.achievementDefId },
+        });
+    }
+    /**
+     * Apply a match result as a rating delta (trusted — host-gated by
+     * default; `kit.matches` computes the delta). Resolves with the new
+     * rating.
+     */
+    async applyMatchResult(progressId, delta) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.adjustRatingFn,
+            selfContainerId: progressId,
+            params: { delta },
+        });
+    }
+}

package/dist/kit/quests.d.ts

@@ -0,0 +1,110 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link QuestsKit}. Must match the deployed quests blueprint. */
+export interface QuestsKitOptions {
+    /** The `typePrefix` the quests blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one quest catalog row. */
+export interface KitQuestDef {
+    containerId: string;
+    displayName: string;
+    questId: string;
+    targetCount: number;
+    rewardItemId: string;
+    rewardQty: number;
+    rewardGold: number;
+    repeatable: boolean;
+    daily: boolean;
+}
+/** A parsed view of one player's quest progress. */
+export interface KitQuestProgress {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    questId: string;
+    count: number;
+    target: number;
+    completed: boolean;
+    claimed: boolean;
+    daily: boolean;
+}
+/**
+ * Runtime helpers for the {@link questsBlueprint} conventions: browse the
+ * quest catalog, accept quests into per-player progress rows, advance them
+ * (trusted — app admins or event automations), and claim rewards atomically
+ * into a stack + wallet. Denials resolve with `success: false`.
+ *
+ * Obtained via `client.kit(appId).quests`.
+ */
+export declare class QuestsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: QuestsKitOptions);
+    /** List the quest catalog (admin-seeded QuestDef containers). */
+    catalog(): Promise<KitQuestDef[]>;
+    /** Define a quest (admin — the catalog type is admin-instantiable). */
+    defineQuest(input: {
+        questId: string;
+        targetCount?: number;
+        rewardItemId?: string;
+        rewardQty?: number;
+        rewardGold?: number;
+        repeatable?: boolean;
+        daily?: boolean;
+        displayName?: string;
+        properties?: SeedPropertyInput[];
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Accept a quest: creates the caller's progress row seeded from the def
+     * (target and daily flag copied at accept time).
+     */
+    accept(ownerUserId: Scalars['BigInt']['input'], questDefId: string, 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;
+    }>;
+    /** List a player's quest progress rows. */
+    mine(ownerUserId: Scalars['BigInt']['input']): Promise<KitQuestProgress[]>;
+    /** Read one progress row. */
+    state(progressId: string): Promise<KitQuestProgress>;
+    /**
+     * Advance quest progress — a **trusted** call (default blueprint
+     * authority: app admins; or wire `advanceOn` event automations). Resolves
+     * with the new count.
+     */
+    advance(progressId: string, amount?: number): Promise<KitInvokeResult<number>>;
+    /**
+     * Turn in a completed quest: marks it claimed AND grants the item +
+     * currency rewards in one transaction. Resolves with the wallet's new
+     * balance.
+     */
+    claim(input: {
+        progressId: string;
+        questDefId: string;
+        toStackId: string;
+        walletId: string;
+    }): Promise<KitInvokeResult<number>>;
+}
+//# sourceMappingURL=quests.d.ts.map

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

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