Library / SDK
wangwangit/SubsTracker avatar
wangwangit/SubsTracker

SubsTracker: exact-day reminders, an hourly send window, and three channel counts

A lightweight subscription management system built on Cloudflare Workers that helps you track expiration dates of various subscription services and sends timely reminders via Telegram.

3,289 stars2,667 forksJavaScriptMIT

At a glance

What is it?
wangwangit/SubsTracker is a Cloudflare Workers plus KV subscription expiry tracker written in JavaScript on Hono, whose documentation is precise about almost everything except the two places that decide whether a warning is ever delivered: exact-day rule matching and the allowed send hours.
Who is it for?
Use it if you run one Cloudflare account for yourself and you will read the compose-free deploy script and the config JSON rather than trusting the quick start.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 44 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • wangwangit/SubsTracker3,289 ★ · +58
Star history
Repository2026-09-242026-11-22
wangwangit/SubsTracker3.2k3.3k

58 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Three different channel counts for one feature list

The opening line says reminders go out through Telegram, Bark, WeCom, ntfy and 11 kinds of channel in total. The feature section is headed Notification Channels with the number 10 in brackets, and the list under it then names eleven: Telegram, NotifyX, Webhook, WeCom, Resend email, Bark, Gotify, ServerChan, PushPlus, ntfy and WPUSH. So the same repository states a count of eleven, a heading claiming ten, and a list of eleven in the space of about forty lines.

The setup table narrows it again. The table of channels you need to prepare covers seven: Telegram needs a bot token and a chat id with an optional topic id for forum groups, Bark needs a device key with an optional self-hosted server, WeCom needs a group robot webhook, ntfy needs a server defaulting to ntfy.sh plus a topic with an optional token, WPUSH needs an API key with optional channel and topic codes, email needs a Resend key plus sender and recipient addresses, and Webhook needs any HTTP address with an optional template.

That leaves four of the eleven with no configuration row at all: NotifyX, Gotify, ServerChan and PushPlus. The FAQ then adds a dedicated entry for Telegram topic routing, one for ntfy and one for WPUSH, where the success condition is spelled out as the API returning code equal to zero. Nothing covers the remaining channels past the bare name in the list, so a user who picks ServerChan is working from a single word.

The repository has 3236 stars, 2578 forks and one open issue. That fork count is close to four fifths of the star count, which is what a fork-to-deploy-your-own-copy project looks like, and it also means the feature set is exercised by a lot of separate installations rather than by a lot of issue threads.

Exact-day rules plus an hourly send window can drop a warning for good

Reminder rules are exact-day matches, and the README flags this as something many people misread. A rule of N days before expiry fires on the single day when the remaining days equal exactly N. It will not repeat every day from N onwards. The default preset set is 7, 3 and 1 day before expiry plus the day itself, and if you want 7, 6, 5 you need one rule per day.

Now put that next to the send window. A scheduled handler runs once an hour on the hour, the cron expression is 0 * * * *, and it fires on UTC while the decision about whether to send uses the timezone you configured. The allowed hours field is what that decision consults: 08 means only the 8 o'clock hour is permitted, 08, 20 means those two hours are permitted, and leaving it empty or setting it to a wildcard permits every hour.

Combine the two and a rule can be missed permanently. Suppose a subscription expires in seven days and your only allowed hour is 08. The hourly run evaluates it at every hour of that day, and twenty-three of those runs are refused by the window. If the 08 run is the one that matches, the warning goes out and the same-day dedup suppresses any repeat. If anything about that single hour prevents it, the seven-day warning is gone, because nothing re-evaluates a past day. The same applies to the day-of-expiry rule.

The troubleshooting table does not mention this outcome. Its row for having no relevant record at all offers two explanations: the hourly check may not have run yet, or the rule did not match. Neither is the case where the check ran, the rule matched, and the window refused it, and there is no backfill step described anywhere.

