@helyx/bot 0.4.46 → 0.6.1

package/dist/shard-supervisor.js

@@ -1,5 +1,5 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
@@ -24,6 +24,9 @@ import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
+import { createPremiumActivationModule } from "./premium-activation-module.js";
+import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
 import { discordRestOptions } from "./discord-rest.js";
 import { availabilityCatalogue, availabilityCatalogueDefinitions, statusCatalogueDefinitions, } from "./module-availability-control.js";
 import { createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
@@ -35,6 +38,8 @@ import { GuildCommandWorker } from "./guild-command-worker.js";
 import { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
 import { GuildCommandReadService } from "./guild-command-read-service.js";
 import { scheduleGuildCommandRelease } from "./guild-command-release.js";
+import { assertReviewedPremiumCatalogue, requirePremiumProviderEnvironment, } from "./premium-access.js";
+import { enforcePremiumCatalogue, PREMIUM_CATALOGUE_ENFORCEMENT_INTERVAL_MS, } from "./premium-catalogue-enforcement.js";
 const LEASE_RENEW_INTERVAL_MS = 10_000;
 const STARTUP_LEASE_RENEW_INTERVAL_MS = 5_000;
 const LEASE_VALIDATION_TIMEOUT_MS = 1_000;
@@ -121,6 +126,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let maintainingLeases = false;
     let rebalancingShards = false;
     let retentionTimer;
+    let premiumCatalogueTimer;
     let leaseTimer;
     let startupLeaseTimer;
     let startupWorkerHeartbeats;
@@ -156,6 +162,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
         const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const featureModules = modulePackages.map(({ definition }) => definition);
+        assertReviewedPremiumCatalogue(featureModules);
         const gateway = await fetchGatewayBotInformation(environment.DISCORD_TOKEN);
         shardCount =
             environment.HELYX_SHARD_MODE === "fixed"
@@ -211,6 +218,16 @@ export async function startShardSupervisor(environment, processEnvironment, work
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
+        const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
+        const premiumActivationModule = !premiumEnvironment
+            ? undefined
+            : createPremiumActivationModule({
+                allocations: new PremiumAllocationRepository(database),
+                authority: new DiscordPremiumGuildAuthority(commandClient),
+                provider: "stripe",
+                providerEnvironment: premiumEnvironment,
+                reviewedPremiumModuleIds: REVIEWED_PREMIUM_MODULE_IDS,
+            });
         const oauthModule = environment.HELYX_OAUTH_ENABLED
             ? createOAuthModule()
             : undefined;
@@ -219,6 +236,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             permissionsModule,
             supportModule,
             privacyModule,
+            ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
@@ -240,6 +258,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
@@ -1102,6 +1121,13 @@ export async function startShardSupervisor(environment, processEnvironment, work
         await cleanupExpiredCoreRecords(database, logger);
         retentionTimer = setInterval(() => void cleanupExpiredCoreRecords(database, logger), RETENTION_CLEANUP_INTERVAL_MS);
         retentionTimer.unref();
+        premiumCatalogueTimer = setInterval(() => void enforcePremiumCatalogue(database, logger).catch((error) => {
+            logger.warn({
+                event: "premium.catalogue_enforcement_failed",
+                error: safeError(error),
+            }, "Premium module catalogue enforcement failed");
+        }), PREMIUM_CATALOGUE_ENFORCEMENT_INTERVAL_MS);
+        premiumCatalogueTimer.unref();
         await cloudConnector?.start();
         cloudStarted = true;
         if (workersRoutable)
@@ -1373,6 +1399,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
         startupWorkerHeartbeats = undefined;
         if (retentionTimer)
             clearInterval(retentionTimer);
+        if (premiumCatalogueTimer)
+            clearInterval(premiumCatalogueTimer);
         workersRoutable = false;
         await scheduledTasks?.stop().catch(() => undefined);
         scheduledTasks = undefined;
@@ -1443,6 +1471,7 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
         moduleVersion: definition.manifest.version,
         migrationsDirectory: join(packageRoot, "migrations"),
     })));
