ring-client-api 11.3.1 → 11.4.0-beta.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Dusty Greif
+Copyright (c) 2022 Dusty Greif
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,35 +23,44 @@ First, generate a `refreshToken` using the instructions in the [Refresh Tokens W
 import { RingApi } from 'ring-client-api'
 
 const ringApi = new RingApi({
-  refreshToken: 'token generated with ring-auth-cli.  See https://github.com/dgreif/ring/wiki/Refresh-Tokens',
+  refreshToken:
+    'token generated with ring-auth-cli.  See https://github.com/dgreif/ring/wiki/Refresh-Tokens',
 
   // The following are all optional. See below for details
   cameraStatusPollingSeconds: 20,
-  locationIds: ['488e4800-fcde-4493-969b-d1a06f683102', '4bbed7a7-06df-4f18-b3af-291c89854d60']
-});
+  locationIds: [
+    '488e4800-fcde-4493-969b-d1a06f683102',
+    '4bbed7a7-06df-4f18-b3af-291c89854d60',
+  ],
+})
 ```
 
 ### Optional Parameters
 
-Option | Default | Explanation
---- | --- | ---
-`cameraStatusPollingSeconds` | `undefined` (No Polling) | How frequently to poll for updates to your cameras and chimes (in seconds).  Information like light/siren/volume/snooze status do not update in real time and need to be requested periodically.
-`locationModePollingSeconds` | `undefined` (No Polling) | How frequently to poll for location mode updates (in seconds).  This is only useful if you are using location modes to control camera settings and want to keep an up-to-date reference of the current mode for each location.  Polling is automatically disabled for locations equipped with a Ring Alarm.
-`locationIds` | All Locations | Allows you to limit the results to a specific set of locations. This is mainly useful for the [homebridge-ring 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 locations. This will also limit the results for `ringApi.getCameras()` to the configured locations. If this option is not included, all locations will be returned.
-`debug` | false | Turns on additional logging.  In particular, ffmpeg logging.
-`ffmpegPath` | undefined | A custom path to the `ffmpeg` executable.  By default, `ffmpeg` will be installed using `ffmpeg-for-homebridge`, and then fall back to using the `PATH` environment variable.
-`ffmpegPath` | Uses `ffmpeg-for-homebridge` | A custom path to the `ffmpeg` executable.  By default, the static binaries built in [ffmpeg-for-homebridge](https://github.com/oznu/ffmpeg-for-homebridg) will be used.  If you prefer to use your own version of ffmpeg, you can pass a complete path, or simply `"ffmpeg"` to use ffmpeg from your `PATH`.
-`controlCenterDisplayName` | 'ring-client-api' | This allows you to change the displayed name for the Authorized Device within Control Center in the Ring app
-`avoidSnapshotBatteryDrain` | false | Causes snapshots for battery cameras to be fetched at a minimum 10 minute interval to avoid draining the battery.
+| Option                       | Default                      | Explanation                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `cameraStatusPollingSeconds` | `undefined` (No Polling)     | How frequently to poll for updates to your cameras and chimes (in seconds). Information like light/siren/volume/snooze status do not update in real time and need to be requested periodically.                                                                                                                                                                                                                                                                          |
+| `locationModePollingSeconds` | `undefined` (No Polling)     | How frequently to poll for location mode updates (in seconds). This is only useful if you are using location modes to control camera settings and want to keep an up-to-date reference of the current mode for each location. Polling is automatically disabled for locations equipped with a Ring Alarm.                                                                                                                                                                |
+| `locationIds`                | All Locations                | Allows you to limit the results to a specific set of locations. This is mainly useful for the [homebridge-ring 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 locations. This will also limit the results for `ringApi.getCameras()` to the configured locations. If this option is not included, all locations will be returned. |
+| `debug`                      | false                        | Turns on additional logging. In particular, ffmpeg logging.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `ffmpegPath`                 | undefined                    | A custom path to the `ffmpeg` executable. By default, `ffmpeg` will be installed using `ffmpeg-for-homebridge`, and then fall back to using the `PATH` environment variable.                                                                                                                                                                                                                                                                                             |
+| `ffmpegPath`                 | Uses `ffmpeg-for-homebridge` | A custom path to the `ffmpeg` executable. By default, the static binaries built in [ffmpeg-for-homebridge](https://github.com/oznu/ffmpeg-for-homebridg) will be used. If you prefer to use your own version of ffmpeg, you can pass a complete path, or simply `"ffmpeg"` to use ffmpeg from your `PATH`.                                                                                                                                                               |
+| `controlCenterDisplayName`   | 'ring-client-api'            | This allows you to change the displayed name for the Authorized Device within Control Center in the Ring app                                                                                                                                                                                                                                                                                                                                                             |
+| `avoidSnapshotBatteryDrain`  | false                        | Causes snapshots for battery cameras to be fetched at a minimum 10 minute interval to avoid draining the battery.                                                                                                                                                                                                                                                                                                                                                        |
 
 ## Locations
+
 ```typescript
 const locations = await ringApi.getLocations()
 const location = locations[0]
 location.hasHubs // does this location have an alarm and/or lighting bridge
 location.disarm()
