jansathi-community-schema 0.19.0 → 0.22.0

package/dist/comment.d.ts

@@ -2,13 +2,14 @@
  * Comment wire shapes (with one-level reply nesting).
  *
  * Comments attach to any feed item via `(contentKind, contentId)` — the
- * same polymorphic key used by reactions and upvotes. One level of
+ * same polymorphic key used by reactions and votes. One level of
  * nesting only: a reply to a comment is allowed; a reply to a reply
  * is rejected at the server.
  *
- * The shape mirrors the post's `viewer` pattern so the client can
- * render an edit button on own comments and a reaction picker on
- * every comment.
+ * The shape mirrors the post's `viewer` pattern (minus `bookmarked` —
+ * comments aren't bookmarkable, the parent post is the right scope)
+ * so the client can render an edit button on own comments and a
+ * reaction picker on every comment.
  *
  * @module community-schema/comment
  */
@@ -58,14 +59,17 @@ export declare const communityCommentWireSchema: z.ZodObject<{
         identityVerified: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     text: z.ZodString;
-    upvoteCount: z.ZodNumber;
+    score: z.ZodNumber;
     replyCount: z.ZodNumber;
     reactionCounts: z.ZodRecord<z.ZodString, z.ZodNumber>;
     createdAt: z.ZodString;
     editedAt: z.ZodNullable<z.ZodString>;
     deletedAt: z.ZodNullable<z.ZodString>;
     viewer: z.ZodOptional<z.ZodObject<{
-        upvoted: z.ZodBoolean;
+        vote: z.ZodNullable<z.ZodEnum<{
+            up: "up";
+            down: "down";
+        }>>;
         reaction: z.ZodNullable<z.ZodString>;
         isAuthor: z.ZodBoolean;
     }, z.core.$strip>>;

package/dist/comment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../src/comment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkCrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E,eAAO,MAAM,uBAAuB;;;iBAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../src/comment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmCrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E,eAAO,MAAM,uBAAuB;;;iBAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/comment.js

@@ -2,18 +2,20 @@
  * Comment wire shapes (with one-level reply nesting).
  *
  * Comments attach to any feed item via `(contentKind, contentId)` — the
- * same polymorphic key used by reactions and upvotes. One level of
+ * same polymorphic key used by reactions and votes. One level of
  * nesting only: a reply to a comment is allowed; a reply to a reply
  * is rejected at the server.
  *
- * The shape mirrors the post's `viewer` pattern so the client can
- * render an edit button on own comments and a reaction picker on
- * every comment.
+ * The shape mirrors the post's `viewer` pattern (minus `bookmarked` —
+ * comments aren't bookmarkable, the parent post is the right scope)
+ * so the client can render an edit button on own comments and a
+ * reaction picker on every comment.
  *
  * @module community-schema/comment
  */
 import { z } from 'zod';
 import { COMMENT_MAX_BODY_CHARS } from './constants.js';
+import { voteValueSchema } from './engagement.js';
 import { contentKindSchema } from './enums.js';
 import { postAuthorSnapshotSchema } from './post.js';
 // ─── Wire shape ─────────────────────────────────────────────────────────────
@@ -30,7 +32,8 @@ export const communityCommentWireSchema = z.object({
     // Body
     text: z.string().max(COMMENT_MAX_BODY_CHARS),
     // Denormalised engagement
-    upvoteCount: z.number().int().nonnegative(),
+    /** Net score = upvotes - downvotes. Signed. */
+    score: z.number().int(),
     /** Number of replies. Only meaningful on top-level comments; always
      *  0 on replies (the server enforces no-nesting). */
     replyCount: z.number().int().nonnegative(),
@@ -42,7 +45,7 @@ export const communityCommentWireSchema = z.object({
     // Per-viewer state
     viewer: z
         .object({
-        upvoted: z.boolean(),
+        vote: voteValueSchema.nullable(),
         reaction: z.string().nullable(),
         isAuthor: z.boolean(),
     })

package/dist/comment.js.map

@@ -1 +1 @@
-{"version":3,"file":"comment.js","sourceRoot":"","sources":["../src/comment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD,+EAA+E;AAE/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,6CAA6C;IAC7C,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB;;mEAE+D;IAC/D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,MAAM,EAAE,wBAAwB;IAEhC,OAAO;IACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,sBAAsB,CAAC;IAE5C,0BAA0B;IAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC3C;yDACqD;IACrD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAEpE,YAAY;IACZ,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE3C,mBAAmB;IACnB,MAAM,EAAE,CAAC;SACN,MAAM,CAAC;QACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;QACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;KACtB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAGH,+EAA+E;AAE/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACnD;;mCAE+B;IAC/B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAGH,+EAA+E;AAE/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC;CACpD,CAAC,CAAC","sourcesContent":["/**\n * Comment wire shapes (with one-level reply nesting).\n *\n * Comments attach to any feed item via `(contentKind, contentId)` — the\n * same polymorphic key used by reactions and upvotes. One level of\n * nesting only: a reply to a comment is allowed; a reply to a reply\n * is rejected at the server.\n *\n * The shape mirrors the post's `viewer` pattern so the client can\n * render an edit button on own comments and a reaction picker on\n * every comment.\n *\n * @module community-schema/comment\n */\n\nimport { z } from 'zod';\nimport { COMMENT_MAX_BODY_CHARS } from './constants.js';\nimport { contentKindSchema } from './enums.js';\nimport { postAuthorSnapshotSchema } from './post.js';\n\n// ─── Wire shape ─────────────────────────────────────────────────────────────\n\nexport const communityCommentWireSchema = z.object({\n  _id: z.string(),\n  /** The feed item this comment belongs to. */\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** The parent comment id, or null if this is a top-level comment.\n   *  A non-null value MAY only point at a top-level comment — the\n   *  server enforces this so the tree never grows to depth 3. */\n  parentCommentId: z.string().nullable(),\n  author: postAuthorSnapshotSchema,\n\n  // Body\n  text: z.string().max(COMMENT_MAX_BODY_CHARS),\n\n  // Denormalised engagement\n  upvoteCount: z.number().int().nonnegative(),\n  /** Number of replies. Only meaningful on top-level comments; always\n   *  0 on replies (the server enforces no-nesting). */\n  replyCount: z.number().int().nonnegative(),\n  reactionCounts: z.record(z.string(), z.number().int().nonnegative()),\n\n  // Lifecycle\n  createdAt: z.string().datetime(),\n  editedAt: z.string().datetime().nullable(),\n  deletedAt: z.string().datetime().nullable(),\n\n  // Per-viewer state\n  viewer: z\n    .object({\n      upvoted: z.boolean(),\n      reaction: z.string().nullable(),\n      isAuthor: z.boolean(),\n    })\n    .optional(),\n});\nexport type CommunityCommentWire = z.infer<typeof communityCommentWireSchema>;\n\n// ─── Create body ────────────────────────────────────────────────────────────\n\nexport const createCommentBodySchema = z.object({\n  text: z.string().min(1).max(COMMENT_MAX_BODY_CHARS),\n  /** Null = top-level comment on the content; a string id = reply to\n   *  a specific top-level comment. Server rejects ids pointing at a\n   *  reply (depth-3 attempt). */\n  parentCommentId: z.string().nullable(),\n});\nexport type CreateCommentBody = z.infer<typeof createCommentBodySchema>;\n\n// ─── Update body ────────────────────────────────────────────────────────────\n\nexport const updateCommentBodySchema = z.object({\n  text: z.string().min(1).max(COMMENT_MAX_BODY_CHARS),\n});\nexport type UpdateCommentBody = z.infer<typeof updateCommentBodySchema>;\n"]}
+{"version":3,"file":"comment.js","sourceRoot":"","sources":["../src/comment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD,+EAA+E;AAE/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,6CAA6C;IAC7C,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB;;mEAE+D;IAC/D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,MAAM,EAAE,wBAAwB;IAEhC,OAAO;IACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,sBAAsB,CAAC;IAE5C,0BAA0B;IAC1B,+CAA+C;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACvB;yDACqD;IACrD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAEpE,YAAY;IACZ,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE3C,mBAAmB;IACnB,MAAM,EAAE,CAAC;SACN,MAAM,CAAC;QACN,IAAI,EAAE,eAAe,CAAC,QAAQ,EAAE;QAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;KACtB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAGH,+EAA+E;AAE/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACnD;;mCAE+B;IAC/B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAGH,+EAA+E;AAE/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC;CACpD,CAAC,CAAC","sourcesContent":["/**\n * Comment wire shapes (with one-level reply nesting).\n *\n * Comments attach to any feed item via `(contentKind, contentId)` — the\n * same polymorphic key used by reactions and votes. One level of\n * nesting only: a reply to a comment is allowed; a reply to a reply\n * is rejected at the server.\n *\n * The shape mirrors the post's `viewer` pattern (minus `bookmarked` —\n * comments aren't bookmarkable, the parent post is the right scope)\n * so the client can render an edit button on own comments and a\n * reaction picker on every comment.\n *\n * @module community-schema/comment\n */\n\nimport { z } from 'zod';\nimport { COMMENT_MAX_BODY_CHARS } from './constants.js';\nimport { voteValueSchema } from './engagement.js';\nimport { contentKindSchema } from './enums.js';\nimport { postAuthorSnapshotSchema } from './post.js';\n\n// ─── Wire shape ─────────────────────────────────────────────────────────────\n\nexport const communityCommentWireSchema = z.object({\n  _id: z.string(),\n  /** The feed item this comment belongs to. */\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** The parent comment id, or null if this is a top-level comment.\n   *  A non-null value MAY only point at a top-level comment — the\n   *  server enforces this so the tree never grows to depth 3. */\n  parentCommentId: z.string().nullable(),\n  author: postAuthorSnapshotSchema,\n\n  // Body\n  text: z.string().max(COMMENT_MAX_BODY_CHARS),\n\n  // Denormalised engagement\n  /** Net score = upvotes - downvotes. Signed. */\n  score: z.number().int(),\n  /** Number of replies. Only meaningful on top-level comments; always\n   *  0 on replies (the server enforces no-nesting). */\n  replyCount: z.number().int().nonnegative(),\n  reactionCounts: z.record(z.string(), z.number().int().nonnegative()),\n\n  // Lifecycle\n  createdAt: z.string().datetime(),\n  editedAt: z.string().datetime().nullable(),\n  deletedAt: z.string().datetime().nullable(),\n\n  // Per-viewer state\n  viewer: z\n    .object({\n      vote: voteValueSchema.nullable(),\n      reaction: z.string().nullable(),\n      isAuthor: z.boolean(),\n    })\n    .optional(),\n});\nexport type CommunityCommentWire = z.infer<typeof communityCommentWireSchema>;\n\n// ─── Create body ────────────────────────────────────────────────────────────\n\nexport const createCommentBodySchema = z.object({\n  text: z.string().min(1).max(COMMENT_MAX_BODY_CHARS),\n  /** Null = top-level comment on the content; a string id = reply to\n   *  a specific top-level comment. Server rejects ids pointing at a\n   *  reply (depth-3 attempt). */\n  parentCommentId: z.string().nullable(),\n});\nexport type CreateCommentBody = z.infer<typeof createCommentBodySchema>;\n\n// ─── Update body ────────────────────────────────────────────────────────────\n\nexport const updateCommentBodySchema = z.object({\n  text: z.string().min(1).max(COMMENT_MAX_BODY_CHARS),\n});\nexport type UpdateCommentBody = z.infer<typeof updateCommentBodySchema>;\n"]}

package/dist/engagement.d.ts

@@ -1,23 +1,63 @@
 /**
- * Engagement wire shapes — upvotes and reactions.
+ * Engagement wire shapes — vote, reaction, and bookmark.
  *
- * Both are keyed by `(contentKind, contentId)` so the same engagement
- * bar applies to every kind of feed item (post, lost-and-found,
- * voice-box) and to comments.
+ * Three independent axes per the product decision:
  *
- * Per the product decision, upvote and reaction are TWO INDEPENDENT
- * axes — a viewer can upvote AND react. Upvote drives feed sort;
- * reaction is the expressive layer.
+ *   - **Vote** drives ranking. A viewer can be in one of three vote
+ *     states: `'up'` (+1 contribution to score), `'down'` (-1), or
+ *     `null` (no vote). The card surfaces these as paired up/down
+ *     arrows on either side of a single signed `score` — the score
+ *     can go negative when downvotes exceed upvotes.
+ *
+ *   - **Reaction** is the expressive layer. At most one active
+ *     reaction per (viewer, target); reactions don't influence the
+ *     score.
+ *
+ *   - **Bookmark** is private to the viewer. Adds the target to the
+ *     viewer's saved-items list; doesn't affect counts or ranking
+ *     visible to others.
+ *
+ * Every axis is keyed by `(contentKind, contentId)` so the same
+ * EngagementBar applies to every kind of feed item AND to comments.
  *
  * @module community-schema/engagement
  */
 import { z } from 'zod';
 /**
- * What the client sends to `POST /api/v1/community/:contentKind/:id/upvote`.
- * The endpoint is a toggle — calling it twice in a row removes the
- * upvote. Idempotent: the server returns the post-toggle state.
+ * The vote state of a viewer relative to a target.
+ *
+ *   - `'up'`   the viewer upvoted (+1 to score)
+ *   - `'down'` the viewer downvoted (-1 to score)
+ *   - `null`   no vote cast
+ */
+export declare const VOTE_VALUES: readonly ["up", "down"];
+export declare const voteValueSchema: z.ZodEnum<{
+    up: "up";
+    down: "down";
+}>;
+export type VoteValue = z.infer<typeof voteValueSchema>;
+/**
+ * Body for `POST /api/v1/community/:contentKind/:id/vote`.
+ *
+ * Setting `vote: 'up' | 'down'` records that as the viewer's vote
+ * (replacing any prior vote in the opposite direction). Setting
+ * `vote: null` clears the viewer's vote entirely. The endpoint is
+ * idempotent — sending the same vote twice is a no-op; the response
+ * always reflects the final state.
+ */
+export declare const setVoteBodySchema: z.ZodObject<{
+    vote: z.ZodNullable<z.ZodEnum<{
+        up: "up";
+        down: "down";
+    }>>;
+}, z.core.$strip>;
+export type SetVoteBody = z.infer<typeof setVoteBodySchema>;
+/**
+ * Response from the vote endpoint. Returns the viewer's new vote
+ * AND the target's post-write score so the client can render
+ * straight off the response without a follow-up read.
  */
-export declare const toggleUpvoteResponseSchema: z.ZodObject<{
+export declare const setVoteResponseSchema: z.ZodObject<{
     contentKind: z.ZodEnum<{
         post: "post";
         lost_found: "lost_found";
@@ -26,16 +66,19 @@ export declare const toggleUpvoteResponseSchema: z.ZodObject<{
         poll: "poll";
     }>;
     contentId: z.ZodString;
-    upvoted: z.ZodBoolean;
-    upvoteCount: z.ZodNumber;
+    vote: z.ZodNullable<z.ZodEnum<{
+        up: "up";
+        down: "down";
+    }>>;
+    score: z.ZodNumber;
 }, z.core.$strip>;
-export type ToggleUpvoteResponse = z.infer<typeof toggleUpvoteResponseSchema>;
+export type SetVoteResponse = z.infer<typeof setVoteResponseSchema>;
 /**
- * What the client sends to `POST /api/v1/community/:contentKind/:id/reactions`.
+ * Body for `POST /api/v1/community/:contentKind/:id/reactions`.
  *
- * Setting `reaction` to a value replaces the user's current reaction
- * (a user may have at most ONE active reaction per target).
- * Setting `reaction` to null clears it.
+ * Setting `reaction` to a value replaces the viewer's current
+ * reaction (at most ONE active reaction per target). Setting
+ * `reaction` to null clears it.
  */
 export declare const setReactionBodySchema: z.ZodObject<{
     reaction: z.ZodNullable<z.ZodEnum<{
@@ -70,4 +113,24 @@ export declare const setReactionResponseSchema: z.ZodObject<{
     reactionCounts: z.ZodRecord<z.ZodString, z.ZodNumber>;
 }, z.core.$strip>;
 export type SetReactionResponse = z.infer<typeof setReactionResponseSchema>;
+/**
+ * Response from `POST /api/v1/community/:contentKind/:id/bookmark`.
+ *
+ * The endpoint is a toggle — it flips the viewer's bookmark state on
+ * the target. Returns the new state so the card can render directly
+ * off the response. Bookmarks are PRIVATE to the viewer; they don't
+ * affect any aggregate count surfaced to other viewers.
+ */
+export declare const toggleBookmarkResponseSchema: z.ZodObject<{
+    contentKind: z.ZodEnum<{
+        post: "post";
+        lost_found: "lost_found";
+        voice_box: "voice_box";
+        donate_item: "donate_item";
+        poll: "poll";
+    }>;
+    contentId: z.ZodString;
+    bookmarked: z.ZodBoolean;
+}, z.core.$strip>;
+export type ToggleBookmarkResponse = z.infer<typeof toggleBookmarkResponseSchema>;
 //# sourceMappingURL=engagement.d.ts.map

package/dist/engagement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../src/engagement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;iBAQrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;iBAEhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;iBAOpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../src/engagement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,yBAA0B,CAAC;AACnD,eAAO,MAAM,eAAe;;;EAAsB,CAAC;AACnD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;iBAE5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAUhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;iBAEhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;iBAOpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;iBAKvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/engagement.js

@@ -1,40 +1,74 @@
 /**
- * Engagement wire shapes — upvotes and reactions.
+ * Engagement wire shapes — vote, reaction, and bookmark.
  *
- * Both are keyed by `(contentKind, contentId)` so the same engagement
- * bar applies to every kind of feed item (post, lost-and-found,
- * voice-box) and to comments.
+ * Three independent axes per the product decision:
  *
- * Per the product decision, upvote and reaction are TWO INDEPENDENT
- * axes — a viewer can upvote AND react. Upvote drives feed sort;
- * reaction is the expressive layer.
+ *   - **Vote** drives ranking. A viewer can be in one of three vote
+ *     states: `'up'` (+1 contribution to score), `'down'` (-1), or
+ *     `null` (no vote). The card surfaces these as paired up/down
+ *     arrows on either side of a single signed `score` — the score
+ *     can go negative when downvotes exceed upvotes.
+ *
+ *   - **Reaction** is the expressive layer. At most one active
+ *     reaction per (viewer, target); reactions don't influence the
+ *     score.
+ *
+ *   - **Bookmark** is private to the viewer. Adds the target to the
+ *     viewer's saved-items list; doesn't affect counts or ranking
+ *     visible to others.
+ *
+ * Every axis is keyed by `(contentKind, contentId)` so the same
+ * EngagementBar applies to every kind of feed item AND to comments.
  *
  * @module community-schema/engagement
  */
 import { z } from 'zod';
 import { contentKindSchema, reactionTypeSchema } from './enums.js';
-// ─── Upvote ─────────────────────────────────────────────────────────────────
+// ─── Vote ───────────────────────────────────────────────────────────────────
+/**
+ * The vote state of a viewer relative to a target.
+ *
+ *   - `'up'`   the viewer upvoted (+1 to score)
+ *   - `'down'` the viewer downvoted (-1 to score)
+ *   - `null`   no vote cast
+ */
+export const VOTE_VALUES = ['up', 'down'];
+export const voteValueSchema = z.enum(VOTE_VALUES);
+/**
+ * Body for `POST /api/v1/community/:contentKind/:id/vote`.
+ *
+ * Setting `vote: 'up' | 'down'` records that as the viewer's vote
+ * (replacing any prior vote in the opposite direction). Setting
+ * `vote: null` clears the viewer's vote entirely. The endpoint is
+ * idempotent — sending the same vote twice is a no-op; the response
+ * always reflects the final state.
+ */
+export const setVoteBodySchema = z.object({
+    vote: voteValueSchema.nullable(),
+});
 /**
- * What the client sends to `POST /api/v1/community/:contentKind/:id/upvote`.
- * The endpoint is a toggle — calling it twice in a row removes the
- * upvote. Idempotent: the server returns the post-toggle state.
+ * Response from the vote endpoint. Returns the viewer's new vote
+ * AND the target's post-write score so the client can render
+ * straight off the response without a follow-up read.
  */
-export const toggleUpvoteResponseSchema = z.object({
+export const setVoteResponseSchema = z.object({
     contentKind: contentKindSchema,
     contentId: z.string(),
-    /** New upvote state for the calling user. */
-    upvoted: z.boolean(),
-    /** Post-toggle aggregate count, returned so the client can render
-     *  without a follow-up read. */
-    upvoteCount: z.number().int().nonnegative(),
+    /** The viewer's vote AFTER this call. */
+    vote: voteValueSchema.nullable(),
+    /**
+     * Net score = upvotes - downvotes. CAN BE NEGATIVE when downvotes
+     * exceed upvotes. The card's middle number reads this directly.
+     */
+    score: z.number().int(),
 });
 // ─── Reaction ───────────────────────────────────────────────────────────────
 /**
- * What the client sends to `POST /api/v1/community/:contentKind/:id/reactions`.
+ * Body for `POST /api/v1/community/:contentKind/:id/reactions`.
  *
- * Setting `reaction` to a value replaces the user's current reaction
- * (a user may have at most ONE active reaction per target).
- * Setting `reaction` to null clears it.
+ * Setting `reaction` to a value replaces the viewer's current
+ * reaction (at most ONE active reaction per target). Setting
+ * `reaction` to null clears it.
  */
 export const setReactionBodySchema = z.object({
     reaction: reactionTypeSchema.nullable(),
@@ -42,9 +76,24 @@ export const setReactionBodySchema = z.object({
 export const setReactionResponseSchema = z.object({
     contentKind: contentKindSchema,
     contentId: z.string(),
-    /** The viewer's new reaction, or null when cleared. */
+    /** Viewer's new reaction, or null when cleared. */
     reaction: reactionTypeSchema.nullable(),
     /** Post-set aggregate counts, keyed by reaction type. */
     reactionCounts: z.record(z.string(), z.number().int().nonnegative()),
 });
+// ─── Bookmark ───────────────────────────────────────────────────────────────
+/**
+ * Response from `POST /api/v1/community/:contentKind/:id/bookmark`.
+ *
+ * The endpoint is a toggle — it flips the viewer's bookmark state on
+ * the target. Returns the new state so the card can render directly
+ * off the response. Bookmarks are PRIVATE to the viewer; they don't
+ * affect any aggregate count surfaced to other viewers.
+ */
+export const toggleBookmarkResponseSchema = z.object({
+    contentKind: contentKindSchema,
+    contentId: z.string(),
+    /** Viewer's bookmark state AFTER this call. */
+    bookmarked: z.boolean(),
+});
 //# sourceMappingURL=engagement.js.map

package/dist/engagement.js.map

@@ -1 +1 @@
-{"version":3,"file":"engagement.js","sourceRoot":"","sources":["../src/engagement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEnE,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB;oCACgC;IAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CAC5C,CAAC,CAAC;AAGH,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,uDAAuD;IACvD,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IACvC,yDAAyD;IACzD,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;CACrE,CAAC,CAAC","sourcesContent":["/**\n * Engagement wire shapes — upvotes and reactions.\n *\n * Both are keyed by `(contentKind, contentId)` so the same engagement\n * bar applies to every kind of feed item (post, lost-and-found,\n * voice-box) and to comments.\n *\n * Per the product decision, upvote and reaction are TWO INDEPENDENT\n * axes — a viewer can upvote AND react. Upvote drives feed sort;\n * reaction is the expressive layer.\n *\n * @module community-schema/engagement\n */\n\nimport { z } from 'zod';\nimport { contentKindSchema, reactionTypeSchema } from './enums.js';\n\n// ─── Upvote ─────────────────────────────────────────────────────────────────\n\n/**\n * What the client sends to `POST /api/v1/community/:contentKind/:id/upvote`.\n * The endpoint is a toggle — calling it twice in a row removes the\n * upvote. Idempotent: the server returns the post-toggle state.\n */\nexport const toggleUpvoteResponseSchema = z.object({\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** New upvote state for the calling user. */\n  upvoted: z.boolean(),\n  /** Post-toggle aggregate count, returned so the client can render\n   *  without a follow-up read. */\n  upvoteCount: z.number().int().nonnegative(),\n});\nexport type ToggleUpvoteResponse = z.infer<typeof toggleUpvoteResponseSchema>;\n\n// ─── Reaction ───────────────────────────────────────────────────────────────\n\n/**\n * What the client sends to `POST /api/v1/community/:contentKind/:id/reactions`.\n *\n * Setting `reaction` to a value replaces the user's current reaction\n * (a user may have at most ONE active reaction per target).\n * Setting `reaction` to null clears it.\n */\nexport const setReactionBodySchema = z.object({\n  reaction: reactionTypeSchema.nullable(),\n});\nexport type SetReactionBody = z.infer<typeof setReactionBodySchema>;\n\nexport const setReactionResponseSchema = z.object({\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** The viewer's new reaction, or null when cleared. */\n  reaction: reactionTypeSchema.nullable(),\n  /** Post-set aggregate counts, keyed by reaction type. */\n  reactionCounts: z.record(z.string(), z.number().int().nonnegative()),\n});\nexport type SetReactionResponse = z.infer<typeof setReactionResponseSchema>;\n"]}
+{"version":3,"file":"engagement.js","sourceRoot":"","sources":["../src/engagement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEnE,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAU,CAAC;AACnD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAGnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,eAAe,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,yCAAyC;IACzC,IAAI,EAAE,eAAe,CAAC,QAAQ,EAAE;IAChC;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAGH,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,mDAAmD;IACnD,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IACvC,yDAAyD;IACzD,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;CACrE,CAAC,CAAC;AAGH,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,+CAA+C;IAC/C,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACxB,CAAC,CAAC","sourcesContent":["/**\n * Engagement wire shapes — vote, reaction, and bookmark.\n *\n * Three independent axes per the product decision:\n *\n *   - **Vote** drives ranking. A viewer can be in one of three vote\n *     states: `'up'` (+1 contribution to score), `'down'` (-1), or\n *     `null` (no vote). The card surfaces these as paired up/down\n *     arrows on either side of a single signed `score` — the score\n *     can go negative when downvotes exceed upvotes.\n *\n *   - **Reaction** is the expressive layer. At most one active\n *     reaction per (viewer, target); reactions don't influence the\n *     score.\n *\n *   - **Bookmark** is private to the viewer. Adds the target to the\n *     viewer's saved-items list; doesn't affect counts or ranking\n *     visible to others.\n *\n * Every axis is keyed by `(contentKind, contentId)` so the same\n * EngagementBar applies to every kind of feed item AND to comments.\n *\n * @module community-schema/engagement\n */\n\nimport { z } from 'zod';\nimport { contentKindSchema, reactionTypeSchema } from './enums.js';\n\n// ─── Vote ───────────────────────────────────────────────────────────────────\n\n/**\n * The vote state of a viewer relative to a target.\n *\n *   - `'up'`   the viewer upvoted (+1 to score)\n *   - `'down'` the viewer downvoted (-1 to score)\n *   - `null`   no vote cast\n */\nexport const VOTE_VALUES = ['up', 'down'] as const;\nexport const voteValueSchema = z.enum(VOTE_VALUES);\nexport type VoteValue = z.infer<typeof voteValueSchema>;\n\n/**\n * Body for `POST /api/v1/community/:contentKind/:id/vote`.\n *\n * Setting `vote: 'up' | 'down'` records that as the viewer's vote\n * (replacing any prior vote in the opposite direction). Setting\n * `vote: null` clears the viewer's vote entirely. The endpoint is\n * idempotent — sending the same vote twice is a no-op; the response\n * always reflects the final state.\n */\nexport const setVoteBodySchema = z.object({\n  vote: voteValueSchema.nullable(),\n});\nexport type SetVoteBody = z.infer<typeof setVoteBodySchema>;\n\n/**\n * Response from the vote endpoint. Returns the viewer's new vote\n * AND the target's post-write score so the client can render\n * straight off the response without a follow-up read.\n */\nexport const setVoteResponseSchema = z.object({\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** The viewer's vote AFTER this call. */\n  vote: voteValueSchema.nullable(),\n  /**\n   * Net score = upvotes - downvotes. CAN BE NEGATIVE when downvotes\n   * exceed upvotes. The card's middle number reads this directly.\n   */\n  score: z.number().int(),\n});\nexport type SetVoteResponse = z.infer<typeof setVoteResponseSchema>;\n\n// ─── Reaction ───────────────────────────────────────────────────────────────\n\n/**\n * Body for `POST /api/v1/community/:contentKind/:id/reactions`.\n *\n * Setting `reaction` to a value replaces the viewer's current\n * reaction (at most ONE active reaction per target). Setting\n * `reaction` to null clears it.\n */\nexport const setReactionBodySchema = z.object({\n  reaction: reactionTypeSchema.nullable(),\n});\nexport type SetReactionBody = z.infer<typeof setReactionBodySchema>;\n\nexport const setReactionResponseSchema = z.object({\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** Viewer's new reaction, or null when cleared. */\n  reaction: reactionTypeSchema.nullable(),\n  /** Post-set aggregate counts, keyed by reaction type. */\n  reactionCounts: z.record(z.string(), z.number().int().nonnegative()),\n});\nexport type SetReactionResponse = z.infer<typeof setReactionResponseSchema>;\n\n// ─── Bookmark ───────────────────────────────────────────────────────────────\n\n/**\n * Response from `POST /api/v1/community/:contentKind/:id/bookmark`.\n *\n * The endpoint is a toggle — it flips the viewer's bookmark state on\n * the target. Returns the new state so the card can render directly\n * off the response. Bookmarks are PRIVATE to the viewer; they don't\n * affect any aggregate count surfaced to other viewers.\n */\nexport const toggleBookmarkResponseSchema = z.object({\n  contentKind: contentKindSchema,\n  contentId: z.string(),\n  /** Viewer's bookmark state AFTER this call. */\n  bookmarked: z.boolean(),\n});\nexport type ToggleBookmarkResponse = z.infer<typeof toggleBookmarkResponseSchema>;\n"]}