@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/social.d.ts

@@ -0,0 +1,267 @@
+import type { ChannelsAPI } from '../domains/channels.js';
+import type { GameAppsAPI } from '../domains/gameApps.js';
+import type { TeamsAPI } from '../domains/teams.js';
+import type { UdpAPI } from '../domains/udp.js';
+import type { Scalars } from '../generated/graphql.js';
+/** Options for {@link SocialKit}. */
+export interface SocialKitOptions {
+    /**
+     * The 32-ASCII-char actor uuid used as the sender id on chat messages.
+     * Defaults to a random uuid per kit instance — set it to YOUR actor uuid
+     * so receivers can attribute messages.
+     */
+    actorUuid?: string;
+    /** Name prefix for party teams/channels. Defaults to `'party:'`. */
+    partyPrefix?: string;
+    /** Name prefix for guild teams/channels. Defaults to `'guild:'`. */
+    guildPrefix?: string;
+}
+/** A party or guild: the team plus its paired chat channel. */
+export interface KitGroupWithChannel {
+    /** The team's group id (membership/roles live here). */
+    teamId: string;
+    /** The paired chat channel's group id (may be '' if pairing failed). */
+    channelId: string;
+    name: string;
+}
+/** A decoded chat message from a kit chat room. */
+export interface KitChatMessage {
+    channelId: string;
+    /** The sender's actor uuid (attribution is by app convention). */
+    senderUuid: string;
+    text: string;
+    epochMillis: string;
+}
+/**
+ * Runtime **social** helpers — parties, guilds, and chat rooms in familiar
+ * words, wrapped over the platform's teams (membership + roles) and
+ * channels (location-independent messaging) with realtime delivery via the
+ * UDP notification subscription. No model schema needed; the only
+ * deployable is the optional {@link guildBlueprint} composite (guild hall +
+ * bank).
+ *
+ * Conventions: a party is a team named `party:<name>` paired with an
+ * equally-named channel; a guild is `guild:<name>` likewise. Guild
+ * territory = a grid group-grant (`claimTerritory`), enforced by the
+ * replication layer.
+ *
+ * Obtained via `client.kit(appId).social`.
+ */
+export declare class SocialKit {
+    private readonly appId;
+    private readonly teams;
+    private readonly channels;
+    private readonly udp;
+    private readonly gameApps;
+    private readonly actorUuid;
+    private readonly partyPrefix;
+    private readonly guildPrefix;
+    constructor(appId: Scalars['BigInt']['input'], teams: TeamsAPI | undefined, channels: ChannelsAPI | undefined, udp: UdpAPI | undefined, gameApps: GameAppsAPI, options?: SocialKitOptions);
+    private requireTeams;
+    private requireChannels;
+    private requireUdp;
+    /** Create a team + equally-named chat channel pair. */
+    private createPair;
+    /** Find a team + channel pair by its full name. */
+    private findPair;
+    /** Parties: small invite-based groups with their own chat channel. */
+    readonly party: {
+        /** Create a party (invite-only by default). The creator becomes leader. */
+        create: (name: string) => Promise<KitGroupWithChannel>;
+        /** Find a party by name. */
+        find: (name: string) => Promise<KitGroupWithChannel | undefined>;
+        /**
+         * Invite (add) a player to the party — requires the leader's
+         * `manage_members`. Adds them to the chat channel membership too.
+         */
+        invite: (party: KitGroupWithChannel, userId: Scalars["BigInt"]["input"]) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }>;
+        /** Join an open party (and its chat channel) as the caller. */
+        join: (party: KitGroupWithChannel) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }>;
+        /** Leave the party (and its chat channel). */
+        leave: (party: KitGroupWithChannel) => Promise<boolean>;
+        /** The party roster. */
+        members: (party: KitGroupWithChannel) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }[]>;
+    };
+    /** Guilds: persistent role-based organizations with chat + territory. */
+    readonly guild: {
+        /** Create a guild (request-to-join by default). The creator becomes leader. */
+        create: (name: string, options?: {
+            membershipPolicy?: string;
+            description?: string;
+        }) => Promise<KitGroupWithChannel>;
+        /** Find a guild by name. */
+        find: (name: string) => Promise<KitGroupWithChannel | undefined>;
+        /** The guild roster (members + pending join requests). */
+        roster: (guild: KitGroupWithChannel) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }[]>;
+        /** The guild's roles (including the system leader role). */
+        roles: (guild: KitGroupWithChannel) => Promise<{
+            __typename?: "GroupRole";
+            groupRoleId: string;
+            groupId: string;
+            roleName: string;
+            rank: number;
+            isSystem: boolean;
+            permissions: Array<string>;
+            createdAt: string;
+        }[]>;
+        /** Create a custom guild role (requires `manage_roles`). */
+        createRole: (guild: KitGroupWithChannel, input: {
+            roleName: string;
+            permissions?: string[];
+            rank?: number;
+        }) => Promise<{
+            __typename?: "GroupRole";
+            groupRoleId: string;
+            groupId: string;
+            roleName: string;
+            rank: number;
+            isSystem: boolean;
+            permissions: Array<string>;
+            createdAt: string;
+        }>;
+        /**
+         * Promote/demote a member: REPLACES their role set (requires
+         * `manage_roles`).
+         */
+        promote: (guild: KitGroupWithChannel, userId: Scalars["BigInt"]["input"], roleIds: string[]) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }>;
+        /**
+         * Claim territory for the guild: grants runtime permission keys on a
+         * grid to every guild member (optionally one role) — enforced by the
+         * replication layer on movement/voxel writes. Requires grid admin
+         * rights on the app.
+         */
+        claimTerritory: (guild: KitGroupWithChannel, gridId: Scalars["BigInt"]["input"], options?: {
+            permissionKeys?: string[];
+            groupRoleId?: string;
+        }) => Promise<{
+            __typename?: "GridGroupGrant";
+            appId: string;
+            gridId: string;
+            groupId: string;
+            groupRoleId: string | null;
+            permissionKey: string;
+            expiresAt: string | null;
+        }[]>;
+    };
+    /** Chat rooms: named channels with realtime text delivery. */
+    readonly chat: {
+        /** Find-or-create a chat room (an open channel) by name. */
+        room: (name: string) => Promise<{
+            __typename?: "Group";
+            groupId: string;
+            appId: string;
+            groupType: string;
+            name: string;
+            description: string | null;
+            ownerUserId: string | null;
+            membershipPolicy: string;
+            status: string;
+            defaultRoleId: string | null;
+            createdAt: string;
+        }>;
+        /** Join a chat room. */
+        join: (channelId: Scalars["BigInt"]["input"]) => Promise<{
+            __typename?: "GroupMember";
+            groupMemberId: string;
+            groupId: string;
+            userId: string;
+            status: string;
+            createdAt: string;
+            roles: Array<{
+                __typename?: "GroupRole";
+                groupRoleId: string;
+                roleName: string;
+                rank: number;
+                isSystem: boolean;
+                permissions: Array<string>;
+            }>;
+        }>;
+        /**
+         * Send a UTF-8 text message to a room (requires channel membership with
+         * `send_messages`). Delivery is fan-out to every active member's
+         * notification subscription, regardless of world location.
+         */
+        send: (channelId: Scalars["BigInt"]["input"], text: string) => Promise<boolean>;
+        /**
+         * Listen for messages in one room: decodes each ping's payload as UTF-8
+         * text. Returns the unsubscribe function.
+         */
+        onMessage: (channelId: Scalars["BigInt"]["input"], callback: (message: KitChatMessage) => void) => (() => void);
+    };
+}
+//# sourceMappingURL=social.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"social.d.ts","sourceRoot":"","sources":["../../src/kit/social.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGvD,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IAMlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAC3B,QAAQ,EAAE,WAAW,GAAG,SAAS,EACjC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,WAAW,EACtC,OAAO,GAAE,gBAAqB;IAOhC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,UAAU;IASlB,uDAAuD;YACzC,UAAU;IAuBxB,mDAAmD;YACrC,QAAQ;IAetB,sEAAsE;IACtE,QAAQ,CAAC,KAAK;QACZ,2EAA2E;uBACtD,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAAC;QAI1D,4BAA4B;qBACT,MAAM,KAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;QAIpE;;;WAGG;wBACmB,mBAAmB,UAAU,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;;;;;;;;0BA8Ku9ue,CAAC;;;;;;;;QAtKrive,+DAA+D;sBAC3C,mBAAmB;;;;;;;;0BAqK4jye,CAAC;;;;;;;;QA7Jpmye,8CAA8C;uBACzB,mBAAmB;QAOxC,wBAAwB;yBACD,mBAAmB;;;;;;;;0BAoJsq4e,CAAC;;;;;;;;MAjJjt4e;IAEF,yEAAyE;IACzE,QAAQ,CAAC,KAAK;QACZ,+EAA+E;uBAEvE,MAAM,YACH;YAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,KAC3D,OAAO,CAAC,mBAAmB,CAAC;QAQ/B,4BAA4B;qBACT,MAAM,KAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;QAIpE,0DAA0D;wBACpC,mBAAmB;;;;;;;;0BA2Huq4e,CAAC;;;;;;;;QAvHjt4e,4DAA4D;uBACvC,mBAAmB;;;;;;;;;;QAIxC,4DAA4D;4BAEnD,mBAAmB,SACnB;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE;;;;;;;;;;QAUpE;;;WAGG;yBAEM,mBAAmB,UAClB,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,WACzB,MAAM,EAAE;;;;;;;;0BA8Fwi2e,CAAC;;;;;;;;QArF5j2e;;;;;WAKG;gCAEM,mBAAmB,UAClB,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,YACzB;YAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE;;;;;;;;;MAY9D;IAEF,8DAA8D;IAC9D,QAAQ,CAAC,IAAI;QACX,4DAA4D;qBACzC,MAAM;;;;;;;;;;;;;QAOzB,wBAAwB;0BACA,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;;;;;;;;0BAmD4tqZ,CAAC;;;;;;;;QA/C/wqZ;;;;WAIG;0BAEU,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,QAC/B,MAAM,KACX,OAAO,CAAC,OAAO,CAAC;QAQnB;;;WAGG;+BAEU,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,YAC3B,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,KAC1C,CAAC,MAAM,IAAI,CAAC;MAsBf;CACH"}