-location.armHome([/* optional array of zids for devices to bypass */])
-location.armAway([/* bypass zids */])
+location.armHome([
+  /* optional array of zids for devices to bypass */
+])
+location.armAway([
+  /* bypass zids */
+])
 location.getAlarmMode() // returns Promise<'all' | 'some' | 'none'>
 location.soundSiren()
 location.silenceSiren()
@@ -64,29 +73,34 @@ location.getCameraEvents() // ding events from all cameras in the location
 and used to interact with all devices in that location.
 
 ## Devices
+
 Once you have acquired the desired location, you can start
 to interact with associated devices. These devices include ring alarm, ring lighting,
 and third party devices connected to ring alarm
+
 ```js
 import { RingDeviceType } from 'ring-client-api'
 
 const devices = await location.getDevices()
-const baseStation = devices.find(device => device.data.deviceType === RingDeviceType.BaseStation)
-baseStation.setVolume(.75) // base station and keypad support volume settings between 0 and 1
+const baseStation = devices.find(
+  (device) => device.data.deviceType === RingDeviceType.BaseStation
+)
+baseStation.setVolume(0.75) // base station and keypad support volume settings between 0 and 1
 console.log(baseStation.data) // object containing properties like zid, name, roomId, faulted, tamperStatus, etc.
-baseStation.onData.subscribe(data => {
-    // called any time data is updated for this specific device
+baseStation.onData.subscribe((data) => {
+  // called any time data is updated for this specific device
 })
 ```
 
 ## Cameras
+
 You can get all cameras using `await ringApi.getCameras()` or cameras for a particular
 location with `location.cameras`
 
 ```typescript
 const camera = location.cameras[0]
 camera.data // camera info including motion zones, light status, battery, etc.
-camera.onData.subscribe(data => {
+camera.onData.subscribe((data) => {
   // called every time new data is fetched for this camera
 })
 camera.setLight(true) // turn light on/off
@@ -97,43 +111,23 @@ camera.createSipSession() // creates a new SipSession which allows you to contro
 camera.getEvents() // fetch ding events for the camera (like motion and doorbell presses)
 camera.getRecordingUrl(dingIdStr, { transcoded: true }) // fetch the url for a recording
 camera.getSnapshot() // returns a Promise<Buffer> of the latest snapshot from the camera
-
 ```
 
 Camera also includes the following observables:
-* `onNewDing`: this will include the sip info and ding information every time a new ding is created
-* `onActiveDings`: dings created within the last 65 seconds
-* `onDoorbellPressed`: emits a ding every time the doorbell is pressed
-* `onMotionDetected`: `true` or `false` based on `onActiveDings` containing a motion ding
 
-Some other useful properties
-* `id`
-* `name`: same as `description` from `data`
-* `hasLight`: does this camera have a light
-* `hasSiren`: does this camera have a siren
-* `isDoorbot`: is this camera a doorbell
+- `onNewDing`: this will include the sip info and ding information every time a new ding is created
+- `onActiveDings`: dings created within the last 65 seconds
+- `onDoorbellPressed`: emits a ding every time the doorbell is pressed
+- `onMotionDetected`: `true` or `false` based on `onActiveDings` containing a motion ding
 
-## Examples
+Some other useful properties
 
-See the [examples directory](examples) for additional code examples.  For a full project example, see https://github.com/dgreif/ring-client-example
+- `id`
+- `name`: same as `description` from `data`
+- `hasLight`: does this camera have a light
+- `hasSiren`: does this camera have a siren
+- `isDoorbot`: is this camera a doorbell
 
 ## Refresh Token
 
