@rocapine/community-core 0.1.0

package/lib/inbox-hooks.js

@@ -0,0 +1,57 @@
+"use strict";
+// React Query hooks over the inbox service. Ported from a host app's
+// notification-center hooks, gated on `cfg.modules.inbox` in addition
+// to the usual `cfg.supabase !== null` degraded-mode guard.
+//
+// No React Native / analytics-SDK / store imports here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useNotificationInbox = useNotificationInbox;
+exports.useUnreadNotificationCount = useUnreadNotificationCount;
+exports.useMarkInboxSeen = useMarkInboxSeen;
+const react_query_1 = require("@tanstack/react-query");
+const provider_1 = require("./provider");
+const inbox_service_1 = require("./inbox-service");
+const INBOX_KEY = ["community", "inbox"];
+/**
+ * The inbox, shared by the host's badge and the center screen — one query
+ * key backs both, so opening the screen never triggers a second fetch on top
+ * of the badge's. Refreshes on foreground like every query (host's own
+ * focusManager wiring, same as the rest of this package).
+ */
+function useNotificationInbox() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useQuery)({
+        queryKey: INBOX_KEY,
+        queryFn: () => (0, inbox_service_1.fetchInbox)(cfg),
+        enabled: cfg.supabase !== null && cfg.modules.inbox,
+        staleTime: 60000,
+        retry: 1,
+    });
+}
+/**
+ * Unread badge count. Fail-soft rule (mold): the inbox is an enhancement, so a
+ * fetch error, a disabled module, or a degraded (no-backend) host must never
+ * surface upstream — this returns 0 in every one of those cases, never
+ * `undefined` and never a thrown error.
+ */
+function useUnreadNotificationCount() {
+    const { data } = useNotificationInbox();
+    return data ? (0, inbox_service_1.unreadCount)(data.items, data.seenAt) : 0;
+}
+/**
+ * Moves the seen marker past everything currently in the inbox so the badge
+ * clears immediately (optimistic), then persists the clock-skew-safe marker
+ * server-side (see `markInboxSeen`) — the next fetch reconciles the cache
+ * with that authoritative value.
+ */
+function useMarkInboxSeen() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => (0, inbox_service_1.markInboxSeen)(cfg),
+        onMutate: () => {
+            const optimisticSeenAt = new Date().toISOString();
+            queryClient.setQueryData(INBOX_KEY, (state) => state ? { ...state, seenAt: optimisticSeenAt } : state);
+        },
+    });
+}

package/lib/inbox-service.d.ts

@@ -0,0 +1,26 @@
+import type { ResolvedCommunityConfig } from "./config";
+export type InboxItem = {
+    id: string;
+    kind: "like" | "comment" | "reaction" | "official_post" | (string & {});
+    createdAt: string;
+    actorName: string | null;
+    postId: string | null;
+    payload: Record<string, unknown>;
+};
+export interface InboxState {
+    items: InboxItem[];
+    /** Everything at or before this instant is read; null = never opened. */
+    seenAt: string | null;
+}
+/** The inbox's whole state in one fetch: items (newest first) + seen marker. */
+export declare function fetchInbox(cfg: ResolvedCommunityConfig): Promise<InboxState>;
+/**
+ * Marks everything currently in the inbox as read. The brief's signature
+ * takes only `cfg` (unlike the mold's `markNotificationsSeen(latestItemCreatedAt)`),
+ * so the clock-skew-safe anchor is derived internally: a cheap `list_notifications`
+ * call for just the newest row, rather than dropping the guard or duplicating
+ * the full `fetchInbox` (items + seen marker) round trip.
+ */
+export declare function markInboxSeen(cfg: ResolvedCommunityConfig): Promise<void>;
+/** Unread = items strictly newer than the seen marker (all of them if never opened). Pure. */
+export declare function unreadCount(items: InboxItem[], seenAt: string | null): number;

package/lib/inbox-service.js

