@helyx/bot 0.4.25 → 0.4.27

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.27
+
+### Patch Changes
+
+- Allow a strictly newer coordinated deployment to atomically replace an incompatible module-catalogue generation while preserving application and environment namespace isolation.
+
+## 0.4.26
+
+### Patch Changes
+
+- Require the database runner that installs packaged module migration seeds before runtime readiness.
+
 ## 0.4.25
 
 ### Patch Changes

package/README.md

@@ -23,11 +23,9 @@ resume secure weighted-selection checkpoints without exposing the selection
 key to a module. Keep it stable across deployments; do not rotate it while a
 giveaway is drawing.
 
-Trivia uses the operator-only `HELYX_TRIVIA_API_KEY`. Commercial deployments
-need a paid The Trivia API subscription. Guess reuses saved Multiple Choice
-questions and checks answers locally, so it does not require the provider's
-Complete subscription. Local development may exercise Multiple Choice without
-a key; production never enables the provider adapter without one.
+Trivia uses questions already imported into PostgreSQL. Multiple Choice and
+Guess both run entirely from the saved question catalogue, and the bot runtime
+does not call an external trivia provider.
 
 The always-available guild-only `/bug` command can be used by any guild member.
 Hosted deployments submit through the dedicated `HELYX_SUPPORT_SERVICE_SECRET`;

package/dist/cloud-connector.js

