feat: add support for China

Author: rossiam

.changeset/moody-bars-act.md

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

src/endpoint-client.ts

@@ -21,16 +21,21 @@ export type HttpClientMethod =
 
 export interface SmartThingsURLProvider {
 	baseURL: string
-	authURL: string
-	keyApiURL: string
+	authURL?: string
+	keyApiURL?: string
 }
 
-export const defaultSmartThingsURLProvider: SmartThingsURLProvider = {
+export const globalSmartThingsURLProvider: Required<SmartThingsURLProvider> = {
 	baseURL: 'https://api.smartthings.com',
 	authURL: 'https://auth-global.api.smartthings.com/oauth/token',
 	keyApiURL: 'https://key.smartthings.com',
 }
 
+export const chinaSmartThingsURLProvider: SmartThingsURLProvider = {
+	// When login auth flow is added for China, make authURL required again.
+	baseURL: 'https://api.samsungiotcloud.cn',
+}
+
 export interface EndpointClientConfig {
 	authenticator: Authenticator
 	urlProvider?: SmartThingsURLProvider
@@ -50,8 +55,8 @@ export interface EndpointClientConfig {
 	warningLogger?: (warnings: WarningFromHeader[] | string) => void | Promise<void>
 }
 
-export interface ItemsList {
-	items: []
+export interface ItemsList<T> {
+	items: T[]
 	_links?: {
 		next?: {
 			href: string
@@ -269,11 +274,11 @@ export class EndpointClient {
 		return this.request('delete', path, undefined, params, options)
 	}
 
-	public async getPagedItems<T = unknown>(path?: string, params?: HttpClientParams, options?: EndpointClientRequestOptions<ItemsList>): Promise<T[]> {
-		let list = await this.get<ItemsList>(path, params, options)
+	public async getPagedItems<T = unknown>(path?: string, params?: HttpClientParams, options?: EndpointClientRequestOptions<ItemsList<T>>): Promise<T[]> {
+		let list = await this.get<ItemsList<T>>(path, params, options)
 		const result = list.items
 		while (list._links && list._links.next) {
-			list = await this.get<ItemsList>(list._links.next.href, undefined, options)
+			list = await this.get<ItemsList<T>>(list._links.next.href, undefined, options)
 			result.push(...list.items)
 		}
 		return result

src/endpoint/devices.ts

@@ -783,7 +783,7 @@ export interface CapabilityStatus {
 }
 
 export interface ComponentStatus {
-	[attributeName: string]: CapabilityStatus
+	[capabilityName: string]: CapabilityStatus
 }
 
 export interface DeviceStatus {

src/endpoint/schema.ts

@@ -302,6 +302,8 @@ export class SchemaEndpoint extends Endpoint {
 	 */
 	public async update(id: string, data: SchemaAppRequest, organizationId?: string): Promise<Status> {
 		const options = organizationId ? { headerOverrides: { 'X-ST-Organization': organizationId } } : undefined
+		// The API documentation says this should return the updated schema app but it does not.
+		// Rather, on success, it simply returns an empty body.
 		await this.client.put<SchemaApp>(`apps/${id}`, data, undefined, options)
 		return SuccessStatusValue
 	}

src/rest-client.ts

@@ -1,6 +1,6 @@
 import { Authenticator } from './authenticator'
 import { EndpointClientConfig, HttpClientHeaders, SmartThingsURLProvider,
-	defaultSmartThingsURLProvider, WarningFromHeader } from './endpoint-client'
+	globalSmartThingsURLProvider, WarningFromHeader } from './endpoint-client'
 import { Logger } from './logger'
 
 
@@ -30,7 +30,7 @@ export class RESTClient {
 	constructor(authenticator: Authenticator, config?: RESTClientConfig) {
 		const defaultConfig = {
 			authenticator,
-			urlProvider: defaultSmartThingsURLProvider,
+			urlProvider: globalSmartThingsURLProvider,
 			useAuth: true,
 		}
 		const headers = (config && config.headers)

src/signature.ts

@@ -1,7 +1,8 @@
 import axios from 'axios'
-import sshpk from 'sshpk'
 import httpSignature from 'http-signature'
-import { SmartThingsURLProvider, defaultSmartThingsURLProvider } from './endpoint-client'
+import sshpk from 'sshpk'
+
+import { SmartThingsURLProvider, globalSmartThingsURLProvider } from './endpoint-client'
 import { Logger } from './logger'
 
 
@@ -23,11 +24,14 @@ export class HttpKeyResolver {
 	private keyCacheTTL: number
 
 	constructor(config?: KeyResolverConfig ) {
-		this.keyApiUrl = defaultSmartThingsURLProvider.keyApiURL
+		this.keyApiUrl = globalSmartThingsURLProvider.keyApiURL
 		this.keyCache = undefined
 		this.keyCacheTTL = (24 * 60 * 60 * 1000)
 		if (config) {
 			if (config.urlProvider) {
+				if (!config.urlProvider.keyApiURL) {
+					throw Error('keyApiURL is required in urlProvider')
+				}
 				this.keyApiUrl = config.urlProvider.keyApiURL
 			}
 			if (config.keyCacheTTL) {

src/st-client.ts

@@ -26,7 +26,7 @@ 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'
+import { SmartThingsURLProvider, globalSmartThingsURLProvider, HttpClientHeaders } from './endpoint-client'
 
 
 export class SmartThingsClient extends RESTClient {
@@ -103,7 +103,7 @@ export class SmartThingsOAuthClient {
 
 	constructor(private clientId: string, private clientSecret: string,
 			private redirectUri: string, urlProvider?: SmartThingsURLProvider) {
-		this.authURL = urlProvider?.authURL || defaultSmartThingsURLProvider.authURL
+		this.authURL = urlProvider?.authURL || globalSmartThingsURLProvider.authURL
 	}
 
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any

test/unit/authenticator.test.ts

@@ -1,16 +1,16 @@
 import axios from '../../__mocks__/axios'
-import { MutexInterface } from 'async-mutex'
+import { type MutexInterface } from 'async-mutex'
 
 import {
-	AuthData,
-	RefreshData,
+	type AuthData,
+	type RefreshData,
 	NoOpAuthenticator,
 	BearerTokenAuthenticator,
 	RefreshTokenAuthenticator,
 	RefreshTokenStore,
 	SequentialRefreshTokenAuthenticator,
 } from '../../src/authenticator'
-import { defaultSmartThingsURLProvider } from '../../src/endpoint-client'
+import { globalSmartThingsURLProvider } from '../../src/endpoint-client'
 
 
 class TokenStore implements RefreshTokenStore {
@@ -23,6 +23,7 @@ class TokenStore implements RefreshTokenStore {
 		return Promise.resolve()
 	}
 }
+
 describe('authenticators', () => {
 	afterEach(() => {
 		jest.clearAllMocks()
@@ -59,7 +60,7 @@ describe('authenticators', () => {
 
 			const tokenStore = new TokenStore()
 			const authenticator = new RefreshTokenAuthenticator('a-refreshable-bearer-token', tokenStore)
-			const endpointConfig = { urlProvider: defaultSmartThingsURLProvider, authenticator }
+			const endpointConfig = { urlProvider: globalSmartThingsURLProvider, authenticator }
 
 			expect(await authenticator.refresh(endpointConfig)).toStrictEqual({ Authorization: 'Bearer the-access-token' })
 
@@ -86,7 +87,7 @@ describe('authenticators', () => {
 
 			const tokenStore = new TokenStore()
 			const authenticator = new RefreshTokenAuthenticator('a-refreshable-bearer-token', tokenStore)
-			const endpointConfig = { urlProvider: defaultSmartThingsURLProvider, authenticator }
+			const endpointConfig = { urlProvider: globalSmartThingsURLProvider, authenticator }
 			let message
 			try {
 				await authenticator.refresh(endpointConfig)
@@ -120,7 +121,7 @@ describe('authenticators', () => {
 				},
 			})
 
-			const endpointConfig = { urlProvider: defaultSmartThingsURLProvider, authenticator }
+			const endpointConfig = { urlProvider: globalSmartThingsURLProvider, authenticator }
 
 			it('updates token', async () => {
 				await authenticator.refresh(endpointConfig)

test/unit/endpoint-client.test.ts

@@ -1,12 +1,25 @@
 import { Mutex } from 'async-mutex'
-import axios, { AxiosError, AxiosRequestConfig, AxiosResponse, ParamsSerializerOptions } from 'axios'
+import axios, { AxiosError, type AxiosRequestConfig, type AxiosResponse, type ParamsSerializerOptions } from 'axios'
 import qs from 'qs'
 
-import { AuthData, Authenticator, BearerTokenAuthenticator, NoOpAuthenticator, RefreshData,
-	RefreshTokenAuthenticator, RefreshTokenStore, SequentialRefreshTokenAuthenticator }
-	from '../../src/authenticator'
-import { defaultSmartThingsURLProvider, EndpointClient, EndpointClientConfig, HttpClientHeaders, parseWarningHeader } from '../../src/endpoint-client'
-import { Logger, NoLogLogger } from '../../src/logger'
+import {
+	type AuthData,
+	type Authenticator,
+	BearerTokenAuthenticator,
+	NoOpAuthenticator,
+	type RefreshData,
+	RefreshTokenAuthenticator,
+	type RefreshTokenStore,
+	SequentialRefreshTokenAuthenticator,
+} from '../../src/authenticator'
+import {
+	EndpointClient,
+	type EndpointClientConfig,
+	type HttpClientHeaders,
+	globalSmartThingsURLProvider,
+	parseWarningHeader,
+} from '../../src/endpoint-client'
+import { type Logger, NoLogLogger } from '../../src/logger'
 
 
 jest.mock('axios')
@@ -86,7 +99,7 @@ describe('EndpointClient',  () => {
 	let client: EndpointClient
 
 	const configWithoutHeaders = {
-		urlProvider: defaultSmartThingsURLProvider,
+		urlProvider: globalSmartThingsURLProvider,
 		authenticator: new RefreshTokenAuthenticator(token, tokenStore),
 		baseURL: 'https://api.smartthings.com',
 		authURL: 'https://auth.smartthings.com',