gymmonk-schema 0.15.0 → 0.17.0

package/dist/chat.d.ts

@@ -0,0 +1,235 @@
+/**
+ * gymmonk-schema — Chat
+ * =====================
+ * THE wire contract between `gymmonk-web-client` and `gymmonk-chat-server`, and
+ * the only place either is allowed to name a socket event.
+ *
+ * It lives here rather than in the chat server because three codebases need it
+ * and none of them owns the other two: the client emits, the chat server
+ * handles, and gymmonk-backend mints the tokens that let the two meet. An event
+ * name that differs by one character between any pair of them produces a
+ * message nobody receives and no error anywhere, which is exactly the class of
+ * bug a shared package exists to make impossible.
+ *
+ * @module gymmonk-schema/chat
+ */
+import { z } from 'zod';
+/**
+ * Every socket event name.
+ *
+ * String literals rather than an enum, so both sides put the identical bytes on
+ * the wire without either importing the other's runtime.
+ */
+export declare const CHAT_SOCKET_EVENTS: {
+    /** Server → client, on connect. The socket is up and awaiting auth. */
+    readonly HELLO: "hello";
+    /** Client → server. `{ token }`. Must arrive inside the auth window. */
+    readonly AUTH: "auth";
+    /** Server → client. `{ userId }` on success. */
+    readonly AUTH_OK: "auth:ok";
+    /** Server → client. `{ code, message }` for any failure, auth or otherwise. */
+    readonly ERROR: "error";
+    /** Client → server. Open a conversation and start receiving it live. */
+    readonly CONVERSATION_JOIN: "conversation:join";
+    /** Client → server. Leave it (navigated away). */
+    readonly CONVERSATION_LEAVE: "conversation:leave";
+    /** Client → server. `{ conversationId, clientMessageId, text }`. */
+    readonly MESSAGE_SEND: "message:send";
+    /** Server → everyone in the room, and the recipients' own rooms. */
+    readonly MESSAGE_NEW: "message:new";
+    /** Server → sender only. Their send, acknowledged and stored. */
+    readonly MESSAGE_SENT: "message:sent";
+    /** Client → server. Mark everything up to now as read. */
+    readonly MESSAGE_READ: "message:read";
+    /** Server → the room. `{ conversationId, userId, readAt }`. */
+    readonly MESSAGE_READ_BY: "message:read-by";
+    /** Client → server. `{ conversationId, typing }`. */
+    readonly TYPING: "typing";
+    /** Server → the other participants. `{ conversationId, userId, typing }`. */
+    readonly TYPING_UPDATE: "typing:update";
+    /** Server → the room. Who currently has this conversation open. */
+    readonly PRESENCE_UPDATE: "presence:update";
+};
+export type ChatSocketEvent = (typeof CHAT_SOCKET_EVENTS)[keyof typeof CHAT_SOCKET_EVENTS];
+/** Stable codes on the `error` event. The client branches on these; the message is for logs. */
+export declare const CHAT_ERROR: {
+    readonly AUTH_TIMEOUT: "AUTH_TIMEOUT";
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    readonly NOT_A_PARTICIPANT: "NOT_A_PARTICIPANT";
+    readonly CONVERSATION_NOT_FOUND: "CONVERSATION_NOT_FOUND";
+    readonly INVALID_PAYLOAD: "INVALID_PAYLOAD";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+export type ChatErrorCode = (typeof CHAT_ERROR)[keyof typeof CHAT_ERROR];
+/** Longest message body accepted. Matches the column cap in the model. */
+export declare const MAX_MESSAGE_LENGTH = 4000;
+/** Messages per page of history. */
+export declare const MESSAGE_PAGE_SIZE = 50;
+/**
+ * Messages one socket may send per minute.
+ *
+ * Not an anti-abuse boundary on its own: a member can only ever write to a
+ * conversation their own backend authorised. This is what stops a broken client
+ * looping a send from filling a collection.
+ */
+export declare const MESSAGE_RATE_PER_MINUTE = 60;
+/** How long an unauthenticated socket may hold a connection, in ms. */
+export declare const CHAT_AUTH_TIMEOUT_MS = 10000;
+/**
+ * How long a typing indicator survives without a refresh, in ms.
+ *
+ * Someone who closes the app mid-sentence never sends `typing: false`, so the
+ * indicator has to expire on its own or it stays on screen forever. The sender
+ * re-emits well inside this window while they are still typing.
+ */
+export declare const TYPING_TIMEOUT_MS = 4000;
+/** How often the sender re-emits `typing: true` while typing, in ms. */
+export declare const TYPING_THROTTLE_MS = 2000;
+/** A participant, denormalised onto the conversation so a list renders without joins. */
+export declare const chatParticipantSchema: z.ZodObject<{
+    userId: z.ZodString;
+    displayName: z.ZodString;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ChatParticipant = z.infer<typeof chatParticipantSchema>;
+/** A message as every client sees it. */
+export declare const chatMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    conversationId: z.ZodString;
+    senderId: z.ZodString;
+    text: z.ZodString;
+    clientMessageId: z.ZodString;
+    sentAt: z.ZodISODateTime;
+    readAt: z.ZodNullable<z.ZodISODateTime>;
+    deleted: z.ZodBoolean;
+}, z.core.$strip>;
+export type ChatMessage = z.infer<typeof chatMessageSchema>;
+/** The one-line preview a conversation row shows. */
+export declare const chatLastMessageSchema: z.ZodObject<{
+    text: z.ZodString;
+    senderId: z.ZodString;
+    sentAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ChatLastMessage = z.infer<typeof chatLastMessageSchema>;
+/**
+ * A conversation as the list screen sees it.
+ *
+ * `unreadCount` is the CALLER's, not a global figure: the same row means
+ * different things to the two people in it.
+ */
+export declare const chatConversationSchema: z.ZodObject<{
+    id: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        userId: z.ZodString;
+        displayName: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    lastMessage: z.ZodNullable<z.ZodObject<{
+        text: z.ZodString;
+        senderId: z.ZodString;
+        sentAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    unreadCount: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    frozen: z.ZodBoolean;
+}, z.core.$strip>;
+export type ChatConversation = z.infer<typeof chatConversationSchema>;
+export interface ChatAuthPayload {
+    token: string;
+}
+export interface ChatConversationRoomPayload {
+    conversationId: string;
+}
+export interface ChatMessageSendPayload {
+    conversationId: string;
+    /** Client-generated idempotency key. A retry with the same value is not a second message. */
+    clientMessageId: string;
+    text: string;
+}
+export interface ChatMessageReadPayload {
+    conversationId: string;
+}
+export interface ChatTypingPayload {
+    conversationId: string;
+    typing: boolean;
+}
+export interface ChatServerToClientEvents {
+    [CHAT_SOCKET_EVENTS.HELLO]: (payload: {
+        message: string;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.AUTH_OK]: (payload: {
+        userId: string;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.ERROR]: (payload: {
+        code: string;
+        message: string;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.MESSAGE_NEW]: (message: ChatMessage) => void;
+    [CHAT_SOCKET_EVENTS.MESSAGE_SENT]: (payload: {
+        clientMessageId: string;
+        message: ChatMessage;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.MESSAGE_READ_BY]: (payload: {
+        conversationId: string;
+        userId: string;
+        readAt: string;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.TYPING_UPDATE]: (payload: {
+        conversationId: string;
+        userId: string;
+        typing: boolean;
+    }) => void;
+    [CHAT_SOCKET_EVENTS.PRESENCE_UPDATE]: (payload: {
+        conversationId: string;
+        userIds: string[];
+    }) => void;
+}
+export interface ChatClientToServerEvents {
+    [CHAT_SOCKET_EVENTS.AUTH]: (payload: ChatAuthPayload) => void;
+    [CHAT_SOCKET_EVENTS.CONVERSATION_JOIN]: (payload: ChatConversationRoomPayload) => void;
+    [CHAT_SOCKET_EVENTS.CONVERSATION_LEAVE]: (payload: ChatConversationRoomPayload) => void;
+    [CHAT_SOCKET_EVENTS.MESSAGE_SEND]: (payload: ChatMessageSendPayload) => void;
+    [CHAT_SOCKET_EVENTS.MESSAGE_READ]: (payload: ChatMessageReadPayload) => void;
+    [CHAT_SOCKET_EVENTS.TYPING]: (payload: ChatTypingPayload) => void;
+}
+/** `GET /api/v1/chat/config` — where chat lives, whether it is on, and who the caller is. */
+export declare const chatConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    url: z.ZodNullable<z.ZodString>;
+    userId: z.ZodString;
+}, z.core.$strip>;
+export type ChatConfig = z.infer<typeof chatConfigSchema>;
+/** `POST /api/v1/chat/auth-token` */
+export declare const chatAuthTokenSchema: z.ZodObject<{
+    token: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    expiresIn: z.ZodNumber;
+}, z.core.$strip>;
+export type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;
+/** `POST /api/v1/chat/invitation` — permission to open a conversation with someone. */
+export declare const chatInvitationBodySchema: z.ZodObject<{
+    userId: z.ZodString;
+}, z.core.$strip>;
+export type ChatInvitationBody = z.infer<typeof chatInvitationBodySchema>;
+export declare const chatInvitationSchema: z.ZodObject<{
+    invitationToken: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ChatInvitation = z.infer<typeof chatInvitationSchema>;
+/** `POST /api/v1/chat/notify` — chat-server telling the backend to notify people. */
+export declare const chatNotifyBodySchema: z.ZodObject<{
+    recipientIds: z.ZodArray<z.ZodString>;
+    conversationId: z.ZodString;
+    senderId: z.ZodString;
+    senderName: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type ChatNotifyBody = z.infer<typeof chatNotifyBodySchema>;
+/** JWT `aud` on every chat token. chat-server accepts exactly this. */
+export declare const CHAT_TOKEN_AUDIENCE = "gymmonk-chat-server";
+/** `purpose` claim marking an invitation. Auth tokens carry no purpose. */
+export declare const CHAT_INVITATION_PURPOSE = "invitation";
+//# 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":"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"}

package/dist/chat.js

@@ -0,0 +1,182 @@
+/**
+ * gymmonk-schema — Chat
+ * =====================
+ * THE wire contract between `gymmonk-web-client` and `gymmonk-chat-server`, and
+ * the only place either is allowed to name a socket event.
+ *
+ * It lives here rather than in the chat server because three codebases need it
+ * and none of them owns the other two: the client emits, the chat server
+ * handles, and gymmonk-backend mints the tokens that let the two meet. An event
+ * name that differs by one character between any pair of them produces a
+ * message nobody receives and no error anywhere, which is exactly the class of
+ * bug a shared package exists to make impossible.
+ *
+ * @module gymmonk-schema/chat
+ */
+import { z } from 'zod';
+import { isoDateTimeSchema, objectIdSchema } from './common.js';
+// ─── Socket events ───────────────────────────────────────────────────────────
+/**
+ * Every socket event name.
+ *
+ * String literals rather than an enum, so both sides put the identical bytes on
+ * the wire without either importing the other's runtime.
+ */
+export const CHAT_SOCKET_EVENTS = {
+    /** Server → client, on connect. The socket is up and awaiting auth. */
+    HELLO: 'hello',
+    /** Client → server. `{ token }`. Must arrive inside the auth window. */
+    AUTH: 'auth',
+    /** Server → client. `{ userId }` on success. */
+    AUTH_OK: 'auth:ok',
+    /** Server → client. `{ code, message }` for any failure, auth or otherwise. */
+    ERROR: 'error',
+    /** Client → server. Open a conversation and start receiving it live. */
+    CONVERSATION_JOIN: 'conversation:join',
+    /** Client → server. Leave it (navigated away). */
+    CONVERSATION_LEAVE: 'conversation:leave',
+    /** Client → server. `{ conversationId, clientMessageId, text }`. */
+    MESSAGE_SEND: 'message:send',
+    /** Server → everyone in the room, and the recipients' own rooms. */
+    MESSAGE_NEW: 'message:new',
+    /** Server → sender only. Their send, acknowledged and stored. */
+    MESSAGE_SENT: 'message:sent',
+    /** Client → server. Mark everything up to now as read. */
+    MESSAGE_READ: 'message:read',
+    /** Server → the room. `{ conversationId, userId, readAt }`. */
+    MESSAGE_READ_BY: 'message:read-by',
+    /** Client → server. `{ conversationId, typing }`. */
+    TYPING: 'typing',
+    /** Server → the other participants. `{ conversationId, userId, typing }`. */
+    TYPING_UPDATE: 'typing:update',
+    /** Server → the room. Who currently has this conversation open. */
+    PRESENCE_UPDATE: 'presence:update',
+};
+// ─── Error codes ─────────────────────────────────────────────────────────────
+/** Stable codes on the `error` event. The client branches on these; the message is for logs. */
+export const CHAT_ERROR = {
+    AUTH_TIMEOUT: 'AUTH_TIMEOUT',
+    AUTH_FAILED: 'AUTH_FAILED',
+    NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+    NOT_A_PARTICIPANT: 'NOT_A_PARTICIPANT',
+    CONVERSATION_NOT_FOUND: 'CONVERSATION_NOT_FOUND',
+    INVALID_PAYLOAD: 'INVALID_PAYLOAD',
+    RATE_LIMITED: 'RATE_LIMITED',
+    SERVER_ERROR: 'SERVER_ERROR',
+};
+// ─── Limits ──────────────────────────────────────────────────────────────────
+/** Longest message body accepted. Matches the column cap in the model. */
+export const MAX_MESSAGE_LENGTH = 4000;
+/** Messages per page of history. */
+export const MESSAGE_PAGE_SIZE = 50;
+/**
+ * Messages one socket may send per minute.
+ *
+ * Not an anti-abuse boundary on its own: a member can only ever write to a
+ * conversation their own backend authorised. This is what stops a broken client
+ * looping a send from filling a collection.
+ */
+export const MESSAGE_RATE_PER_MINUTE = 60;
+/** How long an unauthenticated socket may hold a connection, in ms. */
+export const CHAT_AUTH_TIMEOUT_MS = 10_000;
+/**
+ * How long a typing indicator survives without a refresh, in ms.
+ *
+ * Someone who closes the app mid-sentence never sends `typing: false`, so the
+ * indicator has to expire on its own or it stays on screen forever. The sender
+ * re-emits well inside this window while they are still typing.
+ */
+export const TYPING_TIMEOUT_MS = 4_000;
+/** How often the sender re-emits `typing: true` while typing, in ms. */
+export const TYPING_THROTTLE_MS = 2_000;
+// ─── Wire shapes ─────────────────────────────────────────────────────────────
+/** A participant, denormalised onto the conversation so a list renders without joins. */
+export const chatParticipantSchema = z.object({
+    userId: objectIdSchema,
+    displayName: z.string(),
+    avatarUrl: z.string().nullable(),
+});
+/** A message as every client sees it. */
+export const chatMessageSchema = z.object({
+    id: objectIdSchema,
+    conversationId: objectIdSchema,
+    senderId: objectIdSchema,
+    text: z.string(),
+    /** Echoed back so the sender can reconcile its optimistic row. */
+    clientMessageId: z.string(),
+    sentAt: isoDateTimeSchema,
+    readAt: isoDateTimeSchema.nullable(),
+    /** Deleted for everyone. `text` is then empty. */
+    deleted: z.boolean(),
+});
+/** The one-line preview a conversation row shows. */
+export const chatLastMessageSchema = z.object({
+    text: z.string(),
+    senderId: objectIdSchema,
+    sentAt: isoDateTimeSchema,
+});
+/**
+ * A conversation as the list screen sees it.
+ *
+ * `unreadCount` is the CALLER's, not a global figure: the same row means
+ * different things to the two people in it.
+ */
+export const chatConversationSchema = z.object({
+    id: objectIdSchema,
+    participants: z.array(chatParticipantSchema),
+    lastMessage: chatLastMessageSchema.nullable(),
+    unreadCount: z.number().int().nonnegative(),
+    createdAt: isoDateTimeSchema,
+    /** Last activity. The inbox sorts on this, newest first. */
+    updatedAt: isoDateTimeSchema,
+    /**
+     * Closed to new messages. True once one participant blocks the other.
+     *
+     * History still reads: freezing stops the next message, and deleting what was
+     * already said is a different and much larger decision. The client uses this
+     * to disable its composer rather than letting a send fail at the server.
+     */
+    frozen: z.boolean(),
+});
+// ─── Backend bridge ──────────────────────────────────────────────────────────
+/** `GET /api/v1/chat/config` — where chat lives, whether it is on, and who the caller is. */
+export const chatConfigSchema = z.object({
+    enabled: z.boolean(),
+    url: z.string().nullable(),
+    /**
+     * The caller's id AS CHAT-SERVER WILL SEE IT.
+     *
+     * Sourced from the same place that mints the token rather than from the
+     * client session, because the two must agree or "is this message mine" is
+     * wrong for somebody.
+     */
+    userId: objectIdSchema,
+});
+/** `POST /api/v1/chat/auth-token` */
+export const chatAuthTokenSchema = z.object({
+    token: z.string(),
+    expiresAt: isoDateTimeSchema,
+    /** Seconds, so a client can schedule a refresh without parsing a date. */
+    expiresIn: z.number().int().positive(),
+});
+/** `POST /api/v1/chat/invitation` — permission to open a conversation with someone. */
+export const chatInvitationBodySchema = z.object({
+    userId: objectIdSchema,
+});
+export const chatInvitationSchema = z.object({
+    invitationToken: z.string(),
+    expiresAt: isoDateTimeSchema,
+});
+/** `POST /api/v1/chat/notify` — chat-server telling the backend to notify people. */
+export const chatNotifyBodySchema = z.object({
+    recipientIds: z.array(objectIdSchema).min(1),
+    conversationId: objectIdSchema,
+    senderId: objectIdSchema,
+    senderName: z.string(),
+    text: z.string(),
+});
+/** JWT `aud` on every chat token. chat-server accepts exactly this. */
+export const CHAT_TOKEN_AUDIENCE = 'gymmonk-chat-server';
+/** `purpose` claim marking an invitation. Auth tokens carry no purpose. */
+export const CHAT_INVITATION_PURPOSE = 'invitation';
+//# sourceMappingURL=chat.js.map

package/dist/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * gymmonk-schema — Chat\n * =====================\n * THE wire contract between `gymmonk-web-client` and `gymmonk-chat-server`, and\n * the only place either is allowed to name a socket event.\n *\n * It lives here rather than in the chat server because three codebases need it\n * and none of them owns the other two: the client emits, the chat server\n * handles, and gymmonk-backend mints the tokens that let the two meet. An event\n * name that differs by one character between any pair of them produces a\n * message nobody receives and no error anywhere, which is exactly the class of\n * bug a shared package exists to make impossible.\n *\n * @module gymmonk-schema/chat\n */\n\nimport { z } from 'zod';\nimport { isoDateTimeSchema, objectIdSchema } from './common.js';\n\n// ─── Socket events ───────────────────────────────────────────────────────────\n\n/**\n * Every socket event name.\n *\n * String literals rather than an enum, so both sides put the identical bytes on\n * the wire without either importing the other's runtime.\n */\nexport const CHAT_SOCKET_EVENTS = {\n  /** Server → client, on connect. The socket is up and awaiting auth. */\n  HELLO: 'hello',\n  /** Client → server. `{ token }`. Must arrive inside the auth window. */\n  AUTH: 'auth',\n  /** Server → client. `{ userId }` on success. */\n  AUTH_OK: 'auth:ok',\n  /** Server → client. `{ code, message }` for any failure, auth or otherwise. */\n  ERROR: 'error',\n\n  /** Client → server. Open a conversation and start receiving it live. */\n  CONVERSATION_JOIN: 'conversation:join',\n  /** Client → server. Leave it (navigated away). */\n  CONVERSATION_LEAVE: 'conversation:leave',\n\n  /** Client → server. `{ conversationId, clientMessageId, text }`. */\n  MESSAGE_SEND: 'message:send',\n  /** Server → everyone in the room, and the recipients' own rooms. */\n  MESSAGE_NEW: 'message:new',\n  /** Server → sender only. Their send, acknowledged and stored. */\n  MESSAGE_SENT: 'message:sent',\n  /** Client → server. Mark everything up to now as read. */\n  MESSAGE_READ: 'message:read',\n  /** Server → the room. `{ conversationId, userId, readAt }`. */\n  MESSAGE_READ_BY: 'message:read-by',\n\n  /** Client → server. `{ conversationId, typing }`. */\n  TYPING: 'typing',\n  /** Server → the other participants. `{ conversationId, userId, typing }`. */\n  TYPING_UPDATE: 'typing:update',\n\n  /** Server → the room. Who currently has this conversation open. */\n  PRESENCE_UPDATE: 'presence:update',\n} as const;\n\nexport type ChatSocketEvent = (typeof CHAT_SOCKET_EVENTS)[keyof typeof CHAT_SOCKET_EVENTS];\n\n// ─── Error codes ─────────────────────────────────────────────────────────────\n\n/** Stable codes on the `error` event. The client branches on these; the message is for logs. */\nexport const CHAT_ERROR = {\n  AUTH_TIMEOUT: 'AUTH_TIMEOUT',\n  AUTH_FAILED: 'AUTH_FAILED',\n  NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',\n  NOT_A_PARTICIPANT: 'NOT_A_PARTICIPANT',\n  CONVERSATION_NOT_FOUND: 'CONVERSATION_NOT_FOUND',\n  INVALID_PAYLOAD: 'INVALID_PAYLOAD',\n  RATE_LIMITED: 'RATE_LIMITED',\n  SERVER_ERROR: 'SERVER_ERROR',\n} as const;\n\nexport type ChatErrorCode = (typeof CHAT_ERROR)[keyof typeof CHAT_ERROR];\n\n// ─── Limits ──────────────────────────────────────────────────────────────────\n\n/** Longest message body accepted. Matches the column cap in the model. */\nexport const MAX_MESSAGE_LENGTH = 4000;\n\n/** Messages per page of history. */\nexport const MESSAGE_PAGE_SIZE = 50;\n\n/**\n * Messages one socket may send per minute.\n *\n * Not an anti-abuse boundary on its own: a member can only ever write to a\n * conversation their own backend authorised. This is what stops a broken client\n * looping a send from filling a collection.\n */\nexport const MESSAGE_RATE_PER_MINUTE = 60;\n\n/** How long an unauthenticated socket may hold a connection, in ms. */\nexport const CHAT_AUTH_TIMEOUT_MS = 10_000;\n\n/**\n * How long a typing indicator survives without a refresh, in ms.\n *\n * Someone who closes the app mid-sentence never sends `typing: false`, so the\n * indicator has to expire on its own or it stays on screen forever. The sender\n * re-emits well inside this window while they are still typing.\n */\nexport const TYPING_TIMEOUT_MS = 4_000;\n\n/** How often the sender re-emits `typing: true` while typing, in ms. */\nexport const TYPING_THROTTLE_MS = 2_000;\n\n// ─── Wire shapes ─────────────────────────────────────────────────────────────\n\n/** A participant, denormalised onto the conversation so a list renders without joins. */\nexport const chatParticipantSchema = z.object({\n  userId: objectIdSchema,\n  displayName: z.string(),\n  avatarUrl: z.string().nullable(),\n});\nexport type ChatParticipant = z.infer<typeof chatParticipantSchema>;\n\n/** A message as every client sees it. */\nexport const chatMessageSchema = z.object({\n  id: objectIdSchema,\n  conversationId: objectIdSchema,\n  senderId: objectIdSchema,\n  text: z.string(),\n  /** Echoed back so the sender can reconcile its optimistic row. */\n  clientMessageId: z.string(),\n  sentAt: isoDateTimeSchema,\n  readAt: isoDateTimeSchema.nullable(),\n  /** Deleted for everyone. `text` is then empty. */\n  deleted: z.boolean(),\n});\nexport type ChatMessage = z.infer<typeof chatMessageSchema>;\n\n/** The one-line preview a conversation row shows. */\nexport const chatLastMessageSchema = z.object({\n  text: z.string(),\n  senderId: objectIdSchema,\n  sentAt: isoDateTimeSchema,\n});\nexport type ChatLastMessage = z.infer<typeof chatLastMessageSchema>;\n\n/**\n * A conversation as the list screen sees it.\n *\n * `unreadCount` is the CALLER's, not a global figure: the same row means\n * different things to the two people in it.\n */\nexport const chatConversationSchema = z.object({\n  id: objectIdSchema,\n  participants: z.array(chatParticipantSchema),\n  lastMessage: chatLastMessageSchema.nullable(),\n  unreadCount: z.number().int().nonnegative(),\n  createdAt: isoDateTimeSchema,\n  /** Last activity. The inbox sorts on this, newest first. */\n  updatedAt: isoDateTimeSchema,\n});\nexport type ChatConversation = z.infer<typeof chatConversationSchema>;\n\n// ─── Event payloads ──────────────────────────────────────────────────────────\n\nexport interface ChatAuthPayload {\n  token: string;\n}\n\nexport interface ChatConversationRoomPayload {\n  conversationId: string;\n}\n\nexport interface ChatMessageSendPayload {\n  conversationId: string;\n  /** Client-generated idempotency key. A retry with the same value is not a second message. */\n  clientMessageId: string;\n  text: string;\n}\n\nexport interface ChatMessageReadPayload {\n  conversationId: string;\n}\n\nexport interface ChatTypingPayload {\n  conversationId: string;\n  typing: boolean;\n}\n\n// ─── Typed event maps ────────────────────────────────────────────────────────\n// Socket.io takes these as generics on both ends, so an event emitted with the\n// wrong payload is a compile error rather than a message nobody receives.\n\nexport interface ChatServerToClientEvents {\n  [CHAT_SOCKET_EVENTS.HELLO]: (payload: { message: string }) => void;\n  [CHAT_SOCKET_EVENTS.AUTH_OK]: (payload: { userId: string }) => void;\n  [CHAT_SOCKET_EVENTS.ERROR]: (payload: { code: string; message: string }) => void;\n  [CHAT_SOCKET_EVENTS.MESSAGE_NEW]: (message: ChatMessage) => void;\n  [CHAT_SOCKET_EVENTS.MESSAGE_SENT]: (payload: {\n    clientMessageId: string;\n    message: ChatMessage;\n  }) => void;\n  [CHAT_SOCKET_EVENTS.MESSAGE_READ_BY]: (payload: {\n    conversationId: string;\n    userId: string;\n    readAt: string;\n  }) => void;\n  [CHAT_SOCKET_EVENTS.TYPING_UPDATE]: (payload: {\n    conversationId: string;\n    userId: string;\n    typing: boolean;\n  }) => void;\n  [CHAT_SOCKET_EVENTS.PRESENCE_UPDATE]: (payload: {\n    conversationId: string;\n    userIds: string[];\n  }) => void;\n}\n\nexport interface ChatClientToServerEvents {\n  [CHAT_SOCKET_EVENTS.AUTH]: (payload: ChatAuthPayload) => void;\n  [CHAT_SOCKET_EVENTS.CONVERSATION_JOIN]: (payload: ChatConversationRoomPayload) => void;\n  [CHAT_SOCKET_EVENTS.CONVERSATION_LEAVE]: (payload: ChatConversationRoomPayload) => void;\n  [CHAT_SOCKET_EVENTS.MESSAGE_SEND]: (payload: ChatMessageSendPayload) => void;\n  [CHAT_SOCKET_EVENTS.MESSAGE_READ]: (payload: ChatMessageReadPayload) => void;\n  [CHAT_SOCKET_EVENTS.TYPING]: (payload: ChatTypingPayload) => void;\n}\n\n// ─── Backend bridge ──────────────────────────────────────────────────────────\n\n/** `GET /api/v1/chat/config` — where chat lives, whether it is on, and who the caller is. */\nexport const chatConfigSchema = z.object({\n  enabled: z.boolean(),\n  url: z.string().nullable(),\n  /**\n   * The caller's id AS CHAT-SERVER WILL SEE IT.\n   *\n   * Sourced from the same place that mints the token rather than from the\n   * client session, because the two must agree or \"is this message mine\" is\n   * wrong for somebody.\n   */\n  userId: objectIdSchema,\n});\nexport type ChatConfig = z.infer<typeof chatConfigSchema>;\n\n/** `POST /api/v1/chat/auth-token` */\nexport const chatAuthTokenSchema = z.object({\n  token: z.string(),\n  expiresAt: isoDateTimeSchema,\n  /** Seconds, so a client can schedule a refresh without parsing a date. */\n  expiresIn: z.number().int().positive(),\n});\nexport type ChatAuthToken = z.infer<typeof chatAuthTokenSchema>;\n\n/** `POST /api/v1/chat/invitation` — permission to open a conversation with someone. */\nexport const chatInvitationBodySchema = z.object({\n  userId: objectIdSchema,\n});\nexport type ChatInvitationBody = z.infer<typeof chatInvitationBodySchema>;\n\nexport const chatInvitationSchema = z.object({\n  invitationToken: z.string(),\n  expiresAt: isoDateTimeSchema,\n});\nexport type ChatInvitation = z.infer<typeof chatInvitationSchema>;\n\n/** `POST /api/v1/chat/notify` — chat-server telling the backend to notify people. */\nexport const chatNotifyBodySchema = z.object({\n  recipientIds: z.array(objectIdSchema).min(1),\n  conversationId: objectIdSchema,\n  senderId: objectIdSchema,\n  senderName: z.string(),\n  text: z.string(),\n});\nexport type ChatNotifyBody = z.infer<typeof chatNotifyBodySchema>;\n\n/** JWT `aud` on every chat token. chat-server accepts exactly this. */\nexport const CHAT_TOKEN_AUDIENCE = 'gymmonk-chat-server';\n\n/** `purpose` claim marking an invitation. Auth tokens carry no purpose. */\nexport const CHAT_INVITATION_PURPOSE = 'invitation';\n"]}

package/dist/index.d.ts

@@ -40,4 +40,6 @@ export * from './staff.js';
 export * from './subscription.js';
 export * from './user.js';
 export * from './workout-plan.js';
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=index.d.ts.map
+export * from './chat.js';
+export * from './social.js';

package/dist/index.js

@@ -54,4 +54,6 @@ export * from './staff.js';
 export * from './subscription.js';
 export * from './user.js';
 export * from './workout-plan.js';
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map
+export * from './chat.js';
+export * from './social.js';

package/dist/session.d.ts

@@ -14,6 +14,39 @@ export declare const sessionStatusSchema: z.ZodEnum<{
     completed: "completed";
 }>;
 export type SessionStatus = z.infer<typeof sessionStatusSchema>;
+/**
+ * The member's own stopwatch, which is NOT the session clock.
+ *
+ * Home shows two running times and they measure different things. The session
+ * clock is "how long have you been in the gym" — it runs from `checkInAt`,
+ * cannot be paused, and is derived rather than stored. This one is "how long
+ * has this set taken", and the member starts, pauses and resets it freely.
+ *
+ * Stored as ACCUMULATED + STARTED-AT rather than as a running total, because a
+ * total would need the server to tick. Elapsed is
+ * `accumulatedSec + (running ? now - startedAt : 0)`, so a paused stopwatch is
+ * a plain number, a running one survives a refresh or a dead battery, and no
+ * job has to write to the database once a second.
+ *
+ * `startedAt` is null exactly when `running` is false; the pair is a small
+ * state machine, and the backend is the only writer.
+ */
+export declare const sessionStopwatchSchema: z.ZodObject<{
+    running: z.ZodBoolean;
+    accumulatedSec: z.ZodNumber;
+    startedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type SessionStopwatch = z.infer<typeof sessionStopwatchSchema>;
+/** A stopwatch that has never been started. */
+export declare const IDLE_STOPWATCH: SessionStopwatch;
+/**
+ * Resolve a stopwatch to whole seconds elapsed.
+ *
+ * Shared rather than reimplemented on each side: the backend needs it to bank
+ * time on pause, and the client needs it to render every tick. Two copies of
+ * this arithmetic would drift the moment one of them forgot the running run.
+ */
+export declare function stopwatchElapsedSec(stopwatch: SessionStopwatch, now?: Date): number;
 export declare const workoutSessionSchema: z.ZodObject<{
     id: z.ZodString;
     userId: z.ZodString;
@@ -36,6 +69,11 @@ export declare const workoutSessionSchema: z.ZodObject<{
     }>>;
     completedExerciseIds: z.ZodArray<z.ZodString>;
     totalExercises: z.ZodNumber;
+    stopwatch: z.ZodObject<{
+        running: z.ZodBoolean;
+        accumulatedSec: z.ZodNumber;
+        startedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export type WorkoutSession = z.infer<typeof workoutSessionSchema>;
 /**
@@ -67,6 +105,22 @@ export declare const markExerciseDoneBodySchema: z.ZodObject<{
     done: z.ZodBoolean;
 }, z.core.$strip>;
 export type MarkExerciseDoneBody = z.infer<typeof markExerciseDoneBodySchema>;
+/**
+ * Drive the set stopwatch.
+ *
+ * An ACTION, not a state patch. The client says what the member pressed and the
+ * server computes the resulting `{ running, accumulatedSec, startedAt }` — which
+ * keeps the banking arithmetic in one place and means a client cannot post an
+ * arbitrary elapsed time to inflate a workout.
+ */
+export declare const stopwatchActionBodySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        start: "start";
+        pause: "pause";
+        reset: "reset";
+    }>;
+}, z.core.$strip>;
+export type StopwatchActionBody = z.infer<typeof stopwatchActionBodySchema>;
 export declare const attendanceStatusSchema: z.ZodEnum<{
     present: "present";
     absent: "absent";

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,mBAAmB;;;;EAA0C,CAAC;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;iBAW/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB;;iBAE5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,0BAA0B;;;iBAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E,eAAO,MAAM,sBAAsB;;;;EAAwC,CAAC;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,qBAAqB;;;;;;iBAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,sEAAsE;AACtE,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAOnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,mBAAmB;;;;EAA0C,CAAC;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB;;;;iBAMjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,+CAA+C;AAC/C,eAAO,MAAM,cAAc,EAAE,gBAI5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAO/F;AAID,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB;;iBAE5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,0BAA0B;;;iBAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;;iBAEpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E,eAAO,MAAM,sBAAsB;;;;EAAwC,CAAC;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,qBAAqB;;;;;;iBAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,sEAAsE;AACtE,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAOnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/session.js

@@ -13,6 +13,54 @@ import { isoDateSchema, isoDateTimeSchema, objectIdSchema, optionalTrimmedString
 import { weekdaySchema } from './shared.js';
 // ─── Live session widget status ──────────────────────────────────────────────
 export const sessionStatusSchema = z.enum(['idle', 'active', 'completed']);
+// ─── The set stopwatch ───────────────────────────────────────────────────────
+/**
+ * The member's own stopwatch, which is NOT the session clock.
+ *
+ * Home shows two running times and they measure different things. The session
+ * clock is "how long have you been in the gym" — it runs from `checkInAt`,
+ * cannot be paused, and is derived rather than stored. This one is "how long
+ * has this set taken", and the member starts, pauses and resets it freely.
+ *
+ * Stored as ACCUMULATED + STARTED-AT rather than as a running total, because a
+ * total would need the server to tick. Elapsed is
+ * `accumulatedSec + (running ? now - startedAt : 0)`, so a paused stopwatch is
+ * a plain number, a running one survives a refresh or a dead battery, and no
+ * job has to write to the database once a second.
+ *
+ * `startedAt` is null exactly when `running` is false; the pair is a small
+ * state machine, and the backend is the only writer.
+ */
+export const sessionStopwatchSchema = z.object({
+    running: z.boolean(),
+    /** Seconds banked by previous runs, excluding any run in progress. */
+    accumulatedSec: z.number().int().nonnegative(),
+    /** When the current run began. Null while paused. */
+    startedAt: isoDateTimeSchema.nullable(),
+});
+/** A stopwatch that has never been started. */
+export const IDLE_STOPWATCH = {
+    running: false,
+    accumulatedSec: 0,
+    startedAt: null,
+};
+/**
+ * Resolve a stopwatch to whole seconds elapsed.
+ *
+ * Shared rather than reimplemented on each side: the backend needs it to bank
+ * time on pause, and the client needs it to render every tick. Two copies of
+ * this arithmetic would drift the moment one of them forgot the running run.
+ */
+export function stopwatchElapsedSec(stopwatch, now = new Date()) {
+    if (!stopwatch.running || !stopwatch.startedAt)
+        return stopwatch.accumulatedSec;
+    const started = Date.parse(stopwatch.startedAt);
+    if (Number.isNaN(started))
+        return stopwatch.accumulatedSec;
+    // Floored at the banked value: a client clock behind the server's would
+    // otherwise make the number run backwards.
+    return stopwatch.accumulatedSec + Math.max(0, Math.floor((now.getTime() - started) / 1000));
+}
 // ─── Session entity ──────────────────────────────────────────────────────────
 export const workoutSessionSchema = z.object({
     id: objectIdSchema,
@@ -25,6 +73,7 @@ export const workoutSessionSchema = z.object({
     planWeekday: weekdaySchema.nullable(),
     completedExerciseIds: z.array(objectIdSchema),
     totalExercises: z.number().int().nonnegative(),
+    stopwatch: sessionStopwatchSchema,
 });
 // ─── Session mutations ───────────────────────────────────────────────────────
 /**
@@ -53,6 +102,17 @@ export const markExerciseDoneBodySchema = z.object({
     exerciseId: objectIdSchema,
     done: z.boolean(),
 });
+/**
+ * Drive the set stopwatch.
+ *
+ * An ACTION, not a state patch. The client says what the member pressed and the
+ * server computes the resulting `{ running, accumulatedSec, startedAt }` — which
+ * keeps the banking arithmetic in one place and means a client cannot post an
+ * arbitrary elapsed time to inflate a workout.
+ */
+export const stopwatchActionBodySchema = z.object({
+    action: z.enum(['start', 'pause', 'reset']),
+});
 // ─── Attendance ──────────────────────────────────────────────────────────────
 export const attendanceStatusSchema = z.enum(['present', 'absent', 'rest']);
 export const attendanceEntrySchema = z.object({

package/dist/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,gFAAgF;AAEhF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;AAG3E,gFAAgF;AAEhF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,EAAE,EAAE,cAAc;IAClB,MAAM,EAAE,cAAc;IACtB,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,mBAAmB;IAC3B,SAAS,EAAE,iBAAiB;IAC5B,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACxC,kEAAkE;IAClE,WAAW,EAAE,aAAa,CAAC,QAAQ,EAAE;IACrC,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CAC/C,CAAC,CAAC;AAGH,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,iBAAiB;CACxB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,iBAAiB;CACxB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,UAAU,EAAE,cAAc;IAC1B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;CAClB,CAAC,CAAC;AAGH,gFAAgF;AAEhF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAG5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,aAAa;IACnB,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACvC,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACxC,MAAM,EAAE,sBAAsB;CAC/B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAC3D,MAAM,EAAE,cAAc,CAAC,QAAQ,EAAE;IACjC,IAAI,EAAE,aAAa,CAAC,QAAQ,EAAE;IAC9B,EAAE,EAAE,aAAa,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,MAAM,EAAE,cAAc;IACtB,IAAI,EAAE,aAAa,CAAC,QAAQ,EAAE;IAC9B,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,SAAS,CAAC;IACjD,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACvC,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACxC,IAAI,EAAE,qBAAqB,CAAC,GAAG,CAAC;CACjC,CAAC,CAAC","sourcesContent":["/**\n * gymmonk-schema — Workout sessions, check-in & attendance\n * ========================================================\n * A member checks in to start a live session, marks exercises done, and checks\n * out. Sessions roll up into attendance records the owner can review, and can\n * also be recorded directly by an owner (manual attendance marking).\n *\n * @module gymmonk-schema/session\n */\n\nimport { z } from 'zod';\nimport { checkInCodeSchema } from './check-in.js';\nimport {\n  isoDateSchema,\n  isoDateTimeSchema,\n  objectIdSchema,\n  optionalTrimmedString,\n  paginationSchema,\n} from './common.js';\nimport { weekdaySchema } from './shared.js';\n\n// ─── Live session widget status ──────────────────────────────────────────────\n\nexport const sessionStatusSchema = z.enum(['idle', 'active', 'completed']);\nexport type SessionStatus = z.infer<typeof sessionStatusSchema>;\n\n// ─── Session entity ──────────────────────────────────────────────────────────\n\nexport const workoutSessionSchema = z.object({\n  id: objectIdSchema,\n  userId: objectIdSchema,\n  centerId: objectIdSchema,\n  status: sessionStatusSchema,\n  checkInAt: isoDateTimeSchema,\n  checkOutAt: isoDateTimeSchema.nullable(),\n  /** The plan weekday being trained, if the member is on a plan. */\n  planWeekday: weekdaySchema.nullable(),\n  completedExerciseIds: z.array(objectIdSchema),\n  totalExercises: z.number().int().nonnegative(),\n});\nexport type WorkoutSession = z.infer<typeof workoutSessionSchema>;\n\n// ─── Session mutations ───────────────────────────────────────────────────────\n\n/**\n * Check in by scanning the gym's QR poster.\n *\n * `code` is REQUIRED and is the whole point: the center is resolved FROM the\n * scanned code, never from a client-supplied `centerId`. An earlier version of\n * this body took an optional `centerId`, which meant any authenticated member\n * could mark themselves present from their sofa. Presence has to be proven by\n * being close enough to the poster to photograph it.\n *\n * Staff marking someone present by hand is a different, authorised path —\n * `markAttendanceBodySchema` below.\n */\nexport const checkInBodySchema = z.object({\n  code: checkInCodeSchema,\n});\nexport type CheckInBody = z.infer<typeof checkInBodySchema>;\n\n/**\n * Check out — the same poster, scanned again. Verified against the session's\n * OWN center, so a member cannot close a session by scanning a different gym.\n */\nexport const checkOutBodySchema = z.object({\n  code: checkInCodeSchema,\n});\nexport type CheckOutBody = z.infer<typeof checkOutBodySchema>;\n\nexport const markExerciseDoneBodySchema = z.object({\n  exerciseId: objectIdSchema,\n  done: z.boolean(),\n});\nexport type MarkExerciseDoneBody = z.infer<typeof markExerciseDoneBodySchema>;\n\n// ─── Attendance ──────────────────────────────────────────────────────────────\n\nexport const attendanceStatusSchema = z.enum(['present', 'absent', 'rest']);\nexport type AttendanceStatus = z.infer<typeof attendanceStatusSchema>;\n\nexport const attendanceEntrySchema = z.object({\n  date: isoDateSchema,\n  checkInAt: isoDateTimeSchema.nullable(),\n  checkOutAt: isoDateTimeSchema.nullable(),\n  status: attendanceStatusSchema,\n});\nexport type AttendanceEntry = z.infer<typeof attendanceEntrySchema>;\n\nexport const attendanceQuerySchema = paginationSchema.extend({\n  userId: objectIdSchema.optional(),\n  from: isoDateSchema.optional(),\n  to: isoDateSchema.optional(),\n});\nexport type AttendanceQuery = z.infer<typeof attendanceQuerySchema>;\n\n/** Owner marking attendance for a member or staff member manually. */\nexport const markAttendanceBodySchema = z.object({\n  userId: objectIdSchema,\n  date: isoDateSchema.optional(),\n  status: attendanceStatusSchema.default('present'),\n  checkInAt: isoDateTimeSchema.optional(),\n  checkOutAt: isoDateTimeSchema.optional(),\n  note: optionalTrimmedString(160),\n});\nexport type MarkAttendanceBody = z.infer<typeof markAttendanceBodySchema>;\n"]}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * gymmonk-schema — Workout sessions, check-in & attendance\n * ========================================================\n * A member checks in to start a live session, marks exercises done, and checks\n * out. Sessions roll up into attendance records the owner can review, and can\n * also be recorded directly by an owner (manual attendance marking).\n *\n * @module gymmonk-schema/session\n */\n\nimport { z } from 'zod';\nimport { checkInCodeSchema } from './check-in.js';\nimport {\n  isoDateSchema,\n  isoDateTimeSchema,\n  objectIdSchema,\n  optionalTrimmedString,\n  paginationSchema,\n} from './common.js';\nimport { weekdaySchema } from './shared.js';\n\n// ─── Live session widget status ──────────────────────────────────────────────\n\nexport const sessionStatusSchema = z.enum(['idle', 'active', 'completed']);\nexport type SessionStatus = z.infer<typeof sessionStatusSchema>;\n\n// ─── The set stopwatch ───────────────────────────────────────────────────────\n\n/**\n * The member's own stopwatch, which is NOT the session clock.\n *\n * Home shows two running times and they measure different things. The session\n * clock is \"how long have you been in the gym\" — it runs from `checkInAt`,\n * cannot be paused, and is derived rather than stored. This one is \"how long\n * has this set taken\", and the member starts, pauses and resets it freely.\n *\n * Stored as ACCUMULATED + STARTED-AT rather than as a running total, because a\n * total would need the server to tick. Elapsed is\n * `accumulatedSec + (running ? now - startedAt : 0)`, so a paused stopwatch is\n * a plain number, a running one survives a refresh or a dead battery, and no\n * job has to write to the database once a second.\n *\n * `startedAt` is null exactly when `running` is false; the pair is a small\n * state machine, and the backend is the only writer.\n */\nexport const sessionStopwatchSchema = z.object({\n  running: z.boolean(),\n  /** Seconds banked by previous runs, excluding any run in progress. */\n  accumulatedSec: z.number().int().nonnegative(),\n  /** When the current run began. Null while paused. */\n  startedAt: isoDateTimeSchema.nullable(),\n});\nexport type SessionStopwatch = z.infer<typeof sessionStopwatchSchema>;\n\n/** A stopwatch that has never been started. */\nexport const IDLE_STOPWATCH: SessionStopwatch = {\n  running: false,\n  accumulatedSec: 0,\n  startedAt: null,\n};\n\n/**\n * Resolve a stopwatch to whole seconds elapsed.\n *\n * Shared rather than reimplemented on each side: the backend needs it to bank\n * time on pause, and the client needs it to render every tick. Two copies of\n * this arithmetic would drift the moment one of them forgot the running run.\n */\nexport function stopwatchElapsedSec(stopwatch: SessionStopwatch, now: Date = new Date()): number {\n  if (!stopwatch.running || !stopwatch.startedAt) return stopwatch.accumulatedSec;\n  const started = Date.parse(stopwatch.startedAt);\n  if (Number.isNaN(started)) return stopwatch.accumulatedSec;\n  // Floored at the banked value: a client clock behind the server's would\n  // otherwise make the number run backwards.\n  return stopwatch.accumulatedSec + Math.max(0, Math.floor((now.getTime() - started) / 1000));\n}\n\n// ─── Session entity ──────────────────────────────────────────────────────────\n\nexport const workoutSessionSchema = z.object({\n  id: objectIdSchema,\n  userId: objectIdSchema,\n  centerId: objectIdSchema,\n  status: sessionStatusSchema,\n  checkInAt: isoDateTimeSchema,\n  checkOutAt: isoDateTimeSchema.nullable(),\n  /** The plan weekday being trained, if the member is on a plan. */\n  planWeekday: weekdaySchema.nullable(),\n  completedExerciseIds: z.array(objectIdSchema),\n  totalExercises: z.number().int().nonnegative(),\n  stopwatch: sessionStopwatchSchema,\n});\nexport type WorkoutSession = z.infer<typeof workoutSessionSchema>;\n\n// ─── Session mutations ───────────────────────────────────────────────────────\n\n/**\n * Check in by scanning the gym's QR poster.\n *\n * `code` is REQUIRED and is the whole point: the center is resolved FROM the\n * scanned code, never from a client-supplied `centerId`. An earlier version of\n * this body took an optional `centerId`, which meant any authenticated member\n * could mark themselves present from their sofa. Presence has to be proven by\n * being close enough to the poster to photograph it.\n *\n * Staff marking someone present by hand is a different, authorised path —\n * `markAttendanceBodySchema` below.\n */\nexport const checkInBodySchema = z.object({\n  code: checkInCodeSchema,\n});\nexport type CheckInBody = z.infer<typeof checkInBodySchema>;\n\n/**\n * Check out — the same poster, scanned again. Verified against the session's\n * OWN center, so a member cannot close a session by scanning a different gym.\n */\nexport const checkOutBodySchema = z.object({\n  code: checkInCodeSchema,\n});\nexport type CheckOutBody = z.infer<typeof checkOutBodySchema>;\n\nexport const markExerciseDoneBodySchema = z.object({\n  exerciseId: objectIdSchema,\n  done: z.boolean(),\n});\nexport type MarkExerciseDoneBody = z.infer<typeof markExerciseDoneBodySchema>;\n\n/**\n * Drive the set stopwatch.\n *\n * An ACTION, not a state patch. The client says what the member pressed and the\n * server computes the resulting `{ running, accumulatedSec, startedAt }` — which\n * keeps the banking arithmetic in one place and means a client cannot post an\n * arbitrary elapsed time to inflate a workout.\n */\nexport const stopwatchActionBodySchema = z.object({\n  action: z.enum(['start', 'pause', 'reset']),\n});\nexport type StopwatchActionBody = z.infer<typeof stopwatchActionBodySchema>;\n\n// ─── Attendance ──────────────────────────────────────────────────────────────\n\nexport const attendanceStatusSchema = z.enum(['present', 'absent', 'rest']);\nexport type AttendanceStatus = z.infer<typeof attendanceStatusSchema>;\n\nexport const attendanceEntrySchema = z.object({\n  date: isoDateSchema,\n  checkInAt: isoDateTimeSchema.nullable(),\n  checkOutAt: isoDateTimeSchema.nullable(),\n  status: attendanceStatusSchema,\n});\nexport type AttendanceEntry = z.infer<typeof attendanceEntrySchema>;\n\nexport const attendanceQuerySchema = paginationSchema.extend({\n  userId: objectIdSchema.optional(),\n  from: isoDateSchema.optional(),\n  to: isoDateSchema.optional(),\n});\nexport type AttendanceQuery = z.infer<typeof attendanceQuerySchema>;\n\n/** Owner marking attendance for a member or staff member manually. */\nexport const markAttendanceBodySchema = z.object({\n  userId: objectIdSchema,\n  date: isoDateSchema.optional(),\n  status: attendanceStatusSchema.default('present'),\n  checkInAt: isoDateTimeSchema.optional(),\n  checkOutAt: isoDateTimeSchema.optional(),\n  note: optionalTrimmedString(160),\n});\nexport type MarkAttendanceBody = z.infer<typeof markAttendanceBodySchema>;\n"]}

package/dist/social.d.ts

@@ -0,0 +1,197 @@
+/**
+ * gymmonk-schema — Social graph (follow)
+ * ======================================
+ * The follow relationship and the people list it feeds.
+ *
+ * A follow is UNILATERAL: one row, one direction, no acceptance step. A mutual
+ * follow is two independent rows. That is what makes "do I follow them" and
+ * "do they follow me" separately answerable, and therefore what makes
+ * "Follow back" a state the UI can offer at all.
+ *
+ * @module gymmonk-schema/social
+ */
+import { z } from 'zod';
+/**
+ * How the viewer stands with one other person.
+ *
+ * Both directions are carried, and both timestamps with them. `followedYouAt`
+ * is what the Followers list shows as "· 2w", and `followsViewer` is the only
+ * thing that distinguishes a "Follow" button from a "Follow back" button.
+ */
+export declare const viewerSocialStateSchema: z.ZodObject<{
+    following: z.ZodBoolean;
+    followsViewer: z.ZodBoolean;
+    followedAt: z.ZodNullable<z.ZodISODateTime>;
+    followedYouAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type ViewerSocialState = z.infer<typeof viewerSocialStateSchema>;
+/** Nobody follows anybody. The shape a missing lookup falls back to. */
+export declare const EMPTY_VIEWER_SOCIAL_STATE: ViewerSocialState;
+/**
+ * "Followed by Priya, Rahul + 3 more" — this person's MUTUAL FOLLOWERS.
+ *
+ * The direction is easy to get backwards and the label depends on it: a mutual
+ * is someone the VIEWER FOLLOWS who ALSO FOLLOWS this person. "Followed by
+ * Priya" says Priya follows them, and Priya is worth naming because the viewer
+ * follows Priya and will recognise her. The inverse set (people they both
+ * follow) is a different thing and reads as a lie under this label.
+ *
+ * `count` is the TOTAL; `avatars` and `sampleNames` carry only the handful
+ * actually rendered. Sending every mutual so the client can count them would
+ * put an unbounded array on a list row for one line of secondary text.
+ */
+export declare const mutualsSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    avatars: z.ZodArray<z.ZodNullable<z.ZodString>>;
+    sampleNames: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type Mutuals = z.infer<typeof mutualsSchema>;
+/** How many faces and names a mutuals line carries. */
+export declare const MUTUALS_SAMPLE_SIZE = 3;
+/**
+ * Why this person is in the viewer's list.
+ *
+ *   `gym`        at the viewer's gym, not followed
+ *   `following`  followed by the viewer, and NOT at their gym any more
+ *   `both`       at the gym AND followed
+ *
+ * The distinction is load-bearing rather than cosmetic. Messaging is gated on
+ * sharing a gym, so a `following` row must not offer a Message button the
+ * backend will refuse. jansathi has no equivalent because its People tab is the
+ * whole community and there is no second axis to be on the wrong side of.
+ */
+export declare const buddyRelationSchema: z.ZodEnum<{
+    gym: "gym";
+    following: "following";
+    both: "both";
+}>;
+export type BuddyRelation = z.infer<typeof buddyRelationSchema>;
+/** Which slice of the list the caller asked for. */
+export declare const buddyFilterSchema: z.ZodEnum<{
+    all: "all";
+    gym: "gym";
+    following: "following";
+    followers: "followers";
+}>;
+export type BuddyFilter = z.infer<typeof buddyFilterSchema>;
+export declare const BUDDY_FILTER_VALUES: readonly ["all", "gym", "following", "followers"];
+/**
+ * One person as a peer is allowed to see them.
+ *
+ * Deliberately NOT derived from the owner's member projection. That one carries
+ * phone numbers, addresses, emergency contacts, dues and attendance, and the
+ * only reliable way to guarantee none of it reaches a peer is for this to be a
+ * separate shape rather than the same one with fields removed.
+ */
+export declare const buddySchema: z.ZodObject<{
+    userId: z.ZodString;
+    name: z.ZodString;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+    memberSince: z.ZodNullable<z.ZodString>;
+    lastActiveAt: z.ZodNullable<z.ZodISODateTime>;
+    relation: z.ZodEnum<{
+        gym: "gym";
+        following: "following";
+        both: "both";
+    }>;
+    viewer: z.ZodObject<{
+        following: z.ZodBoolean;
+        followsViewer: z.ZodBoolean;
+        followedAt: z.ZodNullable<z.ZodISODateTime>;
+        followedYouAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>;
+    mutuals: z.ZodNullable<z.ZodObject<{
+        count: z.ZodNumber;
+        avatars: z.ZodArray<z.ZodNullable<z.ZodString>>;
+        sampleNames: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Buddy = z.infer<typeof buddySchema>;
+/** `GET /api/v1/members/at-my-gym?filter=` */
+export declare const buddyListQuerySchema: z.ZodObject<{
+    filter: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        gym: "gym";
+        following: "following";
+        followers: "followers";
+    }>>;
+}, z.core.$strip>;
+export type BuddyListQuery = z.infer<typeof buddyListQuerySchema>;
+/**
+ * The state AFTER a toggle.
+ *
+ * A toggle rather than separate follow and unfollow endpoints: a button acting
+ * on stale state can send the wrong one, and then the server has to decide
+ * whether a double unfollow is an error. A toggle has one meaning whatever the
+ * client believed, and this response says what is now true.
+ */
+export declare const toggleFollowResultSchema: z.ZodObject<{
+    targetUserId: z.ZodString;
+    following: z.ZodBoolean;
+    followerCount: z.ZodNumber;
+}, z.core.$strip>;
+export type ToggleFollowResult = z.infer<typeof toggleFollowResultSchema>;
+/**
+ * `GET /api/v1/users/:id/social` — who this person is, and where the viewer
+ * stands with them.
+ *
+ * `person` is the SAME shape as a row in the people list, deliberately. The
+ * profile screen and the list row show the same facts and offer the same
+ * actions, so giving them two shapes would mean two places to add a field and
+ * one of them being forgotten.
+ */
+export declare const socialSnapshotSchema: z.ZodObject<{
+    person: z.ZodObject<{
+        userId: z.ZodString;
+        name: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+        memberSince: z.ZodNullable<z.ZodString>;
+        lastActiveAt: z.ZodNullable<z.ZodISODateTime>;
+        relation: z.ZodEnum<{
+            gym: "gym";
+            following: "following";
+            both: "both";
+        }>;
+        viewer: z.ZodObject<{
+            following: z.ZodBoolean;
+            followsViewer: z.ZodBoolean;
+            followedAt: z.ZodNullable<z.ZodISODateTime>;
+            followedYouAt: z.ZodNullable<z.ZodISODateTime>;
+        }, z.core.$strip>;
+        mutuals: z.ZodNullable<z.ZodObject<{
+            count: z.ZodNumber;
+            avatars: z.ZodArray<z.ZodNullable<z.ZodString>>;
+            sampleNames: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    followerCount: z.ZodNumber;
+    followingCount: z.ZodNumber;
+}, z.core.$strip>;
+export type SocialSnapshot = z.infer<typeof socialSnapshotSchema>;
+/**
+ * Blocking is ONE-WAY in storage and BIDIRECTIONAL in effect.
+ *
+ * One row records that A blocked B. Nothing records the reverse, because B has
+ * not blocked anybody. But every gate that consults it looks BOTH ways: B must
+ * not be able to follow, message or even see A, or the block would only work
+ * against the person who asked for it.
+ *
+ * Blocking is also a reset, not a mute: it tears down any follow in either
+ * direction and freezes any conversation the two had. Leaving a follow in place
+ * would keep the blocked person in the blocker's follower count, which is
+ * exactly the connection they just severed.
+ */
+export declare const blockedUserSchema: z.ZodObject<{
+    userId: z.ZodString;
+    name: z.ZodString;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+    blockedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type BlockedUser = z.infer<typeof blockedUserSchema>;
+/** `POST /api/v1/users/:id/block` — the state AFTER the toggle. */
+export declare const toggleBlockResultSchema: z.ZodObject<{
+    targetUserId: z.ZodString;
+    blocked: z.ZodBoolean;
+}, z.core.$strip>;
+export type ToggleBlockResult = z.infer<typeof toggleBlockResultSchema>;
+//# sourceMappingURL=social.d.ts.map

package/dist/social.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"social.d.ts","sourceRoot":"","sources":["../src/social.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,EAAE,iBAKvC,CAAC;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;iBAMxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB;;;;EAAuC,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,oDAAoD;AACpD,eAAO,MAAM,iBAAiB;;;;;EAAmD,CAAC;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB,mDAAoD,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;iBAmBtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB;;;;;;;iBAE/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;iBAInC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,oFAAoF;AACpF,eAAO,MAAM,oBAAoB;;;;;;;;;iBAI/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/social.js

@@ -0,0 +1,165 @@
+/**
+ * gymmonk-schema — Social graph (follow)
+ * ======================================
+ * The follow relationship and the people list it feeds.
+ *
+ * A follow is UNILATERAL: one row, one direction, no acceptance step. A mutual
+ * follow is two independent rows. That is what makes "do I follow them" and
+ * "do they follow me" separately answerable, and therefore what makes
+ * "Follow back" a state the UI can offer at all.
+ *
+ * @module gymmonk-schema/social
+ */
+import { z } from 'zod';
+import { isoDateTimeSchema, objectIdSchema } from './common.js';
+// ─── Viewer state ────────────────────────────────────────────────────────────
+/**
+ * How the viewer stands with one other person.
+ *
+ * Both directions are carried, and both timestamps with them. `followedYouAt`
+ * is what the Followers list shows as "· 2w", and `followsViewer` is the only
+ * thing that distinguishes a "Follow" button from a "Follow back" button.
+ */
+export const viewerSocialStateSchema = z.object({
+    /** The viewer follows them. */
+    following: z.boolean(),
+    /** They follow the viewer. */
+    followsViewer: z.boolean(),
+    /** When the viewer started following them. Null when they do not. */
+    followedAt: isoDateTimeSchema.nullable(),
+    /** When they started following the viewer. Null when they do not. */
+    followedYouAt: isoDateTimeSchema.nullable(),
+});
+/** Nobody follows anybody. The shape a missing lookup falls back to. */
+export const EMPTY_VIEWER_SOCIAL_STATE = {
+    following: false,
+    followsViewer: false,
+    followedAt: null,
+    followedYouAt: null,
+};
+// ─── Mutuals ─────────────────────────────────────────────────────────────────
+/**
+ * "Followed by Priya, Rahul + 3 more" — this person's MUTUAL FOLLOWERS.
+ *
+ * The direction is easy to get backwards and the label depends on it: a mutual
+ * is someone the VIEWER FOLLOWS who ALSO FOLLOWS this person. "Followed by
+ * Priya" says Priya follows them, and Priya is worth naming because the viewer
+ * follows Priya and will recognise her. The inverse set (people they both
+ * follow) is a different thing and reads as a lie under this label.
+ *
+ * `count` is the TOTAL; `avatars` and `sampleNames` carry only the handful
+ * actually rendered. Sending every mutual so the client can count them would
+ * put an unbounded array on a list row for one line of secondary text.
+ */
+export const mutualsSchema = z.object({
+    count: z.number().int().nonnegative(),
+    /** Up to three, for the stacked faces. An entry is null when that person has no photo. */
+    avatars: z.array(z.string().nullable()),
+    /** Up to three names, for the sentence. */
+    sampleNames: z.array(z.string()),
+});
+/** How many faces and names a mutuals line carries. */
+export const MUTUALS_SAMPLE_SIZE = 3;
+// ─── People list ─────────────────────────────────────────────────────────────
+/**
+ * Why this person is in the viewer's list.
+ *
+ *   `gym`        at the viewer's gym, not followed
+ *   `following`  followed by the viewer, and NOT at their gym any more
+ *   `both`       at the gym AND followed
+ *
+ * The distinction is load-bearing rather than cosmetic. Messaging is gated on
+ * sharing a gym, so a `following` row must not offer a Message button the
+ * backend will refuse. jansathi has no equivalent because its People tab is the
+ * whole community and there is no second axis to be on the wrong side of.
+ */
+export const buddyRelationSchema = z.enum(['gym', 'following', 'both']);
+/** Which slice of the list the caller asked for. */
+export const buddyFilterSchema = z.enum(['all', 'gym', 'following', 'followers']);
+export const BUDDY_FILTER_VALUES = ['all', 'gym', 'following', 'followers'];
+/**
+ * One person as a peer is allowed to see them.
+ *
+ * Deliberately NOT derived from the owner's member projection. That one carries
+ * phone numbers, addresses, emergency contacts, dues and attendance, and the
+ * only reliable way to guarantee none of it reaches a peer is for this to be a
+ * separate shape rather than the same one with fields removed.
+ */
+export const buddySchema = z.object({
+    /** The USER id. This is who you follow and message, not a profile row. */
+    userId: objectIdSchema,
+    name: z.string(),
+    avatarUrl: z.string().nullable(),
+    /** "Member since Mar 2025", or null for someone with no membership history here. */
+    memberSince: z.string().nullable(),
+    /**
+     * When this person was last seen in the app. Null if never.
+     *
+     * Carried so the list can offer a "Recently active" sort. It is deliberately
+     * a raw instant rather than a rendered "2h ago": the client is the only side
+     * that knows what time it is where the reader is sitting, and a string
+     * formatted on the server goes stale the moment it is cached.
+     */
+    lastActiveAt: isoDateTimeSchema.nullable(),
+    relation: buddyRelationSchema,
+    viewer: viewerSocialStateSchema,
+    mutuals: mutualsSchema.nullable(),
+});
+/** `GET /api/v1/members/at-my-gym?filter=` */
+export const buddyListQuerySchema = z.object({
+    filter: buddyFilterSchema.default('all'),
+});
+// ─── Toggle ──────────────────────────────────────────────────────────────────
+/**
+ * The state AFTER a toggle.
+ *
+ * A toggle rather than separate follow and unfollow endpoints: a button acting
+ * on stale state can send the wrong one, and then the server has to decide
+ * whether a double unfollow is an error. A toggle has one meaning whatever the
+ * client believed, and this response says what is now true.
+ */
+export const toggleFollowResultSchema = z.object({
+    targetUserId: objectIdSchema,
+    following: z.boolean(),
+    followerCount: z.number().int().nonnegative(),
+});
+/**
+ * `GET /api/v1/users/:id/social` — who this person is, and where the viewer
+ * stands with them.
+ *
+ * `person` is the SAME shape as a row in the people list, deliberately. The
+ * profile screen and the list row show the same facts and offer the same
+ * actions, so giving them two shapes would mean two places to add a field and
+ * one of them being forgotten.
+ */
+export const socialSnapshotSchema = z.object({
+    person: buddySchema,
+    followerCount: z.number().int().nonnegative(),
+    followingCount: z.number().int().nonnegative(),
+});
+// ─── Block ───────────────────────────────────────────────────────────────────
+/**
+ * Blocking is ONE-WAY in storage and BIDIRECTIONAL in effect.
+ *
+ * One row records that A blocked B. Nothing records the reverse, because B has
+ * not blocked anybody. But every gate that consults it looks BOTH ways: B must
+ * not be able to follow, message or even see A, or the block would only work
+ * against the person who asked for it.
+ *
+ * Blocking is also a reset, not a mute: it tears down any follow in either
+ * direction and freezes any conversation the two had. Leaving a follow in place
+ * would keep the blocked person in the blocker's follower count, which is
+ * exactly the connection they just severed.
+ */
+export const blockedUserSchema = z.object({
+    userId: objectIdSchema,
+    name: z.string(),
+    avatarUrl: z.string().nullable(),
+    blockedAt: isoDateTimeSchema,
+});
+/** `POST /api/v1/users/:id/block` — the state AFTER the toggle. */
+export const toggleBlockResultSchema = z.object({
+    targetUserId: objectIdSchema,
+    blocked: z.boolean(),
+});
+//# sourceMappingURL=social.js.map

package/dist/social.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social.js","sourceRoot":"","sources":["../src/social.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * gymmonk-schema — Social graph (follow)\n * ======================================\n * The follow relationship and the people list it feeds.\n *\n * A follow is UNILATERAL: one row, one direction, no acceptance step. A mutual\n * follow is two independent rows. That is what makes \"do I follow them\" and\n * \"do they follow me\" separately answerable, and therefore what makes\n * \"Follow back\" a state the UI can offer at all.\n *\n * @module gymmonk-schema/social\n */\n\nimport { z } from 'zod';\nimport { isoDateTimeSchema, objectIdSchema } from './common.js';\n\n// ─── Viewer state ────────────────────────────────────────────────────────────\n\n/**\n * How the viewer stands with one other person.\n *\n * Both directions are carried, and both timestamps with them. `followedYouAt`\n * is what the Followers list shows as \"· 2w\", and `followsViewer` is the only\n * thing that distinguishes a \"Follow\" button from a \"Follow back\" button.\n */\nexport const viewerSocialStateSchema = z.object({\n  /** The viewer follows them. */\n  following: z.boolean(),\n  /** They follow the viewer. */\n  followsViewer: z.boolean(),\n  /** When the viewer started following them. Null when they do not. */\n  followedAt: isoDateTimeSchema.nullable(),\n  /** When they started following the viewer. Null when they do not. */\n  followedYouAt: isoDateTimeSchema.nullable(),\n});\nexport type ViewerSocialState = z.infer<typeof viewerSocialStateSchema>;\n\n/** Nobody follows anybody. The shape a missing lookup falls back to. */\nexport const EMPTY_VIEWER_SOCIAL_STATE: ViewerSocialState = {\n  following: false,\n  followsViewer: false,\n  followedAt: null,\n  followedYouAt: null,\n};\n\n// ─── Mutuals ─────────────────────────────────────────────────────────────────\n\n/**\n * \"Followed by Priya, Rahul and 3 more\" — the people the viewer and this person\n * both follow.\n *\n * `count` is the TOTAL; `avatars` and `sampleNames` carry only the handful\n * actually rendered. Sending every mutual so the client can count them would\n * put an unbounded array on a list row for one line of secondary text.\n */\nexport const mutualsSchema = z.object({\n  count: z.number().int().nonnegative(),\n  /** Up to three, for the stacked faces. An entry is null when that person has no photo. */\n  avatars: z.array(z.string().nullable()),\n  /** Up to three names, for the sentence. */\n  sampleNames: z.array(z.string()),\n});\nexport type Mutuals = z.infer<typeof mutualsSchema>;\n\n/** How many faces and names a mutuals line carries. */\nexport const MUTUALS_SAMPLE_SIZE = 3;\n\n// ─── People list ─────────────────────────────────────────────────────────────\n\n/**\n * Why this person is in the viewer's list.\n *\n *   `gym`        at the viewer's gym, not followed\n *   `following`  followed by the viewer, and NOT at their gym any more\n *   `both`       at the gym AND followed\n *\n * The distinction is load-bearing rather than cosmetic. Messaging is gated on\n * sharing a gym, so a `following` row must not offer a Message button the\n * backend will refuse. jansathi has no equivalent because its People tab is the\n * whole community and there is no second axis to be on the wrong side of.\n */\nexport const buddyRelationSchema = z.enum(['gym', 'following', 'both']);\nexport type BuddyRelation = z.infer<typeof buddyRelationSchema>;\n\n/** Which slice of the list the caller asked for. */\nexport const buddyFilterSchema = z.enum(['all', 'gym', 'following', 'followers']);\nexport type BuddyFilter = z.infer<typeof buddyFilterSchema>;\n\nexport const BUDDY_FILTER_VALUES = ['all', 'gym', 'following', 'followers'] as const;\n\n/**\n * One person as a peer is allowed to see them.\n *\n * Deliberately NOT derived from the owner's member projection. That one carries\n * phone numbers, addresses, emergency contacts, dues and attendance, and the\n * only reliable way to guarantee none of it reaches a peer is for this to be a\n * separate shape rather than the same one with fields removed.\n */\nexport const buddySchema = z.object({\n  /** The USER id. This is who you follow and message, not a profile row. */\n  userId: objectIdSchema,\n  name: z.string(),\n  avatarUrl: z.string().nullable(),\n  /** \"Member since Mar 2025\", or null for someone with no membership history here. */\n  memberSince: z.string().nullable(),\n  /**\n   * When this person was last seen in the app. Null if never.\n   *\n   * Carried so the list can offer a \"Recently active\" sort. It is deliberately\n   * a raw instant rather than a rendered \"2h ago\": the client is the only side\n   * that knows what time it is where the reader is sitting, and a string\n   * formatted on the server goes stale the moment it is cached.\n   */\n  lastActiveAt: isoDateTimeSchema.nullable(),\n  relation: buddyRelationSchema,\n  viewer: viewerSocialStateSchema,\n  mutuals: mutualsSchema.nullable(),\n});\nexport type Buddy = z.infer<typeof buddySchema>;\n\n/** `GET /api/v1/members/at-my-gym?filter=` */\nexport const buddyListQuerySchema = z.object({\n  filter: buddyFilterSchema.default('all'),\n});\nexport type BuddyListQuery = z.infer<typeof buddyListQuerySchema>;\n\n// ─── Toggle ──────────────────────────────────────────────────────────────────\n\n/**\n * The state AFTER a toggle.\n *\n * A toggle rather than separate follow and unfollow endpoints: a button acting\n * on stale state can send the wrong one, and then the server has to decide\n * whether a double unfollow is an error. A toggle has one meaning whatever the\n * client believed, and this response says what is now true.\n */\nexport const toggleFollowResultSchema = z.object({\n  targetUserId: objectIdSchema,\n  following: z.boolean(),\n  followerCount: z.number().int().nonnegative(),\n});\nexport type ToggleFollowResult = z.infer<typeof toggleFollowResultSchema>;\n\n/** `GET /api/v1/users/:id/social` — one person's relationship plus their totals. */\nexport const socialSnapshotSchema = z.object({\n  viewer: viewerSocialStateSchema,\n  followerCount: z.number().int().nonnegative(),\n  followingCount: z.number().int().nonnegative(),\n});\nexport type SocialSnapshot = z.infer<typeof socialSnapshotSchema>;\n"]}

package/package.json

@@ -1,49 +1,49 @@
 {
-	"name": "gymmonk-schema",
-	"version": "0.15.0",
-	"description": "Shared Zod schemas, enums and domain types for GymMonk (fitness SaaS) — single source of truth (SSOT) consumed by gymmonk-backend and gymmonk-web-client.",
-	"type": "module",
-	"main": "./dist/index.js",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"README.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"build": "tsc -p tsconfig.json",
-		"type-check": "tsc --noEmit",
-		"lint": "biome lint .",
-		"format": "biome format --write .",
-		"check": "npm run type-check && biome check --write .",
-		"check:staged": "biome check --staged --write --no-errors-on-unmatched",
-		"prepublishOnly": "npm run build && npm run check"
-	},
-	"keywords": [
-		"zod",
-		"schema",
-		"gymmonk",
-		"gym",
-		"fitness",
-		"typescript"
-	],
-	"author": "Hari",
-	"license": "MIT",
-	"peerDependencies": {
-		"zod": "^4.4.0"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.4.2",
-		"@types/node": "^24.10.1",
-		"typescript": "^5.9.3",
-		"zod": "^4.4.3"
-	}
-}
+  "name": "gymmonk-schema",
+  "version": "0.17.0",
+  "description": "Shared Zod schemas, enums and domain types for GymMonk (fitness SaaS) — single source of truth (SSOT) consumed by gymmonk-backend and gymmonk-web-client.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "type-check": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "npm run type-check && biome check --write .",
+    "check:staged": "biome check --staged --write --no-errors-on-unmatched",
+    "prepublishOnly": "npm run build && npm run check"
+  },
+  "keywords": [
+    "zod",
+    "schema",
+    "gymmonk",
+    "gym",
+    "fitness",
+    "typescript"
+  ],
+  "author": "Hari",
+  "license": "MIT",
+  "peerDependencies": {
+    "zod": "^4.4.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.2",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  }
+}