The allowed hours list is documented as a window, a twice-a-day plan and a multi-send switch

Three sections of the README answer the question of what happens when you list more than one allowed hour, and the three answers disagree.

The first answer is in the configuration table. A value of 08, 20 is glossed as early morning 8 and evening 8, each possibly sending once, which reads as two opportunities a day.

The second answer is in the section explaining how notification actually works. There it says that with 08, 12 configured, once the same day-level rule has matched it will normally only send at 08, that 12 will not send a duplicate, and that this is not a plan to send twice a day. The hours are described as a permission window rather than a schedule, so the first permitted hour after a match wins and the rest are wasted.

The third answer is in the troubleshooting table, whose row for wanting more than one reminder per day tells you to write several hours such as 08, 12 and 20, or to leave the field empty. On the second reading that advice cannot work for a day-precision rule, because dedup is defined as not resending the same rule on the same day.

The rule type that does produce repeats is a different one. A post-expiry rule reminds every X hours until you renew, and the README notes that it is constrained by the allowed hours field. So the mechanism that yields multiple daily reminders is the rule type, not the width of the window, and the troubleshooting row points at the wrong control. Related to all of this: the configuration page shows a live preview of whether it would send right now, and the README warns that the preview only agrees with the server after you save.

The third-party notify token travels in the URL path

Any system that wants to push a message through SubsTracker generates a third-party API token in the configuration page and then calls one endpoint:

bash
curl -X POST "https://你的域名.workers.dev/api/notify/你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"title":"标题","content":"正文"}'

The token is the last path segment of the URL. It is also accepted as a header, since the README adds that an Authorization bearer header works too, which makes the path form a convenience rather than a requirement.

Putting a bearer secret in a path is the part worth arguing about. A path segment ends up in server access logs, in any proxy log between the caller and the Worker, in the browser history of anyone who pastes the URL into a bar, and in the Referer header of any request that page makes afterwards. On a Cloudflare Worker the request log is not yours, so a token that identifies your notification endpoint ends up in infrastructure you do not operate. The header form avoids all of that and is documented in the same three lines, so the choice is available.

Authentication on that endpoint is possession of the token and nothing else. There is no second factor, no scope, no expiry and no per-token rate limit described, so a leaked token is a permanently usable send capability against whatever channels your configuration has enabled.

The admin credential is stored the same self-service way. Password recovery is documented as opening the SUBSCRIPTIONS_KV namespace in the Cloudflare dashboard, editing the config key's JSON and changing ADMIN_PASSWORD. That means the password is a field in a JSON blob in KV, and recovering access means hand-editing a document in a web console rather than running anything in the application.

deploy:safe creates the KV namespace, not the credentials

The recommended install path is four commands and one environment variable:

bash
git clone https://github.com/wangwangit/SubsTracker.git
cd SubsTracker
npm install

# Linux / macOS
export CLOUDFLARE_API_TOKEN=你的token
# Windows PowerShell
# $env:CLOUDFLARE_API_TOKEN="你的token"

npm run deploy:safe

The script behind the last line is defined in package.json as npm run setup followed by npm run deploy, where setup runs node scripts/setup-kv.cjs and deploy runs npx wrangler deploy. So the safe in the name covers creating and binding the SUBSCRIPTIONS_KV namespace and then deploying the Worker. It says nothing about credentials.

The Worker comes up with a fixed default login, and the README puts it in a table: username admin, password password. Its own warning is that exposing the default password publicly leads to takeover, and the five-minute flow makes changing it the second step, after the Worker is already reachable at the printed https://subscription-manager.<your subdomain>.workers.dev address. Between the deploy command returning and the password being changed there is a window in which a publicly resolvable hostname serves a known password, and nothing in the flow shortens it automatically.

