homebridge-ring-secure-video 1.0.0-beta.4 → 1.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,51 @@
1
1
  # homebridge-ring-secure-video
2
2
 
3
+ ## 1.0.0-beta.5 (2026-11-13)
4
+
5
+ **Changes in behaviour to check after updating:**
6
+
7
+ - Automatic Ring session refresh is on by default. When it runs, a child bridge restarts itself,
8
+ a new `homebridge-ring-secure-video` entry appears in Authorized Client Devices in the Ring app
9
+ (remove the older one), and the identity in `.ring.json` changes, which other Ring plugins in
10
+ the same Homebridge (such as homebridge-ring) also use the next time they sign in from scratch.
11
+ If Ring is set to send no motion alerts in some Modes or on a schedule, set
12
+ `"automaticSessionRefresh": false`.
13
+
14
+ **New:**
15
+
16
+ - **Automatic Ring session refresh** (`automaticSessionRefresh`, on by default). Ring can stop
17
+ sending push notifications to the plugin's device identity while the connection to Google's
18
+ push service stays healthy: motion then only arrives late from the event history, and doorbell
19
+ presses not at all. When Ring's event history shows 3 motion events over at least 30 minutes
20
+ that Ring sent no push notification for, and no push notification of any kind arrived in
21
+ between, the plugin does what "Force Ring API Session Refresh" does: a new device identity and
22
+ push registration. A child bridge restarts itself for it; on the main bridge it happens at the
23
+ next Homebridge restart (dropped if a push notification arrives first). At most once a day,
24
+ and no more after 2 refreshes that brought no motion push. Not counted:
25
+ motion while snoozed, and motion without a person when the camera alerts for people only.
26
+ Needs the motion history fallback (on by default). After a refresh the log says "Automatic Ring
27
+ session refresh done", naming the Authorized Client Devices entry to remove.
28
+ - **"Ring Session Refreshed" sensor** (`sessionRefreshSensor`, off by default): a contact sensor
29
+ that opens after an automatic session refresh and closes a day later, so the Home app can
30
+ notify you (turn on its notifications; needs a home hub). Needs Automatic Ring Session Refresh.
31
+
32
+ **Fixes:**
33
+
34
+ - A child bridge that Homebridge restarted on its own (after a crash, or for the automatic
35
+ refresh) signed in with the Ring token from when Homebridge started, and couldn't save the
36
+ next one; a "Force Ring ..." setting cleared since was on again. It now takes the token and
37
+ the force settings from its block in config.json.
38
+ - New Ring tokens are also saved when the platform block in config.json is named
39
+ `"homebridge-ring-secure-video.Ring Secure Video"`; before, they weren't, and the next start
40
+ signed in with an old token.
41
+ - README: what to do when Ring's push notifications stop arriving (Troubleshooting).
42
+
43
+ **Maintenance:** dependency updates (`@homebridge/plugin-ui-utils` 2.3, ajv, globals,
44
+ typescript-eslint, concurrently 10), Homebridge 2.5 for development, and newer GitHub Actions for
45
+ CI and publishing. `@eneris/push-receiver` stays at 4.3.1 and ring-client-api at 14.3.0;
46
+ Dependabot no longer bundles them with other updates. werift stays at 0.22.4 (the version
47
+ ring-client-api pins), and Dependabot now ignores it.
48
+
3
49
  ## 1.0.0-beta.4 (2026-11-13)
4
50
 
5
51
  More fixes from the full independent review of 1.0.0-beta.2.
package/README.md CHANGED
@@ -28,6 +28,8 @@ Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reu
28
28
  | --- | --- |
29
29
  | `enableHksv` | Enables experimental HKSV support for eligible cameras; on by default, set `false` to turn it off |
30
30
  | `enableCameraMotionHistory` | Allows camera motion to fall back to recent Ring event history if push notifications don't arrive. The history is checked every `cameraStatusPollingSeconds` until motion events turn out to come by push too, then every 5 minutes as a safety net (and frequently again once a push is missed, so motion can go unreported for up to 5 minutes after push stops working); disable to only trust push-triggered motion |