-Ring has restricted refresh tokens so that they expire shortly after use.  See https://github.com/dgreif/ring/wiki/Refresh-Tokens#refresh-token-expiration for details on how to properly handle refresh tokens in your library.
-
-## homebridge-ring
-
-The `homebridge-ring` is also maintained in this repo.  Its readme can be found in [the `homebridge` directory](./homebridge)
-
-## Credits
-
-I'd like to give a big thanks to a number developers who have put a lot of hard work into analyzing the
-Ring api and building similar libraries which were extremely valuable in my creation of this project.  Thank you all
-for your hard work!
-
- * @davglass - https://github.com/davglass/doorbot - The original node project that proved we can interact with Ring's api
- * @jimhigson - https://github.com/jimhigson/ring-api - A promisified api for Ring's original line of products
- * @tchellomello - https://github.com/tchellomello/python-ring-doorbell - A python api which is widely used for Ring integrations
- * @mrose17 - https://github.com/homespun/homebridge-platform-ring-video-doorbell - The original Ring camera homebridge plugin
- * @codahq - Thanks for all your help debugging the Ring api
- * @joeyberkovitz - Great discovery work on the Ring Alarm websockets api
+Ring has restricted refresh tokens so that they expire shortly after use. See https://github.com/dgreif/ring/wiki/Refresh-Tokens#refresh-token-expiration for details on how to properly handle refresh tokens in your library.

package/lib/ring-auth-cli.js

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
 "use strict";
-require('./lib/api/refresh-token').logRefreshToken();
+Object.defineProperty(exports, "__esModule", { value: true });
+const refresh_token_1 = require("./refresh-token");
+(0, refresh_token_1.logRefreshToken)().catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error(e);
+    process.exit(1);
+});

package/lib/ring-device-data-cli.js

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
 "use strict";
-require('./lib/api/device-data').logDeviceData();
+Object.defineProperty(exports, "__esModule", { value: true });
+const device_data_1 = require("./device-data");
+(0, device_data_1.logDeviceData)().catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error(e);
+    process.exit(1);
+});

package/lib/test/ring-camera.spec.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe('Ring Camera', () => {
+    describe('battery level', () => {
+        it('should handle string battery life', () => {
+            expect((0, index_1.getBatteryLevel)({
+                battery_life: '49',
+            })).toEqual(49);
+        });
+        it('should handle null battery life', () => {
+            expect((0, index_1.getBatteryLevel)({ battery_life: null })).toEqual(null);
+        });
+        it('should handle right battery only', () => {
+            expect((0, index_1.getBatteryLevel)({ battery_life: null, battery_life_2: 24 })).toEqual(24);
+        });
+        it('should handle left battery only', () => {
+            expect((0, index_1.getBatteryLevel)({ battery_life: 76, battery_life_2: null })).toEqual(76);
+        });
+        it('should handle dual batteries', () => {
+            expect((0, index_1.getBatteryLevel)({ battery_life: '92', battery_life_2: 84 })).toEqual(84);
+            expect((0, index_1.getBatteryLevel)({ battery_life: '92', battery_life_2: 100 })).toEqual(92);
+        });
+    });
+});

package/package.json