There is a second install path with a different credential footprint. Forking the repository and adding CLOUDFLARE_API_TOKEN as a GitHub Actions secret, with CLOUDFLARE_ACCOUNT_ID optional, deploys from a workflow that runs on a push to master or main or on a manual Deploy run. The same Cloudflare token that sits in your shell for the command line path ends up stored as a repository secret in a fork, where anyone who can push a branch can trigger a job that holds it.

Deploy failures are documented in one FAQ entry: Authentication error with code 10000, attributed to insufficient token permissions or a Wrangler cache problem, fixed by checking the token permissions and deleting .wrangler. The token needs Workers edit plus KV edit. The repository publishes no GitHub releases at all while package.json declares version 3.0.0, so there is no tag to roll back to; upgrading is git pull, npm install and deploy:safe.

npm run lint is a type check and npm run build is an echo

The two script names that promise quality control deliver something else. build is defined as echo 'No build step required for Workers runtime', which is correct for a Workers deployment and means the script exists only so that tooling expecting a build step finds one. lint is defined as tsc --noEmit -p jsconfig.json, which is a TypeScript type check pointed at a JavaScript codebase through jsconfig.json. There is no ESLint and no Prettier in devDependencies, so nothing checks formatting, unused variables as a linter would, or style.

The runtime dependency list is a single entry, hono at ^4.6.14. Eleven notification channels, a scheduler, JWT handling, a lunar calendar and a currency layer are all built on that one framework and the platform fetch. The development side is five packages: the Cloudflare vitest pool for workers, Cloudflare workers types pinned to a December 2024 build, TypeScript at ^5.7.2, Vitest at ~2.1.9 and Wrangler at ^3.99.0.

The development block shows how the pieces are run locally:

bash
npm install
npm test           # 单元 / 集成测试
npm run lint
npx wrangler dev --config wrangler.dev.toml --local
# http://127.0.0.1:8787  默认 admin / password

Wrangler is pointed at a second configuration file, wrangler.dev.toml, alongside the deployment wrangler.toml, and the local server is documented at http://127.0.0.1:8787 with the same admin and password defaults as production.

The layout the README prints for the source is worth reading as a responsibility map. core/ holds time, lunar calendar, currency and JWT. data/ holds KV and migrations. services/ holds the scheduler and the notification channels. views/ holds the admin HTML. migrations live under data/ and the README says the schema migration runs automatically on first access after an upgrade, which means a version bump takes effect on the first request rather than at deploy time, and no rollback path is described for a migration that changes stored keys.

Two of the thirteen FAQ entries are about a browser serving a stale deploy

The FAQ has thirteen entries. Two of them are about the same underlying problem: the admin page is serving cached assets after a redeploy.

The first is the reminder column on the subscription list showing the wrong summary, such as a constant seven days ahead. The advice is to force refresh with Ctrl+Shift+R, and if that does not work, to open the browser developer tools, go to Network, look at the subscriptions request and check whether the response contains reminderRulesSummary. That is a debugging procedure for a response the server is not sending, not for a page the browser is holding on to.

The second is the clone button being invisible or uncoloured. The advice is again a hard refresh, and if the button shows only as grey text, to confirm that a build including the theme styles has been deployed. That answer admits a deploy can go out without the styling, which means the theme CSS is produced as part of the deploy rather than served from a versioned asset URL.

A third entry belongs in the same family. A console error mentioning beacon.min.js or cloudflareinsights is explained as the Cloudflare statistics script rather than project code, and as something that can generally be ignored. That is an acknowledgement that analytics is running on your deployment. It appears nowhere in package.json, nowhere in the dependency list and nowhere in the feature list, and the README does not say what it collects or how to turn it off, so an operator reading the repository has no signal that their Worker reports usage to Cloudflare.

Taken together, the three entries describe an admin UI with no cache-busting strategy, deployed theme assets, and a third-party beacon switched on outside the code the reader can see.

Renewal mode is specified only for the subscription that has not expired yet

