founder-schema 0.1.0 → 0.2.0

package/README.md

@@ -20,56 +20,116 @@ the package is right and the consumer is the bug.
 
 Consumed by:
 
-| Repo | What it uses today |
+| Repo | What it uses |
 |---|---|
-| `founder-circle-backend` | The four enum arrays and `USERNAME_MAX`, as Mongoose `enum` and `maxlength` constraints |
-| `founder-circle-web-client` | Nothing yet |
+| `founder-circle-backend` | Every write body to validate requests, the enums and limits as Mongoose constraints, `toValidationIssues` for every 400 |
+| `founder-circle-web-client` | The same write bodies for its forms, the limits for counters, the read shapes for what comes back |
 
 ---
 
-## Using it in a consumer, before the first publish
+## Installing it
 
-**This package is not on npm.** The name and the first publish are the user's
-decision and have not been made, so there is nothing to `npm install` yet.
-
-The interim path is the one TEAM.md documents: build this package, then copy its
-`dist/` into the consumer's `node_modules`. The backend already has a script that
-does exactly that.
+On npm since 0.1.0. Pin the EXACT version, with `-E` so npm writes `0.2.0` and
+not `^0.2.0` (a caret on `0.x` pins the minor; see Publishing):
 
 ```sh
-# 1. build here
-cd founder-circle-schema
-npm install
-npm run build
-
-# 2. link it into the consumer
-cd ../founder-circle-backend
-npm run schema:link
+npm install -E founder-schema@0.2.0
 ```
 
-**A fresh clone has no build.** `dist/` is gitignored, which is right for a
-package that ships a build artifact to npm rather than to git, but it means
-`npm run schema:link` fails on a clone until `npm run build` has been run here at
-least once. That is the first step above and it is not optional. The link script
-checks for `dist/index.js` and tells you so rather than copying an empty folder.
-
-Three things about that link, each of which has bitten this family of repos:
+**Working against a change that is not published yet** is the path TEAM.md
+documents: build here, copy `dist/` over the consumer's
+`node_modules/founder-schema/dist/`, and commit nothing that pins the new version
+until it is on npm.
 
-- **Re-run `npm run schema:link` after every `npm install` in the consumer.** npm
-  prunes packages it has no record of, so an install silently deletes the link and
-  the next type-check fails on imports that were fine an hour ago.
+- **Any `npm install` in the consumer undoes the copy.** npm restores what its
+  lockfile names, and the next type-check fails on imports that were fine an hour
+  ago. Copy again after every install.
 - **Never use `file:../` in a consumer's `package.json`.** A path link resolves to
-  a different copy than a Docker build or a CI checkout sees, and it drags in a
-  second Zod, which breaks `instanceof` checks in ways that look like random
-  validation failures.
+  a different copy than a Docker build sees, and it drags in a second Zod, which
+  breaks `instanceof` checks in ways that look like random validation failures.
 - **Never commit a consumer whose `package.json` pins a version that is not on
   npm.** The pin has to follow the publish, never lead it.
 
+---
+
+## Validation: one set of rules, both sides (0.2.0)
+
+The backend validates a request and the web client validates a form with the
+SAME schema object, so the two can never disagree about what is allowed.
+
+- **Every limit has a name** (`src/limits.ts`: `DISPLAY_NAME_MAX`,
+  `LINK_URL_MAX`, `UPLOAD_MAX_BYTES`...). A schema uses the constant; a consumer
+  imports the same constant for its counters or its Mongoose `maxlength`. Nobody
+  types the digits again. Three copies of one number is how image alt text came
+  to be 280 here and 500 in the backend.
+- **A custom message is a KEY, never a sentence** (`VALIDATION_MESSAGE`:
+  `phoneInvalid`, `dobUnderAge`...). The client words it in English or Hindi.
+  Plain bounds carry no message at all: Zod's own `too_small` / `too_big` issue
+  already says which bound and what it was. A test fails if a sentence creeps back.
+- **A 400 carries every issue** in `error.details.issues`, each with its `path`,
+  built by `toValidationIssues`. ⚠️ That helper copies a whitelist and never the
+  rejected `input`: these bodies hold a date of birth and a phone number. A test
+  forces Zod to attach the input and proves it does not leave.
+- **Every issue says where it is**: `location` is `body`, `query` or `params`,
+  and `path` is relative to it (`['venture', 'name']`, never
+  `['body', 'venture', 'name']`).
+- **Every error has a code from `API_ERROR_CODE_VALUES`.** A schema failure is
+  `VALIDATION_ERROR` with issues; a refusal by the state of things (a closed
+  poll, the edit window) has its own code. The client words the code; the
+  English `message` is for logs.
+- **Every request part and every response has a schema here**: bodies, queries
+  (with `...Input` types for building URLs), route params (`contentParamsSchema`,
+  `engagementTargetParamsSchema`...), pages (`feedPageSchema`,
+  `discoverPageSchema`...), mutations (`idResponseSchema`). The backend builds
+  each response `satisfies` its type and tests it with its schema.
+- **Onboarding validates a step with its slice of the finish**
+  (`ONBOARDING_STEP_SCHEMAS`), so a step the wizard lets through is a step the
+  finish accepts. The step list (`FOUNDER_ONBOARDING_STEPS`) is built from those
+  slices, including whether a step may be skipped.
+- **No copy.** Step titles, help lines and topic categories are translation keys
+  (`titleKey`, `helpKey`, `labelKey`); the words live in each client.
+- **Bodies are typed JSON; only queries coerce.** `teamSize: "5"` is refused in a
+  body, and `?limit=5` is read as 5.
+- **Shapes are derived, never copied.** One `locationSchema`, one
+  `founderLinksSchema`, one `ventureSchema`, one `uploadKeySchema`; the other
+  places pick, omit or reuse them, and a test checks by object identity.
+
 `zod` is a **peer** dependency (`^4.4.0`), on purpose. The consumer owns the Zod
 instance; this package must not bring its own.
 
 ---
 
