founder-schema 0.17.0 → 0.19.0

package/dist/domains/location/areas.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Where a member is and where they live: Jansathi's location model (0.19.0)
+ * =========================================================================
+ *
+ * The user, 2026-10-21: Founder Circle takes Jansathi's location drawer
+ * (state, then district, then locality, from `master_db.areas`) and its whole
+ * location model ("just copy paste things from jansathi"). The plan, with the
+ * Jansathi analysis it copies: founder-circle/LOCATION-PLAN-2026-10-21.md.
+ *
+ * Two axes, as in Jansathi, never mixed:
+ * - the DECLARED location (where the member lives): picked in the drawer, or
+ *   filled from GPS by the member, then saved. A client sends AREA IDS only
+ *   (`locationPickSchema`); the server reads the names, the public city and
+ *   the coordinates from `master_db`, so no client can store a place the area
+ *   tree does not have.
+ * - the GPS axis (where the member is): the daily sync and "Use my location"
+ *   send a fix (`geolocationFixSchema`); the server keeps it, the area it
+ *   falls in, and the last `LOCATION_HISTORY_MAX` of each. Nothing on this
+ *   axis is ever shown to another member.
+ *
+ * Area ids are master_db's ObjectIds: stable for the life of the area tree.
+ *
+ * @module domains/location/areas
+ */
+import { z } from 'zod';
+/** The levels of `master_db.areas` a member's location can name. */
+export declare const AREA_TYPE_VALUES: readonly ["COUNTRY", "STATE", "DISTRICT", "SUB_DISTRICT", "BLOCK", "GRAM_PANCHAYAT", "VILLAGE", "URBAN_BODY", "URBAN_WARD"];
+export declare const areaTypeSchema: z.ZodEnum<{
+    COUNTRY: "COUNTRY";
+    STATE: "STATE";
+    DISTRICT: "DISTRICT";
+    SUB_DISTRICT: "SUB_DISTRICT";
+    BLOCK: "BLOCK";
+    GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+    VILLAGE: "VILLAGE";
+    URBAN_BODY: "URBAN_BODY";
+    URBAN_WARD: "URBAN_WARD";
+}>;
+export type AreaType = z.infer<typeof areaTypeSchema>;
+/**
+ * The drawer's third step lists these, everything below a district that a
+ * member can live in: Jansathi's `LOCALITY_TYPE_TO_ADMIN_KEY`, each one a
+ * stored level. Jansathi's drawer also lists HAMLET and LOCALITY and then
+ * refuses them on save (no stored level); here they are never offered.
+ * RURAL_WARD is not offered either (Jansathi neither): it has no point.
+ */
+export declare const LOCALITY_AREA_TYPES: readonly ["SUB_DISTRICT", "BLOCK", "GRAM_PANCHAYAT", "VILLAGE", "URBAN_BODY", "URBAN_WARD"];
+export type LocalityAreaType = (typeof LOCALITY_AREA_TYPES)[number];
+/** How a locality row names its level (Jansathi's `addressForm.areaTypes`). */
+export declare const LOCALITY_TYPE_LABEL: Record<LocalityAreaType, string>;
+/**
+ * An urban body's kind, as the area builder writes it (reform-backend's
+ * `URBAN_BODY_TYPES`, LGD). Read leniently: a kind added there later shows as
+ * "Town or city" rather than breaking the list.
+ */
+export declare const URBAN_BODY_TYPE_VALUES: readonly ["Municipal Corporation", "Municipality", "Notified Area Council", "Town Panchayat", "Nagar Panchayat", "Municipal Council", "NCT Municipal Council", "City Municipal Council", "Town Municipal Council", "Cantonment Board"];
+/** One area as a list row and as part of a place: what a client may show. */
+export declare const areaOptionSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        COUNTRY: "COUNTRY";
+        STATE: "STATE";
+        DISTRICT: "DISTRICT";
+        SUB_DISTRICT: "SUB_DISTRICT";
+        BLOCK: "BLOCK";
+        GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+        VILLAGE: "VILLAGE";
+        URBAN_BODY: "URBAN_BODY";
+        URBAN_WARD: "URBAN_WARD";
+    }>;
+    urbanBodyType: z.ZodOptional<z.ZodString>;
+    within: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AreaOption = z.infer<typeof areaOptionSchema>;
+/**
+ * An area as a member reads it: a ward the tree names by its number alone
+ * ("25") is "Ward 25"; anything else by its name.
+ */
+export declare function areaWords(area: Pick<AreaOption, 'name' | 'type'>): string;
+/** `GET /location/areas/states` and `/districts`: the whole list, sorted by name. */
+export declare const areaListSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            COUNTRY: "COUNTRY";
+            STATE: "STATE";
+            DISTRICT: "DISTRICT";
+            SUB_DISTRICT: "SUB_DISTRICT";
+            BLOCK: "BLOCK";
+            GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+            VILLAGE: "VILLAGE";
+            URBAN_BODY: "URBAN_BODY";
+            URBAN_WARD: "URBAN_WARD";
+        }>;
+        urbanBodyType: z.ZodOptional<z.ZodString>;
+        within: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AreaList = z.infer<typeof areaListSchema>;
+/** `GET /location/areas/localities`: one page (`LOCALITY_PAGE_SIZE`), sorted by name. */
+export declare const areaPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            COUNTRY: "COUNTRY";
+            STATE: "STATE";
+            DISTRICT: "DISTRICT";
+            SUB_DISTRICT: "SUB_DISTRICT";
+            BLOCK: "BLOCK";
+            GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+            VILLAGE: "VILLAGE";
+            URBAN_BODY: "URBAN_BODY";
+            URBAN_WARD: "URBAN_WARD";
+        }>;
+        urbanBodyType: z.ZodOptional<z.ZodString>;
+        within: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+export type AreaPage = z.infer<typeof areaPageSchema>;
+/** `GET /location/areas/districts?stateId=` */
+export declare const districtsQuerySchema: z.ZodObject<{
+    stateId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>;
+export type DistrictsQuery = z.infer<typeof districtsQuerySchema>;
+/**
+ * `GET /location/areas/localities?districtId=&q=&skip=`: every locality level
+ * anywhere inside the district (a ward sits under its town, not under the
+ * district). `q` matches anywhere in the name, as Jansathi's does; an emptied
+ * box is "no search".
+ */
+export declare const localitiesQuerySchema: z.ZodObject<{
+    districtId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    q: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    skip: z.ZodPreprocess<z.ZodDefault<z.ZodCoercedNumber<unknown>>, unknown>;
+}, z.core.$strip>;
+export type LocalitiesQuery = z.infer<typeof localitiesQuerySchema>;
+export type LocalitiesQueryInput = z.input<typeof localitiesQuerySchema>;
+/**
+ * A location as it is WRITTEN (0.19.0): onboarding's finish and Me's personal
+ * details. Ids only. `localityId: null` is the member's "my locality is not
+ * listed": the whole district (the user's choice, 2026-10-21).
+ *
+ * The server refuses ids that are not one chain (a district outside the
+ * state, a locality outside the district) and a state Founder Circle's list
+ * does not name (`findIndiaState`).
+ */
+export declare const locationPickSchema: z.ZodObject<{
+    stateId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    districtId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    localityId: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+export type LocationPick = z.infer<typeof locationPickSchema>;
+/**
+ * A place with its names: the member's own location as Me reads it back, the
+ * area GPS matched, and the onboarding draft. What the location field shows
+ * ("Locality, District, State") and where the drawer reopens. Owner-only:
+ * other members read `locationSchema` (city, state, country).
+ */
+export declare const placeSchema: z.ZodObject<{
+    state: z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            COUNTRY: "COUNTRY";
+            STATE: "STATE";
+            DISTRICT: "DISTRICT";
+            SUB_DISTRICT: "SUB_DISTRICT";
+            BLOCK: "BLOCK";
+            GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+            VILLAGE: "VILLAGE";
+            URBAN_BODY: "URBAN_BODY";
+            URBAN_WARD: "URBAN_WARD";
+        }>;
+        urbanBodyType: z.ZodOptional<z.ZodString>;
+        within: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    district: z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            COUNTRY: "COUNTRY";
+            STATE: "STATE";
+            DISTRICT: "DISTRICT";
+            SUB_DISTRICT: "SUB_DISTRICT";
+            BLOCK: "BLOCK";
+            GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+            VILLAGE: "VILLAGE";
+            URBAN_BODY: "URBAN_BODY";
+            URBAN_WARD: "URBAN_WARD";
+        }>;
+        urbanBodyType: z.ZodOptional<z.ZodString>;
+        within: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    locality: z.ZodNullable<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            COUNTRY: "COUNTRY";
+            STATE: "STATE";
+            DISTRICT: "DISTRICT";
+            SUB_DISTRICT: "SUB_DISTRICT";
+            BLOCK: "BLOCK";
+            GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+            VILLAGE: "VILLAGE";
+            URBAN_BODY: "URBAN_BODY";
+            URBAN_WARD: "URBAN_WARD";
+        }>;
+        urbanBodyType: z.ZodOptional<z.ZodString>;
+        within: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Place = z.infer<typeof placeSchema>;
+/** The pick a place is (what saving it sends). */
+export declare function pickOfPlace(place: Place): LocationPick;
+/**
+ * "Locality, what it sits in, District, State", the deepest first; a name
+ * repeated is said once ("Ward 25, Bassi, Jaipur, Rajasthan"; "Rajpur,
+ * Dehradun, Uttarakhand").
+ */
+export declare function placeWords(place: Place): string;
+/**
+ * `POST /me/geolocation`: one GPS fix, from the daily sync or a member's
+ * "Use my location" (Jansathi's body). Plain degrees, accuracy in metres. A
+ * fix coarser than `GEO_ACCURACY_MAX_M` is refused: it cannot name a place.
+ */
+export declare const geolocationFixSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    accuracy: z.ZodNumber;
+}, z.core.$strict>;
+export type GeolocationFix = z.infer<typeof geolocationFixSchema>;
+/**
+ * The answer: the place the fix falls in, for "Use my location" to put in the
+ * field (the member still saves it), or `null` when the area tree has no
+ * confident match (outside India, or nothing within reach). The daily sync
+ * ignores it. Never the coordinates themselves.
+ */
+export declare const geolocationSyncResultSchema: z.ZodObject<{
+    synced: z.ZodLiteral<true>;
+    match: z.ZodNullable<z.ZodObject<{
+        state: z.ZodObject<{
+            id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                COUNTRY: "COUNTRY";
+                STATE: "STATE";
+                DISTRICT: "DISTRICT";
+                SUB_DISTRICT: "SUB_DISTRICT";
+                BLOCK: "BLOCK";
+                GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+                VILLAGE: "VILLAGE";
+                URBAN_BODY: "URBAN_BODY";
+                URBAN_WARD: "URBAN_WARD";
+            }>;
+            urbanBodyType: z.ZodOptional<z.ZodString>;
+            within: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        district: z.ZodObject<{
+            id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                COUNTRY: "COUNTRY";
+                STATE: "STATE";
+                DISTRICT: "DISTRICT";
+                SUB_DISTRICT: "SUB_DISTRICT";
+                BLOCK: "BLOCK";
+                GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+                VILLAGE: "VILLAGE";
+                URBAN_BODY: "URBAN_BODY";
+                URBAN_WARD: "URBAN_WARD";
+            }>;
+            urbanBodyType: z.ZodOptional<z.ZodString>;
+            within: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        locality: z.ZodNullable<z.ZodObject<{
+            id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                COUNTRY: "COUNTRY";
+                STATE: "STATE";
+                DISTRICT: "DISTRICT";
+                SUB_DISTRICT: "SUB_DISTRICT";
+                BLOCK: "BLOCK";
+                GRAM_PANCHAYAT: "GRAM_PANCHAYAT";
+                VILLAGE: "VILLAGE";
+                URBAN_BODY: "URBAN_BODY";
+                URBAN_WARD: "URBAN_WARD";
+            }>;
+            urbanBodyType: z.ZodOptional<z.ZodString>;
+            within: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GeolocationSyncResult = z.infer<typeof geolocationSyncResultSchema>;
+/**
+ * Whether Founder Circle keeps the member's positions (the user, 2026-10-22:
+ * "Add stop + clear", India's DPDP right to withdraw consent). On by default,
+ * as Jansathi; it only matters once the browser allows location at all.
+ *
+ * OFF: the server keeps NO position: a fix (the daily check or a tap on "Use
+ * my location") is still answered with the place it falls in, so the field can
+ * be filled, but nothing of it is stored, and no history row is written, not
+ * even for a saved place. The web stops the daily check. The member's chosen
+ * place is not touched: removing it is the location field's Remove.
+ *
+ * `GET /api/v1/me/location-settings`, and `PATCH` with
+ * `updateLocationSettingsBodySchema`, both answer this.
+ */
+export declare const locationSettingsSchema: z.ZodObject<{
+    dailyLocation: z.ZodBoolean;
+}, z.core.$strip>;
+export type LocationSettings = z.infer<typeof locationSettingsSchema>;
+/** `PATCH /api/v1/me/location-settings` */
+export declare const updateLocationSettingsBodySchema: z.ZodObject<{
+    dailyLocation: z.ZodBoolean;
+}, z.core.$strict>;
+export type UpdateLocationSettingsBody = z.infer<typeof updateLocationSettingsBodySchema>;
+/**
+ * `DELETE /api/v1/me/location-history`: every position and area the member's
+ * device sent, and the position kept with their saved place, deleted at once.
+ * The chosen place itself (what others see as city and state) stays.
+ */
+export declare const clearLocationHistoryResultSchema: z.ZodObject<{
+    cleared: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type ClearLocationHistoryResult = z.infer<typeof clearLocationHistoryResultSchema>;
+//# sourceMappingURL=areas.d.ts.map

package/dist/domains/location/areas.d.ts.map

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

package/dist/domains/location/areas.js

@@ -0,0 +1,238 @@
+/**
+ * Where a member is and where they live: Jansathi's location model (0.19.0)
+ * =========================================================================
+ *
+ * The user, 2026-10-21: Founder Circle takes Jansathi's location drawer
+ * (state, then district, then locality, from `master_db.areas`) and its whole
+ * location model ("just copy paste things from jansathi"). The plan, with the
+ * Jansathi analysis it copies: founder-circle/LOCATION-PLAN-2026-10-21.md.
+ *
+ * Two axes, as in Jansathi, never mixed:
+ * - the DECLARED location (where the member lives): picked in the drawer, or
+ *   filled from GPS by the member, then saved. A client sends AREA IDS only
+ *   (`locationPickSchema`); the server reads the names, the public city and
+ *   the coordinates from `master_db`, so no client can store a place the area
+ *   tree does not have.
+ * - the GPS axis (where the member is): the daily sync and "Use my location"
+ *   send a fix (`geolocationFixSchema`); the server keeps it, the area it
+ *   falls in, and the last `LOCATION_HISTORY_MAX` of each. Nothing on this
+ *   axis is ever shown to another member.
+ *
+ * Area ids are master_db's ObjectIds: stable for the life of the area tree.
+ *
+ * @module domains/location/areas
+ */
+import { z } from 'zod';
+import { emptyStringToUndefined, objectIdSchema, queryInt } from '../../core/common.js';
+import { AREA_NAME_MAX, AREA_SEARCH_MAX, GEO_ACCURACY_MAX_M, LOCALITY_SKIP_MAX, } from '../../core/limits.js';
+import { VALIDATION_MESSAGE } from '../../core/validation.js';
+// ─── The area tree ───────────────────────────────────────────────────────────
+/** The levels of `master_db.areas` a member's location can name. */
+export const AREA_TYPE_VALUES = [
+    'COUNTRY',
+    'STATE',
+    'DISTRICT',
+    'SUB_DISTRICT',
+    'BLOCK',
+    'GRAM_PANCHAYAT',
+    'VILLAGE',
+    'URBAN_BODY',
+    'URBAN_WARD',
+];
+export const areaTypeSchema = z.enum(AREA_TYPE_VALUES);
+/**
+ * The drawer's third step lists these, everything below a district that a
+ * member can live in: Jansathi's `LOCALITY_TYPE_TO_ADMIN_KEY`, each one a
+ * stored level. Jansathi's drawer also lists HAMLET and LOCALITY and then
+ * refuses them on save (no stored level); here they are never offered.
+ * RURAL_WARD is not offered either (Jansathi neither): it has no point.
+ */
+export const LOCALITY_AREA_TYPES = [
+    'SUB_DISTRICT',
+    'BLOCK',
+    'GRAM_PANCHAYAT',
+    'VILLAGE',
+    'URBAN_BODY',
+    'URBAN_WARD',
+];
+/** How a locality row names its level (Jansathi's `addressForm.areaTypes`). */
+export const LOCALITY_TYPE_LABEL = {
+    SUB_DISTRICT: 'Tehsil',
+    BLOCK: 'Block',
+    GRAM_PANCHAYAT: 'Gram Panchayat',
+    VILLAGE: 'Village',
+    URBAN_BODY: 'Town or city',
+    URBAN_WARD: 'Ward',
+};
+/**
+ * An urban body's kind, as the area builder writes it (reform-backend's
+ * `URBAN_BODY_TYPES`, LGD). Read leniently: a kind added there later shows as
+ * "Town or city" rather than breaking the list.
+ */
+export const URBAN_BODY_TYPE_VALUES = [
+    'Municipal Corporation',
+    'Municipality',
+    'Notified Area Council',
+    'Town Panchayat',
+    'Nagar Panchayat',
+    'Municipal Council',
+    'NCT Municipal Council',
+    'City Municipal Council',
+    'Town Municipal Council',
+    'Cantonment Board',
+];
+/** One area as a list row and as part of a place: what a client may show. */
+export const areaOptionSchema = z.object({
+    id: objectIdSchema,
+    name: z.string().trim().min(1).max(AREA_NAME_MAX),
+    type: areaTypeSchema,
+    /** Only on an URBAN_BODY, when the tree knows its kind. */
+    urbanBodyType: z.string().trim().min(1).max(AREA_NAME_MAX).optional(),
+    /**
+     * What a locality sits in, to tell same-named places apart (0.19.0, the
+     * review: one district has 12 villages called "Pali", a town's wards are
+     * named "1" to "35"): a ward's town, a village's or panchayat's tehsil or
+     * block. Absent on states, districts and towns.
+     */
+    within: z.string().trim().min(1).max(AREA_NAME_MAX).optional(),
+});
+/**
+ * An area as a member reads it: a ward the tree names by its number alone
+ * ("25") is "Ward 25"; anything else by its name.
+ */
+export function areaWords(area) {
+    return area.type === 'URBAN_WARD' && /^\d+$/.test(area.name.trim())
+        ? `Ward ${area.name.trim()}`
+        : area.name;
+}
+/** `GET /location/areas/states` and `/districts`: the whole list, sorted by name. */
+export const areaListSchema = z.object({ items: z.array(areaOptionSchema) });
+/** `GET /location/areas/localities`: one page (`LOCALITY_PAGE_SIZE`), sorted by name. */
+export const areaPageSchema = z.object({
+    items: z.array(areaOptionSchema),
+    hasMore: z.boolean(),
+});
+/** `GET /location/areas/districts?stateId=` */
+export const districtsQuerySchema = z.object({ stateId: objectIdSchema });
+/**
+ * `GET /location/areas/localities?districtId=&q=&skip=`: every locality level
+ * anywhere inside the district (a ward sits under its town, not under the
+ * district). `q` matches anywhere in the name, as Jansathi's does; an emptied
+ * box is "no search".
+ */
+export const localitiesQuerySchema = z.object({
+    districtId: objectIdSchema,
+    q: z.preprocess(emptyStringToUndefined, z.string().trim().max(AREA_SEARCH_MAX).optional()),
+    skip: queryInt(0, LOCALITY_SKIP_MAX, 0),
+});
+// ─── The declared location ───────────────────────────────────────────────────
+/** An area id a picker must have chosen: unchosen is worded as a choice. */
+const chosenAreaId = (unchosen) => z
+    .string({ error: unchosen })
+    .min(1, { error: unchosen, abort: true })
+    .regex(/^[0-9a-f]{24}$/i, VALIDATION_MESSAGE.invalidId)
+    .transform((v) => v.toLowerCase());
+/**
+ * A location as it is WRITTEN (0.19.0): onboarding's finish and Me's personal
+ * details. Ids only. `localityId: null` is the member's "my locality is not
+ * listed": the whole district (the user's choice, 2026-10-21).
+ *
+ * The server refuses ids that are not one chain (a district outside the
+ * state, a locality outside the district) and a state Founder Circle's list
+ * does not name (`findIndiaState`).
+ */
+export const locationPickSchema = z
+    .object({
+    stateId: chosenAreaId(VALIDATION_MESSAGE.stateRequired),
+    districtId: chosenAreaId(VALIDATION_MESSAGE.districtRequired),
+    // Said explicitly: an id, or `null` for the whole district. Left out is a
+    // choice not made (`localityRequired`), never Zod's own English.
+    localityId: z
+        .string({ error: VALIDATION_MESSAGE.localityRequired })
+        .regex(/^[0-9a-f]{24}$/i, VALIDATION_MESSAGE.invalidId)
+        .transform((v) => v.toLowerCase())
+        .nullable(),
+})
+    .strict();
+/**
+ * A place with its names: the member's own location as Me reads it back, the
+ * area GPS matched, and the onboarding draft. What the location field shows
+ * ("Locality, District, State") and where the drawer reopens. Owner-only:
+ * other members read `locationSchema` (city, state, country).
+ */
+export const placeSchema = z.object({
+    state: areaOptionSchema,
+    district: areaOptionSchema,
+    /** `null`: the whole district. */
+    locality: areaOptionSchema.nullable(),
+});
+/** The pick a place is (what saving it sends). */
+export function pickOfPlace(place) {
+    return {
+        stateId: place.state.id,
+        districtId: place.district.id,
+        localityId: place.locality?.id ?? null,
+    };
+}
+/**
+ * "Locality, what it sits in, District, State", the deepest first; a name
+ * repeated is said once ("Ward 25, Bassi, Jaipur, Rajasthan"; "Rajpur,
+ * Dehradun, Uttarakhand").
+ */
+export function placeWords(place) {
+    const parts = [
+        place.locality ? areaWords(place.locality) : undefined,
+        place.locality?.within,
+        place.district.name,
+        place.state.name,
+    ].filter((p) => Boolean(p));
+    return parts.filter((p, i) => parts.indexOf(p) === i).join(', ');
+}
+// ─── The GPS axis ────────────────────────────────────────────────────────────
+/**
+ * `POST /me/geolocation`: one GPS fix, from the daily sync or a member's
+ * "Use my location" (Jansathi's body). Plain degrees, accuracy in metres. A
+ * fix coarser than `GEO_ACCURACY_MAX_M` is refused: it cannot name a place.
+ */
+export const geolocationFixSchema = z
+    .object({
+    latitude: z.number().min(-90).max(90),
+    longitude: z.number().min(-180).max(180),
+    accuracy: z.number().min(0).max(GEO_ACCURACY_MAX_M),
+})
+    .strict();
+/**
+ * The answer: the place the fix falls in, for "Use my location" to put in the
+ * field (the member still saves it), or `null` when the area tree has no
+ * confident match (outside India, or nothing within reach). The daily sync
+ * ignores it. Never the coordinates themselves.
+ */
+export const geolocationSyncResultSchema = z.object({
+    synced: z.literal(true),
+    match: placeSchema.nullable(),
+});
+// ─── The member's own control (0.19.0) ───────────────────────────────────────
+/**
+ * Whether Founder Circle keeps the member's positions (the user, 2026-10-22:
+ * "Add stop + clear", India's DPDP right to withdraw consent). On by default,
+ * as Jansathi; it only matters once the browser allows location at all.
+ *
+ * OFF: the server keeps NO position: a fix (the daily check or a tap on "Use
+ * my location") is still answered with the place it falls in, so the field can
+ * be filled, but nothing of it is stored, and no history row is written, not
+ * even for a saved place. The web stops the daily check. The member's chosen
+ * place is not touched: removing it is the location field's Remove.
+ *
+ * `GET /api/v1/me/location-settings`, and `PATCH` with
+ * `updateLocationSettingsBodySchema`, both answer this.
+ */
+export const locationSettingsSchema = z.object({ dailyLocation: z.boolean() });
+/** `PATCH /api/v1/me/location-settings` */
+export const updateLocationSettingsBodySchema = z.object({ dailyLocation: z.boolean() }).strict();
+/**
+ * `DELETE /api/v1/me/location-history`: every position and area the member's
+ * device sent, and the position kept with their saved place, deleted at once.
+ * The chosen place itself (what others see as city and state) stays.
+ */
+export const clearLocationHistoryResultSchema = z.object({ cleared: z.literal(true) });
+//# sourceMappingURL=areas.js.map

package/dist/domains/location/areas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"areas.js","sourceRoot":"","sources":["../../../src/domains/location/areas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where a member is and where they live: Jansathi's location model (0.19.0)\n * =========================================================================\n *\n * The user, 2026-10-21: Founder Circle takes Jansathi's location drawer\n * (state, then district, then locality, from `master_db.areas`) and its whole\n * location model (\"just copy paste things from jansathi\"). The plan, with the\n * Jansathi analysis it copies: founder-circle/LOCATION-PLAN-2026-10-21.md.\n *\n * Two axes, as in Jansathi, never mixed:\n * - the DECLARED location (where the member lives): picked in the drawer, or\n *   filled from GPS by the member, then saved. A client sends AREA IDS only\n *   (`locationPickSchema`); the server reads the names, the public city and\n *   the coordinates from `master_db`, so no client can store a place the area\n *   tree does not have.\n * - the GPS axis (where the member is): the daily sync and \"Use my location\"\n *   send a fix (`geolocationFixSchema`); the server keeps it, the area it\n *   falls in, and the last `LOCATION_HISTORY_MAX` of each. Nothing on this\n *   axis is ever shown to another member.\n *\n * Area ids are master_db's ObjectIds: stable for the life of the area tree.\n *\n * @module domains/location/areas\n */\n\nimport { z } from 'zod';\nimport { emptyStringToUndefined, objectIdSchema, queryInt } from '../../core/common.js';\nimport {\n  AREA_NAME_MAX,\n  AREA_SEARCH_MAX,\n  GEO_ACCURACY_MAX_M,\n  LOCALITY_SKIP_MAX,\n} from '../../core/limits.js';\nimport { VALIDATION_MESSAGE } from '../../core/validation.js';\n\n// ─── The area tree ───────────────────────────────────────────────────────────\n\n/** The levels of `master_db.areas` a member's location can name. */\nexport const AREA_TYPE_VALUES = [\n  'COUNTRY',\n  'STATE',\n  'DISTRICT',\n  'SUB_DISTRICT',\n  'BLOCK',\n  'GRAM_PANCHAYAT',\n  'VILLAGE',\n  'URBAN_BODY',\n  'URBAN_WARD',\n] as const;\nexport const areaTypeSchema = z.enum(AREA_TYPE_VALUES);\nexport type AreaType = z.infer<typeof areaTypeSchema>;\n\n/**\n * The drawer's third step lists these, everything below a district that a\n * member can live in: Jansathi's `LOCALITY_TYPE_TO_ADMIN_KEY`, each one a\n * stored level. Jansathi's drawer also lists HAMLET and LOCALITY and then\n * refuses them on save (no stored level); here they are never offered.\n * RURAL_WARD is not offered either (Jansathi neither): it has no point.\n */\nexport const LOCALITY_AREA_TYPES = [\n  'SUB_DISTRICT',\n  'BLOCK',\n  'GRAM_PANCHAYAT',\n  'VILLAGE',\n  'URBAN_BODY',\n  'URBAN_WARD',\n] as const satisfies readonly AreaType[];\nexport type LocalityAreaType = (typeof LOCALITY_AREA_TYPES)[number];\n\n/** How a locality row names its level (Jansathi's `addressForm.areaTypes`). */\nexport const LOCALITY_TYPE_LABEL: Record<LocalityAreaType, string> = {\n  SUB_DISTRICT: 'Tehsil',\n  BLOCK: 'Block',\n  GRAM_PANCHAYAT: 'Gram Panchayat',\n  VILLAGE: 'Village',\n  URBAN_BODY: 'Town or city',\n  URBAN_WARD: 'Ward',\n};\n\n/**\n * An urban body's kind, as the area builder writes it (reform-backend's\n * `URBAN_BODY_TYPES`, LGD). Read leniently: a kind added there later shows as\n * \"Town or city\" rather than breaking the list.\n */\nexport const URBAN_BODY_TYPE_VALUES = [\n  'Municipal Corporation',\n  'Municipality',\n  'Notified Area Council',\n  'Town Panchayat',\n  'Nagar Panchayat',\n  'Municipal Council',\n  'NCT Municipal Council',\n  'City Municipal Council',\n  'Town Municipal Council',\n  'Cantonment Board',\n] as const;\n\n/** One area as a list row and as part of a place: what a client may show. */\nexport const areaOptionSchema = z.object({\n  id: objectIdSchema,\n  name: z.string().trim().min(1).max(AREA_NAME_MAX),\n  type: areaTypeSchema,\n  /** Only on an URBAN_BODY, when the tree knows its kind. */\n  urbanBodyType: z.string().trim().min(1).max(AREA_NAME_MAX).optional(),\n  /**\n   * What a locality sits in, to tell same-named places apart (0.19.0, the\n   * review: one district has 12 villages called \"Pali\", a town's wards are\n   * named \"1\" to \"35\"): a ward's town, a village's or panchayat's tehsil or\n   * block. Absent on states, districts and towns.\n   */\n  within: z.string().trim().min(1).max(AREA_NAME_MAX).optional(),\n});\nexport type AreaOption = z.infer<typeof areaOptionSchema>;\n\n/**\n * An area as a member reads it: a ward the tree names by its number alone\n * (\"25\") is \"Ward 25\"; anything else by its name.\n */\nexport function areaWords(area: Pick<AreaOption, 'name' | 'type'>): string {\n  return area.type === 'URBAN_WARD' && /^\\d+$/.test(area.name.trim())\n    ? `Ward ${area.name.trim()}`\n    : area.name;\n}\n\n/** `GET /location/areas/states` and `/districts`: the whole list, sorted by name. */\nexport const areaListSchema = z.object({ items: z.array(areaOptionSchema) });\nexport type AreaList = z.infer<typeof areaListSchema>;\n\n/** `GET /location/areas/localities`: one page (`LOCALITY_PAGE_SIZE`), sorted by name. */\nexport const areaPageSchema = z.object({\n  items: z.array(areaOptionSchema),\n  hasMore: z.boolean(),\n});\nexport type AreaPage = z.infer<typeof areaPageSchema>;\n\n/** `GET /location/areas/districts?stateId=` */\nexport const districtsQuerySchema = z.object({ stateId: objectIdSchema });\nexport type DistrictsQuery = z.infer<typeof districtsQuerySchema>;\n\n/**\n * `GET /location/areas/localities?districtId=&q=&skip=`: every locality level\n * anywhere inside the district (a ward sits under its town, not under the\n * district). `q` matches anywhere in the name, as Jansathi's does; an emptied\n * box is \"no search\".\n */\nexport const localitiesQuerySchema = z.object({\n  districtId: objectIdSchema,\n  q: z.preprocess(emptyStringToUndefined, z.string().trim().max(AREA_SEARCH_MAX).optional()),\n  skip: queryInt(0, LOCALITY_SKIP_MAX, 0),\n});\nexport type LocalitiesQuery = z.infer<typeof localitiesQuerySchema>;\nexport type LocalitiesQueryInput = z.input<typeof localitiesQuerySchema>;\n\n// ─── The declared location ───────────────────────────────────────────────────\n\n/** An area id a picker must have chosen: unchosen is worded as a choice. */\nconst chosenAreaId = (unchosen: string) =>\n  z\n    .string({ error: unchosen })\n    .min(1, { error: unchosen, abort: true })\n    .regex(/^[0-9a-f]{24}$/i, VALIDATION_MESSAGE.invalidId)\n    .transform((v) => v.toLowerCase());\n\n/**\n * A location as it is WRITTEN (0.19.0): onboarding's finish and Me's personal\n * details. Ids only. `localityId: null` is the member's \"my locality is not\n * listed\": the whole district (the user's choice, 2026-10-21).\n *\n * The server refuses ids that are not one chain (a district outside the\n * state, a locality outside the district) and a state Founder Circle's list\n * does not name (`findIndiaState`).\n */\nexport const locationPickSchema = z\n  .object({\n    stateId: chosenAreaId(VALIDATION_MESSAGE.stateRequired),\n    districtId: chosenAreaId(VALIDATION_MESSAGE.districtRequired),\n    // Said explicitly: an id, or `null` for the whole district. Left out is a\n    // choice not made (`localityRequired`), never Zod's own English.\n    localityId: z\n      .string({ error: VALIDATION_MESSAGE.localityRequired })\n      .regex(/^[0-9a-f]{24}$/i, VALIDATION_MESSAGE.invalidId)\n      .transform((v) => v.toLowerCase())\n      .nullable(),\n  })\n  .strict();\nexport type LocationPick = z.infer<typeof locationPickSchema>;\n\n/**\n * A place with its names: the member's own location as Me reads it back, the\n * area GPS matched, and the onboarding draft. What the location field shows\n * (\"Locality, District, State\") and where the drawer reopens. Owner-only:\n * other members read `locationSchema` (city, state, country).\n */\nexport const placeSchema = z.object({\n  state: areaOptionSchema,\n  district: areaOptionSchema,\n  /** `null`: the whole district. */\n  locality: areaOptionSchema.nullable(),\n});\nexport type Place = z.infer<typeof placeSchema>;\n\n/** The pick a place is (what saving it sends). */\nexport function pickOfPlace(place: Place): LocationPick {\n  return {\n    stateId: place.state.id,\n    districtId: place.district.id,\n    localityId: place.locality?.id ?? null,\n  };\n}\n\n/**\n * \"Locality, what it sits in, District, State\", the deepest first; a name\n * repeated is said once (\"Ward 25, Bassi, Jaipur, Rajasthan\"; \"Rajpur,\n * Dehradun, Uttarakhand\").\n */\nexport function placeWords(place: Place): string {\n  const parts = [\n    place.locality ? areaWords(place.locality) : undefined,\n    place.locality?.within,\n    place.district.name,\n    place.state.name,\n  ].filter((p): p is string => Boolean(p));\n  return parts.filter((p, i) => parts.indexOf(p) === i).join(', ');\n}\n\n// ─── The GPS axis ────────────────────────────────────────────────────────────\n\n/**\n * `POST /me/geolocation`: one GPS fix, from the daily sync or a member's\n * \"Use my location\" (Jansathi's body). Plain degrees, accuracy in metres. A\n * fix coarser than `GEO_ACCURACY_MAX_M` is refused: it cannot name a place.\n */\nexport const geolocationFixSchema = z\n  .object({\n    latitude: z.number().min(-90).max(90),\n    longitude: z.number().min(-180).max(180),\n    accuracy: z.number().min(0).max(GEO_ACCURACY_MAX_M),\n  })\n  .strict();\nexport type GeolocationFix = z.infer<typeof geolocationFixSchema>;\n\n/**\n * The answer: the place the fix falls in, for \"Use my location\" to put in the\n * field (the member still saves it), or `null` when the area tree has no\n * confident match (outside India, or nothing within reach). The daily sync\n * ignores it. Never the coordinates themselves.\n */\nexport const geolocationSyncResultSchema = z.object({\n  synced: z.literal(true),\n  match: placeSchema.nullable(),\n});\nexport type GeolocationSyncResult = z.infer<typeof geolocationSyncResultSchema>;\n\n// ─── The member's own control (0.19.0) ───────────────────────────────────────\n\n/**\n * Whether Founder Circle keeps the member's positions (the user, 2026-10-22:\n * \"Add stop + clear\", India's DPDP right to withdraw consent). On by default,\n * as Jansathi; it only matters once the browser allows location at all.\n *\n * OFF: the server keeps NO position: a fix (the daily check or a tap on \"Use\n * my location\") is still answered with the place it falls in, so the field can\n * be filled, but nothing of it is stored, and no history row is written, not\n * even for a saved place. The web stops the daily check. The member's chosen\n * place is not touched: removing it is the location field's Remove.\n *\n * `GET /api/v1/me/location-settings`, and `PATCH` with\n * `updateLocationSettingsBodySchema`, both answer this.\n */\nexport const locationSettingsSchema = z.object({ dailyLocation: z.boolean() });\nexport type LocationSettings = z.infer<typeof locationSettingsSchema>;\n\n/** `PATCH /api/v1/me/location-settings` */\nexport const updateLocationSettingsBodySchema = z.object({ dailyLocation: z.boolean() }).strict();\nexport type UpdateLocationSettingsBody = z.infer<typeof updateLocationSettingsBodySchema>;\n\n/**\n * `DELETE /api/v1/me/location-history`: every position and area the member's\n * device sent, and the position kept with their saved place, deleted at once.\n * The chosen place itself (what others see as city and state) stays.\n */\nexport const clearLocationHistoryResultSchema = z.object({ cleared: z.literal(true) });\nexport type ClearLocationHistoryResult = z.infer<typeof clearLocationHistoryResultSchema>;\n"]}