Skip to content

Commit

Permalink
Merge branch 'main' into main
Browse files Browse the repository at this point in the history
  • Loading branch information
@Scrounger
Scrounger authored Dec 22, 2024
2 parents b95dccc + 70109de commit 7b7bfd8
Show file tree
Hide file tree
Showing 18 changed files with 3,825 additions and 1,890 deletions.
16 changes: 9 additions & 7 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,6 @@ jobs:
build:
name: 'Build package'

# Build only if we've received a push, manual workflow dispatch, or release event with a release tag (aka v1.2.3).
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/v'))

# Create the build matrix for all the environments we're validating against.
strategy:
matrix:
Expand All @@ -39,11 +36,12 @@ jobs:
node-version: ${{ matrix.node-version }}

- name: Build and install the package with a clean slate.
run: |
npm ci
npm run build --if-present
env:
CI: true
ESLINT_MAX_WARNINGS: 0
run: |
npm ci
npm run prepublishOnly
# Publish the release to the NPM registry.
publish-npm:
Expand All @@ -56,6 +54,10 @@ jobs:
# Specify the environment we're going to build in.
runs-on: ubuntu-latest

# Ensure we have permissions to provide our provenance attestation.
permissions:
id-token: write

# Execute the build and publish activities.
steps:
- name: Checkout the repository.
Expand All @@ -75,6 +77,6 @@ jobs:
run: npm ci

- name: Publish the package to NPM.
run: npm publish --access public
run: npm publish --access public --provenance
env:
NODE_AUTH_TOKEN: ${{ secrets.npm_token }}
37 changes: 37 additions & 0 deletions docs/Changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,43 @@

All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/).

## 4.18.0 (2024-12-22)
* Breaking change: the minimum supported node version is now node 20.
* Improvement: we've changed strategies to deal with Protect controller quirkiness/bugginess that results in network disconnects from the controller, while ensuring we have reasonable backpressure measures.
* Housekeeping.

## 4.17.0 (2024-12-08)
* Minor updates to the Protect JSON descriptions.
* Housekeeping.

## 4.16.0 (2024-10-05)
* New feature: ufp - a command line utility to query and execute some utility commands using the Protect API. You'll need to create either ~/.ufp.json or ufp.json in your current directory with the properties `controller`, `username`, `password` all defined in a valid JSON.
* Housekeeping.

## 4.15.1 (2024-09-29)
* Minor updates to the Protect JSON descriptions.
* Housekeeping.

## 4.15.0 (2024-09-26)
* New feature: added the `isThrottled` as a publicly accessible readonly property that returns whether the API connection is currently throttled due to connectivity issues.
* Housekeeping.

## 4.14.0 (2024-09-22)
* Updates to the Protect JSON descriptions.
* Housekeeping.

## 4.13.0 (2024-09-15)
* Updates to the Protect JSON descriptions.
* Housekeeping.

## 4.12.0 (2024-09-14)
* Change: API has been updated to reflect the recent changes to the Protect API by Ubiquiti to snapshots. Specifically, you can no longer specify a timestamp.
* Minor updates to the Protect JSON descriptions.
* Housekeeping.

## 4.11.1 (2024-06-06)
* Housekeeping.

## 4.11.0 (2024-06-03)
* Performance improvements and housekeeping.

Expand Down
114 changes: 69 additions & 45 deletions docs/ProtectApi.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[**unifi-protect**](README.md) • **Docs**
[**unifi-protect**](README.md)

***

Expand Down Expand Up @@ -31,7 +31,7 @@ Those are the basics that gets us up and running.

- `EventEmitter`

#### Constructor
#### Constructors

##### new ProtectApi()

