mangabaka-seeder/HANDOVER.md

Handover

Read this first if you are picking up this repo. It records the state of the work and the context from the design conversation (2026-10-14) that isn't obvious from the code.

Read these, in this order:

1. this file
2. TODO.md
3. docs/ARCHITECTURE.md, the approved design spec with the external facts we verified
4. README.md, user-facing behaviour.

Status

• Phase: the design is complete and approved by the user. No code exists yet.
• Branch: feat/webtoons-covers. The repo had no commits before this branch, and nothing has been pushed.
• Next step: write the implementation plan, using the superpowers:writing-plans skill, from docs/ARCHITECTURE.md. Then implement it with test-driven development.
• Approval gates: the user's global preference is "once I approve a design, carry it through spec → plan → execution with no extra review stops". In this session, though, they explicitly said "Do not write the plan afterwards. Wait for my approval." and later approved the spec ("everything seems good"). Unless they say otherwise, show the plan before implementing.

What we're building (in the user's words, then refined)

"a nice and easy to use seeder for adding new data to mangabaka. The first thing we should be able to do is given a webtoons url, get all covers related to the series in name, and request them added as main cover english."

"think of this as a mangabaka version of /home/user/yambs"

The user is a regular MangaBaka contributor and uses the normal edit-request flow, not admin access. At the time of the conversation they did not have API access (fewer than 25 approved submissions).

Decisions made with the user

Topic	Decision	Source
Stack	TypeScript / Node (≥ 22). The user picked this over Go, despite yambs being Go, to keep a browser extension or userscript possible later.	user
Submission path	Both. The API when MANGABAKA_TOKEN is set; otherwise a local review page for manual entry.	user
Which images	All: poster, square thumbnail, banner/background and foreground art.	user ("3")
Old covers	Also find historical covers through the Wayback Machine.	user
Main cover	The current poster (the square for canvas series) gets is_default: true, and existing covers get is_default: false. The reviewer can reject this.	Claude, accepted
Rehosting	Required. MangaBaka may not be able to fetch Webtoons URLs. The image host is pluggable: catbox.moe by default, an S3-compatible bucket, or direct. Temporary hosts like litterbox were rejected because links can expire before review. imgur is banned by MangaBaka.	user ("1")
Content rating	The user sets it, default safe: through a flag, an interactive prompt or a per-card selector. --yes requires an explicit --content-rating. Mature titles show a warning.	user
Image bytes	Kept in memory between inspection and upload. Sizes up to about 650 KB have been seen, so don't assume small images. There is a 20 MB per-image safety cap.	user, confirmed
Extensibility	New sources (Tapas, Tappytoon, Lezhin, Manta, …) are one module under src/sources/ plus one registry line. Image hosts use the same pattern under src/hosting/. No pipeline changes.	user requirement
Safety	Nothing is uploaded or sent to MangaBaka without explicit user action. API saves always use save_mode: "review".	Claude, accepted
Not now	Editing fields other than images; following Webtoons across language editions.	Claude, accepted

Key facts (details in ARCHITECTURE §2)

• MangaBaka:
  • Endpoints: site https://mangabaka.org, API https://api.mangabaka.org. api.mangabaka.dev is deprecated.
  • OpenAPI spec: https://mangabaka.org/api.json, about 700 KB. Download it again; the earlier copy was in a temporary scratchpad and is gone.
  • Cover submissions: GET, POST, and POST …/preview on /v0/my/submissions/series-images/{id}, with the x-api-key header. images replaces the whole set. These endpoints return 403 unless the user has the contributor role or at least 25 approved submissions.
  • Web cover form: /data/submissions/series/{id}/images. It can't be pre-filled, and SvelteKit's CSRF check blocks cross-site POSTs.
  • Test series: Tower of God is series 9999. Its link is https://www.webtoons.com/-/-/-/list?title_no=95, so links are stored canonicalised.
  • Finding a series: there's no reverse lookup by URL. Use /v2/series/match?q= or /v2/series/search, then /v1/series/{id}/links.
  • Rate limits: about 30 requests per minute for search, 180 otherwise.
