@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/onboarding/onboarding.service.js

@@ -0,0 +1,171 @@
+"use strict";
+// =============================================================================
+// OnboardingService: the caller's derived checklists (issue #745, PP-9.3)
+// =============================================================================
+//
+// READ-ONLY. The stored UI state is read straight from `user_settings`
+// through `ONBOARDING_DATA.readUserSettingsValue` (a select), never through
+// `UserSettingsService.getSettings`, which creates a default row on first
+// read: a GET leaves the database unchanged for a user with no settings row.
+// Step status is derived by the engine on every request and never stored.
+//
+// The admin steps reuse the Doctor (its cache, its timeouts, its remedies):
+// one `DoctorService.run` per Doctor category the applicable steps' checks
+// span, with `refresh` forwarded.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var OnboardingService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnboardingService = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const core_1 = require("@nestjs/core");
+const index_1 = require("../doctor/index");
+const onboarding_builtins_1 = require("./onboarding.builtins");
+const onboarding_engine_1 = require("./onboarding.engine");
+const onboarding_options_1 = require("./onboarding.options");
+const onboarding_audiences_1 = require("./onboarding.audiences");
+const onboarding_registries_1 = require("./onboarding.registries");
+const onboarding_settings_1 = require("./onboarding.settings");
+const ports_1 = require("./ports");
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+/**
+ * Derives `GET /api/onboarding`. Provided by `OnboardingModule.forRoot()`.
+ *
+ * @stability experimental
+ */
+let OnboardingService = OnboardingService_1 = class OnboardingService {
+    data;
+    moduleRef;
+    features;
+    doctor;
+    checks;
+    config;
+    logger = new common_1.Logger(OnboardingService_1.name);
+    options;
+    /**
+     * @param data - the app's data port.
+     * @param moduleRef - for app facts (`ctx.get(token)`).
+     * @param features - the feature gate; absent: every feature-gated step is omitted.
+     * @param doctor - the Doctor; absent: every Doctor-backed step is omitted.
+     * @param checks - the Doctor's check registry.
+     * @param config - reads `INITIAL_ADMIN_EMAIL`.
+     * @param options - the resolved module options.
+     */
+    constructor(data, moduleRef, features, doctor, checks, config, options) {
+        this.data = data;
+        this.moduleRef = moduleRef;
+        this.features = features;
+        this.doctor = doctor;
+        this.checks = checks;
+        this.config = config;
+        this.options = options ?? onboarding_options_1.DEFAULT_ONBOARDING_OPTIONS;
+    }
+    /** Fails the boot when a step or an ordering names an unregistered fact. */
+    onApplicationBootstrap() {
+        (0, onboarding_registries_1.assertOnboardingRegistries)();
+    }
+    /**
+     * The caller's stored UI state, user block and (for an administrator)
+     * admin block.
+     *
+     * @param caller - the request user.
+     * @param options - `refresh` bypasses the Doctor's cache.
+     * @returns the response.
+     */
+    async get(caller, options = {}) {
+        const value = asRecord(await this.data.readUserSettingsValue(caller.id));
+        const settings = (0, onboarding_settings_1.readOnboardingState)(value);
+        const refresh = options.refresh === true;
+        const who = {
+            id: caller.id,
+            permissions: [...caller.permissions],
+            roles: [...(caller.roles ?? [])],
+            activeOrgId: caller.activeOrgId ?? null,
+        };
+        const featureMemo = new Map();
+        const isFeatureEnabled = (feature) => {
+            let pending = featureMemo.get(feature);
+            if (!pending) {
+                pending = this.features ? this.features.isEnabled(feature).catch(() => false) : Promise.resolve(false);
+                featureMemo.set(feature, pending);
+            }
+            return pending;
+        };
+        const initialAdminEmail = this.config?.get(this.options.initialAdminEmailEnv)?.trim() || null;
+        const doctor = this.doctorAccess();
+        const { user, admin, audiences } = await (0, onboarding_engine_1.evaluateOnboarding)({
+            steps: onboarding_registries_1.onboardingStepRegistry.list(),
+            facts: onboarding_registries_1.onboardingFactRegistry.list(),
+            orderings: onboarding_registries_1.onboardingOrderingRegistry.list(),
+            includeAdmin: who.permissions.includes(this.options.adminPermission),
+            audiences: onboarding_audiences_1.onboardingAudienceRegistry.list(),
+            audienceContext: { adminPermission: this.options.adminPermission },
+            skipped: settings.skipped,
+            seed: new Map([[onboarding_builtins_1.ONBOARDING_FACTS.USER_SETTINGS, value]]),
+            warn: (message) => this.logger.warn(message),
+            context: (doctorCheckIds, fact) => ({
+                caller: who,
+                refresh,
+                data: this.data,
+                doctor,
+                doctorCheckIds,
+                initialAdminEmail,
+                isFeatureEnabled,
+                fact: (id) => fact(id),
+                get: (token) => this.moduleRef.get(token, { strict: false }),
+            }),
+        });
+        return { settings, user, admin, ...(audiences ? { audiences } : {}) };
+    }
+    doctorAccess() {
+        const doctor = this.doctor;
+        const checks = this.checks;
+        if (!doctor || !checks)
+            return null;
+        return {
+            has: (id) => checks.get(id) !== undefined,
+            reports: async (ids, refresh) => {
+                const categories = [...new Set(ids.map((id) => checks.get(id)?.category).filter((c) => !!c))];
+                const reports = await Promise.all(categories.map((category) => doctor.run({ category, refresh })));
+                const byId = new Map();
+                for (const report of reports)
+                    for (const check of report.checks)
+                        byId.set(check.id, check);
+                return byId;
+            },
+        };
+    }
+};
+exports.OnboardingService = OnboardingService;
+exports.OnboardingService = OnboardingService = OnboardingService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(ports_1.ONBOARDING_DATA)),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(ports_1.ONBOARDING_FEATURES)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(index_1.DoctorService)),
+    __param(4, (0, common_1.Optional)()),
+    __param(4, (0, common_1.Inject)(index_1.DoctorCheckRegistry)),
+    __param(5, (0, common_1.Optional)()),
+    __param(5, (0, common_1.Inject)(config_1.ConfigService)),
+    __param(6, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Inject)(onboarding_options_1.ONBOARDING_OPTIONS)),
+    __metadata("design:paramtypes", [Object, core_1.ModuleRef, Object, index_1.DoctorService,
+        index_1.DoctorCheckRegistry,
+        config_1.ConfigService, Object])
+], OnboardingService);
+//# sourceMappingURL=onboarding.service.js.map

