founder-schema 0.1.0 → 0.3.0

package/dist/uploads.js

@@ -0,0 +1,106 @@
+/**
+ * founder-schema — Uploads: the key a client carries, and asking for a slot
+ *
+ * Its own module so that both `feed` (a post's media) and `onboarding` (the
+ * avatar) can use the one key rule. It lived in `feed` until 0.2.0, and
+ * `onboarding` could not import it from there without a cycle (`feed` imports
+ * `onboarding` for the topic list), so the avatar key was a bare string and
+ * `'../../etc/passwd'` passed.
+ *
+ * Imports only the limits and the message keys.
+ *
+ * @module founder-schema/uploads
+ */
+import { z } from 'zod';
+import { UPLOAD_MAX_BYTES } from './limits.js';
+import { VALIDATION_MESSAGE } from './validation.js';
+/**
+ * ⚠ IMAGES ONLY, and that is a product decision rather than an oversight.
+ *
+ * The asymmetry was real and was raised: `feedVideoSchema` is in the read union
+ * and a card can render a video, while nothing could ever upload one. The user
+ * settled it on 2026-09-21: members upload images, and share video by putting a
+ * link in the post text, which the client renders inline. So the minter stays
+ * images-only by intent.
+ *
+ * `feedVideoSchema` is deliberately KEPT. Widening the write path later is
+ * additive; removing video from the read union once a client handles it is not.
+ * A test named for refusing a video key holds this visible, so whoever adds
+ * video uploads has to delete a test that says out loud why it exists.
+ */
+export const UPLOAD_KEY_EXTENSIONS = ['jpg', 'jpeg', 'png', 'webp', 'gif'];
+export const uploadKeyExtensionSchema = z.enum(UPLOAD_KEY_EXTENSIONS);
+/**
+ * The content type each extension is signed for, and the only types an
+ * attached object may turn out to have. The server signs the PUT with this
+ * type and refuses to attach an object whose stored type is anything else.
+ */
+export const UPLOAD_CONTENT_TYPES = {
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    webp: 'image/webp',
+    gif: 'image/gif',
+};
+export const UPLOAD_KEY_MAX_CHARS = 300;
+/**
+ * An attachment on the way IN is a KEY, never a URL. FORMAT, minted
+ * server-side and never by a client:
+ *
+ *     media/<userId>/<uuid>.<ext>
+ *
+ * Built from `UPLOAD_KEY_EXTENSIONS`, so the extension list exists once. The
+ * backend reads the owner segment with this same pattern.
+ *
+ * ⚠ THIS IS THE FIRST OF THREE CHECKS AND THE WEAKEST. It proves the key is
+ * well FORMED. It cannot prove the two things that actually matter:
+ *
+ *   1. OWNERSHIP. The `userId` segment is what makes "is this your object"
+ *      checkable, and the backend compares it against the authenticated caller.
+ *      A pattern happily accepts a well-formed key belonging to somebody else.
+ *   2. EXISTENCE. The backend reads the object before attaching it, so a key
+ *      for an object nobody uploaded cannot be committed.
+ */
+export const UPLOAD_KEY_PATTERN = new RegExp(`^media/[0-9a-f]{24}/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\.(${UPLOAD_KEY_EXTENSIONS.join('|')})$`);
+/**
+ * The length ceiling and the traversal refusal are redundant against the
+ * pattern, which is anchored and admits no dots outside the extension. They are
+ * kept on purpose: they are what still holds if the pattern is ever loosened.
+ */
+export const uploadKeySchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(UPLOAD_KEY_MAX_CHARS)
+    .regex(UPLOAD_KEY_PATTERN, VALIDATION_MESSAGE.uploadKeyInvalid)
+    .refine((k) => !k.includes('..'), { error: VALIDATION_MESSAGE.uploadKeyInvalid });
+/**
+ * Asking for an upload slot: `POST /api/v1/uploads/presign`.
+ *
+ * The server chooses the key (so it carries the caller's id), the content type
+ * and the expiry; a client that could name its own key could aim it at
+ * someone else's folder.
+ *
+ * `contentLength` is the file's exact size in bytes, and it is SIGNED INTO the
+ * URL: storage refuses a PUT whose body is any other size. Until 0.2.0 nothing
+ * capped the size at upload, so a member could put 40 MB into the bucket and
+ * only learn at attach time that it was refused.
+ */
+export const uploadPresignBodySchema = z.object({
+    extension: uploadKeyExtensionSchema,
+    contentLength: z.number().int().min(1).max(UPLOAD_MAX_BYTES),
+});
+/**
+ * The upload slot. `headers` are part of the signature, not advice: send every
+ * one of them verbatim on the PUT, with a body of exactly `contentLength`
+ * bytes, or storage answers with a signature mismatch. `key` is what a create
+ * body then carries, exactly as given.
+ */
+export const uploadPresignResponseSchema = z.object({
+    key: uploadKeySchema,
+    url: z.url(),
+    headers: z.record(z.string(), z.string()),
+    /** Seconds the URL stays valid. */
+    expiresIn: z.number().int().positive(),
+});
+//# sourceMappingURL=uploads.js.map

