ad2app-lib 1.29.0 → 1.30.0

package/dist/types/I_User.d.ts

@@ -10,8 +10,39 @@ export declare class I_User {
     has_connected_platforms?: boolean;
     influencer?: I_Influencer;
 }
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
 export declare class I_SignedUser extends I_User {
     accessToken: string;
+    /**
+     * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+     * a session carries this, not just `authenticate` — the client replaces its
+     * authed slice wholesale with whichever payload arrives, so a path that omits
+     * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+     *
+     * It lives HERE because AC3 chose an echoing PATCH over a failing one
+     * specifically to remove the forward-only rule from the client, and that only
+     * works if both sides agree on the shape. Until this shipped, the field was
+     * written by the backend, read by the frontend, and declared by neither: the
+     * frontend had to cast through `unknown` to see it, and a rename on either
+     * side would have type-checked clean while the onboarding funnel silently
+     * went dark.
+     *
+     * Optional on purpose — see OnboardingState: absent means "could not read".
+     */
+    onboardingState?: OnboardingState | null;
 }
 export declare enum UserRoles {
     ADMIN = "ADMIN",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -47,7 +47,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej Górski@ad2.app",
+  "author": "Maciej G\u00f3rski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/types/I_User.ts

@@ -13,8 +13,41 @@ export class I_User {
   influencer?: I_Influencer;
 }
 
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
+
 export class I_SignedUser extends I_User {
   accessToken: string;
+
+  /**
+   * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+   * a session carries this, not just `authenticate` — the client replaces its
+   * authed slice wholesale with whichever payload arrives, so a path that omits
+   * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+   *
+   * It lives HERE because AC3 chose an echoing PATCH over a failing one
+   * specifically to remove the forward-only rule from the client, and that only
+   * works if both sides agree on the shape. Until this shipped, the field was
+   * written by the backend, read by the frontend, and declared by neither: the
+   * frontend had to cast through `unknown` to see it, and a rename on either
+   * side would have type-checked clean while the onboarding funnel silently
+   * went dark.
+   *
+   * Optional on purpose — see OnboardingState: absent means "could not read".
+   */
+  onboardingState?: OnboardingState | null;
 }
 
 export enum UserRoles {

package/src/types/onboarding-state.test.ts

@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { I_SignedUser, OnboardingState, UserRoles } from './I_User';
+
+/**
+ * AD2-1331 AC3 — the shared shape, pinned.
+ *
+ * These are mostly COMPILE-time assertions: the value of this file is that
+ * `tsc` fails if `onboardingState` is renamed, narrowed, or made required on
+ * one side of the wire. Before it existed the field was written by the backend,
+ * read by the frontend, and declared by neither, so either side could rename it
+ * and every type-check would still pass while the onboarding funnel went dark.
+ *
+ * The runtime assertions below exist so the file is also a real test rather
+ * than a silent type-only artefact that a test runner skips over.
+ */
+
+test('a signed user may carry a recorded answer', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: 'completed',
+	};
+
+	assert.equal(user.onboardingState, 'completed');
+});
+
+test('null is a value, and means "no record yet" — a new user', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: null,
+	};
+
+	// null must survive as null: the client tells it apart from absent, and
+	// only null means "show the tour".
+	assert.equal(user.onboardingState, null);
+	assert.ok('onboardingState' in user);
+});
+
+test('ABSENT is distinct from null — the field may be omitted entirely', () => {
+	// The migration-pending case. If this ever stops compiling because the
+	// field was made required, the deploy window that follows would show the
+	// onboarding tour to the entire existing user base.
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+	};
+
+	assert.equal('onboardingState' in user, false);
+	assert.equal(user.onboardingState, undefined);
+});
+
+test('the state union is exactly the two recorded answers', () => {
+	const every: OnboardingState[] = ['skipped', 'completed'];
+
+	assert.deepEqual(every, ['skipped', 'completed']);
+	// @ts-expect-error 'pending' is not a recorded answer; null/absent cover
+	// "no answer", and a third string would be a state nobody handles.
+	const invalid: OnboardingState = 'pending';
+	assert.equal(invalid, 'pending');
+});