@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/matches.d.ts

@@ -0,0 +1,140 @@
+import type { ChannelsAPI } from '../domains/channels.js';
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { UdpAPI } from '../domains/udp.js';
+import type { Scalars } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link MatchesKit}. Must match the deployed matches blueprint. */
+export interface MatchesKitOptions {
+    /** The `typePrefix` the matches blueprint was deployed with. */
+    typePrefix?: string;
+    /**
+     * The 32-ASCII-char actor uuid used as the sender id on channel pings.
+     * Defaults to a random uuid per kit instance.
+     */
+    actorUuid?: string;
+}
+/** A parsed view of one match. */
+export interface KitMatch {
+    /** The session backing the match (participants + turn order). */
+    sessionId: string;
+    /** The MatchMeta container id (the `self` of the lifecycle functions). */
+    metaId: string;
+    displayName: string;
+    creatorUserId: number;
+    mode: string;
+    state: string;
+    round: number;
+    maxPlayers: number;
+    winnerUserId: number;
+    /** The per-match notification channel (0 when none was wired). */
+    channelId: string;
+    /** Present when the blueprint was deployed with `turnTick`. */
+    tickCount?: number;
+}
+/** One row of the match standings. */
+export interface KitMatchScore {
+    containerId: string;
+    ownerUserId: string | null;
+    points: number;
+}
+/**
+ * Runtime helpers for the {@link matchesBlueprint} conventions: sessions ARE
+ * the match primitive — `create` makes a session + a `MatchMeta` + a
+ * per-match channel; turn order goes through the platform's session-turn
+ * authority; lifecycle functions ping the channel post-commit and
+ * {@link onMatchChanged} wraps the notify-to-pull loop (subscribe →
+ * `"match_changed"` ping → re-pull state).
+ *
+ * Obtained via `client.kit(appId).matches`.
+ */
+export declare class MatchesKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly channels;
+    private readonly udp;
+    private readonly names;
+    private readonly actorUuid;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, channels: ChannelsAPI | undefined, udp: UdpAPI | undefined, options?: MatchesKitOptions);
+    private requireChannels;
+    private requireUdp;
+    /**
+     * Create a match: a session (the platform match primitive), a per-match
+     * notification channel, and the session-scoped `MatchMeta`.
+     *
+     * @param input.creatorUserId - The calling player's user id (stored so the
+     *   creator may start/advance/end the match).
+     */
+    create(input: {
+        creatorUserId: Scalars['BigInt']['input'];
+        mode?: string;
+        maxPlayers?: number;
+        displayName?: string;
+    }): Promise<KitMatch>;
+    /** List joinable matches (metas still in the lobby state). */
+    open(): Promise<KitMatch[]>;
+    /** Read one match by its MatchMeta container. */
+    get(metaId: string): Promise<KitMatch>;
+    /** Join a match: session participation + the notification channel. */
+    join(match: KitMatch): Promise<{
+        __typename?: "GmSessionParticipant";
+        sessionId: string;
+        userId: string;
+        role: string;
+    }>;
+    /** Start the match (creator or host). Pings the match channel post-commit. */
+    start(match: KitMatch): Promise<KitInvokeResult<string>>;
+    /** Advance to the next round (creator or host). */
+    advanceRound(match: KitMatch): Promise<KitInvokeResult<number>>;
+    /** Whether it is `userId`'s session turn right now. */
+    myTurn(match: KitMatch, userId: Scalars['BigInt']['input']): Promise<boolean>;
+    /**
+     * Pass the turn to the next player via the platform's session-turn
+     * authority (current holder, host, or admin — enforced by the service),
+     * then ping the match channel so everyone re-pulls.
+     */
+    endTurn(match: KitMatch, nextUserId: Scalars['BigInt']['input']): Promise<{
+        __typename?: "GmSession";
+        sessionId: string;
+        appId: string;
+        name: string | null;
+        status: string;
+        createdByUserId: string | null;
+        currentTurnUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Find-or-create a player's session-scoped Score row. */
+    ensureScore(match: KitMatch, ownerUserId: Scalars['BigInt']['input']): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Add points to a Score row — trusted (host-refereed by default).
+     * Resolves with the new points.
+     */
+    score(match: KitMatch, scoreId: string, points: number): Promise<KitInvokeResult<number>>;
+    /** The match standings, highest points first (client-side sort). */
+    standings(match: KitMatch): Promise<KitMatchScore[]>;
+    /** Finish the match and record the winner (creator or host). */
+    finish(match: KitMatch, winnerUserId: Scalars['BigInt']['input']): Promise<KitInvokeResult<string>>;
+    /**
+     * Manually ping the match channel with `"match_changed"` (the lifecycle
+     * functions do this automatically via their declared notifications; use
+     * this after out-of-band changes such as `endTurn`).
+     */
+    notifyChanged(match: KitMatch): Promise<boolean>;
+    /**
+     * The notify-to-pull loop, wrapped: subscribe to the app's notifications,
+     * and on every ping of THIS match's channel re-pull the match state and
+     * hand it to `callback`. Returns the unsubscribe function.
+     */
+    onMatchChanged(match: KitMatch, callback: (match: KitMatch) => void): () => void;
+    private toMatch;
+}
+//# sourceMappingURL=matches.d.ts.map

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

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

