@helyx/bot 1.3.0 → 1.4.0

package/dist/creator-guild-join-service.js

@@ -0,0 +1,218 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { DiscordAPIError, REST, RESTJSONErrorCodes, Routes, } from "discord.js";
+import { discordRestOptions } from "./discord-rest.js";
+import { canAccessModule } from "./premium-access.js";
+const snowflake = /^\d{17,20}$/u;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** The only onboarding boundary which can add a member. Never supplies roles or other admission overrides. */
+export class DiscordCreatorGuildJoinService {
+    client;
+    services;
+    modules;
+    repository;
+    credentials;
+    #rest;
+    constructor(client, services, modules, repository, credentials) {
+        this.client = client;
+        this.services = services;
+        this.modules = modules;
+        this.repository = repository;
+        this.credentials = credentials;
+    }
+    async inspect(input) {
+        if (!snowflake.test(input.guildId) ||
+            (input.memberUserId !== undefined && !snowflake.test(input.memberUserId)))
+            return { joining: "unavailable", memberReadiness: "unavailable" };
+        const guild = this.client.isReady()
+            ? this.client.guilds.cache.get(input.guildId)
+            : undefined;
+        if (!guild?.available)
+            return { joining: "unavailable", memberReadiness: "unavailable" };
+        try {
+            if (!(await this.enabled(guild.id)))
+                return { joining: "unavailable", memberReadiness: "unavailable" };
+            await guild.fetch();
+            const paused = guild.features.includes("INVITES_DISABLED") ||
+                (guild.incidentsData?.invitesDisabledUntil?.getTime() ?? 0) >
+                    Date.now();
+            return {
+                joining: paused ? "paused" : "open",
+                memberReadiness: input.memberUserId
+                    ? await this.readiness(guild, input.memberUserId)
+                    : "member_missing",
+            };
+        }
+        catch {
+            return { joining: "unavailable", memberReadiness: "unavailable" };
+        }
+    }
+    async join(input) {
+        if (!snowflake.test(input.guildId) ||
+            !snowflake.test(input.memberUserId) ||
+            !uuid.test(input.sessionId) ||
+            !/^[A-Za-z0-9_-]{43}$/u.test(input.authorisationReference))
+            return {
+                outcome: "rejected",
+                memberReadiness: "unavailable",
+                safeCode: "invalid_authorisation",
+            };
+        return this.repository.runGuildExclusive(input.guildId, async () => {
+            const before = await this.inspect(input);
+            if (before.joining !== "open")
+                return {
+                    outcome: "rejected",
+                    memberReadiness: before.memberReadiness,
+                    safeCode: "joining_unavailable",
+                };
+            if (before.memberReadiness !== "member_missing" &&
+                before.memberReadiness !== "unavailable")
+                return {
+                    outcome: "already_member",
+                    memberReadiness: before.memberReadiness,
+                };
+            if (before.memberReadiness === "unavailable")
+                return { outcome: "uncertain", memberReadiness: "unavailable" };
+            let credential;
+            try {
+                credential = await this.credentials(input);
+            }
+            catch {
+                // No Discord write has happened, so this is a definite no-join result.
+                return {
+                    outcome: "rejected",
+                    memberReadiness: "member_missing",
+                    safeCode: "authorisation_unavailable",
+                };
+            }
+            if (!credential.accessToken ||
+                credential.applicationId !== this.client.user?.id ||
+                !this.client.token)
+                return {
+                    outcome: "rejected",
+                    memberReadiness: "member_missing",
+                    safeCode: "application_mismatch",
+                };
+            // The broker call crosses a network boundary. Check admission again just
+            // before the only write; never replay this PUT after an uncertain result.
+            const current = await this.inspect(input);
+            if (current.joining !== "open")
+                return {
+                    outcome: "rejected",
+                    memberReadiness: current.memberReadiness,
+                    safeCode: "joining_unavailable",
+                };
+            if (current.memberReadiness !== "member_missing")
+                return current.memberReadiness === "unavailable"
+                    ? { outcome: "uncertain", memberReadiness: "unavailable" }
+                    : {
+                        outcome: "already_member",
+                        memberReadiness: current.memberReadiness,
+                    };
+            this.#rest ??= new REST({
+                ...discordRestOptions,
+                retries: 0,
+                timeout: 15_000,
+            }).setToken(this.client.token);
+            try {
+                await this.#rest.put(Routes.guildMember(input.guildId, input.memberUserId), { body: { access_token: credential.accessToken } });
+            }
+            catch (error) {
+                const after = await this.inspect(input);
+                if (!["member_missing", "unavailable"].includes(after.memberReadiness)) {
+                    await this.logJoined(input);
+                    return { outcome: "joined", memberReadiness: after.memberReadiness };
+                }
+                return {
+                    outcome: error instanceof DiscordAPIError &&
+                        error.status >= 400 &&
+                        error.status < 500 &&
+                        error.status !== 429
+                        ? "rejected"
+                        : "uncertain",
+                    memberReadiness: after.memberReadiness,
+                    safeCode: "join_not_confirmed",
+                };
+            }
+            const after = await this.inspect(input);
+            if (!["member_missing", "unavailable"].includes(after.memberReadiness))
+                await this.logJoined(input);
+            return {
+                outcome: ["member_missing", "unavailable"].includes(after.memberReadiness)
+                    ? "uncertain"
+                    : "joined",
+                memberReadiness: after.memberReadiness,
+            };
+        });
+    }
+    async logJoined(input) {
+        // Joining is core-owned; emit the module-declared event only after a new
+        // admission is confirmed. Logging must never change the admission outcome.
+        try {
+            if (!this.services.has(HELYX_SERVICE_NAMES.moduleLogging))
+                return;
+            await this.services
+                .get(HELYX_SERVICE_NAMES.moduleLogging)
+                .emit({
+                guildId: input.guildId,
+                moduleId: "helyx.creator-connections",
+                eventId: "integrated-invite-joined",
+                summary: "Member joined through integrated invite",
+                details: [{ label: "Member", value: input.memberUserId }],
+                idempotencyKey: `cc-integrated-join:${input.sessionId}`,
+            });
+        }
+        catch {
+            // Optional log delivery cannot turn a successful join into an error.
+        }
+    }
+    async enabled(guildId) {
+        const module = this.modules.find((candidate) => candidate.manifest.id === "helyx.creator-connections");
+        return Boolean(module &&
+            (await this.services
+                .get(HELYX_SERVICE_NAMES.installations)
+                .isModuleEnabled(guildId, module.manifest.id)) &&
+            (await this.services
+                .get(HELYX_SERVICE_NAMES.moduleAvailability)
+                .isAvailable(module.manifest.id)) &&
+            (await canAccessModule(this.services, guildId, module)));
+    }
+    async readiness(guild, memberUserId) {
+        try {
+            const member = await guild.members.fetch({
+                user: memberUserId,
+                force: true,
+            });
+            if (member.pending)
+                return "screening_pending";
+            for (const module of this.modules) {
+                if (!module.admissionGate ||
+                    !(await this.services
+                        .get(HELYX_SERVICE_NAMES.installations)
+                        .isModuleEnabled(guild.id, module.manifest.id)))
+                    continue;
+                if (!(await this.services
+                    .get(HELYX_SERVICE_NAMES.moduleAvailability)
+                    .isAvailable(module.manifest.id)))
+                    return "unavailable";
+                const gate = await module.admissionGate({
+                    guildId: guild.id,
+                    memberUserId,
+                    roleIds: [...member.roles.cache.keys()],
+                    services: this.services,
+                });
+                if (gate === "unavailable")
+                    return "unavailable";
+                if (gate !== "ready")
+                    return "access_pending";
+            }
+            return "ready";
+        }
+        catch (error) {
+            return error instanceof DiscordAPIError &&
+                error.code === RESTJSONErrorCodes.UnknownMember
+                ? "member_missing"
+                : "unavailable";
+        }
+    }
+}
+//# sourceMappingURL=creator-guild-join-service.js.map

