@rocapine/community-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rocapine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @rocapine/community-core
+
+Headless data layer for the Community SDK: config, models, Supabase queries,
+React Query hooks, anonymous identity, and the analytics event seam. No
+React Native, no components, no store, no router, no analytics provider.
+
+```bash
+npm install @rocapine/community-core
+```
+
+Peer dependencies: `react >=18`, `@supabase/supabase-js ^2.45.0`,
+`@tanstack/react-query ^5.50.0`.
+
+## `CommunityConfig`
+
+The single configuration object passed to `<CommunityProvider config={...}>`:
+
+```ts
+import type { CommunityConfig } from "@rocapine/community-core";
+
+const config: CommunityConfig = {
+  // Connection — injected, never created by the SDK.
+  supabase: mySupabaseClient, // or `null` for degraded mode, see below
+
+  // Product vocabulary
+  appName: "My App", // pushes, inbox, broadcast fallback title
+  anonymousAuthorFallback: "Someone", // shown when an author has no username yet
+
+  // Topics — nothing hardcoded. `id` resolves to `topics.<id>` in the UI
+  // package's i18n catalog (see packages/ui/README.md); the app supplies
+  // the key for any topic it invents. `officialOnly: true` topics (e.g.
+  // "news") are writable only by `is_official` profiles — enforced by RLS.
+  topics: [{ id: "general" }, { id: "question" }, { id: "news", officialOnly: true }],
+
+  // Opt-in modules — MUST mirror what the CLI installed on the backend.
+  modules: {
+    polls: true,
+    push: false,
+    inbox: true,
+    reaction: { key: "cheer" }, // or `false` to disable the reaction module
+  },
+
+  // Host adapters — every field optional, no-op defaults.
+  host: {
+    getDisplayName: () => myUserStore.firstName,
+    getAnalyticsIds: () => ({ amplitudeId: "...", revenuecatId: "..." }),
+    onEvent: (name, props) => myAnalytics.track(name, props),
+    rulesAcceptance: {
+      get: async () => myStore.acceptedRules,
+      set: async () => myStore.setAcceptedRules(true),
+    },
+    onContentPublished: () => myReviewGate.arm(),
+    getLocale: () => "en",
+  },
+};
+```
+
+### Degraded mode
+
+`supabase: null` is a first-class, supported state (not an error path): every
+hook returns empty/loading-false states, `useCommunityConfig()`'s
+`requireClient()` throws a `CommunityDisabledError` that hooks catch
+internally, and exactly one `console.warn` is logged the first time a query
+actually needs the client. The app boots and renders normally with no
+backend configured — the pattern `examples/expo-app` uses when
+`EXPO_PUBLIC_SUPABASE_URL`/`_KEY` are unset.
+
+### Host adapters (`CommunityHostAdapters`)
+
+All optional, all default to a no-op:
+
+| Field                | Signature                                                | Purpose                                                                                                                                                                               |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getDisplayName`     | `() => string \| null`                                   | Feeds the display name shown for the current user before their community username is set                                                                                              |
+| `getAnalyticsIds`    | `() => { amplitudeId?: string; revenuecatId?: string }`  | Cross-referencing ids attached where the host wants them                                                                                                                              |
+| `onEvent`            | `(name: string, props: Record<string, unknown>) => void` | **The only analytics seam.** Every product event goes through this; the SDK never depends on any analytics provider. Never throws through to the UI even if the adapter itself throws |
+| `rulesAcceptance`    | `{ get(): Promise<boolean>; set(): Promise<void> }`      | Persists whether the user has accepted the one-time community guidelines sheet                                                                                                        |
+| `onContentPublished` | `() => void`                                             | Fired after a post/comment is successfully published (e.g. to arm a review-gate)                                                                                                      |
+| `getLocale`          | `() => string`                                           | Selects which locale-specific behavior the _host_ wants (distinct from the UI package's own `translations.locale` prop)                                                               |
+
+### Feed row extension point (`CommunityConfig.feed`)
+
+Optional, defaults to `{}` — omitting `feed` entirely keeps today's behavior
+byte-identical. It exists for a host that stores extra columns on `posts` the
+shared schema doesn't know about (e.g. Nightward's `posts.seed_likes`
+top-up), without forking the query or mapping layer:
+
+```ts
+import type { CommunityConfig } from "@rocapine/community-core";
+
+const config: CommunityConfig = {
+  // ...supabase, appName, anonymousAuthorFallback, topics, modules...
+  feed: {
+    // Appended to the posts `select` in every posts-table query
+    // (fetchFeedPage, fetchUserPosts, searchPosts). Only `[a-z0-9_]+`
+    // column names are accepted — anything else (a relation embed, a rename,
+    // a stray `*`) is dropped with a `console.warn` instead of reaching the
+    // query string.
+    extraPostColumns: ["seed_likes"],
+    // Runs last inside `mapPostRow`, given the mapped post and the raw row
+    // (including any extraPostColumns) it came from.
+    transformPost: (post, row) => ({
+      ...post,
+      likeCount: post.likeCount + (Number(row.seed_likes) || 0),
+    }),
+  },
+};
+```
+
+Two things worth knowing:
+
+- `transformPost` only runs on rows the SDK fetched from the backend. The
+  optimistic post shown right after `createPost` has no raw row yet, so it
+  renders untransformed until the next refetch swaps in the server-mapped
+  (and transformed) version — acceptable since the gap is a moderation-queue
+  window, not a rendered-forever state.
+- `fetchThread` queries `comments`, not `posts` — `extraPostColumns` and
+  `transformPost` don't apply there; a thread's parent post is the
+  already-fetched, already-transformed `FeedPost` the caller passes in, never
+  re-fetched.
+
+### Event names (`COMMUNITY_EVENTS`)
+
+```ts
+import { COMMUNITY_EVENTS, type CommunityEventName } from "@rocapine/community-core";
+```
+
+`COMMUNITY_EVENTS` is a frozen map of stable event-name strings — `opened`,
+`rulesAccepted`, `postPublished`, `pollVoted`, `threadOpened`, `postLiked`,
+`commentPublished`, `profileOpened`, `profileUpdated`, `reactionAdded`,
+`userReported`, `userBlocked`, `contentDeleted`, `inboxOpened` — forwarded to
+`host.onEvent` by the exported `emitEvent(cfg, name, props)` helper. Route or
+ignore these in your own tracking plan; nothing else in the package calls an
+analytics provider directly.
+
+### Schema drift check
+
+`CommunityProvider` calls a dev-only diagnostic on mount that reads
+`community_meta.schema_version` from the backend and warns (never throws) if
+it doesn't match `REQUIRED_SCHEMA_VERSION` (currently `1`, exported from the
+package). This only runs when React Native's `__DEV__` is true — it never
+runs in production and is silent in degraded mode.
+
+## What else is exported
+
+- **Models & limits**: `PostRow`, `CommentRow`, `ProfileRow`, `FeedPost`,
+  `ThreadComment`, `CommunityProfile`, `FeedPoll`, `PollData`,
+  `ReactionData`, and DB-mirroring constants `FEED_PAGE_SIZE`,
+  `POST_MAX_LENGTH` (2000), `COMMENT_MAX_LENGTH` (1000), `POLL_MIN_OPTIONS`
+  (2), `POLL_MAX_OPTIONS` (4), `POLL_OPTION_MAX_LENGTH` (60) — client-side
+  mirrors of the backend's check constraints.
+- **Identity**: `ensureIdentity()`, `resetIdentity()`, `syncProfileFromHost()`
+  — anonymous Supabase auth session management.
+- **Queries** (`service.ts`): `fetchFeedPage`, `countNewPosts`, `fetchProfile`,
+  `fetchUserPosts`, `searchPosts`, `fetchThread`, `createPost`, `votePoll`,
+  `createComment`, `moderateOne`, `setLike`, `setReaction`,
+  `fetchReactionSummaries`, `reportContent`, `blockUser`, `deleteOwnPost`,
+  `deleteOwnComment`, `updateProfile`, `uploadAvatar`, `buildFeedSelect`
+  (pure helper behind `feed.extraPostColumns`, see below).
+- **React Query hooks** (`hooks.ts`): `useCommunityFeed`, `useSearchPosts`,
+  `useNewPostsCount`, `useCommunityUnseenCount`, `useThread`, `useProfile`,
+  `useUserPosts`, `useMyUid`, `useUpdateProfile`, `useCreatePost`,
+  `useCreateComment`, `useToggleLike`, `useVotePoll`, `useReactToPost`,
+  `useReport`, `useBlockUser`, `useDeleteContent`.
+- **Inbox** (opt-in via `modules.inbox`): `fetchInbox`, `markInboxSeen`,
+  `unreadCount`, and hooks `useNotificationInbox`,
+  `useUnreadNotificationCount`, `useMarkInboxSeen`.
+- **`timeAgo(iso)`** — hardcoded-English relative-time formatting, kept for
+  back-compat. **`timeAgoParts(iso, nowMs)`** — the language-free unit+value
+  decomposition the UI package actually localizes through its own catalog
+  (see `formatTimeAgo` in `@rocapine/community-ui`).
+
+See `src/index.ts` for the exhaustive, authoritative export list.

package/lib/config.d.ts

@@ -0,0 +1,74 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { FeedPost } from "./models";
+export type CommunityTopicDef = {
+    id: string;
+    officialOnly?: boolean;
+};
+export type CommunityModules = {
+    polls: boolean;
+    push: boolean;
+    inbox: boolean;
+    reaction: {
+        key: string;
+    } | false;
+};
+export type CommunityHostAdapters = {
+    getDisplayName?: () => string | null;
+    getAnalyticsIds?: () => {
+        amplitudeId?: string;
+        revenuecatId?: string;
+    };
+    onEvent?: (name: string, props: Record<string, unknown>) => void;
+    rulesAcceptance?: {
+        get(): Promise<boolean>;
+        set(): Promise<void>;
+    };
+    onContentPublished?: () => void;
+    getLocale?: () => string;
+};
+/**
+ * Host-defined extension point for the raw `posts` row shape and its mapped
+ * `FeedPost` output — added for hosts (e.g. Nightward) that store extra
+ * columns on `posts` (like a seed-likes top-up) the shared schema doesn't
+ * know about. Both fields are optional and default to a no-op, so a host
+ * that never sets `feed` gets byte-identical behavior to before this existed.
+ *
+ * `transformPost` only runs on rows fetched from the backend (`fetchFeedPage`,
+ * `fetchUserPosts`, `searchPosts` — see `mapPostRow` call sites in
+ * `service.ts`). It does NOT run on the optimistic post shown immediately
+ * after `createPost` (there is no raw row yet) — that post renders untransformed
+ * until the next refetch replaces it with a server-mapped one. `fetchThread`
+ * queries `comments`, not `posts`, so `extraPostColumns`/`transformPost` don't
+ * apply there.
+ */
+export type CommunityFeedConfig = {
+    /** Appended to the posts select in every posts-table query. Only
+     * `[a-z0-9_]+` column names are accepted; anything else is dropped with a
+     * `console.warn` (minimal guard against passing a crafted select fragment). */
+    extraPostColumns?: string[];
+    /** Applied to every server-mapped `FeedPost`, given the raw row (including
+     * any `extraPostColumns`) it was built from. */
+    transformPost?: (post: FeedPost, row: Record<string, unknown>) => FeedPost;
+};
+export type CommunityConfig = {
+    supabase: SupabaseClient | null;
+    appName: string;
+    anonymousAuthorFallback: string;
+    topics: CommunityTopicDef[];
+    modules: CommunityModules;
+    host?: CommunityHostAdapters;
+    feed?: CommunityFeedConfig;
+};
+export declare class CommunityDisabledError extends Error {
+    constructor();
+}
+type RequiredCommunityHostAdapters = Required<CommunityHostAdapters>;
+export type ResolvedCommunityConfig = CommunityConfig & {
+    host: RequiredCommunityHostAdapters;
+    feed: CommunityFeedConfig;
+    requireClient(): SupabaseClient;
+    composeTopics(): CommunityTopicDef[];
+    isOfficialTopic(id: string): boolean;
+};
+export declare function resolveConfig(config: CommunityConfig): ResolvedCommunityConfig;
+export {};

package/lib/config.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunityDisabledError = void 0;
+exports.resolveConfig = resolveConfig;
+class CommunityDisabledError extends Error {
+    constructor() {
+        super("community backend not configured");
+        this.name = "CommunityDisabledError";
+    }
+}
+exports.CommunityDisabledError = CommunityDisabledError;
+let warned = false;
+const defaultHost = {
+    getDisplayName: () => null,
+    getAnalyticsIds: () => ({}),
+    onEvent: () => { },
+    rulesAcceptance: {
+        get: async () => false,
+        set: async () => { },
+    },
+    onContentPublished: () => { },
+    getLocale: () => "en",
+};
+function resolveConfig(config) {
+    const host = {
+        ...defaultHost,
+        ...config.host,
+    };
+    const resolved = {
+        ...config,
+        host,
+        feed: config.feed ?? {},
+        requireClient() {
+            if (!resolved.supabase) {
+                if (!warned) {
+                    warned = true;
+                    console.warn("[@rocapine/community-core] community backend not configured — running in degraded mode.");
+                }
+                throw new CommunityDisabledError();
+            }
+            return resolved.supabase;
+        },
+        composeTopics() {
+            return resolved.topics.filter((topic) => !topic.officialOnly);
+        },
+        isOfficialTopic(id) {
+            return resolved.topics.some((topic) => topic.id === id && topic.officialOnly === true);
+        },
+    };
+    return Object.freeze(resolved);
+}

package/lib/events.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedCommunityConfig } from "./config";
+export declare const COMMUNITY_EVENTS: {
+    readonly opened: "community_opened";
+    readonly rulesAccepted: "community_rules_accepted";
+    readonly postPublished: "community_post_published";
+    readonly pollVoted: "community_poll_voted";
+    readonly threadOpened: "community_thread_opened";
+    readonly postLiked: "community_post_liked";
+    readonly commentPublished: "community_comment_published";
+    readonly profileOpened: "community_profile_opened";
+    readonly profileUpdated: "community_profile_updated";
+    readonly reactionAdded: "community_reaction_added";
+    readonly userReported: "user_reported";
+    readonly userBlocked: "user_blocked";
+    readonly contentDeleted: "content_deleted";
+    readonly inboxOpened: "notification_center_opened";
+};
+export type CommunityEventName = (typeof COMMUNITY_EVENTS)[keyof typeof COMMUNITY_EVENTS];
+/** Forwards to the host's onEvent adapter. Never throws — a bad adapter must never break the UI. */
+export declare function emitEvent(cfg: ResolvedCommunityConfig, name: CommunityEventName, props?: Record<string, unknown>): void;

package/lib/events.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMUNITY_EVENTS = void 0;
+exports.emitEvent = emitEvent;
+// ⭐ Analytics seam — community code emits every product event through
+// emitEvent() and nothing else. The host wires cfg.host.onEvent to its own
+// tracking plan; left as a no-op by default so the community works before
+// analytics are wired.
+exports.COMMUNITY_EVENTS = {
+    opened: "community_opened",
+    rulesAccepted: "community_rules_accepted",
+    postPublished: "community_post_published",
+    pollVoted: "community_poll_voted",
+    threadOpened: "community_thread_opened",
+    postLiked: "community_post_liked",
+    commentPublished: "community_comment_published",
+    profileOpened: "community_profile_opened",
+    profileUpdated: "community_profile_updated",
+    reactionAdded: "community_reaction_added",
+    userReported: "user_reported",
+    userBlocked: "user_blocked",
+    contentDeleted: "content_deleted",
+    inboxOpened: "notification_center_opened",
+};
+/** Forwards to the host's onEvent adapter. Never throws — a bad adapter must never break the UI. */
+function emitEvent(cfg, name, props) {
+    try {
+        cfg.host.onEvent(name, props ?? {});
+    }
+    catch {
+        // swallow — analytics must never break the app
+    }
+}

package/lib/hooks.d.ts

@@ -0,0 +1,122 @@
+import { type InfiniteData } from "@tanstack/react-query";
+import { type CommunityProfile, type FeedPost, type ThreadComment } from "./models";
+import { type ModerationVerdict, type ReportInput, type UpdateProfileInput, type UpdateProfileResult } from "./service";
+type PostCacheEntry = [readonly unknown[], InfiniteData<FeedPost[]> | undefined];
+/**
+ * Snapshot of every post-holding cache, for optimistic-update rollback on
+ * error. The feed, user-posts and search caches are all `InfiniteData` now
+ * that user-posts and search are paginated like the feed — one flat list of
+ * entries instead of the feed/flat split this needed before.
+ */
+interface PostCacheSnapshot {
+    entries: PostCacheEntry[];
+}
+/**
+ * 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.
+ */
+export declare function useCommunityFeed(topic?: string, enabled?: boolean): import("@tanstack/react-query").UseInfiniteQueryResult<InfiniteData<FeedPost[], unknown>, Error>;
+/**
+ * Search visible posts by content, infinite-scrolling like the feed.
+ * Enabled once the term has >= 2 chars.
+ */
+export declare function useSearchPosts(term: string): import("@tanstack/react-query").UseInfiniteQueryResult<InfiniteData<FeedPost[], unknown>, Error>;
+/**
+ * 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.
+ */
+export declare function useNewPostsCount(sinceIso: string | null, topic?: string, polling?: boolean): number;
+/**
+ * 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).
+ */
+export declare function useCommunityUnseenCount(lastSeenAtIso: string | null): number;
+export declare function useThread(postId: string | null): import("@tanstack/react-query").UseQueryResult<ThreadComment[], Error>;
+export declare function useProfile(userId: string | null): import("@tanstack/react-query").UseQueryResult<CommunityProfile, Error>;
+/**
+ * One user's posts, newest first, infinite-scrolling like the feed.
+ */
+export declare function useUserPosts(userId: string | null): import("@tanstack/react-query").UseInfiniteQueryResult<InfiniteData<FeedPost[], unknown>, Error>;
+/** Our own stable community uid, resolved once and cached for the app session. */
+export declare function useMyUid(): string | null;
+/** Profile edits refresh everything derived from a profile row: the profile
+ * itself, plus the handle/avatar shown on every cached feed and thread. */
+export declare function useUpdateProfile(): import("@tanstack/react-query").UseMutationResult<UpdateProfileResult, Error, UpdateProfileInput, unknown>;
+type PostResult = {
+    id: string;
+    verdict: ModerationVerdict;
+};
+/**
+ * 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.
+ */
+export declare function useCreatePost(): import("@tanstack/react-query").UseMutationResult<PostResult, Error, {
+    topic: string;
+    text: string;
+    authorName: string;
+    pollOptions?: string[];
+}, {
+    tempId: string;
+}>;
+/** Optimistic comment creation, same reconcile-in-place model as posts. */
+export declare function useCreateComment(): import("@tanstack/react-query").UseMutationResult<PostResult, Error, {
+    postId: string;
+    text: string;
+    authorName: string;
+}, {
+    tempId: string;
+}>;
+/** Optimistic like toggle across all cached feed pages (every topic filter). */
+export declare function useToggleLike(): import("@tanstack/react-query").UseMutationResult<void, Error, {
+    postId: string;
+    liked: boolean;
+    topic: string | null;
+}, {
+    previous: [readonly unknown[], InfiniteData<FeedPost[], unknown> | undefined][];
+}>;
+/**
+ * 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.
+ */
+export declare function useVotePoll(): import("@tanstack/react-query").UseMutationResult<void, Error, {
+    postId: string;
+    optionId: string;
+}, PostCacheSnapshot>;
+/**
+ * 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.
+ */
+export declare function useReactToPost(): import("@tanstack/react-query").UseMutationResult<void, Error, {
+    postId: string;
+}, PostCacheSnapshot & {
+    alreadyReacted: boolean;
+}>;
+export declare function useReport(): import("@tanstack/react-query").UseMutationResult<void, Error, ReportInput, unknown>;
+/** Blocking re-filters everything: drop every community cache and refetch. */
+export declare function useBlockUser(): import("@tanstack/react-query").UseMutationResult<void, Error, {
+    userId: string;
+}, unknown>;
+export declare function useDeleteContent(): import("@tanstack/react-query").UseMutationResult<void, Error, {
+    kind: "post" | "comment";
+    id: string;
+    postId: string;
+}, unknown>;
+export {};