@crowdedkingdoms/crowdyjs 8.1.0 → 8.2.0

package/dist/kit/plots.d.ts

@@ -0,0 +1,81 @@
+import type { GameAppsAPI } from '../domains/gameApps.js';
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link PlotsKit}. Must match the deployed plot blueprint. */
+export interface PlotsKitOptions {
+    /** The `typeName` the plot blueprint was deployed with. Defaults to `'Plot'`. */
+    typeName?: string;
+}
+/** A parsed view of one plot. */
+export interface KitPlot {
+    containerId: string;
+    displayName: string;
+    gridId: number;
+    price: number;
+    /** 0 when unowned. */
+    ownerUserId: number;
+    rentPrice?: number;
+    rentTtlSeconds?: number;
+}
+/**
+ * Runtime helpers for the {@link plotBlueprint} conventions: list/create
+ * plots and drive the buy/rent/evict functions whose permission effects grant
+ * or revoke real, replication-enforced grid permissions transactionally with
+ * the currency mutation. Authorization (wallet ownership, price, plot
+ * ownership) is enforced server-side — a denial resolves with
+ * `success: false`, never an exception.
+ *
+ * Obtained via `client.kit(appId).plots`.
+ */
+export declare class PlotsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly gameApps;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, gameApps: GameAppsAPI, options?: PlotsKitOptions);
+    /**
+     * Instantiate a plot over an existing grid (admin — the type is
+     * admin-instantiable). Create the grid first (`client.gameApps.createGrid`)
+     * and pass its id here.
+     */
+    create(input: {
+        displayName: string;
+        gridId: Scalars['BigInt']['input'];
+        price: number;
+        rentPrice?: number;
+        rentTtlSeconds?: 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 plots with parsed state (grid, price, current owner). */
+    list(): Promise<KitPlot[]>;
+    /**
+     * Buy a plot: spends the price from the caller's wallet AND grants the
+     * blueprint's grid permissions in one transaction. Resolves with the
+     * wallet's remaining balance.
+     */
+    buy(plotId: string, walletId: string): Promise<KitInvokeResult<number>>;
+    /**
+     * Rent a plot (blueprint deployed with `rentable: true`): like {@link buy}
+     * but the grant expires after the plot's `rent_ttl_seconds`.
+     */
+    rent(plotId: string, walletId: string): Promise<KitInvokeResult<number>>;
+    /** Revoke a user's permissions on a plot (plot owner or app admin). */
+    evict(plotId: string, targetUserId: Scalars['BigInt']['input']): Promise<KitInvokeResult>;
+    /**
+     * A user's effective permission keys on a plot's grid (for HUD display —
+     * enforcement happens server-side regardless).
+     */
+    accessOf(userId: Scalars['BigInt']['input'], gridId: Scalars['BigInt']['input']): Promise<string[]>;
+}
+//# sourceMappingURL=plots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plots.d.ts","sourceRoot":"","sources":["../../src/kit/plots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,QAAQ,EAAE,WAAW,EACtC,OAAO,GAAE,eAAoB;IAK/B;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAClC;;;;;;;;;;;IA0BD,iEAAiE;IAC3D,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IA2BhC;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS7E;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS9E,uEAAuE;IACjE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAS/F;;;OAGG;IACG,QAAQ,CACZ,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAClC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC;CAQrB"}

package/dist/kit/plots.js

@@ -0,0 +1,113 @@
+import { plotNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link plotBlueprint} conventions: list/create
+ * plots and drive the buy/rent/evict functions whose permission effects grant
+ * or revoke real, replication-enforced grid permissions transactionally with
+ * the currency mutation. Authorization (wallet ownership, price, plot
+ * ownership) is enforced server-side — a denial resolves with
+ * `success: false`, never an exception.
+ *
+ * Obtained via `client.kit(appId).plots`.
+ */
+export class PlotsKit {
+    constructor(appId, gameModel, gameApps, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.gameApps = gameApps;
+        this.names = plotNames(options.typeName);
+    }
+    /**
+     * Instantiate a plot over an existing grid (admin — the type is
+     * admin-instantiable). Create the grid first (`client.gameApps.createGrid`)
+     * and pass its id here.
+     */
+    async create(input) {
+        const properties = [
+            { key: 'grid_id', valueType: 'int', valueJson: String(input.gridId) },
+            { key: 'price', valueType: 'int', valueJson: String(input.price) },
+            ...(input.rentPrice !== undefined
+                ? [{ key: 'rent_price', valueType: 'int', valueJson: String(input.rentPrice) }]
+                : []),
+            ...(input.rentTtlSeconds !== undefined
+                ? [
+                    {
+                        key: 'rent_ttl_seconds',
+                        valueType: 'int',
+                        valueJson: String(input.rentTtlSeconds),
+                    },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.plotType,
+            displayName: input.displayName,
+            properties,
+        });
+    }
+    /** List plots with parsed state (grid, price, current owner). */
+    async list() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.plotType,
+        });
+        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,
+                gridId: Number(props.grid_id ?? 0),
+                price: Number(props.price ?? 0),
+                ownerUserId: Number(props.owner_user_id ?? 0),
+                ...(props.rent_price !== undefined ? { rentPrice: Number(props.rent_price) } : {}),
+                ...(props.rent_ttl_seconds !== undefined
+                    ? { rentTtlSeconds: Number(props.rent_ttl_seconds) }
+                    : {}),
+            };
+        }));
+    }
+    /**
+     * Buy a plot: spends the price from the caller's wallet AND grants the
+     * blueprint's grid permissions in one transaction. Resolves with the
+     * wallet's remaining balance.
+     */
+    async buy(plotId, walletId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.buyFn,
+            selfContainerId: plotId,
+            params: { wallet_id: walletId },
+        });
+    }
+    /**
+     * Rent a plot (blueprint deployed with `rentable: true`): like {@link buy}
+     * but the grant expires after the plot's `rent_ttl_seconds`.
+     */
+    async rent(plotId, walletId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.rentFn,
+            selfContainerId: plotId,
+            params: { wallet_id: walletId },
+        });
+    }
+    /** Revoke a user's permissions on a plot (plot owner or app admin). */
+    async evict(plotId, targetUserId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.evictFn,
+            selfContainerId: plotId,
+            params: { target_user_id: Number(targetUserId) },
+        });
+    }
+    /**
+     * A user's effective permission keys on a plot's grid (for HUD display —
+     * enforcement happens server-side regardless).
+     */
+    async accessOf(userId, gridId) {
+        const res = await this.gameApps.userPermissions(String(this.appId), String(gridId), String(userId));
+        return [...res.permissionKeys];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",