@rocapine/community-core 0.1.0

package/lib/hooks.js

@@ -0,0 +1,494 @@
+"use strict";
+// React Query hooks over the community service — the primary consumer-facing API of this
+// package. Every hook threads `cfg = useCommunityConfig()` through to the service layer and
+// to `emitEvent`, and every query is gated on `cfg.supabase !== null` so a host that never
+// configured a backend degrades to "always empty / never loading forever" instead of
+// throwing inside a render.
+//
+// Ported from the mold (`sdk/client/hooks/useCommunity.ts`) with a host app's newer
+// generalized reaction feature (`usePrayForPost` -> `useReactToPost`, optimistic
+// `applyReaction`) and unseen-count hook (parameterized on `lastSeenAtIso` instead of
+// reading that host's own store). No React Native / analytics-SDK / store imports here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCommunityFeed = useCommunityFeed;
+exports.useSearchPosts = useSearchPosts;
+exports.useNewPostsCount = useNewPostsCount;
+exports.useCommunityUnseenCount = useCommunityUnseenCount;
+exports.useThread = useThread;
+exports.useProfile = useProfile;
+exports.useUserPosts = useUserPosts;
+exports.useMyUid = useMyUid;
+exports.useUpdateProfile = useUpdateProfile;
+exports.useCreatePost = useCreatePost;
+exports.useCreateComment = useCreateComment;
+exports.useToggleLike = useToggleLike;
+exports.useVotePoll = useVotePoll;
+exports.useReactToPost = useReactToPost;
+exports.useReport = useReport;
+exports.useBlockUser = useBlockUser;
+exports.useDeleteContent = useDeleteContent;
+const react_query_1 = require("@tanstack/react-query");
+const events_1 = require("./events");
+const identity_1 = require("./identity");
+const models_1 = require("./models");
+const provider_1 = require("./provider");
+const service_1 = require("./service");
+const FEED_KEY = ["community", "feed"];
+const feedKey = (topic) => [...FEED_KEY, topic ?? "all"];
+const threadKey = (postId) => ["community", "thread", postId];
+const profileKey = (userId) => ["community", "profile", userId];
+const userPostsKey = (userId) => ["community", "userPosts", userId];
+const USER_POSTS_KEY = ["community", "userPosts"];
+const SEARCH_KEY = ["community", "search"];
+/**
+ * Adjust a post's commentCount across every cached feed page (all topic
+ * filters). The feed is never refetched after commenting (kept smooth), so the
+ * badge only tracks new comments if we reconcile the cache in place. Scoped to
+ * the feed only (matching the mold and the newer host's source) — a comment count
+ * change is not reflected in the user-posts/search caches, same as upstream.
+ */
+function bumpFeedCommentCount(queryClient, postId, delta) {
+    queryClient.setQueriesData({ queryKey: FEED_KEY }, (data) => data
+        ? {
+            ...data,
+            pages: data.pages.map((page) => page.map((post) => post.id === postId
+                ? { ...post, commentCount: Math.max(0, post.commentCount + delta) }
+                : post)),
+        }
+        : data);
+}
+/**
+ * Apply `mapPost` optimistically across every cache that can hold a
+ * `FeedPost`: the topic feeds, user-posts and search results (all
+ * `InfiniteData<FeedPost[]>`). Returns a snapshot for `rollbackPostCaches` on
+ * error. Used by `useVotePoll` and `useReactToPost`, the two mutations whose
+ * optimistic update must be visible from any screen that renders a
+ * `FeedPost` (mirrors the mold's `POST_PAGES_KEYS` sweep).
+ */
+async function applyOptimisticToAllPostCaches(queryClient, mapPost) {
+    await Promise.all([
+        queryClient.cancelQueries({ queryKey: FEED_KEY }),
+        queryClient.cancelQueries({ queryKey: USER_POSTS_KEY }),
+        queryClient.cancelQueries({ queryKey: SEARCH_KEY }),
+    ]);
+    const entries = [
+        ...queryClient.getQueriesData({ queryKey: FEED_KEY }),
+        ...queryClient.getQueriesData({ queryKey: USER_POSTS_KEY }),
+        ...queryClient.getQueriesData({ queryKey: SEARCH_KEY }),
+    ];
+    const applyToPages = (data) => data ? { ...data, pages: data.pages.map((page) => page.map(mapPost)) } : data;
+    queryClient.setQueriesData({ queryKey: FEED_KEY }, applyToPages);
+    queryClient.setQueriesData({ queryKey: USER_POSTS_KEY }, applyToPages);
+    queryClient.setQueriesData({ queryKey: SEARCH_KEY }, applyToPages);
+    return { entries };
+}
+function rollbackPostCaches(queryClient, snapshot) {
+    for (const [key, data] of snapshot.entries)
+        queryClient.setQueryData(key, data);
+}
+/**
+ * One infinite-scrolling feed, newest (then pinned) first. `enabled` is kept
+ * beyond the brief's literal `(topic?)` signature (both source apps take it,
+ * e.g. to pause the feed query while an in-progress search query is active) —
+ * defaults to `true` so `useCommunityFeed(topic)` still matches the brief.
+ */
+function useCommunityFeed(topic, enabled = true) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useInfiniteQuery)({
+        queryKey: feedKey(topic),
+        queryFn: ({ pageParam }) => (0, service_1.fetchFeedPage)(cfg, { topic, cursor: pageParam }),
+        initialPageParam: 0,
+        getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
+        enabled: cfg.supabase !== null && enabled,
+        staleTime: 1000 * 30,
+        retry: 1,
+    });
+}
+/**
+ * Search visible posts by content, infinite-scrolling like the feed.
+ * Enabled once the term has >= 2 chars.
+ */
+function useSearchPosts(term) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const cleaned = term.trim();
+    return (0, react_query_1.useInfiniteQuery)({
+        queryKey: [...SEARCH_KEY, cleaned],
+        queryFn: ({ pageParam }) => (0, service_1.searchPosts)(cfg, cleaned, { cursor: pageParam }),
+        initialPageParam: 0,
+        getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
+        enabled: cfg.supabase !== null && cleaned.length >= 2,
+        staleTime: 1000 * 30,
+        retry: 1,
+    });
+}
+/**
+ * Polls (5s, while `polling`) for posts newer than the loaded top. `topic`
+ * and `polling` are kept beyond the brief's literal `(sinceIso)` signature
+ * (both source apps take them, needed for a topic-filtered "N new posts" pill —
+ * see Task 5's same call on `countNewPosts`) — both default so
+ * `useNewPostsCount(sinceIso)` still matches the brief.
+ */
+function useNewPostsCount(sinceIso, topic, polling = true) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const q = (0, react_query_1.useQuery)({
+        queryKey: ["community", "newCount", topic ?? "all", sinceIso],
+        queryFn: () => (0, service_1.countNewPosts)(cfg, sinceIso, topic),
+        enabled: cfg.supabase !== null && !!sinceIso && polling,
+        refetchInterval: polling ? 5000 : false,
+        refetchIntervalInBackground: false,
+        staleTime: 0,
+    });
+    return q.data ?? 0;
+}
+/**
+ * Number of posts by others since the community was last opened (0 while
+ * loading/failing) — feeds a host's Community tab badge. Takes `lastSeenAtIso`
+ * as a parameter instead of reading a host's "last seen" store directly (the
+ * mold read a host-seam function, the newer host read its own store — this
+ * package has no store access at all, so the host now owns that value and
+ * passes it in).
+ */
+function useCommunityUnseenCount(lastSeenAtIso) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const q = (0, react_query_1.useQuery)({
+        queryKey: ["community", "unseen", lastSeenAtIso ?? "never"],
+        queryFn: () => (0, service_1.countNewPosts)(cfg, lastSeenAtIso ?? "1970-01-01T00:00:00Z"),
+        enabled: cfg.supabase !== null,
+        staleTime: 1000 * 60,
+        refetchInterval: 1000 * 120,
+        refetchIntervalInBackground: false,
+        retry: 1,
+    });
+    return q.data ?? 0;
+}
+function useThread(postId) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useQuery)({
+        queryKey: threadKey(postId ?? "none"),
+        queryFn: () => (0, service_1.fetchThread)(cfg, postId),
+        enabled: cfg.supabase !== null && !!postId,
+        staleTime: 1000 * 15,
+        retry: 1,
+    });
+}
+function useProfile(userId) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useQuery)({
+        queryKey: profileKey(userId ?? "none"),
+        queryFn: () => (0, service_1.fetchProfile)(cfg, userId),
+        enabled: cfg.supabase !== null && !!userId,
+        staleTime: 1000 * 30,
+        retry: 1,
+    });
+}
+/**
+ * One user's posts, newest first, infinite-scrolling like the feed.
+ */
+function useUserPosts(userId) {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useInfiniteQuery)({
+        queryKey: userPostsKey(userId ?? "none"),
+        queryFn: ({ pageParam }) => (0, service_1.fetchUserPosts)(cfg, userId, { cursor: pageParam }),
+        initialPageParam: 0,
+        getNextPageParam: (lastPage, pages) => lastPage.length === models_1.FEED_PAGE_SIZE ? pages.length : undefined,
+        enabled: cfg.supabase !== null && !!userId,
+        staleTime: 1000 * 30,
+        retry: 1,
+    });
+}
+/** Our own stable community uid, resolved once and cached for the app session. */
+function useMyUid() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const q = (0, react_query_1.useQuery)({
+        queryKey: ["community", "myUid"],
+        queryFn: () => (0, identity_1.ensureIdentity)(cfg),
+        enabled: cfg.supabase !== null,
+        staleTime: Infinity,
+        gcTime: Infinity,
+    });
+    return q.data ?? null;
+}
+/** Profile edits refresh everything derived from a profile row: the profile
+ * itself, plus the handle/avatar shown on every cached feed and thread. */
+function useUpdateProfile() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (input) => (0, service_1.updateProfile)(cfg, input),
+        onSuccess: (result, input) => {
+            if (result.status !== "ok")
+                return;
+            queryClient.invalidateQueries({ queryKey: ["community"] });
+            (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.profileUpdated, {
+                hasBio: !!input.bio,
+                hasAvatar: !!input.avatarUrl,
+                handleChanged: !!input.handle,
+            });
+        },
+    });
+}
+/**
+ * Optimistic post creation with NO refetch: the post shows instantly, and after
+ * moderation we reconcile the cache in place, published -> swap the temp id for
+ * the real one (stays), rejected -> remove it. Smooth, no loading flicker.
+ */
+function useCreatePost() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        onMutate: async ({ topic, text, authorName, pollOptions }) => {
+            await queryClient.cancelQueries({ queryKey: FEED_KEY });
+            const tempId = `optimistic-${Date.now()}`;
+            const optimistic = {
+                id: tempId,
+                authorId: "",
+                authorName,
+                authorOfficial: false,
+                authorHandle: null,
+                authorAvatarUrl: null,
+                topic,
+                text,
+                status: "visible",
+                likeCount: 0,
+                commentCount: 0,
+                likedByMe: false,
+                isOwn: true,
+                createdAt: new Date().toISOString(),
+                pinnedAt: null,
+                // Temp option ids: PollBlock refuses votes on them; the post-publish
+                // refetch below swaps in the real uuids.
+                poll: pollOptions && pollOptions.length > 0
+                    ? {
+                        options: pollOptions.map((label, i) => ({ id: `temp-${i}`, label, votes: 0 })),
+                        myOptionId: null,
+                        totalVotes: 0,
+                    }
+                    : null,
+                reactionCount: 0,
+                hasReacted: false,
+                lastReactorName: null,
+            };
+            const prepend = (key) => queryClient.setQueryData(key, (d) => d ? { ...d, pages: [[optimistic, ...(d.pages[0] ?? [])], ...d.pages.slice(1)] } : d);
+            prepend(feedKey(undefined));
+            prepend(feedKey(topic));
+            return { tempId };
+        },
+        mutationFn: async ({ topic, text, pollOptions }) => {
+            const id = await (0, service_1.createPost)(cfg, { topic, body: text, pollOptions });
+            const verdict = await (0, service_1.moderateOne)(cfg, { kind: "post", id });
+            return { id, verdict };
+        },
+        onSuccess: ({ id, verdict }, { topic, text, pollOptions }, { tempId }) => {
+            const rejected = verdict.status === "rejected";
+            queryClient.setQueriesData({ queryKey: FEED_KEY }, (d) => d
+                ? {
+                    ...d,
+                    pages: d.pages.map((p) => rejected
+                        ? p.filter((post) => post.id !== tempId)
+                        : p.map((post) => post.id === tempId ? { ...post, id, status: "visible" } : post)),
+                }
+                : d);
+            if (verdict.status === "published") {
+                const hasPoll = !!pollOptions && pollOptions.length > 0;
+                (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.postPublished, {
+                    topic,
+                    bodyLength: text.trim().length,
+                    hasPoll,
+                });
+                cfg.host.onContentPublished();
+                // The in-place swap above keeps the optimistic poll's temp option ids;
+                // voting needs the real uuids, so a poll post refetches in background.
+                if (hasPoll)
+                    queryClient.invalidateQueries({ queryKey: FEED_KEY });
+            }
+        },
+        onError: (_e, _v, context) => {
+            queryClient.setQueriesData({ queryKey: FEED_KEY }, (d) => d
+                ? { ...d, pages: d.pages.map((p) => p.filter((post) => post.id !== context?.tempId)) }
+                : d);
+        },
+    });
+}
+/** Optimistic comment creation, same reconcile-in-place model as posts. */
+function useCreateComment() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        onMutate: async ({ postId, text, authorName }) => {
+            await queryClient.cancelQueries({ queryKey: threadKey(postId) });
+            await queryClient.cancelQueries({ queryKey: FEED_KEY });
+            const tempId = `optimistic-${Date.now()}`;
+            const optimistic = {
+                id: tempId,
+                postId,
+                authorId: "",
+                authorName,
+                authorOfficial: false,
+                authorHandle: null,
+                authorAvatarUrl: null,
+                text,
+                isOwn: true,
+                createdAt: new Date().toISOString(),
+            };
+            queryClient.setQueryData(threadKey(postId), (d) => [
+                ...(d ?? []),
+                optimistic,
+            ]);
+            bumpFeedCommentCount(queryClient, postId, 1);
+            return { tempId };
+        },
+        mutationFn: async ({ postId, text }) => {
+            const id = await (0, service_1.createComment)(cfg, postId, text);
+            const verdict = await (0, service_1.moderateOne)(cfg, { kind: "comment", id });
+            return { id, verdict };
+        },
+        onSuccess: ({ id, verdict }, { postId, text }, { tempId }) => {
+            const rejected = verdict.status === "rejected";
+            queryClient.setQueryData(threadKey(postId), (d) => (d ?? [])
+                .filter((c) => !(rejected && c.id === tempId))
+                .map((c) => (c.id === tempId ? { ...c, id } : c)));
+            // A rejected comment never becomes visible, so undo the optimistic bump.
+            if (rejected)
+                bumpFeedCommentCount(queryClient, postId, -1);
+            if (verdict.status === "published") {
+                (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.commentPublished, {
+                    postId,
+                    bodyLength: text.trim().length,
+                });
+                cfg.host.onContentPublished();
+            }
+        },
+        onError: (_e, { postId }, context) => {
+            queryClient.setQueryData(threadKey(postId), (d) => (d ?? []).filter((c) => c.id !== context?.tempId));
+            bumpFeedCommentCount(queryClient, postId, -1);
+        },
+    });
+}
+/** Optimistic like toggle across all cached feed pages (every topic filter). */
+function useToggleLike() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ postId, liked }) => (0, service_1.setLike)(cfg, postId, liked),
+        onMutate: async ({ postId, liked }) => {
+            await queryClient.cancelQueries({ queryKey: FEED_KEY });
+            const previous = queryClient.getQueriesData({
+                queryKey: FEED_KEY,
+            });
+            queryClient.setQueriesData({ queryKey: FEED_KEY }, (data) => data
+                ? {
+                    ...data,
+                    pages: data.pages.map((page) => page.map((post) => post.id === postId
+                        ? {
+                            ...post,
+                            likedByMe: liked,
+                            likeCount: Math.max(0, post.likeCount + (liked ? 1 : -1)),
+                        }
+                        : post)),
+                }
+                : data);
+            return { previous };
+        },
+        onError: (_err, _vars, context) => {
+            for (const [key, data] of context?.previous ?? [])
+                queryClient.setQueryData(key, data);
+        },
+        onSuccess: (_data, { liked, postId, topic }) => {
+            if (liked)
+                (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.postLiked, { postId, topic });
+        },
+    });
+}
+/**
+ * Optimistic poll vote across every post cache (mirror of useToggleLike, but
+ * reaching the user-posts/search caches too — see `applyOptimisticToAllPostCaches`).
+ * `optionId` is the poll option's row id (Task 5 ruling), not a numeric index —
+ * the brief's `optionIndex` naming is dropped since neither `votePoll` nor
+ * `applyPollVote` operate on one.
+ */
+function useVotePoll() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ postId, optionId }) => (0, service_1.votePoll)(cfg, postId, optionId),
+        onMutate: ({ postId, optionId }) => applyOptimisticToAllPostCaches(queryClient, (post) => (0, models_1.applyPollVote)(post, postId, optionId)),
+        onError: (_err, _vars, context) => {
+            if (context)
+                rollbackPostCaches(queryClient, context);
+        },
+        onSuccess: (_data, { postId, optionId }) => {
+            (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.pollVoted, { postId, optionId });
+        },
+    });
+}
+/**
+ * Optimistic reaction across every post cache (mirror of useVotePoll; renamed
+ * from the mold's `usePrayForPost`). `applyReaction(post)` is single-argument
+ * (Task 3 ruling — it does not filter by post id), so the mapper here pre-filters
+ * to the target post itself before calling it, and separately tracks whether
+ * that post already had `hasReacted` so a retap of an already-reacted post
+ * (the reaction is non-retractable, `setReaction` is idempotent) does not
+ * re-emit the analytics event.
+ */
+function useReactToPost() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ postId }) => (0, service_1.setReaction)(cfg, postId),
+        onMutate: async ({ postId }) => {
+            let alreadyReacted = false;
+            const snapshot = await applyOptimisticToAllPostCaches(queryClient, (post) => {
+                if (post.id !== postId)
+                    return post;
+                if (post.hasReacted)
+                    alreadyReacted = true;
+                return (0, models_1.applyReaction)(post);
+            });
+            return { ...snapshot, alreadyReacted };
+        },
+        onError: (_err, _vars, context) => {
+            if (context)
+                rollbackPostCaches(queryClient, context);
+        },
+        onSuccess: (_data, { postId }, context) => {
+            if (!context?.alreadyReacted)
+                (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.reactionAdded, { postId });
+        },
+    });
+}
+function useReport() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (input) => (0, service_1.reportContent)(cfg, input),
+        onSuccess: (_data, input) => {
+            (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.userReported, {
+                reason: input.reason,
+                contentType: input.postId ? "post" : "comment",
+            });
+        },
+    });
+}
+/** Blocking re-filters everything: drop every community cache and refetch. */
+function useBlockUser() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ userId }) => (0, service_1.blockUser)(cfg, userId),
+        onSuccess: () => {
+            (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.userBlocked);
+            queryClient.invalidateQueries({ queryKey: ["community"] });
+        },
+    });
+}
+function useDeleteContent() {
+    const cfg = (0, provider_1.useCommunityConfig)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ kind, id }) => kind === "post" ? (0, service_1.deleteOwnPost)(cfg, id) : (0, service_1.deleteOwnComment)(cfg, id),
+        onSuccess: (_data, { kind, postId }) => {
+            (0, events_1.emitEvent)(cfg, events_1.COMMUNITY_EVENTS.contentDeleted, { contentType: kind });
+            queryClient.invalidateQueries({ queryKey: threadKey(postId) });
+            queryClient.invalidateQueries({ queryKey: FEED_KEY });
+        },
+    });
+}

