feat: locationIds option to filter alarms

README.md

@@ -15,11 +15,20 @@ This is TypeScript api for the [Ring Alarm System](https://shop.ring.com/pages/s
 ```js
 import { getAlarms } from '@dgreif/ring-alarm'
 
-const alarms = await getAlarms();
+const alarms = await getAlarms({
+  email: '[email protected]',
+  password: 'abc123!#',
+  locationIds: ['488e4800-fcde-4493-969b-d1a06f683102', '4bbed7a7-06df-4f18-b3af-291c89854d60'] // OPTIONAL. See below for details
+});
 ```
 `alarms` will be an array of alarms based on the locations you have set
 up in Ring.  Each location has it's own alarm that can be armed or disarmed,
 and used to interact with alarm devices in that location.
+
+`locationIds` is an optional parameter that allows you to limit the alarm results to a specific set of locations.
+This is mainly useful for the [homebridge-ring-alarm Plugin](./homebridge), but can also be used if you only care about
+listening for events at a subset of your locations and don't want to create websocket connections to _all_ of your base
+ stations.  If this option is not included, all alarm locations will be returned.
 ## Arming/Disarming Alarms
 ```js
 const alarm = alarms[0]

api/index.ts

@@ -6,12 +6,25 @@ import { BaseStation } from './ring-types'
 export * from './alarm'
 export * from './ring-types'
 
-export async function getAlarms(options: { email: string; password: string }) {
+export interface RingAlarmOptions {
+  email: string
+  password: string
+  locationIds?: string[]
+}
+
+export async function getAlarms(options: RingAlarmOptions) {
   const restClient = new RingRestClient(options.email, options.password)
   const { base_stations: baseStations } = await restClient.request<{
     base_stations: BaseStation[]
   }>('GET', 'https://app.ring.com/rhq/v1/clients_api/ring_devices')
-  const locationIds = baseStations.map(baseStation => baseStation.location_id)
+  const locationIds = baseStations
+    .map(baseStation => baseStation.location_id)
+    .filter(locationId => {
+      return (
+        !Array.isArray(options.locationIds) ||
+        options.locationIds.includes(locationId)
+      )
+    })
 
   return unique(locationIds).map(
     locationId => new Alarm(locationId, restClient)

examples/example.ts

@@ -7,7 +7,8 @@ async function example() {
   const alarms = await getAlarms({
     // Replace with your ring email/password
     email: env.RING_EMAIL!,
-    password: env.RING_PASS!
+    password: env.RING_PASS!,
+    locationIds: [env.RING_LOCATION_ID!] // Remove is you want all locations
   })
 
   console.log(`Found ${alarms.length} alarm(s).`)

homebridge/README.md

@@ -24,12 +24,17 @@ This [Homebridge](https://github.com/nfarina/homebridge) plugin provides a platf
     {
       "platform": "RingAlarm",
       "email": "[email protected]",
-      "password": "abc123!#"
+      "password": "abc123!#",
+      "locationIds": ["488e4800-fcde-4493-969b-d1a06f683102", "4bbed7a7-06df-4f18-b3af-291c89854d60"] // OPTIONAL. See below for details
     }
   ]
 }
 ```
 
+`locationIds` is an optional parameter that allows you to limit the alarm results to a specific set of locations.
+Use this option if you only want a subset of your alarms to appear in HomeKit. If this option is not included, 
+all of your alarms will be added to HomeKit (which is what most users will want to do).  
+
 ### Supported Devices
   * Security Panel
     * This is a software device that represents the alarm for a Ring location
@@ -50,6 +55,10 @@ This [Homebridge](https://github.com/nfarina/homebridge) plugin provides a platf
     * Detect motion
     * Tamper status
     * Battery status
+  * Smoke Alarm
+  * Carbon Monoxide Alarm
+  * Smoke/Carbon Monoxide Listener
+  * Smart Locks
 
 ### Alarm Modes
 

homebridge/ring-alarm-platform.ts

@@ -1,4 +1,9 @@
-import { AlarmDevice, AlarmDeviceType, getAlarms } from '../api'
+import {
+  AlarmDevice,
+  AlarmDeviceType,
+  getAlarms,
+  RingAlarmOptions
+} from '../api'
 import { HAP, hap } from './hap'
 import { SecurityPanel } from './security-panel'
 import { BaseStation } from './base-station'
@@ -42,7 +47,7 @@ export class RingAlarmPlatform {
 
   constructor(
     public log: HAP.Log,
-    public config: { email: string; password: string },
+    public config: RingAlarmOptions,
     public api: HAP.Platform
   ) {
     this.api.on('didFinishLaunching', () => {