Discord Novel Launch, Arc, Extras & Completion Notifier

Automatically monitors paid and free RSS feeds for your novels, tracks arc history, side stories/extras published, and fires three types of Discord announcements via webhook:

1. New Novel Launch Alerts looks out for the first free chapter of a new series (Ch. 1, Chapter 1, Ep. 1, Episode 1, 1.1, Prologue)
2. New Arc Alerts (locked‑advance content)
3. Side Stories/Extra Alerts (locked‑advance content, fires one time for each novel)
4. Completion Announcements when the final chapter appears (paid) and full series unlocks (free)

Notifications are sent via the Discord bot API (using DISCORD_BOT_TOKEN + DISCORD_CHANNEL_ID).
The old setup used a single DISCORD_WEBHOOK URL — that webhook flow is legacy and only applies to earlier versions.

---

⚙️ GitHub Repository Settings

🔧 Repository Secrets Setup

Name	Value
DISCORD_WEBHOOK	Your Discord webhook URL (Legacy, not required for bot use)
GH_PAT	Personal Access Token for history push

🔑 1. Add the Discord Webhook URL to Secrets (Legacy — See update below for new Repository Secrets)

1. Go to Settings → Secrets and variables → Actions.
2. Click New repository secret.
3. Set Name to DISCORD_WEBHOOK.
4. Set Value to your Discord webhook URL.
5. Click Add secret.

🔑 2. Add a Personal Access Token (PAT) from the Source Repository

To allow the script to update the novel history JSON files and push changes back to GitHub, you need to generate and store a Personal Access Token (PAT) from the source repository that triggers this script.

✅ Generate a PAT from the Source Repository

1. Go to GitHub Personal Access Tokens.
2. Click "Generate new token (classic)".
3. Select Expiration (no expiration).
4. Under Scopes, check:
   • ✅ repo (Full control of private repositories)
   • ✅ workflow (Required for GitHub Actions)
5. Click Generate token and copy it.

✅ Store the PAT in the Source Repository

1. Go to Settings → Secrets and variables → Actions.
2. Click New repository secret.
3. Set Name to GH_PAT.
4. Set Value to the Personal Access Token copied earlier.
5. Click Add secret.

🚨 Important:

• The PAT must be set in the repository where GitHub Actions runs the script (i.e., the source repo that triggers Discord updates).
• If this repo is forked, the PAT must be added to the forked repository’s secrets, not just the original.

---

🛠️ 3. Set GitHub Actions Permissions

1. Go to Settings → Actions → General.
2. Under Workflow permissions, select:
   • ✅ Allow all actions and reusable workflows
   • ✅ Read and write permissions
3. Click Save.

---

📂 User Setup Guide (pick one)

Option 1:📋 Install Mapping Package

If you’d rather always pull the latest novel_mappings.py from the rss-feed repo, add this to your CI’s install step:

pip install --upgrade git+https://github.com/Cannibal-Turtle/rss-feed.git@main

Your rss-feed repo needs a pyproject.toml at its root, for example:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "cannibal-turtle-rss-feed"
version = "0.1.0"
description = "Mapping data for feeds"
authors = [ { name = "Cannibal Turtle" } ]
readme = "README.md"
requires-python = ">=3.7"
license = { text = "MIT" }
classifiers = [
  "Programming Language :: Python :: 3",
]

[project.urls]
Homepage = "https://github.com/Cannibal-Turtle/rss-feed"

[tool.setuptools]
# explicitly list each standalone .py you want installed
py-modules = [
  "novel_mappings",
]

With that in place, you do not need a local config.json—both new_arc_checker.py and completed_novel_checker.py will import HOSTING_SITE_DATA directly.

📋 Option 2: Configuration to Add a New Novel to Track

Only if you choose not to install the mapping package.

1. Add or update config.json at the repo root:

{
  "novels": [
    {
      "novel_title": "Your Novel Title",
      "role_mention": "<@&DISCORD_ROLE_ID>",
      "chapter_count": "Total number of chapters",
      "last_chapter": "Last chapter for novel",
      "start_date": "31/8/2024",
      "free_feed": "https://your-free-feed-url.xml",
      "paid_feed": "https://your-paid-feed-url.xml",
      "novel_link": "https://your-novel-link/",
      "host": "Your Hosting Site",
      "custom_emoji": ":EmojiID:",
      "discord_role_url": "https://discord.com/channels/YOUR_ROLE_URL",
      "history_file": "your_novel_history.json"
    }
  ]
}

2. Script changes in both new_arc_checker.py and completed_novel_checker.py:

• Remove the mapping-package import:

  - from novel_mappings import HOSTING_SITE_DATA

• Re-add your CONFIG_PATH constant:

  + CONFIG_PATH = "config.json"

