refactor: introduce provider abstraction for multi-platform lock support

[raman325]

Summary

This PR introduces a provider abstraction layer to enable support for multiple lock platforms. The architecture allows adding support for additional platforms without modifying core keymaster code.

Breaking change

None. Existing Z-Wave JS configurations continue to work unchanged. The provider is automatically detected and instantiated based on the lock entity's platform.

Proposed change

Architecture

• Created providers/ module with:
  • _base.py - BaseLockProvider abstract base class and CodeSlot dataclass
  • __init__.py - Provider registry and factory functions
  • zwave_js.py - Z-Wave JS implementation (extracted from coordinator)
  • PROVIDERS.md - Developer guide for implementing new providers

Key Changes

1. Provider Interface: New BaseLockProvider ABC defines required methods:

   • async_connect() - Connect to lock
   • async_is_connected() - Check connection status
   • async_get_usercodes() - Get all codes from lock
   • async_get_usercode() - Get a specific code (may return cached data)
   • async_refresh_usercode() - Bypass cache and query device directly (for integrations with caching)
   • async_set_usercode() - Set a code slot
   • async_clear_usercode() - Clear a code slot

2. Capability Flags: Providers declare capabilities:

   • supports_push_updates - Real-time lock/unlock events
   • supports_connection_status - Connection monitoring

3. Coordinator Refactoring:

   • Removed direct Z-Wave JS imports and API calls
   • Uses provider methods for all lock operations
   • Provider handles event subscription internally

4. Config Flow Improvements:

   • Now filters lock entities to only show supported platforms
   • Added generic filter_func parameter to _get_entities for extensible filtering
   • Prevents users from selecting unsupported locks

5. Entity Updates:

   • binary_sensor.py and switch.py use async_has_supported_provider()
   • Connection sensor only created when provider supports it

Files Changed

New Files:

• providers/__init__.py - Registry and factory
• providers/_base.py - Base classes
• providers/zwave_js.py - Z-Wave JS provider
• providers/PROVIDERS.md - Developer documentation
• tests/providers/ - Provider-specific tests

Modified Files:

• coordinator.py - Use provider abstraction
• lock.py - Added provider field
• helpers.py - Added async_has_supported_provider()
• config_flow.py - Filter locks by supported platform
• binary_sensor.py, switch.py - Use new helper

Test Updates

• Added cleanup fixture to prevent JSON file corruption between tests
• Updated fixtures to patch new async_has_supported_provider function
• Rewrote coordinator event tests for provider callback interface
• Moved provider tests to tests/providers/ directory
• All 352 tests pass with 85% coverage

Type of change

• New feature (which adds functionality)

Additional information

• Developer guide included for implementing new providers
• async_refresh_usercode defaults to calling async_get_usercode - only integrations with caching (like Z-Wave JS) need to override

🤖 Generated with Claude Code

[tykeal]

YAY! @raman325 you're awesome! I'll get this onto my test system as soon as I can! I've been wanting something like this as I've been working with someone that went all Schlage WiFi locks but they are doing short term rentals. I wrote a custom automation that's really fragile to work with the lock and rental control, but if (when) this lands getting a Schlage provider in (after I get home-assistant/core#151014) merged will make it so much better!

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 81.08808% with 73 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.91%. Comparing base (a9a30ef) to head (d2d4cc5).
⚠️ Report is 13 commits behind head on beta.

Files with missing lines	Patch %	Lines
custom_components/keymaster/providers/zwave_js.py	83.68%	31 Missing ⚠️
custom_components/keymaster/providers/_base.py	77.63%	17 Missing ⚠️
custom_components/keymaster/coordinator.py	69.38%	15 Missing ⚠️
custom_components/keymaster/switch.py	82.35%	3 Missing ⚠️
custom_components/keymaster/binary_sensor.py	66.66%	2 Missing ⚠️
custom_components/keymaster/providers/__init__.py	93.93%	2 Missing ⚠️
custom_components/keymaster/config_flow.py	75.00%	1 Missing ⚠️
custom_components/keymaster/exceptions.py	50.00%	1 Missing ⚠️
custom_components/keymaster/helpers.py	85.71%	1 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             beta     #538      +/-   ##
==========================================
+ Coverage   80.86%   84.91%   +4.05%     
==========================================
  Files          19       24       +5     
  Lines        2341     2685     +344     
==========================================
+ Hits         1893     2280     +387     
+ Misses        448      405      -43     

Flag	Coverage Δ
python	84.91% <81.08%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tykeal]

I pulled the latest version of this and pushed it onto my test instance.

The good news, the new dynamic dashboards still work ;)

