@endora-commerce/mod-settings 0.100.0

package/dist/backend/services/settings-admin.service.d.ts

@@ -0,0 +1,206 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type SettingWriteValidatorRegistryPort } from '@endora-commerce/contracts';
+import type { EventBus } from '@endora-commerce/platform/events';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { SettingGroup } from '@endora-commerce/platform/kernel';
+import { Setting } from '@endora-commerce/platform/kernel';
+import { SettingValue } from '@endora-commerce/platform/kernel';
+import type { SettingsCacheInvalidation } from '@endora-commerce/platform/kernel';
+/**
+ * SettingsAdminService — feature 004 / US2 (T034).
+ *
+ * Centralises every mutation an Admin UI client can make to settings:
+ *   - per-channel value writes (apply-to-all / apply-to-subset / reset)
+ *   - group CRUD (create / rename / rescope / delete-with-reassign-to-general)
+ *
+ * Optimistic concurrency uses an ISO-timestamp `expectedVersion` field
+ * matching the pattern adopted in feature 003 governance: when present and
+ * stale, the service rejects with `409 VERSION_CONFLICT`.
+ *
+ * Every successful mutation, in this order:
+ *   - flushes;
+ *   - records an `audit_log_entries` row via {@link AuditPort};
+ *   - **drops the settings cache** through {@link SettingsCacheInvalidation};
+ *   - emits an EventBus event (see contract section E).
+ *
+ * The third step is the write seam this service exists to be (issue #45). The
+ * drop used to be a *consequence* of the fourth: the kernel subscribed
+ * `SettingsCacheInvalidator` to `settings.value_changed`, and `EventBus`
+ * dispatches handlers in registration order and fire-and-forget outside a
+ * scope. So the cache was dropped in time only because that subscriber
+ * happened to be registered first and reached `SharedDropMarks.begin`
+ * synchronously — a module subscribing ahead of it deferred the drop past a
+ * caller's read, and a write inside an `EventBus.run` scope (every Command —
+ * `CommandBus.run` opens one) deferred it past the whole command. Three
+ * separate defects came out of that arrangement (MR !540 / issue #30, issue
+ * #33, issue #45), so the fourth fix is not another correction of the ordering:
+ * the drop is now part of the write and is awaited, and nothing on the bus can
+ * be early or late for it.
+ *
+ * It stays **before** the emit, which also gives every subscriber what the
+ * ordering used to promise them: `inventory`'s threshold mirror, `search`'s LLM
+ * reactor and `product_feeds`' schedule reconcile all re-read the setting they
+ * were told about, and all three now read post-invalidation state by
+ * construction rather than by registration luck.
+ */
+export interface AdminAuditContext {
+    actorAdminUserId: string | null;
+    requestId?: string | null;
+}
+/**
+ * The effective-state surface this module needs — feature 073, Constitution
+ * XVII. Injected rather than imported so `settings` keeps no edge into the
+ * lifecycle service graph; `_lifecycle` already depends on this module's
+ * `Setting` entity, and reversing that edge in code would make the direction of
+ * the dependency a matter of which file you happened to open.
+ */
+export interface ModulePresencePort {
+    /**
+     * Platform availability AND operator activation, resolved in memory.
+     * `undefined` when the platform has never heard of this owner — a
+     * hand-created group, a legacy row, a fixture. Those are not modules whose
+     * presence anybody can toggle, and treating them as absent would take an
+     * operator's configuration away for a module that does not exist.
+     */
+    presenceOf(moduleId: string): boolean | undefined;
+    /** The module whose activation control this code holds, if any. */
+    activationControlOwner(settingCode: string): string | undefined;
+}
+/** One setting, plus what feature 073 says an operator may do with it. */
+export interface ClassifiedSetting {
+    setting: Setting;
+    values: SettingValue[];
+    /**
+     * `false` when the owning module is not effectively present. The value is
+     * still readable — off is not uninstall — but every write is refused
+     * (FR-033).
+     */
+    editable: boolean;
+    /**
+     * This setting IS its module's activation control: the single exception that
+     * stays writable while the module is off, and the one setting this service
+     * refuses outright (the audited Command owns it).
+     */
+    activationControl: boolean;
+}
+export interface SetValueResult {
+    setting: Setting;
+    affectedChannelIds: string[];
+    newVersion: string;
+}
+export declare class SettingsAdminService {
+    private readonly emFactory;
+    private readonly eventBus;
+    /**
+     * The kernel's settings cache, contributed by a root as `settingsCache`.
+     * Required, and deliberately not optional: an optional cache is a cache
+     * that is silently absent in one composition and present in the other,
+     * which is the shape every previous defect in this area had.
+     */
+    private readonly cache;
+    private readonly auditLogService?;
+    /** Base64 32-byte key for `secret` settings (feature 043, FR-021). */
+    private readonly secretEncryptionKey?;
+    /**
+     * Feature 073. Absent in a composition with no lifecycle (unit tests):
+     * every setting then classifies as editable, which is the pre-073
+     * behaviour rather than a fall-open — there is no activation axis to
+     * resolve at all.
+     */
+    private readonly presence?;
+    /**
+     * Feature 078, D-95.2. Absent in a composition that registers no registry:
+     * every write is then accepted on shape alone, which is the pre-078
+     * behaviour. Present, it is where the module that declared the setting gets
+     * to refuse a value `settings` cannot judge.
+     */
+    private readonly writeValidators?;
+    constructor(emFactory: () => EntityManager, eventBus: EventBus, 
+    /**
+     * The kernel's settings cache, contributed by a root as `settingsCache`.
+     * Required, and deliberately not optional: an optional cache is a cache
+     * that is silently absent in one composition and present in the other,
+     * which is the shape every previous defect in this area had.
+     */
+    cache: SettingsCacheInvalidation, auditLogService?: AuditPort | undefined, 
+    /** Base64 32-byte key for `secret` settings (feature 043, FR-021). */
+    secretEncryptionKey?: string | undefined, 
+    /**
+     * Feature 073. Absent in a composition with no lifecycle (unit tests):
+     * every setting then classifies as editable, which is the pre-073
+     * behaviour rather than a fall-open — there is no activation axis to
+     * resolve at all.
+     */
+    presence?: ModulePresencePort | undefined, 
+    /**
+     * Feature 078, D-95.2. Absent in a composition that registers no registry:
+     * every write is then accepted on shape alone, which is the pre-078
+     * behaviour. Present, it is where the module that declared the setting gets
+     * to refuse a value `settings` cannot judge.
+     */
+    writeValidators?: SettingWriteValidatorRegistryPort | undefined);
+    /**
+     * Classify one setting against the effective state of the module that owns
+     * it. Per setting, not per group: a disabled module's activation control must
+     * stay visible and writable (Constitution XVII's single exception), so its
+     * group stays non-empty and a group-level filter would render the whole
+     * group — every knob of a module that is supposed to be gone.
+     */
+    private classify;
+    /**
+     * Refuse a write the classification says is not available.
+     *
+     * Two distinct refusals, because they mean different things to an operator:
+     * an activation code has a *different* door (the audited Command), while an
+     * absent module's ordinary setting has *no* door until the module is back.
+     */
+    private assertWritable;
+    listGroups(filter?: {
+        groupCode?: string;
+    }): Promise<{
+        groups: Array<{
+            group: SettingGroup;
+            settings: ClassifiedSetting[];
+        }>;
+    }>;
+    getSettingByCode(code: string): Promise<{
+        setting: Setting;
+        values: SettingValue[];
+        version: string;
+        editable: boolean;
+        activationControl: boolean;
+    }>;
+    setValueForAllChannels(code: string, rawValue: unknown, expectedVersion: string | null, actor: AdminAuditContext): Promise<SetValueResult>;
+    setValueForSubset(code: string, channelCodes: string[], rawValue: unknown, expectedVersion: string | null, actor: AdminAuditContext): Promise<SetValueResult>;
+    private setValue;
+    /**
+     * Hand every channel's **post-write** value to the validators the owning
+     * module contributed, and let their throw reach the caller unchanged.
+     *
+     * `settings` computes the projection because it owns three-tier resolution
+     * (per-channel row → globalValue → manifest defaultValue); a validator that
+     * re-derived it would drift from it. The extra `SalesChannel` read only
+     * happens when a validator is actually registered for the code.
+     */
+    private runWriteValidators;
+    resetValues(code: string, channelCodes: string[] | undefined, actor: AdminAuditContext): Promise<{
+        setting: Setting;
+        resetChannelIds: string[];
+        globalValueCleared: boolean;
+        newVersion: string;
+    }>;
+    createGroup(input: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[];
+    }, actor: AdminAuditContext): Promise<SettingGroup>;
+    updateGroup(code: string, patch: {
+        name?: string;
+        salesChannelCodes?: string[];
+    }, expectedVersion: string | null, actor: AdminAuditContext): Promise<SettingGroup>;
+    deleteGroup(code: string, actor: AdminAuditContext): Promise<void>;
+    /** Compute the setting's effective version = max(setting.updated_at, max(values.updated_at)). */
+    computeSettingVersion(setting: Setting, values: SettingValue[]): string;
+    private assertVersion;
+}
+//# sourceMappingURL=settings-admin.service.d.ts.map

package/dist/backend/services/settings-admin.service.d.ts.map

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