feat: add support for schema invitations

Author: rossiam

.changeset/fifty-onions-wash.md

@@ -0,0 +1,5 @@
+---
+"@smartthings/core-sdk": minor
+---
+
+add support for schema invitations

README.md

@@ -27,11 +27,11 @@ import {SmartThingsClient} from '@smartthings/core-sdk'
 ```
 
 ## Example Usage
-Substitue your Personal Access Token (PAT) with at least the `r:locations:*` scope
-for `{YOUR-PAT-TOKEN}` in the following code.
+For this example, you'll need to create a [Personal Access Token (PAT)](https://account.smartthings.com/tokens)
+with at least the `r:locations:*` scope. Substitute it for `YOUR-PAT-HERE` in the following code:
 ```javascript
 const {SmartThingsClient, BearerTokenAuthenticator} = require('@smartthings/core-sdk')
-const client = new SmartThingsClient(new BearerTokenAuthenticator('{YOUR-PAT-TOKEN}'))
+const client = new SmartThingsClient(new BearerTokenAuthenticator('YOUR-PAT-HERE'))
 
 client.locations.list().then(locations => {
     console.log(`Found ${locations.length} locations`)

src/endpoint.ts

@@ -2,9 +2,7 @@ import { EndpointClient } from './endpoint-client'
 
 
 export class Endpoint {
-	constructor(protected client: EndpointClient) {
-
-	}
+	constructor(protected client: EndpointClient) {}
 
 	locationId(id?: string): string {
 		const result = id || this.client.config.locationId

src/endpoint/invites-schemaApp.ts

@@ -0,0 +1,60 @@
+import { EndpointClient, EndpointClientConfig } from '../endpoint-client'
+import { Endpoint } from '../endpoint'
+
+
+export type SchemaAppId = {
+	schemaAppId: string
+}
+
+export type SchemaAppInvitationId = {
+	invitationId: string
+}
+
+export type SchemaAppInvitationSummary = {
+	invitationId: string
+	acceptUrl: string
+}
+
+export type SchemaAppInvitationCreate = SchemaAppId & {
+	description?: string
+}
+
+export type SchemaAppInvitation = SchemaAppId & {
+	id: string
+	description?: string
+	expiration?: number
+	acceptUrl?: string
+	declineUrl?: string
+	shortCode?: string
+}
+
+export type SchemaAppAcceptanceStatus = Omit<SchemaAppInvitation, 'id'> & {
+	isAccepted?: boolean
+}
+
+
+export class InvitesSchemaAppEndpoint extends Endpoint {
+	constructor(config: EndpointClientConfig) {
+		super(new EndpointClient('invites/schemaApp', config))
+	}
+
+	public async create(schemaAppInvitation: SchemaAppInvitationCreate): Promise<SchemaAppInvitationId> {
+		return this.client.post('', schemaAppInvitation)
+	}
+
+	public async list(schemaAppId: string): Promise<SchemaAppInvitation[]> {
+		return this.client.getPagedItems('', { schemaAppId })
+	}
+
+	public async revoke(invitationId: string): Promise<void> {
+		await this.client.delete(invitationId)
+	}
+
+	public async getAcceptanceStatus(invitationId: string): Promise<SchemaAppAcceptanceStatus> {
+		return this.client.get('checkAcceptance', { invitationId })
+	}
+
+	public async accept(shortCode: string): Promise<SchemaAppId> {
+		return this.client.put(`${shortCode}/accept`)
+	}
+}

src/index.ts

@@ -19,6 +19,7 @@ export * from './endpoint/drivers'
 export * from './endpoint/history'
 export * from './endpoint/hubdevices'
 export * from './endpoint/installedapps'
+export * from './endpoint/invites-schemaApp'
 export * from './endpoint/locations'
 export * from './endpoint/modes'
 export * from './endpoint/notifications'

src/st-client.ts

@@ -12,6 +12,7 @@ import { DriversEndpoint } from './endpoint/drivers'
 import { HistoryEndpoint } from './endpoint/history'
 import { HubdevicesEndpoint } from './endpoint/hubdevices'
 import { InstalledAppsEndpoint } from './endpoint/installedapps'
+import { InvitesSchemaAppEndpoint } from './endpoint/invites-schemaApp'
 import { ModesEndpoint } from './endpoint/modes'
 import { LocationsEndpoint } from './endpoint/locations'
 import { NotificationsEndpoint } from './endpoint/notifications'
@@ -39,10 +40,11 @@ export class SmartThingsClient extends RESTClient {
 	public readonly history: HistoryEndpoint
 	public readonly hubdevices: HubdevicesEndpoint
 	public readonly installedApps: InstalledAppsEndpoint
+	public readonly invitesSchema: InvitesSchemaAppEndpoint
+	public readonly locations: LocationsEndpoint
 	public readonly modes: ModesEndpoint
 	public readonly notifications: NotificationsEndpoint
 	public readonly organizations: OrganizationsEndpoint
-	public readonly locations: LocationsEndpoint
 	public readonly presentation: PresentationEndpoint
 	public readonly rooms: RoomsEndpoint
 	public readonly rules: RulesEndpoint
@@ -66,6 +68,7 @@ export class SmartThingsClient extends RESTClient {
 		this.history = new HistoryEndpoint(this.config)
 		this.hubdevices = new HubdevicesEndpoint(this.config)
 		this.installedApps = new InstalledAppsEndpoint(this.config)
+		this.invitesSchema = new InvitesSchemaAppEndpoint(this.config)
 		this.locations = new LocationsEndpoint(this.config)
 		this.modes = new ModesEndpoint(this.config)
 		this.notifications = new NotificationsEndpoint(this.config)

test/unit/invites-schemaApp.test.ts

@@ -0,0 +1,69 @@
+import { NoOpAuthenticator } from '../../src/authenticator'
+import { EndpointClient } from '../../src/endpoint-client'
+import { InvitesSchemaAppEndpoint, SchemaAppInvitation } from '../../src/endpoint/invites-schemaApp'
+
+
+afterEach(() => {
+	jest.clearAllMocks()
+})
+
+const postSpy = jest.spyOn(EndpointClient.prototype, 'post').mockImplementation()
+const getPagedItemsSpy = jest.spyOn(EndpointClient.prototype, 'getPagedItems').mockImplementation()
+const deleteSpy = jest.spyOn(EndpointClient.prototype, 'delete')
+const getSpy = jest.spyOn(EndpointClient.prototype, 'get').mockImplementation()
+const putSpy = jest.spyOn(EndpointClient.prototype, 'put').mockImplementation()
+
+const authenticator = new NoOpAuthenticator()
+const invitesEndpoint = new InvitesSchemaAppEndpoint( {authenticator})
+
+test('create', async () => {
+	const invitationId = { invitationId: 'my-invitation-id' }
+	const createData = { schemaAppId: 'schema-app-id' }
+
+	postSpy.mockResolvedValueOnce(invitationId)
+
+	expect(await invitesEndpoint.create(createData)).toBe(invitationId)
+
+	expect(postSpy).toHaveBeenCalledTimes(1)
+	expect(postSpy).toHaveBeenCalledWith('', createData)
+})
+
+test('list', async () => {
+	const invitations = [{ id: 'my-invitation-id' } as SchemaAppInvitation]
+
+	getPagedItemsSpy.mockResolvedValueOnce(invitations)
+
+	expect(await invitesEndpoint.list('schema-app-id')).toBe(invitations)
+
+	expect(getPagedItemsSpy).toHaveBeenCalledTimes(1)
+	expect(getPagedItemsSpy).toHaveBeenCalledWith('', { schemaAppId: 'schema-app-id' })
+})
+
+test('revoke', async () => {
+	await expect(invitesEndpoint.revoke('schema-app-id')).resolves.not.toThrow()
+
+	expect(deleteSpy).toHaveBeenCalledTimes(1)
+	expect(deleteSpy).toHaveBeenCalledWith('schema-app-id')
+})
+
+test('getAcceptanceStatus', async () => {
+	const status = [{ description: 'invitation description', isAccepted: true }]
+
+	getSpy.mockResolvedValueOnce(status)
+
+	expect(await invitesEndpoint.getAcceptanceStatus('invitation-id')).toBe(status)
+
+	expect(getSpy).toHaveBeenCalledTimes(1)
+	expect(getSpy).toHaveBeenCalledWith('checkAcceptance', { invitationId: 'invitation-id' })
+})
+
+test('accept', async () => {
+	const schemaAppId = { schemaAppId: 'schema-app-id' }
+
+	putSpy.mockResolvedValueOnce(schemaAppId)
+
+	expect(await invitesEndpoint.accept('short-code')).toBe(schemaAppId)
+
+	expect(putSpy).toHaveBeenCalledTimes(1)
+	expect(putSpy).toHaveBeenCalledWith('short-code/accept')
+})