Subscriptions carry one of two renewal modes and the difference is where the date comes from. Under a recurring mode, if the subscription has not yet expired the new period is appended to the current expiry date, so a membership expiring on 15 June and renewed on 3 June lands around 15 July. Under an expiry reset, a full period is recalculated from the payment date, which is what a number-retention card wants, where topping up restarts 180 days from the day you paid.

The recurring definition opens with a condition: if not yet expired, extend from the current expiry date. What happens when it has already expired is not stated. Renewing a subscription that lapsed three days ago either extends from the stale date, which puts it in the past, or from today, which is a third behaviour. The example given, and the only one, is the early-renewal case, which is also the case where the two modes agree least.

The same conditionality shows up in the calendar options. Periods offer quarterly, half-year and yearly shortcuts, which are three, six and twelve months. A last-day-of-month option exists for the Gregorian calendar, with the note that it is not used under the lunar calendar, so a subscription tracked by lunar date cannot be pinned to a month end even though both calendars are supported and core/ contains a lunar calendar module.

Two more conventions are worth carrying into any import. The backup export is a JSON file with a choice about whether secrets are included, and importing has two modes: merge overwrites subscriptions that share an ID and keeps everything else, while overwrite clears the whole namespace first and is labelled dangerous. Separately, the finance dashboard's spend totals depend on payment records and exchange rates, with a fallback when the rate service fails, and the basis of that fallback is not described, so a total can change meaning between runs.

Editorial conclusion

Use it if you run one Cloudflare account for yourself and you will read the compose-free deploy script and the config JSON rather than trusting the quick start. Three things to settle before you rely on it: change the admin password in the same sitting as the deploy rather than after it, decide whether listing several allowed hours is meant to send several times a day or merely to widen a window, and test the exact-day rules against a subscription expiring inside a week so you can see the skip reasons in the notification history. Avoid it for anything multi-user, which the README itself rules out, and keep the third-party token out of URLs.

Frequently asked questions

What are the default SubsTracker login credentials?

Username admin and password password, both of which the README prints in a table and asks you to change immediately in the system configuration page. It states plainly that leaving the default password exposed publicly leads to takeover, and the local development server on port 8787 uses the same pair.

How many notification channels does SubsTracker actually support?

The opening line claims 11, the feature section is headed with the number 10, and the list beneath it names eleven: Telegram, NotifyX, Webhook, WeCom, Resend email, Bark, Gotify, ServerChan, PushPlus, ntfy and WPUSH. The setup table gives configuration rows for seven of them, and the FAQ has a dedicated entry only for Telegram topics, ntfy and WPUSH.

Why did SubsTracker not send my seven day reminder?

A reminder of N days before expiry fires only on the day the remaining days equal exactly N, and it does not repeat on the days after that. The hourly handler runs on 0 * * * * but only sends during the hours you allow, so if the matching hour was skipped the rule produced no record to retry from. Dedup is per rule per day, so a second attempt the same day is suppressed.

Can another system send notifications through SubsTracker?

Yes, with a third-party API token generated in the system configuration. POST to https://your domain.workers.dev/api/notify/your token with a JSON body containing title and content, or send the same token as an Authorization bearer header. There is no documented expiry, scope or rate limit on such a token.

How do I recover the SubsTracker admin password if I forget it?

Through Cloudflare rather than the app: open Workers and Pages, then KV, then the SUBSCRIPTIONS_KV namespace, and edit the config key's JSON to change ADMIN_PASSWORD. The credential is a field in that stored document, so recovery means editing JSON in a web console.

Does SubsTracker publish tagged releases?

No. The repository has no GitHub releases, while package.json declares version 3.0.0. Upgrading is documented as git pull, npm install and npm run deploy:safe, and the first request after that deploy performs the KV schema migration automatically.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. wangwangit/SubsTracker on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/wangwangit-substracker.svg)](https://hysenlabs.com/projects/wangwangit-substracker)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/wangwangit-substracker.svg)](https://hysenlabs.com/projects/wangwangit-substracker)

Was this useful?