• Webtoons:
  • Image fields: og:image is the poster (480×623 when the ?type= query is stripped), and twitter:image is the square thumbnail.
  • Hero art: div.detail_bg style and .detail_header span.thmb img.
  • Hotlinking: webtoon-phinf needs a Webtoons Referer, but swebtoon-phinf doesn't. Rewrite the host.
  • Old hosts: rewrite swebtoon.phinf.naver.net to swebtoon-phinf.pstatic.net.
  • No JSON API: the app API needs signed requests, so scrape the HTML.
• Wayback: querying CDX with collapse=timestamp:6 and fetching id_ snapshots works.
  • Tower of God has about 2000 snapshots (2015–2026), which reference five distinct cover images.
  • Old images tested from 2014, 2015 and 2019 are still live on swebtoon-phinf.pstatic.net.
  • The 2021 one is gone from Wayback's own copy, but is live on pstatic.
  • Some historical og:images are landing-page art rather than covers. This is why the tool classifies by shape and the user reviews the list.

Tower of God historical og:images found (useful as test data)

2015  http://swebtoon.phinf.naver.net/20140710_28/1404979632969uKBA8_JPEG/01_EC8BA0EC9D98ED8391.jpg
2017  http://swebtoon.phinf.naver.net/20151006_141/1444125046528RTfRM_JPEG/_EB93BBEB80AF_EBA38CEABCA5_E29587EABCB1_EB9384EB84B0_ipa.jpg
      (twitter:image …/20151006_243/1444125042491PuNza_JPEG/…_mob.jpg)
2019  https://swebtoon-phinf.pstatic.net/20190318_291/1552868599909GoVLY_JPEG/10_EC8DB8EB84A4EC9DBC_ipad.jpg
      (twitter:image …/20190318_26/1552868584759vl9A1_JPEG/11_EC8DB8EB84A4EC9DBC_mobile.jpg)
2021  https://swebtoon-phinf.pstatic.net/20210127_106/1611705089085OYcUB_JPEG/1Tower-of-God-Mobile-Landing-Page.jpg
2023+ https://swebtoon-phinf.pstatic.net/20230324_114/1679612146968KhLLz_JPEG/6TowerOfGod_landingpage_mobile.jpg
live  https://swebtoon-phinf.pstatic.net/20250204_46/17386458444547o1b2_JPEG/95.jpg   (poster, 480×623)

Other test URLs:

• canvas: https://www.webtoons.com/en/canvas/crow-time/list?title_no=693372
• mature: title_no 6065 (filename contains spaces and ); URL-encode it)
• FR example: Violet Romance, 2Thumb_Poster_9782.jpg.

Open questions and risks

1. When MangaBaka copies images. We don't know if it copies the image when the request is submitted or when it is approved. Permanent hosting (catbox) is the mitigation.
2. Whether MangaBaka accepts catbox URLs. Not verified. If it doesn't, try s3, or direct (swebtoon-phinf.pstatic.net).
3. The "main cover" mapping. Mapping "main cover" to is_default is inferred from the API spec, not confirmed by MangaBaka.
4. Request limits. Rate limits and region blocks on Webtoons or Wayback at scale haven't been tested.
5. Personal access tokens. We don't know where a user creates a PAT in the MangaBaka UI. The submission endpoints say auth: pat.

References

• yambs (the model project, Go): /home/user/yambs, with the same sources → seed → actions shape.
• MangaBaka API docs: https://mangabaka.org/data/api; explorer: https://mangabaka.org/data/api/explorer
• MangaBaka support: https://mangabaka.org/discord
• catbox API: POST https://catbox.moe/user/api.php with reqtype=fileupload, fileToUpload and optional userhash.