package/dist/uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["../src/uploads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAGtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;CACgD,CAAC;AAEnE,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,MAAM,CAC1C,uFAAuF,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAC3H,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,oBAAoB,CAAC;KACzB,KAAK,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,gBAAgB,CAAC;KAC9D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,kBAAkB,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAGpF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,SAAS,EAAE,wBAAwB;IACnC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;CAC7D,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,GAAG,EAAE,eAAe;IACpB,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IACzC,mCAAmC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC","sourcesContent":["/**\n * founder-schema — Uploads: the key a client carries, and asking for a slot\n *\n * Its own module so that both `feed` (a post's media) and `onboarding` (the\n * avatar) can use the one key rule. It lived in `feed` until 0.2.0, and\n * `onboarding` could not import it from there without a cycle (`feed` imports\n * `onboarding` for the topic list), so the avatar key was a bare string and\n * `'../../etc/passwd'` passed.\n *\n * Imports only the limits and the message keys.\n *\n * @module founder-schema/uploads\n */\n\nimport { z } from 'zod';\nimport { UPLOAD_MAX_BYTES } from './limits.js';\nimport { VALIDATION_MESSAGE } from './validation.js';\n\n/**\n * ⚠ IMAGES ONLY, and that is a product decision rather than an oversight.\n *\n * The asymmetry was real and was raised: `feedVideoSchema` is in the read union\n * and a card can render a video, while nothing could ever upload one. The user\n * settled it on 2026-09-21: members upload images, and share video by putting a\n * link in the post text, which the client renders inline. So the minter stays\n * images-only by intent.\n *\n * `feedVideoSchema` is deliberately KEPT. Widening the write path later is\n * additive; removing video from the read union once a client handles it is not.\n * A test named for refusing a video key holds this visible, so whoever adds\n * video uploads has to delete a test that says out loud why it exists.\n */\nexport const UPLOAD_KEY_EXTENSIONS = ['jpg', 'jpeg', 'png', 'webp', 'gif'] as const;\nexport const uploadKeyExtensionSchema = z.enum(UPLOAD_KEY_EXTENSIONS);\nexport type UploadKeyExtension = z.infer<typeof uploadKeyExtensionSchema>;\n\n/**\n * The content type each extension is signed for, and the only types an\n * attached object may turn out to have. The server signs the PUT with this\n * type and refuses to attach an object whose stored type is anything else.\n */\nexport const UPLOAD_CONTENT_TYPES = {\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  png: 'image/png',\n  webp: 'image/webp',\n  gif: 'image/gif',\n} as const satisfies Record<UploadKeyExtension, `image/${string}`>;\n\nexport const UPLOAD_KEY_MAX_CHARS = 300;\n\n/**\n * An attachment on the way IN is a KEY, never a URL. FORMAT, minted\n * server-side and never by a client:\n *\n *     media/<userId>/<uuid>.<ext>\n *\n * Built from `UPLOAD_KEY_EXTENSIONS`, so the extension list exists once. The\n * backend reads the owner segment with this same pattern.\n *\n * ⚠ THIS IS THE FIRST OF THREE CHECKS AND THE WEAKEST. It proves the key is\n * well FORMED. It cannot prove the two things that actually matter:\n *\n *   1. OWNERSHIP. The `userId` segment is what makes \"is this your object\"\n *      checkable, and the backend compares it against the authenticated caller.\n *      A pattern happily accepts a well-formed key belonging to somebody else.\n *   2. EXISTENCE. The backend reads the object before attaching it, so a key\n *      for an object nobody uploaded cannot be committed.\n */\nexport const UPLOAD_KEY_PATTERN = new RegExp(\n  `^media/[0-9a-f]{24}/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\\\.(${UPLOAD_KEY_EXTENSIONS.join('|')})$`,\n);\n\n/**\n * The length ceiling and the traversal refusal are redundant against the\n * pattern, which is anchored and admits no dots outside the extension. They are\n * kept on purpose: they are what still holds if the pattern is ever loosened.\n */\nexport const uploadKeySchema = z\n  .string()\n  .trim()\n  .min(1)\n  .max(UPLOAD_KEY_MAX_CHARS)\n  .regex(UPLOAD_KEY_PATTERN, VALIDATION_MESSAGE.uploadKeyInvalid)\n  .refine((k) => !k.includes('..'), { error: VALIDATION_MESSAGE.uploadKeyInvalid });\nexport type UploadKey = z.infer<typeof uploadKeySchema>;\n\n/**\n * Asking for an upload slot: `POST /api/v1/uploads/presign`.\n *\n * The server chooses the key (so it carries the caller's id), the content type\n * and the expiry; a client that could name its own key could aim it at\n * someone else's folder.\n *\n * `contentLength` is the file's exact size in bytes, and it is SIGNED INTO the\n * URL: storage refuses a PUT whose body is any other size. Until 0.2.0 nothing\n * capped the size at upload, so a member could put 40 MB into the bucket and\n * only learn at attach time that it was refused.\n */\nexport const uploadPresignBodySchema = z.object({\n  extension: uploadKeyExtensionSchema,\n  contentLength: z.number().int().min(1).max(UPLOAD_MAX_BYTES),\n});\nexport type UploadPresignBody = z.infer<typeof uploadPresignBodySchema>;\n\n/**\n * The upload slot. `headers` are part of the signature, not advice: send every\n * one of them verbatim on the PUT, with a body of exactly `contentLength`\n * bytes, or storage answers with a signature mismatch. `key` is what a create\n * body then carries, exactly as given.\n */\nexport const uploadPresignResponseSchema = z.object({\n  key: uploadKeySchema,\n  url: z.url(),\n  headers: z.record(z.string(), z.string()),\n  /** Seconds the URL stays valid. */\n  expiresIn: z.number().int().positive(),\n});\nexport type UploadPresignResponse = z.infer<typeof uploadPresignResponseSchema>;\n"]}