@@ -719,6 +719,7 @@ function connectorCapabilities() {
     return [
         "installation.health.read.v1",
         "guild.state.read.v1",
+        "guild.module.public.read.v1",
         "guild.module.status.write.v1",
         "guild.module.configuration.write.v1",
         "guild.module.permissions.write.v1",

package/dist/cloud-control-dispatcher.js

@@ -25,6 +25,19 @@ export class CloudControlDispatcher {
                 result = await this.control.getGuildState(input.guildId);
                 break;
             }
+            case "guild.module.public.read.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                if (request.actor.kind !== "public")
+                    throw new CloudControlDeniedError("public_actor_required");
+                result = await this.control.readPublicModuleProjection({
+                    guildId: input.guildId,
+                    moduleId: input.moduleId,
+                    ...(input.memberUserId ? { subjectUserId: input.memberUserId } : {}),
+                    ...(input.cursor ? { cursor: input.cursor } : {}),
+                    limit: input.limit,
+                });
+                break;
+            }
             case "guild.module.status.write.v1": {
                 const input = parseOperationInput(request.operation, request.input);
                 result = await this.control.setModuleStatus({

package/dist/control-server.d.ts

@@ -1,5 +1,5 @@
 import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
-import { type DashboardActionResult, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type ServiceAccess } from "@helyx/sdk";
+import { type DashboardActionResult, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, 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";
 import { type FastifyInstance } from "fastify";
@@ -43,6 +43,7 @@ interface DashboardModuleDefinition {
     commands: DashboardCommandDefinition[];
     logEvents: DashboardLogEventDefinition[];
     actions: DashboardActionDefinition[];
+    achievementTriggers: NonNullable<ModuleDefinition["manifest"]["contributions"]["achievementTriggers"]>;
     resources: readonly DashboardResourceDefinition[];
 }
 interface DashboardLoggingPolicy {
@@ -72,6 +73,14 @@ export interface BotControlGuildResources {
         colour: string;
     }>;
 }
+export interface BotPublicModuleProjection {
+    server: {
+        id: string;
+        name: string;
+        memberCount: number;
+    };
+    projection: PublicAchievementProjectionPage;
+}
 export type BotGuildPresenceState = "installed" | "not_installed" | "unknown" | "unavailable";
 export interface BotGuildPresenceObservation {
     guildId: string;
@@ -81,6 +90,11 @@ export interface BotGuildPresenceObservation {
 export interface BotControlGuildResourceDirectory {
     listGuildPresence(guildIds: readonly string[]): Promise<BotGuildPresenceObservation[]>;
     getGuildResources(guildId: string): Promise<BotControlGuildResources>;
+    getGuildPublicSummary(guildId: string): Promise<{
+        id: string;
+        name: string;
+        memberCount: number;
+    }>;
     sendToChannel(channelId: string, response: MessageResponse): Promise<{
         messageId: string;
     }>;
@@ -95,6 +109,11 @@ export declare class DiscordGuildResourceDirectory implements BotControlGuildRes
     constructor(client: Client);
     listGuildPresence(guildIds: readonly string[]): Promise<BotGuildPresenceObservation[]>;
     getGuildResources(guildId: string): Promise<BotControlGuildResources>;
+    getGuildPublicSummary(guildId: string): Promise<{
+        id: string;
+        name: string;
+        memberCount: number;
+    }>;
     sendToChannel(channelId: string, response: MessageResponse): Promise<{
         messageId: string;
     }>;
@@ -134,6 +153,13 @@ export interface BotControlHandler {
         correlationId: string;
     }): Promise<BotGuildPresenceObservation[]>;
     getGuildState(guildId: string): Promise<BotControlState>;
+    readPublicModuleProjection(input: {
+        guildId: string;
+        moduleId: string;
+        subjectUserId?: string;
+        cursor?: string;
+        limit: number;
+    }): Promise<BotPublicModuleProjection>;
     canAccessManagedResource(input: {
         guildId: string;
         moduleId: string;
@@ -328,6 +354,13 @@ export declare class BotControlService implements BotControlHandler {
         cursor?: string;
     }): Promise<PrivacyErasePage>;
     getGuildState(guildId: string): Promise<BotControlState>;
+    readPublicModuleProjection(input: {
+        guildId: string;
+        moduleId: string;
+        subjectUserId?: string;
+        cursor?: string;
+        limit: number;
+    }): Promise<BotPublicModuleProjection>;
     canAccessManagedResource(input: {
         guildId: string;
         moduleId: string;

package/dist/control-server.js

@@ -155,6 +155,17 @@ export class DiscordGuildResourceDirectory {
             throw error;
         }
     }
+    async getGuildPublicSummary(guildId) {
+        try {
+            const guild = await this.client.guilds.fetch(guildId);
+            return { id: guild.id, name: guild.name, memberCount: guild.memberCount };
+        }
+        catch (error) {
+            if (isUnknownGuildError(error))
+                throw new BotControlNotFoundError();
+            throw error;
+        }
+    }
     sendToChannel(channelId, response) {
         return sendDiscordMessageToChannel(this.client, channelId, response);
     }
@@ -414,6 +425,39 @@ export class BotControlService {
             logging,
         };
     }
+    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)))
+            throw new BotControlValidationError("This module is not enabled");
+        if (input.subjectUserId) {
+            if (!this.#services.has(HELYX_SERVICE_NAMES.discordResources))
+                throw new BotControlTransportError(503, "Discord membership confirmation is unavailable");
+            const [member] = await this.#services
+                .get(HELYX_SERVICE_NAMES.discordResources)
+                .resolveMemberSnapshots({
+                guildId: input.guildId,
+                userIds: [input.subjectUserId],
+            });
+            if (!member?.exists)
+                throw new BotControlForbiddenError("Server membership is required");
+        }
+        const [server, projection] = await Promise.all([
+            this.resources.getGuildPublicSummary(input.guildId),
+            module.publicProjection.read({
+                guildId: input.guildId,
+                ...(input.subjectUserId
+                    ? { subjectUserId: input.subjectUserId }
+                    : {}),
+                services: this.#services,
+            }, {
+                ...(input.cursor ? { cursor: input.cursor } : {}),
+                limit: Math.min(10, Math.max(1, input.limit)),
+            }),
+        ]);
+        return { server, projection };
+    }
     async canAccessManagedResource(input) {
         try {
             const { module } = await this.#prepareManagedResource(input);
@@ -1095,6 +1139,26 @@ export async function createBotControlServer(input) {
         const { guildId } = z.object({ guildId: snowflake }).parse(request.params);
         return input.service.getGuildState(guildId);
     });
+    server.get("/v1/guilds/:guildId/modules/:moduleId/public-projection", async (request) => {
+        const params = z
+            .object({ guildId: snowflake, moduleId })
+            .strict()
+            .parse(request.params);
+        const query = z
+            .object({
+            subjectUserId: snowflake.optional(),
+            cursor: z.string().min(1).max(2_048).optional(),
+            limit: z.coerce.number().int().min(1).max(10).default(10),
+        })
+            .strict()
+            .parse(request.query);
+        return input.service.readPublicModuleProjection({
+            ...params,
+            ...(query.subjectUserId ? { subjectUserId: query.subjectUserId } : {}),
+            ...(query.cursor ? { cursor: query.cursor } : {}),
+            limit: query.limit,
+        });
+    });
     server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/access", async (request) => {
         const params = z
             .object({
@@ -1602,6 +1666,7 @@ function mapDashboardModule(module) {
         commands: dashboardCommands(module),
         logEvents: (module.logging?.events ?? []).map((event) => ({ ...event })),
         actions: (dashboard.actions ?? []).map((action) => ({ ...action })),
+        achievementTriggers: (module.manifest.contributions?.achievementTriggers ?? []).map((trigger) => structuredClone(trigger)),
         resources: (dashboard.resources ?? []).map((resource) => structuredClone(resource)),
     };
 }

package/dist/index.js

@@ -2,7 +2,7 @@ import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices, gamingStatisticsRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
@@ -292,11 +292,19 @@ async function startUnshardedBot(processEnvironment) {
             ]),
         }, bootstrapLogger, serviceAccess);
         const moduleEvents = installModuleEvents(client, publicModules, bootstrapLogger, serviceAccess);
-        const controlService = new BotControlService(database, [...publicModules, gamingStatisticsRecordOwner], guildResources, serviceAccess, privacyDatabase
+        const controlService = new BotControlService(database, [
+            ...publicModules,
+            gamingStatisticsRecordOwner,
+            achievementContributionRecordOwner,
+        ], guildResources, serviceAccess, privacyDatabase
             ? new PostgresPrivacyProviderExecutor({
                 readPool: database,
                 executorPool: privacyDatabase,
-                modules: [...featureModules, gamingStatisticsRecordOwner],
+                modules: [
+                    ...featureModules,
+                    gamingStatisticsRecordOwner,
+                    achievementContributionRecordOwner,
+                ],
             })
             : undefined, environment.DISCORD_INTERNAL_GUILD_ID &&
             environment.HELYX_SUPPORT_STAFF_CHANNEL_ID

package/dist/shard-contracts.d.ts

@@ -169,6 +169,13 @@ export type ShardHealthSnapshot = z.infer<typeof shardHealthSnapshotSchema>;
 export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"guild.state.get">;
     guildId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"guild.module.public.read">;
+    guildId: z.ZodString;
+    moduleId: z.ZodString;
+    subjectUserId: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"guild.presence.list">;
     guildIds: z.ZodArray<z.ZodString>;
@@ -478,6 +485,13 @@ export declare const shardControlRequestSchema: z.ZodObject<{
     operation: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"guild.module.public.read">;
+        guildId: z.ZodString;
+        moduleId: z.ZodString;
+        subjectUserId: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodNumber;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.presence.list">;
         guildIds: z.ZodArray<z.ZodString>;
@@ -1292,6 +1306,13 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     operation: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"guild.module.public.read">;
+        guildId: z.ZodString;
+        moduleId: z.ZodString;
+        subjectUserId: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodNumber;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.presence.list">;
         guildIds: z.ZodArray<z.ZodString>;

package/dist/shard-contracts.js

@@ -222,6 +222,16 @@ export const shardHealthSnapshotSchema = z
 });
 export const shardControlOperationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("guild.state.get"), guildId: snowflake }).strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.public.read"),
+        guildId: snowflake,
+        moduleId,
+        subjectUserId: snowflake.optional(),
+        cursor: resourceCursor.optional(),
+        limit: z.number().int().min(1).max(10),
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("guild.presence.list"),
@@ -901,6 +911,16 @@ export async function executeShardControlOperation(handler, operation) {
             });
         case "guild.state.get":
             return handler.getGuildState(operation.guildId);
+        case "guild.module.public.read":
+            return handler.readPublicModuleProjection({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                ...(operation.subjectUserId
+                    ? { subjectUserId: operation.subjectUserId }
+                    : {}),
+                ...(operation.cursor ? { cursor: operation.cursor } : {}),
+                limit: operation.limit,
+            });
         case "guild.module.resource.access":
             return handler.canAccessManagedResource({
                 guildId: operation.guildId,

package/dist/shard-coordinator.js

@@ -137,8 +137,22 @@ export class RedisShardCoordinator {
         const parsed = activeGenerationSchema.safeParse(parseJson(current ?? ""));
         if (parsed.success) {
             if (JSON.stringify(withoutDeploymentOrder(parsed.data)) !==
-                JSON.stringify(accepted))
-                throw new Error("Shard coordination namespace is owned by an incompatible generation");
+                JSON.stringify(accepted)) {
+                if (parsed.data.applicationId !== accepted.applicationId ||
+                    parsed.data.environment !== accepted.environment ||
+                    deploymentOrder <= parsed.data.deploymentOrder ||
+                    !current)
+                    throw new Error("Shard coordination namespace is owned by an incompatible generation");
+                const replaced = await compareAndReplace(this.#command, this.#generationKey(), current, serialized, GENERATION_TTL_MS);
+                if (replaced)
+                    return deploymentOrder;
+                const winner = activeGenerationSchema.safeParse(parseJson((await this.#command.get(this.#generationKey())) ?? ""));
+                if (winner.success &&
+                    JSON.stringify(withoutDeploymentOrder(winner.data)) ===
+                        JSON.stringify(accepted))
+                    return winner.data.deploymentOrder;
+                throw new Error("Shard coordination generation changed while it was being validated");
+            }
             if (!current ||
                 !(await compareAndExpire(this.#command, this.#generationKey(), current, GENERATION_TTL_MS)))
                 throw new Error("Shard coordination generation changed while it was being validated");

package/dist/shard-router.d.ts

@@ -16,6 +16,7 @@ export declare class ShardControlRouter implements BotControlHandler {
         notificationGuildId?: string;
     });
     getGuildState(guildId: string): ReturnType<BotControlHandler["getGuildState"]>;
+    readPublicModuleProjection(input: Parameters<BotControlHandler["readPublicModuleProjection"]>[0]): ReturnType<BotControlHandler["readPublicModuleProjection"]>;
     canAccessManagedResource(input: Parameters<BotControlHandler["canAccessManagedResource"]>[0]): ReturnType<BotControlHandler["canAccessManagedResource"]>;
     listGuildPresence(input: Parameters<BotControlHandler["listGuildPresence"]>[0]): ReturnType<BotControlHandler["listGuildPresence"]>;
     setModuleStatus(input: Parameters<BotControlHandler["setModuleStatus"]>[0]): ReturnType<BotControlHandler["setModuleStatus"]>;

package/dist/shard-router.js

@@ -10,6 +10,9 @@ export class ShardControlRouter {
     getGuildState(guildId) {
         return this.#route({ kind: "guild.state.get", guildId });
     }
+    readPublicModuleProjection(input) {
+        return this.#route({ kind: "guild.module.public.read", ...input });
+    }
     canAccessManagedResource(input) {
         return this.#route({
             kind: "guild.module.resource.access",

package/dist/shard-supervisor.js

@@ -1,6 +1,6 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
-import { createPlatformServices, gamingStatisticsRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -169,6 +169,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 observedAt: new Date().toISOString(),
             }))),
             getGuildResources: () => Promise.reject(new Error("Guild resources are worker-owned")),
+            getGuildPublicSummary: () => Promise.reject(new Error("Guild resources are worker-owned")),
             sendToChannel: () => Promise.reject(new Error("Guild resources are worker-owned")),
             deleteChannelMessage: () => Promise.reject(new Error("Guild resources are worker-owned")),
             editChannelMessage: () => Promise.reject(new Error("Guild resources are worker-owned")),
@@ -230,11 +231,19 @@ export async function startShardSupervisor(environment, processEnvironment, work
             const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
             if (numericWriteBehind)
                 services.set(HELYX_SERVICE_NAMES.numericWriteBehind, numericWriteBehind);
-            privacyService = new BotControlService(database, [...publicModules, gamingStatisticsRecordOwner], unavailableResources, new ServiceRegistry(services), privacyDatabase
+            privacyService = new BotControlService(database, [
+                ...publicModules,
+                gamingStatisticsRecordOwner,
+                achievementContributionRecordOwner,
+            ], unavailableResources, new ServiceRegistry(services), privacyDatabase
                 ? new PostgresPrivacyProviderExecutor({
                     readPool: database,
                     executorPool: privacyDatabase,
-                    modules: [...featureModules, gamingStatisticsRecordOwner],
+                    modules: [
+                        ...featureModules,
+                        gamingStatisticsRecordOwner,
+                        achievementContributionRecordOwner,
+                    ],
                 })
                 : undefined);
             cloudConnector?.setControlHandler(new ShardControlRouter({

package/dist/shard-worker.d.ts

@@ -41,7 +41,6 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS: number;
     HELYX_PRIVACY_ENABLED: boolean;
     HELYX_MESSAGE_CONTENT_ENABLED: boolean;
-    HELYX_TRIVIA_API_KEY: string | undefined;
     HELYX_CLOUD_CONNECT_ENABLED: boolean;
     HELYX_CLOUD_ENROLMENT_TOKEN: string | undefined;
     HELYX_CLOUD_ENROLMENT_FILE: string;

package/dist/shard-worker.js

@@ -10,7 +10,6 @@ import pino from "pino";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, DiscordGuildResourceDirectory, mapBotControlError, } from "./control-server.js";
 import { HttpVerificationService } from "./verification-service.js";
-import { HttpTriviaQuestionProvider } from "./trivia-provider.js";
 import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
@@ -183,14 +182,6 @@ export async function startShardWorker(processEnvironment = process.env, identit
             }));
             platformServices.set(HELYX_SERVICE_NAMES.verificationMembers, new DiscordVerificationMemberService(client));
         }
-        if (environment.HELYX_TRIVIA_API_KEY ||
-            environment.NODE_ENV !== "production") {
-            platformServices.set(HELYX_SERVICE_NAMES.triviaQuestions, new HttpTriviaQuestionProvider({
-                ...(environment.HELYX_TRIVIA_API_KEY
-                    ? { apiKey: environment.HELYX_TRIVIA_API_KEY }
-                    : {}),
-            }));
-        }
         numericWriteBehind =
             identity.scope === "coordinated"
                 ? new WorkerNumericWriteBehindProxy(identity)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -51,7 +51,7 @@
     "@helyx/config": ">=0.5.0 <0.6.0",
     "@helyx/control-protocol": ">=0.3.0 <0.4.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=0.7.0 <0.8.0",
+    "@helyx/database": ">=0.7.10 <0.8.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
     "@helyx/module-manifest": ">=0.6.0 <0.7.0",
     "@helyx/platform": ">=0.4.0 <0.5.0",

package/dist/trivia-provider.d.ts

@@ -1,15 +0,0 @@
-import { type TriviaProviderFailureCode, type TriviaQuestion, type TriviaQuestionProvider } from "@helyx/sdk";
-export interface HttpTriviaQuestionProviderOptions {
-    apiKey?: string;
-    fetchImplementation?: typeof fetch;
-}
-export declare class HttpTriviaQuestionProvider implements TriviaQuestionProvider {
-    #private;
-    constructor(options: HttpTriviaQuestionProviderOptions);
-    getQuestions(input: Parameters<TriviaQuestionProvider["getQuestions"]>[0]): Promise<readonly TriviaQuestion[]>;
-    health(): Promise<{
-        status: "healthy" | "degraded" | "unavailable";
-        safeCode?: TriviaProviderFailureCode;
-    }>;
-}
-//# sourceMappingURL=trivia-provider.d.ts.map

package/dist/trivia-provider.js

@@ -1,123 +0,0 @@
-import { TRIVIA_CATEGORIES, TriviaProviderError, } from "@helyx/sdk";
-import { z } from "zod";
-const BASE_URL = "https://the-trivia-api.com/v2";
-const MAX_RESPONSE_BYTES = 256 * 1_024;
-const REQUEST_TIMEOUT_MS = 8_000;
-const questionSchema = z.object({
-    category: z.enum(TRIVIA_CATEGORIES),
-    id: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/u),
-    tags: z.array(z.string().trim().min(1).max(100)).max(100),
-    difficulty: z.enum(["easy", "medium", "hard"]),
-    regions: z.array(z.string().trim().min(1).max(20)).max(100),
-    isNiche: z.boolean(),
-    question: z.object({ text: z.string().trim().min(1).max(2_000) }),
-    correctAnswer: z.string().trim().min(1).max(500),
-    incorrectAnswers: z.array(z.string().trim().min(1).max(500)).max(10),
-    type: z.literal("text_choice"),
-});
-export class HttpTriviaQuestionProvider {
-    #apiKey;
-    #fetch;
-    #lastFailure;
-    constructor(options) {
-        this.#apiKey = options.apiKey;
-        this.#fetch = options.fetchImplementation ?? fetch;
-    }
-    async getQuestions(input) {
-        if (!Number.isSafeInteger(input.limit) ||
-            input.limit < 1 ||
-            input.limit > 50)
-            this.#fail("invalid_response");
-        const query = new URLSearchParams({
-            limit: input.isNiche === undefined ? String(input.limit) : "50",
-            types: input.type,
-            contentFilter: input.familyContentOnly ? "family" : "all",
-        });
-        if (input.category)
-            query.set("categories", input.category);
-        if (input.difficulty)
-            query.set("difficulties", input.difficulty);
-        const raw = await this.#request(`/questions?${query.toString()}`, "GET");
-        const parsed = z.array(questionSchema).max(50).safeParse(raw);
-        if (!parsed.success) {
-            this.#fail("invalid_response");
-        }
-        const matching = parsed.data.filter((question) => question.type === input.type &&
-            (input.isNiche === undefined || question.isNiche === input.isNiche));
-        this.#lastFailure = undefined;
-        return matching.slice(0, input.limit);
-    }
-    health() {
-        return Promise.resolve(this.#lastFailure
-            ? { status: "degraded", safeCode: this.#lastFailure }
-            : { status: "healthy" });
-    }
-    async #request(path, method) {
-        let response;
-        try {
-            response = await this.#fetch(`${BASE_URL}${path}`, {
-                method,
-                headers: {
-                    accept: "application/json",
-                    ...(this.#apiKey ? { "x-api-key": this.#apiKey } : {}),
-                },
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-        }
-        catch (error) {
-            this.#fail(error instanceof DOMException && error.name === "TimeoutError"
-                ? "timeout"
-                : "unavailable");
-        }
-        if (!response.ok) {
-            if (response.status === 429)
-                this.#fail("rate_limited");
-            if (response.status === 401)
-                this.#fail("authentication");
-            if (response.status === 403)
-                this.#fail("subscription");
-            this.#fail(response.status >= 500 ? "unavailable" : "invalid_response");
-        }
-        try {
-            return JSON.parse(await readBoundedResponse(response));
-        }
-        catch (error) {
-            if (error instanceof TriviaProviderError)
-                throw error;
-            this.#fail("invalid_response");
-        }
-    }
-    #fail(code) {
-        this.#lastFailure = code;
-        throw new TriviaProviderError(code);
-    }
-}
-async function readBoundedResponse(response) {
-    const declared = Number(response.headers.get("content-length"));
-    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES)
-        throw new TriviaProviderError("invalid_response");
-    if (!response.body)
-        return "";
-    const reader = response.body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        for (;;) {
-            const chunk = await reader.read();
-            if (chunk.done)
-                break;
-            const boundedValue = chunk.value;
-            if (!(boundedValue instanceof Uint8Array))
-                throw new TriviaProviderError("invalid_response");
-            total += boundedValue.byteLength;
-            if (total > MAX_RESPONSE_BYTES)
-                throw new TriviaProviderError("invalid_response");
-            chunks.push(boundedValue);
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    return Buffer.concat(chunks, total).toString("utf8");
-}
-//# sourceMappingURL=trivia-provider.js.map