Add blog post feature: migrations, API helpers, admin tools, and web pages for listing, viewing, and editing posts.

Author: MartinBraquet

android/app/build.gradle

@@ -11,7 +11,7 @@ android {
         applicationId "com.compassconnections.app"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 158
+        versionCode 159
         versionName "1.40.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         aaptOptions {

backend/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compass/api",
-  "version": "1.66.1",
+  "version": "1.67.0",
   "private": true,
   "description": "Backend API endpoints",
   "main": "src/serve.ts",

backend/api/src/app.ts

@@ -58,6 +58,7 @@ import {blockUser, unblockUser} from './block-user'
 import {cancelEvent} from './cancel-event'
 import {cancelRsvp} from './cancel-rsvp'
 import {getCompatibleProfilesHandler} from './compatible-profiles'
+import {createBlogPost} from './create-blog-post'
 import {createBookmarkedSearch} from './create-bookmarked-search'
 import {createComment} from './create-comment'
 import {createCompatibilityQuestion} from './create-compatibility-question'
@@ -71,6 +72,9 @@ import {createUserAndProfile} from './create-user-and-profile'
 import {deleteBookmarkedSearch} from './delete-bookmarked-search'
 import {deleteCompatibilityAnswer} from './delete-compatibility-answer'
 import {deleteMe} from './delete-me'
+import {getBlogPost} from './get-blog-post'
+import {getBlogPosts} from './get-blog-posts'
+import {getBlogPostsAdmin} from './get-blog-posts-admin'
 import {getCompatibilityQuestions} from './get-compatibililty-questions'
 import {getConnectionInterestsEndpoint} from './get-connection-interests'
 import {getCurrentPrivateUser} from './get-current-private-user'
@@ -115,6 +119,7 @@ import {starProfile} from './star-profile'
 import {stats} from './stats'
 import {transcribeAudio} from './transcribe-audio'
 import {unsubscribe} from './unsubscribe'
+import {updateBlogPost} from './update-blog-post'
 import {updateEvent} from './update-event'
 import {updateMe} from './update-me'
 import {updateNotifSettings} from './update-notif-setting'
@@ -590,6 +595,11 @@ Commit: ${git.revision} (${git.commitDate})`,
       description:
         'The public testimonials wall, plus the moderation endpoints that decide what appears on it',
     },
+    {
+      name: 'Blog',
+      description:
+        'The Compass blog: the public index and post reads, plus the admin endpoints that write and publish them',
+    },
     {
       name: 'Spotlights',
       description:
@@ -659,6 +669,11 @@ const handlers: {[k in APIPath]: APIHandler<k>} = {
   'get-testimonials-mod': getTestimonialsMod,
   'create-testimonial': createTestimonial,
   'update-testimonial-status': updateTestimonialStatus,
+  'get-blog-posts': getBlogPosts,
+  'get-blog-post': getBlogPost,
+  'get-blog-posts-admin': getBlogPostsAdmin,
+  'create-blog-post': createBlogPost,
+  'update-blog-post': updateBlogPost,
   'get-spotlights': getSpotlights,
   'get-spotlights-admin': getSpotlightsAdmin,
   'create-spotlight': createSpotlight,

backend/api/src/create-blog-post.ts

@@ -0,0 +1,72 @@
+import {BLOG_FROM, BLOG_FULL_COLUMNS, BlogQueryRow, toAdminBlogPost} from 'api/helpers/blog'
+import {APIErrors, APIHandler} from 'api/helpers/endpoint'
+import {MAX_BLOG_CONTENT_LENGTH} from 'common/blog/blog'
+import {parseJsonContentToText} from 'common/util/parse'
+import {throwErrorIfNotAdmin} from 'shared/helpers/auth'
+import {createSupabaseDirectClient} from 'shared/supabase/init'
+
+/**
+ * Create a post. Always as a `draft`, never published, and never broadcast.
+ *
+ * Publishing is a second, separate call to `update-blog-post`, for the same reason creating a
+ * spotlight cannot publish one: the thing that makes a post public also mails every member, and an
+ * endpoint that can do that as a side effect of "save what I just typed" is one mis-click away from
+ * sending an unfinished draft to everybody.
+ *
+ * Admins only, not mods — publishing under the Compass name is an editorial act, not a moderation
+ * one. Same split as `create-spotlight`.
+ */
+export const createBlogPost: APIHandler<'create-blog-post'> = async (props, auth) => {
+  await throwErrorIfNotAdmin(auth.uid)
+
+  const {slug, title, excerpt, content, coverImageUrl} = props
+
+  // Flattened once, here, so that every consumer of `content_text` — reading time today, search
+  // later — reads the same string, and none of them has to know how to walk a ProseMirror tree.
+  const contentText = parseJsonContentToText(content ?? null)
+  if (contentText.length > MAX_BLOG_CONTENT_LENGTH) {
+    throw APIErrors.badRequest(
+      `That post is ${contentText.length} characters; the limit is ${MAX_BLOG_CONTENT_LENGTH}`,
+    )
+  }
+
+  const pg = createSupabaseDirectClient()
+
+  // The unique index on `slug` is the real guard — two admins creating the same slug at once is not
+  // a race we can win with a pre-check — so this catches it after the fact and reports it in terms of
+  // what the admin did rather than as a constraint name.
+  const existing = await pg.oneOrNone<{status: string}>(
+    `select status from blog_posts where slug = $(slug)`,
+    {slug},
+  )
+  if (existing) {
+    throw APIErrors.badRequest(
+      `The slug “${slug}” is already taken by a ${existing.status} post — edit that one, or pick another slug`,
+    )
+  }
+
+  const inserted = await pg.one<{id: string}>(
+    `insert into blog_posts (slug, title, excerpt, content, content_text, cover_image_url, author_id)
+     values ($(slug), $(title), $(excerpt), $(content), $(contentText), $(coverImageUrl), $(authorId))
+     returning id`,
+    {
+      slug,
+      title,
+      excerpt: excerpt?.trim() || null,
+      content: content ?? {},
+      contentText,
+      coverImageUrl: coverImageUrl || null,
+      authorId: auth.uid,
+    },
+  )
+
+  // Re-read through the byline join rather than returning the inserted row, so the admin page gets
+  // exactly the same shape as `get-blog-posts-admin` and does not need a second code path for the
+  // row it just created.
+  const row = await pg.one<BlogQueryRow>(
+    `select ${BLOG_FULL_COLUMNS} ${BLOG_FROM} where b.id = $(id)`,
+    {id: inserted.id},
+  )
+
+  return {post: toAdminBlogPost(row)}
+}

backend/api/src/get-blog-post.ts

@@ -0,0 +1,28 @@
+import {BLOG_FROM, BLOG_FULL_COLUMNS, BlogQueryRow, toBlogPost} from 'api/helpers/blog'
+import {APIHandler} from 'api/helpers/endpoint'
+import {createSupabaseDirectClient} from 'shared/supabase/init'
+
+/**
+ * One post by slug, body included.
+ *
+ * `status = 'published'` is in the query rather than checked afterwards, so a draft is not merely
+ * hidden by the page — it never reaches the response, and guessing the slug of an unpublished post
+ * gets you the same `null` as guessing a slug that was never used.
+ *
+ * Answers `null` rather than 404ing, because the caller is a statically-generated page that has its
+ * own not-found state to render, and because this response is CDN-cached: a 404 body cached under a
+ * slug that is published minutes later is worse than a cached `null` the page can retry past.
+ */
+export const getBlogPost: APIHandler<'get-blog-post'> = async (props) => {
+  const pg = createSupabaseDirectClient()
+
+  const row = await pg.oneOrNone<BlogQueryRow>(
+    `select ${BLOG_FULL_COLUMNS}
+     ${BLOG_FROM}
+     where b.slug = $(slug)
+       and b.status = 'published'`,
+    {slug: props.slug},
+  )
+
+  return {post: row ? toBlogPost(row) : null}
+}

backend/api/src/get-blog-posts-admin.ts

@@ -0,0 +1,29 @@
+import {BLOG_FROM, BLOG_FULL_COLUMNS, BlogQueryRow, toAdminBlogPost} from 'api/helpers/blog'
+import {APIHandler} from 'api/helpers/endpoint'
+import {throwErrorIfNotAdmin} from 'shared/helpers/auth'
+import {createSupabaseDirectClient} from 'shared/supabase/init'
+
+/**
+ * Every post in every state, bodies included, for `/admin/blog`.
+ *
+ * Bodies are included here where the public list omits them: the admin page is an editor, and every
+ * row on it is one click away from being opened in the rich-text editor. Fetching them lazily would
+ * put a spinner inside each post's edit box for no benefit — this list is a handful of rows read by
+ * a handful of people.
+ *
+ * Drafts sort first: they are the only group that represents work owed.
+ */
+export const getBlogPostsAdmin: APIHandler<'get-blog-posts-admin'> = async (_, auth) => {
+  await throwErrorIfNotAdmin(auth.uid)
+
+  const pg = createSupabaseDirectClient()
+
+  const rows = await pg.any<BlogQueryRow>(
+    `select ${BLOG_FULL_COLUMNS}
+     ${BLOG_FROM}
+     order by case b.status when 'draft' then 0 when 'published' then 1 else 2 end,
+              coalesce(b.published_time, b.created_time) desc`,
+  )
+
+  return {posts: rows.map(toAdminBlogPost)}
+}

backend/api/src/get-blog-posts.ts

@@ -0,0 +1,28 @@
+import {BLOG_FROM, BLOG_SUMMARY_COLUMNS, BlogQueryRow, toBlogPostSummary} from 'api/helpers/blog'
+import {APIHandler} from 'api/helpers/endpoint'
+import {BLOG_POSTS_PER_PAGE} from 'common/blog/blog'
+import {createSupabaseDirectClient} from 'shared/supabase/init'
+
+/**
+ * The `/blog` index. Published rows only — `draft` and `archived` never leave the server.
+ *
+ * Bodies are excluded. A blog index that shipped every post's full rich-text document would grow
+ * without bound as the blog does, and the list renders none of it.
+ *
+ * Ordered by `published_time`, not `created_time`: those differ for anything written days before it
+ * went out, and the date on the card is the one readers reason about.
+ */
+export const getBlogPosts: APIHandler<'get-blog-posts'> = async (props) => {
+  const pg = createSupabaseDirectClient()
+
+  const rows = await pg.any<BlogQueryRow>(
+    `select ${BLOG_SUMMARY_COLUMNS}
+     ${BLOG_FROM}
+     where b.status = 'published'
+     order by b.published_time desc nulls last, b.id desc
+     limit $(limit) offset $(offset)`,
+    {limit: props.limit ?? BLOG_POSTS_PER_PAGE, offset: props.offset ?? 0},
+  )
+
+  return {posts: rows.map(toBlogPostSummary)}
+}

backend/api/src/get-spotlights-admin.ts

@@ -60,6 +60,7 @@ export const getSpotlightsAdmin: APIHandler<'get-spotlights-admin'> = async (_,
         // The whole document, unsliced: the admin is reading for the one good sentence, and it is
         // rarely in the first paragraph. Capped instead by the candidate list's own `limit 200`.
         bio: row.bio,
+        socialConsent: row.social_media_consent,
       }),
     ),
   }

backend/api/src/helpers/blog.ts

@@ -0,0 +1,86 @@
+import {type JSONContent} from '@tiptap/core'
+import {
+  AdminBlogPost,
+  BlogAuthor,
+  BlogPost,
+  BlogPostStatus,
+  BlogPostSummary,
+  getReadingMinutes,
+} from 'common/blog/blog'
+
+/**
+ * The columns as they come back from `blog_posts`, joined to `users` for the byline.
+ *
+ * The author fields are prefixed rather than nested because pg-promise returns a flat row; they are
+ * all null when `author_id` is null (the account is gone) and the mappers below collapse that to a
+ * missing byline rather than to a byline made of nulls.
+ */
+export type BlogQueryRow = {
+  id: string
+  slug: string
+  title: string
+  excerpt: string | null
+  content: JSONContent | string | null
+  content_text: string
+  cover_image_url: string | null
+  status: BlogPostStatus
+  author_id: string | null
+  author_name: string | null
+  author_username: string | null
+  author_avatar_url: string | null
+  published_time: string | null
+  notified_time: string | null
+  created_time: string
+  updated_time: string
+}
+
+/**
+ * Everything but the body. `content_text` is still selected — the reading-time estimate on the list
+ * card is computed from it, and it is a fraction of the size of the JSONB document.
+ */
+export const BLOG_SUMMARY_COLUMNS = `b.id, b.slug, b.title, b.excerpt, b.content_text,
+                                     b.cover_image_url, b.status, b.author_id, b.published_time,
+                                     b.notified_time, b.created_time, b.updated_time,
+                                     u.name       as author_name,
+                                     u.username   as author_username,
+                                     u.avatar_url as author_avatar_url`
+
+export const BLOG_FULL_COLUMNS = `${BLOG_SUMMARY_COLUMNS}, b.content`
+
+/** The join every blog read uses. Left, so a post whose author deleted their account still loads. */
+export const BLOG_FROM = `from blog_posts b left join users u on u.id = b.author_id`
+
+const toAuthor = (row: BlogQueryRow): BlogAuthor | null =>
+  row.author_id === null || row.author_name === null || row.author_username === null
+    ? null
+    : {
+        name: row.author_name,
+        username: row.author_username,
+        avatarUrl: row.author_avatar_url,
+      }
+
+export const toBlogPostSummary = (row: BlogQueryRow): BlogPostSummary => ({
+  id: Number(row.id),
+  slug: row.slug,
+  title: row.title,
+  excerpt: row.excerpt,
+  coverImageUrl: row.cover_image_url,
+  author: toAuthor(row),
+  publishedTime: row.published_time === null ? null : new Date(row.published_time).toISOString(),
+  readingMinutes: getReadingMinutes(row.content_text ?? ''),
+})
+
+export const toBlogPost = (row: BlogQueryRow): BlogPost => ({
+  ...toBlogPostSummary(row),
+  // `{}` is the column default for a post created before anything was typed into the editor. Sent as
+  // an empty document rather than as `{}`, which the TipTap renderer treats as a malformed node.
+  content: row.content && Object.keys(row.content).length > 0 ? row.content : '',
+})
+
+export const toAdminBlogPost = (row: BlogQueryRow): AdminBlogPost => ({
+  ...toBlogPost(row),
+  status: row.status,
+  notifiedTime: row.notified_time === null ? null : new Date(row.notified_time).toISOString(),
+  createdTime: new Date(row.created_time).toISOString(),
+  updatedTime: new Date(row.updated_time).toISOString(),
+})

backend/api/src/helpers/spotlights.ts

@@ -91,6 +91,7 @@ export type SpotlightSourceRow = {
   /** The TipTap document. `bio_text` is its flattened form, and reads like one when rendered. */
   bio: JSONContent | string | null
   spotlight_consent: boolean
+  social_media_consent: boolean
   visibility: string
 }
 
@@ -104,6 +105,7 @@ export const SPOTLIGHT_SOURCE_SELECT = `select p.user_id,
                                                p.headline,
                                                p.bio,
                                                p.spotlight_consent,
+                                               p.social_media_consent,
                                                p.visibility
                                         from profiles p
                                                  join users u on u.id = p.user_id`