{"id":18695341,"url":"https://github.com/smartthingscommunity/smartthings-core-sdk","last_synced_at":"2025-04-05T12:09:18.631Z","repository":{"id":37854077,"uuid":"243361636","full_name":"SmartThingsCommunity/smartthings-core-sdk","owner":"SmartThingsCommunity","description":"SDK for calling the SmartThings API from JavaScript and TypeScript applications","archived":false,"fork":false,"pushed_at":"2024-04-23T18:42:33.000Z","size":2551,"stargazers_count":108,"open_issues_count":1,"forks_count":54,"subscribers_count":76,"default_branch":"main","last_synced_at":"2024-04-23T20:32:02.579Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmartThingsCommunity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-26T20:43:08.000Z","updated_at":"2024-06-17T15:11:21.778Z","dependencies_parsed_at":"2023-02-11T22:01:57.704Z","dependency_job_id":"d3d6017e-8af1-4136-8f9e-233f2704dd52","html_url":"https://github.com/SmartThingsCommunity/smartthings-core-sdk","commit_stats":{"total_commits":220,"total_committers":13,"mean_commits":"16.923076923076923","dds":0.7545454545454545,"last_synced_commit":"081d93015637c6e9fd85faadabc300a5477f4f8f"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fsmartthings-core-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fsmartthings-core-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fsmartthings-core-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fsmartthings-core-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmartThingsCommunity","download_url":"https://codeload.github.com/SmartThingsCommunity/smartthings-core-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T11:14:40.732Z","updated_at":"2025-04-05T12:09:18.610Z","avatar_url":"https://github.com/SmartThingsCommunity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SmartThings Core SDK\n\nThe SmartThings Core SDK is a wrapper designed to simplify the use of the\n[SmartThings REST API](https://developer.smartthings.com/docs/api/public)\nfrom JavaScript and TypeScript applications. This is the very first release of this SDK and should be considered\na work in progress. Changes may still be made that are not backwardly compatible.\n\n\n## Installation\n\n```bash\nnpm install @smartthings/core-sdk\n```\n\n:warning: Note that if you use axios in your project, you must use version 0.28.1 or later.\n\n## Importing\n\n`NodeJS`:\n\n```javascript\nconst {SmartThingsClient} = require('@smartthings/core-sdk')\n```\n\nOr `ES2015`+:\n\n```javascript\nimport {SmartThingsClient} from '@smartthings/core-sdk'\n```\n\n## Example Usage\nFor this example, you'll need to create a [Personal Access Token (PAT)](https://account.smartthings.com/tokens)\nwith at least the `r:locations:*` scope. Substitute it for `YOUR-PAT-HERE` in the following code:\n```javascript\nconst {SmartThingsClient, BearerTokenAuthenticator} = require('@smartthings/core-sdk')\nconst client = new SmartThingsClient(new BearerTokenAuthenticator('YOUR-PAT-HERE'))\n\nclient.locations.list().then(locations =\u003e {\n    console.log(`Found ${locations.length} locations`)\n})\n\n```\n\n## Logging\n\nThere is some logging done of requests and responses made to the API. The\ndefault logger does nothing but you can pass your own. Logging is done via a generic interface so\nyou can use whatever logger you want in your application.\n\nFirst, write an implementation of the `Logger` interface defined in\n[logger.ts](src/logger.ts)\nwhich proxies to your logger. For example:\n\n```javascript\nimport { Logger as WinstonLogger } from 'winston'\nimport { Logger } from '@smartthings/core-sdk'\n\n\nexport class WinstonLoggerProxy implements Logger {\n\tproxy: WinstonLogger\n\tlevel: string\n\n\tconstructor(winstonLogger) {\n\t\tthis.level = proxy.level\n\t}\n\n\ttrace(message: any, ...args: any[]): void {\n\t\t// Winston doesn't have a \"trace\" level but it has a \"silly\" level in the same place.\n\t\tproxy.silly(message, args)\n\t}\n\n\tdebug(message: any, ...args: any[]): void {\n\t\tproxy.debug(message, args)\n\t}\n\n\tinfo(message: any, ...args: any[]): void {\n\t\tproxy.info(message, args)\n\t}\n\n\t...\n\n\tisTraceEnabled(): boolean {\n\t\treturn proxy.isSillyEnabled()\n\t}\n\n\t...\n}\n```\n\nThen, when you create your `SmartThingsClient`, pass this in via the `config` parameter.\n\n```javascript\nconst config = {\n\tlogger: new WinstonLoggerProxy(myWinstonLoggerInstance)\n}\nconst client = new SmartThingsClient(new BearerTokenAuthenticator('{YOUR-PAT-TOKEN}'), config)\n```\n\n## Reference\n\n### Authenticators\n\nThis SDK supports multiple ways of authenticating with the SmartThings platform. The currently available authenticators\nare:\n\n* [BearerTokenAuthenticator](src/authenticator.ts#L55) -- Authenticator that is instantiated with any valid bearer\ntoken. This is the authenticator you would use with a PAT (Personal Access) Token.\n\n* [RefreshTokenAuthenticator](src/authenticator.ts#L99) -- Authenticator that is instantiated with a bearer token and\na [RefreshTokenStore](src/authenticator.ts#L86) that provides methods for retrieving and storing access and refresh\ntokens. When this authenticator is used the API will automatically refresh expired access tokens, save the new tokens,\nand retry the original request.\n\n* [SequentialRefreshTokenAuthenticator](src/authenticator.ts#L151)\n\n### Endpoints\n\n* apps -- A SmartApp can be an AWS lambda function or WebHook endpoint. Like to code interface [here](src/endpoint/apps.ts#L267), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Apps)\n\n* capabilities - Operations to read standard Capability definitions as well as create and modify custom Capabilities.  Link to code interface [here](src/endpoint/capabilities.ts#L763), link to wiki page [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Capabilities).\n\n* deviceProfiles - A Device Profile contains the Components, Capabilities, and metadata (ID, name, ownership, etc.) that define a SmartThings Device. Link to code interface [here](src/endpoint/deviceprofiles.ts#L93), link to wiki page [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Device-Profiles)\n\n* devices - Operations to access, control, create, update, and delete Devices.  Like to code interface [here](src/endpoint/devices.ts#L658), link to wiki page [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Devices)\n\n* history - Operations to query event history. Link to code interface [here](src/endpoint/history.ts#L96).\n\n* installedApps - Apps are installed by users.  Link to code interface [here](src/endpoint/installedapps.ts#L331), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Installed-Apps)\n\n* locations - Locations can include Hubs, Devices, and Automations.  Link to code interface [here](src/endpoint/locations.ts#L141), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Locations)\n\n* modes - Operations to change the current Mode of a Location.  Link to code interface [here](src/endpoint/modes.ts#L26), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Modes)\n\n* notifications - Operations to send push notifications to SmartThings mobile app.  Link to code interface [here](src/endpoint/notifications.ts#L83), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Notifications)\n\n* organizations - Operations to list and get Organizations. Link to code interface [here](src/endpoint/organizations.ts#L38). _Future feature. Not yet supported._\n\n* presentation - Operations to query and create Device Configurations and Presentations. Link to code interface [here](src/endpoint/presentation.ts#L189).\n\n* rooms - Operations related to Rooms, a grouping of Devices within a Location.  Link to code interface [here](src/endpoint/rooms.ts#L26), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Rooms)\n\n* rules - Operations for working with Rules.  Rules allow you to create Automations that can operate on SmartThings connected Devices.  Link to code interface [here](src/endpoint/rules.ts#L351), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Rules)\n\n* scenes - Operations to list and execute Scenes.  Currently this endpoint does not support creating or updating Scenes.  Link to code interface [here](src/endpoint/scenes.ts#L56), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Scenes)\n\n* schedules - Operations for scheduling future executions for use in SmartApps.  Link to code interface [here](src/endpoint/schedules.ts#L80), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Schedules)\n\n* schema - Operations for ST Schema connectors and installed instances, along with operations to list the Devices owned by each installed instance. Link to code interface [here](src/endpoint/schema.ts#L244), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Schema)\n\n* services - Operations to query for and subscribe to location service data, currently consisting of current weather conditions, weather forecast, and air quality data.  Link to code interface [here](src/endpoint/services.ts#L499), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Services)\n\n* subscriptions -  Operations for subscribing to events, for use in SmartApps and API Access apps.  Link to code interface [here](src/endpoint/subscriptions.ts#L213), link to wiki page description [here](https://github.com/SmartThingsCommunity/smartthings-core-sdk/wiki/Subscriptions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fsmartthings-core-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartthingscommunity%2Fsmartthings-core-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fsmartthings-core-sdk/lists"}