@helyx/bot 1.6.0 → 1.7.0

package/dist/server-overview-routes.d.ts

@@ -0,0 +1,4 @@
+import { type ServerOverviewControl } from "@helyx/control-protocol";
+import type { FastifyInstance } from "fastify";
+export declare function registerServerOverviewControlRoutes(server: FastifyInstance, control: ServerOverviewControl): void;
+//# sourceMappingURL=server-overview-routes.d.ts.map

package/dist/server-overview-routes.js

@@ -0,0 +1,41 @@
+import { overviewReadInputSchema, overviewRevokeInputSchema, } from "@helyx/control-protocol";
+import { z } from "zod";
+import { BotControlTransportError } from "./control-errors.js";
+export function registerServerOverviewControlRoutes(server, control) {
+    const actor = z.string().regex(/^\d{17,20}$/u);
+    server.post("/v1/guilds/:guildId/overview", async (request) => {
+        const { guildId } = z
+            .object({ guildId: actor })
+            .strict()
+            .parse(request.params);
+        const raw = z
+            .object({ actorUserId: actor })
+            .passthrough()
+            .parse(request.body);
+        const { actorUserId, ...query } = raw;
+        const input = overviewReadInputSchema.parse({ ...query, guildId });
+        if (query.guildId !== undefined && query.guildId !== guildId)
+            throw new BotControlTransportError(400, "Server scope does not match");
+        if (!control.readServerOverview)
+            throw new BotControlTransportError(503, "Overview is unavailable");
+        return control.readServerOverview({ ...input, actorUserId });
+    });
+    server.post("/v1/guilds/:guildId/overview/invites/revoke", async (request) => {
+        const { guildId } = z
+            .object({ guildId: actor })
+            .strict()
+            .parse(request.params);
+        const raw = z
+            .object({ actorUserId: actor })
+            .passthrough()
+            .parse(request.body);
+        const { actorUserId, ...query } = raw;
+        const input = overviewRevokeInputSchema.parse({ ...query, guildId });
+        if (query.guildId !== undefined && query.guildId !== guildId)
+            throw new BotControlTransportError(400, "Server scope does not match");
+        if (!control.revokeServerOverviewInvite)
+            throw new BotControlTransportError(503, "Invite management is unavailable");
+        return control.revokeServerOverviewInvite({ ...input, actorUserId });
+    });
+}
+//# sourceMappingURL=server-overview-routes.js.map

package/dist/shard-contracts.d.ts

@@ -239,6 +239,28 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"guild.state.get">;
     guildId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    guildId: z.ZodString;
+    operation: z.ZodEnum<{
+        summary: "summary";
+        members: "members";
+        member: "member";
+        invites: "invites";
+    }>;
+    memberId: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodOptional<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    roleId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"guild.overview.read">;
+    actorUserId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    guildId: z.ZodString;
+    code: z.ZodString;
+    confirmed: z.ZodLiteral<true>;
+    kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+    actorUserId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     guildId: z.ZodString;
     userIds: z.ZodArray<z.ZodString>;
@@ -742,6 +764,28 @@ export declare const shardControlRequestSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        operation: z.ZodEnum<{
+            summary: "summary";
+            members: "members";
+            member: "member";
+            invites: "invites";
+        }>;
+        memberId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodOptional<z.ZodBoolean>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        search: z.ZodOptional<z.ZodString>;
+        roleId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"guild.overview.read">;
+        actorUserId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        code: z.ZodString;
+        confirmed: z.ZodLiteral<true>;
+        kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+        actorUserId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         guildId: z.ZodString;
         userIds: z.ZodArray<z.ZodString>;
@@ -1765,6 +1809,28 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        operation: z.ZodEnum<{
+            summary: "summary";
+            members: "members";
+            member: "member";
+            invites: "invites";
+        }>;
+        memberId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodOptional<z.ZodBoolean>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        search: z.ZodOptional<z.ZodString>;
+        roleId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"guild.overview.read">;
+        actorUserId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        code: z.ZodString;
+        confirmed: z.ZodLiteral<true>;
+        kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+        actorUserId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         guildId: z.ZodString;
         userIds: z.ZodArray<z.ZodString>;

