feat: add quran manifest endpoint

GET /v3/quran/manifest returns version metadata, CDN paths, and
checksums for the app's image-based Quran reader.

Author: F2had

src/app.ts

@@ -6,8 +6,8 @@ import { Elysia } from "elysia";
 import { athkarModule } from "@/modules/athkar";
 import { healthModule } from "@/modules/health";
 import { locationsModule } from "@/modules/locations";
-import { mushafModule } from "@/modules/mushaf";
 import { prayerModule } from "@/modules/prayers";
+import { quranModule } from "@/modules/quran";
 import { statsModule } from "@/modules/stats";
 import { telemetry } from "@/observability/telemetry";
 // Plugins
@@ -36,6 +36,10 @@ export const app = new Elysia()
 						name: "Health",
 						description: "Health check endpoint",
 					},
+					{
+						name: "Quran",
+						description: "Quran mushaf manifest and assets",
+					},
 				],
 			},
 		}),
@@ -49,7 +53,7 @@ export const app = new Elysia()
 			.use(healthModule)
 			.use(prayerModule)
 			.use(locationsModule)
-			.use(mushafModule)
+			.use(quranModule)
 			.use(statsModule),
 	);
 

src/modules/quran/index.ts

@@ -0,0 +1,15 @@
+import { Elysia } from "elysia";
+import { QuranManifestResponse } from "@/modules/quran/quran.schemas";
+import { QuranService } from "@/modules/quran/quran.service";
+
+export const quranModule = new Elysia({
+	name: "quranModule",
+	prefix: "/quran",
+	detail: {
+		tags: ["Quran"],
+	},
+}).get("/manifest", () => QuranService.getManifest(), {
+	response: {
+		200: QuranManifestResponse,
+	},
+});

src/modules/quran/quran.schemas.ts

@@ -0,0 +1,35 @@
+import { type Static, t } from "elysia";
+
+const ChecksumsSchema = t.Object({
+	boundsDb: t.String(),
+	manifest: t.String(),
+});
+
+const PathsSchema = t.Object({
+	lines: t.String(),
+	boundsDb: t.String(),
+	markers: t.String(),
+});
+
+const QuranVersionSchema = t.Object({
+	id: t.String(),
+	name: t.String(),
+	totalPages: t.Number(),
+	linesPerPage: t.Number(),
+	imageWidth: t.Number(),
+	imageHeight: t.Number(),
+	totalSizeMB: t.Number(),
+	boundsDbSizeMB: t.Number(),
+	baseUrl: t.String(),
+	paths: PathsSchema,
+	markers: t.Array(t.String()),
+	checksums: ChecksumsSchema,
+});
+
+export const QuranManifestResponse = t.Object({
+	manifestVersion: t.Number(),
+	versions: t.Array(QuranVersionSchema),
+});
+
+export type QuranManifest = Static<typeof QuranManifestResponse>;
+export type QuranVersion = Static<typeof QuranVersionSchema>;

src/modules/quran/quran.service.ts