package/dist/kit/matches.js

@@ -0,0 +1,253 @@
+import { encodeBase64, generateCrowdyUuid } from '../utils.js';
+import { matchesNames } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link matchesBlueprint} conventions: sessions ARE
+ * the match primitive — `create` makes a session + a `MatchMeta` + a
+ * per-match channel; turn order goes through the platform's session-turn
+ * authority; lifecycle functions ping the channel post-commit and
+ * {@link onMatchChanged} wraps the notify-to-pull loop (subscribe →
+ * `"match_changed"` ping → re-pull state).
+ *
+ * Obtained via `client.kit(appId).matches`.
+ */
+export class MatchesKit {
+    constructor(appId, gameModel, channels, udp, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.channels = channels;
+        this.udp = udp;
+        this.names = matchesNames(options.typePrefix ?? '');
+        this.actorUuid = options.actorUuid ?? generateCrowdyUuid();
+    }
+    requireChannels() {
+        if (!this.channels) {
+            throw new Error('kit.matches needs the channels domain — construct the kit via client.kit(appId)');
+        }
+        return this.channels;
+    }
+    requireUdp() {
+        if (!this.udp) {
+            throw new Error('kit.matches needs the udp domain — construct the kit via client.kit(appId)');
+        }
+        return this.udp;
+    }
+    /**
+     * Create a match: a session (the platform match primitive), a per-match
+     * notification channel, and the session-scoped `MatchMeta`.
+     *
+     * @param input.creatorUserId - The calling player's user id (stored so the
+     *   creator may start/advance/end the match).
+     */
+    async create(input) {
+        const session = await this.gameModel.createSession({
+            appId: this.appId,
+            name: input.displayName ?? `match-${input.mode ?? 'default'}`,
+        });
+        const channel = await this.requireChannels().create({
+            appId: this.appId,
+            name: `match-${session.sessionId}`,
+            description: 'Per-match notification channel (kit.matches notify-to-pull).',
+        });
+        const meta = await this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.metaType,
+            displayName: input.displayName ?? `Match ${session.sessionId}`,
+            sessionId: session.sessionId,
+            properties: [
+                {
+                    key: 'creator_user_id',
+                    valueType: 'int',
+                    valueJson: String(input.creatorUserId),
+                },
+                { key: 'mode', valueType: 'string', valueJson: JSON.stringify(input.mode ?? '') },
+                {
+                    key: 'max_players',
+                    valueType: 'int',
+                    valueJson: String(input.maxPlayers ?? 0),
+                },
+                { key: 'channel_id', valueType: 'int', valueJson: String(channel.groupId) },
+            ],
+        });
+        return this.toMatch(meta.containerId, session.sessionId, meta.displayName);
+    }
+    /** List joinable matches (metas still in the lobby state). */
+    async open() {
+        const metas = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.metaType,
+        });
+        const matches = await Promise.all(metas
+            .filter((m) => m.sessionId != null)
+            .map((m) => this.toMatch(m.containerId, String(m.sessionId), m.displayName)));
+        return matches.filter((m) => m.state === 'lobby');
+    }
+    /** Read one match by its MatchMeta container. */
+    async get(metaId) {
+        const meta = await this.gameModel.container({
+            appId: this.appId,
+            containerId: metaId,
+        });
+        return this.toMatch(meta.containerId, meta.sessionId != null ? String(meta.sessionId) : '', meta.displayName);
+    }
+    /** Join a match: session participation + the notification channel. */
+    async join(match) {
+        const participant = await this.gameModel.joinSession({
+            appId: this.appId,
+            sessionId: match.sessionId,
+        });
+        if (match.channelId !== '0' && match.channelId !== '') {
+            await this.requireChannels().join(match.channelId);
+        }
+        return participant;
+    }
+    /** Start the match (creator or host). Pings the match channel post-commit. */
+    async start(match) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.startFn,
+            selfContainerId: match.metaId,
+            sessionId: match.sessionId,
+            params: {},
+        });
+    }
+    /** Advance to the next round (creator or host). */
+    async advanceRound(match) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.advanceRoundFn,
+            selfContainerId: match.metaId,
+            sessionId: match.sessionId,
+            params: {},
+        });
+    }
+    /** Whether it is `userId`'s session turn right now. */
+    async myTurn(match, userId) {
+        const session = await this.gameModel.session({
+            appId: this.appId,
+            sessionId: match.sessionId,
+        });
+        return (session.currentTurnUserId != null &&
+            String(session.currentTurnUserId) === String(userId));
+    }
+    /**
+     * Pass the turn to the next player via the platform's session-turn
+     * authority (current holder, host, or admin — enforced by the service),
+     * then ping the match channel so everyone re-pulls.
+     */
+    async endTurn(match, nextUserId) {
+        const session = await this.gameModel.setSessionTurn({
+            appId: this.appId,
+            sessionId: match.sessionId,
+            userId: nextUserId,
+        });
+        await this.notifyChanged(match);
+        return session;
+    }
+    /** Find-or-create a player's session-scoped Score row. */
+    async ensureScore(match, ownerUserId) {
+        const scores = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.scoreType,
+            sessionId: match.sessionId,
+        });
+        const mine = scores.find((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        if (mine)
+            return mine;
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.scoreType,
+            displayName: `Score ${ownerUserId}`,
+            sessionId: match.sessionId,
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(ownerUserId) },
+            ],
+        });
+    }
+    /**
+     * Add points to a Score row — trusted (host-refereed by default).
+     * Resolves with the new points.
+     */
+    async score(match, scoreId, points) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.scoreFn,
+            selfContainerId: scoreId,
+            sessionId: match.sessionId,
+            params: { points },
+        });
+    }
+    /** The match standings, highest points first (client-side sort). */
+    async standings(match) {
+        const scores = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.scoreType,
+            sessionId: match.sessionId,
+        });
+        const rows = await Promise.all(scores.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                points: Number(props.points ?? 0),
+            };
+        }));
+        return rows.sort((a, b) => b.points - a.points);
+    }
+    /** Finish the match and record the winner (creator or host). */
+    async finish(match, winnerUserId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.endFn,
+            selfContainerId: match.metaId,
+            sessionId: match.sessionId,
+            params: { winner_user_id: Number(winnerUserId) },
+        });
+    }
+    /**
+     * Manually ping the match channel with `"match_changed"` (the lifecycle
+     * functions do this automatically via their declared notifications; use
+     * this after out-of-band changes such as `endTurn`).
+     */
+    async notifyChanged(match) {
+        if (match.channelId === '0' || match.channelId === '')
+            return false;
+        return this.requireUdp().sendChannelMessage({
+            channelId: match.channelId,
+            uuid: this.actorUuid,
+            payload: encodeBase64(new TextEncoder().encode('match_changed')),
+        });
+    }
+    /**
+     * The notify-to-pull loop, wrapped: subscribe to the app's notifications,
+     * and on every ping of THIS match's channel re-pull the match state and
+     * hand it to `callback`. Returns the unsubscribe function.
+     */
+    onMatchChanged(match, callback) {
+        return this.requireUdp().subscribe({
+            channelMessage: (notification) => {
+                if (String(notification.channelId) !== String(match.channelId))
+                    return;
+                void this.get(match.metaId).then(callback);
+            },
+        }, String(this.appId));
+    }
+    async toMatch(metaId, sessionId, displayName) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), metaId);
+        return {
+            sessionId,
+            metaId,
+            displayName,
+            creatorUserId: Number(props.creator_user_id ?? 0),
+            mode: String(props.mode ?? ''),
+            state: String(props.state ?? ''),
+            round: Number(props.round ?? 0),
+            maxPlayers: Number(props.max_players ?? 0),
+            winnerUserId: Number(props.winner_user_id ?? 0),
+            channelId: String(props.channel_id ?? '0'),
+            ...(props.tick_count !== undefined
+                ? { tickCount: Number(props.tick_count) }
+                : {}),
+        };
+    }
+}

package/dist/kit/objects.js

@@ -1,4 +1,4 @@
-import { lockNames } from './blueprints.js';
+import { lockNames } from './blueprints/index.js';
 import { kitContainerProperties, kitInvoke, } from './shared.js';
 /**
  * Runtime helpers for the {@link lockBlueprint} conventions: instantiate

package/dist/kit/plots.js

@@ -1,4 +1,4 @@
-import { plotNames } from './blueprints.js';
+import { plotNames } from './blueprints/index.js';
 import { kitContainerProperties, kitInvoke, } from './shared.js';
 /**
  * Runtime helpers for the {@link plotBlueprint} conventions: list/create

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":"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"}