yoyoAPI

API Wrapper for Individual Product Users of Yolink / Yosmart Devices

Description

yoyoAPI is an open source wrapper that facilitates the use of the YoSmart API to manage YoLink devices. Specifically, yoyoAPI supports individual product users (UAC) API, also known as Open API V2.

Note that the documentation on the YoSmart website is not always up-to-date with the current responses. Only devices that could be tested have been included here. More to follow as additional Yosmart items are purchased. Here are the versions of supported devices:

Supported Devices and Versions

| Device Name | Model Name | Tested Version | | ------------- | ---------- | -------------- | | Hub | YS1603-UC | 0361 | | Outlet | YS6604-UC | 040e | | MotionSensor | YS7804-UC | 0471 | | DoorSensor* | YS7707-UC | 0704 | | GarageSensor* | YS7706-UC | 060f | | GarageDoor | YS4906-UC | 060b |

*GarageSensor uses the same interface as DoorSensor.

Features

• Automated Authentication and Token Refresh - yoyoAPI will automatically authenticate on the first API request, and then continually refresh as JWT tokens expire.
• Fully typesafe and intellisense for requests.
• Generate and Interact with Outlet, MotionSensor, and DoorSensor devices.
• Custom error response to resolve when inputs or responses from Open API V2 do not conform to current standards.
  • Any error code with 700XXX is custom and returned from yoyoApi. See list of custom error codes below.
  • Official error codes are listed on the documentation site, but this list is not comprehensive.
• Unit tests of basic functions and rudimentary integrated tests of API using Jest with ~74% coverage.

Custom Error Codes

| Code | Description | | ------ | ----------------------- | | 700101 | Invalid Server Response | | 700102 | Invalid Request Body | | 700103 | Authentication Error | | 700999 | Unknown yoyoApi Error |

yoyoApi Usage

const getYo = async () => {
    const yo = new yoyoApi(
        'ua_11111111111111111111111111111111',
        'sec_v1_xxxxxxxxxxxxxxxxxxxxxxxx'
    );

    // Create a Home class
    const home = yo.Home();

    // Get a full list of devices
    const deviceList = await home.getDeviceList();

    // Selecting a MotionSensor
    const motionDetails = deviceList.data.devices[1];
    const motionsensor = yo.MotionSensor(motionDetails);

    const result = await motionsensor.getState();

    if (result.code !== '000000') throw new Error('Errors Happen');

    console.log('Result: ' + JSON.stringify(result));
};

Technology

Every effort has been made to minimize the number of external packages used, and instead, favor native JavaScript methods (such as fetch()). Other packages and tools are listed below:

• Typescript
• Zod
• Bruno Opensource API Client
• Jest

Default URLs

The default URL for Open API V2 is: https://api.yosmart.com/open/yolink/v2/api

The default URL for obtaining a authorization token is: https://api.yosmart.com/open/yolink/token

Accounts and Credentials

To use the yoyoAPI wrapper you will need:

• An account within the YoLink system using the YoLink application on an Android or Apple device.
• Create Access Credentials for the API, including a UAID and a Secret Key.
  • From within the app: [Account] => [Advanced Settings] => [Personal Access Credentials] => [+]

ChangeLog

• v0.7.6 - Initial Publish
• v0.7.7 - Added Garage Door Control and Garage Door Sensor
• v0.7.8 - Minor name change to match product

Disclaimer

yoyoAPI, and any associated websites or works, are not affiliated with or in anyway endorsed by YoSmart Inc., or their division, YoLink.

Any product names, logos, brands, and other trademarks or images featured or referred to within are the property of their respective trademark holders. These trademark holders are not affiliated with yoyoAPI. These trademark holders do not sponsor or endorse yoyoAPI or any of it's software, comments, or services. yoyoAPI declares no affiliation, sponsorship, nor any partnerships with any registered trademarks unless otherwise stated.

Further, this software is provided "as-is," without any express or implied warranty of any kind. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. Use this software at your own risk. The authors and copyright holders disclaim all warranties, express or implied, including but not limited to any implied warranties of merchantability and fitness for a particular purpose. By using this software, you agree to bear all risks and responsibilities for any damages or losses that may result from its use.