@@ -0,0 +1,90 @@
+import { env } from "@/config/env";
+import type { QuranManifest, QuranVersion } from "./quran.schemas";
+
+const quranBase = `${env.CDN_URL}/quran`;
+
+const MARKERS = ["marker-light", "marker-dark", "marker-sepia", "surah-frame"];
+
+const VERSIONS: QuranVersion[] = [
+	{
+		id: "v1",
+		name: "Madinah Mushaf V1",
+		totalPages: 604,
+		linesPerPage: 15,
+		imageWidth: 1440,
+		imageHeight: 232,
+		totalSizeMB: 96,
+		boundsDbSizeMB: 5,
+		baseUrl: `${quranBase}/v1`,
+		paths: {
+			lines: "/lines/{page}/{line}.png",
+			boundsDb: "/bounds.db",
+			markers: "/markers/{name}.png",
+		},
+		markers: MARKERS,
+		checksums: {
+			boundsDb:
+				"sha256:58732bcf3d3485df7708908bdabd76ed8c9f0b3e555a7f543936c8a7712a588d",
+			manifest:
+				"sha256:4966f017f4ead78ce9faadcb4eb30c684f8d510659783155f7ed20dc607d1998",
+		},
+	},
+	{
+		id: "v2",
+		name: "Madinah Mushaf V2",
+		totalPages: 604,
+		linesPerPage: 15,
+		imageWidth: 1440,
+		imageHeight: 232,
+		totalSizeMB: 108,
+		boundsDbSizeMB: 5,
+		baseUrl: `${quranBase}/v2`,
+		paths: {
+			lines: "/lines/{page}/{line}.png",
+			boundsDb: "/bounds.db",
+			markers: "/markers/{name}.png",
+		},
+		markers: MARKERS,
+		checksums: {
+			boundsDb:
+				"sha256:d3d87b960c51e035a3dc91c0f9ac961567a5dd0197424de5c28ec864091b73be",
+			manifest:
+				"sha256:98dca13b9532db85564b10c66073fccd9858c1e3ff92000b0bfcbfc9fd164df8",
+		},
+	},
+	{
+		id: "v4",
+		name: "Madinah Mushaf V4",
+		totalPages: 604,
+		linesPerPage: 15,
+		imageWidth: 1440,
+		imageHeight: 232,
+		totalSizeMB: 90,
+		boundsDbSizeMB: 5,
+		baseUrl: `${quranBase}/v4`,
+		paths: {
+			lines: "/lines/{page}/{line}.png",
+			boundsDb: "/bounds.db",
+			markers: "/markers/{name}.png",
+		},
+		markers: MARKERS,
+		checksums: {
+			boundsDb:
+				"sha256:a277818bd06ed10fe2397c551ca7990a2fabe3203815ab40f448c108c03e86f2",
+			manifest:
+				"sha256:c679a0887d2558659668f02f8aea49216b7bb62f0c4d8ef79afab913d59bfb9f",
+		},
+	},
+];
+
+const MANIFEST: QuranManifest = {
+	manifestVersion: 1,
+	versions: VERSIONS,
+};
+
+// biome-ignore lint/complexity/noStaticOnlyClass: follows existing service pattern
+export abstract class QuranService {
+	static getManifest(): QuranManifest {
+		return MANIFEST;
+	}
+}

test/modules/quran.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { Elysia } from "elysia";
+import { env } from "@/config/env";
+import { quranModule } from "@/modules/quran";
+
+const app = new Elysia().group("/v3", (app) => app.use(quranModule));
+
+describe("GET /v3/quran/manifest", () => {
+	test("returns 200 with manifest", async () => {
+		const response = await app.handle(
+			new Request("http://localhost/v3/quran/manifest"),
+		);
+		expect(response.status).toBe(200);
+
+		const body = await response.json();
+		expect(body.manifestVersion).toBe(1);
+	});
+
+	test("returns all versions", async () => {
+		const response = await app.handle(
+			new Request("http://localhost/v3/quran/manifest"),
+		);
+		const body = await response.json();
+
+		expect(body.versions).toBeArray();
+		expect(body.versions.length).toBeGreaterThanOrEqual(1);
+
+		const ids = body.versions.map((v: { id: string }) => v.id);
+		expect(ids).toContain("v1");
+		expect(ids).toContain("v2");
+		expect(ids).toContain("v4");
+	});
+
+	test("each version has required fields", async () => {
+		const response = await app.handle(
+			new Request("http://localhost/v3/quran/manifest"),
+		);
+		const body = await response.json();
+
+		for (const version of body.versions) {
+			expect(version.id).toBeString();
+			expect(version.name).toBeString();
+			expect(version.totalPages).toBeNumber();
+			expect(version.linesPerPage).toBeNumber();
+			expect(version.imageWidth).toBeNumber();
+			expect(version.imageHeight).toBeNumber();
+			expect(version.totalSizeMB).toBeNumber();
+			expect(version.boundsDbSizeMB).toBeNumber();
+			expect(version.baseUrl).toBeString();
+			expect(version.paths).toBeDefined();
+			expect(version.paths.lines).toBeString();
+			expect(version.paths.boundsDb).toBeString();
+			expect(version.paths.markers).toBeString();
+			expect(version.markers).toBeArray();
+			expect(version.checksums).toBeDefined();
+			expect(version.checksums.boundsDb).toBeString();
+			expect(version.checksums.manifest).toBeString();
+		}
+	});
+
+	test("baseUrl uses CDN_URL", async () => {
+		const response = await app.handle(
+			new Request("http://localhost/v3/quran/manifest"),
+		);
+		const body = await response.json();
+
+		for (const version of body.versions) {
+			expect(version.baseUrl).toStartWith(env.CDN_URL);
+			expect(version.baseUrl).toContain(`/quran/${version.id}`);
+		}
+	});
+});