@azurioh/discord-kernel 0.1.0 → 1.0.0

package/dist/settings/registry.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSettingsRegistry = createSettingsRegistry;
+const field_1 = require("../settings/fields/field");
+const settings_declaration_error_1 = require("../settings/settings-declaration-error");
+const kernel_settings_1 = require("../settings/system/kernel-settings");
+/**
+ * Collect the modules' settings declarations at boot, after the kernel's own
+ * declaration ({@link kernelSettings}), which is always included.
+ *
+ * @param input.declarations - every module's declaration.
+ * @param input.translations - must already contain the modules' catalogs and
+ * `SETTINGS_CATALOG`, which holds the kernel declaration's texts.
+ * @param input.modules - the registered modules (a `BotModule` fits), whose
+ * names and `defaultEnabled` build the kernel's module toggles. None by default.
+ * @returns the registry of declarations, by id.
+ * @throws SettingsDeclarationError when two declarations share an id (FR-005)
+ * or a declaration references a catalog key without an English source (FR-028),
+ * or two modules share a name.
+ */
+function createSettingsRegistry(input) {
+    const kernel = (0, kernel_settings_1.kernelSettings)(input.modules ?? []);
+    const byId = new Map();
+    for (const declaration of [kernel, ...input.declarations]) {
+        if (byId.has(declaration.id)) {
+            throw new settings_declaration_error_1.SettingsDeclarationError(declaration.id, "is declared more than once");
+        }
+        checkKeys({ declaration, translations: input.translations });
+        byId.set(declaration.id, declaration);
+    }
+    return {
+        declarations: [...byId.values()],
+        kernel,
+        get: (id) => byId.get(id),
+    };
+}
+function checkKeys(params) {
+    const { declaration, translations } = params;
+    for (const key of catalogKeys(declaration)) {
+        if (!translations.has(key)) {
+            throw new settings_declaration_error_1.SettingsDeclarationError(declaration.id, `catalog key "${key}" has no English source`);
+        }
+    }
+}
+/**
+ * Every catalog key a declaration references: labels, groups, fields, choices
+ * and toggle key labels.
+ */
+function* catalogKeys(declaration) {
+    yield* defined([declaration.labels.title, declaration.labels.description]);
+    for (const group of Object.values(declaration.groups ?? {})) {
+        yield* defined([group.label, group.description]);
+    }
+    for (const declared of Object.values(declaration.fields)) {
+        yield* fieldKeys(declared);
+    }
+}
+function* fieldKeys(declared) {
+    yield* defined([declared.label, declared.description, declared.placeholder, declared.unit]);
+    yield* specKeys(declared.spec);
+}
+function* specKeys(spec) {
+    switch (spec.kind) {
+        case "enum":
+            yield* spec.choices.map(choiceLabel);
+            return;
+        case "integer":
+        case "text":
+            yield* suggestionKeys(spec.suggest);
+            return;
+        case "list":
+            yield* fieldKeys(spec.item);
+            return;
+        case "toggles":
+            yield* defined(Object.values(spec.keyLabels ?? {}));
+            return;
+        case "channel":
+        case "role":
+        case "user":
+        case "color":
+        case "duration":
+        case "number":
+        case "boolean":
+        case "secret":
+            return;
+        default:
+            (0, field_1.unhandledFieldKind)(spec);
+    }
+}
+function suggestionKeys(suggest) {
+    if (suggest === undefined || !("choices" in suggest)) {
+        return [];
+    }
+    return suggest.choices.map(choiceLabel);
+}
+function choiceLabel(choice) {
+    return choice.label;
+}
+function defined(keys) {
+    return keys.filter((key) => key !== undefined);
+}
+//# sourceMappingURL=registry.js.map

package/dist/settings/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/settings/registry.ts"],"names":[],"mappings":"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"}

package/dist/settings/settings-declaration-error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A module's settings declaration breaks a rule that can be checked without a
+ * guild: a default failing its own field, a secret with a default, too many
+ * choices, a duplicate id, a catalog key with no English source… Raised by
+ * `defineSettings` and `createSettingsRegistry` at boot, so a broken
+ * declaration never reaches a server.
+ */
+export declare class SettingsDeclarationError extends Error {
+    readonly declarationId: string;
+    readonly reason: string;
+    constructor(declarationId: string, reason: string);
+}
+//# sourceMappingURL=settings-declaration-error.d.ts.map

package/dist/settings/settings-declaration-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-declaration-error.d.ts","sourceRoot":"","sources":["../../src/settings/settings-declaration-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAEjD,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;CAKxB"}