package/dist/creator-invite-service.d.ts

@@ -0,0 +1,37 @@
+import type { CreatorInviteRepository } from "@helyx/database";
+import { type CreatorInviteService, type CreatorOwnedInvite, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import { type Client } from "discord.js";
+/** Hosted, guild-owning core adapter. Modules never receive its encryption key/store. */
+export declare class DiscordCreatorInviteService implements CreatorInviteService {
+    #private;
+    private readonly client;
+    private readonly repository;
+    private readonly services;
+    private readonly module;
+    constructor(client: Client, repository: CreatorInviteRepository, services: ServiceAccess, module: ModuleDefinition | undefined, encodedEncryptionKey: string);
+    selectableRoles(input: Parameters<CreatorInviteService["selectableRoles"]>[0]): ReturnType<CreatorInviteService["selectableRoles"]>;
+    create(input: Parameters<CreatorInviteService["create"]>[0]): Promise<CreatorOwnedInvite>;
+    inspect(input: Parameters<CreatorInviteService["inspect"]>[0]): Promise<CreatorOwnedInvite>;
+    shareUrl(input: Parameters<CreatorInviteService["shareUrl"]>[0]): Promise<{
+        url: string;
+    }>;
+    publicOverview(input: {
+        guildId: string;
+        reference: string;
+    }): Promise<{
+        guildName: string;
+        guildIconUrl: string | null;
+        discordInviteUrl: string;
+    }>;
+    revoke(input: Parameters<CreatorInviteService["revoke"]>[0]): ReturnType<CreatorInviteService["revoke"]>;
+    /** Cancels a durable intent without issuing a create POST, including rejected intents. */
+    cancelOperation(input: {
+        guildId: string;
+        operationId: string;
+    }): Promise<{
+        state: "revoked" | "revocation_pending" | "unknown";
+    }>;
+    /** Runs outside module enablement; only proven access/safety loss initiates revocation. */
+    cleanupUnavailableInvites(): Promise<void>;
+}
+//# sourceMappingURL=creator-invite-service.d.ts.map