package/dist/onboarding/onboarding.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.service.js","sourceRoot":"","sources":["../../src/onboarding/onboarding.service.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,kCAAkC;AAClC,gFAAgF;;;;;;;;;;;;;;;;AAIhF,2CAA8F;AAC9F,2CAA+C;AAC/C,uCAAyC;AAEzC,2CAAqE;AACrE,+DAAyD;AACzD,2DAAyD;AACzD,6DAA4H;AAC5H,iEAAoE;AACpE,mEAKiC;AACjC,+DAA4D;AAE5D,mCAAoH;AAkBpH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1H,CAAC;AAED;;;;GAIG;AAEI,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAcgB;IACzB;IACyC;IACN;IACM;IACN;IAlBrC,MAAM,GAAG,IAAI,eAAM,CAAC,mBAAiB,CAAC,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAkC;IAE1D;;;;;;;;OAQG;IACH,YAC4C,IAAwB,EACjD,SAAoB,EACqB,QAAgC,EACtC,MAAsB,EAChB,MAA4B,EAClC,MAAsB,EAClC,OAAyC;QANvC,SAAI,GAAJ,IAAI,CAAoB;QACjD,cAAS,GAAT,SAAS,CAAW;QACqB,aAAQ,GAAR,QAAQ,CAAwB;QACtC,WAAM,GAAN,MAAM,CAAgB;QAChB,WAAM,GAAN,MAAM,CAAsB;QAClC,WAAM,GAAN,MAAM,CAAgB;QAG1E,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,+CAA0B,CAAC;IACvD,CAAC;IAED,4EAA4E;IAC5E,sBAAsB;QACpB,IAAA,kDAA0B,GAAE,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,MAA+B,EAAE,UAAiC,EAAE;QAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,IAAA,yCAAmB,EAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC;QACzC,MAAM,GAAG,GAAqB;YAC5B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,WAAW,EAAE,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC;YACpC,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAChC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;SACxC,CAAC;QAEF,MAAM,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;QACxD,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAoB,EAAE;YAC7D,IAAI,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACvC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACvG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;QACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAS,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QACtG,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAEnC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,IAAA,sCAAkB,EAAC;YAC1D,KAAK,EAAE,8CAAsB,CAAC,IAAI,EAAE;YACpC,KAAK,EAAE,8CAAsB,CAAC,IAAI,EAAE;YACpC,SAAS,EAAE,kDAA0B,CAAC,IAAI,EAAE;YAC5C,YAAY,EAAE,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;YACpE,SAAS,EAAE,iDAA0B,CAAC,IAAI,EAAE;YAC5C,eAAe,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE;YAClE,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,sCAAgB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;YACxD,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;YAC5C,OAAO,EAAE,CAAC,cAAc,EAAE,IAAI,EAA4B,EAAE,CAAC,CAAC;gBAC5D,MAAM,EAAE,GAAG;gBACX,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM;gBACN,cAAc;gBACd,iBAAiB;gBACjB,gBAAgB;gBAChB,IAAI,EAAE,CAAI,EAAU,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAe;gBAC/C,GAAG,EAAE,CAAI,KAA+D,EAAE,EAAE,CAC1E,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAc,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAM;aAC7D,CAAC;SACH,CAAC,CAAC;QAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACxE,CAAC;IAEO,YAAY;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEpC,OAAO;YACL,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,SAAS;YACzC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;gBAC9B,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3G,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBACnG,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6B,CAAC;gBAClD,KAAK,MAAM,MAAM,IAAI,OAAO;oBAAE,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM;wBAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;gBAC3F,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AAxGY,8CAAiB;4BAAjB,iBAAiB;IAD7B,IAAA,mBAAU,GAAE;IAeR,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;IAEvB,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,2BAAmB,CAAC,CAAA;IACvC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,qBAAa,CAAC,CAAA;IACjC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,2BAAmB,CAAC,CAAA;IACvC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,sBAAa,CAAC,CAAA;IACjC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,uCAAkB,CAAC,CAAA;6CALX,gBAAS,UAEwB,qBAAa;QACP,2BAAmB;QACzB,sBAAa;GAnBjE,iBAAiB,CAwG7B"}