@@ -0,0 +1,94 @@
+"use strict";
+// Notification inbox service — every function is a thin wrapper around the
+// injected Supabase client, gated on `cfg.modules.inbox` (the mutation/read
+// pair below throw when the module is off, same pattern as
+// setReaction/votePoll in service.ts; hooks additionally gate via `enabled`
+// so a disabled module never even reaches these).
+//
+// Ported from a host app's notification-center service. Transformations:
+// kind `prayer` -> `reaction` (the mold's generic reaction module, same
+// prayer->reaction rename as the rest of this package); the `kind` union is
+// widened with `(string & {})` so a custom service-role kind (that host's
+// support-reply kind) passes through untouched instead of being special-cased
+// here — the host UI decides what to do with a kind it doesn't recognize.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchInbox = fetchInbox;
+exports.markInboxSeen = markInboxSeen;
+exports.unreadCount = unreadCount;
+const identity_1 = require("./identity");
+const INBOX_PAGE_SIZE = 50;
+async function requireUid(cfg) {
+    const uid = await (0, identity_1.ensureIdentity)(cfg);
+    if (!uid)
+        throw new Error("You appear to be offline. Please try again.");
+    return uid;
+}
+function mapKind(raw) {
+    return raw === "prayer" ? "reaction" : raw;
+}
+function mapNotificationRow(row) {
+    return {
+        id: row.id,
+        kind: mapKind(row.kind),
+        createdAt: row.created_at,
+        actorName: row.actor_username,
+        postId: row.post_id,
+        payload: { actorId: row.actor_id, postExcerpt: row.post_excerpt },
+    };
+}
+/**
+ * Move the seen marker past everything just read. Item timestamps are server
+ * clocks and the device clock can lag them by minutes, so "now" alone would
+ * leave the newest items permanently unread — take the max of both (mold
+ * `seenMarkerFor`).
+ */
+function seenMarkerFor(latestItemCreatedAt) {
+    const latest = latestItemCreatedAt ? Date.parse(latestItemCreatedAt) : 0;
+    return new Date(Math.max(Date.now(), Number.isNaN(latest) ? 0 : latest)).toISOString();
+}
+/** The inbox's whole state in one fetch: items (newest first) + seen marker. */
+async function fetchInbox(cfg) {
+    if (!cfg.modules.inbox)
+        throw new Error("inbox module is not enabled");
+    const client = cfg.requireClient();
+    const uid = await requireUid(cfg);
+    const [listRes, seenRes] = await Promise.all([
+        client.rpc("list_notifications", { p_limit: INBOX_PAGE_SIZE }),
+        client.from("notification_seen").select("seen_at").eq("user_id", uid).maybeSingle(),
+    ]);
+    if (listRes.error)
+        throw listRes.error;
+    if (seenRes.error)
+        throw seenRes.error;
+    const items = (listRes.data ?? []).map(mapNotificationRow);
+    return { items, seenAt: seenRes.data?.seen_at ?? null };
+}
+/**
+ * Marks everything currently in the inbox as read. The brief's signature
+ * takes only `cfg` (unlike the mold's `markNotificationsSeen(latestItemCreatedAt)`),
+ * so the clock-skew-safe anchor is derived internally: a cheap `list_notifications`
+ * call for just the newest row, rather than dropping the guard or duplicating
+ * the full `fetchInbox` (items + seen marker) round trip.
+ */
+async function markInboxSeen(cfg) {
+    if (!cfg.modules.inbox)
+        throw new Error("inbox module is not enabled");
+    const client = cfg.requireClient();
+    const uid = await requireUid(cfg);
+    const { data, error: listError } = await client.rpc("list_notifications", { p_limit: 1 });
+    if (listError)
+        throw listError;
+    const latestCreatedAt = (data ?? [])[0]?.created_at ?? null;
+    const { error } = await client
+        .from("notification_seen")
+        .upsert({ user_id: uid, seen_at: seenMarkerFor(latestCreatedAt) });
+    if (error)
+        throw error;
+}
+/** Unread = items strictly newer than the seen marker (all of them if never opened). Pure. */
+function unreadCount(items, seenAt) {
+    if (!seenAt)
+        return items.length;
+    const seen = Date.parse(seenAt);
+    return items.filter((item) => Date.parse(item.createdAt) > seen).length;
+}

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+export type { CommunityTopicDef, CommunityModules, CommunityHostAdapters, CommunityFeedConfig, CommunityConfig, ResolvedCommunityConfig, } from "./config";
+export { CommunityDisabledError, resolveConfig } from "./config";
+export { CommunityProvider, useCommunityConfig } from "./provider";
+export type { PostRow, PollOptionRow, CommentRow, ProfileRow, PollOption, FeedPoll, PollData, ReactionData, FeedPost, ThreadComment, CommunityProfile, } from "./models";
+export { FEED_PAGE_SIZE, POST_MAX_LENGTH, COMMENT_MAX_LENGTH, POLL_MIN_OPTIONS, POLL_MAX_OPTIONS, POLL_OPTION_MAX_LENGTH, EMPTY_POLL_DATA, EMPTY_REACTION_DATA, displayName, normalizeTopic, mapProfileRow, buildPoll, pollPercent, mapPostRow, applyPollVote, applyReaction, mapCommentRow, newPostsLabel, newestCreatedAt, } from "./models";
+export type { TimeAgoParts } from "./time";
+export { timeAgo, timeAgoParts } from "./time";
+export { COMMUNITY_EVENTS, emitEvent } from "./events";
+export type { CommunityEventName } from "./events";
+export { ensureIdentity, resetIdentity, syncProfileFromHost } from "./identity";
+export { buildFeedSelect, fetchFeedPage, countNewPosts, fetchProfile, fetchUserPosts, searchPosts, fetchThread, createPost, votePoll, createComment, moderateOne, setLike, setReaction, fetchReactionSummaries, reportContent, blockUser, deleteOwnPost, deleteOwnComment, updateProfile, uploadAvatar, } from "./service";
+export type { ModerationVerdict, CreatePostInput, ReportReason, ReportInput, UpdateProfileInput, UpdateProfileResult, } from "./service";
+export { useCommunityFeed, useSearchPosts, useNewPostsCount, useCommunityUnseenCount, useThread, useProfile, useUserPosts, useMyUid, useUpdateProfile, useCreatePost, useCreateComment, useToggleLike, useVotePoll, useReactToPost, useReport, useBlockUser, useDeleteContent, } from "./hooks";
+export { fetchInbox, markInboxSeen, unreadCount } from "./inbox-service";
+export type { InboxItem, InboxState } from "./inbox-service";
+export { useNotificationInbox, useUnreadNotificationCount, useMarkInboxSeen } from "./inbox-hooks";
+export { REQUIRED_SCHEMA_VERSION } from "./schema-check";

