@crowdedkingdoms/crowdyjs 17.14.0-dev.1 → 18.0.1-dev.1

package/dist/kit/progression.js

@@ -1,265 +0,0 @@
-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

@@ -1,171 +0,0 @@
-import type { GameModelAPI } from '../domains/gameModel.js';
-import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
-import { type KitOwnerIdKind } from './blueprints/index.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;
-    /** Must match questsBlueprint.ownerIdKind. Defaults to `int`. */
-    ownerIdKind?: KitOwnerIdKind;
-}
-/** 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;
-    private readonly ownerIdKind;
-    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[]>;
-    /**
-     * STUDIO (admin) — define an ordered tutorial chain as quest defs. Steps
-     * are plain quests whose `questId` encodes the chain + index
-     * (`"<chain>:<i>"`), so no new server surface is involved: the sequencing
-     * is a read-side convention enforced by {@link tutorial} /
-     * {@link acceptNextTutorialStep} (a step is `locked` until every earlier
-     * step completes).
-     */
-    defineTutorial(input: {
-        /** Chain id (one app can ship several tutorials). Defaults to `'ftue'`. */
-        chain?: string;
-        steps: Array<{
-            displayName: string;
-            targetCount?: number;
-            rewardItemId?: string;
-            rewardQty?: number;
-            rewardGold?: number;
-        }>;
-    }): Promise<{
-        __typename?: "GmContainer";
-        containerId: string;
-        appId: string;
-        sessionId: string | null;
-        typeName: string;
-        displayName: string;
-        description: string | null;
-        ownerUserId: string | null;
-        metadataJson: string;
-    }[]>;
-    /** One tutorial step joined with the player's progress. */
-    /**
-     * A player's view of a tutorial chain: steps in order, each `locked`
-     * (an earlier step is incomplete), `active` (the first incomplete step),
-     * or `complete`. The client shows/drives only the `active` step; the
-     * trusted advance authority is unchanged (players still cannot complete
-     * their own quests).
-     */
-    tutorial(ownerUserId: Scalars['BigInt']['input'], chain?: string): Promise<Array<{
-        stepIndex: number;
-        def: KitQuestDef;
-        progress: KitQuestProgress | null;
-        status: 'locked' | 'active' | 'complete';
-    }>>;
-    /**
-     * Ensure the player's ACTIVE tutorial step has a progress row (accepting
-     * it when missing) and return the step. Returns null when the chain is
-     * complete. Calling this for a locked step is impossible by construction —
-     * it always targets the first incomplete step.
-     */
-    acceptNextTutorialStep(ownerUserId: Scalars['BigInt']['input'], chain?: string, options?: {
-        sessionId?: string;
-    }): Promise<{
-        stepIndex: number;
-        def: KitQuestDef;
-        progress: KitQuestProgress | null;
-        status: "locked" | "active" | "complete";
-    } | null>;
-    /** 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

@@ -1 +0,0 @@
-{"version":3,"file":"quests.d.ts","sourceRoot":"","sources":["../../src/kit/quests.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,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,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;gBAG1B,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,gBAAqB;IAMhC,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IA2BvC,uEAAuE;IACjE,WAAW,CAAC,KAAK,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAClC;;;;;;;;;;;IAkCD;;;OAGG;IACG,MAAM,CACV,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAqC5D,2CAA2C;IACrC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAahF;;;;;;;OAOG;IACG,cAAc,CAAC,KAAK,EAAE;QAC1B,2EAA2E;QAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,KAAK,CAAC;YACX,WAAW,EAAE,MAAM,CAAC;YACpB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,YAAY,CAAC,EAAE,MAAM,CAAC;YACtB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC,CAAC;KACJ;;;;;;;;;;;IAkBD,2DAA2D;IAE3D;;;;;;OAMG;IACG,QAAQ,CACZ,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,KAAK,SAAS,GACb,OAAO,CACR,KAAK,CAAC;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,WAAW,CAAC;QACjB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAClC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;KAC1C,CAAC,CACH;IAsBD;;;;;OAKG;IACG,sBAAsB,CAC1B,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,KAAK,SAAS,EACd,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;mBApCvB,MAAM;aACZ,WAAW;kBACN,gBAAgB,GAAG,IAAI;gBACzB,QAAQ,GAAG,QAAQ,GAAG,UAAU;;IA4C5C,6BAA6B;IACvB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuB1D;;;;OAIG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS/E;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CAYrC"}

package/dist/kit/quests.js

@@ -1,237 +0,0 @@
-import { questsNames, } from './blueprints/index.js';
-import { kitContainerProperties, kitInvoke, } from './shared.js';
-/**
- * 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 class QuestsKit {
-    constructor(appId, gameModel, options = {}) {
-        this.appId = appId;
-        this.gameModel = gameModel;
-        this.names = questsNames(options.typePrefix ?? '');
-        this.ownerIdKind = options.ownerIdKind ?? 'int';
-    }
-    /** List the quest catalog (admin-seeded QuestDef containers). */
-    async catalog() {
-        const containers = await this.gameModel.containers({
-            appId: this.appId,
-            typeName: this.names.defType,
-        });
-        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,
-                questId: String(props.quest_id ?? ''),
-                targetCount: Number(props.target_count ?? 1),
-                rewardItemId: String(props.reward_item_id ?? ''),
-                rewardQty: Number(props.reward_qty ?? 0),
-                rewardGold: Number(props.reward_gold ?? 0),
-                repeatable: props.repeatable === true,
-                daily: props.daily === true,
-            };
-        }));
-    }
-    /** Define a quest (admin — the catalog type is admin-instantiable). */
-    async defineQuest(input) {
-        return this.gameModel.createContainer({
-            appId: this.appId,
-            typeName: this.names.defType,
-            displayName: input.displayName ?? `Quest ${input.questId}`,
-            properties: [
-                { key: 'quest_id', valueType: 'string', valueJson: JSON.stringify(input.questId) },
-                {
-                    key: 'target_count',
-                    valueType: 'int',
-                    valueJson: String(input.targetCount ?? 1),
-                },
-                {
-                    key: 'reward_item_id',
-                    valueType: 'string',
-                    valueJson: JSON.stringify(input.rewardItemId ?? ''),
-                },
-                { key: 'reward_qty', valueType: 'int', valueJson: String(input.rewardQty ?? 0) },
-                {
-                    key: 'reward_gold',
-                    valueType: 'int',
-                    valueJson: String(input.rewardGold ?? 0),
-                },
-                {
-                    key: 'repeatable',
-                    valueType: 'bool',
-                    valueJson: String(input.repeatable ?? false),
-                },
-                { key: 'daily', valueType: 'bool', valueJson: String(input.daily ?? false) },
-                ...(input.properties ?? []),
-            ],
-        });
-    }
-    /**
-     * Accept a quest: creates the caller's progress row seeded from the def
-     * (target and daily flag copied at accept time).
-     */
-    async accept(ownerUserId, questDefId, options = {}) {
-        const props = await kitContainerProperties(this.gameModel, String(this.appId), questDefId);
-        const questId = String(props.quest_id ?? '');
-        return this.gameModel.createContainer({
-            appId: this.appId,
-            typeName: this.names.progressType,
-            displayName: options.displayName ?? `Quest ${questId} ${ownerUserId}`,
-            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
-            properties: [
-                {
-                    key: 'owner_user_id',
-                    valueType: this.ownerIdKind,
-                    valueJson: this.ownerIdKind === 'string'
-                        ? JSON.stringify(String(ownerUserId))
-                        : String(ownerUserId),
-                },
-                { key: 'quest_id', valueType: 'string', valueJson: JSON.stringify(questId) },
-                {
-                    key: 'target',
-                    valueType: 'int',
-                    valueJson: String(Number(props.target_count ?? 1)),
-                },
-                {
-                    key: 'daily',
-                    valueType: 'bool',
-                    valueJson: String(props.daily === true),
-                },
-            ],
-        });
-    }
-    /** List a player's quest progress rows. */
-    async mine(ownerUserId) {
-        const containers = await this.gameModel.containers({
-            appId: this.appId,
-            typeName: this.names.progressType,
-        });
-        const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
-        return Promise.all(mine.map((c) => this.state(c.containerId)));
-    }
-    // -- FTUE / tutorial step sequencing (Wave 2) -----------------------------
-    /**
-     * STUDIO (admin) — define an ordered tutorial chain as quest defs. Steps
-     * are plain quests whose `questId` encodes the chain + index
-     * (`"<chain>:<i>"`), so no new server surface is involved: the sequencing
-     * is a read-side convention enforced by {@link tutorial} /
-     * {@link acceptNextTutorialStep} (a step is `locked` until every earlier
-     * step completes).
-     */
-    async defineTutorial(input) {
-        const chain = input.chain ?? 'ftue';
-        const created = [];
-        for (const [index, step] of input.steps.entries()) {
-            created.push(await this.defineQuest({
-                questId: `${chain}:${index}`,
-                displayName: step.displayName,
-                targetCount: step.targetCount ?? 1,
-                rewardItemId: step.rewardItemId,
-                rewardQty: step.rewardQty,
-                rewardGold: step.rewardGold,
-            }));
-        }
-        return created;
-    }
-    /** One tutorial step joined with the player's progress. */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- documented shape
-    /**
-     * A player's view of a tutorial chain: steps in order, each `locked`
-     * (an earlier step is incomplete), `active` (the first incomplete step),
-     * or `complete`. The client shows/drives only the `active` step; the
-     * trusted advance authority is unchanged (players still cannot complete
-     * their own quests).
-     */
-    async tutorial(ownerUserId, chain = 'ftue') {
-        const prefix = `${chain}:`;
-        const defs = (await this.catalog())
-            .filter((def) => def.questId.startsWith(prefix))
-            .map((def) => ({ def, stepIndex: Number(def.questId.slice(prefix.length)) }))
-            .filter(({ stepIndex }) => Number.isFinite(stepIndex))
-            .sort((a, b) => a.stepIndex - b.stepIndex);
-        const progressRows = await this.mine(ownerUserId);
-        let blocked = false;
-        return defs.map(({ def, stepIndex }) => {
-            const progress = progressRows.find((p) => p.questId === def.questId) ?? null;
-            const complete = progress?.completed === true;
-            const status = complete
-                ? 'complete'
-                : blocked
-                    ? 'locked'
-                    : 'active';
-            if (!complete)
-                blocked = true;
-            return { stepIndex, def, progress, status };
-        });
-    }
-    /**
-     * Ensure the player's ACTIVE tutorial step has a progress row (accepting
-     * it when missing) and return the step. Returns null when the chain is
-     * complete. Calling this for a locked step is impossible by construction —
-     * it always targets the first incomplete step.
-     */
-    async acceptNextTutorialStep(ownerUserId, chain = 'ftue', options = {}) {
-        const steps = await this.tutorial(ownerUserId, chain);
-        const active = steps.find((step) => step.status === 'active');
-        if (!active)
-            return null;
-        if (active.progress)
-            return active;
-        await this.accept(ownerUserId, active.def.containerId, options);
-        const refreshed = await this.tutorial(ownerUserId, chain);
-        return refreshed.find((step) => step.stepIndex === active.stepIndex) ?? null;
-    }
-    /** Read one progress row. */
-    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,
-            questId: String(props.quest_id ?? ''),
-            count: Number(props.count ?? 0),
-            target: Number(props.target ?? 1),
-            completed: props.completed === true,
-            claimed: props.claimed === true,
-            daily: props.daily === true,
-        };
-    }
-    /**
-     * Advance quest progress — a **trusted** call (default blueprint
-     * authority: app admins; or wire `advanceOn` event automations). Resolves
-     * with the new count.
-     */
-    async advance(progressId, amount = 1) {
-        return kitInvoke(this.gameModel, {
-            appId: String(this.appId),
-            functionName: this.names.advanceFn,
-            selfContainerId: progressId,
-            params: { amount },
-        });
-    }
-    /**
-     * Turn in a completed quest: marks it claimed AND grants the item +
-     * currency rewards in one transaction. Resolves with the wallet's new
-     * balance.
-     */
-    async claim(input) {
-        return kitInvoke(this.gameModel, {
-            appId: String(this.appId),
-            functionName: this.names.claimFn,
-            selfContainerId: input.progressId,
-            params: {
-                def_id: input.questDefId,
-                to_stack_id: input.toStackId,
-                wallet_id: input.walletId,
-            },
-        });
-    }
-}