package/dist/validation.d.ts

@@ -0,0 +1,136 @@
+/**
+ * founder-schema — How a validation failure is described, on both sides
+ *
+ * TWO RULES, and they are what let the web client show any error, its own or
+ * the server's, on the right field in the member's language:
+ *
+ *  1. A CUSTOM MESSAGE IS A KEY, NEVER A SENTENCE. Where a schema needs its own
+ *     message (a refine, a regex), the message is one of `VALIDATION_MESSAGE`,
+ *     such as `phoneInvalid`. The client turns the key into text in English or
+ *     Hindi. Before 0.2.0 these were English sentences, so a Hindi screen showed
+ *     an English error, and a client that wanted to translate one had to match
+ *     on the wording.
+ *
+ *     Plain bounds carry NO custom message. `.min(1)` and `.max(80)` produce
+ *     Zod's own `too_small` / `too_big` issues, which already say which bound
+ *     and what it was (`minimum`, `maximum`, `origin`), and the client words
+ *     them from those. A hand-written "at most 80 characters" would only
+ *     restate the number in one language.
+ *
+ *  2. THE SERVER SENDS EVERY ISSUE, IN THIS SHAPE. A 400 answers with
+ *     `error.details.issues`, built by `toValidationIssues`, so the client can
+ *     put each one under its field. Until 0.2.0 the backend sent only the
+ *     first issue's message, with no path at all.
+ *
+ * ⚠️ `toValidationIssues` COPIES A WHITELIST OF FIELDS, it never spreads an
+ * issue. Zod can carry the rejected `input` on an issue, and these bodies hold a
+ * date of birth and a phone number. Echoing them into an error response sends
+ * them back to the client, into logs and into any proxy in between. A test
+ * proves `input` never survives.
+ *
+ * @module founder-schema/validation
+ */
+import { z } from 'zod';
+/**
+ * Every custom message a schema in this package can produce. Each is a
+ * translation key the clients define in every language they ship.
+ *
+ * ⚠️ Append only, and add the translation in the same change. Renaming one
+ * shows the raw key to every member until each client ships the new name.
+ */
+export declare const VALIDATION_MESSAGE: {
+    /** Not a 24-hex Mongo id. */
+    readonly invalidId: "invalidId";
+    /** Handle: wrong characters, or a dot in the wrong place. */
+    readonly usernameInvalid: "usernameInvalid";
+    /** Not a 10-digit Indian mobile number. */
+    readonly phoneInvalid: "phoneInvalid";
+    /** Not a `YYYY-MM-DD` date. */
+    readonly dateInvalid: "dateInvalid";
+    /** A date that does not exist, such as 30 February. */
+    readonly dobInvalid: "dobInvalid";
+    /** Under the minimum age. */
+    readonly dobUnderAge: "dobUnderAge";
+    /** Over the sanity ceiling: almost always a mistyped year. */
+    readonly dobTooOld: "dobTooOld";
+    /** A founding year after this year. */
+    readonly foundedYearFuture: "foundedYearFuture";
+    /** An upload key that is not one this product mints. */
+    readonly uploadKeyInvalid: "uploadKeyInvalid";
+    /** A post with neither text nor media. */
+    readonly postEmpty: "postEmpty";
+    /** Two poll options with the same label. */
+    readonly pollOptionsDuplicate: "pollOptionsDuplicate";
+    /** An empty string sent to clear a patch field; clearing is `null`. */
+    readonly clearWithNull: "clearWithNull";
+    /** Not a plain http(s) URL on a real domain (`javascript:`, `localhost`, an IP...). */
+    readonly urlInvalid: "urlInvalid";
+    /** A handle this product keeps for itself (`admin`, `support`...). */
+    readonly usernameReserved: "usernameReserved";
+    /** Agreed to a version of the guidelines that is not the current one. */
+    readonly guidelinesOutdated: "guidelinesOutdated";
+};
+export type ValidationMessageKey = (typeof VALIDATION_MESSAGE)[keyof typeof VALIDATION_MESSAGE];
+/**
+ * Which part of the request an issue is about.
+ *
+ * ONE PATH CONVENTION: `path` is ALWAYS relative to this part, so a body field
+ * reads `['venture', 'name']` with `location: 'body'`, never
+ * `['body', 'venture', 'name']`. A form maps body issues straight onto its
+ * fields without stripping a prefix, and a client that sees `query` or
+ * `params` knows the problem is the URL, not anything the member typed.
+ */
+export declare const REQUEST_PART_VALUES: readonly ["body", "query", "params"];
+export declare const requestPartSchema: z.ZodEnum<{
+    body: "body";
+    query: "query";
+    params: "params";
+}>;
+export type RequestPart = z.infer<typeof requestPartSchema>;
+/**
+ * One problem with one field, as it crosses the wire.
+ *
+ * `code` is Zod's issue code (`too_small`, `too_big`, `invalid_type`,
+ * `invalid_format`, `custom`...). `message` is either one of
+ * `VALIDATION_MESSAGE` or, for a plain bound, Zod's own English text, which the
+ * client ignores in favour of `code` plus `minimum` / `maximum`.
+ */
+export declare const validationIssueSchema: z.ZodObject<{
+    location: z.ZodOptional<z.ZodEnum<{
+        body: "body";
+        query: "query";
+        params: "params";
+    }>>;
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    code: z.ZodString;
+    message: z.ZodString;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    origin: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ValidationIssue = z.infer<typeof validationIssueSchema>;
+/** The loosest shape this needs from a Zod issue, so it works across 4.x. */
+interface ZodIssueLike {
+    path: readonly PropertyKey[];
+    code: string;
+    message: string;
+    minimum?: unknown;
+    maximum?: unknown;
+    origin?: unknown;
+    format?: unknown;
+}
+/**
+ * A Zod error as the wire shape. Use this on the server for every 400, and on
+ * the client to treat its own errors and the server's the same way.
+ *
+ * `location` is stamped on every issue when given; the server always gives it.
+ *
+ * Copies a WHITELIST of fields (see the module note). A path segment that is a
+ * symbol, which JSON cannot carry, becomes its description.
+ */
+export declare function toValidationIssues(error: {
+    issues: readonly ZodIssueLike[];
+}, location?: RequestPart): ValidationIssue[];
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;IAC7B,6BAA6B;;IAE7B,6DAA6D;;IAE7D,2CAA2C;;IAE3C,+BAA+B;;IAE/B,uDAAuD;;IAEvD,6BAA6B;;IAE7B,8DAA8D;;IAE9D,uCAAuC;;IAEvC,wDAAwD;;IAExD,0CAA0C;;IAE1C,4CAA4C;;IAE5C,uEAAuE;;IAEvE,uFAAuF;;IAEvF,sEAAsE;;IAEtE,yEAAyE;;CAEjE,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAEhG;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,sCAAuC,CAAC;AACxE,eAAO,MAAM,iBAAiB;;;;EAA8B,CAAC;AAC7D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAkBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,6EAA6E;AAC7E,UAAU,YAAY;IACpB,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAKD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,EAC1C,QAAQ,CAAC,EAAE,WAAW,GACrB,eAAe,EAAE,CAkBnB"}

package/dist/validation.js

@@ -0,0 +1,142 @@
+/**
+ * founder-schema — How a validation failure is described, on both sides
+ *
+ * TWO RULES, and they are what let the web client show any error, its own or
+ * the server's, on the right field in the member's language:
+ *
+ *  1. A CUSTOM MESSAGE IS A KEY, NEVER A SENTENCE. Where a schema needs its own
+ *     message (a refine, a regex), the message is one of `VALIDATION_MESSAGE`,
+ *     such as `phoneInvalid`. The client turns the key into text in English or
+ *     Hindi. Before 0.2.0 these were English sentences, so a Hindi screen showed
+ *     an English error, and a client that wanted to translate one had to match
+ *     on the wording.
+ *
+ *     Plain bounds carry NO custom message. `.min(1)` and `.max(80)` produce
+ *     Zod's own `too_small` / `too_big` issues, which already say which bound
+ *     and what it was (`minimum`, `maximum`, `origin`), and the client words
+ *     them from those. A hand-written "at most 80 characters" would only
+ *     restate the number in one language.
+ *
+ *  2. THE SERVER SENDS EVERY ISSUE, IN THIS SHAPE. A 400 answers with
+ *     `error.details.issues`, built by `toValidationIssues`, so the client can
+ *     put each one under its field. Until 0.2.0 the backend sent only the
+ *     first issue's message, with no path at all.
+ *
+ * ⚠️ `toValidationIssues` COPIES A WHITELIST OF FIELDS, it never spreads an
+ * issue. Zod can carry the rejected `input` on an issue, and these bodies hold a
+ * date of birth and a phone number. Echoing them into an error response sends
+ * them back to the client, into logs and into any proxy in between. A test
+ * proves `input` never survives.
+ *
+ * @module founder-schema/validation
+ */
+import { z } from 'zod';
+/**
+ * Every custom message a schema in this package can produce. Each is a
+ * translation key the clients define in every language they ship.
+ *
+ * ⚠️ Append only, and add the translation in the same change. Renaming one
+ * shows the raw key to every member until each client ships the new name.
+ */
+export const VALIDATION_MESSAGE = {
+    /** Not a 24-hex Mongo id. */
+    invalidId: 'invalidId',
+    /** Handle: wrong characters, or a dot in the wrong place. */
+    usernameInvalid: 'usernameInvalid',
+    /** Not a 10-digit Indian mobile number. */
+    phoneInvalid: 'phoneInvalid',
+    /** Not a `YYYY-MM-DD` date. */
+    dateInvalid: 'dateInvalid',
+    /** A date that does not exist, such as 30 February. */
+    dobInvalid: 'dobInvalid',
+    /** Under the minimum age. */
+    dobUnderAge: 'dobUnderAge',
+    /** Over the sanity ceiling: almost always a mistyped year. */
+    dobTooOld: 'dobTooOld',
+    /** A founding year after this year. */
+    foundedYearFuture: 'foundedYearFuture',
+    /** An upload key that is not one this product mints. */
+    uploadKeyInvalid: 'uploadKeyInvalid',
+    /** A post with neither text nor media. */
+    postEmpty: 'postEmpty',
+    /** Two poll options with the same label. */
+    pollOptionsDuplicate: 'pollOptionsDuplicate',
+    /** An empty string sent to clear a patch field; clearing is `null`. */
+    clearWithNull: 'clearWithNull',
+    /** Not a plain http(s) URL on a real domain (`javascript:`, `localhost`, an IP...). */
+    urlInvalid: 'urlInvalid',
+    /** A handle this product keeps for itself (`admin`, `support`...). */
+    usernameReserved: 'usernameReserved',
+    /** Agreed to a version of the guidelines that is not the current one. */
+    guidelinesOutdated: 'guidelinesOutdated',
+};
+/**
+ * Which part of the request an issue is about.
+ *
+ * ONE PATH CONVENTION: `path` is ALWAYS relative to this part, so a body field
+ * reads `['venture', 'name']` with `location: 'body'`, never
+ * `['body', 'venture', 'name']`. A form maps body issues straight onto its
+ * fields without stripping a prefix, and a client that sees `query` or
+ * `params` knows the problem is the URL, not anything the member typed.
+ */
+export const REQUEST_PART_VALUES = ['body', 'query', 'params'];
+export const requestPartSchema = z.enum(REQUEST_PART_VALUES);
+/**
+ * One problem with one field, as it crosses the wire.
+ *
+ * `code` is Zod's issue code (`too_small`, `too_big`, `invalid_type`,
+ * `invalid_format`, `custom`...). `message` is either one of
+ * `VALIDATION_MESSAGE` or, for a plain bound, Zod's own English text, which the
+ * client ignores in favour of `code` plus `minimum` / `maximum`.
+ */
+export const validationIssueSchema = z.object({
+    /** Set by the server on every issue it sends; absent on a client's own parse. */
+    location: requestPartSchema.optional(),
+    /**
+     * Where the problem is, RELATIVE TO `location`: `['venture', 'name']`,
+     * `['options', 2, 'label']`, `['contentId']`.
+     */
+    path: z.array(z.union([z.string(), z.number()])),
+    code: z.string(),
+    message: z.string(),
+    /** `too_small`: the bound that was missed. */
+    minimum: z.number().optional(),
+    /** `too_big`: the bound that was passed. */
+    maximum: z.number().optional(),
+    /** What was measured: `string`, `array`, `number`... */
+    origin: z.string().optional(),
+    /** `invalid_format`: which format, e.g. `url`, `regex`, `email`. */
+    format: z.string().optional(),
+});
+const toNumber = (v) => typeof v === 'number' ? v : typeof v === 'bigint' ? Number(v) : undefined;
+/**
+ * A Zod error as the wire shape. Use this on the server for every 400, and on
+ * the client to treat its own errors and the server's the same way.
+ *
+ * `location` is stamped on every issue when given; the server always gives it.
+ *
+ * Copies a WHITELIST of fields (see the module note). A path segment that is a
+ * symbol, which JSON cannot carry, becomes its description.
+ */
+export function toValidationIssues(error, location) {
+    return error.issues.map((issue) => {
+        const out = {
+            ...(location ? { location } : {}),
+            path: issue.path.map((p) => typeof p === 'number' ? p : typeof p === 'string' ? p : String(p.description ?? '')),
+            code: issue.code,
+            message: issue.message,
+        };
+        const minimum = toNumber(issue.minimum);
+        const maximum = toNumber(issue.maximum);
+        if (minimum !== undefined)
+            out.minimum = minimum;
+        if (maximum !== undefined)
+            out.maximum = maximum;
+        if (typeof issue.origin === 'string')
+            out.origin = issue.origin;
+        if (typeof issue.format === 'string')
+            out.format = issue.format;
+        return out;
+    });
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * founder-schema — How a validation failure is described, on both sides\n *\n * TWO RULES, and they are what let the web client show any error, its own or\n * the server's, on the right field in the member's language:\n *\n *  1. A CUSTOM MESSAGE IS A KEY, NEVER A SENTENCE. Where a schema needs its own\n *     message (a refine, a regex), the message is one of `VALIDATION_MESSAGE`,\n *     such as `phoneInvalid`. The client turns the key into text in English or\n *     Hindi. Before 0.2.0 these were English sentences, so a Hindi screen showed\n *     an English error, and a client that wanted to translate one had to match\n *     on the wording.\n *\n *     Plain bounds carry NO custom message. `.min(1)` and `.max(80)` produce\n *     Zod's own `too_small` / `too_big` issues, which already say which bound\n *     and what it was (`minimum`, `maximum`, `origin`), and the client words\n *     them from those. A hand-written \"at most 80 characters\" would only\n *     restate the number in one language.\n *\n *  2. THE SERVER SENDS EVERY ISSUE, IN THIS SHAPE. A 400 answers with\n *     `error.details.issues`, built by `toValidationIssues`, so the client can\n *     put each one under its field. Until 0.2.0 the backend sent only the\n *     first issue's message, with no path at all.\n *\n * ⚠️ `toValidationIssues` COPIES A WHITELIST OF FIELDS, it never spreads an\n * issue. Zod can carry the rejected `input` on an issue, and these bodies hold a\n * date of birth and a phone number. Echoing them into an error response sends\n * them back to the client, into logs and into any proxy in between. A test\n * proves `input` never survives.\n *\n * @module founder-schema/validation\n */\n\nimport { z } from 'zod';\n\n/**\n * Every custom message a schema in this package can produce. Each is a\n * translation key the clients define in every language they ship.\n *\n * ⚠️ Append only, and add the translation in the same change. Renaming one\n * shows the raw key to every member until each client ships the new name.\n */\nexport const VALIDATION_MESSAGE = {\n  /** Not a 24-hex Mongo id. */\n  invalidId: 'invalidId',\n  /** Handle: wrong characters, or a dot in the wrong place. */\n  usernameInvalid: 'usernameInvalid',\n  /** Not a 10-digit Indian mobile number. */\n  phoneInvalid: 'phoneInvalid',\n  /** Not a `YYYY-MM-DD` date. */\n  dateInvalid: 'dateInvalid',\n  /** A date that does not exist, such as 30 February. */\n  dobInvalid: 'dobInvalid',\n  /** Under the minimum age. */\n  dobUnderAge: 'dobUnderAge',\n  /** Over the sanity ceiling: almost always a mistyped year. */\n  dobTooOld: 'dobTooOld',\n  /** A founding year after this year. */\n  foundedYearFuture: 'foundedYearFuture',\n  /** An upload key that is not one this product mints. */\n  uploadKeyInvalid: 'uploadKeyInvalid',\n  /** A post with neither text nor media. */\n  postEmpty: 'postEmpty',\n  /** Two poll options with the same label. */\n  pollOptionsDuplicate: 'pollOptionsDuplicate',\n  /** An empty string sent to clear a patch field; clearing is `null`. */\n  clearWithNull: 'clearWithNull',\n  /** Not a plain http(s) URL on a real domain (`javascript:`, `localhost`, an IP...). */\n  urlInvalid: 'urlInvalid',\n  /** A handle this product keeps for itself (`admin`, `support`...). */\n  usernameReserved: 'usernameReserved',\n  /** Agreed to a version of the guidelines that is not the current one. */\n  guidelinesOutdated: 'guidelinesOutdated',\n} as const;\nexport type ValidationMessageKey = (typeof VALIDATION_MESSAGE)[keyof typeof VALIDATION_MESSAGE];\n\n/**\n * Which part of the request an issue is about.\n *\n * ONE PATH CONVENTION: `path` is ALWAYS relative to this part, so a body field\n * reads `['venture', 'name']` with `location: 'body'`, never\n * `['body', 'venture', 'name']`. A form maps body issues straight onto its\n * fields without stripping a prefix, and a client that sees `query` or\n * `params` knows the problem is the URL, not anything the member typed.\n */\nexport const REQUEST_PART_VALUES = ['body', 'query', 'params'] as const;\nexport const requestPartSchema = z.enum(REQUEST_PART_VALUES);\nexport type RequestPart = z.infer<typeof requestPartSchema>;\n\n/**\n * One problem with one field, as it crosses the wire.\n *\n * `code` is Zod's issue code (`too_small`, `too_big`, `invalid_type`,\n * `invalid_format`, `custom`...). `message` is either one of\n * `VALIDATION_MESSAGE` or, for a plain bound, Zod's own English text, which the\n * client ignores in favour of `code` plus `minimum` / `maximum`.\n */\nexport const validationIssueSchema = z.object({\n  /** Set by the server on every issue it sends; absent on a client's own parse. */\n  location: requestPartSchema.optional(),\n  /**\n   * Where the problem is, RELATIVE TO `location`: `['venture', 'name']`,\n   * `['options', 2, 'label']`, `['contentId']`.\n   */\n  path: z.array(z.union([z.string(), z.number()])),\n  code: z.string(),\n  message: z.string(),\n  /** `too_small`: the bound that was missed. */\n  minimum: z.number().optional(),\n  /** `too_big`: the bound that was passed. */\n  maximum: z.number().optional(),\n  /** What was measured: `string`, `array`, `number`... */\n  origin: z.string().optional(),\n  /** `invalid_format`: which format, e.g. `url`, `regex`, `email`. */\n  format: z.string().optional(),\n});\nexport type ValidationIssue = z.infer<typeof validationIssueSchema>;\n\n/** The loosest shape this needs from a Zod issue, so it works across 4.x. */\ninterface ZodIssueLike {\n  path: readonly PropertyKey[];\n  code: string;\n  message: string;\n  minimum?: unknown;\n  maximum?: unknown;\n  origin?: unknown;\n  format?: unknown;\n}\n\nconst toNumber = (v: unknown): number | undefined =>\n  typeof v === 'number' ? v : typeof v === 'bigint' ? Number(v) : undefined;\n\n/**\n * A Zod error as the wire shape. Use this on the server for every 400, and on\n * the client to treat its own errors and the server's the same way.\n *\n * `location` is stamped on every issue when given; the server always gives it.\n *\n * Copies a WHITELIST of fields (see the module note). A path segment that is a\n * symbol, which JSON cannot carry, becomes its description.\n */\nexport function toValidationIssues(\n  error: { issues: readonly ZodIssueLike[] },\n  location?: RequestPart,\n): ValidationIssue[] {\n  return error.issues.map((issue) => {\n    const out: ValidationIssue = {\n      ...(location ? { location } : {}),\n      path: issue.path.map((p) =>\n        typeof p === 'number' ? p : typeof p === 'string' ? p : String(p.description ?? ''),\n      ),\n      code: issue.code,\n      message: issue.message,\n    };\n    const minimum = toNumber(issue.minimum);\n    const maximum = toNumber(issue.maximum);\n    if (minimum !== undefined) out.minimum = minimum;\n    if (maximum !== undefined) out.maximum = maximum;\n    if (typeof issue.origin === 'string') out.origin = issue.origin;\n    if (typeof issue.format === 'string') out.format = issue.format;\n    return out;\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "founder-schema",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared Zod schemas for Founder Circle — single source of truth for API contracts, validation, and TypeScript types (backend + web client + app client).",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,10 @@
     "test:watch": "vitest",
     "lint": "biome lint .",
     "format": "biome format --write .",
-    "check": "npm run type-check && biome check --write .",
+    "check": "npm run type-check && biome check .",
+    "check:fix": "npm run type-check && biome check --write .",
     "check:staged": "biome check --staged --write --no-errors-on-unmatched",
-    "prepublishOnly": "npm run build && npm run check"
+    "prepublishOnly": "npm run check && npm test && npm run build"
   },
   "keywords": [
     "zod",