+    await enforcePremiumCatalogue(database, logger);
     const repository = new RuntimeStateRepository(database);
     await synchroniseApplicationCommands({
         applicationId: environment.DISCORD_CLIENT_ID,

package/dist/shard-worker.d.ts

@@ -63,6 +63,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_STATUS_ENABLED: boolean;
     HELYX_STATUS_URL: string;
     HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS: number;
+    STRIPE_ENVIRONMENT?: "sandbox" | "live" | undefined;
     HELYX_BOT_CONTROL_SECRET?: string | undefined;
     HELYX_SUPPORT_SERVICE_SECRET?: string | undefined;
     HELYX_VERIFICATION_INSTALLATION_ID?: string | undefined;
@@ -86,6 +87,7 @@ export declare function shardWorkerCommandRegistration(input: {
     prepare: NonNullable<CommandRegistration["prepare"]>;
     operationsModuleId?: string;
     supportModuleId: string;
+    premiumActivationModuleId?: string;
     oauthModuleId?: string;
 }): CommandRegistration;
 //# sourceMappingURL=shard-worker.d.ts.map

package/dist/shard-worker.js

@@ -1,8 +1,9 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, } from "@helyx/database";
+import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices } from "@helyx/platform";
+import { createPlatformServices, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, Partials } from "discord.js";
 import { monitorEventLoopDelay } from "node:perf_hooks";
@@ -18,9 +19,14 @@ import { DiscordModuleLoggingService } from "./module-logging.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
 import { createPermissionsModule } from "./permissions-module.js";
+import { createPremiumActivationModule } from "./premium-activation-module.js";
+import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
+import { assertReviewedPremiumCatalogue, requirePremiumProviderEnvironment, } from "./premium-access.js";
 import { WorkerCloudConnectorProxy } from "./shard-cloud-proxy.js";
 import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
 import { DiscordGuildHealthInspection } from "./discord-guild-health.js";
+import { DiscordAnalyticsInspection } from "./discord-analytics.js";
+import { DiscordInviteInspection } from "./discord-invites.js";
 import { CoreResourceAuthorizationService } from "./resource-authorization.js";
 import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
