founder-schema 0.10.0 → 0.12.0

package/dist/domains/billing/gst.d.ts

@@ -0,0 +1,229 @@
+/**
+ * founder-schema: GST, the states and the GSTIN (0.12.0)
+ *
+ * Its own module so both the billing contract and a member's membership
+ * (the billing details they last used, to prefill a checkout) can use it
+ * without importing each other.
+ *
+ * @module founder-schema/domains/billing/gst
+ */
+import { z } from 'zod';
+/**
+ * India's states and union territories by their GST state code, the first
+ * two digits of every GSTIN registered there. The current codes only: 25
+ * (Daman and Diu) merged into 26 in 2020, and 28 (undivided Andhra Pradesh)
+ * gave way to 37.
+ */
+export declare const GST_STATES: readonly [{
+    readonly code: "01";
+    readonly name: "Jammu and Kashmir";
+}, {
+    readonly code: "02";
+    readonly name: "Himachal Pradesh";
+}, {
+    readonly code: "03";
+    readonly name: "Punjab";
+}, {
+    readonly code: "04";
+    readonly name: "Chandigarh";
+}, {
+    readonly code: "05";
+    readonly name: "Uttarakhand";
+}, {
+    readonly code: "06";
+    readonly name: "Haryana";
+}, {
+    readonly code: "07";
+    readonly name: "Delhi";
+}, {
+    readonly code: "08";
+    readonly name: "Rajasthan";
+}, {
+    readonly code: "09";
+    readonly name: "Uttar Pradesh";
+}, {
+    readonly code: "10";
+    readonly name: "Bihar";
+}, {
+    readonly code: "11";
+    readonly name: "Sikkim";
+}, {
+    readonly code: "12";
+    readonly name: "Arunachal Pradesh";
+}, {
+    readonly code: "13";
+    readonly name: "Nagaland";
+}, {
+    readonly code: "14";
+    readonly name: "Manipur";
+}, {
+    readonly code: "15";
+    readonly name: "Mizoram";
+}, {
+    readonly code: "16";
+    readonly name: "Tripura";
+}, {
+    readonly code: "17";
+    readonly name: "Meghalaya";
+}, {
+    readonly code: "18";
+    readonly name: "Assam";
+}, {
+    readonly code: "19";
+    readonly name: "West Bengal";
+}, {
+    readonly code: "20";
+    readonly name: "Jharkhand";
+}, {
+    readonly code: "21";
+    readonly name: "Odisha";
+}, {
+    readonly code: "22";
+    readonly name: "Chhattisgarh";
+}, {
+    readonly code: "23";
+    readonly name: "Madhya Pradesh";
+}, {
+    readonly code: "24";
+    readonly name: "Gujarat";
+}, {
+    readonly code: "26";
+    readonly name: "Dadra and Nagar Haveli and Daman and Diu";
+}, {
+    readonly code: "27";
+    readonly name: "Maharashtra";
+}, {
+    readonly code: "29";
+    readonly name: "Karnataka";
+}, {
+    readonly code: "30";
+    readonly name: "Goa";
+}, {
+    readonly code: "31";
+    readonly name: "Lakshadweep";
+}, {
+    readonly code: "32";
+    readonly name: "Kerala";
+}, {
+    readonly code: "33";
+    readonly name: "Tamil Nadu";
+}, {
+    readonly code: "34";
+    readonly name: "Puducherry";
+}, {
+    readonly code: "35";
+    readonly name: "Andaman and Nicobar Islands";
+}, {
+    readonly code: "36";
+    readonly name: "Telangana";
+}, {
+    readonly code: "37";
+    readonly name: "Andhra Pradesh";
+}, {
+    readonly code: "38";
+    readonly name: "Ladakh";
+}];
+export type GstStateCode = (typeof GST_STATES)[number]['code'];
+export declare const GST_STATE_CODE_VALUES: [GstStateCode, ...GstStateCode[]];
+export declare const gstStateCodeSchema: z.ZodEnum<{
+    "01": "01";
+    "02": "02";
+    "03": "03";
+    "04": "04";
+    "05": "05";
+    "06": "06";
+    "07": "07";
+    "08": "08";
+    "09": "09";
+    10: "10";
+    11: "11";
+    12: "12";
+    13: "13";
+    14: "14";
+    15: "15";
+    16: "16";
+    17: "17";
+    18: "18";
+    19: "19";
+    20: "20";
+    21: "21";
+    22: "22";
+    23: "23";
+    24: "24";
+    26: "26";
+    27: "27";
+    29: "29";
+    30: "30";
+    31: "31";
+    32: "32";
+    33: "33";
+    34: "34";
+    35: "35";
+    36: "36";
+    37: "37";
+    38: "38";
+}>;
+/** The state's name for its code, as an invoice prints it. */
+export declare function gstStateName(code: GstStateCode): string;
+/** GST is 18% on these services, inside every price. */
+export declare const GST_RATE_PERCENT = 18;
+/**
+ * Whether a GSTIN's 15th character is the check character of the first 14
+ * (the GSTN's base-36 Luhn variant). Catches a mistyped digit, which the
+ * pattern alone does not: a B2B invoice with a wrong GSTIN costs the buyer
+ * their input credit.
+ */
+export declare function gstinChecksumValid(gstin: string): boolean;
+/** A GSTIN, upper-cased, pattern AND check character. */
+export declare const gstinSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * Who is buying, for the invoice. The state is the place of supply and
+ * decides the tax. With a GSTIN (a business claiming input credit) the
+ * invoice is B2B: it must carry the buyer's legal name and address, and the
+ * state is the GSTIN's own.
+ */
+export declare const billingDetailsSchema: z.ZodObject<{
+    stateCode: z.ZodEnum<{
+        "01": "01";
+        "02": "02";
+        "03": "03";
+        "04": "04";
+        "05": "05";
+        "06": "06";
+        "07": "07";
+        "08": "08";
+        "09": "09";
+        10: "10";
+        11: "11";
+        12: "12";
+        13: "13";
+        14: "14";
+        15: "15";
+        16: "16";
+        17: "17";
+        18: "18";
+        19: "19";
+        20: "20";
+        21: "21";
+        22: "22";
+        23: "23";
+        24: "24";
+        26: "26";
+        27: "27";
+        29: "29";
+        30: "30";
+        31: "31";
+        32: "32";
+        33: "33";
+        34: "34";
+        35: "35";
+        36: "36";
+        37: "37";
+        38: "38";
+    }>;
+    gstin: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    legalName: z.ZodOptional<z.ZodString>;
+    address: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BillingDetails = z.infer<typeof billingDetailsSchema>;
+//# sourceMappingURL=gst.d.ts.map

package/dist/domains/billing/gst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gst.d.ts","sourceRoot":"","sources":["../../../src/domains/billing/gst.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqCb,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/D,eAAO,MAAM,qBAAqB,EAAoC,CACpE,YAAY,EACZ,GAAG,YAAY,EAAE,CAClB,CAAC;AACF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAgC,CAAC;AAEhE,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEvD;AAED,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAKnC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUzD;AAED,yDAAyD;AACzD,eAAO,MAAM,WAAW,wDAIiD,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkB7B,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/domains/billing/gst.js

@@ -0,0 +1,117 @@
+/**
+ * founder-schema: GST, the states and the GSTIN (0.12.0)
+ *
+ * Its own module so both the billing contract and a member's membership
+ * (the billing details they last used, to prefill a checkout) can use it
+ * without importing each other.
+ *
+ * @module founder-schema/domains/billing/gst
+ */
+import { z } from 'zod';
+import { BILLING_ADDRESS_MAX, BILLING_NAME_MAX } from '../../core/limits.js';
+import { VALIDATION_MESSAGE } from '../../core/validation.js';
+// ─── GST: states and the GSTIN ───────────────────────────────────────────────
+/**
+ * India's states and union territories by their GST state code, the first
+ * two digits of every GSTIN registered there. The current codes only: 25
+ * (Daman and Diu) merged into 26 in 2020, and 28 (undivided Andhra Pradesh)
+ * gave way to 37.
+ */
+export const GST_STATES = [
+    { code: '01', name: 'Jammu and Kashmir' },
+    { code: '02', name: 'Himachal Pradesh' },
+    { code: '03', name: 'Punjab' },
+    { code: '04', name: 'Chandigarh' },
+    { code: '05', name: 'Uttarakhand' },
+    { code: '06', name: 'Haryana' },
+    { code: '07', name: 'Delhi' },
+    { code: '08', name: 'Rajasthan' },
+    { code: '09', name: 'Uttar Pradesh' },
+    { code: '10', name: 'Bihar' },
+    { code: '11', name: 'Sikkim' },
+    { code: '12', name: 'Arunachal Pradesh' },
+    { code: '13', name: 'Nagaland' },
+    { code: '14', name: 'Manipur' },
+    { code: '15', name: 'Mizoram' },
+    { code: '16', name: 'Tripura' },
+    { code: '17', name: 'Meghalaya' },
+    { code: '18', name: 'Assam' },
+    { code: '19', name: 'West Bengal' },
+    { code: '20', name: 'Jharkhand' },
+    { code: '21', name: 'Odisha' },
+    { code: '22', name: 'Chhattisgarh' },
+    { code: '23', name: 'Madhya Pradesh' },
+    { code: '24', name: 'Gujarat' },
+    { code: '26', name: 'Dadra and Nagar Haveli and Daman and Diu' },
+    { code: '27', name: 'Maharashtra' },
+    { code: '29', name: 'Karnataka' },
+    { code: '30', name: 'Goa' },
+    { code: '31', name: 'Lakshadweep' },
+    { code: '32', name: 'Kerala' },
+    { code: '33', name: 'Tamil Nadu' },
+    { code: '34', name: 'Puducherry' },
+    { code: '35', name: 'Andaman and Nicobar Islands' },
+    { code: '36', name: 'Telangana' },
+    { code: '37', name: 'Andhra Pradesh' },
+    { code: '38', name: 'Ladakh' },
+];
+export const GST_STATE_CODE_VALUES = GST_STATES.map((s) => s.code);
+export const gstStateCodeSchema = z.enum(GST_STATE_CODE_VALUES);
+/** The state's name for its code, as an invoice prints it. */
+export function gstStateName(code) {
+    return GST_STATES.find((s) => s.code === code)?.name ?? code;
+}
+/** GST is 18% on these services, inside every price. */
+export const GST_RATE_PERCENT = 18;
+const GSTIN_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const GSTIN_PATTERN = /^\d{2}[A-Z]{5}\d{4}[A-Z][1-9A-Z]Z[0-9A-Z]$/;
+/**
+ * Whether a GSTIN's 15th character is the check character of the first 14
+ * (the GSTN's base-36 Luhn variant). Catches a mistyped digit, which the
+ * pattern alone does not: a B2B invoice with a wrong GSTIN costs the buyer
+ * their input credit.
+ */
+export function gstinChecksumValid(gstin) {
+    if (!GSTIN_PATTERN.test(gstin))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < 14; i++) {
+        const value = GSTIN_CHARS.indexOf(gstin.charAt(i));
+        const product = value * (i % 2 === 0 ? 1 : 2);
+        sum += Math.floor(product / 36) + (product % 36);
+    }
+    const check = (36 - (sum % 36)) % 36;
+    return gstin.charAt(14) === GSTIN_CHARS.charAt(check);
+}
+/** A GSTIN, upper-cased, pattern AND check character. */
+export const gstinSchema = z
+    .string()
+    .trim()
+    .transform((v) => v.toUpperCase())
+    .refine(gstinChecksumValid, { error: VALIDATION_MESSAGE.gstinInvalid });
+/**
+ * Who is buying, for the invoice. The state is the place of supply and
+ * decides the tax. With a GSTIN (a business claiming input credit) the
+ * invoice is B2B: it must carry the buyer's legal name and address, and the
+ * state is the GSTIN's own.
+ */
+export const billingDetailsSchema = z
+    .object({
+    stateCode: gstStateCodeSchema,
+    gstin: gstinSchema.optional(),
+    legalName: z.string().trim().min(2).max(BILLING_NAME_MAX).optional(),
+    address: z.string().trim().min(10).max(BILLING_ADDRESS_MAX).optional(),
+})
+    .refine((body) => !body.gstin || body.gstin.slice(0, 2) === body.stateCode, {
+    path: ['stateCode'],
+    error: VALIDATION_MESSAGE.gstinStateMismatch,
+})
+    .refine((body) => !body.gstin || body.legalName !== undefined, {
+    path: ['legalName'],
+    error: VALIDATION_MESSAGE.gstinNeedsNameAndAddress,
+})
+    .refine((body) => !body.gstin || body.address !== undefined, {
+    path: ['address'],
+    error: VALIDATION_MESSAGE.gstinNeedsNameAndAddress,
+});
+//# sourceMappingURL=gst.js.map

