* Plugins - select_fetch_backend and recheck_seconds_override hooks, with a fallback fetcher example plugin
select_fetch_backend lets a plugin pick another fetcher for one check: before it, or as a single
immediate retry after the fetch failed (e.g. the site answered 403). The watch's settings are never
changed. recheck_seconds_override gives a plugin the last word on the recheck time, after system,
group and watch, used by the scheduler and the overdue count.
The fallback fetcher example registers a fetcher for a generic scraping API, retries blocked checks
through it, then keeps the watch under its control for a while with a minimum recheck time and a
note in the watch list. Plugin API 0.6.0, which also exports Non200ErrorCodeReceived.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Plugins - chain fallback fetchers by priority, plus a daily limit, stats page and recheck widget in the example
select_fetch_backend now collects every plugin's offer (a name, or {'backend', 'priority'}) and core
tries them lowest priority first, skipping fetchers already tried in this check (new 'tried' argument),
up to FETCH_FALLBACK_MAX_ATTEMPTS retries (default 3). The last error is shown when they all fail.
The fallback fetcher example:
- a Priority setting, and it doesn't offer itself when over its daily limit, so the next one goes
- 'Most successful calls in 24 hours', counted in its own {datastore}/<plugin>-state.json
- takes a watch over only once a fallback fetch through it worked
- the minimum recheck time uses core's TimeBetweenCheckForm widget, fixed read-only by
EXAMPLE_FETCHER_HELLOWORLD_TIME_BETWEEN_RECHECK_MINIMUM_SECONDS when set
- a 'Fetch stats' page with a sidebar icon
Core: plugin_api exports TimeBetweenCheckForm and time_between_check_to_seconds (now also used by
Watch.threshold_seconds), and plugin settings tabs show each field's description.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Settings - AI / LLM settings get their own page at /settings/llm, linked from the left sidebar (new register_sidebar_items hook)
/settings was getting crowded. The AI / LLM tab moves to its own page, /settings/llm, still stored in
settings.application.llm. It has one "AI / LLM" tab for now; an MCP tab will join it.
- blueprint/settings/llm.py becomes the package blueprint/settings/llm/, the page template is
llm/templates/llm-settings.html (the old settings_llm_tab.html content). The save logic moved over as it was
(blank key keeps the stored one, env overrides, protected counters).
- New pluggy hook register_sidebar_items(datastore): plugins add links to the left action sidebar (label,
endpoint or URL, Feather icon, tooltip, active prefix, weight). Each one is preceded by
<!-- blueprint:module.path --> naming the plugin that added it. Bad entries are logged and skipped.
- The AI / LLM link is added through that hook by a built-in plugin.
- LLM_FEATURES_DISABLED: the page and its link aren't registered when it's set at startup, and the page
404s / the link is hidden when it's set later.
- Links that went to /settings#ai now go to the new page; LLM tests save through it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* CI - run the register_sidebar_items hook test
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Sidebar items can be disabled with a badge, or use their own svg icon; the AI / LLM link gets an octopus
register_sidebar_items entries can now set:
- 'disabled': True - greyed out and not clickable, rendered like the built-in "Browsers (coming soon)"
item (href="#", is-disabled, aria-disabled, tabindex -1), no endpoint or URL needed
- 'badge' - a small label after the text, e.g. 'soon'
- 'svg' - their own inline icon instead of a Feather one (trusted plugin markup, never user input)
The AI / LLM link uses a simple octopus drawn in the Feather style (24x24, 2px currentColor line).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Sidebar - the AI / LLM link's icon is Feather's cpu chip with "AI" in the middle, instead of the octopus
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Example plugins - hello_world links its page from the left sidebar (register_sidebar_items), plugin API 0.5.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Plugins - register_blueprints hook so plugins can mount their own Flask blueprints
A plugin returns a Blueprint, a dict ({'blueprint', 'url_prefix', 'login_required'}) or a list of
either. Routes need the same optional password login as the rest of the UI unless the plugin
explicitly passes 'login_required': False. Blueprints are registered after the built-in ones, and a
bad entry or a name clash is logged and skipped rather than stopping the app from starting.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Example plugins - hello_world, its own page inside the normal app layout via register_blueprints
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Plugins - plugin API 0.4.0 (adds the register_blueprints hook)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Example plugins - API fetcher and check stats examples, watch list notes hook, update_finalize fix
New hook watch_list_extra_text(watch) (ported from browser-ui): short plain-text notes under each watch
in the watch list, escaped when rendered.
New example plugins, each `pip install .`-able and importing only from plugin_api:
- fetcher/api_fetcher: register_content_fetcher, plugin_settings_tab, fetcher_status_icon, plugin_static_path
- lifecycle/check_stats: update_handler_alter, update_finalize, watch_list_extra_text, ui_edit_stats_extras,
get_html_head_extras, plugin_static_path
- processor/wordcounter: also shows "Found: N words" in the watch list via watch_list_extra_text
Fixes found by the examples:
- update_finalize always got update_handler=None after a successful check (the worker deleted the handler
before the finally block captured it), so update_handler_alter + update_finalize couldn't be paired
- The API rejected plugin fetchers in 'fetch_backend' (hardcoded pattern), now built from installed fetchers
- fetcher_status_icon docstring said it returns HTML, it returns a dict
plugin_api 0.3.0: exports Fetcher and load_plugin_settings.
Tests check each example end to end, including that it's listed under Settings > Info.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Example plugins - Rename the fetcher example to fetcher/example_browser_fetcher
"Example browser fetcher": an extra fetcher that gets pages through its own API. Package
cdio_example_browser_fetcher, fetch method html_example_browser_fetcher.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Example browser fetcher - Return a screenshot (random noise PNG, standard library only)
Shows the screenshot side of a fetcher: supports_screenshots = True and self.screenshot set to PNG bytes,
saved as last-screenshot.png. The test checks it's served as a valid 240x160 PNG.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* API - Add processor_state_{processor_name} to watch GET and list (current restock price/stock)
The current restock/price state (watch['restock']) was hidden from the API, the only way to
see it was parsing the "In Stock: True - Price: 19.99" history snapshot text.
- New pluggy hook get_api_watch_processor_state(watch, processor_name, context), core picks
the response key processor_state_{processor_name} so a plugin can't overwrite other fields
- restock_diff implements it (in_stock, price, currency, last_price)
- processor_state_* is returned on GET /api/v1/watch/{uuid} and on each item of GET /api/v1/watch,
the list items also gain 'processor'
- processor_config_{name} resolution is now generic in core instead of restock-specific code in
api/Watch.py, still single watch GET only (disk read), and only for the watch's own processor
- A processor_state_{name} schema in a processor's api.yaml is merged into Watch as readOnly
- GET -> PUT round trips no longer save processor_config_*_source into the processor config file
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* API - Accept every installed processor (plugins, image_ssim_diff) in the watch 'processor' field
The static spec enum only listed restock_diff and text_json_diff, so a plugin processor (and the
built-in image_ssim_diff) couldn't be set on a watch via the API. The merged spec now fills the
enum from find_processors(). Also corrects the register_builtin_restock_plugins() docstring, it is
only called from main().
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Add example processor plugin (word counter), and mark the processor storage problem
changedetectionio/example_plugins/processor/wordcounter is a working processor plugin to copy:
register_processor, processor.py, api.yaml (processor_config_word_counter / processor_state_word_counter)
and get_api_watch_processor_state. Nothing scans example_plugins/, it is only active when registered.
The new test registers it the same way a pip-installed plugin is, then creates a watch via the API and
checks processor_state_word_counter on the watch GET and list, the GET -> PUT round trip and the snapshot.
Shipped in the sdist via MANIFEST.in.
Processors have no storage of their own for what a check found, update_obj is merged straight into the
watch. Marked with @IMPORTANT-TODO where it shows up, the fix is planned as its own PR for a new release.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* plugin_api - Export what a processor plugin needs, example plugin uses only the public API
- plugin_api exports difference_detection_processor, get_resolved_processor_config and html_to_text,
lazily (module __getattr__) so importing plugin_api stays cheap. PLUGIN_API_VERSION 0.1.0 -> 0.2.0
- The word counter example and the restock api_state plugin import only from plugin_api
- Fix: importing plugin_api before anything else in the package was a circular import (plugin_api ->
pluggy_interface -> built-in conditions plugins -> plugin_api.hookimpl). The hookimpl marker now lives
in plugin_api and pluggy_interface imports it from there.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* plugin_api - Declare the lazy exports under TYPE_CHECKING so ruff F822 (and IDEs) see them
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Test - plugin_api cheap-import check runs the fresh interpreter from the package's parent dir
CI runs pytest from inside changedetectionio/, where a new interpreter can't import the package.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>