+## Breaking in 0.2.0
+
+No export was removed; these change BEHAVIOUR or a field's shape. Every one is a
+correction of something the backend, the web or the data already disagreed on.
+
+| What | Before | Now |
+|---|---|---|
+| Custom messages | English sentences | keys from `VALIDATION_MESSAGE` |
+| `apiErrorSchema.code` | any string | `ApiErrorCode` |
+| `apiErrorSchema.details` | record of strings (never sent) | `{ issues }`, each with `location` |
+| `locationSchema.country` | defaulted to `'India'` | required, no default |
+| `ventureSchema.teamSize`, `.foundedYear` | coerced | numbers only |
+| `httpUrlSchema` | uncapped, Zod's English error | capped at `LINK_URL_MAX`, key `urlInvalid` |
+| Link preview `url`, `imageUrl` | `httpUrlSchema` | `safeUrlSchema` (no cap) |
+| `completeOnboardingBodySchema.guidelinesVersion` | any string | exactly `GUIDELINES_VERSION` |
+| `completeOnboardingBodySchema.avatarUploadKey` | any string | `uploadKeySchema` |
+| `onboardingDraftSchema` | any keys | the form's keys only (values still opaque) |
+| `uploadPresignBodySchema` | `{ extension }` | `{ extension, contentLength }` |
+| `feedQuerySchema` | `authorId` (ignored by the server) | removed; `interests` added |
+| `setReactionResponseSchema`, `createReportResponseSchema` `.contentKind` | post, poll | post, poll, comment |
+| `FOUNDER_ONBOARDING_STEPS[i]` | `title`, `helpText` | `titleKey`, `helpKey` |
+| `TOPIC_CATEGORIES[i]` | `label` | `labelKey` |
+| `discoverFacetsSchema` options | `{ value, label, count }` | `{ value, count }` |
+| `updateUsernameBodySchema` | format only | format, and not reserved |
+
+Deprecated, removed in 0.3.0: `chatInvitationBodySchema` (use
+`openChatBodySchema`) and `chatInvitationSchema` (describes nothing that
+exists).
+
+---
+
 ## Publishing
 
 **The version only ever moves on `dev`.** Never bump `version` on a feat branch
@@ -92,12 +152,23 @@ Two things that follow from it:
 
 ```
 src/
-  common.ts              username rules, the four enums, location, pagination
-  founder-profile.ts     the profile, the peer-visible card, the write bodies
-  discover.ts            the Discover query and its facets
-  responses/common.ts    success / error / paginated envelopes
+  limits.ts              every length, size and count limit, by name (imports nothing)
+  validation.ts          message keys, the wire shape of an issue, toValidationIssues
+  errors.ts              every API error code (API_ERROR_CODE_VALUES)
+  uploads.ts             the upload key, its extensions and content types, presign
+  common.ts              usernames (and the reserved list), the enums, URLs, phone,
+                         location, coordinates, pagination
+  founder-profile.ts     the profile, links, venture, the card, the write bodies
+  onboarding.ts          the steps, their per-step schemas, the draft and the finish
+  feed.ts                posts, polls, comments, reactions, reports, params, pages
+  discover.ts            the Discover query, its page and its facets
+  chat.ts                config, token, opening a conversation, participants
+  responses/common.ts    success / error / paginated / { id } envelopes
   index.ts               the public surface. Everything a consumer imports.
 tests/
+  ssot.test.ts           derived not copied, no body coercion, URLs, uploads, codes
+  validation.test.ts     keys not sentences, no input leaves, limits applied
+  onboarding-steps.test.ts  steps, step schemas and the finish body agree
   responses.test.ts      the envelopes, pinned
   public-surface.test.ts export-removal tripwire + the values the database is pinned to
 ```
@@ -119,7 +190,9 @@ import { founderCardSchema, type FounderCard } from 'founder-schema';
 | `npm test` | Vitest, run once |
 | `npm run test:watch` | Vitest, watching |
 | `npm run lint` | Biome lint |
-| `npm run check` | type-check, then `biome check --write` |
+| `npm run check` | type-check, then `biome check` (read-only, so a publish never rewrites a file) |
+| `npm run check:fix` | type-check, then `biome check --write` |
+| `prepublishOnly` | `check`, then the tests, then the build. A publish that fails any of them does not happen |
 
 There is no `postinstall` script and there must not be one. They break the
 Dockerized builds in this family.
@@ -176,11 +249,10 @@ bearing, so append at the end and never insert.
 
 ---
 
-## Open, and not ours to decide
+## Settled since the scaffold
 
-- **The npm package name and the first publish.** Publishing a name is public and
-  effectively permanent, so it waits for the user.
-- **The onboarding steps.** The mechanism is settled; the questions are not.
+- **The npm name and the first publish:** `founder-schema`, 0.1.0, by the user.
+- **The onboarding steps:** seven, ruled 2026-09-22; see `src/onboarding.ts`.
 
 ## Contract decisions, 2026-09-21
 

package/dist/chat.d.ts

@@ -1,5 +1,5 @@
 /**
- * founder-schema — Chat: config, auth token, invitation
+ * founder-schema — Chat: config, auth token, opening a conversation, participants
  *
  * Founder Circle does not run a chat server. It uses the shared one, which
  * serves several products, and that is the whole reason this file is careful:
@@ -32,6 +32,7 @@ import { z } from 'zod';
  */
 export declare const CHAT_PRODUCT_ID: "founder-circle";
 export declare const chatProductIdSchema: z.ZodLiteral<"founder-circle">;
