Update ring-client-api to use v3 location/devices REST endpoints#1749
Update ring-client-api to use v3 location/devices REST endpoints#1749tsightler wants to merge 1 commit into
Conversation
|
There was a problem hiding this comment.
Pull request overview
This PR modernizes ring-client-api’s core discovery flow by switching location and device discovery to Ring’s newer location_info/v3 and device_info/v3 REST endpoints, aiming to preserve existing consumer-facing behavior while adapting to the new response shapes.
Changes:
- Added
deviceInfoApi()andlocationInfoApi()URL helpers and corresponding base URLs in the REST client. - Updated
RingApi.fetchRingDevices()to consumedevice_info/v3/devicesand re-bucket devices into the library’s existing categories. - Expanded
UserLocationtypings to accommodate additional fields and updated coordinate value types from the new locations endpoint.
Show a summary per file
| File | Description |
|---|---|
| packages/ring-client-api/ring-types.ts | Updates UserLocation type shape for v3 location payload compatibility. |
| packages/ring-client-api/rest-client.ts | Adds v3 base URLs and helper functions for the new endpoints. |
| packages/ring-client-api/api.ts | Switches device + location discovery to v3 endpoints and updates device classification logic. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 3/3 changed files
- Comments generated: 1
| for (const device of devices) { | ||
| const kind = device.kind as string | ||
|
|
||
| if (doorbellKinds.has(kind)) { |
tbaron
left a comment
tbaron
left a comment
There was a problem hiding this comment.
Thanks for making these changes! Did you find any documentation for the v3 APIs, or were these changes reverse engineered? I didn't see them in the official docs.
| const doorbellKinds: Set<string> = new Set( | ||
| Object.values(RingCameraKind).filter( | ||
| (k) => | ||
| k.startsWith('doorbot') || | ||
| k.startsWith('doorbell') || | ||
| k.startsWith('lpd_') || | ||
| k.startsWith('jbox_') || | ||
| k.startsWith('cocoa_doorbell'), | ||
| ), | ||
| ) |
There was a problem hiding this comment.
This could be cleaner to encapsulate in an exported predicate in ring-types.ts, similar to isWebSocketSupportedAsset that's already implemented there. If placed in proximity to the RingCameraKind type, it would also improve maintenance discoverability. E.g.,
export type RingCameraKind = ...
export function isDoorbellKind({ kind }: { kind: RingCameraKind }) {
return kind && (kind.startsWith( ... ) || ... );
}Or more tersely with a bound regex .test():
export const isDoorbellKind =
RegExp.prototype.test.bind(/^(?:(cocoa_)?doorb(ell|ot)|lpd_|jbox_)/) as
(kind: RingCameraKind) => boolean| export function deviceApi(path: string) { | ||
| return deviceApiBaseUrl + path | ||
| } |
There was a problem hiding this comment.
Should the remaining /devices/v1/ usages be deprecated in favor of /device_info/v3/?
| operation_set?: string | ||
| entitlements?: { | ||
| business_command_center?: boolean | ||
| business_role_management?: boolean | ||
| vm_virtual_security_guard?: boolean | ||
| } |
There was a problem hiding this comment.
Curious - why are these required for the broader change? Could the type spec be generalized to allow flexible parsing of future changes (e.g., key-value map)?
This is the first in a series of PRs to bring ring-client-api on par with modern Ring API specs. While I have tested these changes with ring-mqtt, these are changes in core functions that have remained largely unchaged for many years so this PR has more risk than many.
This PR updates the Ring client library to use the latest REST API endpoints for location and device discovery. I've tried to keep the changes to the minimum and not break anything for API consumers. The new locations endpoint provides roughly the same information and format of the previous, however, the new devices endpoint is quite different.
I've tested this with my account which has the following devices:
Doorbell Pro
Floodlight (1st gen)
Stickup Cams (various)
Floodlight Pro
Chime
Alarm (1st gen) with many devices
The most likely risks to the change are around shared locations as there are some differences in how discovery of location devices works, but I don't have a shared account to test.
Important Note: This code was written 99% by Claude Code. I have manually reviewed the code, applying a few minor tweaks, mostly for style, and also performed manual functional testing.