package/dist/settings/settings-declaration-error.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsDeclarationError = void 0;
+/**
+ * A module's settings declaration breaks a rule that can be checked without a
+ * guild: a default failing its own field, a secret with a default, too many
+ * choices, a duplicate id, a catalog key with no English source… Raised by
+ * `defineSettings` and `createSettingsRegistry` at boot, so a broken
+ * declaration never reaches a server.
+ */
+class SettingsDeclarationError extends Error {
+    declarationId;
+    reason;
+    constructor(declarationId, reason) {
+        super(`Settings declaration "${declarationId}": ${reason}`);
+        this.declarationId = declarationId;
+        this.reason = reason;
+        this.name = "SettingsDeclarationError";
+    }
+}
+exports.SettingsDeclarationError = SettingsDeclarationError;
+//# sourceMappingURL=settings-declaration-error.js.map

package/dist/settings/settings-declaration-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-declaration-error.js","sourceRoot":"","sources":["../../src/settings/settings-declaration-error.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IAExC;IACA;IAFV,YACU,aAAqB,EACrB,MAAc;QAEvB,KAAK,CAAC,yBAAyB,aAAa,MAAM,MAAM,EAAE,CAAC,CAAC;QAHnD,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACxC,CAAC;CACD;AARD,4DAQC"}

package/dist/settings/settings-service.d.ts

