founder-schema 0.1.0

package/README.md

@@ -0,0 +1,200 @@
+# founder-schema
+
+The API contract for Founder Circle, written once as Zod schemas and shared by
+every part of the product.
+
+**Three names here differ, on purpose, so do not "correct" any of them.** The
+npm package is `founder-schema`, the folder on disk is `founder-circle-schema`,
+and the GitLab repo is `founder-schema` inside a group called
+`entrepreneur-connect`. The product is Founder Circle and its `productId`, JWT
+audience and database name all stay `founder-circle`; the group name is how the
+work is filed, not what the product is called (settled with the user,
+2026-09-21). Anything that resolves this package by NAME must read it from
+`package.json`, never assume it matches the directory.
+
+One definition of a founder profile, one definition of the Discover query, one
+definition of the response envelope. The backend validates incoming requests
+with these, the web client validates what comes back, and both get their
+TypeScript types from the same place. When the package and a consumer disagree,
+the package is right and the consumer is the bug.
+
+Consumed by:
+
+| Repo | What it uses today |
+|---|---|
+| `founder-circle-backend` | The four enum arrays and `USERNAME_MAX`, as Mongoose `enum` and `maxlength` constraints |
+| `founder-circle-web-client` | Nothing yet |
+
+---
+
+## Using it in a consumer, before the first publish
+
+**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.
+
+```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
+```
+
+**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:
+
+- **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.
+- **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.
+- **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.
+
+`zod` is a **peer** dependency (`^4.4.0`), on purpose. The consumer owns the Zod
+instance; this package must not bring its own.
+
+---
+
+## Publishing
+
+**The version only ever moves on `dev`.** Never bump `version` on a feat branch
+and never publish from one. The full procedure and the mandatory no-loss check
+are in `personas/TEAM.md`, rule 5a. The short version of why: npm `latest` is one
+global counter and a publish ships the whole package, so publishing from a branch
+silently deletes from `latest` anything published since that branch was cut.
+
+Two things that follow from it:
+
+- A caret on a `0.x` version pins the **minor**: `^0.1.0` resolves `>=0.1.0 <0.2.0`
+  and will never pick up `0.2.0`. Bump consumers to the exact version explicitly.
+- Removing or renaming an export is the only change here that can break a consumer
+  that already compiles. `tests/public-surface.test.ts` fails on any removal, which
+  is the cheap version of the publish-time no-loss check.
+
+---
+
+## Layout
+
+```
+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
+  index.ts               the public surface. Everything a consumer imports.
+tests/
+  responses.test.ts      the envelopes, pinned
+  public-surface.test.ts export-removal tripwire + the values the database is pinned to
+```
+
+A consumer imports from the package root and never from a deep path:
+
+```ts
+import { founderCardSchema, type FounderCard } from 'founder-schema';
+```
+
+---
+
+## Scripts
+
+| Command | What it does |
+|---|---|
+| `npm run build` | Emits `dist/` with declarations and source maps |
+| `npm run type-check` | `tsc --noEmit` over `src`, then again over `src` **and** `tests` |
+| `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` |
+
+There is no `postinstall` script and there must not be one. They break the
+Dockerized builds in this family.
+
+---
+
+## Traps that are specific to this package
+
+**`.partial()` does not switch off `.default()`.** A patch body built as
+`someSchema.pick({...}).partial()` still materialises every defaulted field, so a
+member who edits one field has the others overwritten with the default. `tsc`
+cannot see it and the request looks correct in the network tab. Build a write body
+as its own object with no defaults, and have the client send only the keys the
+member actually changed.
+
+**A default inside a nested object is the same trap one level down.** A patch
+carrying `{ location: { city: 'Berlin' } }` picks up `country: 'India'` from
+`locationSchema`.
+
+**A patch field the member can clear has three states, not two.** Absent means
+do not touch. `null` means clear, and the backend maps it to `$unset`. An empty
+string is **rejected**, deliberately: a form that forgets to convert a cleared
+input to `null` fails loudly at the boundary instead of being silently dropped,
+which would leave the member looking at text they just deleted.
+`optionalTrimmedString` does that dropping, so it belongs in a create body or a
+query, never in a patch body.
+
+**Never `z.url()` for anything a member typed.** The one exception is
+`avatarUrl`, which no write body accepts, so it takes a plain `z.url()` rather
+than refusing hosts we serve avatars from ourselves. That exception is only as
+true as the invariant under it, so `tests/public-surface.test.ts` asserts
+`avatarUrl` stays out of every write body. Adding an avatar field to a form means
+putting `httpUrlSchema` back first.
+
+ It accepts every scheme the URL
+parser accepts, `javascript:`, `data:`, `vbscript:` and `file:` included, and
+each of those is stored XSS as soon as a client renders it. Use `httpUrlSchema`,
+which pins the scheme to http or https and the host to a real domain. The host
+restriction is not cosmetic: this product runs on EC2 with an instance role, so a
+stored `http://169.254.169.254/latest/meta-data/` that anything server-side ever
+fetches is a credential read. A consumer still treats stored URLs as untrusted at
+render time.
+
+**A bound that reads the clock belongs in a `.refine()`, not a `.max()`.**
+`z.number().max(new Date().getUTCFullYear())` is evaluated once, when the module
+is imported, so a server process still up on 1 January rejects the new year until
+somebody restarts it.
+
+**Changing a member of an enum array is a data change, not a type change.** The
+four `*_VALUES` arrays are Mongoose `enum` constraints in the backend. Removing or
+renaming a value orphans documents already saved with it. Appending is safe.
+`STARTUP_STAGE_VALUES` is ordered earliest to latest and that order is load
+bearing, so append at the end and never insert.
+
+---
+
+## Open, and not ours to decide
+
+- **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.
+
+## Contract decisions, 2026-09-21
+
+Seven defects were found in the first scaffold, proven by parsing the build, and
+all seven are fixed. Recorded here because each one settled a rule that applies to
+everything added later, and because the tests that pin them read as arbitrary
+without the reason.
+
+| What it was | The rule now |
+|---|---|
+| The patch body was `pick().partial()`, so every request rewrote `skills`, `lookingFor` and `links` with their defaults | A write body is its own object with no defaults. Defaults live on the read side |
+| A member could not clear `headline` or `about` | Absent, `null` and `""` are three different things. See the trap above |
+| `z.url()` accepted `javascript:`, `data:`, `vbscript:`, `file:` | `httpUrlSchema` everywhere a member supplies a URL |
+| `foundedYear`'s ceiling was captured at import | Read the clock per parse, in a `.refine()` |
+| The paginated envelope's comment contradicted its schema | `nextCursor` is required and nullable. A page always states whether more exist |
+| A patch carrying a city inherited `country: 'India'` | The patch location has no country default and requires the country |
+| An emptied search box answered 400 | An emptied filter means "not provided" |