package/lib/identity.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedCommunityConfig } from "./config";
+/**
+ * Resolve the community user id, signing in anonymously on first use.
+ * Never rejects: resolves to null when offline, when anonymous sign-ins are
+ * off, or when the host never configured a Supabase client (degraded mode) —
+ * the next call retries.
+ */
+export declare function ensureIdentity(cfg: ResolvedCommunityConfig): Promise<string | null>;
+/**
+ * Drops the memoized identity (and every dedupe memo) so the next
+ * ensureIdentity() re-reads the (possibly different) session. Call after any
+ * host auth transition: login/SSO replaces the anonymous uid, logout needs a
+ * fresh anonymous identity.
+ */
+export declare function resetIdentity(): void;
+/**
+ * Mirror the host's display name, locale and analytics ids onto the
+ * profiles row. Safe to call on every app open / community open: each field
+ * hits the network at most once per launch per changed value (mold pattern
+ * from syncCommunityUsername / syncProfileLocale), batched into one update.
+ * No-op in degraded mode (no Supabase client configured).
+ */
+export declare function syncProfileFromHost(cfg: ResolvedCommunityConfig): Promise<void>;

package/lib/identity.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureIdentity = ensureIdentity;
+exports.resetIdentity = resetIdentity;
+exports.syncProfileFromHost = syncProfileFromHost;
+// One anonymous Supabase identity per install. signInAnonymously() runs once;
+// afterwards getSession() restores the same user (and uuid) from AsyncStorage.
+// Ported from the mold's lib/community-identity.ts — see the design spec for
+// what changed crossing the host-adapter seam.
+let inFlight = null;
+let lastSyncedUsername = null;
+let lastSyncedLocale = null;
+let lastSyncedAnalyticsKey = null;
+/**
+ * Resolve the community user id, signing in anonymously on first use.
+ * Never rejects: resolves to null when offline, when anonymous sign-ins are
+ * off, or when the host never configured a Supabase client (degraded mode) —
+ * the next call retries.
+ */
+function ensureIdentity(cfg) {
+    if (!cfg.supabase)
+        return Promise.resolve(null);
+    inFlight ?? (inFlight = bootstrap(cfg).catch(() => {
+        inFlight = null; // allow a retry on the next call
+        return null;
+    }));
+    return inFlight;
+}
+/**
+ * Drops the memoized identity (and every dedupe memo) so the next
+ * ensureIdentity() re-reads the (possibly different) session. Call after any
+ * host auth transition: login/SSO replaces the anonymous uid, logout needs a
+ * fresh anonymous identity.
+ */
+function resetIdentity() {
+    inFlight = null;
+    lastSyncedUsername = null;
+    lastSyncedLocale = null;
+    lastSyncedAnalyticsKey = null;
+}
+async function bootstrap(cfg) {
+    const client = cfg.requireClient();
+    const { data } = await client.auth.getSession();
+    if (data.session)
+        return data.session.user.id;
+    const { data: signIn, error } = await client.auth.signInAnonymously();
+    if (error || !signIn.user)
+        throw error ?? new Error("anonymous sign-in returned no user");
+    const uid = signIn.user.id;
+    // Enrich the trigger-created profile so moderation alerts can identify the
+    // account (repeat offenders, account value). Best effort.
+    const { amplitudeId, revenuecatId } = cfg.host.getAnalyticsIds();
+    await client
+        .from("profiles")
+        .update({ amplitude_id: amplitudeId ?? null, revenuecat_id: revenuecatId ?? null })
+        .eq("id", uid);
+    return uid;
+}
+/**
+ * Mirror the host's display name, locale and analytics ids onto the
+ * profiles row. Safe to call on every app open / community open: each field
+ * hits the network at most once per launch per changed value (mold pattern
+ * from syncCommunityUsername / syncProfileLocale), batched into one update.
+ * No-op in degraded mode (no Supabase client configured).
+ */
+async function syncProfileFromHost(cfg) {
+    if (!cfg.supabase)
+        return;
+    const name = cfg.host.getDisplayName()?.trim() || null;
+    const locale = cfg.host.getLocale();
+    const { amplitudeId, revenuecatId } = cfg.host.getAnalyticsIds();
+    const analyticsKey = JSON.stringify({
+        amplitudeId: amplitudeId ?? null,
+        revenuecatId: revenuecatId ?? null,
+    });
+    const update = {};
+    if (name && name !== lastSyncedUsername)
+        update.username = name;
+    // profiles.locale only exists when the push module's migration ran
+    // (push/001_push.sql) — writing it on a core-only install fails the
+    // update with an unknown-column error.
+    if (cfg.modules.push && locale !== lastSyncedLocale)
+        update.locale = locale;
+    if (analyticsKey !== lastSyncedAnalyticsKey) {
+        update.amplitude_id = amplitudeId ?? null;
+        update.revenuecat_id = revenuecatId ?? null;
+    }
+    if (Object.keys(update).length === 0)
+        return;
+    const uid = await ensureIdentity(cfg);
+    if (!uid)
+        return;
+    const client = cfg.requireClient();
+    const { error } = await client.from("profiles").update(update).eq("id", uid);
+    if (!error) {
+        if ("username" in update)
+            lastSyncedUsername = name;
+        if ("locale" in update)
+            lastSyncedLocale = locale;
+        if ("amplitude_id" in update)
+            lastSyncedAnalyticsKey = analyticsKey;
+    }
+}

package/lib/inbox-hooks.d.ts

@@ -0,0 +1,23 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type InboxState } from "./inbox-service";
+/**
+ * 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).
+ */
+export declare function useNotificationInbox(): UseQueryResult<InboxState>;
+/**
+ * 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.
+ */
+export declare function useUnreadNotificationCount(): number;
+/**
+ * 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.
+ */
+export declare function useMarkInboxSeen(): import("@tanstack/react-query").UseMutationResult<void, Error, void, void>;