Docs(api): docs differ from api call for getUnread

  • [X] I’m using stock docker compose setup, unmodified.
  • [ ] I’m using docker compose setup, with modifications (modified .yml files, third party plugins/themes, etc.) - if so, describe your modifications in your post. Before reporting, see if your issue can be reproduced on the unmodified setup.
  • [ ] I’m not using docker on my primary instance, but my issue can be reproduced on the aforementioned docker setup and/or official demo.

Describe the problem you’re having:

I made a small chrome extension to show unread rss items, since using it i noticed i get errors on tt-rss.
I used getUnread to get the number of unread items.
The error shows:

Undefined array key "fresh"
1. classes/handler/public.php(263): ttrss_error_handler(Undefined array key "fresh", classes/handler/public.php)
2. public.php(50): getUnread()

Forwarded For: Removed
Forwarded Protocol: https
Remote IP: Removed
Request URI: /tt-rss/public.php?op=getUnread&login=Removed
User agent: Removed -> chromium

I checked the docs for the api in the following places:
Gitlab Wiki
Site FAQ
Site ApiRef

All of those don’t include the “fresh” parameter (or array key which we will see shortly)

I know my way around code so i went to the gitlab repo and found out that in /classes/handler/public.php the getUnread function tries to use the “fresh” parameter on line 263
Here is a snippet:

	function getUnread(): void {
		$login = clean($_REQUEST["login"]);
		$fresh = clean($_REQUEST["fresh"]) == "1"; // <= not in docs :O

		$uid = UserHelper::find_user_by_login($login);

		if ($uid) {
			print Feeds::_get_global_unread($uid);

			if ($fresh) {
				print ";";
				print Feeds::_get_counters(Feeds::FEED_FRESH, false, true, $uid);
			}
		} else {
			print "-1;User not found";
		}
	}

I think this should be added to the api docs/FAQ and you might also be able to make “fresh” optional to save a tiny bit of bandwidth (i doubt its worth the focus tho).

Include steps to reproduce the problem:

  1. Call getUnread with the following path: /public.php?op=getUnread&login=[INSERT-USERNAME] as required by the docs.
  2. Get a shiny new error to show up in your tt-rss instence.
  • Tiny Tiny RSS version (including git commit id): v23.05-a4543de3a
  • Platform (i.e. Linux distro, Docker, PHP, PostgreSQL, etc) versions: Docker running on Archlinux host.

Provide any additional information below:

Love this project and want to thank everybody who helped.
I did not notice there is already an extension, does it work with TLS/SSL client authentication?

ironically enough, this endpoint was added (long before current API became a thing…) because of a chrome addon - https://gitlab.tt-rss.org/tt-rss/tt-rss-notifier-chrome

anyway, fresh parameter is not mandatory, so it should be updated to php8 by adding ?? 0 or something of this sort. also, faq should mention it.

i’ll make a note to do both.

nope, unless chrome handles this transparently somehow for specific URL.

e: https://gitlab.tt-rss.org/tt-rss/tt-rss/-/commit/a28d9582e8f36caa40ac2fea05d0af21b071f75b