• Bring back load_config() helper (which reads config.json).
• Swap the bottom if __name__ == "__main__": block to loop over:

   config = load_config()
   state  = load_state()
   for novel in config["novels"]:
       process_novel(novel, state)
   save_state(state)```

Each novel must have a unique history_file to store its arc history.

---

📑 Supported RSS Item Fields

All scripts read from your generated RSS/Atom-style feeds (free_feed, paid_feed).
Each <item> in the feed is expected to look like this:

<item>
  <title>Quick Transmigration: The Villain Is Too Pampered and Alluring</title>
  <volume/>
  <chaptername>Chapter 377</chaptername>
  <nameextend>***My Fiancé Is Definitely Not a Little Pitiful Person 039***</nameextend>
  <link>https://dragonholic.com/novel/.../chapter-377/</link>
  <description><![CDATA[ ... HTML summary ... ]]></description>
  <category>SFW</category>
  <translator>Cannibal Turtle</translator>
  <featuredImage url="https://dragonholic.com/wp-content/uploads/2024/08/177838.jpg"/>
  <pubDate>Sat, 25 Oct 2025 12:00:00 +0000</pubDate>
  <host>Dragonholic</host>
  <hostLogo url="https://dragonholic.com/wp-content/uploads/2025/01/Web-Logo-White.png"/>
  <guid isPermaLink="false">10850</guid>
</item>

The scripts rely on a few specific fields:

Tag	Purpose
<chaptername>	Contains the chapter label (e.g. “Chapter 5”, “Extra 8”) — used to detect paid & free completions
<link>	URL to the chapter page — used to construct message links
<nameextend>	Used for arc detection (looks for markers like “001”, “(1)”, “.1”) when generating New Arc Alerts
<volume>	Optional alternative base name for arcs if present

Only <chaptername> and <link> are strictly required for completion checks. Arc alerts also use <nameextend> or <volume>.

---

⚙️ Workflows

Feed Generation (in your feeds repo)

• update-paid-feed.yml and update-free-feed.yml:
  • Cron/dispatch regenerates the respective XML feed file.
  • Commits changes and triggers the notifier via:

    curl -X POST \
      -H "Accept: application/vnd.github.v3+json" \
      -H "Authorization: Bearer $GH_PAT" \
      https://api.github.com/repos/USER/discord-notifier/dispatches \
      -d '{"event_type":"trigger-discord-notify"}'

Discord Notifier (in your notifier repo)

The workflow listens for:

• on: repository_dispatch.types = [trigger-discord-notify]
• A scheduled cron
• Manual workflow dispatch

Jobs:

1. New Arc Checker

   python new_arc_checker.py
   

2. New Extra Checker

   python new_extra_checker.py
   

3. Completion Checker

   - name: Paid Completion
     run: python completed_novel_checker.py --feed paid
   
   - name: Free Completion
     run: python completed_novel_checker.py --feed free

4. New Launch Checker

   - name: New Launch Checker
     run: python new_novel_checker.py --feed free

🎯 Notes

• For each novel, the HOSTING_SITE_DATA must be updated first before 1st chapter is scheduled to launch.
• For each novel, set a history_file (e.g. tvitpa_history.json) in novel_mappings.py. If it doesn't exist yet, the script will create it on first run and quietly record Arc 1 (no ping on the very first arc).
• Arcs are stored persistently and prevent duplicate notifications.
• NSFW detection adds an extra Discord role mention.
• Every Discord webhook payload uses "allowed_mentions":{"parse":["roles"]} to color role pings and "flags":4 to suppress all link-preview embeds.
• Each novel in HOSTING_SITE_DATA must define:
  • free_feed: the global/public RSS that lists ALL free/public chapters from all novels.
  • paid_feed: the global/advance RSS that lists ALL paid/locked chapters from all novels. The checkers filter those feeds by <title> to isolate just that novel.
    Some scripts will silently skip a novel if one of these feeds is missing. See:

Feed Requirements Per Checker

New Series Launch Alerts

• Requires: free_feed
• Behavior: only fires when a public first drop appears (Chapter 1, Ch 1, Episode 1, Ep 1, 1.1, Prologue)
• Skips paywalled-only debuts

New Arc Alerts

• Requires: free_feed and paid_feed
• Behavior: if either feed is missing, that novel is skipped (no ping, no history update)

Extras / Side Story Alerts

• Requires: paid_feed
• Behavior: if paid_feed is missing, that novel is skipped
• Purpose: announces when extras / side stories begin dropping in paid/advance access

Completion Announcements

• Runs twice:
  • python completed_novel_checker.py --feed paid
    • Requires: paid_feed
    • Announces: the final paid/advance chapter is out (series is fully translated)
  • python completed_novel_checker.py --feed free
    • Requires: free_feed
    • Announces: the full series is now unlocked for free / bingeable
• Behavior: each side only fires once per novel

---

🚀 Now, you're ready to automate new arc and novel completion announcements to Discord!

---

🆕 UPDATE: New Bot Scripts (v3.1)

We’ve just added three standalone Python bots (migrated from MonitoRSS) that post directly as your own Discord bot:

Script	Purpose
bot_free_chapters.py	Posts new free chapters (🔓) in oldest→newest order.
bot_paid_chapters.py	Posts new advance/paid chapters (🔒) in oldest→newest order.
bot_comments.py	Posts new comments with from hosting sites.

🔧 What You Need to Add

1. Repository Secrets
   In Settings → Secrets and variables → Actions, add:

   Name	Value
   DISCORD_BOT_TOKEN	Bot’s token
   DISCORD_CHANNEL_ID	Channel ID for news/announcements
   DISCORD_FREE_CHAPTERS_CHANNEL	Channel ID for free-chapter posts
   DISCORD_ADVANCE_CHAPTERS_CHANNEL	Channel ID for paid-chapter posts
   DISCORD_COMMENTS_CHANNEL	Channel ID for comment posts

2. Dependencies
   Ensure your CI/workflow install step includes:

   pip install discord.py feedparser python-dateutil aiohttp

🔗 Triggering

These scripts are invoked by your rss-feed repository workflows, and can also be scheduled by cron.

📷 How It Looks

Advance Chapters	Free Chapters
Comments

---

🆕 UPDATE: New Novel Updates Analytics (v4)

• You can now receive announcements from Novel Updates to know about:
  • New comments.
  • Weekly readers' statistics.