broken-manga 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akewushola Abdulbakri Temitope (brokenvzn)
+
+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

@@ -1,3 +1,258 @@
-# Temporary Holding Version
+# broken-manga
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Real manga data with zero dependencies.** Search, details, chapter lists and actual page images — via the public MangaDex API. No API key, no scraping, no headless browser.
+
+```bash
+npm install broken-manga
+```
+
+## Why this exists
+
+Most manga "APIs" are HTML scrapers: they run a headless browser, parse a page, and break the moment the site changes its markup. This talks to MangaDex's real JSON API instead, using the `fetch` that already ships with Node 18+.
+
+**0 dependencies. No key. No browser. And it supports adult content properly** — through content ratings, not a separate sketchy endpoint.
+
+## Quick start
+
+```js
+const { search, getChapters, getPages } = require('broken-manga');
+
+const hits = await search('berserk');
+console.log(hits.results[0].title);   // 'Berserk'
+
+const chapters = await getChapters(hits.results[0].id);
+const pages = await getPages(chapters.results[0].id);
+console.log(pages.pages[0]);          // direct image URL
+```
+
+ESM works too:
+
+```js
+import { search, getChapters, getPages } from 'broken-manga';
+```
+
+## Content ratings
+
+MangaDex labels everything with one of four ratings:
+
+| rating | meaning |
+|---|---|
+| `safe` | nothing to warn about |
+| `suggestive` | mild fan service |
+| `erotica` | sexual content |
+| `pornographic` | explicit |
+
+**By default this package only returns `safe` and `suggestive`.** Adult results never leak into a normal search unless you ask for them — there's a test for exactly that.
+
+### Getting adult content
+
+```js
+// adult only
+const r = await search('', { adultOnly: true, sort: 'followed' });
+
+// mix safe and adult
+const r2 = await search('romance', { ratings: ['safe', 'erotica', 'pornographic'] });
+
+// everything
+const r3 = await search('x', { ratings: ['safe', 'suggestive', 'erotica', 'pornographic'] });
+```
+
+Every result also carries `isAdult`, so you can filter after the fact:
+
+```js
+const all = await search('yuri', { ratings: ['safe', 'suggestive', 'erotica'] });
+const clean = all.results.filter((g) => !g.isAdult);
+```
+
+```js
+import { RATINGS, ADULT_RATINGS, SAFE_RATINGS, ratings } from 'broken-manga';
+ratings(); // { all: [...], adult: [...], safe: [...] }
+```
+
+## API
+
+### `search(query?, options?)`
+
+```js
+await search('one piece');
+await search('one piece', { limit: 20, status: 'completed' });
+await search('', { sort: 'rating' });          // browse, no query
+```
+
+| option | default | notes |
+|---|---|---|
+| `ratings` | `['safe','suggestive']` | single value or array |
+| `adultOnly` | `false` | shorthand for adult ratings only |
+| `limit` | `10` | 1–100 |
+| `offset` | `0` | for paging |
+| `status` | — | `ongoing` `completed` `hiatus` `cancelled` |
+| `sort` | `relevance` | `followed` `rating` `latest` `created` `updated` |
+| `language` | — | restrict to a translated language |
+
+Returns `{ results, total, offset, limit }`.
+
+### `getManga(id, options?)`
+
+One manga, full metadata.
+
+```js
+const g = await getManga('801513ba-a712-498c-8f57-cae55b38cc92');
+```
+
+| field | notes |
+|---|---|
+| `id` | MangaDex UUID |
+| `title` / `altTitles` | |
+| `description` | plain text, localised |
+| `contentRating` | one of the four ratings |
+| `isAdult` | `true` for erotica / pornographic |
+| `status` / `year` | |
+| `tags` | genres |
+| `demographic` | shounen, seinen, etc |
+| `authors` / `artist` | |
+| `cover` / `coverThumb` | full-size and 256px thumbnail |
+| `availableLanguages` | which translations exist |
+| `lastChapter` / `lastVolume` | |
+
+Missing fields are `null`, never `undefined`.
+
+### `getChapters(id, options?)`
+
+```js
+await getChapters(mangaId);                                   // English, oldest first
+await getChapters(mangaId, { languages: ['en', 'fr'] });
+await getChapters(mangaId, { ascending: false, limit: 20 });   // newest first
+```
+
+| option | default | notes |
+|---|---|---|
+| `languages` | `['en']` | string or array |
+| `ascending` | `true` | chapter order |
+| `limit` | `100` | 1–500 |
+| `includeExternal` | `true` | chapters hosted on other sites |
+
+Each chapter: `{ id, chapter, volume, title, language, pages, publishedAt, scanlationGroup, externalUrl }`.
+
+### `getPages(chapterId, options?)`
+
+The actual images.
+
+```js
+const p = await getPages(chapterId);
+p.pages;      // ['https://...jpg', ...] — ready to load
+p.pageCount;  // 37
+```
+
+| option | default | notes |
+|---|---|---|
+| `dataSaver` | `false` | use the compressed page set — good for mobile |
+
+MangaDex hands out a short-lived CDN base URL per chapter, so **don't cache these URLs long-term**. Call `getPages` again when you need them.
+
+### `getFull(id, options?)`
+
+Details + chapters + the first chapter's pages, in one call. Three requests, so mind the rate limit.
+
+```js
+const { manga, chapters, firstPages } = await getFull(mangaId);
+```
+
+### `popular(options?)` / `latest(options?)`
+
+Trending and newly added. Same options as `search()`.
+
+### `MangaError`
+
+Every failure throws this, so you branch on `.code`.
+
+| code | meaning |
+|---|---|
+| `BAD_ID` | missing/invalid id |
+| `BAD_QUERY` | the service rejected the query (includes its reason) |
+| `BAD_RATING` | unknown content rating (message lists valid ones) |
+| `BAD_SORT` | unknown sort value |
+| `NOT_FOUND` | no such manga |
+| `NO_PAGES` | chapter exists but has no images |
+| `RATE_LIMITED` | HTTP 429 — backed off and retried |
+| `TIMEOUT` / `NETWORK` | couldn't reach the service |
+| `SERVER_ERROR` | 5xx — retried |
+| `HTTP_ERROR` | other non-2xx |
+| `BAD_RESPONSE` | body wasn't JSON |
+| `API_ERROR` | the service reported an error in the body |
+
+## Common patterns
+
+**A reader**
+
+```js
+const { getChapters, getPages } = require('broken-manga');
+
+const chapters = await getChapters(mangaId, { limit: 500 });
+let index = 0;
+
+async function show(i) {
+  const pages = await getPages(chapters.results[i].id);
+  render(pages.pages);   // your UI
+}
+```
+
+**Next / previous chapter, skipping ones with no pages**
+
+```js
+function nextReadable(chapters, from) {
+  for (let i = from + 1; i < chapters.length; i++) {
+    if (chapters[i].pages > 0) return i;
+  }
+  return -1;
+}
+```
+
+**Search that never shows adult content**
+
+```js
+const r = await search(q, { ratings: ['safe'] });
+```
+
+**Adult-only search, most followed first**
+
+```js
+const r = await search('', { adultOnly: true, sort: 'followed', limit: 20 });
+```
+
+**Handle rate limits**
+
+```js
+try {
+  await getChapters(id);
+} catch (err) {
+  if (err.code === 'RATE_LIMITED') await sleep(3000);
+}
+```
+
+## Rate limits
+
+MangaDex is free and shared, and it is **strict**. Roughly 5 requests per second, and it penalises bursts.
+
+- cache aggressively — manga metadata rarely changes
+- `getPages` URLs expire, so cache the *chapter id*, not the URLs
+- the client already retries `429` and `5xx` with backoff, but don't lean on it
+- `getFull()` costs three requests. Don't call it in a loop.
+
+## Tests
+
+```bash
+npm test          # 34 offline tests, fetch stubbed, no network
+npm run test:live # 9 tests against the real MangaDex API
+```
+
+The offline suite covers mapping, ratings filtering, error codes, clamping and retries. The live suite proves real searches, real chapters and real page images load — and asserts that **safe search never leaks adult titles**, while adult search returns only adult titles.
+
+## Credit
+
+Data from [MangaDex](https://mangadex.org). This is an unofficial client and is
+not affiliated with MangaDex. Please respect their terms and their rate limits,
+and support the official releases where you can.
+
+## Licence
+
+MIT © Akewushola Abdulbakri Temitope (brokenvzn)

package/index.d.ts

@@ -0,0 +1,146 @@
+/** MangaDex content ratings. */
+export type ContentRating = 'safe' | 'suggestive' | 'erotica' | 'pornographic';
+
+export interface Manga {
+  id: string;
+  title: string | null;
+  altTitles: string[];
+  description: string | null;
+  contentRating: ContentRating | null;
+  /** True when contentRating is erotica or pornographic. */
+  isAdult: boolean;
+  status: string | null;
+  year: number | null;
+  originalLanguage: string | null;
+  availableLanguages: string[];
+  lastChapter: string | null;
+  lastVolume: string | null;
+  tags: string[];
+  demographic: string | null;
+  authors: string[];
+  artist: string | null;
+  cover: string | null;
+  coverThumb: string | null;
+  links: Record<string, string>;
+}
+
+export interface Chapter {
+  id: string;
+  chapter: string | null;
+  volume: string | null;
+  title: string | null;
+  language: string | null;
+  pages: number;
+  publishedAt: string | null;
+  readableAt: string | null;
+  externalUrl: string | null;
+  scanlationGroup: string | null;
+}
+
+export interface SearchOptions {
+  /** Which ratings to include. Default ['safe','suggestive']. */
+  ratings?: ContentRating | ContentRating[];
+  /** Shortcut for adult ratings only. */
+  adultOnly?: boolean;
+  /** 1-100. Default 10. */
+  limit?: number;
+  offset?: number;
+  status?: 'ongoing' | 'completed' | 'hiatus' | 'cancelled';
+  sort?: 'relevance' | 'followed' | 'rating' | 'latest' | 'created' | 'updated';
+  language?: string;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface ChapterOptions {
+  /** Translated languages. Default ['en']. */
+  languages?: string | string[];
+  /** Oldest first. Default true. */
+  ascending?: boolean;
+  /** 1-500. Default 100. */
+  limit?: number;
+  offset?: number;
+  includeExternal?: boolean;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface PageOptions {
+  /** Use the compressed page set. Default false. */
+  dataSaver?: boolean;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface Paged<T> {
+  results: T[];
+  total: number;
+  offset: number;
+  limit: number;
+}
+
+export interface Pages {
+  baseUrl: string;
+  hash: string;
+  pages: string[];
+  pageCount: number;
+  dataSaver: boolean;
+}
+
+export type MangaErrorCode =
+  | 'BAD_ID'
+  | 'BAD_QUERY'
+  | 'BAD_RATING'
+  | 'BAD_SORT'
+  | 'NOT_FOUND'
+  | 'NO_PAGES'
+  | 'RATE_LIMITED'
+  | 'TIMEOUT'
+  | 'NETWORK'
+  | 'SERVER_ERROR'
+  | 'HTTP_ERROR'
+  | 'BAD_RESPONSE'
+  | 'API_ERROR';
+
+export declare class MangaError extends Error {
+  name: 'MangaError';
+  code: MangaErrorCode;
+  details?: unknown;
+  constructor(message: string, code: MangaErrorCode, details?: unknown);
+}
+
+export declare function search(query?: string, options?: SearchOptions): Promise<Paged<Manga>>;
+export declare function getManga(id: string, options?: SearchOptions): Promise<Manga>;
+export declare function getChapters(id: string, options?: ChapterOptions): Promise<Paged<Chapter>>;
+export declare function getPages(chapterId: string, options?: PageOptions): Promise<Pages>;
+export declare function getFull(id: string, options?: SearchOptions & ChapterOptions): Promise<{
+  manga: Manga;
+  chapters: Chapter[];
+  firstPages: Pages | null;
+}>;
+export declare function popular(options?: SearchOptions): Promise<Paged<Manga>>;
+export declare function latest(options?: SearchOptions): Promise<Paged<Manga>>;
+
+export declare function ratings(): {
+  all: ContentRating[];
+  adult: ContentRating[];
+  safe: ContentRating[];
+};
+
+export declare const RATINGS: readonly ContentRating[];
+export declare const ADULT_RATINGS: readonly ContentRating[];
+export declare const SAFE_RATINGS: readonly ContentRating[];
+export declare const USER_AGENT: string;
+
+declare const _default: {
+  search: typeof search;
+  getManga: typeof getManga;
+  getChapters: typeof getChapters;
+  getPages: typeof getPages;
+  getFull: typeof getFull;
+  popular: typeof popular;
+  latest: typeof latest;
+  ratings: typeof ratings;
+  MangaError: typeof MangaError;
+};
+export default _default;

package/index.js

@@ -0,0 +1,442 @@
+'use strict';
+
+/**
+ * broken-manga — real manga data, zero dependencies.
+ *
+ * A client for the public MangaDex API using the built-in global `fetch`.
+ * No API key, no signup, no scraping, no headless browser. Node 18+.
+ *
+ * Search, details, chapter lists, and actual page images — including adult
+ * content via MangaDex's content ratings.
+ *
+ *   const { search, getManga, getChapters, getPages } = require('broken-manga');
+ *   const hits = await search('berserk');
+ *   const chapters = await getChapters(hits[0].id);
+ *   const pages = await getPages(chapters[0].id);
+ */
+
+const API = 'https://api.mangadex.org';
+
+/** MangaDex asks clients to identify themselves and not hammer the API. */
+const USER_AGENT = 'broken-manga/1.0 (+https://github.com/Neaterry6/broken-manga)';
+
+/**
+ * MangaDex content ratings.
+ *   safe         — nothing to warn about
+ *   suggestive   — mild fan service
+ *   erotica      — sexual content
+ *   pornographic — explicit
+ */
+const RATINGS = Object.freeze(['safe', 'suggestive', 'erotica', 'pornographic']);
+
+/** Only these two are adult. */
+const ADULT_RATINGS = Object.freeze(['erotica', 'pornographic']);
+
+/** Ratings that are safe to show anywhere. */
+const SAFE_RATINGS = Object.freeze(['safe', 'suggestive']);
+
+class MangaError extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.name = 'MangaError';
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+/** @private */
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * One request, with timeout, retries and error mapping.
+ * @private
+ */
+async function request(path, { timeoutMs = 20000, retries = 2, query } = {}) {
+  let url = `${API}${path}`;
+  if (query) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      if (Array.isArray(v)) v.forEach((item) => qs.append(k, String(item)));
+      else qs.append(k, String(v));
+    }
+    const s = qs.toString();
+    if (s) url += (url.includes('?') ? '&' : '?') + s;
+  }
+
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(url, {
+        signal: controller.signal,
+        headers: { 'User-Agent': USER_AGENT, accept: 'application/json' },
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const code = err.name === 'AbortError' ? 'TIMEOUT' : 'NETWORK';
+      lastError = new MangaError(
+        code === 'TIMEOUT'
+          ? `Request timed out after ${timeoutMs}ms.`
+          : `Could not reach MangaDex: ${err.message}`,
+        code
+      );
+      if (code === 'TIMEOUT' || attempt === retries) throw lastError;
+      await sleep(500 * Math.pow(2, attempt));
+      continue;
+    }
+    clearTimeout(timer);
+
+    if (res.status === 404) throw new MangaError('Not found on MangaDex.', 'NOT_FOUND');
+    if (res.status === 429) {
+      lastError = new MangaError('Rate limited by MangaDex. Slow down.', 'RATE_LIMITED');
+      if (attempt === retries) throw lastError;
+      // MangaDex rate limits are strict; back off generously.
+      await sleep(1500 * Math.pow(2, attempt));
+      continue;
+    }
+    if (res.status === 400) {
+      let detail = '';
+      try { detail = await res.text(); } catch {}
+      throw new MangaError(
+        `MangaDex rejected the query: ${String(detail).slice(0, 200) || 'bad request'}`,
+        'BAD_QUERY',
+        detail
+      );
+    }
+    if (res.status >= 500) {
+      lastError = new MangaError(`MangaDex returned ${res.status}.`, 'SERVER_ERROR');
+      if (attempt === retries) throw lastError;
+      await sleep(500 * Math.pow(2, attempt));
+      continue;
+    }
+    if (!res.ok) throw new MangaError(`MangaDex returned ${res.status}.`, 'HTTP_ERROR', res.status);
+
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new MangaError('MangaDex returned something that is not JSON.', 'BAD_RESPONSE');
+    }
+    if (json && json.result === 'error') {
+      const msg = json.errors?.[0]?.detail || 'MangaDex reported an error.';
+      throw new MangaError(msg, 'API_ERROR', json.errors);
+    }
+    return json;
+  }
+  throw lastError;
+}
+
+/** Normalise a ratings option into the array MangaDex wants. */
+function normaliseRatings(input, fallback) {
+  if (input === undefined || input === null) return fallback.slice();
+  const list = Array.isArray(input) ? input : [input];
+  const clean = list
+    .map((r) => String(r).trim().toLowerCase())
+    .filter((r) => RATINGS.includes(r));
+  if (!clean.length) {
+    throw new MangaError(
+      `No valid content ratings. Use any of: ${RATINGS.join(', ')}.`,
+      'BAD_RATING'
+    );
+  }
+  return [...new Set(clean)];
+}
+
+/** Pull the best title out of MangaDex's multilingual title object. */
+function pickTitle(titles) {
+  if (!titles || typeof titles !== 'object') return null;
+  return titles.en || titles['ja-ro'] || titles.ja || Object.values(titles)[0] || null;
+}
+
+/** Localised string field (description, etc). */
+function pickLocalised(obj, lang = 'en') {
+  if (!obj || typeof obj !== 'object') return null;
+  return obj[lang] || obj.en || Object.values(obj)[0] || null;
+}
+
+function findRelationship(entity, type) {
+  return (entity?.relationships || []).find((r) => r.type === type) || null;
+}
+
+/** Map a MangaDex manga entity into a stable shape. */
+function mapManga(m) {
+  if (!m || !m.attributes) return null;
+  const a = m.attributes;
+  const cover = findRelationship(m, 'cover_art');
+  const author = findRelationship(m, 'author');
+  const artist = findRelationship(m, 'artist');
+
+  return {
+    id: m.id,
+    title: pickTitle(a.title),
+    altTitles: (a.altTitles || []).map((t) => pickTitle(t)).filter(Boolean),
+    description: pickLocalised(a.description),
+    /** 'safe' | 'suggestive' | 'erotica' | 'pornographic' */
+    contentRating: a.contentRating || null,
+    /** true when contentRating is erotica or pornographic. */
+    isAdult: ADULT_RATINGS.includes(a.contentRating),
+    status: a.status || null,
+    year: a.year ?? null,
+    originalLanguage: a.originalLanguage || null,
+    availableLanguages: a.availableTranslatedLanguages || [],
+    lastChapter: a.lastChapter || null,
+    lastVolume: a.lastVolume || null,
+    tags: (a.tags || []).map((t) => pickLocalised(t.attributes?.name)).filter(Boolean),
+    demographic: a.publicationDemographic || null,
+    authors: author?.attributes?.name ? [author.attributes.name] : [],
+    artist: artist?.attributes?.name || null,
+    /** Cover URL, already assembled from the filename. */
+    cover: cover?.attributes?.fileName
+      ? `https://uploads.mangadex.org/covers/${m.id}/${cover.attributes.fileName}`
+      : null,
+    coverThumb: cover?.attributes?.fileName
+      ? `https://uploads.mangadex.org/covers/${m.id}/${cover.attributes.fileName}.256.jpg`
+      : null,
+    links: a.links || {},
+  };
+}
+
+/** Map a chapter entity. */
+function mapChapter(c) {
+  if (!c || !c.attributes) return null;
+  const a = c.attributes;
+  const group = findRelationship(c, 'scanlation_group');
+  return {
+    id: c.id,
+    chapter: a.chapter || null,
+    volume: a.volume || null,
+    title: a.title || null,
+    language: a.translatedLanguage || null,
+    pages: a.pages ?? 0,
+    publishedAt: a.publishAt || null,
+    readableAt: a.readableAt || null,
+    externalUrl: a.externalUrl || null,
+    scanlationGroup: group?.attributes?.name || null,
+  };
+}
+
+/**
+ * Search manga.
+ *
+ * @param {string} [query] Title text. Omit to browse.
+ * @param {object} [options]
+ * @param {string|string[]} [options.ratings] Content ratings to include.
+ *   Defaults to ['safe', 'suggestive']. Pass 'pornographic' or
+ *   ['erotica','pornographic'] for adult content.
+ * @param {boolean} [options.adultOnly=false] Shortcut for adult ratings only.
+ * @param {number} [options.limit=10] 1-100.
+ * @param {number} [options.offset=0]
+ * @param {string} [options.status] ongoing | completed | hiatus | cancelled
+ * @param {string} [options.sort='relevance'] relevance | followed | rating | latest | created
+ * @param {string} [options.language] Restrict to manga with this translated language.
+ * @returns {Promise<{results: object[], total: number, offset: number, limit: number}>}
+ */
+async function search(query, options = {}) {
+  const limit = Math.max(1, Math.min(100, Number(options.limit) || 10));
+  const offset = Math.max(0, Number(options.offset) || 0);
+
+  let ratings;
+  if (options.adultOnly) ratings = ADULT_RATINGS.slice();
+  else ratings = normaliseRatings(options.ratings, SAFE_RATINGS);
+
+  const sortMap = {
+    relevance: null,
+    followed: 'followedCount',
+    rating: 'rating',
+    latest: 'latestUploadedChapter',
+    created: 'createdAt',
+    updated: 'updatedAt',
+  };
+  const sortKey = sortMap[String(options.sort || 'relevance').toLowerCase()];
+  if (options.sort && options.sort !== 'relevance' && !sortKey) {
+    throw new MangaError(
+      `Unknown sort "${options.sort}". Use one of: ${Object.keys(sortMap).join(', ')}.`,
+      'BAD_SORT'
+    );
+  }
+
+  const q = {
+    limit,
+    offset,
+    'contentRating[]': ratings,
+    'includes[]': ['cover_art', 'author', 'artist'],
+    'order[followedCount]': 'desc',
+  };
+  if (typeof query === 'string' && query.trim()) q.title = query.trim();
+  if (options.status) q.status = String(options.status);
+  if (options.language) q['availableTranslatedLanguage[]'] = String(options.language);
+  if (sortKey) {
+    delete q['order[followedCount]'];
+    q[`order[${sortKey}]`] = 'desc';
+  }
+
+  const body = await request('/manga', { ...options, query: q });
+  return {
+    results: (body.data || []).map(mapManga).filter(Boolean),
+    total: body.total ?? 0,
+    offset: body.offset ?? offset,
+    limit: body.limit ?? limit,
+  };
+}
+
+/**
+ * Fetch one manga by id.
+ * @param {string} id MangaDex UUID.
+ */
+async function getManga(id, options = {}) {
+  if (!id || typeof id !== 'string') {
+    throw new MangaError('getManga() needs a MangaDex id.', 'BAD_ID');
+  }
+  const body = await request(`/manga/${encodeURIComponent(id)}`, {
+    ...options,
+    query: { 'includes[]': ['cover_art', 'author', 'artist'] },
+  });
+  const mapped = mapManga(body.data);
+  if (!mapped) throw new MangaError('Manga not found.', 'NOT_FOUND');
+  return mapped;
+}
+
+/**
+ * Chapter list for a manga.
+ *
+ * @param {string} id MangaDex manga id.
+ * @param {object} [options]
+ * @param {string|string[]} [options.languages=['en']] Translated languages.
+ * @param {boolean} [options.ascending=true] Oldest chapter first.
+ * @param {number} [options.limit=100] 1-500.
+ * @param {number} [options.offset=0]
+ * @param {boolean} [options.includeExternal=true] Include chapters hosted elsewhere.
+ */
+async function getChapters(id, options = {}) {
+  if (!id || typeof id !== 'string') {
+    throw new MangaError('getChapters() needs a MangaDex manga id.', 'BAD_ID');
+  }
+  const langs = options.languages
+    ? (Array.isArray(options.languages) ? options.languages : [options.languages])
+    : ['en'];
+  const limit = Math.max(1, Math.min(500, Number(options.limit) || 100));
+  const offset = Math.max(0, Number(options.offset) || 0);
+  const asc = options.ascending !== false;
+
+  const q = {
+    limit,
+    offset,
+    'translatedLanguage[]': langs.map(String),
+    'order[chapter]': asc ? 'asc' : 'desc',
+    'includes[]': ['scanlation_group'],
+  };
+  if (options.includeExternal === false) q.includeExternalUrl = '0';
+
+  const body = await request(`/manga/${encodeURIComponent(id)}/feed`, { ...options, query: q });
+  return {
+    results: (body.data || []).map(mapChapter).filter(Boolean),
+    total: body.total ?? 0,
+    offset: body.offset ?? offset,
+    limit: body.limit ?? limit,
+  };
+}
+
+/**
+ * Page image URLs for a chapter.
+ *
+ * Returns fully-formed URLs ready to load or proxy. MangaDex hands out a
+ * short-lived base URL per chapter, so don't cache these forever.
+ *
+ * @param {string} chapterId Chapter UUID.
+ * @param {object} [options]
+ * @param {boolean} [options.dataSaver=false] Use the compressed page set.
+ * @returns {Promise<{baseUrl: string, hash: string, pages: string[], pageCount: number, dataSaver: boolean}>}
+ */
+async function getPages(chapterId, options = {}) {
+  if (!chapterId || typeof chapterId !== 'string') {
+    throw new MangaError('getPages() needs a chapter id.', 'BAD_ID');
+  }
+  const body = await request(`/at-home/server/${encodeURIComponent(chapterId)}`, options);
+  const base = body.baseUrl;
+  const hash = body.chapter?.hash;
+  if (!base || !hash) {
+    throw new MangaError('MangaDex returned no page data for that chapter.', 'NO_PAGES', body);
+  }
+
+  const dataSaver = options.dataSaver === true;
+  const list = dataSaver ? body.chapter.dataSaver : body.chapter.data;
+  const segment = dataSaver ? 'data-saver' : 'data';
+
+  const pages = (list || []).map((file) => `${base}/${segment}/${hash}/${file}`);
+
+  return {
+    baseUrl: base,
+    hash,
+    pages,
+    pageCount: pages.length,
+    dataSaver,
+  };
+}
+
+/**
+ * Everything about a manga in one call: details, chapters, and the first
+ * chapter's pages. Convenient, but it's three requests — mind the rate limit.
+ *
+ * @param {string} id
+ * @param {object} [options]
+ */
+async function getFull(id, options = {}) {
+  const manga = await getManga(id, options);
+  const chapters = await getChapters(id, { ...options, limit: options.limit || 20 });
+  let firstPages = null;
+  const first = chapters.results.find((c) => c.pages > 0);
+  if (first) {
+    try {
+      firstPages = await getPages(first.id, options);
+    } catch {
+      firstPages = null;
+    }
+  }
+  return { manga, chapters: chapters.results, firstPages };
+}
+
+/**
+ * Trending / most-followed manga.
+ * @param {object} [options] Same as search().
+ */
+async function popular(options = {}) {
+  return search('', { ...options, sort: 'followed' });
+}
+
+/**
+ * Newly added manga.
+ * @param {object} [options] Same as search().
+ */
+async function latest(options = {}) {
+  return search('', { ...options, sort: 'created' });
+}
+
+/** The ratings this package understands. */
+function ratings() {
+  return {
+    all: RATINGS.slice(),
+    adult: ADULT_RATINGS.slice(),
+    safe: SAFE_RATINGS.slice(),
+  };
+}
+
+module.exports = {
+  search,
+  getManga,
+  getChapters,
+  getPages,
+  getFull,
+  popular,
+  latest,
+  ratings,
+  MangaError,
+  RATINGS,
+  ADULT_RATINGS,
+  SAFE_RATINGS,
+  USER_AGENT,
+};

package/index.mjs

@@ -0,0 +1,17 @@
+// ESM wrapper around the CommonJS implementation.
+import mod from './index.js';
+
+export const search = mod.search;
+export const getManga = mod.getManga;
+export const getChapters = mod.getChapters;
+export const getPages = mod.getPages;
+export const getFull = mod.getFull;
+export const popular = mod.popular;
+export const latest = mod.latest;
+export const ratings = mod.ratings;
+export const MangaError = mod.MangaError;
+export const RATINGS = mod.RATINGS;
+export const ADULT_RATINGS = mod.ADULT_RATINGS;
+export const SAFE_RATINGS = mod.SAFE_RATINGS;
+
+export default mod;

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "broken-manga",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Real manga data with zero dependencies — search, details, chapters and page images via MangaDex. Supports adult content ratings. No API key.",
+  "keywords": [
+    "manga", "manga-api", "mangadex", "comic", "hentai", "doujin", "ecchi",
+    "search", "chapters", "reader", "zero-dependency", "fetch"
+  ],
+  "license": "MIT",
+  "author": "Akewushola Abdulbakri Temitope (brokenvzn) <akewusholaabdulbakri101@gmail.com>",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.mjs"
+    }
+  },
+  "files": ["index.js", "index.mjs", "index.d.ts", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test.js",
+    "test:live": "node --test test-live.js"
+  },
+  "engines": { "node": ">=18" },
+  "repository": { "type": "git", "url": "git+https://github.com/Neaterry6/broken-manga.git" },
+  "bugs": { "url": "https://github.com/Neaterry6/broken-manga/issues" },
+  "homepage": "https://github.com/Neaterry6/broken-manga#readme",
+  "sideEffects": false
+}