@crowdedkingdoms/crowdyjs 8.0.1 → 8.1.0

package/dist/kit/objects.d.ts

@@ -0,0 +1,108 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link ObjectsKit}. Must match the deployed lock blueprint. */
+export interface ObjectsKitOptions {
+    /** The `objectTypeName` the lock blueprint was deployed with. Defaults to `'Lockable'`. */
+    objectTypeName?: string;
+    /** The `keyTypeName` the lock blueprint was deployed with. */
+    keyTypeName?: string;
+}
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export declare class ObjectsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: ObjectsKitOptions);
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`.
+     */
+    create(input: {
+        displayName: string;
+        requiredKeyId?: string;
+        ownerUserId?: Scalars['BigInt']['input'];
+        properties?: SeedPropertyInput[];
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    grantKey(input: {
+        keyId: string;
+        toUserId: Scalars['BigInt']['input'];
+        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 the key items a player holds. */
+    keysOf(userId: 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;
+    }[]>;
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    open(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Try to close an object; same authority as {@link open}. */
+    close(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Read whether an object is currently open. */
+    isOpen(objectId: string): Promise<boolean>;
+    /** List all objects of this lockable type. */
+    list(options?: {
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+}
+//# sourceMappingURL=objects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../src/kit/objects.ts"],"names":[],"mappings":"AAAA,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,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,iBAAsB;IAKjC;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACzC,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAwBD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IAiBD,yCAAyC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;;;;;;;;;;;IAU/C;;;;OAIG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,8DAA8D;IACxD,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,gDAAgD;IAC1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD,8CAA8C;IACxC,IAAI,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;CAOhD"}

package/dist/kit/objects.js

@@ -0,0 +1,110 @@
+import { lockNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export class ObjectsKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = lockNames(options.objectTypeName, options.keyTypeName);
+    }
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`.
+     */
+    async create(input) {
+        const properties = [
+            { key: 'is_open', valueType: 'bool', valueJson: 'false' },
+            ...(input.requiredKeyId !== undefined
+                ? [
+                    {
+                        key: 'required_key_id',
+                        valueType: 'string',
+                        valueJson: JSON.stringify(input.requiredKeyId),
+                    },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            displayName: input.displayName,
+            ...(input.ownerUserId !== undefined ? { ownerUserId: input.ownerUserId } : {}),
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties,
+        });
+    }
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    async grantKey(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.keyType,
+            displayName: input.displayName ?? `Key ${input.keyId}`,
+            ownerUserId: input.toUserId,
+            properties: [
+                { key: 'key_id', valueType: 'string', valueJson: JSON.stringify(input.keyId) },
+                {
+                    key: 'owner_user_id',
+                    valueType: 'int',
+                    valueJson: String(input.toUserId),
+                },
+            ],
+        });
+    }
+    /** List the key items a player holds. */
+    async keysOf(userId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.keyType,
+        });
+        return containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(userId));
+    }
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    async open(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.openFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Try to close an object; same authority as {@link open}. */
+    async close(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.closeFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Read whether an object is currently open. */
+    async isOpen(objectId) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), objectId);
+        return props.is_open === true;
+    }
+    /** List all objects of this lockable type. */
+    async list(options = {}) {
+        return this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+    }
+}

package/dist/kit/shared.d.ts

@@ -0,0 +1,32 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { GameModelInvokeMutation } from '../generated/graphql.js';
+/** The raw server result of a `gameModelInvoke` call. */
+export type RawInvokeResult = GameModelInvokeMutation['gameModelInvoke'];
+/**
+ * A kit invoke outcome: the server's authority/evaluation verdict plus the
+ * parsed return value. Authority denials and expression errors are **not**
+ * exceptions — check {@link success}.
+ */
+export interface KitInvokeResult<T = unknown> {
+    /** `false` when the invoke policy denied the caller or the logic errored (rolled back). */
+    success: boolean;
+    /** The parsed `returnValueJson`, when present and `success` is true. */
+    returnValue?: T;
+    /** The server's error message when `success` is false. */
+    errorMessage?: string;
+    /** The full server result (event id, applied mutations, …). */
+    raw: RawInvokeResult;
+}
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export declare function toKitInvokeResult<T>(raw: RawInvokeResult): KitInvokeResult<T>;
+/** Invoke a model function and wrap the result. */
+export declare function kitInvoke<T = unknown>(gameModel: GameModelAPI, input: {
+    appId: string;
+    functionName: string;
+    selfContainerId: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}): Promise<KitInvokeResult<T>>;
+/** Read a container's visible properties as a parsed object. */
+export declare function kitContainerProperties(gameModel: GameModelAPI, appId: string, containerId: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAe7E;AAED,mDAAmD;AACnD,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAS7B;AAED,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlC"}

package/dist/kit/shared.js

@@ -0,0 +1,39 @@
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export function toKitInvokeResult(raw) {
+    let returnValue;
+    if (raw.success && raw.returnValueJson != null) {
+        try {
+            returnValue = JSON.parse(raw.returnValueJson);
+        }
+        catch {
+            returnValue = undefined;
+        }
+    }
+    return {
+        success: raw.success,
+        returnValue,
+        errorMessage: raw.errorMessage ?? undefined,
+        raw,
+    };
+}
+/** Invoke a model function and wrap the result. */
+export async function kitInvoke(gameModel, input) {
+    const raw = await gameModel.invoke({
+        appId: input.appId,
+        functionName: input.functionName,
+        selfContainerId: input.selfContainerId,
+        paramsJson: JSON.stringify(input.params ?? {}),
+        ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+    });
+    return toKitInvokeResult(raw);
+}
+/** Read a container's visible properties as a parsed object. */
+export async function kitContainerProperties(gameModel, appId, containerId) {
+    const state = await gameModel.containerState({ appId, containerId });
+    try {
+        return JSON.parse(state.propertiesJson);
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

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