Freedom SDK

FreedomSDK represents the methods to interface with the Freedom Robotics API.

Table of Contents

1. Introduction :blue_book:
2. Quick start :rocket:
   • Installation
   • Setup provider
   • Request data
   • Request more specific data
   • With Typescript
3. Developers :godmode:
   • Release and deploy package
     • Semantic versioning
     • How to bump versions
4. Links of interest :zap:

Introduction :blue_book:

This is the official software development kit to develop on top of Freedom Robotics API.

With this you will be able to develop assets with most of the available features Freedom has to offer.

Quick start :rocket:

Installation

With NPM:

npm i @freedomrobotics/freedom-sdk --save

With yarn:

yarn add @freedomrobotics/freedom-sdk

Setup provider

The provider is a singleton that stores basic aspects reused by the methods in this kit. Note: Each method pulls the config.

// import provider singleton
import FreedomSDKProvider from '@freedomrobotics/freedom-sdk/dist/esm/utility/provider';

// App inits
FreedomSDKProvider.setConfig({
    user: {}, // FreedomUser
    accountId: 'XXXXXXXXXXXXXXXXXXXXXXXXX', // Your account ID
    onAuthExpire: () => {
    }, // Optional callback when auth expired
    onError: () => {
    }  // Optional callback when the connection with the API throws an error
});

FreedomUser interface required properties are:

interface FreedomUser {
    account: string;
    first_name: string;
    last_name: string;
    user: string;
    email: string;
    token: string;
    secret: string;
}

Request data

import getDevices from '@freedomrobotics/freedom-sdk/dist/esm/methods/account/get-devices';

const fetchDevicesData = async () => {
    const devicesList = await getDevices();
    return devicesList;
};

Request more specific data

import getDevices from '@freedomrobotics/freedom-sdk/dist/esm/methods/account/get-devices';

const fetchDevicesAttributes = async () => {
    const devicesList = await getDevices({
        attributes: ['device', 'name']
    });
    return devicesList;
};

With Typescript

import getDevices from '@freedomrobotics/freedom-sdk/dist/esm/methods/account/get-devices';

// infered type fetchDevicesAttributes = () => Pick<FreedomDevice, 'device' | 'name'>[]
const fetchDevicesAttributes = async () => {
    const devicesList = await getDevices({
        attributes: ['device', 'name'] as const
    });
    return devicesList;
};

⬆ Table of contents

Developers :godmode:

Release and deploy package

The project uses Semantic Release, executed by a Github action when the main branch gets conventional commits messages that include specific header types.

Semantic versioning

Semantic versioning is a scheme that aims to communicate the level of compatibility between releases at a glance. It uses a three-part numbering system: major.minor.patch (e.g. 1.2.3) which may or may not be suffixed with special identifiers such as -alpha or -rc1 (release candidate).

Each part has a different meaning:

Major: incrementing this number (1.0.0 -> 2.0.0) indicates users should expect significant breaking changes.

Minor: the minor number (1.0.0 -> 1.1.0) is incremented when non-breaking features and changes have been released. Minor releases should be backwards-compatible.

Patch: a patch-level change (1.0.0. -> 1.0.1) is a non-breaking upgrade that introduces low-risk changes like fixing bugs or patching security issues.

A developer can quickly assess the risk of upgrading by comparing version numbers.

Major releases are risky and should be planned carefully as they represent breaking changes that the end users will have to deal with immediately after upgrading the library.

Minor and patch-level changes are much less likely to introduce incompatibilities and are safer to install.

How to bump versions

As said, pushing a commit to the main branch does the magic, by choosing the right header type.

git commit -m "feat: new method has been added"

Available header types and versions relationship:

| Header Type | Result | |:--------------------------------|:------------------------------------------------------------------| | fix, perf | Bump version to the next patch level (1.0.0 -> 1.0.1) and release | | feat | Bump version to the next minor level (1.0.0 -> 1.1.0) and release | | docs, build, ci, refactor, test | No version bump. No release. |

And for the footer types:

| Footer Type | Result | |:----------------------------|:------------------------------------------------------------------| | BREAKING CHANGE, DEPRECATED | Bump version to next major level (1.1.1 -> 2.0.0) and release |

Important: Regardless of the header type, if the body of the commit message contains the string BREAKING CHANGE or DEPRECATED, semantic release performs a major version increase.

To clarify, let’s look at a few examples and their outcomes:

| Commit message | Result | |:----------------------------------------------------------------------------------------------------------------|:-------------------------| | fix: get baseURL from provider | Release a patch | | feat: new method has been added | Release a minor version | | perf: move entity methods from account scope to their entitiesBREAKING CHANGE: methods must be re-imported | Release a major version |

⬆ Table of contents

Links of interest :zap:

• Conventional commits
• Semantic Release
• Semantic versioning
• Typescript compiler options
• npm link

⬆ Table of contents