package/dist/domains/billing/gst.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gst.js","sourceRoot":"","sources":["../../../src/domains/billing/gst.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * founder-schema: GST, the states and the GSTIN (0.12.0)\n *\n * Its own module so both the billing contract and a member's membership\n * (the billing details they last used, to prefill a checkout) can use it\n * without importing each other.\n *\n * @module founder-schema/domains/billing/gst\n */\n\nimport { z } from 'zod';\nimport { BILLING_ADDRESS_MAX, BILLING_NAME_MAX } from '../../core/limits.js';\nimport { VALIDATION_MESSAGE } from '../../core/validation.js';\n\n// ─── GST: states and the GSTIN ───────────────────────────────────────────────\n\n/**\n * India's states and union territories by their GST state code, the first\n * two digits of every GSTIN registered there. The current codes only: 25\n * (Daman and Diu) merged into 26 in 2020, and 28 (undivided Andhra Pradesh)\n * gave way to 37.\n */\nexport const GST_STATES = [\n  { code: '01', name: 'Jammu and Kashmir' },\n  { code: '02', name: 'Himachal Pradesh' },\n  { code: '03', name: 'Punjab' },\n  { code: '04', name: 'Chandigarh' },\n  { code: '05', name: 'Uttarakhand' },\n  { code: '06', name: 'Haryana' },\n  { code: '07', name: 'Delhi' },\n  { code: '08', name: 'Rajasthan' },\n  { code: '09', name: 'Uttar Pradesh' },\n  { code: '10', name: 'Bihar' },\n  { code: '11', name: 'Sikkim' },\n  { code: '12', name: 'Arunachal Pradesh' },\n  { code: '13', name: 'Nagaland' },\n  { code: '14', name: 'Manipur' },\n  { code: '15', name: 'Mizoram' },\n  { code: '16', name: 'Tripura' },\n  { code: '17', name: 'Meghalaya' },\n  { code: '18', name: 'Assam' },\n  { code: '19', name: 'West Bengal' },\n  { code: '20', name: 'Jharkhand' },\n  { code: '21', name: 'Odisha' },\n  { code: '22', name: 'Chhattisgarh' },\n  { code: '23', name: 'Madhya Pradesh' },\n  { code: '24', name: 'Gujarat' },\n  { code: '26', name: 'Dadra and Nagar Haveli and Daman and Diu' },\n  { code: '27', name: 'Maharashtra' },\n  { code: '29', name: 'Karnataka' },\n  { code: '30', name: 'Goa' },\n  { code: '31', name: 'Lakshadweep' },\n  { code: '32', name: 'Kerala' },\n  { code: '33', name: 'Tamil Nadu' },\n  { code: '34', name: 'Puducherry' },\n  { code: '35', name: 'Andaman and Nicobar Islands' },\n  { code: '36', name: 'Telangana' },\n  { code: '37', name: 'Andhra Pradesh' },\n  { code: '38', name: 'Ladakh' },\n] as const;\nexport type GstStateCode = (typeof GST_STATES)[number]['code'];\nexport const GST_STATE_CODE_VALUES = GST_STATES.map((s) => s.code) as [\n  GstStateCode,\n  ...GstStateCode[],\n];\nexport const gstStateCodeSchema = z.enum(GST_STATE_CODE_VALUES);\n\n/** The state's name for its code, as an invoice prints it. */\nexport function gstStateName(code: GstStateCode): string {\n  return GST_STATES.find((s) => s.code === code)?.name ?? code;\n}\n\n/** GST is 18% on these services, inside every price. */\nexport const GST_RATE_PERCENT = 18;\n\nconst GSTIN_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';\nconst GSTIN_PATTERN = /^\\d{2}[A-Z]{5}\\d{4}[A-Z][1-9A-Z]Z[0-9A-Z]$/;\n\n/**\n * Whether a GSTIN's 15th character is the check character of the first 14\n * (the GSTN's base-36 Luhn variant). Catches a mistyped digit, which the\n * pattern alone does not: a B2B invoice with a wrong GSTIN costs the buyer\n * their input credit.\n */\nexport function gstinChecksumValid(gstin: string): boolean {\n  if (!GSTIN_PATTERN.test(gstin)) return false;\n  let sum = 0;\n  for (let i = 0; i < 14; i++) {\n    const value = GSTIN_CHARS.indexOf(gstin.charAt(i));\n    const product = value * (i % 2 === 0 ? 1 : 2);\n    sum += Math.floor(product / 36) + (product % 36);\n  }\n  const check = (36 - (sum % 36)) % 36;\n  return gstin.charAt(14) === GSTIN_CHARS.charAt(check);\n}\n\n/** A GSTIN, upper-cased, pattern AND check character. */\nexport const gstinSchema = z\n  .string()\n  .trim()\n  .transform((v) => v.toUpperCase())\n  .refine(gstinChecksumValid, { error: VALIDATION_MESSAGE.gstinInvalid });\n\n/**\n * Who is buying, for the invoice. The state is the place of supply and\n * decides the tax. With a GSTIN (a business claiming input credit) the\n * invoice is B2B: it must carry the buyer's legal name and address, and the\n * state is the GSTIN's own.\n */\nexport const billingDetailsSchema = z\n  .object({\n    stateCode: gstStateCodeSchema,\n    gstin: gstinSchema.optional(),\n    legalName: z.string().trim().min(2).max(BILLING_NAME_MAX).optional(),\n    address: z.string().trim().min(10).max(BILLING_ADDRESS_MAX).optional(),\n  })\n  .refine((body) => !body.gstin || body.gstin.slice(0, 2) === body.stateCode, {\n    path: ['stateCode'],\n    error: VALIDATION_MESSAGE.gstinStateMismatch,\n  })\n  .refine((body) => !body.gstin || body.legalName !== undefined, {\n    path: ['legalName'],\n    error: VALIDATION_MESSAGE.gstinNeedsNameAndAddress,\n  })\n  .refine((body) => !body.gstin || body.address !== undefined, {\n    path: ['address'],\n    error: VALIDATION_MESSAGE.gstinNeedsNameAndAddress,\n  });\nexport type BillingDetails = z.infer<typeof billingDetailsSchema>;\n"]}

package/dist/domains/chat/chat.d.ts

@@ -121,8 +121,21 @@ export type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;
  */
 export declare const openChatBodySchema: z.ZodObject<{
     userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    useAllowance: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type OpenChatBody = z.infer<typeof openChatBodySchema>;
+/**
+ * How a conversation came to be allowed (0.12.0): they know each other, it
+ * used the opener's allowance, or the opener was acting as a staff role,
+ * which reaches anyone. ⚠ Stored: append only.
+ */
+export declare const CHAT_OPENED_VIA_VALUES: readonly ["contact", "allowance", "staff"];
+export declare const chatOpenedViaSchema: z.ZodEnum<{
+    staff: "staff";
+    contact: "contact";
+    allowance: "allowance";
+}>;
+export type ChatOpenedVia = z.infer<typeof chatOpenedViaSchema>;
 /**
  * The conversation to navigate to. `201` with `wasCreated: true` the first
  * time, `200` and `false` on every later open of the same pair.
@@ -130,8 +143,79 @@ export type OpenChatBody = z.infer<typeof openChatBodySchema>;
 export declare const openChatResponseSchema: z.ZodObject<{
     conversationId: z.ZodString;
     wasCreated: z.ZodBoolean;
+    via: z.ZodEnum<{
+        staff: "staff";
+        contact: "contact";
+        allowance: "allowance";
+    }>;
 }, z.core.$strip>;
 export type OpenChatResponse = z.infer<typeof openChatResponseSchema>;
+/**
+ * Whether opening a conversation with someone would work, and what it would
+ * cost, so the button can say so BEFORE it is tapped
+ * (`GET /api/v1/chat/reach/:userId`):
+ *
+ *   contact              they know each other: free
+ *   allowance            uses one of `left` new people this month: confirm first
+ *   allowance_exhausted  none left this month (`resetsAt`)
+ *   plan_required        they do not know each other and the asker has no plan
+ *   membership_required  the asker cannot chat at all (a viewer)
+ *   not_accepted         the other person takes conversations only from people
+ *                        they know, or cannot chat (one answer for both)
+ *   staff                the asker acts as a staff role, which starts a
+ *                        conversation with anyone who can chat: free, past
+ *                        their "people I know only" (the user, 2026-10-12)
+ */
+export declare const CHAT_REACH_VALUES: readonly ["contact", "allowance", "allowance_exhausted", "plan_required", "membership_required", "not_accepted", "staff"];
+export declare const chatReachKindSchema: z.ZodEnum<{
+    staff: "staff";
+    contact: "contact";
+    allowance: "allowance";
+    allowance_exhausted: "allowance_exhausted";
+    plan_required: "plan_required";
+    membership_required: "membership_required";
+    not_accepted: "not_accepted";
+}>;
+export type ChatReachKind = z.infer<typeof chatReachKindSchema>;
+export declare const chatReachSchema: z.ZodObject<{
+    reach: z.ZodEnum<{
+        staff: "staff";
+        contact: "contact";
+        allowance: "allowance";
+        allowance_exhausted: "allowance_exhausted";
+        plan_required: "plan_required";
+        membership_required: "membership_required";
+        not_accepted: "not_accepted";
+    }>;
+    left: z.ZodNullable<z.ZodNumber>;
+    resetsAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type ChatReach = z.infer<typeof chatReachSchema>;
+export declare const chatReachParamsSchema: z.ZodObject<{
+    userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>;
+export type ChatReachParams = z.infer<typeof chatReachParamsSchema>;
+/**
+ * Who may start a conversation with me (0.12.0). People I know always may.
+ * ⚠ Stored: append only.
+ *
+ *   contacts            only people I know
+ *   contacts_and_plans  also Premium and Business members (the default)
+ */
+export declare const MESSAGE_FROM_VALUES: readonly ["contacts", "contacts_and_plans"];
+export declare const messageFromSchema: z.ZodEnum<{
+    contacts: "contacts";
+    contacts_and_plans: "contacts_and_plans";
+}>;
+export type MessageFrom = z.infer<typeof messageFromSchema>;
+/** `GET` and `PUT /api/v1/me/messaging`. */
+export declare const messagingSettingsSchema: z.ZodObject<{
+    from: z.ZodEnum<{
+        contacts: "contacts";
+        contacts_and_plans: "contacts_and_plans";
+    }>;
+}, z.core.$strip>;
+export type MessagingSettings = z.infer<typeof messagingSettingsSchema>;
 /**
  * `POST /api/v1/chat/participants`: names and avatars for the people in the
  * viewer's conversations.
@@ -170,6 +254,7 @@ export type ChatParticipantsResponse = z.infer<typeof chatParticipantsResponseSc
  */
 export declare const chatInvitationBodySchema: z.ZodObject<{
     userId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    useAllowance: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** @deprecated Since 0.2.0: use `OpenChatBody`. */
 export type ChatInvitationBody = OpenChatBody;

package/dist/domains/chat/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/domains/chat/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;AAStF;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;iBAAqB,CAAC;AAC3D,mDAAmD;AACnD,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/domains/chat/chat.ts"],"names":[],"mappings":"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"}

package/dist/domains/chat/chat.js

@@ -130,7 +130,21 @@ export const chatAuthTokenSchema = z.object({
 export const openChatBodySchema = z.object({
     /** The OTHER participant. The viewer is taken from the credential, never the body. */
     userId: objectIdSchema,
+    /**
+     * Agreement to use one of this month's allowance (0.12.0), when they do
+     * not know the other person. Without it such an open is refused with
+     * `MESSAGE_ALLOWANCE_UNCONFIRMED` and nothing is spent: an allowance is
+     * never used by accident. Ignored for someone they know.
+     */
+    useAllowance: z.boolean().optional(),
 });
+/**
+ * How a conversation came to be allowed (0.12.0): they know each other, it
+ * used the opener's allowance, or the opener was acting as a staff role,
+ * which reaches anyone. ⚠ Stored: append only.
+ */
+export const CHAT_OPENED_VIA_VALUES = ['contact', 'allowance', 'staff'];
+export const chatOpenedViaSchema = z.enum(CHAT_OPENED_VIA_VALUES);
 /**
  * The conversation to navigate to. `201` with `wasCreated: true` the first
  * time, `200` and `false` on every later open of the same pair.
@@ -138,7 +152,55 @@ export const openChatBodySchema = z.object({
 export const openChatResponseSchema = z.object({
     conversationId: z.string().min(1),
     wasCreated: z.boolean(),
+    /** 0.12.0. Every later open of the same pair is `contact`: they have a conversation now. */
+    via: chatOpenedViaSchema,
+});
+// ─── Who may start a conversation with whom (0.12.0) ─────────────────────────
+/**
+ * Whether opening a conversation with someone would work, and what it would
+ * cost, so the button can say so BEFORE it is tapped
+ * (`GET /api/v1/chat/reach/:userId`):
+ *
+ *   contact              they know each other: free
+ *   allowance            uses one of `left` new people this month: confirm first
+ *   allowance_exhausted  none left this month (`resetsAt`)
+ *   plan_required        they do not know each other and the asker has no plan
+ *   membership_required  the asker cannot chat at all (a viewer)
+ *   not_accepted         the other person takes conversations only from people
+ *                        they know, or cannot chat (one answer for both)
+ *   staff                the asker acts as a staff role, which starts a
+ *                        conversation with anyone who can chat: free, past
+ *                        their "people I know only" (the user, 2026-10-12)
+ */
+export const CHAT_REACH_VALUES = [
+    'contact',
+    'allowance',
+    'allowance_exhausted',
+    'plan_required',
+    'membership_required',
+    'not_accepted',
+    'staff',
+];
+export const chatReachKindSchema = z.enum(CHAT_REACH_VALUES);
+export const chatReachSchema = z.object({
+    reach: chatReachKindSchema,
+    /** For `allowance`: how many new people are left this month, this one included. */
+    left: z.number().int().nonnegative().nullable(),
+    /** For `allowance` and `allowance_exhausted`: when the month's count starts again. */
+    resetsAt: z.iso.datetime().nullable(),
 });
+export const chatReachParamsSchema = z.object({ userId: objectIdSchema });
+/**
+ * Who may start a conversation with me (0.12.0). People I know always may.
+ * ⚠ Stored: append only.
+ *
+ *   contacts            only people I know
+ *   contacts_and_plans  also Premium and Business members (the default)
+ */
+export const MESSAGE_FROM_VALUES = ['contacts', 'contacts_and_plans'];
+export const messageFromSchema = z.enum(MESSAGE_FROM_VALUES);
+/** `GET` and `PUT /api/v1/me/messaging`. */
+export const messagingSettingsSchema = z.object({ from: messageFromSchema });
 // ─── Participants ────────────────────────────────────────────────────────────
 /**
  * `POST /api/v1/chat/participants`: names and avatars for the people in the

package/dist/domains/chat/chat.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../../src/domains/chat/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAyB,CAAC;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AAG9D,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;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,sFAAsF;IACtF,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACxB,CAAC,CAAC;AAGH,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC;CACnE,CAAC,CAAC;AAGH,wEAAwE;AACxE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,cAAc;IACxB,2EAA2E;IAC3E,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACrD,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,qBAAqB,CAAC;CAC1D,CAAC,CAAC;AAGH,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,0BAA0B;AAE1B;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAI3D;;;;;GAKG;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, 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/domains/chat\n */\n\nimport { z } from 'zod';\nimport { objectIdSchema, usernameSchema } from '../../core/common.js';\nimport { CHAT_PARTICIPANTS_MAX } from '../../core/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// Unused by every consumer, and still exported: removing an export trips the\n// publish rule that refuses a release missing anything the live one has, so it\n// is the user's decision, not a side effect. They were meant to go in 0.3.0;\n// that release kept them.\n\n/**\n * @deprecated Since 0.2.0: use `openChatBodySchema`, the same shape under the\n * name of the route that takes it.\n */\nexport const chatInvitationBodySchema = openChatBodySchema;\n/** @deprecated Since 0.2.0: use `OpenChatBody`. */\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.\n */\nexport const chatInvitationSchema = z.object({\n  invitationToken: z.string().min(1),\n});\n/** @deprecated Since 0.2.0. */\nexport type ChatInvitation = z.infer<typeof chatInvitationSchema>;\n"]}
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../../src/domains/chat/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/domains/chat\n */\n\nimport { z } from 'zod';\nimport { objectIdSchema, usernameSchema } from '../../core/common.js';\nimport { CHAT_PARTICIPANTS_MAX } from '../../core/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  /**\n   * Agreement to use one of this month's allowance (0.12.0), when they do\n   * not know the other person. Without it such an open is refused with\n   * `MESSAGE_ALLOWANCE_UNCONFIRMED` and nothing is spent: an allowance is\n   * never used by accident. Ignored for someone they know.\n   */\n  useAllowance: z.boolean().optional(),\n});\nexport type OpenChatBody = z.infer<typeof openChatBodySchema>;\n\n/**\n * How a conversation came to be allowed (0.12.0): they know each other, it\n * used the opener's allowance, or the opener was acting as a staff role,\n * which reaches anyone. ⚠ Stored: append only.\n */\nexport const CHAT_OPENED_VIA_VALUES = ['contact', 'allowance', 'staff'] as const;\nexport const chatOpenedViaSchema = z.enum(CHAT_OPENED_VIA_VALUES);\nexport type ChatOpenedVia = z.infer<typeof chatOpenedViaSchema>;\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  /** 0.12.0. Every later open of the same pair is `contact`: they have a conversation now. */\n  via: chatOpenedViaSchema,\n});\nexport type OpenChatResponse = z.infer<typeof openChatResponseSchema>;\n\n// ─── Who may start a conversation with whom (0.12.0) ─────────────────────────\n\n/**\n * Whether opening a conversation with someone would work, and what it would\n * cost, so the button can say so BEFORE it is tapped\n * (`GET /api/v1/chat/reach/:userId`):\n *\n *   contact              they know each other: free\n *   allowance            uses one of `left` new people this month: confirm first\n *   allowance_exhausted  none left this month (`resetsAt`)\n *   plan_required        they do not know each other and the asker has no plan\n *   membership_required  the asker cannot chat at all (a viewer)\n *   not_accepted         the other person takes conversations only from people\n *                        they know, or cannot chat (one answer for both)\n *   staff                the asker acts as a staff role, which starts a\n *                        conversation with anyone who can chat: free, past\n *                        their \"people I know only\" (the user, 2026-10-12)\n */\nexport const CHAT_REACH_VALUES = [\n  'contact',\n  'allowance',\n  'allowance_exhausted',\n  'plan_required',\n  'membership_required',\n  'not_accepted',\n  'staff',\n] as const;\nexport const chatReachKindSchema = z.enum(CHAT_REACH_VALUES);\nexport type ChatReachKind = z.infer<typeof chatReachKindSchema>;\n\nexport const chatReachSchema = z.object({\n  reach: chatReachKindSchema,\n  /** For `allowance`: how many new people are left this month, this one included. */\n  left: z.number().int().nonnegative().nullable(),\n  /** For `allowance` and `allowance_exhausted`: when the month's count starts again. */\n  resetsAt: z.iso.datetime().nullable(),\n});\nexport type ChatReach = z.infer<typeof chatReachSchema>;\n\nexport const chatReachParamsSchema = z.object({ userId: objectIdSchema });\nexport type ChatReachParams = z.infer<typeof chatReachParamsSchema>;\n\n/**\n * Who may start a conversation with me (0.12.0). People I know always may.\n * ⚠ Stored: append only.\n *\n *   contacts            only people I know\n *   contacts_and_plans  also Premium and Business members (the default)\n */\nexport const MESSAGE_FROM_VALUES = ['contacts', 'contacts_and_plans'] as const;\nexport const messageFromSchema = z.enum(MESSAGE_FROM_VALUES);\nexport type MessageFrom = z.infer<typeof messageFromSchema>;\n\n/** `GET` and `PUT /api/v1/me/messaging`. */\nexport const messagingSettingsSchema = z.object({ from: messageFromSchema });\nexport type MessagingSettings = z.infer<typeof messagingSettingsSchema>;\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// Unused by every consumer, and still exported: removing an export trips the\n// publish rule that refuses a release missing anything the live one has, so it\n// is the user's decision, not a side effect. They were meant to go in 0.3.0;\n// that release kept them.\n\n/**\n * @deprecated Since 0.2.0: use `openChatBodySchema`, the same shape under the\n * name of the route that takes it.\n */\nexport const chatInvitationBodySchema = openChatBodySchema;\n/** @deprecated Since 0.2.0: use `OpenChatBody`. */\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.\n */\nexport const chatInvitationSchema = z.object({\n  invitationToken: z.string().min(1),\n});\n/** @deprecated Since 0.2.0. */\nexport type ChatInvitation = z.infer<typeof chatInvitationSchema>;\n"]}