founder-schema 0.16.0 → 0.17.0

package/dist/domains/onboarding/onboarding.js

@@ -16,8 +16,8 @@
  * for the end. Letting those two drift is how a wizard says a step is optional
  * and then answers 422 at Finish.
  *
- * NO COPY IN HERE. Step titles and help lines are translation KEYS
- * (`titleKey`, `helpKey`), Jansathi's rule for every config string: an English
+ * NO COPY IN HERE. A step's label and title are translation KEYS
+ * (`labelKey`, `titleKey`), Jansathi's rule for every config string: an English
  * sentence in a shared package is a sentence every other language has to match
  * by wording. A topic category is named by its `key`, which the client words
  * (0.6.0 dropped its `labelKey`: the web, English-only since 2026-10-06, read
@@ -26,9 +26,11 @@
  * @module founder-schema/domains/onboarding
  */
 import { z } from 'zod';
-import { displayNameSchema, GENDER_VALUES, GOAL_VALUES, genderSchema, goalSchema, INDUSTRY_VALUES, industrySchema, locationSchema, objectIdSchema, optionalTrimmedString, phoneSchema, SKILL_VALUES, STARTUP_STAGE_VALUES, skillSchema, startupStageSchema, } from '../../core/common.js';
+import { displayNameSchema, GENDER_VALUES, GOAL_VALUES, genderSchema, goalListSchema, goalSchema, INDUSTRY_VALUES, industrySchema, objectIdSchema, optionalTrimmedString, phoneSchema, SKILL_VALUES, STARTUP_STAGE_VALUES, skillListSchema, skillSchema, startupStageSchema, } from '../../core/common.js';
 import { ABOUT_MAX, CITY_MAX, COUNTRY_MAX, DISPLAY_NAME_MAX, GOALS_MIN, HEADLINE_MAX, LINK_URL_MAX, SKILLS_MAX, STATE_MAX, TEAM_SIZE_MAX, VENTURE_NAME_MAX, } from '../../core/limits.js';
 import { VALIDATION_MESSAGE } from '../../core/validation.js';
+import { indiaLocationSchema } from '../location/india.js';
+import { mediaImageSchema } from '../media/media.js';
 import { founderLinksSchema, ventureSchema } from '../profile/founder-profile.js';
 // ─── Age ─────────────────────────────────────────────────────────────────────
 /**
@@ -87,6 +89,58 @@ function isRealDate(iso) {
     const asDate = new Date(Date.UTC(y, m - 1, d));
     return (asDate.getUTCFullYear() === y && asDate.getUTCMonth() === m - 1 && asDate.getUTCDate() === d);
 }
+/**
+ * True for a `YYYY-MM-DD` that is a real calendar date (0.17.0, exported so a
+ * client's date picker checks a date exactly as `dateOfBirthSchema` does):
+ * not 2026-02-30, not 2026-13-01.
+ */
+export function isRealIsoDate(value) {
+    return isoDateSchema.safeParse(value).success && isRealDate(value.trim());
+}
+/** `YYYY-MM-DD` for a moment, counted in India's calendar. */
+const isoInIndia = (moment) => new Date(moment + INDIA_OFFSET_MS).toISOString().slice(0, 10);
+/**
+ * Today in India, `YYYY-MM-DD` (0.17.0): the day every age here is counted
+ * from (`ageInYears`), so a client's "today" must be this one, never the
+ * device's own: east of India the device is already on tomorrow.
+ */
+export function todayInIndia(now = new Date()) {
+    return isoInIndia(now.getTime());
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+const isoOfUtc = (ms) => new Date(ms).toISOString().slice(0, 10);
+/**
+ * The dates of birth `dateOfBirthSchema` accepts TODAY, both ends included
+ * (0.17.0): `latest` makes someone exactly `MIN_AGE_YEARS` today, `earliest`
+ * exactly `MAX_AGE_YEARS`. Worked out with `ageInYears` itself, so a picker
+ * that offers only this window can never offer a date the schema refuses, a
+ * 29 February included.
+ */
+export function dateOfBirthBounds(now = new Date()) {
+    const [y, m, d] = todayInIndia(now).split('-').map(Number);
+    let latest = Date.UTC(y - MIN_AGE_YEARS, m - 1, d);
+    while (ageInYears(isoOfUtc(latest), now) < MIN_AGE_YEARS)
+        latest -= DAY_MS;
+    let earliest = Date.UTC(y - MAX_AGE_YEARS - 1, m - 1, d);
+    while (ageInYears(isoOfUtc(earliest), now) > MAX_AGE_YEARS)
+        earliest += DAY_MS;
+    return { earliest: isoOfUtc(earliest), latest: isoOfUtc(latest) };
+}
+/**
+ * True only for a COMPLETE, real date of birth that is under `MIN_AGE_YEARS`
+ * today (0.17.0): the rule the server applies to a draft, where a date still
+ * being typed must pass ("19" says nothing about anyone's age yet). Until
+ * 0.17.0 the backend wrote this out by hand and skipped the real-date check.
+ */
+export function isUnderAgeDateOfBirth(value, now = new Date()) {
+    if (typeof value !== 'string' || !isRealIsoDate(value))
+        return false;
+    return ageInYears(value.trim(), now) < MIN_AGE_YEARS;
+}
+/** A `YYYY-MM-DD` as the instant it is stored as: midnight UTC that day (0.17.0). */
+export const isoDateToDate = (iso) => new Date(`${iso.trim()}T00:00:00.000Z`);
+/** A stored date (midnight UTC) as `YYYY-MM-DD` (0.17.0): `isoDateToDate`'s inverse. */
+export const dateToIsoDate = (date) => date.toISOString().slice(0, 10);
 /**
  * Date of birth, with the age gate applied per parse.
  *
@@ -370,6 +424,53 @@ export const TOPIC_CATEGORIES = [
         'education_access',
     ]),
 ];
+// ─── Goals: the grouping the picker renders ──────────────────────────────────
+/**
+ * The goals step's three headings (0.17.0, moved here from the web, where the
+ * grouping lived in the screen): eighteen goals since 0.16.0, shown a group at
+ * a time so the eye takes six tiles, not a wall of eighteen. A group is named
+ * by its `key`, which the client words, like a topic category.
+ *
+ * ⚠ `GOAL_VALUES` stays the single source of truth for what a goal IS; this is
+ * typed against it, and a test holds the two together in both directions:
+ * every goal in exactly one group, nothing in a group that is not a goal.
+ */
+export const GOAL_CATEGORY_KEYS = ['build', 'grow', 'learn'];
+export const GOAL_CATEGORIES = [
+    {
+        key: 'build',
+        values: [
+            'start_company',
+            'get_feedback',
+            'find_cofounder',
+            'find_testers',
+            'hiring',
+            'find_service_providers',
+        ],
+    },
+    {
+        key: 'grow',
+        values: [
+            'find_customers',
+            'find_investors',
+            'partnerships',
+            'market_insights',
+            'business_ideas',
+            'grow_network',
+        ],
+    },
+    {
+        key: 'learn',
+        values: [
+            'learn_startup',
+            'mentorship',
+            'attend_events',
+            'join_startup',
+            'mentor_others',
+            'invest_in_startups',
+        ],
+    },
+];
 /**
  * How many a member must pick. A minimum exists because these drive feed
  * relevance and zero of them means no relevance at all.
@@ -438,8 +539,15 @@ export const ONBOARDING_STEP_KEYS = [
  * profile; that record is the point.
  */
 export const GUIDELINES_VERSION = '2026-10-03';
+/**
+ * Not agreed at all (the box left unticked) is `guidelinesRequired`; agreed to
+ * another text is `guidelinesOutdated` (0.17.0: both were the second, so a
+ * client had to word an unticked box itself).
+ */
 export const guidelinesVersionSchema = z.literal(GUIDELINES_VERSION, {
-    error: VALIDATION_MESSAGE.guidelinesOutdated,
+    error: (issue) => issue.input === undefined || issue.input === null
+        ? VALIDATION_MESSAGE.guidelinesRequired
+        : VALIDATION_MESSAGE.guidelinesOutdated,
 });
 // ─── Contact ─────────────────────────────────────────────────────────────────
 /**
@@ -454,6 +562,12 @@ export const contactLinksSchema = founderLinksSchema.pick({
 });
 /** A team size has at most this many digits: `TEAM_SIZE_MAX` written out. */
 export const TEAM_SIZE_DIGITS_MAX = String(TEAM_SIZE_MAX).length;
+/**
+ * A team size as typed, kept to what the field may hold: digits only, at most
+ * `TEAM_SIZE_DIGITS_MAX` (0.17.0: the draft reader and every client's field
+ * clean it with this one rule).
+ */
+export const teamSizeDigits = (raw) => raw.replace(/\D/g, '').slice(0, TEAM_SIZE_DIGITS_MAX);
 // ─── The form, mid-flight: the draft each step saves ──────────────────────────
 /**
  * The answers so far, keyed by the finish body's own field names: what each
@@ -485,11 +599,16 @@ export const onboardingFormSchema = z.object({
     headline: z.string().max(HEADLINE_MAX),
     about: z.string().max(ABOUT_MAX),
     /**
-     * The completed upload's id (`media`, purpose `avatar`). Allowed in the form,
-     * and NEVER restored by `readOnboardingDraft`: an upload not attached within
-     * `MEDIA_UNATTACHED_TTL_HOURS` is deleted, so an id from an older draft would
-     * fail at Finish, on the last screen, about a photo picked days ago. Clients
-     * hold it for the visit and do not save it.
+     * The completed upload's id (`media`, purpose `avatar`), or `null` for no
+     * photo.
+     *
+     * SAVED BY THE PHOTO STEP, KEPT BY THE SERVER, NOT IN THE DRAFT (0.17.0). A
+     * step save carrying this key hands the upload to the server, which holds it
+     * for the draft (so the unattached sweep, `MEDIA_UNATTACHED_TTL_HOURS`, never
+     * deletes it) and lets go of the one it replaces; `null` lets go of it. It
+     * comes back as the status's `photo`, read from what the server holds, never
+     * from a stored draft: `readOnboardingDraft` still gives `null` here, so an
+     * id an older client left in a draft is never trusted.
      */
     avatarMediaId: objectIdSchema.nullable(),
     skills: z.array(skillSchema).max(SKILLS_MAX),
@@ -587,10 +706,7 @@ const draftReaderSchema = z.object({
         website: draftText(LINK_URL_MAX),
         industry: draftChoice(INDUSTRY_VALUES),
         stage: draftChoice(STARTUP_STAGE_VALUES),
-        teamSize: z
-            .string()
-            .catch('')
-            .transform((v) => v.replace(/\D/g, '').slice(0, TEAM_SIZE_DIGITS_MAX)),
+        teamSize: z.string().catch('').transform(teamSizeDigits),
     }).transform((venture) => venture ?? { ...EMPTY_ONBOARDING_VENTURE }),
     businessType: draftChoice(BUSINESS_TYPE_VALUES),
     legalStructure: draftChoice(LEGAL_STRUCTURE_VALUES),
@@ -615,8 +731,8 @@ export const EMPTY_ONBOARDING_VENTURE = {
  * one that does not fit becomes "not answered" (`''`, `null`, `[]`) and the
  * rest of the draft survives. Never coerced into a different answer: a value
  * outside a vocabulary is dropped, not mapped to the nearest one. A photo
- * is never restored (see `avatarMediaId`), and agreement only counts for the
- * CURRENT guidelines.
+ * is never restored from here (it comes back as the status's `photo`; see
+ * `avatarMediaId`), and agreement only counts for the CURRENT guidelines.
  *
  * It fills in no answer the member did not give: a blank country stays blank.
  * Whatever a screen shows by default is that screen's choice.
@@ -627,23 +743,12 @@ export function readOnboardingDraft(draft) {
 }
 // ─── The finalize body ───────────────────────────────────────────────────────
 /**
- * What the client sends to finish. Completed answers only.
- *
- * ⚠️ EVERY OPTIONAL FIELD HERE MUST BE ABSENT WHEN UNANSWERED, never a default
- * standing in for one. The sibling gym product sent `bloodGroup ?? 'O+'`, so
- * every member who skipped the question was recorded as O-positive: a real
- * answer, indistinguishable from one somebody gave, sitting on a screen staff
- * would read in an emergency. Absent has to stay absent.
- *
- * ⚠️ AND THIS IS NOT THE GATE EITHER. The server re-checks the age and refuses
- * at finalize. `isOnboarded` may be set here and nowhere else: four of the
- * profile's partial indexes are gated on it, so a half-built profile carrying
- * it true appears in Discover half-built.
- *
- * Location, venture and links are the profile's own shapes, not copies: the
- * copies are how the profile model came to lack Instagram.
+ * The finish body's fields, before the rules that span fields: what each
+ * step's slice is PICKED from (Zod 4 refuses `.pick` on a refined object).
+ * Everything outside this file reads `completeOnboardingBodySchema`, whose
+ * note below says what the body is.
  */
-export const completeOnboardingBodySchema = z.object({
+const completeOnboardingBodyFields = z.object({
     // Plain bounds, no custom message: `too_small` with minimum 1 already says
     // "required", and the client words it in the member's language.
     displayName: displayNameSchema,
@@ -674,11 +779,16 @@ export const completeOnboardingBodySchema = z.object({
     avatarMediaId: objectIdSchema.optional(),
     phone: phoneSchema,
     links: contactLinksSchema.optional(),
-    /** Absent when the member skipped the step or refused the permission. */
-    location: locationSchema.optional(),
-    goals: z.array(goalSchema).min(GOALS_MIN).max(GOAL_VALUES.length),
+    /**
+     * Absent when the member skipped the step or refused the permission. In
+     * India, one of its states (0.17.0: `indiaLocationSchema`, the rule the
+     * screen always showed).
+     */
+    location: indiaLocationSchema.optional(),
+    /** The shared list rule (each goal once, 0.17.0) plus finish's minimum. */
+    goals: goalListSchema.min(GOALS_MIN),
     interests: interestsSchema,
-    skills: z.array(skillSchema).max(SKILLS_MAX).optional(),
+    skills: skillListSchema.optional(),
     /**
      * Absent when the member skipped the business step. The profile's venture
      * without `foundedYear`, which onboarding does not ask; the Me tab does.
@@ -698,6 +808,37 @@ export const completeOnboardingBodySchema = z.object({
      */
     guidelinesVersion: guidelinesVersionSchema,
 });
+const typeHasVenture = (body) => body.venture !== undefined || body.businessType === undefined;
+const registrationHasVenture = (body) => body.venture !== undefined || body.legalStructure === undefined;
+const TYPE_NEEDS_VENTURE = { error: VALIDATION_MESSAGE.ventureRequired, path: ['businessType'] };
+const REGISTRATION_NEEDS_VENTURE = {
+    error: VALIDATION_MESSAGE.ventureRequired,
+    path: ['legalStructure'],
+};
+/**
+ * What the client sends to finish. Completed answers only.
+ *
+ * ⚠️ EVERY OPTIONAL FIELD HERE MUST BE ABSENT WHEN UNANSWERED, never a default
+ * standing in for one. The sibling gym product sent `bloodGroup ?? 'O+'`, so
+ * every member who skipped the question was recorded as O-positive: a real
+ * answer, indistinguishable from one somebody gave, sitting on a screen staff
+ * would read in an emergency. Absent has to stay absent.
+ *
+ * ⚠️ AND THIS IS NOT THE GATE EITHER. The server re-checks the age and refuses
+ * at finalize. `isOnboarded` may be set here and nowhere else: four of the
+ * profile's partial indexes are gated on it, so a half-built profile carrying
+ * it true appears in Discover half-built.
+ *
+ * Location, venture and links are the profile's own shapes, not copies: the
+ * copies are how the profile model came to lack Instagram.
+ *
+ * Refined (the business type and registration need a venture, above), so Zod 4
+ * throws on `.pick` / `.omit` / `.partial` / `.merge` of it: read a field with
+ * `.shape.<field>`, a step's with `ONBOARDING_STEP_SCHEMAS.<step>`.
+ */
+export const completeOnboardingBodySchema = completeOnboardingBodyFields
+    .refine(typeHasVenture, TYPE_NEEDS_VENTURE)
+    .refine(registrationHasVenture, REGISTRATION_NEEDS_VENTURE);
 // ─── The steps ───────────────────────────────────────────────────────────────
 /**
  * Each step's slice of the finish body, picked FROM it, so a client validating
@@ -717,32 +858,35 @@ export const ONBOARDING_STEP_SCHEMAS = {
     // 0.16.0: the old `identity` step, split three ways by the user. The basics
     // are the step's only required answers; the photo and the professional
     // details may each be passed over.
-    basics: completeOnboardingBodySchema.pick({ displayName: true, gender: true, dateOfBirth: true }),
-    photo: completeOnboardingBodySchema.pick({ avatarMediaId: true }),
-    professional: completeOnboardingBodySchema.pick({
+    basics: completeOnboardingBodyFields.pick({ displayName: true, gender: true, dateOfBirth: true }),
+    photo: completeOnboardingBodyFields.pick({ avatarMediaId: true }),
+    professional: completeOnboardingBodyFields.pick({
         headline: true,
         about: true,
         // Ruling D8 folded the design's "title, achievements, skills" screen into
         // the profile's first questions; it now has a step of its own again.
         skills: true,
     }),
-    contact: completeOnboardingBodySchema.pick({ phone: true, links: true }),
-    location: completeOnboardingBodySchema.pick({ location: true }),
-    goals: completeOnboardingBodySchema.pick({ goals: true }),
-    interests: completeOnboardingBodySchema.pick({ interests: true }),
-    business: completeOnboardingBodySchema.pick({
+    contact: completeOnboardingBodyFields.pick({ phone: true, links: true }),
+    location: completeOnboardingBodyFields.pick({ location: true }),
+    goals: completeOnboardingBodyFields.pick({ goals: true }),
+    interests: completeOnboardingBodyFields.pick({ interests: true }),
+    business: completeOnboardingBodyFields
+        .pick({
         venture: true,
         businessType: true,
         legalStructure: true,
-    }),
-    guidelines: completeOnboardingBodySchema.pick({ guidelinesVersion: true }),
+    })
+        .refine(typeHasVenture, TYPE_NEEDS_VENTURE)
+        .refine(registrationHasVenture, REGISTRATION_NEEDS_VENTURE),
+    guidelines: completeOnboardingBodyFields.pick({ guidelinesVersion: true }),
 };
 export const FOUNDER_ONBOARDING_STEPS = ONBOARDING_STEP_KEYS.map((key) => {
     const slice = ONBOARDING_STEP_SCHEMAS[key];
     return {
         key,
+        labelKey: `onboarding.steps.${key}.label`,
         titleKey: `onboarding.steps.${key}.title`,
-        helpKey: `onboarding.steps.${key}.help`,
         fields: Object.keys(slice.shape),
         required: !slice.safeParse({}).success,
     };
@@ -791,10 +935,26 @@ export const onboardingProgressSchema = z.object({
  * `PATCH` body: any subset of the cursor, merged server-side. No defaults.
  * `step` may equal `ONBOARDING_TOTAL_STEPS`: "past the last step", which the
  * client sends on its way to finish.
+ *
+ * The draft's values are opaque, but ONE is not kept as typed (0.17.0): the
+ * photo step's `avatarMediaId` is handed to the server, which holds that
+ * upload, so it must be an upload id or `null` like the form's own field.
  */
 export const onboardingProgressUpdateSchema = z.object({
     step: z.number().int().min(0).max(ONBOARDING_TOTAL_STEPS).optional(),
-    draft: onboardingDraftSchema.optional(),
+    draft: onboardingDraftSchema
+        .refine((draft) => !('avatarMediaId' in draft) ||
+        onboardingFormSchema.shape.avatarMediaId.safeParse(draft.avatarMediaId).success, { error: VALIDATION_MESSAGE.invalidId, path: ['avatarMediaId'] })
+        // ...and read as an id is read everywhere (`objectIdSchema`: lower case),
+        // since the server compares it with the upload it already holds: the
+        // same photo sent in capitals was not "the one held", and was refused.
+        .transform((draft) => 'avatarMediaId' in draft
+        ? {
+            ...draft,
+            avatarMediaId: onboardingFormSchema.shape.avatarMediaId.parse(draft.avatarMediaId),
+        }
+        : draft)
+        .optional(),
 });
 /**
  * What the client reads on return, from `GET` and from every `PATCH`.
@@ -808,5 +968,13 @@ export const onboardingStatusSchema = z.object({
     onboarded: z.boolean(),
     step: z.number().int().min(0).max(ONBOARDING_TOTAL_STEPS),
     draft: onboardingDraftSchema.optional(),
+    /**
+     * The photo the member saved on the photo step, as it will appear (0.17.0):
+     * the upload the server holds for this member's draft. Absent when they
+     * saved none, removed it, or have finished. A client resumes the photo step
+     * from this (its `id` is the finish body's `avatarMediaId`), never from the
+     * draft.
+     */
+    photo: mediaImageSchema.optional(),
 });
 //# sourceMappingURL=onboarding.js.map