@@ -0,0 +1,148 @@
+import type { Clock } from "../clock";
+import type { Translator } from "../i18n/translator";
+import type { Logger } from "../logger";
+import type { Choice } from "../settings/choice";
+import type { SettingsDeclaration } from "../settings/define-settings";
+import { type SettingsSchema } from "../settings/describe";
+import type { GuildDirectory } from "../settings/ports/guild-directory";
+import type { SettingsChangedNotifier } from "../settings/ports/settings-changed-notifier";
+import type { SettingsStore, StoredSettings } from "../settings/ports/settings-store";
+import type { SettingsRegistry } from "../settings/registry";
+import { type SettingsIssue } from "../settings/settings-validation-error";
+import { type SettingsStatus } from "../settings/status";
+import type { SettingsValues, SurfaceValues } from "../settings/types";
+/** Who asks, for which guild and in which language. */
+export interface RequestContext {
+    readonly guildId: string;
+    readonly userId: string;
+    readonly locale: string;
+}
+/**
+ * Outcome of {@link SettingsService.validate}: the submitted fields in their
+ * stored form (an unset field maps to `undefined`), or every issue found.
+ */
+export type ValidationResult<D extends SettingsDeclaration> = {
+    readonly ok: true;
+    readonly values: Partial<SettingsValues<D>>;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SettingsIssue[];
+};
+/** Reads and writes the settings modules declare, per guild. */
+export interface SettingsService {
+    /**
+     * Module logic read: every declared field, secrets included. A field with
+     * no valid stored value reads as its default. Cached per guild and module
+     * until a change of them (this service's writes, or a notifier event) or
+     * `SETTINGS_CACHE_TTL_MS`, whichever comes first.
+     *
+     * Writes only to migrate (FR-018): values stored under an older declaration
+     * version go through the declaration's `migrate`, are validated, and are
+     * written back once under the declared version, like any other write. A
+     * migration that throws or yields invalid values writes nothing and is
+     * logged; the guild then reads defaults for the fields it cannot read.
+     * Values stored under a newer version are never written (FR-019).
+     */
+    get<D extends SettingsDeclaration>(declaration: D, guildId: string): Promise<SettingsValues<D>>;
+    /**
+     * Surface read: like {@link get}, with each secret replaced by whether it
+     * is set. A secret's value never leaves the service through a surface.
+     */
+    getForSurface<D extends SettingsDeclaration>(declaration: D, guildId: string): Promise<SurfaceValues<D>>;
+    /**
+     * Configuration status (FR-040): the required fields without default the
+     * guild left unset, read through the same cache as {@link get}, so a write
+     * shows at once. A stored value that fails validation counts as unset.
+     */
+    status(declaration: SettingsDeclaration, guildId: string): Promise<SettingsStatus>;
+    /**
+     * Validate a submission without writing: the same checks as {@link set},
+     * shared by every surface.
+     *
+     * @throws ValidationError when `ctx` is for another guild than `guildId`.
+     */
+    validate<D extends SettingsDeclaration>(declaration: D, guildId: string, patch: unknown, ctx: RequestContext): Promise<ValidationResult<D>>;
+    /**
+     * Validate a submission, then merge it onto the stored values in one write:
+     * nothing is stored unless every field is valid. A field submitted as
+     * `null` is unset; stored fields the declaration no longer declares are
+     * dropped. Values stored under an older declaration version are migrated
+     * first, so the patch merges onto the values the guild reads. Emits a
+     * settings change once written.
+     *
+     * @returns the written record.
+     * @throws SettingsValidationError listing every invalid field.
+     * @throws ConflictError when `ctx.expectedRevision` is not the stored
+     * revision, or when the stored record was written under a newer declaration
+     * version.
+     * @throws ValidationError when `ctx` is for another guild than `guildId`.
+     */
+    set<D extends SettingsDeclaration>(declaration: D, guildId: string, patch: unknown, ctx: RequestContext & {
+        readonly expectedRevision?: number;
+    }): Promise<StoredSettings>;
+    /**
+     * Unset the given fields (or every field), so they read as their defaults.
+     * Writes nothing for a guild that never stored settings. Like
+     * {@link set}, migrates older stored values before unsetting.
+     *
+     * @throws SettingsValidationError when a key is not declared.
+     * @throws ConflictError when the stored record changed concurrently or was
+     * written under a newer declaration version.
+     * @throws ValidationError when `ctx` is for another guild than `guildId`.
+     */
+    reset<D extends SettingsDeclaration>(declaration: D, guildId: string, keys: readonly string[] | "all", ctx: RequestContext): Promise<void>;
+    /**
+     * Describe a module's settings for surfaces other than Discord (FR-030), as
+     * a JSON Schema with every text translated.
+     *
+     * @param locale - any locale string; an unsupported one falls back to English.
+     */
+    describe(declaration: SettingsDeclaration, locale: string): SettingsSchema;
+    /**
+     * Suggestions for one field (FR-021 to FR-026), in the command
+     * autocomplete's own `Choice` format, so one search serves both. A channel,
+     * role or member field searches the guild; static choices are translated
+     * to `ctx.locale` and kept when their name or value contains `query`; a
+     * dynamic search gets `query` and `ctx` (with `ctx.values`, the other
+     * values currently entered). A list suggests for its item. At most 25
+     * results; a search slower than `SUGGESTION_TIMEOUT_MS` (2.5 s) or failing
+     * yields none and is logged at `warn`.
+     *
+     * @throws ValidationError when `fieldKey` is not declared: a malformed
+     * request, like a patch that is not an object.
+     */
+    suggest<D extends SettingsDeclaration>(declaration: D, fieldKey: string, query: string, ctx: RequestContext & {
+        readonly values: Readonly<Record<string, unknown>>;
+    }): Promise<readonly Choice[]>;
+    /**
+     * The readable label of one value of a field, in `ctx.locale` (FR-022): a
+     * channel, role or member's name on the guild, a static choice's
+     * translated label, a dynamic search's `label`, or, without one, the name
+     * of the exact match in `resolve(String(value))`. A list reads `value` as
+     * one item. A search gets the guild's current values as `ctx.values`.
+     *
+     * @returns the label, or `undefined` when none is known (the value is not
+     * suggested, the entity is gone, or the search timed out or failed, logged).
+     * @throws ValidationError when `fieldKey` is not declared.
+     */
+    label<D extends SettingsDeclaration>(declaration: D, fieldKey: string, value: unknown, ctx: RequestContext): Promise<string | undefined>;
+}
+interface SettingsServiceDeps {
+    readonly registry: SettingsRegistry;
+    readonly store: SettingsStore;
+    readonly guilds: GuildDirectory;
+    readonly notifier: SettingsChangedNotifier;
+    readonly translator: Translator;
+    readonly clock: Clock;
+    readonly logger: Logger;
+}
+/**
+ * Create the settings service over its ports.
+ *
+ * @param deps - the registry of declarations and the ports the service reads,
+ * writes, notifies and logs through.
+ * @returns the service shared by module logic and every configuration surface.
+ */
+export declare function createSettingsService(deps: SettingsServiceDeps): SettingsService;
+export {};
+//# sourceMappingURL=settings-service.d.ts.map

package/dist/settings/settings-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-service.d.ts","sourceRoot":"","sources":["../../src/settings/settings-service.ts"],"names":[],"mappings":"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"}