+export type ChatProductId = z.infer<typeof chatProductIdSchema>;
 /**
  * What the client needs before it can open a socket.
  *
@@ -110,30 +111,77 @@ export declare const chatAuthTokenSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;
 /**
- * Asking our own backend for permission to start a conversation with somebody.
+ * `POST /api/v1/chat/open`: start (or find) the direct conversation with
+ * another member.
  *
  * Our backend decides who may talk to whom, because only it knows this
- * product's rules. The chat server is deliberately not in that decision.
+ * product's rules, and it does the whole exchange with the chat server itself:
+ * it mints the viewer's token and an invitation naming both participants, and
+ * redeems them server to server. No credential reaches the browser.
  */
-export declare const chatInvitationBodySchema: z.ZodObject<{
+export declare const openChatBodySchema: z.ZodObject<{
     userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 }, z.core.$strip>;
-export type ChatInvitationBody = z.infer<typeof chatInvitationBodySchema>;
+export type OpenChatBody = z.infer<typeof openChatBodySchema>;
 /**
- * The invitation itself.
- *
- * ⚠️ THE INVITATION IS THE CREDENTIAL, and the call that redeems it at the chat
- * server deliberately carries NO Authorization header. The token already names
- * both participants, which is precisely what keeps the chat server out of
- * deciding who may talk to whom.
+ * The conversation to navigate to. `201` with `wasCreated: true` the first
+ * time, `200` and `false` on every later open of the same pair.
+ */
+export declare const openChatResponseSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    wasCreated: z.ZodBoolean;
+}, z.core.$strip>;
+export type OpenChatResponse = z.infer<typeof openChatResponseSchema>;
+/**
+ * `POST /api/v1/chat/participants`: names and avatars for the people in the
+ * viewer's conversations.
  *
- * That looks like an oversight and is not. Anyone "fixing" it by attaching a
- * bearer would move the authorisation decision to a server that serves several
- * products and does not know this one's rules. If it ever needs changing, the
- * thing to change is who issues the invitation, not what accompanies it.
+ * The chat server knows ids and nothing about who anybody is, because it serves
+ * several products and identity belongs to each; so the conversation list asks
+ * here, once per screen. Bounded by `CHAT_PARTICIPANTS_MAX`, so it cannot page
+ * through the directory.
+ */
+export declare const chatParticipantsBodySchema: z.ZodObject<{
+    userIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strip>;
+export type ChatParticipantsBody = z.infer<typeof chatParticipantsBodySchema>;
+/** The public card fields any member already sees, and nothing more. */
+export declare const chatParticipantSchema: z.ZodObject<{
+    displayName: z.ZodString;
+    username: z.ZodString;
+    avatarUrl: z.ZodNullable<z.ZodURL>;
+}, z.core.$strip>;
+export type ChatParticipant = z.infer<typeof chatParticipantSchema>;
+/**
+ * Keyed by user id. ⚠ An id with no active, onboarded profile is ABSENT, not
+ * an error: the client renders it as a former member rather than guessing.
+ */
+export declare const chatParticipantsResponseSchema: z.ZodObject<{
+    participants: z.ZodRecord<z.ZodString, z.ZodObject<{
+        displayName: z.ZodString;
+        username: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodURL>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChatParticipantsResponse = z.infer<typeof chatParticipantsResponseSchema>;
+/**
+ * @deprecated Since 0.2.0: use `openChatBodySchema`, the same shape under the
+ * name of the route that takes it. Removed in 0.3.0.
+ */
+export declare const chatInvitationBodySchema: z.ZodObject<{
+    userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>;
+/** @deprecated Since 0.2.0: use `OpenChatBody`. Removed in 0.3.0. */
+export type ChatInvitationBody = OpenChatBody;
+/**
+ * @deprecated Since 0.2.0, and it describes nothing that exists. The browser
+ * never holds an invitation: `/chat/open` mints and redeems it server to
+ * server. The old `/invitation` route that handed one out could never have
+ * worked and is gone. Removed in 0.3.0.
  */
 export declare const chatInvitationSchema: z.ZodObject<{
     invitationToken: z.ZodString;
 }, z.core.$strip>;
+/** @deprecated Since 0.2.0. Removed in 0.3.0. */
 export type ChatInvitation = z.infer<typeof chatInvitationSchema>;
 //# sourceMappingURL=chat.d.ts.map

package/dist/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAG,gBAAyB,CAAC;AACzD,eAAO,MAAM,mBAAmB,gCAA6B,CAAC;AAI9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,QAAU,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB;;;;;iBAQ9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAG,gBAAyB,CAAC;AACzD,eAAO,MAAM,mBAAmB,gCAA6B,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,QAAU,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB;;;;;iBAQ9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;iBAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B;;iBAErC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,wEAAwE;AACxE,eAAO,MAAM,qBAAqB;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;iBAEzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAItF;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;iBAAqB,CAAC;AAC3D,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/chat.js

@@ -1,5 +1,5 @@
 /**
- * founder-schema — Chat: config, auth token, invitation
+ * founder-schema — Chat: config, auth token, opening a conversation, participants
  *
  * Founder Circle does not run a chat server. It uses the shared one, which
  * serves several products, and that is the whole reason this file is careful:
@@ -21,7 +21,8 @@
  * @module founder-schema/chat
  */
 import { z } from 'zod';
-import { objectIdSchema } from './common.js';
+import { objectIdSchema, usernameSchema } from './common.js';
+import { CHAT_PARTICIPANTS_MAX } from './limits.js';
 /**
  * The product this package speaks for.
  *
@@ -116,29 +117,66 @@ export const chatAuthTokenSchema = z.object({
     /** The product this token is scoped to. A mismatch must fail loudly. */
     productId: chatProductIdSchema,
 });
-// ─── Invitation ──────────────────────────────────────────────────────────────
+// ─── Opening a conversation ──────────────────────────────────────────────────
 /**
- * Asking our own backend for permission to start a conversation with somebody.
+ * `POST /api/v1/chat/open`: start (or find) the direct conversation with
+ * another member.
  *
  * Our backend decides who may talk to whom, because only it knows this
- * product's rules. The chat server is deliberately not in that decision.
+ * product's rules, and it does the whole exchange with the chat server itself:
+ * it mints the viewer's token and an invitation naming both participants, and
+ * redeems them server to server. No credential reaches the browser.
  */
-export const chatInvitationBodySchema = z.object({
-    /** The OTHER participant. The viewer is taken from the credential. */
+export const openChatBodySchema = z.object({
+    /** The OTHER participant. The viewer is taken from the credential, never the body. */
     userId: objectIdSchema,
 });
 /**
- * The invitation itself.
- *
- * ⚠️ THE INVITATION IS THE CREDENTIAL, and the call that redeems it at the chat
- * server deliberately carries NO Authorization header. The token already names
- * both participants, which is precisely what keeps the chat server out of
- * deciding who may talk to whom.
+ * The conversation to navigate to. `201` with `wasCreated: true` the first
+ * time, `200` and `false` on every later open of the same pair.
+ */
+export const openChatResponseSchema = z.object({
+    conversationId: z.string().min(1),
+    wasCreated: z.boolean(),
+});
+// ─── Participants ────────────────────────────────────────────────────────────
+/**
+ * `POST /api/v1/chat/participants`: names and avatars for the people in the
+ * viewer's conversations.
  *
- * That looks like an oversight and is not. Anyone "fixing" it by attaching a
- * bearer would move the authorisation decision to a server that serves several
- * products and does not know this one's rules. If it ever needs changing, the
- * thing to change is who issues the invitation, not what accompanies it.
+ * The chat server knows ids and nothing about who anybody is, because it serves
+ * several products and identity belongs to each; so the conversation list asks
+ * here, once per screen. Bounded by `CHAT_PARTICIPANTS_MAX`, so it cannot page
+ * through the directory.
+ */
+export const chatParticipantsBodySchema = z.object({
+    userIds: z.array(objectIdSchema).min(1).max(CHAT_PARTICIPANTS_MAX),
+});
+/** The public card fields any member already sees, and nothing more. */
+export const chatParticipantSchema = z.object({
+    displayName: z.string(),
+    username: usernameSchema,
+    /** Null when the member has no photo. Ours, or from the login provider. */
+    avatarUrl: z.url().nullable(),
+});
+/**
+ * Keyed by user id. ⚠ An id with no active, onboarded profile is ABSENT, not
+ * an error: the client renders it as a former member rather than guessing.
+ */
+export const chatParticipantsResponseSchema = z.object({
+    participants: z.record(z.string(), chatParticipantSchema),
+});
+// ─── Deprecated ──────────────────────────────────────────────────────────────
+/**
+ * @deprecated Since 0.2.0: use `openChatBodySchema`, the same shape under the
+ * name of the route that takes it. Removed in 0.3.0.
+ */
+export const chatInvitationBodySchema = openChatBodySchema;
+/**
+ * @deprecated Since 0.2.0, and it describes nothing that exists. The browser
+ * never holds an invitation: `/chat/open` mints and redeems it server to
+ * server. The old `/invitation` route that handed one out could never have
+ * worked and is gone. Removed in 0.3.0.
  */
 export const chatInvitationSchema = z.object({
     invitationToken: z.string().min(1),

package/dist/chat.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAyB,CAAC;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9D,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,yEAAyE;IACzE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvB,sDAAsD;IACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,mEAAmE;IACnE,SAAS,EAAE,mBAAmB;CAC/B,CAAC,CAAC;AAGH,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,EAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,iEAAiE;IACjE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC3B,gEAAgE;IAChE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,wEAAwE;IACxE,SAAS,EAAE,mBAAmB;CAC/B,CAAC,CAAC;AAGH,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,sEAAsE;IACtE,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC;AAGH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC","sourcesContent":["/**\n * founder-schema — Chat: config, auth token, invitation\n *\n * Founder Circle does not run a chat server. It uses the shared one, which\n * serves several products, and that is the whole reason this file is careful:\n * when one server serves many tenants, the failure mode is SILENT. A push once\n * returned success having sent nothing, because the caller held the wrong\n * product's key and nothing in the exchange said which product it was for.\n *\n * So the rule these shapes exist to hold: TENANCY COMES FROM THE CREDENTIAL,\n * never from a request body. The token says which product it is for, the chat\n * server resolves the product from the token and from nothing else, and a\n * Founder Circle token cannot address another product's conversation even when\n * handed a valid-looking id.\n *\n * ⚠️ TEXT ONLY. There is deliberately no `callsEnabled` flag here, and its\n * absence is the feature: the user ruled chat is text only, there is no call\n * code to branch on, and the browser is told to deny camera and microphone\n * outright. A boolean that can never be true is an invitation to turn it on.\n *\n * @module founder-schema/chat\n */\n\nimport { z } from 'zod';\nimport { objectIdSchema } from './common.js';\n\n/**\n * The product this package speaks for.\n *\n * Typed as a LITERAL on purpose. If the shared chat server ever hands back a\n * config or a token minted for a different product, parsing fails loudly here\n * rather than the client quietly talking to the wrong tenant. That is exactly\n * the class of bug this file exists to prevent, so it should be impossible to\n * carry past the first parse.\n */\nexport const CHAT_PRODUCT_ID = 'founder-circle' as const;\nexport const chatProductIdSchema = z.literal(CHAT_PRODUCT_ID);\n\n// ─── Config ──────────────────────────────────────────────────────────────────\n\n/**\n * What the client needs before it can open a socket.\n *\n * ⚠️ `enabled` IS MANDATORY AND IS NOT DERIVED FROM `url`. \"Messaging is not\n * switched on yet\" is a first-class state, not a failure: a 404 is the expected\n * answer today, and the client collapses a disabled flag, a null url, a non-2xx\n * and a thrown fetch to the same quiet \"not on yet\" rather than an error. If\n * `enabled` were inferred from a missing url, \"off\" and \"broken\" would be the\n * same wire shape and the inbox could not tell a member which one it was.\n *\n * ⚠️ `userId` is required and is the field nothing works without. The client\n * needs to know WHO THE VIEWER IS to decide which side a bubble sits on, to\n * filter the viewer out of presence and typing, to pick the other participant\n * for a row's name and avatar, and to tell its own optimistic message from one\n * echoed back. Without it every conversation renders as though the viewer were\n * nobody. It was missing from the first sketch of this endpoint.\n */\nexport const chatConfigSchema = z.object({\n  enabled: z.boolean(),\n  /** Null whenever chat is not switched on. Never a placeholder string. */\n  url: z.url().nullable(),\n  /** The VIEWER's id, as the chat server knows them. */\n  userId: z.string(),\n  /** Which product this config is for. See `chatProductIdSchema`. */\n  productId: chatProductIdSchema,\n});\nexport type ChatConfig = z.infer<typeof chatConfigSchema>;\n\n// ─── Auth token ──────────────────────────────────────────────────────────────\n\n/**\n * How long before expiry the client re-mints, in seconds.\n *\n * Exported because it is a contract detail and not an implementation one: a\n * token handed over with two seconds left is a socket that authenticates and is\n * closed again immediately, so the minting side needs to know the consuming\n * side will not use the last minute of a token's life.\n */\nexport const CHAT_TOKEN_REFRESH_MARGIN_SECONDS = 60;\n\n/**\n * How often the live socket re-authenticates, in seconds.\n *\n * Auth is an EVENT on the open socket rather than a handshake parameter, so\n * re-authenticating does not drop the connection.\n *\n * ⚠️ THIS MUST STAY BELOW THE REAL TOKEN LIFETIME, by more than the refresh\n * margin. It assumes a 15 minute token. A re-auth interval longer than the\n * lifetime is a socket that dies every quarter of an hour with no explanation,\n * and the symptom appears far from the cause. If the issued lifetime changes,\n * this number moves with it or the two silently disagree.\n */\nexport const CHAT_SOCKET_REAUTH_SECONDS = 10 * 60;\n\n/**\n * A short-lived token for the shared chat server.\n *\n * ⚠️ BOTH TIME FIELDS ARE KEPT, and they are not redundant, because two\n * different parties read them with two different clocks:\n *\n *   `expiresAt`  an absolute instant, for the SERVER. The chat server holds the\n *                authoritative clock and must reject an expired token on its\n *                own, whatever any client believes.\n *   `expiresIn`  a duration in seconds, for the CLIENT. Scheduling a refresh\n *                from `receivedAt + expiresIn` uses only the client's own\n *                elapsed time, so a device whose absolute clock is wrong still\n *                refreshes correctly. Scheduling from `expiresAt` instead means\n *                a browser an hour fast treats every fresh token as already\n *                expired and re-mints forever.\n *\n * Dropping either one breaks the party that reads it. This is the same reason\n * OAuth carries `expires_in` on the wire while the token itself carries `exp`.\n *\n * ⚠️ AND THE CLIENT IS NOT THE ENFORCER. Its margin is an optimisation to avoid\n * a pointless round trip. A wrong clock, a tab asleep for an hour, or a modified\n * client all defeat anything the client does, so the chat server rejects an\n * expired token on its own.\n */\nexport const chatAuthTokenSchema = z.object({\n  token: z.string().min(1),\n  /** ISO 8601. Parsed with `Date.parse`, never an epoch number. */\n  expiresAt: z.iso.datetime(),\n  /** Seconds from issue. See the note above on why both exist. */\n  expiresIn: z.number().int().positive(),\n  /** The product this token is scoped to. A mismatch must fail loudly. */\n  productId: chatProductIdSchema,\n});\nexport type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;\n\n// ─── Invitation ──────────────────────────────────────────────────────────────\n\n/**\n * Asking our own backend for permission to start a conversation with somebody.\n *\n * Our backend decides who may talk to whom, because only it knows this\n * product's rules. The chat server is deliberately not in that decision.\n */\nexport const chatInvitationBodySchema = z.object({\n  /** The OTHER participant. The viewer is taken from the credential. */\n  userId: objectIdSchema,\n});\nexport type ChatInvitationBody = z.infer<typeof chatInvitationBodySchema>;\n\n/**\n * The invitation itself.\n *\n * ⚠️ THE INVITATION IS THE CREDENTIAL, and the call that redeems it at the chat\n * server deliberately carries NO Authorization header. The token already names\n * both participants, which is precisely what keeps the chat server out of\n * deciding who may talk to whom.\n *\n * That looks like an oversight and is not. Anyone \"fixing\" it by attaching a\n * bearer would move the authorisation decision to a server that serves several\n * products and does not know this one's rules. If it ever needs changing, the\n * thing to change is who issues the invitation, not what accompanies it.\n */\nexport const chatInvitationSchema = z.object({\n  invitationToken: z.string().min(1),\n});\nexport type ChatInvitation = z.infer<typeof chatInvitationSchema>;\n"]}
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * founder-schema — Chat: config, auth token, opening a conversation, participants\n *\n * Founder Circle does not run a chat server. It uses the shared one, which\n * serves several products, and that is the whole reason this file is careful:\n * when one server serves many tenants, the failure mode is SILENT. A push once\n * returned success having sent nothing, because the caller held the wrong\n * product's key and nothing in the exchange said which product it was for.\n *\n * So the rule these shapes exist to hold: TENANCY COMES FROM THE CREDENTIAL,\n * never from a request body. The token says which product it is for, the chat\n * server resolves the product from the token and from nothing else, and a\n * Founder Circle token cannot address another product's conversation even when\n * handed a valid-looking id.\n *\n * ⚠️ TEXT ONLY. There is deliberately no `callsEnabled` flag here, and its\n * absence is the feature: the user ruled chat is text only, there is no call\n * code to branch on, and the browser is told to deny camera and microphone\n * outright. A boolean that can never be true is an invitation to turn it on.\n *\n * @module founder-schema/chat\n */\n\nimport { z } from 'zod';\nimport { objectIdSchema, usernameSchema } from './common.js';\nimport { CHAT_PARTICIPANTS_MAX } from './limits.js';\n\n/**\n * The product this package speaks for.\n *\n * Typed as a LITERAL on purpose. If the shared chat server ever hands back a\n * config or a token minted for a different product, parsing fails loudly here\n * rather than the client quietly talking to the wrong tenant. That is exactly\n * the class of bug this file exists to prevent, so it should be impossible to\n * carry past the first parse.\n */\nexport const CHAT_PRODUCT_ID = 'founder-circle' as const;\nexport const chatProductIdSchema = z.literal(CHAT_PRODUCT_ID);\nexport type ChatProductId = z.infer<typeof chatProductIdSchema>;\n\n// ─── Config ──────────────────────────────────────────────────────────────────\n\n/**\n * What the client needs before it can open a socket.\n *\n * ⚠️ `enabled` IS MANDATORY AND IS NOT DERIVED FROM `url`. \"Messaging is not\n * switched on yet\" is a first-class state, not a failure: a 404 is the expected\n * answer today, and the client collapses a disabled flag, a null url, a non-2xx\n * and a thrown fetch to the same quiet \"not on yet\" rather than an error. If\n * `enabled` were inferred from a missing url, \"off\" and \"broken\" would be the\n * same wire shape and the inbox could not tell a member which one it was.\n *\n * ⚠️ `userId` is required and is the field nothing works without. The client\n * needs to know WHO THE VIEWER IS to decide which side a bubble sits on, to\n * filter the viewer out of presence and typing, to pick the other participant\n * for a row's name and avatar, and to tell its own optimistic message from one\n * echoed back. Without it every conversation renders as though the viewer were\n * nobody. It was missing from the first sketch of this endpoint.\n */\nexport const chatConfigSchema = z.object({\n  enabled: z.boolean(),\n  /** Null whenever chat is not switched on. Never a placeholder string. */\n  url: z.url().nullable(),\n  /** The VIEWER's id, as the chat server knows them. */\n  userId: z.string(),\n  /** Which product this config is for. See `chatProductIdSchema`. */\n  productId: chatProductIdSchema,\n});\nexport type ChatConfig = z.infer<typeof chatConfigSchema>;\n\n// ─── Auth token ──────────────────────────────────────────────────────────────\n\n/**\n * How long before expiry the client re-mints, in seconds.\n *\n * Exported because it is a contract detail and not an implementation one: a\n * token handed over with two seconds left is a socket that authenticates and is\n * closed again immediately, so the minting side needs to know the consuming\n * side will not use the last minute of a token's life.\n */\nexport const CHAT_TOKEN_REFRESH_MARGIN_SECONDS = 60;\n\n/**\n * How often the live socket re-authenticates, in seconds.\n *\n * Auth is an EVENT on the open socket rather than a handshake parameter, so\n * re-authenticating does not drop the connection.\n *\n * ⚠️ THIS MUST STAY BELOW THE REAL TOKEN LIFETIME, by more than the refresh\n * margin. It assumes a 15 minute token. A re-auth interval longer than the\n * lifetime is a socket that dies every quarter of an hour with no explanation,\n * and the symptom appears far from the cause. If the issued lifetime changes,\n * this number moves with it or the two silently disagree.\n */\nexport const CHAT_SOCKET_REAUTH_SECONDS = 10 * 60;\n\n/**\n * A short-lived token for the shared chat server.\n *\n * ⚠️ BOTH TIME FIELDS ARE KEPT, and they are not redundant, because two\n * different parties read them with two different clocks:\n *\n *   `expiresAt`  an absolute instant, for the SERVER. The chat server holds the\n *                authoritative clock and must reject an expired token on its\n *                own, whatever any client believes.\n *   `expiresIn`  a duration in seconds, for the CLIENT. Scheduling a refresh\n *                from `receivedAt + expiresIn` uses only the client's own\n *                elapsed time, so a device whose absolute clock is wrong still\n *                refreshes correctly. Scheduling from `expiresAt` instead means\n *                a browser an hour fast treats every fresh token as already\n *                expired and re-mints forever.\n *\n * Dropping either one breaks the party that reads it. This is the same reason\n * OAuth carries `expires_in` on the wire while the token itself carries `exp`.\n *\n * ⚠️ AND THE CLIENT IS NOT THE ENFORCER. Its margin is an optimisation to avoid\n * a pointless round trip. A wrong clock, a tab asleep for an hour, or a modified\n * client all defeat anything the client does, so the chat server rejects an\n * expired token on its own.\n */\nexport const chatAuthTokenSchema = z.object({\n  token: z.string().min(1),\n  /** ISO 8601. Parsed with `Date.parse`, never an epoch number. */\n  expiresAt: z.iso.datetime(),\n  /** Seconds from issue. See the note above on why both exist. */\n  expiresIn: z.number().int().positive(),\n  /** The product this token is scoped to. A mismatch must fail loudly. */\n  productId: chatProductIdSchema,\n});\nexport type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;\n\n// ─── Opening a conversation ──────────────────────────────────────────────────\n\n/**\n * `POST /api/v1/chat/open`: start (or find) the direct conversation with\n * another member.\n *\n * Our backend decides who may talk to whom, because only it knows this\n * product's rules, and it does the whole exchange with the chat server itself:\n * it mints the viewer's token and an invitation naming both participants, and\n * redeems them server to server. No credential reaches the browser.\n */\nexport const openChatBodySchema = z.object({\n  /** The OTHER participant. The viewer is taken from the credential, never the body. */\n  userId: objectIdSchema,\n});\nexport type OpenChatBody = z.infer<typeof openChatBodySchema>;\n\n/**\n * The conversation to navigate to. `201` with `wasCreated: true` the first\n * time, `200` and `false` on every later open of the same pair.\n */\nexport const openChatResponseSchema = z.object({\n  conversationId: z.string().min(1),\n  wasCreated: z.boolean(),\n});\nexport type OpenChatResponse = z.infer<typeof openChatResponseSchema>;\n\n// ─── Participants ────────────────────────────────────────────────────────────\n\n/**\n * `POST /api/v1/chat/participants`: names and avatars for the people in the\n * viewer's conversations.\n *\n * The chat server knows ids and nothing about who anybody is, because it serves\n * several products and identity belongs to each; so the conversation list asks\n * here, once per screen. Bounded by `CHAT_PARTICIPANTS_MAX`, so it cannot page\n * through the directory.\n */\nexport const chatParticipantsBodySchema = z.object({\n  userIds: z.array(objectIdSchema).min(1).max(CHAT_PARTICIPANTS_MAX),\n});\nexport type ChatParticipantsBody = z.infer<typeof chatParticipantsBodySchema>;\n\n/** The public card fields any member already sees, and nothing more. */\nexport const chatParticipantSchema = z.object({\n  displayName: z.string(),\n  username: usernameSchema,\n  /** Null when the member has no photo. Ours, or from the login provider. */\n  avatarUrl: z.url().nullable(),\n});\nexport type ChatParticipant = z.infer<typeof chatParticipantSchema>;\n\n/**\n * Keyed by user id. ⚠ An id with no active, onboarded profile is ABSENT, not\n * an error: the client renders it as a former member rather than guessing.\n */\nexport const chatParticipantsResponseSchema = z.object({\n  participants: z.record(z.string(), chatParticipantSchema),\n});\nexport type ChatParticipantsResponse = z.infer<typeof chatParticipantsResponseSchema>;\n\n// ─── Deprecated ──────────────────────────────────────────────────────────────\n\n/**\n * @deprecated Since 0.2.0: use `openChatBodySchema`, the same shape under the\n * name of the route that takes it. Removed in 0.3.0.\n */\nexport const chatInvitationBodySchema = openChatBodySchema;\n/** @deprecated Since 0.2.0: use `OpenChatBody`. Removed in 0.3.0. */\nexport type ChatInvitationBody = OpenChatBody;\n\n/**\n * @deprecated Since 0.2.0, and it describes nothing that exists. The browser\n * never holds an invitation: `/chat/open` mints and redeems it server to\n * server. The old `/invitation` route that handed one out could never have\n * worked and is gone. Removed in 0.3.0.\n */\nexport const chatInvitationSchema = z.object({\n  invitationToken: z.string().min(1),\n});\n/** @deprecated Since 0.2.0. Removed in 0.3.0. */\nexport type ChatInvitation = z.infer<typeof chatInvitationSchema>;\n"]}

package/dist/common.d.ts

@@ -20,6 +20,8 @@ export declare const emptyStringToUndefined: (value: unknown) => unknown;
 export declare const optionalTrimmedString: (maxLength?: number) => z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
 /** A Mongo ObjectId as it crosses the wire: 24 lowercase hex characters. */
 export declare const objectIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** Named for what it is on the wire, so it never collides with Mongoose's `ObjectId`. */
+export type ObjectIdString = z.infer<typeof objectIdSchema>;
 /**
  * A URL safe to store and, after the consumer's own check, to render.
  *
@@ -53,19 +55,55 @@ export declare const objectIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<strin
  * (krish hit this rendering inline video, 2026-09-21, and handles it by parsing
  * and comparing the hostname exactly.)
  */
+export declare const safeUrlSchema: z.ZodURL;
+export type SafeUrl = z.infer<typeof safeUrlSchema>;
+/**
+ * A URL a member TYPES: `safeUrlSchema` plus the `LINK_URL_MAX` ceiling, so
+ * every member URL carries the same cap and no consumer has to remember it.
+ *
+ * Two schemas, not one, because the cap is about what a person types and is
+ * wrong for what the server reads from elsewhere. Until 0.2.0 there was only
+ * this one, and it capped a link preview's CDN image URL too: one 314-character
+ * `imageUrl` would have failed a whole feed page.
+ */
 export declare const httpUrlSchema: z.ZodURL;
+export type HttpUrl = z.infer<typeof httpUrlSchema>;
 /**
- * Public handle a founder picks and can change later.
+ * Public handle. Derived by the server at onboarding, changeable later.
  *
  * Rules are deliberately narrow because the handle appears in URLs and in
  * mentions: lowercase letters, digits, underscore and a single dot, 3 to 30
- * characters, must start with a letter. Reserved words are refused by the
- * backend, not here, so the list can change without a schema publish.
+ * characters, must start with a letter.
+ *
+ * This is the FORMAT, and it is what every read shape uses. A handle being
+ * CHOSEN must also not be reserved: that is `chosenUsernameSchema`.
  */
 export declare const USERNAME_MIN = 3;
 export declare const USERNAME_MAX = 30;
 export declare const usernameSchema: z.ZodString;
 export type Username = z.infer<typeof usernameSchema>;
+/**
+ * Handles this product keeps for itself: route names a handle would shadow,
+ * and words that would let a member pass as staff.
+ *
+ * ⚠ HERE, IN THE CONTRACT, since 0.2.0. It used to live in the backend so it
+ * could grow without a publish, and nothing ever read it: the server derived
+ * handles without checking it, so a member called "Support" was handed
+ * `support`. One list, read by the server when it derives a handle and by any
+ * form that lets a member choose one, is worth a publish per addition.
+ *
+ * Matched exactly, after lowercasing.
+ */
+export declare const RESERVED_USERNAMES: readonly ["admin", "about", "api", "chat", "discover", "feed", "founder", "foundercircle", "help", "home", "me", "meetup", "moderator", "onboarding", "settings", "staff", "superadmin", "support", "system", "team"];
+export declare function isReservedUsername(handle: string): boolean;
+/**
+ * A handle a member is CHOOSING: the format, and not reserved.
+ *
+ * ⚠ Not used on read shapes, deliberately. A handle stored before the reserved
+ * check existed must still READ, or one member's old handle would fail every
+ * page that shows their name.
+ */
+export declare const chosenUsernameSchema: z.ZodString;
 /**
  * Stage of the founder's current venture.
  *
@@ -201,19 +239,55 @@ export type Gender = z.infer<typeof genderSchema>;
  * would be the copy nobody keeps in sync.
  */
 export declare const phoneSchema: z.ZodString;
+export type Phone = z.infer<typeof phoneSchema>;
 /**
- * Where the founder is based. City and country are what Discover filters on;
- * coordinates are optional and only present when the member granted location.
+ * Where the founder is based. City and country are what Discover filters on.
  *
- * Note for later: this is a DECLARED location, not a GPS reading. Jansathi's
- * rule applies here too — never write a declared location from a GPS capture.
+ * ONE SHAPE for the profile, the Me tab's patch, onboarding's finish and the
+ * location suggestion. It was written out three times until 0.2.0, the same
+ * kind of copy that let the profile model lose Instagram.
+ *
+ * ⚠ `country` is REQUIRED and has NO default. A default here (it used to be
+ * `'India'`) is destructive on every write path: a founder in Berlin who
+ * corrects only their city would be moved to India by a value they never saw.
+ * A body that carries a location carries the whole location. Every stored
+ * location has a country, because the model requires one, so the read side
+ * loses nothing.
+ *
+ * This is a DECLARED location, not a GPS reading. Jansathi's rule applies
+ * here too: never write a declared location from a GPS capture.
  */
 export declare const locationSchema: z.ZodObject<{
     city: z.ZodString;
     state: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
-    country: z.ZodDefault<z.ZodString>;
+    country: z.ZodString;
 }, z.core.$strip>;
 export type FounderLocation = z.infer<typeof locationSchema>;
+/**
+ * `GET /api/v1/location/areas/reverse?lat=&lng=`: plain decimal degrees.
+ *
+ * A QUERY, so coercion is right here: everything in a URL is a string. An
+ * emptied parameter is "missing", never 0, because 0,0 is a real place in the
+ * Gulf of Guinea and would be looked up rather than refused.
+ */
+export declare const coordinatesQuerySchema: z.ZodObject<{
+    lat: z.ZodPreprocess<z.ZodCoercedNumber<unknown>, unknown>;
+    lng: z.ZodPreprocess<z.ZodCoercedNumber<unknown>, unknown>;
+}, z.core.$strip>;
+export type CoordinatesQuery = z.infer<typeof coordinatesQuerySchema>;
+export type CoordinatesQueryInput = z.input<typeof coordinatesQuerySchema>;
+/**
+ * The city these coordinates look like, for the member to CONFIRM, or `null`
+ * when the lookup could not place them confidently (or they are outside India,
+ * whose area data is all there is). A suggestion, never a write: only what the
+ * member then submits becomes their location.
+ */
+export declare const suggestedLocationSchema: z.ZodNullable<z.ZodObject<{
+    city: z.ZodString;
+    state: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    country: z.ZodString;
+}, z.core.$strip>>;
+export type SuggestedLocation = z.infer<typeof suggestedLocationSchema>;
 /**
  * Cursor pagination query. Feed and Discover both use it.
  *
@@ -225,4 +299,6 @@ export declare const paginationQuerySchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
+/** What a client may put IN the URL: every field optional, numbers as strings. */
+export type PaginationQueryInput = z.input<typeof paginationQuerySchema>;
 //# sourceMappingURL=common.d.ts.map

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,OAGvD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,GAAI,kBAAe,yDAC8B,CAAC;AAEpF,4EAA4E;AAC5E,eAAO,MAAM,cAAc,wDAGS,CAAC;AAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,UAGxB,CAAC;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,eAAO,MAAM,cAAc,aASxB,CAAC;AACJ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAItD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,qGASvB,CAAC;AACX,eAAO,MAAM,kBAAkB;;;;;;;;;EAA+B,CAAC;AAC/D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,eAAe,2PAsBlB,CAAC;AACX,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;EAA0B,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,YAAY,8LAgBf,CAAC;AACX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;EAAuB,CAAC;AAChD,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,gMAYd,CAAC;AACX,eAAO,MAAM,UAAU;;;;;;;;;;;;EAAsB,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAI9C;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,2DAA4D,CAAC;AACvF,eAAO,MAAM,YAAY;;;;;EAAwB,CAAC;AAClD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIlD;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,aAGkC,CAAC;AAI3D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAI7D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;iBAShC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"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"}