@rocapine/community-core 0.1.0

package/lib/provider.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement, type ReactNode } from "react";
+import { type CommunityConfig, type ResolvedCommunityConfig } from "./config";
+export declare function CommunityProvider(props: {
+    config: CommunityConfig;
+    children: ReactNode;
+}): ReactElement;
+export declare function useCommunityConfig(): ResolvedCommunityConfig;

package/lib/provider.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunityProvider = CommunityProvider;
+exports.useCommunityConfig = useCommunityConfig;
+const react_1 = require("react");
+const config_1 = require("./config");
+const schema_check_1 = require("./schema-check");
+const CommunityConfigContext = (0, react_1.createContext)(null);
+function CommunityProvider(props) {
+    const { config, children } = props;
+    const resolved = (0, react_1.useMemo)(() => (0, config_1.resolveConfig)(config), [config]);
+    (0, react_1.useEffect)(() => {
+        void (0, schema_check_1.checkSchemaVersion)(resolved);
+    }, [resolved]);
+    return (<CommunityConfigContext.Provider value={resolved}>{children}</CommunityConfigContext.Provider>);
+}
+function useCommunityConfig() {
+    const resolved = (0, react_1.useContext)(CommunityConfigContext);
+    if (!resolved) {
+        throw new Error("CommunityProvider is missing");
+    }
+    return resolved;
+}

package/lib/schema-check.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedCommunityConfig } from "./config";
+/** Bump whenever the SDK's expected `community_meta` shape changes. */
+export declare const REQUIRED_SCHEMA_VERSION = 1;
+/**
+ * Read path, exported separately from the `__DEV__` gate so tests — where
+ * `__DEV__` is `undefined` under vitest/Node, not `false` — can exercise the
+ * four behaviors (mismatch warns, match is silent, query error is silent,
+ * degraded mode is silent) directly. `checkSchemaVersion` below is the only
+ * symbol wired into `CommunityProvider`; this one stays package-internal
+ * (not re-exported from `index.ts`).
+ */
+export declare function checkSchemaVersionUnguarded(cfg: ResolvedCommunityConfig): Promise<void>;
+/**
+ * Dev-only entry point, called once from `CommunityProvider`'s mount effect.
+ * No-ops outside dev (production RN bundles define `__DEV__ === false`; a
+ * plain Node/test environment leaves it `undefined`, which also no-ops here —
+ * see `checkSchemaVersionUnguarded` for how tests reach the read path).
+ */
+export declare function checkSchemaVersion(cfg: ResolvedCommunityConfig): Promise<void>;

package/lib/schema-check.js

@@ -0,0 +1,52 @@
+"use strict";
+// Dev-only schema drift check. Reads the single `community_meta.schema_version`
+// row and warns when it doesn't match what this SDK version expects, so a host
+// developer notices a stale backend migration during development. This is a
+// diagnostic aid, not a runtime gate — it must never throw and must never run
+// in production (RN's global `__DEV__` gate, same convention every host app
+// already relies on for dev-only logging).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_SCHEMA_VERSION = void 0;
+exports.checkSchemaVersionUnguarded = checkSchemaVersionUnguarded;
+exports.checkSchemaVersion = checkSchemaVersion;
+/** Bump whenever the SDK's expected `community_meta` shape changes. */
+exports.REQUIRED_SCHEMA_VERSION = 1;
+/**
+ * Read path, exported separately from the `__DEV__` gate so tests — where
+ * `__DEV__` is `undefined` under vitest/Node, not `false` — can exercise the
+ * four behaviors (mismatch warns, match is silent, query error is silent,
+ * degraded mode is silent) directly. `checkSchemaVersion` below is the only
+ * symbol wired into `CommunityProvider`; this one stays package-internal
+ * (not re-exported from `index.ts`).
+ */
+async function checkSchemaVersionUnguarded(cfg) {
+    const client = cfg.supabase;
+    if (!client)
+        return; // degraded mode (no backend configured) — nothing to check
+    try {
+        const { data, error } = await client
+            .from("community_meta")
+            .select("schema_version")
+            .maybeSingle();
+        if (error)
+            return; // e.g. table doesn't exist yet on this backend — silent
+        const version = data?.schema_version;
+        if (version !== undefined && version !== exports.REQUIRED_SCHEMA_VERSION) {
+            console.warn(`[@rocapine/community-core] community_meta.schema_version is ${version}, this SDK expects ${exports.REQUIRED_SCHEMA_VERSION}. Run the latest backend migrations.`);
+        }
+    }
+    catch {
+        // network error or unexpected client shape — never throw from a dev diagnostic
+    }
+}
+/**
+ * Dev-only entry point, called once from `CommunityProvider`'s mount effect.
+ * No-ops outside dev (production RN bundles define `__DEV__ === false`; a
+ * plain Node/test environment leaves it `undefined`, which also no-ops here —
+ * see `checkSchemaVersionUnguarded` for how tests reach the read path).
+ */
+async function checkSchemaVersion(cfg) {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+        await checkSchemaVersionUnguarded(cfg);
+    }
+}