The bad news I see the following in the logs during startup (yes I have debug logs enabled but the ERROR isn't at DEBUG level:

2026-01-19 06:38:05.681 DEBUG (MainThread) [custom_components.keymaster.coordinator] [async_setup] Imported 1 keymaster locks
2026-01-19 06:38:05.683 DEBUG (MainThread) [custom_components.keymaster.coordinator] [unsubscribe_listeners] ZWaveTestLock: Removing all listeners
2026-01-19 06:38:05.683 DEBUG (MainThread) [custom_components.keymaster.coordinator] [update_listeners] ZWaveTestLock: Setting create_listeners to run when HA starts
2026-01-19 06:38:05.684 DEBUG (MainThread) [custom_components.keymaster.coordinator] ================================
2026-01-19 06:38:05.684 DEBUG (MainThread) [custom_components.keymaster.coordinator] [verify_lock_configuration] Verifying 01K4ZADY3CDS5DT5BVPBQYQHXP
2026-01-19 06:38:05.684 DEBUG (MainThread) [custom_components.keymaster.coordinator] ================================
2026-01-19 06:38:05.685 DEBUG (MainThread) [custom_components.keymaster.coordinator] [connect_and_update_lock] ZWaveTestLock: Provider connected (platform: zwave_js)
2026-01-19 06:38:05.685 DEBUG (MainThread) [custom_components.keymaster.coordinator] [update_lock_data] ZWaveTestLock: usercodes count: 30
2026-01-19 06:38:09.038 ERROR (MainThread) [custom_components.keymaster.coordinator] Unexpected error fetching keymaster data
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/helpers/update_coordinator.py", line 416, in _async_refresh
    self.data = await self._async_update_data()
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/config/custom_components/keymaster/coordinator.py", line 1604, in _async_update_data
    await self.hass.async_add_executor_job(self._write_config_to_json)
  File "/usr/local/lib/python3.13/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/config/custom_components/keymaster/coordinator.py", line 392, in _write_config_to_json
    json.dump(config, jsonfile)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/json/__init__.py", line 181, in dump
    for chunk in iterable:
                 ^^^^^^^^
  File "/usr/local/lib/python3.13/json/encoder.py", line 435, in _iterencode
    yield from _iterencode_dict(o, _current_indent_level)
  File "/usr/local/lib/python3.13/json/encoder.py", line 409, in _iterencode_dict
    yield from chunks
  File "/usr/local/lib/python3.13/json/encoder.py", line 409, in _iterencode_dict
    yield from chunks
  File "/usr/local/lib/python3.13/json/encoder.py", line 442, in _iterencode
    o = _default(o)
  File "/usr/local/lib/python3.13/json/encoder.py", line 182, in default
    raise TypeError(f'Object of type {o.__class__.__name__} '
                    f'is not JSON serializable')
TypeError: Object of type ZWaveJSLockProvider is not JSON serializable
2026-01-19 06:38:09.304 DEBUG (MainThread) [custom_components.keymaster.coordinator] Finished fetching keymaster data in 3.619 seconds (success: False)

What's more, when I add a PIN I see the same error. The PIN does get set (eventually) but that error does happen when the slot is first modified

[raman325]

Thanks for testing @tykeal!

Fixed in ab9c410 - the provider field was being included in the JSON serialization. It's now excluded alongside autolock_timer and listeners (which are also non-serializable runtime objects).

[tykeal]

@raman325 thanks. I pulled the latest version and now I'm getting the following during startup:

2026-01-19 09:00:40.025 INFO (MainThread) [custom_components.keymaster.coordinator] Keymaster v0.0.0 is starting, if you have any issues please report them here: https://github.com/FutureTense/keymaster
2026-01-19 09:00:40.026 DEBUG (SyncWorker_3) [custom_components.keymaster.coordinator] [create_json_folder] json_kmlocks Location: /config/custom_components/keymaster/json_kmlocks
2026-01-19 09:00:40.030 ERROR (MainThread) [homeassistant.config_entries] Error setting up entry ZWaveTestLock for keymaster
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/config_entries.py", line 762, in __async_setup_with_context
    result = await component.async_setup_entry(hass, self)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/config/custom_components/keymaster/__init__.py", line 131, in async_setup_entry
    await async_setup_services(hass)
  File "/config/custom_components/keymaster/services.py", line 33, in async_setup_services
    await coordinator.initial_setup()
  File "/config/custom_components/keymaster/coordinator.py", line 108, in initial_setup
    await self._async_setup()
  File "/config/custom_components/keymaster/coordinator.py", line 118, in _async_setup
    imported_config = await self.hass.async_add_executor_job(self._get_dict_from_json_file)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/config/custom_components/keymaster/coordinator.py", line 147, in _get_dict_from_json_file
    config = json.load(jsonfile)
  File "/usr/local/lib/python3.13/json/__init__.py", line 298, in load
    return loads(fp.read(),
        cls=cls, object_hook=object_hook,
        parse_float=parse_float, parse_int=parse_int,
        parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, **kw)
  File "/usr/local/lib/python3.13/json/__init__.py", line 352, in loads
    return _default_decoder.decode(s)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^
  File "/usr/local/lib/python3.13/json/decoder.py", line 345, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/json/decoder.py", line 363, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 410 (char 409)

Could this be because of the prior issue? I can revert to the latest version of KM, restart, and then upgrade again if you want me to try that.

[raman325]

@tykeal Yes, that's likely from the corrupted JSON file that was written before the fix. The easiest solution is to delete the corrupted file:

rm /config/custom_components/keymaster/json_kmlocks/keymaster_kmlocks.json

Then restart Home Assistant. Keymaster will recreate the file from scratch using your config entry data.

Alternatively, you could revert to beta, restart (to write a clean JSON), then upgrade again - but deleting the file is simpler.

[tykeal]

@raman325 ok, I removed the json file and restarted. Everything started worked (after I had to reset my test codes).

Tested and works:

• Adding and removing codes works
• Using the date range works

Tested and does not work:
Number of uses does not work (though I think the current release doesn't actually work either). Number never decrements. I did, however, test if it removes the code if it hits zero by manually updated the count and that does work

Not tested:
Custom days of week

[raman325]

@tykeal that should be resolved in this PR now. If you and/or @firstof9 want to retest the number of uses entity and custom days of week and confirm that it works, then I think this PR may be ready 🤞🏾

[tykeal]

@raman325 ok... so the number of uses is working.... kinda.

It seems to take about 30 seconds for it to catch up (standard entity refresh time?) So, it's technically possible to use a code multiple times even if it's set for 1 in a very short amount of time.

[raman325]

ah we probably need to write state on setting the native value of the number entity. I actually noticed that but didn't think to fix it

[tykeal]

Well, with me sitting with my test lock in my lap in a demo "door" it's real easy for me to cheese my way through 2 - 3 cycles on a '1' real quick ;)