@@ -116,6 +122,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const featureModules = modulePackages.map(({ definition }) => definition);
+        assertReviewedPremiumCatalogue(featureModules);
         client = new Client({
             rest: discordRestOptions,
             intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED, environment.HELYX_GUILD_MEMBERS_ENABLED),
@@ -138,6 +145,16 @@ export async function startShardWorker(processEnvironment = process.env, identit
             : undefined;
         const supportModule = createSupportModule(cloudProxy);
         const privacyModule = createPrivacyModule();
+        const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
+        const premiumActivationModule = !premiumEnvironment
+            ? undefined
+            : createPremiumActivationModule({
+                allocations: new PremiumAllocationRepository(database),
+                authority: new DiscordPremiumGuildAuthority(client),
+                provider: "stripe",
+                providerEnvironment: premiumEnvironment,
+                reviewedPremiumModuleIds: REVIEWED_PREMIUM_MODULE_IDS,
+            });
         const oauthModule = environment.HELYX_OAUTH_ENABLED
             ? createOAuthModule()
             : undefined;
@@ -146,6 +163,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             permissionsModule,
             supportModule,
             privacyModule,
+            ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
@@ -166,6 +184,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
@@ -181,8 +200,9 @@ export async function startShardWorker(processEnvironment = process.env, identit
         ];
         const platformServices = new Map();
         const serviceAccess = new ServiceRegistry(platformServices);
+        const serviceOptions = platformServiceOptions(environment, publicModules);
         for (const [name, service] of createPlatformServices(database, publicModules, {
-            ...platformServiceOptions(environment, publicModules),
+            ...serviceOptions,
             activationServices: serviceAccess,
         })) {
             platformServices.set(name, service);
@@ -213,9 +233,14 @@ export async function startShardWorker(processEnvironment = process.env, identit
         platformServices.set(HELYX_SERVICE_NAMES.discordMessages, new DiscordMessageDeliveryService(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordOwnedMessages, new DiscordOwnedMessageDeletionService(client));
         platformServices.set(HELYX_SERVICE_NAMES.memberEnforcement, new DiscordMemberEnforcementService(client));
-        platformServices.set(HELYX_SERVICE_NAMES.memberRoles, new DiscordMemberRoleService(client));
+        const memberRoles = new DiscordMemberRoleService(client);
+        platformServices.set(HELYX_SERVICE_NAMES.memberRoles, memberRoles);
+        platformServices.set(HELYX_SERVICE_NAMES.memberRoleGrants, new PlatformMemberRoleGrantOwnershipService(new PostgresMemberRoleGrantOwnershipStore(database), memberRoles));
         platformServices.set(HELYX_SERVICE_NAMES.discordResources, new DiscordResourceInspection(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordGuildHealth, new DiscordGuildHealthInspection(client, publicModules, serviceAccess));
+        platformServices.set(HELYX_SERVICE_NAMES.discordAnalytics, new DiscordAnalyticsInspection(client));
+        if (serviceOptions.inviteFingerprintKey)
+            platformServices.set(HELYX_SERVICE_NAMES.discordInvites, new DiscordInviteInspection(client, serviceOptions.inviteFingerprintKey));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging"))
             platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, publicModules, logger));
         const scheduledTaskRoute = createLocalScheduledTaskRoute({
@@ -228,6 +253,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             managementModule.manifest.id,
             permissionsModule.manifest.id,
             supportModule.manifest.id,
+            ...(premiumActivationModule ? [premiumActivationModule.manifest.id] : []),
             ...(oauthModule ? [oauthModule.manifest.id] : []),
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
@@ -250,6 +276,9 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 ? { operationsModuleId: operationsModule.manifest.id }
                 : {}),
             supportModuleId: supportModule.manifest.id,
+            ...(premiumActivationModule
+                ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
+                : {}),
             ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
         }), logger, serviceAccess);
         moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess);
@@ -444,6 +473,9 @@ export function shardWorkerCommandRegistration(input) {
         synchronise: false,
         selfAuthorizingGuildModuleIds: new Set([
             input.supportModuleId,
+            ...(input.premiumActivationModuleId
+                ? [input.premiumActivationModuleId]
+                : []),
             ...(input.oauthModuleId ? [input.oauthModuleId] : []),
             ...(input.operationsModuleId ? [input.operationsModuleId] : []),
         ]),

package/documentation/examples/.env.example

@@ -92,8 +92,8 @@ HELYX_OAUTH_ENABLED=false
 # Generated module selection
 HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
 
-# Generated privately by npm run setup. Never change it while Cloud Connect is
-# enrolled or a checkpointed Giveaways draw is in progress.
+# Generated privately by npm run setup. Required by Cloud Connect, Giveaways,
+# and Invite Tracking; retain it unchanged across restarts and deployments.
 # HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
 
 # Official Cloud Connect endpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.46",
+  "version": "0.6.1",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -50,14 +50,14 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=0.5.0 <0.6.0",
+    "@helyx/config": ">=1.0.0 <2.0.0",
     "@helyx/control-protocol": ">=0.4.0 <0.5.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=0.9.0 <0.10.0",
+    "@helyx/database": ">=1.0.0 <2.0.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
-    "@helyx/module-manifest": ">=0.8.0 <0.9.0",
-    "@helyx/platform": ">=0.6.2 <0.7.0",
-    "@helyx/sdk": ">=0.9.0 <0.10.0",
+    "@helyx/module-manifest": ">=0.9.0 <0.10.0",
+    "@helyx/platform": ">=0.8.0 <0.9.0",
+    "@helyx/sdk": ">=0.11.0 <0.12.0",
     "@helyx/status-client": ">=0.1.0 <0.2.0",
     "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
     "discord.js": "14.27.0",