package/dist/shard-contracts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { overviewReadInputSchema, overviewRevokeInputSchema, } from "@helyx/control-protocol";
 import { discordUserIdentityRequestSchema } from "@helyx/control-protocol/discord-user-identities";
 import { dashboardFieldValidationSchema } from "@helyx/control-protocol/field-validation";
 import { channelAuditModuleIdSchema, channelAuditInputSchema, channelAuditConfigurationSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
@@ -299,6 +300,14 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
     })
         .strict(),
     z.object({ kind: z.literal("guild.state.get"), guildId: snowflake }).strict(),
+    overviewReadInputSchema.safeExtend({
+        kind: z.literal("guild.overview.read"),
+        actorUserId: snowflake,
+    }),
+    overviewRevokeInputSchema.extend({
+        kind: z.literal("guild.overview.invite.revoke"),
+        actorUserId: snowflake,
+    }),
     discordUserIdentityRequestSchema.extend({
         kind: z.literal("guild.user-identities.read"),
     }),
@@ -1107,6 +1116,20 @@ export async function executeShardControlOperation(handler, operation) {
             });
         case "guild.state.get":
             return handler.getGuildState(operation.guildId);
+        case "guild.overview.read": {
+            if (!handler.readServerOverview)
+                throw new Error("Overview is unavailable");
+            const { kind: _kind, ...input } = operation;
+            void _kind;
+            return handler.readServerOverview(input);
+        }
+        case "guild.overview.invite.revoke": {
+            if (!handler.revokeServerOverviewInvite)
+                throw new Error("Invite management is unavailable");
+            const { kind: _kind, ...input } = operation;
+            void _kind;
+            return handler.revokeServerOverviewInvite(input);
+        }
         case "guild.user-identities.read": {
             if (!handler.resolveDiscordUserIdentities)
                 throw new Error("Discord identity lookup is unavailable");

package/dist/shard-coordinator.d.ts

@@ -5,9 +5,9 @@ declare const generationDescriptorSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     applicationId: z.ZodString;
     environment: z.ZodEnum<{
-        production: "production";
         development: "development";
         test: "test";
+        production: "production";
     }>;
     generation: z.ZodString;
     shardCount: z.ZodNumber;

package/dist/shard-router.d.ts

@@ -1,3 +1,4 @@
+import type { OverviewReadInput, OverviewRevokeInput, OverviewResponse } from "@helyx/control-protocol";
 import type { DiscordUserIdentityRequest, DiscordUserIdentityResponse } from "@helyx/control-protocol/discord-user-identities";
 import { type AutoModerationEnhancedResultOutcome, type CreatorOnboardingRequest, type CreatorOnboardingResponse } from "@helyx/sdk";
 import { type BotControlHandler } from "./control-server.js";
@@ -9,6 +10,14 @@ type LocalDispatcher = (shardId: number, request: ShardControlRequest) => Promis
 export declare class ShardControlRouter implements BotControlHandler {
     #private;
     private readonly input;
+    readServerOverview(input: OverviewReadInput & {
+        actorUserId: string;
+    }): Promise<OverviewResponse>;
+    revokeServerOverviewInvite(input: OverviewRevokeInput & {
+        actorUserId: string;
+    }): Promise<{
+        revoked: true;
+    }>;
     creatorOnboarding(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     constructor(input: {
         generation: string;

package/dist/shard-router.js

@@ -11,6 +11,12 @@ const LEASE_VALIDATION_TIMEOUT_MS = 3_000;
 const ECKO_RESULT_TIMEOUT_MS = AUTOMOD_SCANNER_LIMITS.resultAcknowledgementSeconds * 1_000;
 export class ShardControlRouter {
     input;
+    readServerOverview(input) {
+        return this.#route({ kind: "guild.overview.read", ...input });
+    }
+    revokeServerOverviewInvite(input) {
+        return this.#route({ kind: "guild.overview.invite.revoke", ...input });
+    }
     creatorOnboarding(input) {
         return this.#route({
             kind: "creator.onboarding",

package/dist/shard-supervisor.d.ts

@@ -22,7 +22,7 @@ export declare function shardHostedControlCallbacks(router: Pick<ShardControlRou
     deliverHostedServerLeave: (input: {
         operationId: string;
         guildId: string;
-    }) => Promise<"completed" | "requires_review" | "queued" | "not_currently_installed" | "accepted_for_retry">;
+    }) => Promise<"queued" | "completed" | "not_currently_installed" | "accepted_for_retry" | "requires_review">;
     refreshHostedServerOwner: (guildId: string) => Promise<{
         username: string;
         observedAt: string;

package/dist/shard-supervisor.js

@@ -37,6 +37,7 @@ import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
 import { createProcessInfoModule } from "./process-info-module.js";
+import { createRuntimeHelpModule } from "./help-runtime.js";
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createPremiumActivationModule } from "./premium-activation-module.js";
 import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
@@ -250,6 +251,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
         const processInfoModule = createProcessInfoModule("shard supervisor");
+        const helpModule = createRuntimeHelpModule(environment);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -270,6 +272,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             supportModule,
             privacyModule,
             processInfoModule,
+            helpModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -295,6 +298,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     supportModule,
                     privacyModule,
                     processInfoModule,
+                    helpModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/shard-worker.d.ts

@@ -63,7 +63,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_OAUTH_ENABLED: boolean;
     HELYX_CLOUD_ENDPOINT: string;
     HELYX_OWNER_USER_IDS: string[];
-    HELYX_SHARD_MODE: "fixed" | "off" | "auto";
+    HELYX_SHARD_MODE: "off" | "auto" | "fixed";
     HELYX_SHARD_SCOPE: "local" | "coordinated";
     HELYX_CLOUD_AUDIT_RETENTION_DAYS: number;
     HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS: number;

package/dist/shard-worker.js

@@ -45,6 +45,7 @@ import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
 import { createProcessInfoModule } from "./process-info-module.js";
+import { createRuntimeHelpModule } from "./help-runtime.js";
 import { HttpOAuthService } from "./oauth-service.js";
 import { createLocalScheduledTaskRoute, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
@@ -204,6 +205,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const supportModule = createSupportModule(cloudProxy);
         const privacyModule = createPrivacyModule();
         const processInfoModule = createProcessInfoModule(`shard worker ${identity.shardId}`);
+        const helpModule = createRuntimeHelpModule(environment);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -224,6 +226,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             supportModule,
             privacyModule,
             processInfoModule,
+            helpModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -248,6 +251,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     supportModule,
                     privacyModule,
                     processInfoModule,
+                    helpModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/verification-service.d.ts

@@ -21,6 +21,10 @@ export declare class HttpVerificationService implements VerificationService {
     }): Promise<{
         cancelled: number;
     }>;
+    countPendingAttempts(input: {
+        installationId: string;
+        guildId: string;
+    }): Promise<number>;
     listAttempts(input: DashboardAttemptQuery & {
         installationId: string;
         guildId: string;

package/dist/verification-service.js

@@ -82,6 +82,16 @@ export class HttpVerificationService {
         }
         return cancelled;
     }
+    async countPendingAttempts(input) {
+        const result = z
+            .object({ count: z.number().int().nonnegative() })
+            .strict()
+            .parse(await this.#request("/internal/v1/attempts/pending-count", {
+            method: "POST",
+            body: input,
+        }));
+        return result.count;
+    }
     async listAttempts(input) {
         const { installationId, guildId, ...query } = input;
         return dashboardAttemptPageSchema.parse(await this.#request("/internal/v1/attempts/query", {

package/documentation/README.md

@@ -18,6 +18,7 @@ and module guides.
 - [Operate installations and upgrades](runbooks/installation-and-upgrades.md)
 - [Plan backup and recovery](runbooks/backup-and-recovery.md)
 - [Handle privacy and support](guides/privacy-and-support.md)
+- [Use Help and optional online matching](guides/help-command.md)
 - [Build an independent module](modules/building-a-module.md)
 - [Test a module](modules/testing-a-module.md)
 - [Prepare a module package](modules/publishing-a-module.md)

package/documentation/guides/help-command.md

@@ -0,0 +1,62 @@
+# Help Command
+
+Use `/help question:your question` to search Helyx's saved FAQ answers. You can
+choose a module or documentation area to narrow the question, for example
+`/help module:Feedback question:The command is not visible`. Use `/help` for a
+short introduction. Replies are private, and Help is available without enabling
+a customer module or purchasing Premium.
+
+Help returns a stored answer, possible FAQ questions to choose from, or a
+documentation link when it cannot find a suitable match. You can also enter a
+six-digit FAQ ID. Answers retain their source and availability labels; a Planned
+or Testing answer does not mean that feature is available. Staff-authored shared
+and Custom answers are labelled separately. Help does not inspect your server
+settings, execute repairs or generate new answers.
+
+## Self-hosted installations
+
+The bot includes an approved FAQ snapshot for local search. Local Help needs no
+Helyx account, Cloud Connect, Cloudflare key, local AI model or internet service.
+The snapshot belongs to the installed release; update the bot to receive a newer
+one. Central suppression or editing cannot change an offline release already on
+your computer. When an enrolled online request fails, self-hosted Help labels
+its local fallback clearly.
+
+Online matching is optional. When available, open your Helyx account's
+self-hosting page and create a Help code. On the bot's host, from the generated
+project folder, run:
+
+```sh
+npx helyx help connect
+npx helyx help status
+npx helyx help disconnect
+```
+
+Read the connection notice and paste the single-use code at the prompt. Codes
+expire after ten minutes; do not put one in a command argument or screenshot.
+The project needs its existing data-encryption key and a writable `.helyx`
+directory. Help saves a separate encrypted credential there. Docker starters
+retain it in their private named volume. Preserve the encryption key when
+restarting; changing it makes the saved credential unreadable.
+
+Status reads only the local file. Disconnect revokes online access when the
+service is reachable and removes the local credential. If remote revocation
+fails, revoke the installation from the account dashboard. A replacement code
+rotates the credential when consumed; account revocation takes effect centrally.
+Neither action disables local Help or requires Cloud Connect.
+
+## Questions and privacy
+
+Online Help sends the question and selected area to Helyx; its embedding
+provider receives the public question text needed for meaning comparison.
+Do not include credentials, private messages or personal details. Self-host
+online requests use a Help installation identity and do not send Discord user
+or server IDs. Hosted requests use trusted member/server identities for limits.
+The service does not store a persistent history of member questions or completed
+question embeddings. Short-lived request counters and Help connection metadata
+are handled through Helyx's privacy system. Providers have their own processing
+terms. See [Privacy and support](privacy-and-support.md).
+
+Shared request and spending limits may make semantic matching temporarily
+unavailable. Hosted Help fails safely to documentation when it cannot verify
+the current collection; self-hosted Help can still use its labelled local copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -51,15 +51,15 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=1.6.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.9.0 <0.10.0",
-    "@helyx/core": ">=0.2.0 <0.3.0",
-    "@helyx/database": ">=2.5.0 <3.0.0",
+    "@helyx/config": ">=1.7.0 <2.0.0",
+    "@helyx/control-protocol": ">=0.9.1 <0.10.0",
+    "@helyx/core": ">=0.2.3 <0.3.0",
+    "@helyx/database": ">=2.5.1 <3.0.0",
     "@helyx/database-contracts": ">=0.3.0 <0.4.0",
     "@helyx/framework": ">=0.2.0 <0.3.0",
     "@helyx/module-manifest": ">=0.14.0 <0.15.0",
     "@helyx/platform": ">=1.3.0 <2.0.0",
-    "@helyx/sdk": ">=0.17.0 <0.18.0",
+    "@helyx/sdk": ">=0.17.1 <0.18.0",
     "@helyx/status-client": ">=0.3.0 <0.4.0",
     "@helyx/verification-contracts": ">=0.5.0 <0.6.0",
     "discord.js": "14.27.0",