package/lib/service.d.ts

@@ -0,0 +1,147 @@
+import type { ResolvedCommunityConfig } from "./config";
+import { type CommunityProfile, type FeedPost, type ReactionData, type ThreadComment } from "./models";
+/**
+ * Appends `extraPostColumns` (if any) to the posts feed select. Pure and
+ * exported so it's unit-testable without a Supabase client. Invalid column
+ * names are dropped with a `console.warn` rather than failing the query.
+ */
+export declare function buildFeedSelect(extraPostColumns?: readonly string[]): string;
+/**
+ * Batched reaction state for one page: count + last reactor's display name + my-reaction
+ * flag, all from the single security-definer `post_reaction_summary` RPC (the backend
+ * already resolves "did I react" server-side, so unlike the mold's prayer batching this
+ * needs no second query). Gated on `cfg.modules.reaction`; a missing/erroring RPC (e.g.
+ * the reaction module's migration not installed yet) degrades to no reaction data instead
+ * of taking the whole feed down.
+ */
+export declare function fetchReactionSummaries(cfg: ResolvedCommunityConfig, postIds: string[]): Promise<ReactionData>;
+/**
+ * One feed page, newest first. RLS already excludes other users' hidden and
+ * blocked-author content; we only exclude our own soft-deleted posts.
+ */
+export declare function fetchFeedPage(cfg: ResolvedCommunityConfig, opts?: {
+    topic?: string;
+    cursor?: number;
+}): Promise<FeedPost[]>;
+/**
+ * Count of visible posts newer than `sinceIso`, excluding my own, for the
+ * given topic. RLS already excludes blocked authors and hidden/deleted rows.
+ * `topic` is beyond the brief's literal signature but kept (both source apps
+ * take it) so a topic-filtered feed's "N new posts" pill stays accurate.
+ */
+export declare function countNewPosts(cfg: ResolvedCommunityConfig, sinceIso: string, topic?: string): Promise<number>;
+/** A single profile by id, e.g. for the profile page header. */
+export declare function fetchProfile(cfg: ResolvedCommunityConfig, userId: string): Promise<CommunityProfile>;
+/**
+ * One user's posts, newest first (no pinned ordering — a profile page is
+ * strictly chronological). Same visibility rules as the main feed, same
+ * page-index cursor as `fetchFeedPage` (product decision, reversing the
+ * earlier single-page scope cut).
+ */
+export declare function fetchUserPosts(cfg: ResolvedCommunityConfig, userId: string, opts?: {
+    cursor?: number;
+}): Promise<FeedPost[]>;
+/**
+ * Full-text-ish search over visible post content (newest first), same
+ * page-index cursor as `fetchFeedPage` (product decision, reversing the
+ * earlier single-page scope cut).
+ */
+export declare function searchPosts(cfg: ResolvedCommunityConfig, query: string, opts?: {
+    cursor?: number;
+}): Promise<FeedPost[]>;
+/**
+ * Note: `cfg.feed.extraPostColumns`/`transformPost` do NOT apply here — this
+ * queries `comments`, not `posts` (the thread's parent post is passed in by
+ * the caller from an already-fetched, already-transformed `FeedPost`, not
+ * re-fetched).
+ */
+export declare function fetchThread(cfg: ResolvedCommunityConfig, postId: string): Promise<ThreadComment[]>;
+/** Verdict returned by the synchronous moderate-one Edge Function. */
+export type ModerationVerdict = {
+    status: "published" | "rejected" | "pending";
+    reason?: string;
+};
+export type CreatePostInput = {
+    topic: string;
+    body: string;
+    pollOptions?: string[];
+};
+/**
+ * Insert a post as 'pending' (invisible to others until moderated). Returns id.
+ * With pollOptions, the post and its options are created transactionally by
+ * the create_poll_post RPC (security invoker, same RLS as a plain insert);
+ * that branch is gated on `cfg.modules.polls`.
+ */
+export declare function createPost(cfg: ResolvedCommunityConfig, input: CreatePostInput): Promise<string>;
+/**
+ * Cast or change my vote: one row per (post, user), upsert swaps the option.
+ * `optionId` is the poll option's row id (matching `FeedPoll.myOptionId` /
+ * `applyPollVote`'s optimistic-update contract from Task 3), not a numeric
+ * index — see the task report for this naming call against the brief.
+ * Gated on `cfg.modules.polls` for consistent DX with the reaction module.
+ */
+export declare function votePoll(cfg: ResolvedCommunityConfig, postId: string, optionId: string): Promise<void>;
+/** Insert a comment as 'pending'. Returns id. */
+export declare function createComment(cfg: ResolvedCommunityConfig, postId: string, body: string): Promise<string>;
+/** Run synchronous moderation on a just-created pending post/comment. */
+export declare function moderateOne(cfg: ResolvedCommunityConfig, input: {
+    kind: "post" | "comment";
+    id: string;
+}): Promise<ModerationVerdict>;
+export declare function setLike(cfg: ResolvedCommunityConfig, postId: string, on: boolean): Promise<void>;
+/**
+ * `setPrayed` generalized to `setReaction`: insert my private, non-retractable
+ * reaction row (rows are never deleted — see spec §6). Gated on `cfg.modules.reaction`.
+ */
+export declare function setReaction(cfg: ResolvedCommunityConfig, postId: string): Promise<void>;
+export type ReportReason = "spam" | "harassment" | "hate" | "inappropriate" | "other";
+export interface ReportInput {
+    reportedUserId: string;
+    postId?: string;
+    commentId?: string;
+    reason: ReportReason;
+    details?: string;
+}
+export declare function reportContent(cfg: ResolvedCommunityConfig, input: ReportInput): Promise<void>;
+export declare function blockUser(cfg: ResolvedCommunityConfig, blockedId: string): Promise<void>;
+export declare function deleteOwnPost(cfg: ResolvedCommunityConfig, postId: string): Promise<void>;
+export declare function deleteOwnComment(cfg: ResolvedCommunityConfig, commentId: string): Promise<void>;
+/**
+ * `avatarUrl` here is actually the Storage *path* returned by `uploadAvatar`
+ * (mold field name `avatarPath`) — kept as `avatarUrl` per the brief's produced
+ * signature and translated to the Edge Function's expected `avatarPath` body
+ * key at the call site below.
+ */
+export type UpdateProfileInput = {
+    handle?: string;
+    bio?: string;
+    avatarUrl?: string;
+};
+export type UpdateProfileResult = {
+    status: "ok";
+    handle: string | null;
+    bio: string | null;
+    avatarUrl: string | null;
+} | {
+    status: "rejected";
+    field: "handle" | "bio" | "avatar";
+    reason?: string;
+} | {
+    status: "error";
+    code?: "handle_taken";
+    error?: string;
+};
+/**
+ * The only write path for handle/bio/avatar — moderated server-side by the
+ * `update-profile` Edge Function. `invoke` treats any non-2xx as `error`; a
+ * `FunctionsHttpError` carries the typed JSON body (e.g. `handle_taken`) on
+ * its `context` response, other error kinds mean the request never landed.
+ */
+export declare function updateProfile(cfg: ResolvedCommunityConfig, input: UpdateProfileInput): Promise<UpdateProfileResult>;
+/**
+ * Upload a JPEG avatar to the `avatars` bucket from a local file URI. Returns
+ * the storage path. Takes a `fileUri` (not a base64 string, unlike the mold)
+ * so the core has no Hermes/`atob` dependency — `fetch` on a `file://` URI is
+ * the portable way to read local bytes in React Native.
+ */
+export declare function uploadAvatar(cfg: ResolvedCommunityConfig, fileUri: string): Promise<string>;