package/dist/onboarding/onboarding.settings.d.ts

@@ -0,0 +1,101 @@
+import { type OnboardingSettings, type OnboardingSettingsPatch, type OnboardingState } from '@marinoscar/platform-contract/onboarding';
+import { z } from 'zod';
+import { type UserSettingsNamespaceExtension } from '../settings/index';
+/**
+ * Whether `id` names a registered step the user may skip.
+ *
+ * @param id - a step id.
+ * @returns `true` for a registered, skippable step.
+ *
+ * @stability experimental
+ */
+export declare function isSkippableStepId(id: string): boolean;
+/**
+ * The `onboarding` merge (JSON Merge Patch, shallow): `undefined` keeps the
+ * stored value, `null` clears the namespace; inside it, a provided field
+ * replaces, an explicit `null` deletes it. A `skipped` id that is not a
+ * registered, skippable step is a 400.
+ *
+ * @param current - the stored namespace.
+ * @param patch - the parsed PATCH branch.
+ * @returns the merged namespace, or `undefined` when empty.
+ * @throws BadRequestException when `skipped` names an id that cannot be skipped.
+ *
+ * @stability experimental
+ */
+export declare function mergeOnboardingSettings(current: OnboardingSettings | undefined, patch: OnboardingSettingsPatch | null | undefined): OnboardingSettings | undefined;
+/**
+ * The platform's `onboarding` user namespace. The app registers it in its
+ * user manifest (appended after the namespaces it already has).
+ *
+ * @stability experimental
+ */
+export declare const ONBOARDING_USER_SETTINGS: {
+    /** The namespace key. */
+    key: "onboarding";
+    /** What it holds. */
+    description: string;
+    /** The stored shape (strict). */
+    schema: z.ZodObject<{
+        welcomeSeenAt: z.ZodOptional<z.ZodString>;
+        checklistDismissedAt: z.ZodOptional<z.ZodString>;
+        adminDismissedAt: z.ZodOptional<z.ZodString>;
+        skipped: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    /** The PATCH shape (`null` clears a field). */
+    patchSchema: z.ZodObject<{
+        welcomeSeenAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        checklistDismissedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        adminDismissedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        skipped: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
+    /** See {@link mergeOnboardingSettings}. */
+    merge: typeof mergeOnboardingSettings;
+};
+declare module '../settings/index' {
+    interface UserSettingsNamespaces {
+        /** First-run onboarding UI state (#745). Absent: never seen, never dismissed, nothing skipped. */
+        onboarding: OnboardingSettings;
+    }
+    interface UserSettingsNamespaceDeclarations {
+        /** The `onboarding` declaration. */
+        onboarding: typeof ONBOARDING_USER_SETTINGS;
+    }
+}
+/**
+ * Fields an app adds to the stored `onboarding` namespace (EvoPath's `goal`),
+ * as a settings extension. List the result in the app's user-settings
+ * extensions (`APP_USER_SETTINGS_EXTENSIONS`): the manifest folds it in, so
+ * the namespace stays `.strict()`, `PATCH /api/user-settings` accepts the
+ * fields (`null` deletes one) and `GET /api/onboarding` reports them under
+ * `settings`.
+ *
+ * @param shape - the added fields; each optional, never `.default()`.
+ * @returns the extension.
+ * @throws Error when a field collides with a platform field.
+ *
+ * @example
+ * ```ts
+ * export const APP_USER_SETTINGS_EXTENSIONS = [
+ *   extendOnboardingSettings({ goal: z.enum(['strength', 'endurance']).optional() }),
+ * ];
+ * ```
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare function extendOnboardingSettings(shape: z.ZodRawShape): UserSettingsNamespaceExtension;
+/**
+ * The stored `onboarding` namespace as the response reports it, from the raw
+ * `user_settings.value`: parsed with the REGISTERED declaration (so an app's
+ * extended fields come through), each platform field `null` when unset, and
+ * `skipped` reduced to registered, skippable ids. An absent or unparseable
+ * namespace reads as all `null`, never as an error.
+ *
+ * @param value - the raw `user_settings.value`, or `null`.
+ * @returns the state.
+ *
+ * @stability experimental
+ */
+export declare function readOnboardingState(value: unknown): OnboardingState;
+//# sourceMappingURL=onboarding.settings.d.ts.map

package/dist/onboarding/onboarding.settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.settings.d.ts","sourceRoot":"","sources":["../../src/onboarding/onboarding.settings.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACrB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAGL,KAAK,8BAA8B,EACpC,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,GAAG,SAAS,EACvC,KAAK,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAChD,kBAAkB,GAAG,SAAS,CAkChC;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;IACnC,yBAAyB;;IAEzB,qBAAqB;;IAGrB,iCAAiC;;;;;;;IAEjC,+CAA+C;;;;;;;IAE/C,2CAA2C;;CAE+C,CAAC;AAE7F,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,sBAAsB;QAC9B,kGAAkG;QAClG,UAAU,EAAE,kBAAkB,CAAC;KAChC;IACD,UAAU,iCAAiC;QACzC,oCAAoC;QACpC,UAAU,EAAE,OAAO,wBAAwB,CAAC;KAC7C;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,GAAG,8BAA8B,CAO7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAiBnE"}

package/dist/onboarding/onboarding.settings.js

@@ -0,0 +1,171 @@
+"use strict";
+// =============================================================================
+// The `onboarding` user-settings namespace (issue #745, PP-9.3)
+// =============================================================================
+//
+// The ONLY stored onboarding state: UI facts (`welcomeSeenAt`,
+// `checklistDismissedAt`, `adminDismissedAt`) and the user's `skipped` step
+// ids. No step's completion is ever stored: a stored flag lies after a key
+// rotation, a derived status cannot drift.
+//
+// Written through the existing `PATCH /api/user-settings` (with `If-Match`):
+// a shallow merge where an explicit `null` clears a key (EvoPath's
+// `mergeOnboarding`). `skipped` accepts only ids of registered, skippable
+// steps (a 400 otherwise); ids that stopped qualifying are dropped on read
+// and on the next write rather than failing either.
+//
+// The namespace is `.strict()`; an app adds fields (EvoPath's `goal`) with
+// `extendOnboardingSettings`, which folds into this declaration through the
+// settings slice's own extension mechanism, so it stays strict.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ONBOARDING_USER_SETTINGS = void 0;
+exports.isSkippableStepId = isSkippableStepId;
+exports.mergeOnboardingSettings = mergeOnboardingSettings;
+exports.extendOnboardingSettings = extendOnboardingSettings;
+exports.readOnboardingState = readOnboardingState;
+const common_1 = require("@nestjs/common");
+const onboarding_1 = require("@marinoscar/platform-contract/onboarding");
+const zod_1 = require("zod");
+const index_1 = require("../settings/index");
+const onboarding_registries_1 = require("./onboarding.registries");
+const PLATFORM_FIELDS = ['welcomeSeenAt', 'checklistDismissedAt', 'adminDismissedAt', 'skipped'];
+/**
+ * Whether `id` names a registered step the user may skip.
+ *
+ * @param id - a step id.
+ * @returns `true` for a registered, skippable step.
+ *
+ * @stability experimental
+ */
+function isSkippableStepId(id) {
+    return onboarding_registries_1.onboardingStepRegistry.get(id)?.skippable === true;
+}
+function dedupe(ids) {
+    return [...new Set(ids)];
+}
+/**
+ * The `onboarding` merge (JSON Merge Patch, shallow): `undefined` keeps the
+ * stored value, `null` clears the namespace; inside it, a provided field
+ * replaces, an explicit `null` deletes it. A `skipped` id that is not a
+ * registered, skippable step is a 400.
+ *
+ * @param current - the stored namespace.
+ * @param patch - the parsed PATCH branch.
+ * @returns the merged namespace, or `undefined` when empty.
+ * @throws BadRequestException when `skipped` names an id that cannot be skipped.
+ *
+ * @stability experimental
+ */
+function mergeOnboardingSettings(current, patch) {
+    if (patch === undefined)
+        return current;
+    if (patch === null)
+        return undefined;
+    const merged = {};
+    for (const field of PLATFORM_FIELDS) {
+        if (current?.[field] !== undefined)
+            merged[field] = current[field];
+    }
+    if (Array.isArray(merged['skipped'])) {
+        merged['skipped'] = merged['skipped'].filter(isSkippableStepId);
+    }
+    for (const field of PLATFORM_FIELDS) {
+        const value = patch[field];
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            delete merged[field];
+            continue;
+        }
+        if (field === 'skipped') {
+            const refused = value.filter((id) => !isSkippableStepId(id));
+            if (refused.length > 0) {
+                throw new common_1.BadRequestException(`onboarding.skipped may hold only registered, skippable step ids; refused: ${refused.join(', ')}`);
+            }
+            merged[field] = dedupe(value);
+            continue;
+        }
+        merged[field] = value;
+    }
+    if (Array.isArray(merged['skipped']) && merged['skipped'].length === 0)
+        delete merged['skipped'];
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * The platform's `onboarding` user namespace. The app registers it in its
+ * user manifest (appended after the namespaces it already has).
+ *
+ * @stability experimental
+ */
+exports.ONBOARDING_USER_SETTINGS = {
+    /** The namespace key. */
+    key: onboarding_1.ONBOARDING_SETTINGS_KEY,
+    /** What it holds. */
+    description: 'First-run onboarding UI state: when the welcome was seen, when a checklist was dismissed, and which skippable steps were skipped. Never step completion.',
+    /** The stored shape (strict). */
+    schema: onboarding_1.onboardingSettingsSchema,
+    /** The PATCH shape (`null` clears a field). */
+    patchSchema: onboarding_1.onboardingSettingsPatchSchema,
+    /** See {@link mergeOnboardingSettings}. */
+    merge: mergeOnboardingSettings,
+};
+/**
+ * Fields an app adds to the stored `onboarding` namespace (EvoPath's `goal`),
+ * as a settings extension. List the result in the app's user-settings
+ * extensions (`APP_USER_SETTINGS_EXTENSIONS`): the manifest folds it in, so
+ * the namespace stays `.strict()`, `PATCH /api/user-settings` accepts the
+ * fields (`null` deletes one) and `GET /api/onboarding` reports them under
+ * `settings`.
+ *
+ * @param shape - the added fields; each optional, never `.default()`.
+ * @returns the extension.
+ * @throws Error when a field collides with a platform field.
+ *
+ * @example
+ * ```ts
+ * export const APP_USER_SETTINGS_EXTENSIONS = [
+ *   extendOnboardingSettings({ goal: z.enum(['strength', 'endurance']).optional() }),
+ * ];
+ * ```
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+function extendOnboardingSettings(shape) {
+    for (const key of Object.keys(shape)) {
+        if (PLATFORM_FIELDS.includes(key)) {
+            throw new Error(`extendOnboardingSettings: "${key}" is a platform field of the onboarding namespace`);
+        }
+    }
+    return { key: onboarding_1.ONBOARDING_SETTINGS_KEY, schema: zod_1.z.object(shape) };
+}
+/**
+ * The stored `onboarding` namespace as the response reports it, from the raw
+ * `user_settings.value`: parsed with the REGISTERED declaration (so an app's
+ * extended fields come through), each platform field `null` when unset, and
+ * `skipped` reduced to registered, skippable ids. An absent or unparseable
+ * namespace reads as all `null`, never as an error.
+ *
+ * @param value - the raw `user_settings.value`, or `null`.
+ * @returns the state.
+ *
+ * @stability experimental
+ */
+function readOnboardingState(value) {
+    const raw = value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value[onboarding_1.ONBOARDING_SETTINGS_KEY]
+        : undefined;
+    const schema = index_1.userSettingsNamespaceRegistry.get(onboarding_1.ONBOARDING_SETTINGS_KEY)?.schema ?? onboarding_1.onboardingSettingsSchema;
+    const parsed = schema.safeParse(raw ?? {});
+    const stored = (parsed.success ? parsed.data : {});
+    const skipped = Array.isArray(stored['skipped']) ? stored['skipped'].filter(isSkippableStepId) : [];
+    return {
+        ...stored,
+        welcomeSeenAt: stored['welcomeSeenAt'] ?? null,
+        checklistDismissedAt: stored['checklistDismissedAt'] ?? null,
+        adminDismissedAt: stored['adminDismissedAt'] ?? null,
+        skipped,
+    };
+}
+//# sourceMappingURL=onboarding.settings.js.map

package/dist/onboarding/onboarding.settings.js.map

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