31
+ | `automaticSessionRefresh` | When Ring's event history shows motion that Ring sent no push notification for (3 events over at least 30 minutes, none pushed), refreshes the Ring API session by itself, as **Force Ring API Session Refresh** does (see Troubleshooting): a child bridge restarts for it, the main bridge does it at the next Homebridge restart. At most once a day, and no more after 2 refreshes that brought no push notification. Needs `enableCameraMotionHistory`. On by default; set `false` to turn it off, for example if Ring is set to send no motion alerts in some Modes or on a schedule |
32
+ | `sessionRefreshSensor` | Adds a "Ring Session Refreshed" contact sensor that opens after an automatic session refresh (10 s after the Home app is connected to it, within 3 minutes) and stays open for a day, also across restarts (which don't notify again). Turn on its notifications in the Home app (needs a home hub) to be told when to remove the older `homebridge-ring-secure-video` entry from Authorized Client Devices. Needs `automaticSessionRefresh`. Off by default |
31
33
  | `disableHksvOnBattery` | Disables HKSV on cameras running on battery to reduce battery/network usage; wired battery models keep it. On by default |
32
34
  | `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
33
35
  | `hksvFragmentLengthMs` | HKSV fragment duration target |
@@ -163,16 +165,47 @@ For support and debugging:
163
165
 
164
166
  - Upstream Ring wiki (token/auth/camera references): <https://github.com/dgreif/ring/wiki>
165
167
 
166
- If motion and doorbell events arrive late (the log shows "Detected Motion from Ring event history
167
- fallback" rather than right away), Ring's instant notifications aren't reaching the plugin. At start the
168
- log says which `@eneris/push-receiver` the Ring push client uses ("Ring push notifications: ..."), or
169
- warns "Could not fix Ring push notifications" if the plugin couldn't give it the fixed 4.3.1. See also the upstream [notification troubleshooting](https://github.com/dgreif/ring/wiki/Notification-Troubleshooting).
170
-
171
- Use the "Force Ring Push Credential Refresh" and "Force Ring API Session Refresh" settings only as a
172
- last resort, once. Each refresh adds a registration with Ring, and repeated ones can make Ring stop
173
- sending notifications to the plugin. If that happens, remove `homebridge-ring-secure-video` from
174
- Authorized Client Devices in the Ring app's Control Center, create a new refresh token, and paste it
175
- into the plugin's settings.
168
+ ### Motion arrives late or doorbell presses are missed
169
+
170
+ If motion arrives 20–30 seconds late with "Detected Motion from Ring event history fallback" in the
171
+ log (or "Ring event history shows motion no push notification reported"), and doorbell presses don't
172
+ reach HomeKit at all, Ring's instant push notifications aren't reaching the plugin. Once they do, the
173
+ "...from Ring event history fallback" lines stop, and (with the motion history fallback on, the
174
+ default) the log says "Ring push notifications are arriving".
175
+
176
+ 1. Check that the Homebridge machine can reach Google's push service: `mtalk.google.com` must
177
+ resolve to a real address (not `0.0.0.0`; DNS ad blockers such as AdGuard or Pi-hole can block it)
178
+ and TCP port 5228 must be open. See the upstream
179
+ [notification troubleshooting](https://github.com/dgreif/ring/wiki/Notification-Troubleshooting).
180
+ 2. If the connection is fine, Ring may have stopped sending to the plugin's device identity, even
181
+ though the Ring app on your phone still gets alerts. Removing the plugin from Authorized Client
182
+ Devices and signing in again keeps the same identity (it is stored in `.ring.json`), so it may not
183
+ help. What does: turn on **Force Ring API Session Refresh** in the plugin's settings once, and
184
+ restart. The log then shows "Forcing Ring API session refresh" (and usually "Session hardware_id
185
+ not found" as Ring meets the new identity), and the setting turns itself off once the new sign-in
186
+ is saved. Then, in
187
+ the Ring app's Control Center, remove the older `homebridge-ring-secure-video` entry from
188
+ Authorized Client Devices.
189
+
190
+ With **Automatic Ring Session Refresh** on (the default) and the motion history fallback on, the
191
+ plugin does step 2 by itself when Ring's event history shows 3 motion events over at least 30
192
+ minutes that Ring sent no push notification for, and no push arrived in between. Events while
193
+ motion is snoozed, and events Ring saw no person in (which Smart Alerts may keep quiet), are not
194
+ counted. The log then says "Ring event history shows motion that Ring sent no push notification
195
+ for", and as a child bridge it restarts (on the main bridge, the refresh waits for the next
196
+ Homebridge restart, and is dropped if a push arrives first). It does this at most once a day, and
197
+ stops after 2 refreshes that brought no motion push notification, logging "Ring still sends no
198
+ push notifications after 2 automatic Ring session refreshes": then check step 1 and Authorized
199
+ Client Devices. If you have Ring send no motion alerts on purpose (for example in some Modes, or on
200
+ a schedule), turn the setting off, or the plugin will take the missing alerts for a fault.
201
+
202
+ Use the "Force Ring ..." settings only for this, and only once. Each API session refresh, automatic
203
+ or not, adds an entry to Authorized Client Devices, and many entries can themselves make Ring stop
204
+ sending notifications, so after one remove the older `homebridge-ring-secure-video` entry (after
205
+ an automatic refresh the log says "Automatic Ring session refresh done", and the optional
206
+ `sessionRefreshSensor` opens in the Home app). It also
207
+ changes the identity that other Ring plugins in the same Homebridge (such as homebridge-ring) will
208
+ use the next time they sign in from scratch, since they share `.ring.json`.
176
209
 
177
210
  ## Disclaimer
178
211
 
@@ -152,6 +152,18 @@
152
152
  "type": "boolean",
153
153
  "description": "Advanced recovery option: rotates the Ring API hardware/session identity and forces fresh push credentials on next startup. Try this when refreshing only Ring push credentials still leaves motion/button events delayed or missing. The option clears itself after the updated refresh token is saved. The identity is stored in .ring.json in the Homebridge storage folder, which other Ring plugins in the same Homebridge (such as homebridge-ring) also use, so rotating it can affect their sign-in."
154
154
  },
155
+ "automaticSessionRefresh": {
156
+ "title": "Automatic Ring Session Refresh",
157
+ "type": "boolean",
158
+ "description": "When Ring's event history shows motion but Ring has sent the plugin no push notification for it (3 events over at least 30 minutes, none pushed), the plugin does a Ring API session refresh by itself, as Force Ring API Session Refresh does: as a child bridge it restarts, otherwise at the next restart of Homebridge. Events while motion is snoozed or without a person are not counted. At most once a day, and no more after 2 that brought no push notification. Needs the camera motion history fallback. Turn this off if Ring is set to send no motion alerts in some Modes or on a schedule. Each refresh adds an entry to Authorized Client Devices in the Ring app (remove the older homebridge-ring-secure-video entries) and changes the identity in .ring.json, which other Ring plugins in the same Homebridge also use.",
159
+ "default": true
160
+ },
161
+ "sessionRefreshSensor": {
162
+ "title": "Session Refresh Sensor",
163
+ "type": "boolean",
164
+ "description": "Adds a \"Ring Session Refreshed\" contact sensor that opens after an automatic Ring session refresh (10 s after the Home app is connected to it, within 3 minutes) and stays open for a day, so the Home app can notify you (turn on its notifications; needs a home hub): then remove the older homebridge-ring-secure-video entry from Authorized Client Devices in the Ring app. Needs Automatic Ring Session Refresh.",
165
+ "default": false
166
+ },
155
167
  "enableCameraMotionHistory": {
156
168
  "title": "Enable Camera Motion History Fallback",
157
169
  "type": "boolean",
@@ -484,6 +496,8 @@
484
496
  "media",
485
497
  "forceRefreshRingPushCredentials",
486
498
  "forceRefreshRingApiSession",
499
+ "automaticSessionRefresh",
500
+ "sessionRefreshSensor",
487
501
  "enableCameraMotionHistory",
488
502
  "disableHksvOnBattery",
489
503
  "hksvVideoPreset",
package/lib/camera.js CHANGED
@@ -33,7 +33,7 @@ const ID_MEMORY_MS = 60 * 60_000;
33
33
  * a gap (5-minute checks, a failure) only events from the last 3 minutes do, as one found later
34
34
  * would only record an empty doorway.
35
35
  */
36
- export function getHistoryMotionEvents(device, pollSeconds) {
36
+ export function getHistoryMotionEvents(device, pollSeconds, pushHealth) {
37
37
  return defer(() => {
38
38
  const startedAt = Date.now() - 5000, historySeen = new Map(),
39
39
  // Events that already gave motion from here (a young one is judged again later).
@@ -47,6 +47,7 @@ export function getHistoryMotionEvents(device, pollSeconds) {
47
47
  };
48
48
  let pushWorks = false, matchedInARow = 0, lastCheckAt = 0, lastSuccessAt = 0, failureCount = 0, nextCheckAt = 0;
49
49
  const notifications = device.onNewNotification.subscribe((notification) => {
50
+ pushHealth?.recordPush(notification.android_config?.category === PushNotificationAction.Motion);
50
51
  if (notification.android_config?.category !== PushNotificationAction.Motion)
51
52
  return;
52
53
  const id = notification.data?.event?.ding?.id, now = Date.now();
@@ -115,6 +116,14 @@ export function getHistoryMotionEvents(device, pollSeconds) {
115
116
  lastCheckAt = checkedAt - HISTORY_CHECK_WHILE_PUSH_WORKS_MS + PUSH_GRACE_MS + 10_000;
116
117
  }
117
118
  if (missed.length) {
119
+ // Ring sends no alert while motion is snoozed, nor, when set to alert for people
120
+ // only, for motion it saw no person in: those say nothing about whether its
121
+ // pushes reach the plugin.
122
+ const peopleOnly = device.data?.settings?.advanced_motion_detection_human_only_mode === true, unexplained = device.data?.motion_snooze
123
+ ? []
124
+ : missed.filter((event) => !peopleOnly || event.cv_properties?.person_detected !== false);
125
+ if (unexplained.length)
126
+ pushHealth?.recordMissed(unexplained.length);
118
127
  matchedInARow = 0;
119
128
  if (pushWorks) {
120
129
  pushWorks = false;
@@ -198,11 +207,13 @@ export class Camera extends BaseDataAccessory {
198
207
  accessory;
199
208
  config;
200
209
  motionDetected;
201
- constructor(device, accessory, config) {
210
+ pushHealth;
211
+ constructor(device, accessory, config, pushHealth) {
202
212
  super();
203
213
  this.device = device;
204
214
  this.accessory = accessory;
205
215
  this.config = config;
216
+ this.pushHealth = pushHealth;
206
217
  this.cameraSource = new CameraSource(this.device, this.config);
207
218
  if (!hap.CameraController) {
208
219
  const error = 'HAP CameraController not found. Please make sure you are on homebridge version 1.0.0 or newer';
@@ -365,7 +376,7 @@ export class Camera extends BaseDataAccessory {
365
376
  return addMotionWatchdog(pushMotionEvents);
366
377
  }
367
378
  const pollSeconds = Math.max(this.config.cameraStatusPollingSeconds ?? 20, 10);
368
- return addMotionWatchdog(merge(pushMotionEvents, getHistoryMotionEvents(this.device, pollSeconds)));
379
+ return addMotionWatchdog(merge(pushMotionEvents, getHistoryMotionEvents(this.device, pollSeconds, this.pushHealth)));
369
380
  }
370
381
  async loadSnapshotForEvent(eventDescription, characteristicValue) {
371
382
  let imageUuid = this.device.latestNotificationSnapshotUuid;
@@ -0,0 +1,136 @@
1
+ import { readFileSync } from 'fs';
2
+ import { performance } from 'perf_hooks';
3
+ import { join } from 'path';
4
+ import { logError, logInfo } from 'ring-client-api/util';
5
+ import { writeFileAtomic } from "./config.js";
6
+ const stateFileName = '.ring-secure-video-push.json';
7
+ /** Motion events in Ring's history with no push notification, since the last push... */
8
+ export const MISSES_BEFORE_REFRESH = 3;
9
+ /** ...spread over at least this long (one visit can make several events)... */
10
+ export const MISS_SPAN_BEFORE_REFRESH_MS = 30 * 60_000;
11
+ /** ...give an automatic session refresh, at most once in this long... */
12
+ export const REFRESH_INTERVAL_MS = 24 * 60 * 60_000;
13
+ /** ...and no more after this many in a row that brought no push. */
14
+ export const MAX_REFRESHES_WITHOUT_PUSH = 2;
15
+ export function readPushRecoveryState(storagePath) {
16
+ try {
17
+ const state = JSON.parse(readFileSync(join(storagePath, stateFileName)).toString());
18
+ return state && typeof state === 'object' ? state : {};
19
+ }
20
+ catch {
21
+ return {};
22
+ }
23
+ }
24
+ export function writePushRecoveryState(storagePath, state) {
25
+ try {
26
+ writeFileAtomic(join(storagePath, stateFileName), JSON.stringify(state));
27
+ return true;
28
+ }
29
+ catch (error) {
30
+ logError(`Failed to save ${stateFileName}`);
31
+ logError(error);
32
+ return false;
33
+ }
34
+ }
35
+ /**
36
+ * Notices when Ring has stopped sending push notifications to the plugin while its event history
37
+ * still shows motion, and then asks for a Ring API session refresh (a new device identity and push
38
+ * registration, as "Force Ring API Session Refresh" does), which is what brings them back.
39
+ *
40
+ * Only when no push at all arrived while the misses piled up: Ring sometimes drops a single
41
+ * notification, and then a refresh would only add an entry to Authorized Client Devices.
42
+ */
43
+ export class PushHealthMonitor {
44
+ missTimes = [];
45
+ pushSeen = false;
46
+ motionPushSeen = false;
47
+ /** A refresh was asked for in this run, and no push has arrived since. */
48
+ requested = false;
49
+ /** This run's refresh has not saved its new token yet: it must stay pending. */
50
+ holdPending = false;
51
+ done = false;
52
+ loggedWaitUntil = 0;
53
+ storagePath;
54
+ refresh;
55
+ now;
56
+ elapsed;
57
+ /**
58
+ * now: the clock saved with a refresh (it must survive restarts); elapsed: the clock the
59
+ * misses are timed with, which a clock set by NTP after a boot (a Pi has no clock of its own)
60
+ * can't make jump.
61
+ */
62
+ constructor(storagePath, refresh, now = Date.now, elapsed = () => performance.now()) {
63
+ this.storagePath = storagePath;
64
+ this.refresh = refresh;
65
+ this.now = now;
66
+ this.elapsed = elapsed;
67
+ }
68
+ /** Set while this run's own refresh has not saved its new token (see connectToApi). */
69
+ setHoldPending(hold) {
70
+ this.holdPending = hold;
71
+ }
72
+ /** Any push shows they reach the plugin; only a motion push ends the refresh count. */
73
+ recordPush(isMotion) {
74
+ this.missTimes = [];
75
+ const checkPending = !this.pushSeen || this.requested, firstMotionPush = isMotion && !this.motionPushSeen;
76
+ this.pushSeen = true;
77
+ this.requested = false;
78
+ this.motionPushSeen ||= isMotion;
79
+ if (!checkPending && !firstMotionPush)
80
+ return;
81
+ const state = readPushRecoveryState(this.storagePath), update = {};
82
+ // A refresh still waiting for a restart (main bridge) is no longer needed.
83
+ if (checkPending && state.refreshPending && !this.holdPending) {
84
+ update.refreshPending = false;
85
+ }
86
+ if (firstMotionPush && state.refreshesWithoutPush)
87
+ update.refreshesWithoutPush = 0;
88
+ if (!Object.keys(update).length)
89
+ return;
90
+ writePushRecoveryState(this.storagePath, { ...state, ...update });
91
+ if (update.refreshesWithoutPush === 0) {
92
+ logInfo('Ring push notifications arrive again after the automatic Ring session refresh');
93
+ }
94
+ }
95
+ recordMissed(count) {
96
+ if (this.done || count < 1)
97
+ return;
98
+ const at = this.elapsed();
99
+ for (let i = 0; i < count; i++)
100
+ this.missTimes.push(at);
101
+ if (this.missTimes.length < MISSES_BEFORE_REFRESH ||
102
+ at - this.missTimes[0] < MISS_SPAN_BEFORE_REFRESH_MS) {
103
+ return;
104
+ }
105
+ const now = this.now();
106
+ const state = readPushRecoveryState(this.storagePath), refreshes = state.refreshesWithoutPush ?? 0;
107
+ if (refreshes >= MAX_REFRESHES_WITHOUT_PUSH) {
108
+ this.done = true;
109
+ logError(`Ring still sends no push notifications after ${refreshes} automatic Ring session refreshes; not trying again until one arrives. Check that mtalk.google.com resolves and port 5228 is open, and remove old homebridge-ring-secure-video entries from Authorized Client Devices in the Ring app (see the README, Troubleshooting).`);
110
+ return;
111
+ }
112
+ // A refresh saved later than now (one of the clocks was wrong) counts as done now, so the
113
+ // next one waits at most a day.
114
+ if ((state.lastRefreshAt ?? 0) > now) {
115
+ state.lastRefreshAt = now;
116
+ writePushRecoveryState(this.storagePath, state);
117
+ }
118
+ const nextAllowedAt = (state.lastRefreshAt ?? 0) + REFRESH_INTERVAL_MS;
119
+ if (now < nextAllowedAt) {
120
+ if (this.loggedWaitUntil !== nextAllowedAt) {
121
+ this.loggedWaitUntil = nextAllowedAt;
122
+ logInfo(`Ring sends no push notifications for motion; the last automatic Ring session refresh was less than a day ago, so the next one is due after ${new Date(nextAllowedAt).toLocaleString()}`);
123
+ }
124
+ return;
125
+ }
126
+ this.done = true;
127
+ if (writePushRecoveryState(this.storagePath, {
128
+ refreshPending: true,
129
+ lastRefreshAt: now,
130
+ refreshesWithoutPush: refreshes + 1,
131
+ })) {
132
+ this.requested = true;
133
+ this.refresh();
134
+ }
135
+ }
136
+ }
@@ -19,6 +19,9 @@ import { Fan } from "./fan.js";
19
19
  import { Outlet } from "./outlet.js";
20
20
  import { Switch } from "./switch.js";
21
21
  import { Camera } from "./camera.js";
22
+ import { PushHealthMonitor, readPushRecoveryState, writePushRecoveryState, } from "./push-health.js";
23
+ import { readFileSync } from 'fs';
24
+ import { getSessionRefreshSensorUuid, SessionRefreshSensor, } from "./session-refresh-sensor.js";
22
25
  import { PanicButtons } from "./panic-buttons.js";
23
26
  import { logInfo, useLogger } from 'ring-client-api/util';
24
27
  import { FloodFreezeSensor } from "./flood-freeze-sensor.js";
@@ -135,7 +138,8 @@ function removePushCredentialsFromRefreshToken(refreshToken, removeHardwareId =
135
138
  }
136
139
  function updateRefreshTokenInConfig(configContents, oldRefreshToken, newRefreshToken, clearRefreshFlags) {
137
140
  try {
138
- const homebridgeConfig = JSON.parse(configContents), platformConfig = homebridgeConfig.platforms?.find((platform) => platform.platform === platformName &&
141
+ const homebridgeConfig = JSON.parse(configContents), platformConfig = homebridgeConfig.platforms?.find((platform) => (platform.platform === platformName ||
142
+ platform.platform === `${pluginName}.${platformName}`) &&
139
143
  platform.refreshToken === oldRefreshToken);
140
144
  if (!platformConfig) {
141
145
  throw new Error('Ring platform config not found');
@@ -151,15 +155,46 @@ function updateRefreshTokenInConfig(configContents, oldRefreshToken, newRefreshT
151
155
  return configContents.replace(oldRefreshToken, newRefreshToken);
152
156
  }
153
157
  }
158
+ /**
159
+ * This platform's block as saved in config.json now, if exactly one block matches and it has a
160
+ * Ring token.
161
+ *
162
+ * Homebridge restarts a child bridge with the config it read when it started, not the one in
163
+ * config.json now: after a renewal the token it hands over is out of date (and replacing it in
164
+ * config.json would then fail), and a force setting cleared since would be on again. The block is
165
+ * this child bridge's, or the one on the main bridge.
166
+ */
167
+ export function getSavedPlatformConfig(api, config) {
168
+ try {
169
+ // Homebridge upper-cases the username it hands over; config.json may have it either way.
170
+ const username = config._bridge?.username?.toUpperCase(), blocks = (JSON.parse(readFileSync(api.user.configPath()).toString()).platforms ?? []).filter((block) => (block.platform === platformName ||
171
+ block.platform === `${pluginName}.${platformName}`) &&
172
+ (username
173
+ ? String(block._bridge?.username ?? '').toUpperCase() === username
174
+ : !block._bridge));
175
+ const block = blocks.length === 1 ? blocks[0] : undefined;
176
+ return typeof block?.refreshToken === 'string' && block.refreshToken ? block : undefined;
177
+ }
178
+ catch {
179
+ return undefined;
180
+ }
181
+ }
182
+ function clearRefreshPending(storagePath, update = {}) {
183
+ const state = readPushRecoveryState(storagePath);
184
+ if (state.refreshPending) {
185
+ writePushRecoveryState(storagePath, { ...state, ...update, refreshPending: false });
186
+ }
187
+ }
154
188
  /**
155
189
  * Saves each new Ring refresh token into config.json, replacing the token that is there now.
156
190
  *
157
191
  * The token in config.json is tracked here rather than taken from ring-client-api's
158
192
  * "oldRefreshToken": after a forced refresh, ring-client-api starts from a modified token that
159
193
  * was never written to config.json, and following its old token would save only the first new
160
- * token and none after it (so the next start would register with Ring again).
194
+ * token and none after it (so the next start would register with Ring again). onSaved is called
195
+ * after the first save.
161
196
  */
162
- export function createRefreshTokenSaver(api, tokenInConfig, clearRefreshFlags) {
197
+ export function createRefreshTokenSaver(api, tokenInConfig, clearRefreshFlags, onSaved) {
163
198
  let current = tokenInConfig,
164
199
  // Only with the first save: turning a force setting back on later must survive renewals.
165
200
  clearFlags = clearRefreshFlags, warned = false;
@@ -174,6 +209,9 @@ export function createRefreshTokenSaver(api, tokenInConfig, clearRefreshFlags) {
174
209
  if (saved) {
175
210
  current = newRefreshToken;
176
211
  clearFlags = false;
212
+ const firstSave = onSaved;
213
+ onSaved = undefined;
214
+ firstSave?.();
177
215
  }
178
216
  else if (!warned) {
179
217
  // Once per run: after a new sign-in while running, every renewal would end up here.
@@ -206,7 +244,7 @@ export function isPermanentRingError(error) {
206
244
  */
207
245
  function markNotResponding(accessory) {
208
246
  const failure = () => {
209
- throw new hap.HapStatusError(-70402 /* hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
247
+ throw new hap.HapStatusError(hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
210
248
  };
211
249
  for (const service of accessory.services) {
212
250
  if (service.UUID === hap.Service.AccessoryInformation.UUID)
@@ -268,9 +306,22 @@ export class RingPlatform {
268
306
  this.api.on('shutdown', () => {
269
307
  this.shuttingDown = true;
270
308
  clearTimeout(this.retryTimer);
309
+ this.sessionRefreshSensor?.stop();
271
310
  });
311
+ if (config.automaticSessionRefresh !== false) {
312
+ this.pushHealth = new PushHealthMonitor(api.user.storagePath(), () => this.refreshSessionAutomatically());
313
+ }
272
314
  this.api.on('didFinishLaunching', () => {
273
315
  this.log.debug('didFinishLaunching');
316
+ const saved = config.refreshToken ? getSavedPlatformConfig(api, config) : undefined;
317
+ if (saved) {
318
+ if (saved.refreshToken !== config.refreshToken) {
319
+ this.log.info('Using the newer Ring token saved in config.json');
320
+ config.refreshToken = saved.refreshToken;
321
+ }
322
+ config.forceRefreshRingPushCredentials = Boolean(saved.forceRefreshRingPushCredentials);
323
+ config.forceRefreshRingApiSession = Boolean(saved.forceRefreshRingApiSession);
324
+ }
274
325
  if (config.refreshToken) {
275
326
  void this.connectWithRetry();
276
327
  }
@@ -282,6 +333,31 @@ export class RingPlatform {
282
333
  retryTimer;
283
334
  shuttingDown = false;
284
335
  devicesSetUp = false;
336
+ pushHealth;
337
+ gotNewToken = false;
338
+ sessionRefreshSensor;
339
+ startedAt = Date.now();
340
+ /**
341
+ * Ring has stopped sending push notifications: the session is refreshed at the next start (see
342
+ * connectToApi). A child bridge restarts itself for that; Homebridge starts it again at once.
343
+ */
344
+ refreshSessionAutomatically() {
345
+ if (this.shuttingDown)
346
+ return;
347
+ const reason = 'Ring event history shows motion that Ring sent no push notification for (3 events over at least 30 minutes, none pushed)';
348
+ if (this.config._bridge && typeof process.send === 'function') {
349
+ this.log.warn(`${reason}; restarting this child bridge to refresh the Ring API session (turn off "Automatic Ring Session Refresh" to stop this)`);
350
+ this.restartChildBridge();
351
+ }
352
+ else {
353
+ this.log.warn(`${reason}; the Ring API session will be refreshed the next time Homebridge restarts (run the plugin as a child bridge to have this done automatically)`);
354
+ }
355
+ }
356
+ // A separate method so tests can stand in for it. Homebridge's own shutdown (SIGTERM) stops
357
+ // the accessories cleanly, and a child bridge that ends that way is started again at once.
358
+ restartChildBridge() {
359
+ process.kill(process.pid, 'SIGTERM');
360
+ }
285
361
  /**
286
362
  * Connects to Ring, retrying later if Ring can't be reached when Homebridge starts (an outage,
287
363
  * a server error), with a fresh connection each time: until then the alarm and every other
@@ -317,9 +393,13 @@ export class RingPlatform {
317
393
  this.homebridgeAccessories[accessory.UUID] = accessory;
318
394
  }
319
395
  async connectToApi() {
320
- const { api, config } = this, shouldRotateRingApiSession = config.forceRefreshRingApiSession && config.refreshToken, systemId = shouldRotateRingApiSession
321
- ? rotateSystemId(api.user.storagePath())
322
- : getSystemId(api.user.storagePath()), configuredHomeKitAccessoryTag = config.homeKitAccessoryTag?.trim(), accessoryIdSuffix = configuredHomeKitAccessoryTag
396
+ const { api, config } = this, storagePath = api.user.storagePath(),
397
+ // Asked for by the push check (refreshSessionAutomatically) before the last restart.
398
+ refreshPendingInState = Boolean(readPushRecoveryState(storagePath).refreshPending),
399
+ // Like the force settings, not again on a retry once Ring has given a new token.
400
+ automaticRefresh = Boolean(this.pushHealth) && refreshPendingInState && !this.gotNewToken, shouldRotateRingApiSession = (config.forceRefreshRingApiSession || automaticRefresh) && config.refreshToken, systemId = shouldRotateRingApiSession
401
+ ? rotateSystemId(storagePath)
402
+ : getSystemId(storagePath), configuredHomeKitAccessoryTag = config.homeKitAccessoryTag?.trim(), accessoryIdSuffix = configuredHomeKitAccessoryTag
323
403
  ? `-${configuredHomeKitAccessoryTag}`
324
404
  : '', accessoryNameSuffix = configuredHomeKitAccessoryTag
325
405
  ? ` (${configuredHomeKitAccessoryTag})`
@@ -329,7 +409,17 @@ export class RingPlatform {
329
409
  ? removePushCredentialsFromRefreshToken(config.refreshToken, Boolean(shouldRotateRingApiSession))
330
410
  : undefined;
331
411
  if (shouldRotateRingApiSession) {
332
- logInfo('Forcing Ring API session refresh because forceRefreshRingApiSession is enabled');
412
+ logInfo(automaticRefresh && !config.forceRefreshRingApiSession
413
+ ? 'Forcing Ring API session refresh because Ring stopped sending push notifications (automatic session refresh)'
414
+ : 'Forcing Ring API session refresh because forceRefreshRingApiSession is enabled');
415
+ }
416
+ // Until its new token is saved, a push must not drop this run's refresh: the next start
417
+ // would sign in with the old token again.
418
+ if (automaticRefresh)
419
+ this.pushHealth?.setHoldPending(true);
420
+ // Asked for while the setting was on: not done later on old evidence once it is back on.
421
+ if (refreshPendingInState && !this.pushHealth) {
422
+ clearRefreshPending(storagePath);
333
423
  }
334
424
  if (refreshTokenWithoutPushCredentials) {
335
425
  logInfo('Forcing Ring push credential refresh because Ring push credentials were removed from the startup token');
@@ -342,13 +432,27 @@ export class RingPlatform {
342
432
  : {}),
343
433
  systemId,
344
434
  });
345
- ringApi.onRefreshTokenUpdated.subscribe(createRefreshTokenSaver(this.api, config.refreshToken, Boolean(refreshTokenWithoutPushCredentials)));
435
+ ringApi.onRefreshTokenUpdated.subscribe(createRefreshTokenSaver(this.api, config.refreshToken, Boolean(refreshTokenWithoutPushCredentials),
436
+ // Cleared once the new identity's token is saved: until then the next start would
437
+ // sign in with the old one.
438
+ automaticRefresh
439
+ ? () => {
440
+ const doneAt = Date.now();
441
+ this.pushHealth?.setHoldPending(false);
442
+ clearRefreshPending(storagePath, { refreshDoneAt: doneAt });
443
+ // Usually saved while connecting, before the sensor is set up (which then reads
444
+ // refreshDoneAt); this covers a save after that.
445
+ this.sessionRefreshSensor?.show(doneAt);
446
+ this.log.warn('Automatic Ring session refresh done: in the Ring app, Control Center > Authorized Client Devices now lists homebridge-ring-secure-video twice. Remove the older entry (keep the newest).');
447
+ }
448
+ : undefined));
346
449
  // A retry must sign in with the newest token (Ring may have replaced the old one) and must
347
450
  // not force a new identity or push registration again.
348
451
  ringApi.onRefreshTokenUpdated.subscribe(({ newRefreshToken }) => {
349
452
  config.refreshToken = newRefreshToken;
350
453
  config.forceRefreshRingPushCredentials = false;
351
454
  config.forceRefreshRingApiSession = false;
455
+ this.gotNewToken = true;
352
456
  });
353
457
  let locations, loadedDevices;
354
458
  try {
@@ -483,7 +587,7 @@ export class RingPlatform {
483
587
  addTo = platformAccessories;
484
588
  }
485
589
  return accessory;
486
- }, homebridgeAccessory = this.homebridgeAccessories[uuid] || createHomebridgeAccessory(), accessory = new AccessoryClass(device, homebridgeAccessory, config);
590
+ }, homebridgeAccessory = this.homebridgeAccessories[uuid] || createHomebridgeAccessory(), accessory = new AccessoryClass(device, homebridgeAccessory, config, this.pushHealth);
487
591
  accessory.initBase();
488
592
  // Registered only once set up: a half-built accessory isn't added to HomeKit.
489
593
  addTo?.push(homebridgeAccessory);
@@ -516,6 +620,20 @@ export class RingPlatform {
516
620
  }
517
621
  });
518
622
  }));
623
+ // Opens after an automatic session refresh, so the Home app can notify.
624
+ if (this.pushHealth && config.sessionRefreshSensor) {
625
+ const sensorUuid = getSessionRefreshSensorUuid(`${debug ? 'TEST ' : ''}ring-secure-video${accessoryIdSuffix}`), sensorName = `Ring Session Refreshed${accessoryNameSuffix}`;
626
+ let sensorAccessory = this.homebridgeAccessories[sensorUuid];
627
+ if (!sensorAccessory) {
628
+ sensorAccessory = new api.platformAccessory(sensorName, sensorUuid, 10 /* hap.Categories.SENSOR */);
629
+ logInfo(`Adding session refresh sensor ${sensorUuid} ${sensorName}`);
630
+ platformAccessories.push(sensorAccessory);
631
+ this.homebridgeAccessories[sensorUuid] = sensorAccessory;
632
+ }
633
+ this.sessionRefreshSensor = new SessionRefreshSensor(sensorAccessory, sensorName, this.startedAt);
634
+ this.sessionRefreshSensor.show(readPushRecoveryState(storagePath).refreshDoneAt);
635
+ activeAccessoryIds.push(sensorUuid);
636
+ }
519
637
  const failedLocations = locations.filter((_, i) => locationResults[i].status === 'rejected');
520
638
  locationResults.forEach((result, i) => {
521
639
  if (result.status === 'rejected') {
@@ -0,0 +1,106 @@
1
+ import { logInfo } from 'ring-client-api/util';
2
+ import { hap } from "./hap.js";
3
+ /** How long the sensor stays open after an automatic Ring session refresh. */
4
+ export const SESSION_REFRESH_SENSOR_OPEN_MS = 24 * 60 * 60_000;
5
+ /** After a home hub subscribes again, the sensor opens this much later... */
6
+ export const SESSION_REFRESH_SENSOR_SUBSCRIBED_DELAY_MS = 10_000;
7
+ /** ...or after this long at most. */
8
+ export const SESSION_REFRESH_SENSOR_MAX_DELAY_MS = 3 * 60_000;
9
+ // Kept stable so the accessory, and its room and notification settings, survive restarts.
10
+ export function getSessionRefreshSensorUuid(id) {
11
+ return hap.uuid.generate(`${id}-zm-session-refresh`);
12
+ }
13
+ /**
14
+ * A contact sensor that opens after an automatic Ring session refresh, so the Home app can
15
+ * notify: the older homebridge-ring-secure-video entry in Authorized Client Devices is then to
16
+ * be removed. It closes again a day later.
17
+ *
18
+ * The refresh happens right after a restart, and the Home app notifies for a change it sees, not
19
+ * for a value it finds: so after a refresh in this run the sensor opens 10 s after a Home app
20
+ * or home hub is subscribed to it (or after 3 minutes). After a restart later that day it is
21
+ * simply open, without a second notification.
22
+ */
23
+ export class SessionRefreshSensor {
24
+ characteristic;
25
+ runStartedAt;
26
+ openTimer;
27
+ closeTimer;
28
+ onSubscribe;
29
+ constructor(accessory, name, runStartedAt) {
30
+ const { Characteristic, Service } = hap;
31
+ accessory
32
+ .getService(Service.AccessoryInformation)
33
+ .setCharacteristic(Characteristic.Manufacturer, 'Ring')
34
+ .setCharacteristic(Characteristic.Model, 'Session refresh sensor')
35
+ .setCharacteristic(Characteristic.SerialNumber, 'session-refresh');
36
+ const service = accessory.getService(Service.ContactSensor) ??
37
+ accessory.addService(Service.ContactSensor, name);
38
+ // Its value is kept from the last run (Homebridge caches it) until show() decides: every
39
+ // update is sent to the Home app, so closing it here and opening it again in show() would
40
+ // notify a second time.
41
+ this.characteristic = service.getCharacteristic(Characteristic.ContactSensorState);
42
+ this.runStartedAt = runStartedAt;
43
+ }
44
+ set(value) {
45
+ if (this.characteristic.value !== value)
46
+ this.characteristic.updateValue(value);
47
+ }
48
+ /** Shows a refresh done at refreshDoneAt (if it is less than a day ago); closed otherwise. */
49
+ show(refreshDoneAt) {
50
+ const now = Date.now(), { ContactSensorState } = hap.Characteristic, closeAt = (refreshDoneAt ?? 0) + SESSION_REFRESH_SENSOR_OPEN_MS;
51
+ this.stop();
52
+ if (!refreshDoneAt || refreshDoneAt > now || closeAt <= now) {
53
+ this.set(ContactSensorState.CONTACT_DETECTED);
54
+ return;
55
+ }
56
+ const open = () => {
57
+ this.stopWaiting();
58
+ if (Date.now() < closeAt)
59
+ this.set(ContactSensorState.CONTACT_NOT_DETECTED);
60
+ };
61
+ if (refreshDoneAt < this.runStartedAt) {
62
+ open();
63
+ }
64
+ else {
65
+ // A refresh in this run: closed until the Home app can see it open.
66
+ this.set(ContactSensorState.CONTACT_DETECTED);
67
+ this.openTimer = setTimeout(() => {
68
+ open();
69
+ logInfo('Ring Session Refreshed sensor opened (remove the older entry in Authorized Client Devices)');
70
+ }, Math.min(SESSION_REFRESH_SENSOR_MAX_DELAY_MS, closeAt - now));
71
+ this.onSubscribe = () => {
72
+ clearTimeout(this.openTimer);
73
+ this.openTimer = setTimeout(() => {
74
+ open();
75
+ logInfo('Ring Session Refreshed sensor opened (remove the older entry in Authorized Client Devices)');
76
+ }, SESSION_REFRESH_SENSOR_SUBSCRIBED_DELAY_MS);
77
+ this.openTimer.unref?.();
78
+ this.stopWaiting();
79
+ };
80
+ this.openTimer.unref?.();
81
+ // hap-nodejs only reports the first subscriber; a home hub that came back while the
82
+ // plugin was connecting to Ring has subscribed already (the count is private).
83
+ if (this.characteristic.subscriptions) {
84
+ this.onSubscribe();
85
+ }
86
+ else {
87
+ this.characteristic.on("subscribe" /* hap.CharacteristicEventTypes.SUBSCRIBE */, this.onSubscribe);
88
+ }
89
+ }
90
+ this.closeTimer = setTimeout(() => {
91
+ this.set(ContactSensorState.CONTACT_DETECTED);
92
+ }, closeAt - now);
93
+ this.closeTimer.unref?.();
94
+ }
95
+ stopWaiting() {
96
+ if (this.onSubscribe) {
97
+ this.characteristic.removeListener("subscribe" /* hap.CharacteristicEventTypes.SUBSCRIBE */, this.onSubscribe);
98
+ this.onSubscribe = undefined;
99
+ }
100
+ }
101
+ stop() {
102
+ this.stopWaiting();
103
+ clearTimeout(this.openTimer);
104
+ clearTimeout(this.closeTimer);
105
+ }
106
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "homebridge-ring-secure-video",
3
3
  "displayName": "Ring Secure Video",
4
- "version": "1.0.0-beta.4",
4
+ "version": "1.0.0-beta.5",
5
5
  "description": "Homebridge plugin for Ring devices with HomeKit Secure Video recording, based on homebridge-ring and homebridge-ring-hksv",
6
6
  "type": "module",
7
7
  "main": "./lib/index.js",
@@ -18,7 +18,7 @@
18
18
  "dependencies": {
19
19
  "@eneris/push-receiver": "4.3.1",
20
20
  "@homebridge/camera-utils": "^3.0.0",
21
- "@homebridge/plugin-ui-utils": "^2.1.2",
21
+ "@homebridge/plugin-ui-utils": "^2.3.0",
22
22
  "ring-client-api": "14.3.0",
23
23
  "rxjs": "^7.8.2",
24
24
  "werift": "0.22.4"
@@ -26,14 +26,14 @@
26
26
  "devDependencies": {
27
27
  "@eslint/js": "9.39.2",
28
28
  "@typescript-eslint/parser": "^8.54.0",
29
- "ajv": "8.17.1",
30
- "concurrently": "^9.2.1",
29
+ "ajv": "8.20.0",
30
+ "concurrently": "^10.0.7",
31
31
  "eslint": "9.39.2",
32
- "globals": "17.3.0",
33
- "homebridge": "^2.1.0",
32
+ "globals": "17.14.0",
33
+ "homebridge": "^2.5.0",
34
34
  "homebridge-config-ui-x": "^5.24.0",
35
35
  "typescript": "5.9.3",
36
- "typescript-eslint": "8.54.0"
36
+ "typescript-eslint": "8.72.2"
37
37
  },
38
38
  "engines": {
39
39
  "node": "^20 || ^22 || ^24",