package/dist/settings/settings-service.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSettingsService = createSettingsService;
+const node_util_1 = require("node:util");
+const business_error_1 = require("../errors/business-error");
+const error_message_1 = require("../errors/error-message");
+const cache_1 = require("../settings/cache");
+const decode_stored_1 = require("../settings/decode-stored");
+const describe_1 = require("../settings/describe");
+const messages_1 = require("../settings/messages");
+const migrate_1 = require("../settings/migrate");
+const settings_validation_error_1 = require("../settings/settings-validation-error");
+const status_1 = require("../settings/status");
+const suggest_1 = require("../settings/suggest");
+const validate_1 = require("../settings/validate");
+/**
+ * Create the settings service over its ports.
+ *
+ * @param deps - the registry of declarations and the ports the service reads,
+ * writes, notifies and logs through.
+ * @returns the service shared by module logic and every configuration surface.
+ */
+function createSettingsService(deps) {
+    const { store, guilds, notifier, translator, clock, logger } = deps;
+    const cache = (0, cache_1.createSettingsCache)({ clock, notifier });
+    const ports = { guilds, translator, logger };
+    /**
+     * What a guild reads of `stored`: its valid declared fields, defaults not
+     * applied, migrated in memory when stored under an older version. Logs
+     * every field it has to drop and every failed migration.
+     *
+     * @returns the values, and whether they are a successful migration still to
+     * be written back.
+     */
+    function readable(declaration, stored) {
+        if (stored === null) {
+            return { values: {}, migrated: false };
+        }
+        const at = { guildId: stored.guildId, moduleId: declaration.id };
+        if (stored.version < declaration.version) {
+            const outcome = (0, migrate_1.migrateStored)(declaration, stored);
+            if (!outcome.ok) {
+                logger.error({
+                    ...at,
+                    fromVersion: stored.version,
+                    toVersion: declaration.version,
+                    keys: outcome.invalidKeys,
+                    ...(outcome.error === undefined ? {} : { err: (0, error_message_1.errorMessage)(outcome.error) }),
+                }, "Settings migration failed; storage left unchanged, reading defaults for the fields it cannot read");
+            }
+            return { values: outcome.values, migrated: outcome.ok };
+        }
+        const decoded = (0, decode_stored_1.decodeStored)(declaration, stored.values);
+        if (decoded.invalidKeys.length > 0) {
+            logger.error({ ...at, keys: decoded.invalidKeys }, "Stored settings failed validation; reading defaults for these fields");
+        }
+        return { values: decoded.values, migrated: false };
+    }
+    /**
+     * Write a successful migration back, expecting the revision it was read at.
+     * When another reader (another shard) wrote first, its record is read
+     * again instead: the conflict is not the caller's to handle.
+     */
+    async function writeBack(params) {
+        const { declaration, stored, values } = params;
+        const keys = new Set([...Object.keys(stored.values), ...Object.keys(values)]);
+        const changedKeys = [...keys].filter((key) => !(0, node_util_1.isDeepStrictEqual)(stored.values[key], values[key]));
+        try {
+            await write({
+                declaration,
+                guildId: stored.guildId,
+                stored,
+                expectedRevision: stored.revision,
+                values,
+                changedKeys,
+                author: undefined,
+            });
+            return values;
+        }
+        catch (error) {
+            if (error instanceof business_error_1.ConflictError) {
+                const latest = await store.read(stored.guildId, declaration.id);
+                return readable(declaration, latest).values;
+            }
+            logger.error({
+                guildId: stored.guildId,
+                moduleId: declaration.id,
+                fromVersion: stored.version,
+                toVersion: declaration.version,
+                err: (0, error_message_1.errorMessage)(error),
+            }, "Failed to write migrated settings back; reading the migrated values");
+            return values;
+        }
+    }
+    /** Read and decode a guild's stored settings, bypassing the cache. */
+    async function load(declaration, guildId) {
+        const stored = await store.read(guildId, declaration.id);
+        const read = readable(declaration, stored);
+        const values = read.migrated && stored !== null
+            ? await writeBack({ declaration, stored, values: read.values })
+            : read.values;
+        const withDefaults = Object.entries(declaration.fields).map(([key, declared]) => [
+            key,
+            Object.hasOwn(values, key) ? values[key] : declared.default,
+        ]);
+        return Object.fromEntries(withDefaults);
+    }
+    function get(declaration, guildId) {
+        return cache.read(guildId, declaration.id, () => load(declaration, guildId));
+    }
+    /**
+     * Write `values` over `stored` under the declared version and tell
+     * listeners which keys changed. `author` is the user who asked, or
+     * `undefined` for a write the kernel makes on its own (a migration).
+     */
+    async function write(params) {
+        const { declaration, guildId, stored, author } = params;
+        const next = {
+            guildId,
+            moduleId: declaration.id,
+            version: declaration.version,
+            revision: (stored?.revision ?? 0) + 1,
+            values: params.values,
+            updatedAt: clock.now().toISOString(),
+            ...(author === undefined ? {} : { updatedBy: author }),
+        };
+        await store.write(next, { expectedRevision: params.expectedRevision });
+        // Before notifying: a listener that reads back must see the new values.
+        cache.invalidate(guildId, declaration.id);
+        notifier.notify({
+            guildId,
+            moduleId: declaration.id,
+            changedKeys: params.changedKeys,
+            revision: next.revision,
+            ...(author === undefined ? {} : { changedBy: author }),
+        });
+        return next;
+    }
+    async function getForSurface(declaration, guildId) {
+        const values = await get(declaration, guildId);
+        const surface = Object.entries(values).map(([key, value]) => declaration.fields[key]?.spec.kind === "secret"
+            ? [key, { isSet: value !== undefined }]
+            : [key, value]);
+        return Object.fromEntries(surface);
+    }
+    /** What a strict field's search is checked with while validating a submission. */
+    function validationScope(declaration, ctx) {
+        return {
+            ports,
+            guildId: ctx.guildId,
+            userId: ctx.userId,
+            locale: ctx.locale,
+            currentValues: () => getForSurface(declaration, ctx.guildId),
+        };
+    }
+    return {
+        get,
+        getForSurface,
+        async status(declaration, guildId) {
+            return (0, status_1.settingsStatus)(declaration, await get(declaration, guildId));
+        },
+        async validate(declaration, guildId, patch, ctx) {
+            assertSameGuild(guildId, ctx);
+            const scope = validationScope(declaration, ctx);
+            const result = await (0, validate_1.validateSettings)({ declaration, patch, scope });
+            return result;
+        },
+        async set(declaration, guildId, patch, ctx) {
+            assertSameGuild(guildId, ctx);
+            const scope = validationScope(declaration, ctx);
+            const result = await (0, validate_1.validateSettings)({ declaration, patch, scope });
+            if (!result.ok) {
+                throw new settings_validation_error_1.SettingsValidationError(result.issues);
+            }
+            const stored = await store.read(guildId, declaration.id);
+            assertWritable(declaration, stored);
+            const values = { ...readable(declaration, stored).values };
+            for (const [key, value] of Object.entries(result.values)) {
+                if (value === undefined) {
+                    delete values[key];
+                }
+                else {
+                    values[key] = value;
+                }
+            }
+            return write({
+                declaration,
+                guildId,
+                stored,
+                expectedRevision: ctx.expectedRevision === undefined ? (stored?.revision ?? null) : ctx.expectedRevision,
+                values,
+                changedKeys: Object.keys(result.values),
+                author: ctx.userId,
+            });
+        },
+        async reset(declaration, guildId, keys, ctx) {
+            assertSameGuild(guildId, ctx);
+            const declaredKeys = Object.keys(declaration.fields);
+            const resetKeys = keys === "all" ? declaredKeys : keys;
+            const issues = resetKeys.filter((key) => !declaredKeys.includes(key)).map(unknownField);
+            if (issues.length > 0) {
+                throw new settings_validation_error_1.SettingsValidationError(issues);
+            }
+            const stored = await store.read(guildId, declaration.id);
+            if (stored === null) {
+                return;
+            }
+            assertWritable(declaration, stored);
+            const values = { ...readable(declaration, stored).values };
+            for (const key of resetKeys) {
+                delete values[key];
+            }
+            await write({
+                declaration,
+                guildId,
+                stored,
+                expectedRevision: stored.revision,
+                values,
+                changedKeys: resetKeys,
+                author: ctx.userId,
+            });
+        },
+        describe(declaration, locale) {
+            return (0, describe_1.describeSettings)({ declaration, locale, translator });
+        },
+        async suggest(declaration, fieldKey, query, ctx) {
+            const spec = declaredField(declaration, fieldKey).spec;
+            const scope = { ...ports, moduleId: declaration.id, key: fieldKey, ctx };
+            return (0, suggest_1.suggestChoices)({ scope, spec, query });
+        },
+        async label(declaration, fieldKey, value, ctx) {
+            const spec = declaredField(declaration, fieldKey).spec;
+            const values = await getForSurface(declaration, ctx.guildId);
+            const scope = {
+                ...ports,
+                moduleId: declaration.id,
+                key: fieldKey,
+                ctx: { ...ctx, values },
+            };
+            return (0, suggest_1.suggestionLabel)({ scope, spec, value });
+        },
+    };
+}
+/**
+ * A surface acts for the guild of its request only: a context of another
+ * guild is a malformed request, rejected before anything is read or written.
+ */
+function assertSameGuild(guildId, ctx) {
+    if (ctx.guildId !== guildId) {
+        throw new business_error_1.ValidationError(`Settings request for guild ${ctx.guildId} cannot target guild ${guildId}`);
+    }
+}
+/** A record written under a newer declaration version is never overwritten (FR-019). */
+function assertWritable(declaration, stored) {
+    if (stored !== null && stored.version > declaration.version) {
+        throw new business_error_1.ConflictError(`Settings of module "${declaration.id}" in guild ${stored.guildId} were written under version ${stored.version}, newer than the declared version ${declaration.version}`);
+    }
+}
+/**
+ * The declared field under `key`.
+ *
+ * @throws ValidationError when the declaration has none: asking a field's
+ * suggestions or labels by a wrong key is a malformed request.
+ */
+function declaredField(declaration, key) {
+    const declared = Object.hasOwn(declaration.fields, key) ? declaration.fields[key] : undefined;
+    if (declared === undefined) {
+        throw new business_error_1.ValidationError(`Settings of module "${declaration.id}" have no field "${key}"`);
+    }
+    return declared;
+}
+function unknownField(key) {
+    return {
+        field: key,
+        code: "unknownField",
+        translation: { key: messages_1.SETTINGS_ISSUE_MESSAGES.unknownField },
+    };
+}
+//# sourceMappingURL=settings-service.js.map