@@ -1,109 +1,59 @@
 {
   "name": "ring-client-api",
-  "version": "11.3.1",
+  "version": "11.4.0-beta.1",
   "description": "Unofficial API for Ring doorbells, cameras, security alarm system and smart lighting",
-  "main": "lib/api/index.js",
-  "bin": {
-    "ring-auth-cli": "ring-auth-cli.js",
-    "ring-device-data-cli": "ring-device-data-cli.js"
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./ffmpeg": "./lib/ffmpeg.js",
+    "./util": "./lib/util.js",
+    "./rest-client": "./lib/rest-client.js"
   },
   "scripts": {
-    "start": "concurrently -c yellow,blue --kill-others \"npm:hb\" \"npm:watch:ui\"",
-    "watch:ui": "npm start --prefix homebridge-ui",
-    "test": "jest && eslint '**/*.ts'",
-    "watch:tests": "jest --watch",
-    "lint": "eslint '**/*.ts' --fix",
-    "build": "rm -rf lib && tsc --declaration",
-    "build-quick": "rm -rf lib && esbuild ./{api,examples,homebridge}/*.ts ./api/streaming/*.ts --target=es2017 --format=cjs --outdir=lib",
-    "example": "node -r @swc-node/register ./examples/example.ts",
-    "api-example": "node -r @swc-node/register ./examples/api-example.ts",
-    "record-example": "node -r @swc-node/register ./examples/record-example.ts",
-    "return-audio-example": "node -r @swc-node/register ./examples/return-audio-example.ts",
-    "stream-example": "node -r @swc-node/register ./examples/stream-example.ts",
-    "browser-example": "node -r @swc-node/register ./examples/browser-example.ts",
-    "auth-cli": "npm run build-quick && ./ring-auth-cli.js",
-    "device-data-cli": "npm run build-quick && ./ring-device-data-cli.js",
-    "hb": "npm run build-quick && ./build/package-homebridge.sh && homebridge -P ./release-homebridge -U ./.homebridge",
-    "prepare-npm-packages": "./build/package-api.sh && ./build/package-homebridge.sh",
-    "push-with-tags": "git push --follow-tags && node ./build/github-releaser.js",
-    "deploy": "git pull -r && standard-version && npm publish ./release-api && npm publish ./release-homebridge && npm run push-with-tags",
-    "deploy-beta": "git pull -r && standard-version --prerelease beta && npm publish --tag beta ./release-api && npm publish --tag beta ./release-homebridge && npm run push-with-tags"
-  },
-  "standard-version": {
-    "scripts": {
-      "prerelease": "npm run build && npm test",
-      "pretag": "npm run prepare-npm-packages && npm run --prefix homebridge-ui build"
-    }
+    "build": "rm -rf lib && tsc --declaration --excludeDirectories test",
+    "lint": "eslint . --ext .ts",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/dgreif/ring.git"
-  },
-  "keywords": [
-    "ring",
-    "doorbell",
-    "doorbot",
-    "camera",
-    "alarm",
-    "smart",
-    "light",
-    "beam",
-    "security",
-    "client",
-    "api"
-  ],
-  "author": "dgreif",
-  "license": "MIT",
   "dependencies": {
     "@eneris/push-receiver": "^3.1.2",
     "@homebridge/camera-utils": "^2.2.0",
-    "@homebridge/plugin-ui-utils": "^0.0.19",
-    "werift": "0.16.2",
+    "werift": "0.17.0",
     "@types/socket.io-client": "1.4.36",
     "colors": "^1.4.0",
     "debug": "^4.3.4",
     "got": "^11.8.5",
     "rxjs": "^7.5.7",
-    "socket.io-client": "^2.4.0",
-    "systeminformation": "^5.12.7",
+    "socket.io-client": "^2.5.0",
+    "systeminformation": "^5.12.14",
     "uuid": "^9.0.0",
-    "ws": "^8.9.0"
+    "ws": "^8.11.0"
   },
   "devDependencies": {
-    "@swc-node/register": "^1.5.4",
     "@types/debug": "4.1.7",
-    "@types/jest": "29.1.2",
-    "@types/node": "18.11.0",
+    "@types/jest": "29.2.2",
+    "@types/node": "18.11.9",
     "@types/uuid": "8.3.4",
     "@types/ws": "^8.5.3",
-    "@typescript-eslint/eslint-plugin": "5.40.0",
-    "@typescript-eslint/parser": "5.40.0",
-    "concurrently": "^7.4.0",
-    "conventional-github-releaser": "3.1.5",
-    "dotenv": "16.0.3",
-    "esbuild": "^0.15.11",
-    "eslint": "8.25.0",
-    "eslint-config-prettier": "8.5.0",
-    "eslint-plugin-jest": "27.1.2",
-    "eslint-plugin-prettier": "4.2.1",
-    "express": "4.18.2",
-    "homebridge": "1.5.0",
-    "jest": "29.2.0",
-    "prettier": "2.7.1",
-    "reflect-metadata": "0.1.13",
-    "rimraf": "3.0.2",
-    "standard-version": "9.5.0",
+    "eslint-config-shared": "0.0.0",
+    "jest": "29.3.1",
     "ts-jest": "29.0.3",
+    "tsconfig": "0.0.0",
     "typescript": "4.8.4"
   },
   "engines": {
-    "node": "^16 || ^18",
-    "homebridge": ">=1.4.0"
+    "node": "^16 || ^18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/dgreif/ring.git"
   },
   "bugs": {
     "url": "https://github.com/dgreif/ring/issues"
   },
-  "homepage": "https://github.com/dgreif/ring#readme",
+  "homepage": "https://github.com/dgreif/ring/tree/main/packages/ring-client-api#ring-client-api",
+  "author": "dgreif",
+  "license": "MIT",
   "funding": [
     {
       "type": "paypal",
@@ -114,7 +64,24 @@
       "url": "https://github.com/sponsors/dgreif"
     }
   ],
-  "workspaces": [
-    "homebridge-ui"
+  "bin": {
+    "ring-auth-cli": "lib/ring-auth-cli.js",
+    "ring-device-data-cli": "lib/ring-device-data-cli.js"
+  },
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "ring",
+    "doorbell",
+    "doorbot",
+    "camera",
+    "alarm",
+    "smart",
+    "light",
+    "beam",
+    "security",
+    "client",
+    "api"
   ]
 }