7 Commits
Author SHA1 Message Date
dgtlmoonandClaude Opus 5.5 712b3e2772 Plugins - select_fetch_backend and recheck_seconds_override hooks, with a fallback fetcher example plugin (#4652)
* 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>
2026-11-03 13:36:49 +01:00
dgtlmoonandClaude Opus 5.5 a6e3251251 Settings - AI / LLM settings get their own page at /settings/llm, linked from the left sidebar (#4637)
* 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>
2026-10-30 21:34:05 +01:00
dgtlmoonandClaude Opus 5.5 73e4b22de9 Plugins - register_blueprints hook so plugins can mount their own Flask blueprints (#4632)
* 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>
2026-10-30 15:08:26 +01:00
dgtlmoonandClaude Opus 5.5 11c7ca8719 API Examples (#4625)
* 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>

* Restock charts - Pluggy hooks so a plugin can replace either restock price chart (#4623)

restock_diff now has its own plugin hooks (processors/restock_diff/hookspecs.py):
  restock_diff_watchlist_overview_chart(series, currency, summary, watch)
  restock_diff_watch_history_page_chart(series, currency, summary, watch)
firstresult, returning the chart HTML. The existing charts are the built-in implementation
(plugins/default_charts.py, trylast), so any plugin implementing a hook replaces that chart.

- Processors can add plugin hooks: register_plugin_hooks(plugin_manager) in the processor package,
  called for every installed processor at startup (processors.register_processor_plugin_hooks()).
  Core doesn't name restock_diff.
- New processor-aware /diff/<uuid>/processor-chart?context=watchlist|history serves the chart HTML,
  loaded by the history page and the watch list roll-down. The table still uses /processor-data.
- The built-in chart carries its data and strings (templates/restock_diff/chart_default.html), drawn by
  window.initRestockGraphs(). The roll-down no longer depends on window.watchOverviewI18n, which was
  only output with an LLM configured, so its chart labels fell back to English otherwise.
- Example plugin example_plugins/restock/simple_svg_chart replaces both with a server-drawn SVG line.
- Translations: strings only moved between templates, catalogs updated, no translation changed.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:09:42 +01:00
dgtlmoonandClaude Opus 5.5 b40193b080 Example plugins - API fetcher and check stats, watch list notes hook, update_finalize fix (#4622)
* 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>
2026-10-29 16:44:03 +01:00
dgtlmoonandClaude Opus 5.5 c0b9320ef3 Example plugins - Each example is a standalone pip install . package, README per example
- processor/wordcounter has its own pyproject.toml (changedetectionio entry point, api.yaml as package
  data) and package cdio_example_wordcounter. Checked: installed, changedetection.io loads it through
  the entry point, lists word_counter and merges its API schemas.
- The test imports it as its own top-level package, the way an installed copy is.
- README: a short section per example - what it does, the hooks it implements, how to install and try it.
- The main wheel still ships the examples as files only, cdio_example_wordcounter isn't importable
  unless installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 15:37:01 +01:00
dgtlmoonandClaude Opus 5.5 ed9c418852 API - Extend 'processor' API - Current restock price/stock state in watch GET and list (processor_state_{processor_name}) (#4621)
* 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>
2026-10-29 15:34:28 +01:00