package/dist/chat.d.ts

@@ -0,0 +1,139 @@
+/**
+ * founder-schema — Chat: config, auth token, invitation
+ *
+ * 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:
+ * when one server serves many tenants, the failure mode is SILENT. A push once
+ * returned success having sent nothing, because the caller held the wrong
+ * product's key and nothing in the exchange said which product it was for.
+ *
+ * So the rule these shapes exist to hold: TENANCY COMES FROM THE CREDENTIAL,
+ * never from a request body. The token says which product it is for, the chat
+ * server resolves the product from the token and from nothing else, and a
+ * Founder Circle token cannot address another product's conversation even when
+ * handed a valid-looking id.
+ *
+ * ⚠️ TEXT ONLY. There is deliberately no `callsEnabled` flag here, and its
+ * absence is the feature: the user ruled chat is text only, there is no call
+ * code to branch on, and the browser is told to deny camera and microphone
+ * outright. A boolean that can never be true is an invitation to turn it on.
+ *
+ * @module founder-schema/chat
+ */
+import { z } from 'zod';
+/**
+ * The product this package speaks for.
+ *
+ * Typed as a LITERAL on purpose. If the shared chat server ever hands back a
+ * config or a token minted for a different product, parsing fails loudly here
+ * rather than the client quietly talking to the wrong tenant. That is exactly
+ * the class of bug this file exists to prevent, so it should be impossible to
+ * carry past the first parse.
+ */
+export declare const CHAT_PRODUCT_ID: "founder-circle";
+export declare const chatProductIdSchema: z.ZodLiteral<"founder-circle">;
+/**
+ * What the client needs before it can open a socket.
+ *
+ * ⚠️ `enabled` IS MANDATORY AND IS NOT DERIVED FROM `url`. "Messaging is not
+ * switched on yet" is a first-class state, not a failure: a 404 is the expected
+ * answer today, and the client collapses a disabled flag, a null url, a non-2xx
+ * and a thrown fetch to the same quiet "not on yet" rather than an error. If
+ * `enabled` were inferred from a missing url, "off" and "broken" would be the
+ * same wire shape and the inbox could not tell a member which one it was.
+ *
+ * ⚠️ `userId` is required and is the field nothing works without. The client
+ * needs to know WHO THE VIEWER IS to decide which side a bubble sits on, to
+ * filter the viewer out of presence and typing, to pick the other participant
+ * for a row's name and avatar, and to tell its own optimistic message from one
+ * echoed back. Without it every conversation renders as though the viewer were
+ * nobody. It was missing from the first sketch of this endpoint.
+ */
+export declare const chatConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    url: z.ZodNullable<z.ZodURL>;
+    userId: z.ZodString;
+    productId: z.ZodLiteral<"founder-circle">;
+}, z.core.$strip>;
+export type ChatConfig = z.infer<typeof chatConfigSchema>;
+/**
+ * How long before expiry the client re-mints, in seconds.
+ *
+ * Exported because it is a contract detail and not an implementation one: a
+ * token handed over with two seconds left is a socket that authenticates and is
+ * closed again immediately, so the minting side needs to know the consuming
+ * side will not use the last minute of a token's life.
+ */
+export declare const CHAT_TOKEN_REFRESH_MARGIN_SECONDS = 60;
+/**
+ * How often the live socket re-authenticates, in seconds.
+ *
+ * Auth is an EVENT on the open socket rather than a handshake parameter, so
+ * re-authenticating does not drop the connection.
+ *
+ * ⚠️ THIS MUST STAY BELOW THE REAL TOKEN LIFETIME, by more than the refresh
+ * margin. It assumes a 15 minute token. A re-auth interval longer than the
+ * lifetime is a socket that dies every quarter of an hour with no explanation,
+ * and the symptom appears far from the cause. If the issued lifetime changes,
+ * this number moves with it or the two silently disagree.
+ */
+export declare const CHAT_SOCKET_REAUTH_SECONDS: number;
+/**
+ * A short-lived token for the shared chat server.
+ *
+ * ⚠️ BOTH TIME FIELDS ARE KEPT, and they are not redundant, because two
+ * different parties read them with two different clocks:
+ *
+ *   `expiresAt`  an absolute instant, for the SERVER. The chat server holds the
+ *                authoritative clock and must reject an expired token on its
+ *                own, whatever any client believes.
+ *   `expiresIn`  a duration in seconds, for the CLIENT. Scheduling a refresh
+ *                from `receivedAt + expiresIn` uses only the client's own
+ *                elapsed time, so a device whose absolute clock is wrong still
+ *                refreshes correctly. Scheduling from `expiresAt` instead means
+ *                a browser an hour fast treats every fresh token as already
+ *                expired and re-mints forever.
+ *
+ * Dropping either one breaks the party that reads it. This is the same reason
+ * OAuth carries `expires_in` on the wire while the token itself carries `exp`.
+ *
+ * ⚠️ AND THE CLIENT IS NOT THE ENFORCER. Its margin is an optimisation to avoid
+ * a pointless round trip. A wrong clock, a tab asleep for an hour, or a modified
+ * client all defeat anything the client does, so the chat server rejects an
+ * expired token on its own.
+ */
+export declare const chatAuthTokenSchema: z.ZodObject<{
+    token: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    expiresIn: z.ZodNumber;
+    productId: z.ZodLiteral<"founder-circle">;
+}, z.core.$strip>;
+export type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;
+/**
+ * Asking our own backend for permission to start a conversation with somebody.
+ *
+ * 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.
+ */
+export declare const chatInvitationBodySchema: z.ZodObject<{
+    userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>;
+export type ChatInvitationBody = z.infer<typeof chatInvitationBodySchema>;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare const chatInvitationSchema: z.ZodObject<{
+    invitationToken: z.ZodString;
+}, z.core.$strip>;
+export type ChatInvitation = z.infer<typeof chatInvitationSchema>;
+//# sourceMappingURL=chat.d.ts.map

package/dist/chat.d.ts.map

@@ -0,0 +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"}

package/dist/chat.js

@@ -0,0 +1,146 @@
+/**
+ * founder-schema — Chat: config, auth token, invitation
+ *
+ * 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:
+ * when one server serves many tenants, the failure mode is SILENT. A push once
+ * returned success having sent nothing, because the caller held the wrong
+ * product's key and nothing in the exchange said which product it was for.
+ *
+ * So the rule these shapes exist to hold: TENANCY COMES FROM THE CREDENTIAL,
+ * never from a request body. The token says which product it is for, the chat
+ * server resolves the product from the token and from nothing else, and a
+ * Founder Circle token cannot address another product's conversation even when
+ * handed a valid-looking id.
+ *
+ * ⚠️ TEXT ONLY. There is deliberately no `callsEnabled` flag here, and its
+ * absence is the feature: the user ruled chat is text only, there is no call
+ * code to branch on, and the browser is told to deny camera and microphone
+ * outright. A boolean that can never be true is an invitation to turn it on.
+ *
+ * @module founder-schema/chat
+ */
+import { z } from 'zod';
+import { objectIdSchema } from './common.js';
+/**
+ * The product this package speaks for.
+ *
+ * Typed as a LITERAL on purpose. If the shared chat server ever hands back a
+ * config or a token minted for a different product, parsing fails loudly here
+ * rather than the client quietly talking to the wrong tenant. That is exactly
+ * the class of bug this file exists to prevent, so it should be impossible to
+ * carry past the first parse.
+ */
+export const CHAT_PRODUCT_ID = 'founder-circle';
+export const chatProductIdSchema = z.literal(CHAT_PRODUCT_ID);
+// ─── Config ──────────────────────────────────────────────────────────────────
+/**
+ * What the client needs before it can open a socket.
+ *
+ * ⚠️ `enabled` IS MANDATORY AND IS NOT DERIVED FROM `url`. "Messaging is not
+ * switched on yet" is a first-class state, not a failure: a 404 is the expected
+ * answer today, and the client collapses a disabled flag, a null url, a non-2xx
+ * and a thrown fetch to the same quiet "not on yet" rather than an error. If
+ * `enabled` were inferred from a missing url, "off" and "broken" would be the
+ * same wire shape and the inbox could not tell a member which one it was.
+ *
+ * ⚠️ `userId` is required and is the field nothing works without. The client
+ * needs to know WHO THE VIEWER IS to decide which side a bubble sits on, to
+ * filter the viewer out of presence and typing, to pick the other participant
+ * for a row's name and avatar, and to tell its own optimistic message from one
+ * echoed back. Without it every conversation renders as though the viewer were
+ * nobody. It was missing from the first sketch of this endpoint.
+ */
+export const chatConfigSchema = z.object({
+    enabled: z.boolean(),
+    /** Null whenever chat is not switched on. Never a placeholder string. */
+    url: z.url().nullable(),
+    /** The VIEWER's id, as the chat server knows them. */
+    userId: z.string(),
+    /** Which product this config is for. See `chatProductIdSchema`. */
+    productId: chatProductIdSchema,
+});
+// ─── Auth token ──────────────────────────────────────────────────────────────
+/**
+ * How long before expiry the client re-mints, in seconds.
+ *
+ * Exported because it is a contract detail and not an implementation one: a
+ * token handed over with two seconds left is a socket that authenticates and is
+ * closed again immediately, so the minting side needs to know the consuming
+ * side will not use the last minute of a token's life.
+ */
+export const CHAT_TOKEN_REFRESH_MARGIN_SECONDS = 60;
+/**
+ * How often the live socket re-authenticates, in seconds.
+ *
+ * Auth is an EVENT on the open socket rather than a handshake parameter, so
+ * re-authenticating does not drop the connection.
+ *
+ * ⚠️ THIS MUST STAY BELOW THE REAL TOKEN LIFETIME, by more than the refresh
+ * margin. It assumes a 15 minute token. A re-auth interval longer than the
+ * lifetime is a socket that dies every quarter of an hour with no explanation,
+ * and the symptom appears far from the cause. If the issued lifetime changes,
+ * this number moves with it or the two silently disagree.
+ */
+export const CHAT_SOCKET_REAUTH_SECONDS = 10 * 60;
+/**
+ * A short-lived token for the shared chat server.
+ *
+ * ⚠️ BOTH TIME FIELDS ARE KEPT, and they are not redundant, because two
+ * different parties read them with two different clocks:
+ *
+ *   `expiresAt`  an absolute instant, for the SERVER. The chat server holds the
+ *                authoritative clock and must reject an expired token on its
+ *                own, whatever any client believes.
+ *   `expiresIn`  a duration in seconds, for the CLIENT. Scheduling a refresh
+ *                from `receivedAt + expiresIn` uses only the client's own
+ *                elapsed time, so a device whose absolute clock is wrong still
+ *                refreshes correctly. Scheduling from `expiresAt` instead means
+ *                a browser an hour fast treats every fresh token as already
+ *                expired and re-mints forever.
+ *
+ * Dropping either one breaks the party that reads it. This is the same reason
+ * OAuth carries `expires_in` on the wire while the token itself carries `exp`.
+ *
+ * ⚠️ AND THE CLIENT IS NOT THE ENFORCER. Its margin is an optimisation to avoid
+ * a pointless round trip. A wrong clock, a tab asleep for an hour, or a modified
+ * client all defeat anything the client does, so the chat server rejects an
+ * expired token on its own.
+ */
+export const chatAuthTokenSchema = z.object({
+    token: z.string().min(1),
+    /** ISO 8601. Parsed with `Date.parse`, never an epoch number. */
+    expiresAt: z.iso.datetime(),
+    /** Seconds from issue. See the note above on why both exist. */
+    expiresIn: z.number().int().positive(),
+    /** The product this token is scoped to. A mismatch must fail loudly. */
+    productId: chatProductIdSchema,
+});
+// ─── Invitation ──────────────────────────────────────────────────────────────
+/**
+ * Asking our own backend for permission to start a conversation with somebody.
+ *
+ * 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.
+ */
+export const chatInvitationBodySchema = z.object({
+    /** The OTHER participant. The viewer is taken from the credential. */
+    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.
+ *
+ * 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.
+ */
+export const chatInvitationSchema = z.object({
+    invitationToken: z.string().min(1),
+});
+//# sourceMappingURL=chat.js.map

package/dist/chat.js.map

@@ -0,0 +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"]}