package/dist/settings/settings-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-service.js","sourceRoot":"","sources":["../../src/settings/settings-service.ts"],"names":[],"mappings":"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"}

package/dist/settings/settings-validation-error.d.ts

@@ -0,0 +1,23 @@
+import { type ErrorTranslation, ValidationError } from "../errors/business-error";
+/** Why one submitted settings value was rejected. */
+export type SettingsIssueCode = "required" | "type" | "min" | "max" | "minLength" | "maxLength" | "minItems" | "maxItems" | "duplicate" | "channelType" | "notFound" | "unknownChoice" | "unknownField";
+/**
+ * One rejected value of a settings submission. `field` is the field key, a
+ * `key[index]` path for a list item (e.g. `pingRoles[2]`), or a `key.name` path
+ * for a toggle (e.g. `modules.music`); `translation` points at the settings
+ * catalog so every surface shows the same wording for the same failure.
+ */
+export interface SettingsIssue {
+    readonly field: string;
+    readonly code: SettingsIssueCode;
+    readonly translation: ErrorTranslation;
+}
+/**
+ * A settings submission failed validation. Carries every issue at once, so a
+ * surface can flag all faulty fields in one round trip; nothing was stored.
+ */
+export declare class SettingsValidationError extends ValidationError {
+    readonly issues: readonly SettingsIssue[];
+    constructor(issues: readonly SettingsIssue[]);
+}
+//# sourceMappingURL=settings-validation-error.d.ts.map

package/dist/settings/settings-validation-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-validation-error.d.ts","sourceRoot":"","sources":["../../src/settings/settings-validation-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEjF,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAC1B,UAAU,GACV,MAAM,GACN,KAAK,GACL,KAAK,GACL,WAAW,GACX,WAAW,GACX,UAAU,GACV,UAAU,GACV,WAAW,GACX,aAAa,GACb,UAAU,GACV,eAAe,GACf,cAAc,CAAC;AAElB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;CACvC;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,eAAe;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE;gBAAhC,MAAM,EAAE,SAAS,aAAa,EAAE;CAKrD"}

package/dist/settings/settings-validation-error.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsValidationError = void 0;
+const business_error_1 = require("../errors/business-error");
+/**
+ * A settings submission failed validation. Carries every issue at once, so a
+ * surface can flag all faulty fields in one round trip; nothing was stored.
+ */
+class SettingsValidationError extends business_error_1.ValidationError {
+    issues;
+    constructor(issues) {
+        super(`Invalid settings: ${issues.map((issue) => `${issue.field} (${issue.code})`).join(", ")}`);
+        this.issues = issues;
+    }
+}
+exports.SettingsValidationError = SettingsValidationError;
+//# sourceMappingURL=settings-validation-error.js.map