What use case are you thinking about? The Special:Notifications page? The badges? They already both have a way of updating themselves, why would you need a function? Is there a specific gadget you're thinking about that needs to use it specifically?

I'm looking to update #pt-notifications-alert and #pt-notifications-notice with gadgets, yes.

Opening them updates them already, so I assume you mean you want to update their counters?

There's a way to do that, but the main issue is that we "lazy load" the javascript that controls the popups, so essentially you get raw html from the server on load (and that's static) and only after you click one of the badges for the first time, we load all the scripts and do the updates. After the first load, the javascript is there and you can call a method to update the counters fairly easily, but that requires an initial load.

If you want to update those counters without loading the scripts, you'll need your gadget to do it on its own using the API (which is what the echo script does too, when it updates the counters) and then inject those numbers into the html of the badges.
Beware that the number must be updated the data attributes (there are two) once raw numbers, and once for translation of the number for view) as well as the text of the badge, otherwise the css will fail on them.

I can help with that if you have a prototype going.

I know it is complicated right now and that's exactly what this task is about: creating and exposing an easy-to-use function so that gadget authors don't have to "inject those numbers into the html of the badges".

In T168570#3368942, @Nirmos wrote:

I know it is complicated right now and that's exactly what this task is about: creating and exposing an easy-to-use function so that gadget authors don't have to "inject those numbers into the html of the badges".

It's not complicated with a gadget, though, that's what the badges do; when you open the popup, the controller asks for the counter by API request, then updates the badge numbers.

Having a function in Echo won't help you, since Echo isn't loaded immediately anyways - so that function won't be available to the gadget even if we set it up.

The Echo system does this with OOjs-UI widgets because when we load for the first time we replace the raw html with ooui widgets -- but it is essentially the same.

Replacing the values of data-* in the badges is not insane at all, it's fairly straight forward. Take a look at mw.echo.ui.BadgeLinkWidget.prototype.setCount :

		this.$element
			.toggleClass( 'mw-echo-notifications-badge-all-read', !numItems )
			.toggleClass( 'mw-echo-notifications-badge-long-label', label.length > 2 )
			.attr( 'data-counter-num', numItems )
			.attr( 'data-counter-text', label );

Where label is using mw.message( 'echo-badge-count', mw.language.convertNumber( numItems ) ).text();

This is fairly straight forward to do directly on the HTML element from a gadget.

@Nirmos I am not 100% sure where you're going with this, but in an effort to help, I created a quick and dirty gadget for you to use as a basis for whatever you need. I did end up loading mw.echo.api module, for convenience, and the required i18n message.

The gadget is available here: https://www.mediawiki.org/wiki/User:Mooeypoo/NotificationsTest.js

If your intention is to create a gadget that periodically updates the count (like "push" notifications) then you can add something like setInterval( function () { /* put both callers for echoApi.fetchUnreadCount(..) here */ }, seconds ). It should work. I outputted the result to the console so you can test it.

Let me know if there's anything you need that I can help with!

@Nirmos: Did the last comment help?

I don't think that that kind of logic belongs in a gadget. I also wouldn't be able to update it in the event that it stops working as it requires deep understanding of the inner workings of Echo and the rest of MediaWiki.

This is being worked on in T219222, so I'm closing this one as a duplicate.