package/lib/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadAvatar = exports.updateProfile = exports.deleteOwnComment = exports.deleteOwnPost = exports.blockUser = exports.reportContent = exports.fetchReactionSummaries = exports.setReaction = exports.setLike = exports.moderateOne = exports.createComment = exports.votePoll = exports.createPost = exports.fetchThread = exports.searchPosts = exports.fetchUserPosts = exports.fetchProfile = exports.countNewPosts = exports.fetchFeedPage = exports.buildFeedSelect = exports.syncProfileFromHost = exports.resetIdentity = exports.ensureIdentity = exports.emitEvent = exports.COMMUNITY_EVENTS = exports.timeAgoParts = exports.timeAgo = exports.newestCreatedAt = exports.newPostsLabel = exports.mapCommentRow = exports.applyReaction = exports.applyPollVote = exports.mapPostRow = exports.pollPercent = exports.buildPoll = exports.mapProfileRow = exports.normalizeTopic = exports.displayName = exports.EMPTY_REACTION_DATA = exports.EMPTY_POLL_DATA = exports.POLL_OPTION_MAX_LENGTH = exports.POLL_MAX_OPTIONS = exports.POLL_MIN_OPTIONS = exports.COMMENT_MAX_LENGTH = exports.POST_MAX_LENGTH = exports.FEED_PAGE_SIZE = exports.useCommunityConfig = exports.CommunityProvider = exports.resolveConfig = exports.CommunityDisabledError = void 0;
+exports.REQUIRED_SCHEMA_VERSION = exports.useMarkInboxSeen = exports.useUnreadNotificationCount = exports.useNotificationInbox = exports.unreadCount = exports.markInboxSeen = exports.fetchInbox = exports.useDeleteContent = exports.useBlockUser = exports.useReport = exports.useReactToPost = exports.useVotePoll = exports.useToggleLike = exports.useCreateComment = exports.useCreatePost = exports.useUpdateProfile = exports.useMyUid = exports.useUserPosts = exports.useProfile = exports.useThread = exports.useCommunityUnseenCount = exports.useNewPostsCount = exports.useSearchPosts = exports.useCommunityFeed = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "CommunityDisabledError", { enumerable: true, get: function () { return config_1.CommunityDisabledError; } });
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "CommunityProvider", { enumerable: true, get: function () { return provider_1.CommunityProvider; } });
+Object.defineProperty(exports, "useCommunityConfig", { enumerable: true, get: function () { return provider_1.useCommunityConfig; } });
+var models_1 = require("./models");
+Object.defineProperty(exports, "FEED_PAGE_SIZE", { enumerable: true, get: function () { return models_1.FEED_PAGE_SIZE; } });
+Object.defineProperty(exports, "POST_MAX_LENGTH", { enumerable: true, get: function () { return models_1.POST_MAX_LENGTH; } });
+Object.defineProperty(exports, "COMMENT_MAX_LENGTH", { enumerable: true, get: function () { return models_1.COMMENT_MAX_LENGTH; } });
+Object.defineProperty(exports, "POLL_MIN_OPTIONS", { enumerable: true, get: function () { return models_1.POLL_MIN_OPTIONS; } });
+Object.defineProperty(exports, "POLL_MAX_OPTIONS", { enumerable: true, get: function () { return models_1.POLL_MAX_OPTIONS; } });
+Object.defineProperty(exports, "POLL_OPTION_MAX_LENGTH", { enumerable: true, get: function () { return models_1.POLL_OPTION_MAX_LENGTH; } });
+Object.defineProperty(exports, "EMPTY_POLL_DATA", { enumerable: true, get: function () { return models_1.EMPTY_POLL_DATA; } });
+Object.defineProperty(exports, "EMPTY_REACTION_DATA", { enumerable: true, get: function () { return models_1.EMPTY_REACTION_DATA; } });
+Object.defineProperty(exports, "displayName", { enumerable: true, get: function () { return models_1.displayName; } });
+Object.defineProperty(exports, "normalizeTopic", { enumerable: true, get: function () { return models_1.normalizeTopic; } });
+Object.defineProperty(exports, "mapProfileRow", { enumerable: true, get: function () { return models_1.mapProfileRow; } });
+Object.defineProperty(exports, "buildPoll", { enumerable: true, get: function () { return models_1.buildPoll; } });
+Object.defineProperty(exports, "pollPercent", { enumerable: true, get: function () { return models_1.pollPercent; } });
+Object.defineProperty(exports, "mapPostRow", { enumerable: true, get: function () { return models_1.mapPostRow; } });
+Object.defineProperty(exports, "applyPollVote", { enumerable: true, get: function () { return models_1.applyPollVote; } });
+Object.defineProperty(exports, "applyReaction", { enumerable: true, get: function () { return models_1.applyReaction; } });
+Object.defineProperty(exports, "mapCommentRow", { enumerable: true, get: function () { return models_1.mapCommentRow; } });
+Object.defineProperty(exports, "newPostsLabel", { enumerable: true, get: function () { return models_1.newPostsLabel; } });
+Object.defineProperty(exports, "newestCreatedAt", { enumerable: true, get: function () { return models_1.newestCreatedAt; } });
+var time_1 = require("./time");
+Object.defineProperty(exports, "timeAgo", { enumerable: true, get: function () { return time_1.timeAgo; } });
+Object.defineProperty(exports, "timeAgoParts", { enumerable: true, get: function () { return time_1.timeAgoParts; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "COMMUNITY_EVENTS", { enumerable: true, get: function () { return events_1.COMMUNITY_EVENTS; } });
+Object.defineProperty(exports, "emitEvent", { enumerable: true, get: function () { return events_1.emitEvent; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "ensureIdentity", { enumerable: true, get: function () { return identity_1.ensureIdentity; } });
+Object.defineProperty(exports, "resetIdentity", { enumerable: true, get: function () { return identity_1.resetIdentity; } });
+Object.defineProperty(exports, "syncProfileFromHost", { enumerable: true, get: function () { return identity_1.syncProfileFromHost; } });
+var service_1 = require("./service");
+Object.defineProperty(exports, "buildFeedSelect", { enumerable: true, get: function () { return service_1.buildFeedSelect; } });
+Object.defineProperty(exports, "fetchFeedPage", { enumerable: true, get: function () { return service_1.fetchFeedPage; } });
+Object.defineProperty(exports, "countNewPosts", { enumerable: true, get: function () { return service_1.countNewPosts; } });
+Object.defineProperty(exports, "fetchProfile", { enumerable: true, get: function () { return service_1.fetchProfile; } });
+Object.defineProperty(exports, "fetchUserPosts", { enumerable: true, get: function () { return service_1.fetchUserPosts; } });
+Object.defineProperty(exports, "searchPosts", { enumerable: true, get: function () { return service_1.searchPosts; } });
+Object.defineProperty(exports, "fetchThread", { enumerable: true, get: function () { return service_1.fetchThread; } });
+Object.defineProperty(exports, "createPost", { enumerable: true, get: function () { return service_1.createPost; } });
+Object.defineProperty(exports, "votePoll", { enumerable: true, get: function () { return service_1.votePoll; } });
+Object.defineProperty(exports, "createComment", { enumerable: true, get: function () { return service_1.createComment; } });
+Object.defineProperty(exports, "moderateOne", { enumerable: true, get: function () { return service_1.moderateOne; } });
+Object.defineProperty(exports, "setLike", { enumerable: true, get: function () { return service_1.setLike; } });
+Object.defineProperty(exports, "setReaction", { enumerable: true, get: function () { return service_1.setReaction; } });
+Object.defineProperty(exports, "fetchReactionSummaries", { enumerable: true, get: function () { return service_1.fetchReactionSummaries; } });
+Object.defineProperty(exports, "reportContent", { enumerable: true, get: function () { return service_1.reportContent; } });
+Object.defineProperty(exports, "blockUser", { enumerable: true, get: function () { return service_1.blockUser; } });
+Object.defineProperty(exports, "deleteOwnPost", { enumerable: true, get: function () { return service_1.deleteOwnPost; } });
+Object.defineProperty(exports, "deleteOwnComment", { enumerable: true, get: function () { return service_1.deleteOwnComment; } });
+Object.defineProperty(exports, "updateProfile", { enumerable: true, get: function () { return service_1.updateProfile; } });
+Object.defineProperty(exports, "uploadAvatar", { enumerable: true, get: function () { return service_1.uploadAvatar; } });
+var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "useCommunityFeed", { enumerable: true, get: function () { return hooks_1.useCommunityFeed; } });
+Object.defineProperty(exports, "useSearchPosts", { enumerable: true, get: function () { return hooks_1.useSearchPosts; } });
+Object.defineProperty(exports, "useNewPostsCount", { enumerable: true, get: function () { return hooks_1.useNewPostsCount; } });
+Object.defineProperty(exports, "useCommunityUnseenCount", { enumerable: true, get: function () { return hooks_1.useCommunityUnseenCount; } });
+Object.defineProperty(exports, "useThread", { enumerable: true, get: function () { return hooks_1.useThread; } });
+Object.defineProperty(exports, "useProfile", { enumerable: true, get: function () { return hooks_1.useProfile; } });
+Object.defineProperty(exports, "useUserPosts", { enumerable: true, get: function () { return hooks_1.useUserPosts; } });
+Object.defineProperty(exports, "useMyUid", { enumerable: true, get: function () { return hooks_1.useMyUid; } });
+Object.defineProperty(exports, "useUpdateProfile", { enumerable: true, get: function () { return hooks_1.useUpdateProfile; } });
+Object.defineProperty(exports, "useCreatePost", { enumerable: true, get: function () { return hooks_1.useCreatePost; } });
+Object.defineProperty(exports, "useCreateComment", { enumerable: true, get: function () { return hooks_1.useCreateComment; } });
+Object.defineProperty(exports, "useToggleLike", { enumerable: true, get: function () { return hooks_1.useToggleLike; } });
+Object.defineProperty(exports, "useVotePoll", { enumerable: true, get: function () { return hooks_1.useVotePoll; } });
+Object.defineProperty(exports, "useReactToPost", { enumerable: true, get: function () { return hooks_1.useReactToPost; } });
+Object.defineProperty(exports, "useReport", { enumerable: true, get: function () { return hooks_1.useReport; } });
+Object.defineProperty(exports, "useBlockUser", { enumerable: true, get: function () { return hooks_1.useBlockUser; } });
+Object.defineProperty(exports, "useDeleteContent", { enumerable: true, get: function () { return hooks_1.useDeleteContent; } });
+var inbox_service_1 = require("./inbox-service");
+Object.defineProperty(exports, "fetchInbox", { enumerable: true, get: function () { return inbox_service_1.fetchInbox; } });
+Object.defineProperty(exports, "markInboxSeen", { enumerable: true, get: function () { return inbox_service_1.markInboxSeen; } });
+Object.defineProperty(exports, "unreadCount", { enumerable: true, get: function () { return inbox_service_1.unreadCount; } });
+var inbox_hooks_1 = require("./inbox-hooks");
+Object.defineProperty(exports, "useNotificationInbox", { enumerable: true, get: function () { return inbox_hooks_1.useNotificationInbox; } });
+Object.defineProperty(exports, "useUnreadNotificationCount", { enumerable: true, get: function () { return inbox_hooks_1.useUnreadNotificationCount; } });
+Object.defineProperty(exports, "useMarkInboxSeen", { enumerable: true, get: function () { return inbox_hooks_1.useMarkInboxSeen; } });
+var schema_check_1 = require("./schema-check");
+Object.defineProperty(exports, "REQUIRED_SCHEMA_VERSION", { enumerable: true, get: function () { return schema_check_1.REQUIRED_SCHEMA_VERSION; } });

package/lib/models.d.ts

@@ -0,0 +1,187 @@
+import type { CommunityTopicDef } from "./config";
+export declare const FEED_PAGE_SIZE = 20;
+export declare const POST_MAX_LENGTH = 2000;
+export declare const COMMENT_MAX_LENGTH = 1000;
+export declare const POLL_MIN_OPTIONS = 2;
+export declare const POLL_MAX_OPTIONS = 4;
+export declare const POLL_OPTION_MAX_LENGTH = 60;
+/** Raw shape returned by the feed select (see the services layer). */
+export interface PostRow {
+    id: string;
+    author_id: string;
+    topic: string | null;
+    content: string;
+    status: "visible" | "hidden" | "deleted";
+    pinned_at: string | null;
+    created_at: string;
+    profiles: {
+        username: string | null;
+        is_official: boolean | null;
+        handle: string | null;
+        avatar_url: string | null;
+    } | null;
+    likes: {
+        count: number;
+    }[];
+    comments: {
+        count: number;
+    }[];
+    /** Empty for a post without a poll. */
+    poll_options: PollOptionRow[];
+}
+export interface PollOptionRow {
+    id: string;
+    idx: number;
+    label: string;
+}
+export interface CommentRow {
+    id: string;
+    post_id: string;
+    author_id: string;
+    content: string;
+    status: "visible" | "hidden" | "deleted";
+    created_at: string;
+    profiles: {
+        username: string | null;
+        is_official: boolean | null;
+        handle: string | null;
+        avatar_url: string | null;
+    } | null;
+}
+export interface PollOption {
+    id: string;
+    label: string;
+    votes: number;
+}
+export interface FeedPoll {
+    /** In creation order (idx). */
+    options: PollOption[];
+    /** Option id I voted for; null until I vote. */
+    myOptionId: string | null;
+    totalVotes: number;
+}
+/** Batched per-post poll state fetched alongside a feed page:
+ * counts is option_id -> votes, myVotes is post_id -> my option_id. */
+export interface PollData {
+    counts: ReadonlyMap<string, number>;
+    myVotes: ReadonlyMap<string, string>;
+}
+export declare const EMPTY_POLL_DATA: PollData;
+/** Batched per-post reaction state fetched alongside a feed page (generalized from
+ * a host app's prayer-style feature: prayerCount/hasPrayed -> reactionCount/hasReacted).
+ * `lastReactorName` mirrors the backend's security-definer summary RPC, which returns
+ * each post's most recent reactor's display name alongside the count. */
+export interface ReactionData {
+    counts: ReadonlyMap<string, number>;
+    mine: ReadonlySet<string>;
+    lastReactorName: ReadonlyMap<string, string | null>;
+}
+export declare const EMPTY_REACTION_DATA: ReactionData;
+export interface FeedPost {
+    id: string;
+    authorId: string;
+    authorName: string;
+    /** Official house account — renders a verified seal. */
+    authorOfficial: boolean;
+    /** Unique public handle, e.g. "marie-4821". Null on stale caches. */
+    authorHandle: string | null;
+    authorAvatarUrl: string | null;
+    /** App-defined free text; unknown values stay visible under their raw id (see normalizeTopic). */
+    topic: string | null;
+    text: string;
+    /** 'deleted' rows are excluded at the query level, so never present here. */
+    status: "visible" | "hidden";
+    likeCount: number;
+    commentCount: number;
+    likedByMe: boolean;
+    isOwn: boolean;
+    createdAt: string;
+    /** Set when the dashboard pinned this post; pinned posts sort first. */
+    pinnedAt: string | null;
+    /** Present when the post carries a poll. */
+    poll: FeedPoll | null;
+    /** Generic "reaction" module count (e.g. a "pray for" tap); the label/verb is host-defined. */
+    reactionCount: number;
+    hasReacted: boolean;
+    /** Display name of the most recent reactor, for a "X and N others reacted" affordance;
+     * null when nobody has reacted yet or the reaction module is off. */
+    lastReactorName: string | null;
+}
+export interface ThreadComment {
+    id: string;
+    postId: string;
+    authorId: string;
+    authorName: string;
+    authorOfficial: boolean;
+    authorHandle: string | null;
+    authorAvatarUrl: string | null;
+    text: string;
+    isOwn: boolean;
+    createdAt: string;
+}
+/**
+ * Public display name, with a host-configured fallback for profiles not yet named.
+ * Accepts either a raw username or any profile-shaped object carrying one (a row's
+ * `.profiles`, a `ProfileRow`, or a previously-mapped `CommunityProfile`).
+ */
+export declare function displayName(profile: string | null | undefined | {
+    username?: string | null;
+}, fallback: string): string;
+/**
+ * The topic column is app-defined free text. Unlike the mold (which dropped topics
+ * unknown to the app's static list), unknown topics stay visible under their raw id —
+ * the topics list is now host-config-driven and may lag behind live data.
+ */
+export declare function normalizeTopic(raw: string | null, topics: readonly CommunityTopicDef[]): string | null;
+export interface ProfileRow {
+    id: string;
+    username: string | null;
+    handle: string | null;
+    is_official: boolean | null;
+    bio: string | null;
+    avatar_url: string | null;
+}
+export interface CommunityProfile {
+    id: string;
+    name: string;
+    handle: string | null;
+    official: boolean;
+    bio: string | null;
+    avatarUrl: string | null;
+    /** Raw username, when available (pre-fallback, unlike `name`); populated by
+     * mapProfileRow so a CommunityProfile can itself be threaded back into displayName(). */
+    username?: string | null;
+}
+export declare function mapProfileRow(row: ProfileRow, fallback: string): CommunityProfile;
+/** Assemble a FeedPoll from the embedded option rows + batched vote data. */
+export declare function buildPoll(options: PollOptionRow[], counts: ReadonlyMap<string, number>, myOptionId: string | null): FeedPoll | null;
+/** Integer percentage for a result bar; a zero-vote poll shows 0% everywhere. */
+export declare function pollPercent(votes: number, totalVotes: number): number;
+export declare function mapPostRow(row: PostRow, myUid: string, fallback: string, topics: readonly CommunityTopicDef[], likedPostIds: ReadonlySet<string>, pollData?: PollData, reactionData?: ReactionData, 
+/** Host extension point (`CommunityConfig.feed.transformPost`), run last with
+ * the raw row (including any `extraPostColumns`) this post was built from. */
+transformPost?: (post: FeedPost, row: Record<string, unknown>) => FeedPost): FeedPost;
+/**
+ * Optimistic vote application: moves my vote to `optionId` on the matching
+ * post, shifting per-option counts; the total only grows on a first vote.
+ */
+export declare function applyPollVote(post: FeedPost, postId: string, optionId: string): FeedPost;
+/**
+ * Optimistic reaction application: +1 and hasReacted on the given post
+ * (idempotent: re-applying to an already-reacted post is a no-op that returns
+ * the same object back). Generalized from a host app's applyPrayer — the
+ * caller is expected to have already located the target post (e.g. via
+ * `posts.map((p) => (p.id === postId ? applyReaction(p) : p))`).
+ */
+export declare function applyReaction(post: FeedPost): FeedPost;
+export declare function mapCommentRow(row: CommentRow, myUid: string, fallback: string): ThreadComment;
+/** Floating pill label. "1 new post" / "N new posts". */
+export declare function newPostsLabel(count: number): string;
+/**
+ * Max createdAt across loaded posts. posts[0] is no longer the newest once a
+ * pinned post floats to the top, and the new-posts pill must not count the
+ * already-visible pinned post as "new".
+ */
+export declare function newestCreatedAt(posts: readonly {
+    createdAt: string;
+}[]): string | null;

package/lib/models.js

@@ -0,0 +1,178 @@
+"use strict";
+// Pure mapping between community backend rows and UI models.
+// No React Native / Supabase imports: this module is exercised by vitest in a node env.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_REACTION_DATA = exports.EMPTY_POLL_DATA = exports.POLL_OPTION_MAX_LENGTH = exports.POLL_MAX_OPTIONS = exports.POLL_MIN_OPTIONS = exports.COMMENT_MAX_LENGTH = exports.POST_MAX_LENGTH = exports.FEED_PAGE_SIZE = void 0;
+exports.displayName = displayName;
+exports.normalizeTopic = normalizeTopic;
+exports.mapProfileRow = mapProfileRow;
+exports.buildPoll = buildPoll;
+exports.pollPercent = pollPercent;
+exports.mapPostRow = mapPostRow;
+exports.applyPollVote = applyPollVote;
+exports.applyReaction = applyReaction;
+exports.mapCommentRow = mapCommentRow;
+exports.newPostsLabel = newPostsLabel;
+exports.newestCreatedAt = newestCreatedAt;
+exports.FEED_PAGE_SIZE = 20;
+// ============ DB-MIRRORING LIMITS (DO NOT CHANGE WITHOUT CHECKING THE DB) ============
+// Client-side mirrors of the community backend's check constraints, so the cap is an
+// invisible input limit instead of a generic insert error. Verified against the mold's
+// own constants on 2026-08-31 — POST_MAX_LENGTH and COMMENT_MAX_LENGTH differ from the
+// task brief's placeholder values (600 / 300); the mold/DB values below win.
+exports.POST_MAX_LENGTH = 2000;
+exports.COMMENT_MAX_LENGTH = 1000;
+exports.POLL_MIN_OPTIONS = 2;
+exports.POLL_MAX_OPTIONS = 4;
+exports.POLL_OPTION_MAX_LENGTH = 60;
+exports.EMPTY_POLL_DATA = { counts: new Map(), myVotes: new Map() };
+exports.EMPTY_REACTION_DATA = {
+    counts: new Map(),
+    mine: new Set(),
+    lastReactorName: new Map(),
+};
+/**
+ * Public display name, with a host-configured fallback for profiles not yet named.
+ * Accepts either a raw username or any profile-shaped object carrying one (a row's
+ * `.profiles`, a `ProfileRow`, or a previously-mapped `CommunityProfile`).
+ */
+function displayName(profile, fallback) {
+    const raw = typeof profile === "string" || profile == null ? profile : profile.username;
+    const trimmed = raw?.trim();
+    return trimmed ? trimmed : fallback;
+}
+/**
+ * The topic column is app-defined free text. Unlike the mold (which dropped topics
+ * unknown to the app's static list), unknown topics stay visible under their raw id —
+ * the topics list is now host-config-driven and may lag behind live data.
+ */
+function normalizeTopic(raw, topics) {
+    if (!raw)
+        return null;
+    const known = topics.find((t) => t.id === raw);
+    return known ? known.id : raw;
+}
+function mapProfileRow(row, fallback) {
+    return {
+        id: row.id,
+        name: displayName(row, fallback),
+        handle: row.handle ?? null,
+        official: row.is_official ?? false,
+        bio: row.bio ?? null,
+        avatarUrl: row.avatar_url ?? null,
+        // Raw username (pre-fallback), so a mapped CommunityProfile can itself be threaded back
+        // into displayName() elsewhere — see the field doc on CommunityProfile.
+        username: row.username ?? null,
+    };
+}
+/** Assemble a FeedPoll from the embedded option rows + batched vote data. */
+function buildPoll(options, counts, myOptionId) {
+    if (options.length === 0)
+        return null;
+    const mapped = [...options]
+        .sort((a, b) => a.idx - b.idx)
+        .map((o) => ({ id: o.id, label: o.label, votes: counts.get(o.id) ?? 0 }));
+    return {
+        options: mapped,
+        myOptionId,
+        totalVotes: mapped.reduce((sum, o) => sum + o.votes, 0),
+    };
+}
+/** Integer percentage for a result bar; a zero-vote poll shows 0% everywhere. */
+function pollPercent(votes, totalVotes) {
+    if (totalVotes <= 0)
+        return 0;
+    return Math.round((votes / totalVotes) * 100);
+}
+function mapPostRow(row, myUid, fallback, topics, likedPostIds, pollData = exports.EMPTY_POLL_DATA, reactionData = exports.EMPTY_REACTION_DATA, 
+/** Host extension point (`CommunityConfig.feed.transformPost`), run last with
+ * the raw row (including any `extraPostColumns`) this post was built from. */
+transformPost) {
+    const post = {
+        id: row.id,
+        authorId: row.author_id,
+        authorName: displayName(row.profiles, fallback),
+        authorOfficial: row.profiles?.is_official ?? false,
+        authorHandle: row.profiles?.handle ?? null,
+        authorAvatarUrl: row.profiles?.avatar_url ?? null,
+        topic: normalizeTopic(row.topic, topics),
+        text: row.content,
+        status: row.status === "hidden" ? "hidden" : "visible",
+        likeCount: row.likes[0]?.count ?? 0,
+        commentCount: row.comments[0]?.count ?? 0,
+        likedByMe: likedPostIds.has(row.id),
+        isOwn: row.author_id === myUid,
+        createdAt: row.created_at,
+        pinnedAt: row.pinned_at,
+        poll: buildPoll(row.poll_options, pollData.counts, pollData.myVotes.get(row.id) ?? null),
+        reactionCount: reactionData.counts.get(row.id) ?? 0,
+        hasReacted: reactionData.mine.has(row.id),
+        lastReactorName: reactionData.lastReactorName.get(row.id) ?? null,
+    };
+    return transformPost ? transformPost(post, row) : post;
+}
+/**
+ * Optimistic vote application: moves my vote to `optionId` on the matching
+ * post, shifting per-option counts; the total only grows on a first vote.
+ */
+function applyPollVote(post, postId, optionId) {
+    if (post.id !== postId || !post.poll)
+        return post;
+    const prev = post.poll.myOptionId;
+    if (prev === optionId)
+        return post;
+    return {
+        ...post,
+        poll: {
+            options: post.poll.options.map((o) => ({
+                ...o,
+                votes: o.votes + (o.id === optionId ? 1 : 0) - (o.id === prev ? 1 : 0),
+            })),
+            myOptionId: optionId,
+            totalVotes: post.poll.totalVotes + (prev === null ? 1 : 0),
+        },
+    };
+}
+/**
+ * Optimistic reaction application: +1 and hasReacted on the given post
+ * (idempotent: re-applying to an already-reacted post is a no-op that returns
+ * the same object back). Generalized from a host app's applyPrayer — the
+ * caller is expected to have already located the target post (e.g. via
+ * `posts.map((p) => (p.id === postId ? applyReaction(p) : p))`).
+ */
+function applyReaction(post) {
+    if (post.hasReacted)
+        return post;
+    return { ...post, hasReacted: true, reactionCount: post.reactionCount + 1 };
+}
+function mapCommentRow(row, myUid, fallback) {
+    return {
+        id: row.id,
+        postId: row.post_id,
+        authorId: row.author_id,
+        authorName: displayName(row.profiles, fallback),
+        authorOfficial: row.profiles?.is_official ?? false,
+        authorHandle: row.profiles?.handle ?? null,
+        authorAvatarUrl: row.profiles?.avatar_url ?? null,
+        text: row.content,
+        isOwn: row.author_id === myUid,
+        createdAt: row.created_at,
+    };
+}
+/** Floating pill label. "1 new post" / "N new posts". */
+function newPostsLabel(count) {
+    return count === 1 ? "1 new post" : `${count} new posts`;
+}
+/**
+ * Max createdAt across loaded posts. posts[0] is no longer the newest once a
+ * pinned post floats to the top, and the new-posts pill must not count the
+ * already-visible pinned post as "new".
+ */
+function newestCreatedAt(posts) {
+    let newest = null;
+    for (const p of posts) {
+        if (newest === null || Date.parse(p.createdAt) > Date.parse(newest))
+            newest = p.createdAt;
+    }
+    return newest;
+}