package/dist/kit/social.js

@@ -0,0 +1,230 @@
+import { decodeBase64, encodeBase64, generateCrowdyUuid } from '../utils.js';
+/**
+ * Runtime **social** helpers — parties, guilds, and chat rooms in familiar
+ * words, wrapped over the platform's teams (membership + roles) and
+ * channels (location-independent messaging) with realtime delivery via the
+ * UDP notification subscription. No model schema needed; the only
+ * deployable is the optional {@link guildBlueprint} composite (guild hall +
+ * bank).
+ *
+ * Conventions: a party is a team named `party:<name>` paired with an
+ * equally-named channel; a guild is `guild:<name>` likewise. Guild
+ * territory = a grid group-grant (`claimTerritory`), enforced by the
+ * replication layer.
+ *
+ * Obtained via `client.kit(appId).social`.
+ */
+export class SocialKit {
+    constructor(appId, teams, channels, udp, gameApps, options = {}) {
+        this.appId = appId;
+        this.teams = teams;
+        this.channels = channels;
+        this.udp = udp;
+        this.gameApps = gameApps;
+        /** Parties: small invite-based groups with their own chat channel. */
+        this.party = {
+            /** Create a party (invite-only by default). The creator becomes leader. */
+            create: async (name) => {
+                return this.createPair(`${this.partyPrefix}${name}`, 'invite', 'Party');
+            },
+            /** Find a party by name. */
+            find: async (name) => {
+                return this.findPair(`${this.partyPrefix}${name}`);
+            },
+            /**
+             * Invite (add) a player to the party — requires the leader's
+             * `manage_members`. Adds them to the chat channel membership too.
+             */
+            invite: async (party, userId) => {
+                const member = await this.requireTeams().addMember(party.teamId, userId);
+                if (party.channelId) {
+                    await this.requireChannels().addMember(party.channelId, userId);
+                }
+                return member;
+            },
+            /** Join an open party (and its chat channel) as the caller. */
+            join: async (party) => {
+                const member = await this.requireTeams().join(party.teamId);
+                if (party.channelId) {
+                    await this.requireChannels().join(party.channelId);
+                }
+                return member;
+            },
+            /** Leave the party (and its chat channel). */
+            leave: async (party) => {
+                if (party.channelId) {
+                    await this.requireChannels().leave(party.channelId);
+                }
+                return this.requireTeams().leave(party.teamId);
+            },
+            /** The party roster. */
+            members: async (party) => {
+                return this.requireTeams().members(party.teamId);
+            },
+        };
+        /** Guilds: persistent role-based organizations with chat + territory. */
+        this.guild = {
+            /** Create a guild (request-to-join by default). The creator becomes leader. */
+            create: async (name, options = {}) => {
+                return this.createPair(`${this.guildPrefix}${name}`, options.membershipPolicy ?? 'request', options.description ?? 'Guild');
+            },
+            /** Find a guild by name. */
+            find: async (name) => {
+                return this.findPair(`${this.guildPrefix}${name}`);
+            },
+            /** The guild roster (members + pending join requests). */
+            roster: async (guild) => {
+                return this.requireTeams().members(guild.teamId);
+            },
+            /** The guild's roles (including the system leader role). */
+            roles: async (guild) => {
+                return this.requireTeams().roles(guild.teamId);
+            },
+            /** Create a custom guild role (requires `manage_roles`). */
+            createRole: async (guild, input) => {
+                return this.requireTeams().createRole({
+                    groupId: guild.teamId,
+                    roleName: input.roleName,
+                    ...(input.permissions !== undefined ? { permissions: input.permissions } : {}),
+                    ...(input.rank !== undefined ? { rank: input.rank } : {}),
+                });
+            },
+            /**
+             * Promote/demote a member: REPLACES their role set (requires
+             * `manage_roles`).
+             */
+            promote: async (guild, userId, roleIds) => {
+                return this.requireTeams().setMemberRoles({
+                    groupId: guild.teamId,
+                    userId,
+                    roleIds,
+                });
+            },
+            /**
+             * Claim territory for the guild: grants runtime permission keys on a
+             * grid to every guild member (optionally one role) — enforced by the
+             * replication layer on movement/voxel writes. Requires grid admin
+             * rights on the app.
+             */
+            claimTerritory: async (guild, gridId, options = {}) => {
+                return this.gameApps.assignGroup({
+                    appId: this.appId,
+                    gridId,
+                    groupId: guild.teamId,
+                    permissionKeys: options.permissionKeys ?? ['access', 'update_voxel_data'],
+                    ...(options.groupRoleId !== undefined
+                        ? { groupRoleId: options.groupRoleId }
+                        : {}),
+                });
+            },
+        };
+        /** Chat rooms: named channels with realtime text delivery. */
+        this.chat = {
+            /** Find-or-create a chat room (an open channel) by name. */
+            room: async (name) => {
+                const channels = this.requireChannels();
+                const existing = (await channels.list(this.appId)).find((c) => c.name === name);
+                if (existing)
+                    return existing;
+                return channels.create({ appId: this.appId, name });
+            },
+            /** Join a chat room. */
+            join: async (channelId) => {
+                return this.requireChannels().join(channelId);
+            },
+            /**
+             * Send a UTF-8 text message to a room (requires channel membership with
+             * `send_messages`). Delivery is fan-out to every active member's
+             * notification subscription, regardless of world location.
+             */
+            send: async (channelId, text) => {
+                return this.requireUdp().sendChannelMessage({
+                    channelId,
+                    uuid: this.actorUuid,
+                    payload: encodeBase64(new TextEncoder().encode(text)),
+                });
+            },
+            /**
+             * Listen for messages in one room: decodes each ping's payload as UTF-8
+             * text. Returns the unsubscribe function.
+             */
+            onMessage: (channelId, callback) => {
+                return this.requireUdp().subscribe({
+                    channelMessage: (notification) => {
+                        if (String(notification.channelId) !== String(channelId))
+                            return;
+                        let text = '';
+                        try {
+                            text = new TextDecoder().decode(decodeBase64(notification.payload));
+                        }
+                        catch {
+                            text = '';
+                        }
+                        callback({
+                            channelId: String(notification.channelId),
+                            senderUuid: notification.uuid,
+                            text,
+                            epochMillis: String(notification.epochMillis),
+                        });
+                    },
+                }, String(this.appId));
+            },
+        };
+        this.actorUuid = options.actorUuid ?? generateCrowdyUuid();
+        this.partyPrefix = options.partyPrefix ?? 'party:';
+        this.guildPrefix = options.guildPrefix ?? 'guild:';
+    }
+    requireTeams() {
+        if (!this.teams) {
+            throw new Error('kit.social needs the teams domain — construct the kit via client.kit(appId)');
+        }
+        return this.teams;
+    }
+    requireChannels() {
+        if (!this.channels) {
+            throw new Error('kit.social needs the channels domain — construct the kit via client.kit(appId)');
+        }
+        return this.channels;
+    }
+    requireUdp() {
+        if (!this.udp) {
+            throw new Error('kit.social needs the udp domain — construct the kit via client.kit(appId)');
+        }
+        return this.udp;
+    }
+    /** Create a team + equally-named chat channel pair. */
+    async createPair(name, membershipPolicy, description) {
+        const team = await this.requireTeams().create({
+            appId: this.appId,
+            name,
+            description,
+            ...(membershipPolicy !== undefined ? { membershipPolicy } : {}),
+        });
+        const channel = await this.requireChannels().create({
+            appId: this.appId,
+            name,
+            description: `Chat for ${name}`,
+        });
+        return {
+            teamId: String(team.groupId),
+            channelId: String(channel.groupId),
+            name,
+        };
+    }
+    /** Find a team + channel pair by its full name. */
+    async findPair(name) {
+        const [teams, channels] = await Promise.all([
+            this.requireTeams().list(this.appId),
+            this.requireChannels().list(this.appId),
+        ]);
+        const team = teams.find((t) => t.name === name);
+        if (!team)
+            return undefined;
+        const channel = channels.find((c) => c.name === name);
+        return {
+            teamId: String(team.groupId),
+            channelId: channel ? String(channel.groupId) : '',
+            name,
+        };
+    }
+}