feat: added support for virtual devices

Author: bflorian

src/endpoint/virtualdevices.ts

@@ -0,0 +1,88 @@
+import { Endpoint} from '../endpoint'
+import { EndpointClient, EndpointClientConfig, HttpClientParams } from '../endpoint-client'
+import { CommandMapping, Device, DeviceEvent } from './devices'
+import { DeviceProfileCreateRequest } from './deviceprofiles'
+
+
+export interface VirtualDeviceOwner {
+	ownerType: VirtualDeviceOwnerTypeEnum
+	ownerId: string
+}
+
+export type VirtualDeviceOwnerTypeEnum = 'USER' | 'LOCATION'
+
+export type ExecutionTarget = 'CLOUD' | 'LOCAL'
+
+export interface VirtualDeviceCreateRequest {
+	name: string
+	owner: VirtualDeviceOwner
+	deviceProfileId?: string
+	deviceProfile?: DeviceProfileCreateRequest
+	roomId?: string
+	commandMappings?: CommandMapping
+	executionTarget?: ExecutionTarget
+	hubId?: string
+	driverId?: string
+}
+
+export interface VirtualDeviceStandardCreateRequest {
+	name: string
+	owner: VirtualDeviceOwner
+	prototype: string
+	roomId?: string
+	executionTarget?: ExecutionTarget
+	hubId?: string
+	driverId?: string
+}
+
+export interface VirtualDeviceListOptions {
+	locationId?: string
+}
+
+export interface VirtualDeviceEventsResponse {
+	stateChanges: boolean[]
+}
+
+export class VirtualDevicesEndpoint extends Endpoint {
+	constructor(config: EndpointClientConfig) {
+		super(new EndpointClient('virtualdevices', config))
+	}
+
+	/**
+	 * Returns list of virtual devices.
+	 * @param options map of filter options. Currently only 'locationId' is supported.
+	 */
+	public list(options: VirtualDeviceListOptions = {}): Promise<Device[]> {
+		const params: HttpClientParams = {}
+		if ('locationId' in options && options.locationId) {
+			params.locationId = options.locationId
+		} else if (this.client.config.locationId) {
+			params.locationId = this.client.config.locationId
+		}
+		return this.client.getPagedItems<Device>(undefined, params)
+	}
+
+	/**
+	 * Create a virtual device from a device profile. An existing device profile can be designated by ID, or the
+	 * definition of a device profile can be provided inline.
+	 */
+	public create(definition: VirtualDeviceCreateRequest): Promise<Device> {
+		return this.client.post<Device>('', definition)
+	}
+
+	/**
+	 * Creates a virtual device from a standard prototype.
+	 */
+	public createStandard(definition: VirtualDeviceStandardCreateRequest): Promise<Device> {
+		return this.client.post<Device>('prototypes', definition)
+	}
+
+	/**
+	 * Creates events for the specified device
+	 * @param id UUID of the device
+	 * @param deviceEvents list of events
+	 */
+	public createEvents(id: string, deviceEvents: DeviceEvent[]): Promise<VirtualDeviceEventsResponse> {
+		return this.client.post(`${id}/events`, { deviceEvents })
+	}
+}

src/index.ts

@@ -29,3 +29,4 @@ export * from './endpoint/schedules'
 export * from './endpoint/schema'
 export * from './endpoint/services'
 export * from './endpoint/subscriptions'
+export * from './endpoint/virtualdevices'

src/st-client.ts

@@ -23,6 +23,7 @@ import { SubscriptionsEndpoint } from './endpoint/subscriptions'
 import { SchedulesEndpoint } from './endpoint/schedules'
 import { SchemaEndpoint } from './endpoint/schema'
 import { ServicesEndpoint } from './endpoint/services'
+import { VirtualDevicesEndpoint } from './endpoint/virtualdevices'
 import { SmartThingsURLProvider, defaultSmartThingsURLProvider, HttpClientHeaders } from './endpoint-client'
 
 