Expand All @@ -44,27 +44,29 @@ Create an instance of the UniFi Protect API.
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `log`? | [`ProtectLogging`](ProtectLogging.md#protectlogging) | Logging functions to use. |
###### Returns
[`ProtectApi`](ProtectApi.md#protectapi)
###### Overrides
`EventEmitter.constructor`
###### Default Value
`none` - Logging will be done to stdout and stderr.
###### Overrides
`EventEmitter.constructor`
#### API Access
##### bootstrap
###### Get Signature
```ts
get bootstrap(): null | ProtectNvrBootstrapInterface
get bootstrap(): Nullable<ProtectNvrBootstrapInterface>
```
Access the Protect controller bootstrap JSON.
Expand All @@ -76,7 +78,7 @@ request to the Protect controller before accessing the bootstrap JSON.
###### Returns
`null` \| [`ProtectNvrBootstrapInterface`](ProtectTypes.md#protectnvrbootstrapinterface)
`Nullable`\<[`ProtectNvrBootstrapInterface`](ProtectTypes.md#protectnvrbootstrapinterface)\>
Returns the bootstrap JSON if the Protect controller has been bootstrapped, `null` otherwise.
Expand Down Expand Up @@ -110,7 +112,7 @@ Return an API endpoint for the requested endpoint type.
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `endpoint` | `string` | Requested endpoint type. |
###### Returns
Expand Down Expand Up @@ -204,50 +206,52 @@ process.stdout.write(util.inspect(ufp.bootstrap, { colors: true, depth: null, so
##### getSnapshot()

```ts
getSnapshot(
device,
width?,
height?,
timestamp?,
usePackageCamera?): Promise<null | Buffer>
getSnapshot(device, options): Promise<Nullable<Buffer<ArrayBufferLike>>>
```

Retrieve a snapshot image from a Protect camera.

###### Parameters

| Parameter | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `device` | [`ProtectCameraConfigInterface`](ProtectTypes.md#protectcameraconfiginterface) | `undefined` | Protect device. |
| `width`? | `number` | `undefined` | Optionally specify the image width to request. Defaults selected by the Protect controller, based on the camera resolution. |
| `height`? | `number` | `undefined` | Optionally specify the image height to request. Defaults selected by the Protect controller, based on the camera resolution. |
| `timestamp`? | `number` | `undefined` | Optionally specify the timestamp index to retrieve. Defaults to the current time. |
| `usePackageCamera`? | `boolean` | `false` | Optionally specify retrieving a snapshot fron the package camera, rather than the primary camera lens. Defaults to `false`. |
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `device` | [`ProtectCameraConfigInterface`](ProtectTypes.md#protectcameraconfiginterface) | Protect device. |
| `options` | `Partial`\<\{ `height`: `number`; `usePackageCamera`: `boolean`; `width`: `number`; \}\> | Parameters to pass on for the snapshot request. |

###### Returns

`Promise`\<`null` \| `Buffer`\>
`Promise`\<`Nullable`\<`Buffer`\<`ArrayBufferLike`\>\>\>

Returns a promise that will resolve to a Buffer containing the JPEG image snapshot if successful, and `null` otherwise.

###### Remarks

The `options` object for snapshot parameters accepts the following properties, all of which are optional:

| Property | Description |
|-------------------|------------------------------------------------------------------------------------------------------------|
| height | The image height to request. Defaults selected by the Protect controller, based on the camera resolution. |
| width | The image width to request. Defaults selected by the Protect controller, based on the camera resolution. |
| usePackageCamera | Retriver a snapshot fron the package camera rather than the primary camera lens. Defaults to `false`. |

##### getWsEndpoint()

```ts
getWsEndpoint(endpoint, params?): Promise<null | string>
getWsEndpoint(endpoint, params?): Promise<Nullable<string>>
```
Return a websocket API endpoint for the requested endpoint type.
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `endpoint` | `"livestream"` \| `"talkback"` | Requested endpoint type. Valid types are `livestream` and `talkback`. |
| `params`? | `URLSearchParams` | Parameters to pass on for the endpoint request. |
###### Returns
`Promise`\<`null` \| `string`\>
`Promise`\<`Nullable`\<`string`\>\>
Returns a promise that will resolve to a URL to the requested endpoint if successful, and `null` otherwise.
Expand All @@ -267,22 +271,22 @@ Valid API endpoints are `livestream` and `talkback`.
retrieve(
url,
options,
logErrors): Promise<null | Response>
logErrors): Promise<Nullable<Response>>
```
Execute an HTTP fetch request to the Protect controller.
###### Parameters
| Parameter | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| ------ | ------ | ------ | ------ |
| `url` | `string` | `undefined` | Complete URL to execute **without** any additional parameters you want to pass (e.g. https://unvr.local/proxy/protect/cameras/someid/snapshot). |
| `options` | `RequestOptions` | `undefined` | Parameters to pass on for the endpoint request. |
| `options` | `RequestOptions` | `...` | Parameters to pass on for the endpoint request. |
| `logErrors` | `boolean` | `true` | Log errors that aren't already accounted for and handled, rather than failing silently. Defaults to `true`. |
###### Returns
`Promise`\<`null` \| `Response`\>
`Promise`\<`Nullable`\<`Response`\>\>
Returns a promise that will resolve to a Response object successful, and `null` otherwise.
Expand All @@ -295,27 +299,27 @@ This method should be used when direct access to the Protect controller is neede
##### updateDevice()
```ts
updateDevice<DeviceType>(device, payload): Promise<null | DeviceType>
updateDevice<DeviceType>(device, payload): Promise<Nullable<DeviceType>>
```
Update a Protect device's configuration on the UniFi Protect controller.
###### Type parameters
###### Type Parameters
| Type parameter | Description |
| :------ | :------ |
| Type Parameter | Description |
| ------ | ------ |
| `DeviceType` *extends* [`ProtectKnownDeviceTypes`](ProtectApi.md#protectknowndevicetypes) | Generic for any known Protect device type. |
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `device` | `DeviceType` | Protect device. |
| `payload` | [`ProtectKnownDevicePayloads`](ProtectApi.md#protectknowndevicepayloads) | Device configuration payload to upload, usually a subset of the device-specific configuration JSON. |
###### Returns
`Promise`\<`null` \| `DeviceType`\>
`Promise`\<`Nullable`\<`DeviceType`\>\>
Returns a promise that will resolve to the updated device-specific configuration JSON if successful, and `null` otherwise.
Expand All @@ -328,6 +332,8 @@ Use this method to change the configuration of a given Protect device or control
##### isAdminUser
###### Get Signature
```ts
get isAdminUser(): boolean
```
Expand All @@ -340,8 +346,26 @@ Utility method that returns whether the credentials that were used to login to t
Returns `true` if the logged in user has administrative privileges, `false` otherwise.
##### isThrottled
###### Get Signature
```ts
get isThrottled(): boolean
```
Utility method that returns whether our connection to the Protect controller is currently throttled or not.
###### Returns
`boolean`
Returns `true` if the API has returned too many errors and is now throttled for a period of time, `false` otherwise.
##### name
###### Get Signature
```ts
get name(): string
```
Expand All @@ -358,20 +382,20 @@ Returns the Protect controller name in the following format:
##### enableRtsp()
```ts
enableRtsp(device): Promise<null | ProtectCameraConfigInterface>
enableRtsp(device): Promise<Nullable<ProtectCameraConfigInterface>>
```
Utility method that enables all RTSP channels on a given Protect camera.
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `device` | [`ProtectCameraConfigInterface`](ProtectTypes.md#protectcameraconfiginterface) | Protect camera to modify. |
###### Returns
`Promise`\<`null` \| [`ProtectCameraConfigInterface`](ProtectTypes.md#protectcameraconfiginterface)\>
`Promise`\<`Nullable`\<[`ProtectCameraConfigInterface`](ProtectTypes.md#protectcameraconfiginterface)\>\>
Returns a promise that will resolve to the updated [ProtectCameraConfig](ProtectTypes.md#protectcameraconfig) if successful, and `null` otherwise.
Expand All @@ -389,7 +413,7 @@ Utility method that generates a nicely formatted device information string.
###### Parameters
| Parameter | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| ------ | ------ | ------ | ------ |
| `device` | [`ProtectKnownDeviceTypes`](ProtectApi.md#protectknowndevicetypes) | `undefined` | Protect device. |
| `name` | `string` | `device.name` | Optional name for the device. Defaults to the device type (e.g. `G4 Pro`). |
| `deviceInfo` | `boolean` | `false` | Optionally specify whether or not to include the IP address and MAC address in the returned string. Defaults to `false`. |
Expand All @@ -416,7 +440,7 @@ Utility method that generates a combined, nicely formatted device and NVR string
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `device` | [`ProtectKnownDeviceTypes`](ProtectApi.md#protectknowndevicetypes) | Protect device. |
###### Returns
Expand Down Expand Up @@ -454,7 +478,7 @@ Execute a login attempt to the UniFi Protect API.
###### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| ------ | ------ | ------ |
| `nvrAddress` | `string` | Address of the UniFi Protect controller, expressed as an FQDN or IP address. |
| `username` | `string` | Username to use when logging into the controller. |
| `password` | `string` | Password to use when logging into the controller. |
Expand Down Expand Up @@ -516,7 +540,7 @@ Clear the login credentials and terminate any open connection to the UniFi Prote
### ProtectKnownDevicePayloads
```ts
type ProtectKnownDevicePayloads:
type ProtectKnownDevicePayloads =
| ProtectCameraConfigPayload
| ProtectChimeConfigPayload
| ProtectLightConfigPayload
Expand All @@ -532,7 +556,7 @@ Define our known Protect device payload types.
### ProtectKnownDeviceTypes
```ts
type ProtectKnownDeviceTypes:
type ProtectKnownDeviceTypes =
| ProtectCameraConfig
| ProtectChimeConfig
| ProtectLightConfig
Expand Down
Loading

0 comments on commit 7b7bfd8

Please sign in to comment.