feat: add typed QuranReflect post helpers

.changeset/typed-quranreflect-posts.md

@@ -0,0 +1,5 @@
+---
+"@quranjs/api": minor
+---
+
+Add typed QuranReflect post helpers for create, update, and get operations.

packages/api/src/generated/specs/operation-catalog.json

@@ -1001,6 +1001,11 @@
           "method": "post",
           "path": "/v1/comments"
         },
+        "commentsControllerEdit": {
+          "auth": "user",
+          "method": "patch",
+          "path": "/v1/comments/{id}"
+        },
         "commentsControllerDeleteComment": {
           "auth": "user",
           "method": "get",

packages/api/src/generated/specs/public-operation-catalog.json

@@ -518,6 +518,11 @@
           "method": "post",
           "path": "/v1/comments"
         },
+        "commentsControllerEdit": {
+          "auth": "user",
+          "method": "patch",
+          "path": "/v1/comments/{id}"
+        },
         "commentsControllerDeleteComment": {
           "auth": "user",
           "method": "get",

packages/api/src/runtime/create-client.ts

@@ -20,6 +20,8 @@ import { operationCatalog } from "@/generated/contracts";
 import { toUserSession } from "@/lib/http-utils";
 import { createGeneratedGroups, createRawClient } from "@/lib/runtime-utils";
 import { replacePathParams } from "@/lib/url";
+import { createQuranReflectPostsFacade } from "@/runtime/quran-reflect-posts";
+import type { QuranReflectPostsFacade } from "@/runtime/quran-reflect-posts";
 import { QuranAnswers } from "@/sdk/answers";
 import { QuranAudio } from "@/sdk/audio";
 import { QuranChapters } from "@/sdk/chapters";
@@ -36,7 +38,7 @@ type RawOperation = (request?: OperationRequest) => Promise<unknown>;
 type GeneratedGroup = Record<string, RawOperation>;
 type QuranReflectFacade = {
   comments: GeneratedGroup;
-  posts: GeneratedGroup;
+  posts: QuranReflectPostsFacade;
   raw: Record<string, RawOperation>;
   rooms: GeneratedGroup;
   tags: GeneratedGroup;
@@ -203,7 +205,10 @@ const createQuranReflectFacade = (
 
   return {
     comments: generatedGroups.comments ?? {},
-    posts: generatedGroups.posts ?? {},
+    posts: createQuranReflectPostsFacade(
+      generatedGroups.posts ?? {},
+      createUserServiceRequest(fetcher, "quranReflect"),
+    ),
     raw,
     rooms: generatedGroups.rooms ?? {},
     tags: generatedGroups.tags ?? {},

packages/api/src/runtime/create-public-client.ts

@@ -10,13 +10,15 @@ import { publicOperationCatalog } from "@/generated/public-contracts";
 import { toUserSession } from "@/lib/http-utils";
 import { createGeneratedGroups, createRawClient } from "@/lib/runtime-utils";
 import { replacePathParams } from "@/lib/url";
+import { createQuranReflectPostsFacade } from "@/runtime/quran-reflect-posts";
+import type { QuranReflectPostsFacade } from "@/runtime/quran-reflect-posts";
 import { PublicQuranFetcher } from "@/sdk/public-fetcher";
 
 type RawOperation = (request?: OperationRequest) => Promise<unknown>;
 type GeneratedGroup = Record<string, RawOperation>;
 type QuranReflectFacade = {
   comments: GeneratedGroup;
-  posts: GeneratedGroup;
+  posts: QuranReflectPostsFacade;
   raw: Record<string, RawOperation>;
   rooms: GeneratedGroup;
   tags: GeneratedGroup;
@@ -188,7 +190,10 @@ const createQuranReflectFacade = (
 
   return {
     comments: generatedGroups.comments ?? {},
-    posts: generatedGroups.posts ?? {},
+    posts: createQuranReflectPostsFacade(
+      generatedGroups.posts ?? {},
+      createUserServiceRequest(fetcher, "quranReflect"),
+    ),
     raw,
     rooms: generatedGroups.rooms ?? {},
     tags: generatedGroups.tags ?? {},

packages/api/src/runtime/quran-reflect-posts.ts

@@ -0,0 +1,156 @@
+import type {
+  ApiParams,
+  CreateQuranReflectPostPayload,
+  OperationRequest,
+  QuranReflectPost,
+  QuranReflectPostMutationResponse,
+  UpdateQuranReflectPostPayload,
+} from "@/types";
+
+type RawOperation = (request?: OperationRequest) => Promise<unknown>;
+type GeneratedGroup = Record<string, RawOperation>;
+
+export type QuranReflectPostCreateOperationRequest = Omit<
+  OperationRequest,
+  "body"
+> & {
+  body: {
+    post: CreateQuranReflectPostPayload;
+  };
+};
+
+export type QuranReflectPostUpdateOperationRequest = Omit<
+  OperationRequest,
+  "body" | "path"
+> & {
+  body: UpdateQuranReflectPostPayload;
+  path: {
+    id: string | number;
+  };
+};
+
+export type QuranReflectPostGetOperationRequest = Omit<
+  OperationRequest,
+  "path"
+> & {
+  path: {
+    id: string | number;
+  };
+};
+
+type CreateQuranReflectPost = {
+  (
+    payload: CreateQuranReflectPostPayload,
+  ): Promise<QuranReflectPostMutationResponse>;
+  (
+    request: QuranReflectPostCreateOperationRequest,
+  ): Promise<QuranReflectPostMutationResponse>;
+  (request?: OperationRequest): Promise<unknown>;
+};
+
+type UpdateQuranReflectPost = {
+  (
+    id: string | number,
+    payload: UpdateQuranReflectPostPayload,
+  ): Promise<QuranReflectPostMutationResponse>;
+  (
+    request: QuranReflectPostUpdateOperationRequest,
+  ): Promise<QuranReflectPostMutationResponse>;
+  (request?: OperationRequest): Promise<unknown>;
+};
+
+type GetQuranReflectPost = {
+  (id: string | number, query?: ApiParams): Promise<QuranReflectPost>;
+  (request: QuranReflectPostGetOperationRequest): Promise<QuranReflectPost>;
+  (request?: OperationRequest): Promise<unknown>;
+};
+
+export type QuranReflectPostsFacade = GeneratedGroup & {
+  create: CreateQuranReflectPost;
+  get: GetQuranReflectPost;
+  update: UpdateQuranReflectPost;
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+const isCreatePayload = (value: unknown): value is CreateQuranReflectPostPayload => {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  return (
+    typeof value["body"] === "string" &&
+    typeof value["draft"] === "boolean" &&
+    Array.isArray(value["references"]) &&
+    Array.isArray(value["mentions"])
+  );
+};
+
+export const createQuranReflectPostsFacade = (
+  generatedPosts: GeneratedGroup,
+  request: (
+    method: "GET" | "PATCH" | "POST",
+    path: string,
+    operationRequest?: OperationRequest,
+  ) => Promise<unknown>,
+): QuranReflectPostsFacade => {
+  const create: CreateQuranReflectPost = ((
+    payloadOrRequest:
+      | CreateQuranReflectPostPayload
+      | QuranReflectPostCreateOperationRequest,
+  ) => {
+    if (isCreatePayload(payloadOrRequest)) {
+      return request("POST", "/v1/posts", {
+        body: {
+          post: payloadOrRequest,
+        },
+      }) as Promise<QuranReflectPostMutationResponse>;
+    }
+
+    return request("POST", "/v1/posts", payloadOrRequest) as Promise<
+      QuranReflectPostMutationResponse
+    >;
+  }) as CreateQuranReflectPost;
+
+  const update: UpdateQuranReflectPost = ((
+    idOrRequest: string | number | QuranReflectPostUpdateOperationRequest,
+    payload?: UpdateQuranReflectPostPayload,
+  ) => {
+    if (payload !== undefined) {
+      return request("PATCH", "/v1/posts/{id}", {
+        body: payload,
+        path: { id: idOrRequest as string | number },
+      }) as Promise<QuranReflectPostMutationResponse>;
+    }
+
+    return request(
+      "PATCH",
+      "/v1/posts/{id}",
+      idOrRequest as QuranReflectPostUpdateOperationRequest,
+    ) as Promise<QuranReflectPostMutationResponse>;
+  }) as UpdateQuranReflectPost;
+
+  const get: GetQuranReflectPost = ((
+    idOrRequest: string | number | QuranReflectPostGetOperationRequest,
+    query?: ApiParams,
+  ) => {
+    if (typeof idOrRequest === "string" || typeof idOrRequest === "number") {
+      return request("GET", "/v1/posts/{id}", {
+        path: { id: idOrRequest },
+        query,
+      }) as Promise<QuranReflectPost>;
+    }
+
+    return request("GET", "/v1/posts/{id}", idOrRequest) as Promise<
+      QuranReflectPost
+    >;
+  }) as GetQuranReflectPost;
+
+  return {
+    ...generatedPosts,
+    create,
+    get,
+    update,
+  };
+};

packages/api/src/types/index.ts

@@ -125,3 +125,4 @@ export * from "./common/rub-number";
 export * from "./api";
 export * from "./BaseApiParams";
 export * from "./quran-client";
+export * from "./quran-reflect";

packages/api/src/types/quran-client.ts

@@ -1,4 +1,4 @@
-import { AuthService } from "@/generated/public-contracts";
+import type { AuthService } from "@/generated/public-contracts";
 
 import type { ApiParams, BaseApiParams } from "./BaseApiParams";
 

packages/api/src/types/quran-reflect.ts

@@ -0,0 +1,69 @@
+export interface QuranReflectPostReference {
+  chapterId: number;
+  from: number;
+  to: number;
+  id?: string;
+}
+
+export interface QuranReflectPostMention {
+  marker: string;
+  userId: string;
+  displayName: string;
+}
+
+export type QuranReflectRoomPostStatus = 0 | 1 | 2;
+
+export interface CreateQuranReflectPostPayload {
+  body: string;
+  draft: boolean;
+  references: QuranReflectPostReference[];
+  mentions: QuranReflectPostMention[];
+  roomId?: number;
+  roomPostStatus?: QuranReflectRoomPostStatus;
+  postAsAuthorId?: string;
+  publishedAt?: string | Date;
+}
+
+export type UpdateQuranReflectPostPayload =
+  Partial<CreateQuranReflectPostPayload>;
+
+export interface QuranReflectPost {
+  id: number | string;
+  authorId?: string;
+  body?: string;
+  commentsCount?: number;
+  createdAt?: string;
+  discussionId?: number;
+  draft?: boolean;
+  estimatedReadingTime?: number;
+  featuredAt?: string;
+  global?: boolean;
+  hidden?: boolean;
+  languageId?: number;
+  languageName?: string;
+  likesCount?: number;
+  mentions?: QuranReflectPostMention[];
+  moderationStatus?: number;
+  postTypeId?: number | null;
+  postTypeName?: string;
+  publishedAt?: string;
+  pushedUpAt?: string;
+  references?: QuranReflectPostReference[];
+  removed?: boolean;
+  reported?: boolean;
+  reviewedAt?: string;
+  roomId?: number | null;
+  roomPostStatus?: number;
+  toxicityScore?: number;
+  updatedAt?: string;
+  verified?: boolean;
+  views?: number;
+  viewsCount?: number;
+}
+
+export interface QuranReflectPostMutationResponse {
+  success: boolean;
+  data?: QuranReflectPost;
+  post?: QuranReflectPost;
+  error?: unknown;
+}

packages/api/test/operation-catalog-generator.test.js

@@ -1,18 +1,34 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { describe, expect, it } from "vitest";
 
-import {
-  checkCatalogs,
-  generateCatalogs,
-} from "../../../scripts/generate-operation-catalogs.mjs";
+const testDir = path.dirname(fileURLToPath(import.meta.url));
 
 const writeJson = async (filePath, value) => {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
 };
 
+const loadCatalogModule = async () => {
+  const sourcePath = path.resolve(
+    testDir,
+    "../../../scripts/generate-operation-catalogs.mjs",
+  );
+  const source = await fs.readFile(sourcePath, "utf8");
+  const moduleDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "quranjs-catalog-module-"),
+  );
+  const modulePath = path.join(moduleDir, "generate-operation-catalogs.mjs");
+
+  await fs.writeFile(modulePath, source.replace(/^#!.*(?:\r?\n|$)/, ""));
+
+  return import(pathToFileURL(modulePath).href);
+};
+
+const catalogModule = loadCatalogModule();
+
 const operation = (
   operationId,
   servers,
@@ -28,6 +44,7 @@ const operation = (
 
 describe("operation catalog generator", () => {
   it("builds compact server and public catalogs from OpenAPI specs", async () => {
+    const { generateCatalogs } = await catalogModule;
     const sourceDir = await fs.mkdtemp(
       path.join(os.tmpdir(), "quranjs-openapi-"),
     );
@@ -170,6 +187,7 @@ describe("operation catalog generator", () => {
   });
 
   it("suffixes duplicate normalized operation names deterministically", async () => {
+    const { generateCatalogs } = await catalogModule;
     const sourceDir = await fs.mkdtemp(
       path.join(os.tmpdir(), "quranjs-openapi-"),
     );
@@ -211,6 +229,7 @@ describe("operation catalog generator", () => {
   });
 
   it("reports missing generated catalog files as out of date", async () => {
+    const { checkCatalogs } = await catalogModule;
     const outputDir = await fs.mkdtemp(
       path.join(os.tmpdir(), "quranjs-catalog-output-"),
     );