@helyx/bot 1.3.0 → 1.4.0

package/dist/control-server-schemas.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { hasBoundedManagedResourceBytes, isBoundedManagedResourceValue, } from "./dashboard-feature-control.js";
+export const snowflake = z.string().regex(/^\d{17,20}$/u);
+export const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+export const configurationValue = z.record(z.string(), z.union([
+    z.null(),
+    z.string(),
+    z.boolean(),
+    z.number().finite(),
+    z.array(z.string()).max(100),
+]));
+const permissionPreset = z.enum([
+    "everyone",
+    "moderators",
+    "administrators",
+    "custom",
+]);
+const dashboardPermissionPolicy = z.object({
+    preset: permissionPreset,
+    allowedRoleIds: z.array(snowflake).max(100),
+    deniedRoleIds: z.array(snowflake).max(100),
+});
+export const permissionState = z.object({
+    version: z.number().int().min(0),
+    module: dashboardPermissionPolicy,
+    commands: z
+        .array(z.object({
+        commandId: z.string().min(1).max(100),
+        version: z.number().int().min(0),
+        enabled: z.boolean(),
+        policy: dashboardPermissionPolicy,
+    }))
+        .max(100),
+});
+export const guildAccessPolicy = z
+    .object({
+    administratorRoleIds: z.array(snowflake).max(25),
+    moderatorRoleIds: z.array(snowflake).max(25),
+    dashboardModeratorsEnabled: z.boolean(),
+    dashboardAllowedRoleIds: z.array(snowflake).max(25),
+    dashboardDeniedRoleIds: z.array(snowflake).max(25),
+})
+    .strict();
+export const mutationContext = z.object({
+    actorUserId: snowflake,
+    correlationId: z.uuid(),
+});
+export const resourceId = z.string().trim().min(1).max(100);
+export const resourceCursor = z.string().min(1).max(2_048);
+export const resourceActionId = z.string().regex(/^[a-z][a-z0-9_-]*$/u);
+export const managedResourceFilters = z
+    .record(z.string().regex(/^[a-z][a-zA-Z0-9_]*$/u), z.string().trim().min(1).max(100))
+    .refine((value) => Object.keys(value).length <= 8);
+const managedResourceValue = z.custom((value) => isBoundedManagedResourceValue(value), "Managed resource value exceeds the transport limits");
+export const managedResourceObject = z
+    .record(z.string().min(1).max(100), managedResourceValue)
+    .refine(hasBoundedManagedResourceBytes);
+const managedResourceSummarySchema = z
+    .object({
+    id: resourceId,
+    revision: z.number().int().min(0),
+    status: z.string().trim().min(1).max(100),
+    title: z.string().trim().min(1).max(200),
+    description: z.string().max(500).optional(),
+    attributes: managedResourceObject.optional(),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+export const managedResourceDetailSchema = managedResourceSummarySchema
+    .extend({
+    value: managedResourceObject,
+    availableActionIds: z.array(z.string().min(1).max(100)).max(50).optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourcePageSchema = z
+    .object({
+    items: z.array(managedResourceSummarySchema).max(50),
+    nextCursor: resourceCursor.optional(),
+    total: z.number().int().min(0).optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourceRelationPageSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        id: resourceId,
+        value: managedResourceObject,
+    })
+        .strict())
+        .max(50),
+    nextCursor: resourceCursor.optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourceDeleteResultSchema = z
+    .object({ deleted: z.boolean() })
+    .strict();
+//# sourceMappingURL=control-server-schemas.js.map

package/dist/control-server.d.ts

@@ -1,4 +1,6 @@
-import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
+import { AuditRepository, GuildAccessPolicyRepository, InstallationRepository, ModuleLoggingPolicyRepository, PermissionPolicyRepository, type DatabasePool, type GuildShardOwnership } from "@helyx/database";
+import type { MysqlPool } from "@helyx/database-mysql";
+import type { CreatorOnboardingRequest, CreatorOnboardingResponse } from "@helyx/sdk";
 import { type DashboardActionInspection, type DashboardActionResult, type FeatureAccessDecision, type GuildAccessPolicy, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type OAuthConsumerCleanupResult, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type PublicAchievementProjectionPage, type ServiceAccess } from "@helyx/sdk";
 import { type ActionReceipt, type SignedAssessmentEnvelope } from "@helyx/verification-contracts";
 import { type Client } from "discord.js";
@@ -7,6 +9,7 @@ import { type BotModuleStatusMutationResult } from "./module-status-control.js";
 import { type FirstTimeCommandSetupHandler } from "./first-time-command-setup.js";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
 import { type DashboardPermissionState } from "./control-permissions.js";
+export { BotControlTransportError } from "./control-errors.js";
 import { type DashboardModuleDefinition } from "./dashboard-module-projection.js";
 import { type AvailabilityModuleCatalogue } from "./module-availability-control.js";
 import { registerGuildCommandControlRoutes } from "./guild-command-control-routes.js";
@@ -118,6 +121,7 @@ export interface DashboardGuildAccessState extends GuildAccessPolicy {
     updatedAt: string | null;
 }
 export interface BotControlHandler extends FirstTimeCommandSetupHandler, DashboardActionHandler {
+    creatorOnboarding?(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     cleanupOAuthConsumer(input: {
         consumerBindingId: string;
         moduleId: string;
@@ -324,21 +328,32 @@ export interface BotControlHandler extends FirstTimeCommandSetupHandler, Dashboa
         cursor?: string;
     }): Promise<PrivacyErasePage>;
 }
-export declare class BotControlTransportError extends Error {
-    readonly status: 400 | 403 | 404 | 409 | 502 | 503 | 504;
-    constructor(status: 400 | 403 | 404 | 409 | 502 | 503 | 504, message: string);
+export interface BotControlRepositories {
+    installations: Pick<InstallationRepository, "adoptGuildsForReconciliation" | "markGuildsRemovedForReconciliation" | "listModules" | "isModuleEnabled">;
+    accessPolicies: Pick<GuildAccessPolicyRepository, "get" | "save">;
+    loggingPolicies: Pick<ModuleLoggingPolicyRepository, "listForGuild" | "save">;
+    permissionPolicies: Pick<PermissionPolicyRepository, "save" | "deleteCommandPolicy">;
+    audit: Pick<AuditRepository, "append">;
 }
+interface ControlPersistence {
+    readonly repositories: BotControlRepositories;
+    withTransaction<Value>(operation: (repositories: BotControlRepositories) => Promise<Value>): Promise<Value>;
+}
+export interface BotControlPersistence extends ControlPersistence {
+    readonly engine: "mysql";
+}
+export declare function createMysqlBotControlPersistence(pool: MysqlPool): Promise<BotControlPersistence>;
 export declare class BotControlService implements BotControlHandler {
     #private;
-    private readonly database;
     private readonly resources;
     private readonly supportNotifications?;
     private readonly presenceOwnership?;
     private readonly presenceShardCount?;
-    constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor, supportNotifications?: {
+    constructor(databaseOrPersistence: DatabasePool | BotControlPersistence, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor, supportNotifications?: {
         guildId: string;
         channelId: string;
     } | undefined, presenceOwnership?: GuildShardOwnership | undefined, presenceShardCount?: number | undefined, statusModules?: readonly ModuleDefinition[]);
+    creatorOnboarding(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     cleanupOAuthConsumer(input: {
         consumerBindingId: string;
         moduleId: string;
@@ -590,5 +605,4 @@ export declare function mapBotControlError(error: unknown): {
     status: 400 | 403 | 404 | 409;
     message: string;
 } | undefined;
-export {};
 //# sourceMappingURL=control-server.d.ts.map

package/dist/control-server.js

@@ -13,116 +13,21 @@ import { canAccessModule, PREMIUM_MODULE_UNAVAILABLE_MESSAGE, } from "./premium-
 import { completeFirstTimeCommandSetup, } from "./first-time-command-setup.js";
 import { SHARD_HEALTH_STALE_MS, } from "./shard-contracts.js";
 import { assertVersion, declaredManagedResourcePermission, fromDashboardPolicy, managedResourcePermissionId, permissionPoliciesEqual, permissionPolicyKey, safeOptionalVersion, safeVersion, toDashboardPolicy, } from "./control-permissions.js";
-import { assertPermissionMutationAllowed, BotControlForbiddenError, } from "./control-errors.js";
+import { assertPermissionMutationAllowed, BotControlForbiddenError, BotControlTransportError, } from "./control-errors.js";
+export { BotControlTransportError } from "./control-errors.js";
 import { dashboardCommands } from "./dashboard-commands.js";
+import { executeCreatorOnboarding, registerCreatorOnboardingControlRoute, } from "./creator-onboarding-control.js";
 import { mapDashboardModule, } from "./dashboard-module-projection.js";
 import { availabilityCatalogueDefinitions, availabilityCatalogue, dashboardModuleStatus, disabledModuleSummary, moduleAvailabilityService, moduleAvailabilityStates, statusCatalogueDefinitions, } from "./module-availability-control.js";
 import { registerGuildCommandControlRoutes } from "./guild-command-control-routes.js";
 import { createPrivacyProviderRegistry, describePrivacyProviders, } from "./privacy-provider-registry.js";
-import { changedSettingFeatureIds, configurationPreviewFeatureIds, hasBoundedManagedResourceBytes, isBoundedManagedResourceValue, managedResourceColumnKeys, normalizeManagedResourceDetail, normalizeManagedResourcePage, normalizeManagedResourceRelationPage, projectManagedResourceObject, requireDashboardFeatures, resourceFieldFeatureIds, scalarInputFeatureIds, validateManagedResourceInput, } from "./dashboard-feature-control.js";
+import { changedSettingFeatureIds, configurationPreviewFeatureIds, managedResourceColumnKeys, normalizeManagedResourceDetail, normalizeManagedResourcePage, normalizeManagedResourceRelationPage, projectManagedResourceObject, requireDashboardFeatures, resourceFieldFeatureIds, scalarInputFeatureIds, validateManagedResourceInput, } from "./dashboard-feature-control.js";
 import { registerDashboardPreviewImportRoutes, registerDashboardResourceMutationRoutes, } from "./dashboard-preview-import-routes.js";
 import { executeDashboardAction as executeDeclaredDashboardAction, previewDashboardAction as previewDeclaredDashboardAction, } from "./dashboard-action-control.js";
 import { registerDashboardActionRoutes, } from "./dashboard-action-routes.js";
 import { registerEckoTransportRoutes, } from "./ecko-transport-routes.js";
 import { validateDiscordUserSettingSelections, validateDiscordSettingSelections, } from "./dashboard-discord-settings.js";
-const snowflake = z.string().regex(/^\d{17,20}$/u);
-const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
-const configurationValue = z.record(z.string(), z.union([
-    z.null(),
-    z.string(),
-    z.boolean(),
-    z.number().finite(),
-    z.array(z.string()).max(100),
-]));
-const permissionPreset = z.enum([
-    "everyone",
-    "moderators",
-    "administrators",
-    "custom",
-]);
-const dashboardPermissionPolicy = z.object({
-    preset: permissionPreset,
-    allowedRoleIds: z.array(snowflake).max(100),
-    deniedRoleIds: z.array(snowflake).max(100),
-});
-const permissionState = z.object({
-    version: z.number().int().min(0),
-    module: dashboardPermissionPolicy,
-    commands: z
-        .array(z.object({
-        commandId: z.string().min(1).max(100),
-        version: z.number().int().min(0),
-        enabled: z.boolean(),
-        policy: dashboardPermissionPolicy,
-    }))
-        .max(100),
-});
-const guildAccessPolicy = z
-    .object({
-    administratorRoleIds: z.array(snowflake).max(25),
-    moderatorRoleIds: z.array(snowflake).max(25),
-    dashboardModeratorsEnabled: z.boolean(),
-    dashboardAllowedRoleIds: z.array(snowflake).max(25),
-    dashboardDeniedRoleIds: z.array(snowflake).max(25),
-})
-    .strict();
-const mutationContext = z.object({
-    actorUserId: snowflake,
-    correlationId: z.uuid(),
-});
-const resourceId = z.string().trim().min(1).max(100);
-const resourceCursor = z.string().min(1).max(2_048);
-const resourceActionId = z.string().regex(/^[a-z][a-z0-9_-]*$/u);
-const managedResourceFilters = z
-    .record(z.string().regex(/^[a-z][a-zA-Z0-9_]*$/u), z.string().trim().min(1).max(100))
-    .refine((value) => Object.keys(value).length <= 8);
-const managedResourceValue = z.custom((value) => isBoundedManagedResourceValue(value), "Managed resource value exceeds the transport limits");
-const managedResourceObject = z
-    .record(z.string().min(1).max(100), managedResourceValue)
-    .refine(hasBoundedManagedResourceBytes);
-const managedResourceSummarySchema = z
-    .object({
-    id: resourceId,
-    revision: z.number().int().min(0),
-    status: z.string().trim().min(1).max(100),
-    title: z.string().trim().min(1).max(200),
-    description: z.string().max(500).optional(),
-    attributes: managedResourceObject.optional(),
-    updatedAt: z.iso.datetime({ offset: true }),
-})
-    .strict();
-const managedResourceDetailSchema = managedResourceSummarySchema
-    .extend({
-    value: managedResourceObject,
-    availableActionIds: z.array(z.string().min(1).max(100)).max(50).optional(),
-})
-    .strict()
-    .refine(hasBoundedManagedResourceBytes);
-const managedResourcePageSchema = z
-    .object({
-    items: z.array(managedResourceSummarySchema).max(50),
-    nextCursor: resourceCursor.optional(),
-    total: z.number().int().min(0).optional(),
-})
-    .strict()
-    .refine(hasBoundedManagedResourceBytes);
-const managedResourceRelationPageSchema = z
-    .object({
-    items: z
-        .array(z
-        .object({
-        id: resourceId,
-        value: managedResourceObject,
-    })
-        .strict())
-        .max(50),
-    nextCursor: resourceCursor.optional(),
-})
-    .strict()
-    .refine(hasBoundedManagedResourceBytes);
-const managedResourceDeleteResultSchema = z
-    .object({ deleted: z.boolean() })
-    .strict();
+import { configurationValue, guildAccessPolicy, managedResourceDeleteResultSchema, managedResourceDetailSchema, managedResourceFilters, managedResourceObject, managedResourcePageSchema, managedResourceRelationPageSchema, moduleId, mutationContext, permissionState, resourceActionId, resourceCursor, resourceId, snowflake, } from "./control-server-schemas.js";
 export class DiscordGuildResourceDirectory {
     client;
     constructor(client) {
@@ -265,16 +170,37 @@ export class DiscordGuildResourceDirectory {
         await sendDiscordMessageToChannel(this.client, channel.id, response, notificationId);
     }
 }
-export class BotControlTransportError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
-        this.name = "BotControlTransportError";
-    }
+function createPostgresControlRepositories(connection) {
+    return {
+        installations: new InstallationRepository(connection),
+        accessPolicies: new GuildAccessPolicyRepository(connection),
+        loggingPolicies: new ModuleLoggingPolicyRepository(connection),
+        permissionPolicies: new PermissionPolicyRepository(connection),
+        audit: new AuditRepository(connection),
+    };
+}
+function createPostgresControlPersistence(database) {
+    return {
+        repositories: createPostgresControlRepositories(database),
+        withTransaction: (operation) => withTransaction(database, (connection) => operation(createPostgresControlRepositories(connection))),
+    };
+}
+export async function createMysqlBotControlPersistence(pool) {
+    const mysql = await import("@helyx/database-mysql");
+    const repositories = (connection) => ({
+        installations: new mysql.InstallationRepository(connection),
+        accessPolicies: new mysql.GuildAccessPolicyRepository(connection),
+        loggingPolicies: new mysql.ModuleLoggingPolicyRepository(connection),
+        permissionPolicies: new mysql.PermissionPolicyRepository(connection),
+        audit: new mysql.AuditRepository(connection),
+    });
+    return {
+        engine: "mysql",
+        repositories: repositories(pool),
+        withTransaction: (operation) => mysql.withMysqlTransaction(pool, (connection) => operation(repositories(mysql.createMysqlQueryExecutor(connection)))),
+    };
 }
 export class BotControlService {
-    database;
     resources;
     supportNotifications;
     presenceOwnership;
@@ -288,12 +214,16 @@ export class BotControlService {
     #permissions;
     #services;
     #privacyProviders;
-    constructor(database, modules, resources, services, privacyExecutor, supportNotifications, presenceOwnership, presenceShardCount, statusModules) {
-        this.database = database;
+    #persistence;
+    constructor(databaseOrPersistence, modules, resources, services, privacyExecutor, supportNotifications, presenceOwnership, presenceShardCount, statusModules) {
         this.resources = resources;
         this.supportNotifications = supportNotifications;
         this.presenceOwnership = presenceOwnership;
         this.presenceShardCount = presenceShardCount;
+        this.#persistence =
+            "engine" in databaseOrPersistence
+                ? databaseOrPersistence
+                : createPostgresControlPersistence(databaseOrPersistence);
         this.#modules = new Map(modules.map((module) => [module.manifest.id, module]));
         this.#dashboardModules = modules
             .filter((module) => module.manifest.dashboard !== undefined)
@@ -306,6 +236,13 @@ export class BotControlService {
         this.#services = services;
         this.#privacyProviders = createPrivacyProviderRegistry(modules, privacyExecutor, this.#services);
     }
+    async creatorOnboarding(input) {
+        return executeCreatorOnboarding(input, {
+            modules: this.#modules,
+            installations: this.#installations,
+            services: this.#services,
+        });
+    }
     async cleanupOAuthConsumer(input) {
         const module = this.#modules.get(input.moduleId);
         if (!module)
@@ -344,7 +281,7 @@ export class BotControlService {
             .filter(({ state }) => state === "not_installed")
             .map(({ guildId }) => guildId);
         if (absent.length > 0) {
-            const repository = new InstallationRepository(this.database);
+            const repository = this.#persistence.repositories.installations;
             if (this.presenceOwnership)
                 await repository.adoptGuildsForReconciliation({
                     guildIds: absent,
@@ -439,8 +376,8 @@ export class BotControlService {
         ]);
         const [resources, installedModules, storedLoggingPolicies, runtime, storedConfigurations, storedPermissions, availabilityStates,] = await Promise.all([
             this.resources.getGuildResources(guildId),
-            new InstallationRepository(this.database).listModules(guildId),
-            new ModuleLoggingPolicyRepository(this.database).listForGuild(guildId),
+            this.#persistence.repositories.installations.listModules(guildId),
+            this.#persistence.repositories.loggingPolicies.listForGuild(guildId),
             this.#inspectRuntimeCapabilities(),
             this.#readConfigurations(guildId, moduleIds),
             this.#readPermissionPolicies(guildId, permissionTargets),
@@ -516,7 +453,7 @@ export class BotControlService {
     async getGuildAccessPolicy(input) {
         const [actor, record] = await Promise.all([
             this.resources.resolveActor(input.guildId, input.actorUserId),
-            new GuildAccessPolicyRepository(this.database).get(input.guildId),
+            this.#persistence.repositories.accessPolicies.get(input.guildId),
         ]);
         const policy = record ?? DEFAULT_GUILD_ACCESS_POLICY;
         return {
@@ -547,8 +484,8 @@ export class BotControlService {
         ];
         if (roleIds.some((roleId) => !availableRoles.has(roleId)))
             throw new BotControlValidationError("Dashboard access contains a Discord role that is no longer available");
-        const saved = await withTransaction(this.database, async (connection) => {
-            const record = await new GuildAccessPolicyRepository(connection).save({
+        const saved = await this.#persistence.withTransaction(async (repositories) => {
+            const record = await repositories.accessPolicies.save({
                 guildId: input.guildId,
                 administratorRoleIds: [...input.policy.administratorRoleIds],
                 moderatorRoleIds: [...input.policy.moderatorRoleIds],
@@ -558,7 +495,7 @@ export class BotControlService {
                 expectedVersion: input.version === 0 ? null : BigInt(input.version),
                 updatedBy: input.actorUserId,
             });
-            await new AuditRepository(connection).append({
+            await repositories.audit.append({
                 guildId: input.guildId,
                 actorUserId: input.actorUserId,
                 action: "guild.access.updated",
@@ -590,14 +527,14 @@ export class BotControlService {
         };
     }
     async #readGuildAccessPolicy(guildId) {
-        return ((await new GuildAccessPolicyRepository(this.database).get(guildId)) ??
+        return ((await this.#persistence.repositories.accessPolicies.get(guildId)) ??
             DEFAULT_GUILD_ACCESS_POLICY);
     }
     async readPublicModuleProjection(input) {
         const module = this.#requireModule(input.moduleId);
         if (!module.publicProjection)
             throw new BotControlNotFoundError("Public module projection was not found");
-        if (!(await new InstallationRepository(this.database).isModuleEnabled(input.guildId, input.moduleId)))
+        if (!(await this.#persistence.repositories.installations.isModuleEnabled(input.guildId, input.moduleId)))
             throw new BotControlValidationError("This module is not enabled");
         if (input.subjectUserId) {
             if (!this.#services.has(HELYX_SERVICE_NAMES.discordResources))
@@ -775,9 +712,9 @@ export class BotControlService {
             if (enabledChanged || !permissionPoliciesEqual(current.policy, target))
                 assertPermissionMutationAllowed(canMutatePermissionPolicy(actor, current.policy, target, guildAccess, rolePositions));
         }
-        await withTransaction(this.database, async (connection) => {
-            const policies = new PermissionPolicyRepository(connection);
-            const audit = new AuditRepository(connection);
+        await this.#persistence.withTransaction(async (repositories) => {
+            const policies = repositories.permissionPolicies;
+            const audit = repositories.audit;
             const savedModule = await policies.save({
                 guildId: input.guildId,
                 moduleId: input.moduleId,
@@ -799,6 +736,12 @@ export class BotControlService {
             for (const command of commands) {
                 const requested = supplied.get(command.id);
                 const current = currentCommands.get(command.id);
+                const target = requested.enabled
+                    ? fromDashboardPolicy(requested.policy, current.policy)
+                    : requestedModulePolicy;
+                const enabledChanged = requested.enabled === current.inherited;
+                if (!enabledChanged && permissionPoliciesEqual(current.policy, target))
+                    continue;
                 if (requested.enabled) {
                     const saved = await policies.save({
                         guildId: input.guildId,
@@ -870,7 +813,7 @@ export class BotControlService {
         if (!this.#modules.has("helyx.logging")) {
             throw new BotControlNotFoundError("Logging is not installed");
         }
-        if (!(await new InstallationRepository(this.database).isModuleEnabled(input.guildId, "helyx.logging"))) {
+        if (!(await this.#persistence.repositories.installations.isModuleEnabled(input.guildId, "helyx.logging"))) {
             throw new BotControlValidationError("Enable Logging before changing activity events");
         }
         const source = this.#requireModule(input.moduleId);
@@ -878,8 +821,8 @@ export class BotControlService {
         if (!event) {
             throw new BotControlNotFoundError("Logging event is not declared by this module");
         }
-        const saved = await withTransaction(this.database, async (connection) => {
-            const policy = await new ModuleLoggingPolicyRepository(connection).save({
+        const saved = await this.#persistence.withTransaction(async (repositories) => {
+            const policy = await repositories.loggingPolicies.save({
                 guildId: input.guildId,
                 sourceModuleId: input.moduleId,
                 eventId: input.eventId,
@@ -887,7 +830,7 @@ export class BotControlService {
                 expectedVersion: input.expectedVersion === 0 ? null : BigInt(input.expectedVersion),
                 updatedBy: input.actorUserId,
             });
-            await new AuditRepository(connection).append({
+            await repositories.audit.append({
                 guildId: input.guildId,
                 actorUserId: input.actorUserId,
                 action: "module.logging.updated",
@@ -917,7 +860,7 @@ export class BotControlService {
     }
     #dashboardActionControl() {
         return {
-            database: this.database,
+            installations: this.#persistence.repositories.installations,
             services: this.#services,
             requireDashboardModule: (moduleIdValue) => this.#requireDashboardModule(moduleIdValue),
             requireModuleAccessible: (guildId, moduleIdValue) => this.#requireModuleAccessible(guildId, moduleIdValue),
@@ -1103,7 +1046,7 @@ export class BotControlService {
         }
     }
     async #requireEnabledManagedResource(guildId, moduleIdValue) {
-        if (!(await new InstallationRepository(this.database).isModuleEnabled(guildId, moduleIdValue)))
+        if (!(await this.#persistence.repositories.installations.isModuleEnabled(guildId, moduleIdValue)))
             throw new BotControlValidationError("Enable this module before managing its resources");
     }
     async #managedResourceContext(input, module, operation, permissionId = managedResourcePermissionId(module, input.resourceType, operation, undefined, declaredManagedResourcePermission(module, input.resourceType, operation))) {
@@ -1309,6 +1252,7 @@ export async function createBotControlServer(input) {
         return reply.code(503).send({ status: "unavailable" });
     }
     server.get("/health", (_request, reply) => readiness(reply));
+    registerCreatorOnboardingControlRoute(server, input.service);
     server.get("/v1/health", (_request, reply) => readiness(reply));
     server.get("/v1/runtime-configuration", (_request, reply) => reply.header("Cache-Control", "no-store").send({
         hostedModerationEnabled: input.runtimeConfiguration?.hostedModerationEnabled ?? false,
@@ -1716,22 +1660,30 @@ export function mapBotControlError(error) {
         return { status: 404, message: error.message };
     if (error instanceof BotControlForbiddenError)
         return { status: 403, message: error.message };
-    if (error instanceof OptimisticConcurrencyError)
+    if (error instanceof OptimisticConcurrencyError ||
+        (error instanceof Error &&
+            error.name === "DatabaseFailure" &&
+            "kind" in error &&
+            error.kind === "conflict"))
         return {
             status: 409,
             message: "Configuration changed in another session. Reload and try again.",
         };
-    if (error instanceof GuildCommandRevisionConflictError)
+    if (error instanceof GuildCommandRevisionConflictError ||
+        (error instanceof Error &&
+            error.name === "GuildCommandRevisionConflictError"))
         return {
             status: 409,
             message: "Command state changed in another session. Refresh and try again.",
         };
-    if (error instanceof GuildCommandActiveLeaseError)
+    if (error instanceof GuildCommandActiveLeaseError ||
+        (error instanceof Error && error.name === "GuildCommandActiveLeaseError"))
         return {
             status: 409,
             message: "A command build is already running. Wait for it to finish.",
         };
-    if (error instanceof GuildCommandSetupConflictError)
+    if (error instanceof GuildCommandSetupConflictError ||
+        (error instanceof Error && error.name === "GuildCommandSetupConflictError"))
         return {
             status: 409,
             message: "Command setup changed. Reload the page and try again.",
@@ -1739,6 +1691,10 @@ export function mapBotControlError(error) {
     return undefined;
 }
 class BotControlValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BotControlValidationError";
+    }
 }
 class BotControlNotFoundError extends Error {
     constructor(message = "Discord server is not available to Helyx") {

package/dist/core-retention.d.ts

@@ -0,0 +1,26 @@
+import { AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, RateLimitRepository, type DatabasePool } from "@helyx/database";
+import type { GuildCommandRepository as MysqlGuildCommandRepository, InteractionSessionRepository as MysqlInteractionSessionRepository, MysqlPool, RateLimitRepository as MysqlRateLimitRepository } from "@helyx/database-mysql";
+import type { Logger } from "@helyx/sdk";
+export interface CoreRetentionRepositories {
+    sessions: Pick<InteractionSessionRepository, "deleteExpired"> & Pick<MysqlInteractionSessionRepository, "deleteExpired">;
+    rateLimits: Pick<RateLimitRepository, "deleteExpired"> & Pick<MysqlRateLimitRepository, "deleteExpired">;
+    commands: Pick<GuildCommandRepository, "deleteExpired"> & Pick<MysqlGuildCommandRepository, "deleteExpired">;
+    verificationAudit?: Pick<AuditRepository, "deleteModuleEventsOlderThanMonths">;
+    hostedLeaveDeliveries?: Pick<HostedServerSafetyRepository, "deleteTerminalLeaveDeliveriesOlderThanMonths">;
+}
+export interface CoreRetentionCounts {
+    interactionSessions: number;
+    rateLimitWindows: number;
+    verificationAuditEvents: number;
+    commandRecords: number;
+    hostedLeaveDeliveries: number;
+}
+/** One cleanup pass; callers retain ownership of scheduling and error logging. */
+export declare function cleanupExpiredCoreRecords(repositories: CoreRetentionRepositories, logger: Pick<Logger, "info">): Promise<CoreRetentionCounts>;
+/** Hosted cleanup remains on by default, matching the PostgreSQL runtime. */
+export declare function createPostgresCoreRetentionRepositories(database: DatabasePool, options?: {
+    hostedCleanup?: boolean;
+}): CoreRetentionRepositories;
+/** Ordinary self-host cleanup needs only the selected MySQL-compatible DB. */
+export declare function createMysqlCoreRetentionRepositories(database: MysqlPool): Promise<CoreRetentionRepositories>;
+//# sourceMappingURL=core-retention.d.ts.map

package/dist/core-retention.js

@@ -0,0 +1,49 @@
+import { AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, RateLimitRepository, } from "@helyx/database";
+/** One cleanup pass; callers retain ownership of scheduling and error logging. */
+export async function cleanupExpiredCoreRecords(repositories, logger) {
+    const [sessions, rateLimits, verificationAudit, commandRecords, hostedLeaves,] = await Promise.all([
+        repositories.sessions.deleteExpired(),
+        repositories.rateLimits.deleteExpired(),
+        repositories.verificationAudit?.deleteModuleEventsOlderThanMonths("helyx.verification", 12) ?? 0,
+        repositories.commands.deleteExpired(12),
+        repositories.hostedLeaveDeliveries?.deleteTerminalLeaveDeliveriesOlderThanMonths(24) ?? 0,
+    ]);
+    const counts = {
+        interactionSessions: sessions,
+        rateLimitWindows: rateLimits,
+        verificationAuditEvents: verificationAudit,
+        commandRecords: commandRecords.history +
+            commandRecords.idempotencyKeys +
+            commandRecords.creationLedger +
+            commandRecords.requests,
+        hostedLeaveDeliveries: hostedLeaves,
+    };
+    if (Object.values(counts).some((count) => count > 0)) {
+        logger.info({ event: "database.retention_cleaned", ...counts }, "Expired core records removed");
+    }
+    return counts;
+}
+/** Hosted cleanup remains on by default, matching the PostgreSQL runtime. */
+export function createPostgresCoreRetentionRepositories(database, options = {}) {
+    return {
+        sessions: new InteractionSessionRepository(database),
+        rateLimits: new RateLimitRepository(database),
+        commands: new GuildCommandRepository(database),
+        ...(options.hostedCleanup === false
+            ? {}
+            : {
+                verificationAudit: new AuditRepository(database),
+                hostedLeaveDeliveries: new HostedServerSafetyRepository(database),
+            }),
+    };
+}
+/** Ordinary self-host cleanup needs only the selected MySQL-compatible DB. */
+export async function createMysqlCoreRetentionRepositories(database) {
+    const { InteractionSessionRepository: MysqlSessions, RateLimitRepository: MysqlRateLimits, GuildCommandRepository: MysqlCommands, } = await import("@helyx/database-mysql");
+    return {
+        sessions: new MysqlSessions(database),
+        rateLimits: new MysqlRateLimits(database),
+        commands: new MysqlCommands(database),
+    };
+}
+//# sourceMappingURL=core-retention.js.map

package/dist/creator-guild-join-service.d.ts

@@ -0,0 +1,25 @@
+import { type CreatorGuildJoinService, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import { type Client } from "discord.js";
+import type { CreatorInviteRepository } from "@helyx/database";
+/** The only onboarding boundary which can add a member. Never supplies roles or other admission overrides. */
+export declare class DiscordCreatorGuildJoinService implements CreatorGuildJoinService {
+    #private;
+    private readonly client;
+    private readonly services;
+    private readonly modules;
+    private readonly repository;
+    private readonly credentials;
+    constructor(client: Client, services: ServiceAccess, modules: readonly ModuleDefinition[], repository: CreatorInviteRepository, credentials: (input: Parameters<CreatorGuildJoinService["join"]>[0]) => Promise<{
+        accessToken: string;
+        applicationId: string;
+    }>);
+    inspect(input: {
+        guildId: string;
+        memberUserId?: string;
+    }): ReturnType<CreatorGuildJoinService["inspect"]>;
+    join(input: Parameters<CreatorGuildJoinService["join"]>[0]): ReturnType<CreatorGuildJoinService["join"]>;
+    private logJoined;
+    private enabled;
+    private readiness;
+}
+//# sourceMappingURL=creator-guild-join-service.d.ts.map