@@ -48,6 +49,7 @@ export class SmartThingsClient extends RESTClient {
 	public readonly schedules: SchedulesEndpoint
 	public readonly schema: SchemaEndpoint
 	public readonly services: ServicesEndpoint
+	public readonly virtualDevices: VirtualDevicesEndpoint
 
 	constructor(authenticator: Authenticator, config?: RESTClientConfig) {
 		super(authenticator, config)
@@ -73,6 +75,7 @@ export class SmartThingsClient extends RESTClient {
 		this.schedules = new SchedulesEndpoint(this.config)
 		this.schema = new SchemaEndpoint(this.config)
 		this.services = new ServicesEndpoint(this.config)
+		this.virtualDevices = new VirtualDevicesEndpoint(this.config)
 	}
 
 	public setLocation(id: string): SmartThingsClient {

test/unit/virtualdevices.test.ts

@@ -0,0 +1,143 @@
+import { Device, DeviceEvent }  from '../../src/endpoint/devices'
+import {
+	VirtualDeviceCreateRequest,
+	VirtualDeviceStandardCreateRequest,
+	VirtualDevicesEndpoint,
+} from '../../src/endpoint/virtualdevices'
+import { BearerTokenAuthenticator } from '../../src/authenticator'
+import { EndpointClient } from '../../src/endpoint-client'
+
+
+const authenticator = new BearerTokenAuthenticator('00000000-0000-0000-0000-000000000000')
+
+describe('VirtualDevicesEndpoint', () => {
+	afterEach(() => {
+		jest.clearAllMocks()
+	})
+
+	const postSpy = jest.spyOn(EndpointClient.prototype, 'post').mockImplementation()
+	const getPagedItemsSpy = jest.spyOn(EndpointClient.prototype, 'getPagedItems').mockImplementation()
+
+	const virtualDevicesEndpoint = new VirtualDevicesEndpoint({ authenticator })
+
+	const deviceList = [{ listed: 'device' }] as unknown as Device[]
+
+	describe('list', () => {
+		getPagedItemsSpy.mockResolvedValue(deviceList)
+
+		it('works without options', async () => {
+			expect(await virtualDevicesEndpoint.list()).toBe(deviceList)
+
+			expect(getPagedItemsSpy).toHaveBeenCalledTimes(1)
+			expect(getPagedItemsSpy).toHaveBeenCalledWith(undefined, {})
+		})
+
+		it('includes configured locationId', async () => {
+			const devices = new VirtualDevicesEndpoint({ authenticator, locationId: 'configured-location-id' })
+			expect(await devices.list()).toBe(deviceList)
+
+			expect(getPagedItemsSpy).toHaveBeenCalledTimes(1)
+			expect(getPagedItemsSpy).toHaveBeenCalledWith(undefined, { locationId: 'configured-location-id' })
+		})
+
+		it('include wanted locationId', async () => {
+			expect(await virtualDevicesEndpoint.list({ locationId: 'wanted-locationId' })).toBe(deviceList)
+
+			expect(getPagedItemsSpy).toHaveBeenCalledTimes(1)
+			expect(getPagedItemsSpy).toHaveBeenCalledWith(undefined, { locationId: 'wanted-locationId' })
+		})
+	})
+
+	describe('create', () => {
+		it('creates from device profile ID', async () => {
+			const device = { new: 'device' }
+			postSpy.mockResolvedValueOnce(device)
+
+			const deviceCreate: VirtualDeviceCreateRequest = {
+				owner: {
+					ownerId: 'owner-id',
+					ownerType: 'LOCATION',
+				},
+				name: 'Living room light',
+				roomId: 'room-id',
+				deviceProfileId: 'profile-id',
+			}
+
+			const expectedData = deviceCreate
+
+			expect(await virtualDevicesEndpoint.create(deviceCreate)).toBe(device)
+
+			expect(postSpy).toHaveBeenCalledTimes(1)
+			expect(postSpy).toHaveBeenCalledWith('', expectedData)
+		})
+
+		it('creates from device profile definition', async () => {
+			const device = { new: 'device' }
+			postSpy.mockResolvedValueOnce(device)
+
+			const deviceCreate: VirtualDeviceCreateRequest = {
+				owner: {
+					ownerId: 'owner-id',
+					ownerType: 'LOCATION',
+				},
+				name: 'Living room light',
+				roomId: 'room-id',
+				deviceProfile: {
+					'components': [
+						{
+							'id': 'main',
+							'capabilities': [
+								{
+									'id': 'switch',
+									'version': 1,
+								},
+							],
+							'categories': [],
+						},
+					],
+				},
+			}
+
+			const expectedData = deviceCreate
+
+			expect(await virtualDevicesEndpoint.create(deviceCreate)).toBe(device)
+
+			expect(postSpy).toHaveBeenCalledTimes(1)
+			expect(postSpy).toHaveBeenCalledWith('', expectedData)
+		})
+	})
+
+	describe('createStandard', () => {
+		it('creates from prototype', async () => {
+			const device = {new: 'device'}
+			postSpy.mockResolvedValueOnce(device)
+
+			const deviceCreate: VirtualDeviceStandardCreateRequest = {
+				owner: {
+					ownerId: 'owner-id',
+					ownerType: 'LOCATION',
+				},
+				name: 'Living room light',
+				roomId: 'room-id',
+				prototype: 'SWITCH',
+			}
+
+			const expectedData = deviceCreate
+
+			expect(await virtualDevicesEndpoint.createStandard(deviceCreate)).toBe(device)
+
+			expect(postSpy).toHaveBeenCalledTimes(1)
+			expect(postSpy).toHaveBeenCalledWith('prototypes', expectedData)
+		})
+	})
+
+	test('createEvents', async () => {
+		const events: DeviceEvent[] = [{ component: 'main' } as DeviceEvent]
+		postSpy.mockResolvedValueOnce([true])
+
+		expect(await virtualDevicesEndpoint.createEvents('device-id', events)).toStrictEqual([true])
+
+		expect(postSpy).toHaveBeenCalledTimes(1)
+		expect(postSpy).toHaveBeenCalledWith('device-id/events', { deviceEvents: events })
+	})
+})