HAT JavaScript SDK

Overview

This library contains all the API calls needed to communicate with the HAT

  • Handle user authentication.
  • Fetch Applications and Data Plugs.
  • Fetch Data Debits
  • Read and write data to endpoints.

Supported Environments

HAT JavaScript SDK supports all the modern browsers. Some older browsers do not support all the features required by HAT JavaScript SDK. If you want to support these browsers you need to load polyfills for Promise and Fetch.

Installation

HAT JavaScript SDK is available as @dataswift/hat-js package on npm.

NPM installation

npm install @dataswift/hat-js

CDN Link

<script src="https://cdn.dataswift.io/libs/hatjs/hat-0.1.4.min.js"></script>

Usage

Importing

ES6

import { HatClient } from "@dataswift/hat-js";

ES5 Modules

var HatClient = require("@dataswift/hat-js");

Initialisation

Configuration:

interface HatClientConfig {
    apiVersion?: string; // Api Version for the HAT. eg. v2.6
    hatDomain?: string; // The HAT domain of the user. eg. testing.hubat.net
    token?: string; // The Application token.
    secure?: boolean; // A flag to choose between https and http. eg. false is http
}

Example:

const config = {
    token: "abcdef1234567890",
    apiVersion: 'v2.6',
    secure: false
};

const hat = new HatClient(config);

Applications

Get all the apps

The are 2 ways to fetch applications:

With default options:

Example:

try {
    const result = await hat.applications().getAllDefault();
    
    if (result.parsedBody) {
        // result.parsedBody contains an array of Applications.
    }
} catch (error) {
    // The request failed...
}

With custom options:

Example:

// In custom options you can specify the following parameters: "ordering", "orderBy", "take", "skip"

const options = {
    ordering: "descending",
    orderBy: "name"
};

try {
    const result = await hat.applications().getAll(options);
    
    if (result.parsedBody) {
        // result.parsedBody contains an array of Applications.
    }
} catch (error) {
    // The request failed...
}

Get an application with a specific ID

Example:

try {
    const result = await hat.applications().getById("testhatapp");
    
    if (result.parsedBody) {
        // result.parsedBody contains the application.
    }
} catch (error) {
    // The request failed...
}

Get an application status

Parameters Type
application HatApplication

Example:

const status = hat.applications().getAppStatus(application);

console.log(status);
// Will print one of  'goto' | 'running' | 'fetching' | 'failing' | 'untouched' | 'update';

Generate a Data Plug setup URL

You can generate a URL in order to redirect the user to setup a Data Plug.

Parameters Type
application HatApplication
redirect string
fallback string

Example:

const redirectUrl = "https://myapp.dataswift.io/app/redirect";
const fallbackUrl = "https://myapp.dataswift.io/app/fallback";
const generatedUrl = hat.applications().getSetupUrl(application, redirectUrl, fallbackUrl);

console.log(generatedUrl); 
// Will print: https://testing.hubat.net/#/hatlogin?name=facebook&fallback=https://myapp.dataswift.io/app/fallback&redirect=https://facebook.hubofallthings.com%3Fredirect=https://myapp.dataswift.io/app/redirect

window.location.href = generatedUrl; // Navigate the user to setup the Data Plug.

HAT Data

Response type:

interface HatRecord<T> {
  endpoint: string; // eg. locations
  recordId: string; // A unique record ID of the record.
  data: T; // The Data
}

Write Data

Parameters Type
namespace string
endpoint string
body stringified Json

Response

  • HatRecord<T>

Example:

const namespace = "testhatapp";
const endpoint = "locations";
const newLocation = {
    latitude: "51.01",
    longitude: "52.12"
};

try {
    const result = await hat.hatData().create(
        namespace, 
        endpoint, 
        JSON.stringify(newLocation)
    );
    
    if (result.parsedBody) {
        // result.parsedBody contains a HatRecord with the new data.
    }
} catch (error) {
  // Failed to write data...
}

Update Data

Parameters Type
body Array<HatRecord<T>>

Response:

  • Array<HatRecord<T>>

Example:

const location = {
    endpoint: "testhatapp/locations",
    recordId: "c14b8f73-157f-40f1-9c77-985d9dea50d2",
    data: {
        latitude: "51.01",
        longitude: "52.12"
    }
};

location.data.latitude = "49.01";

const records = [location]; // Array of records to update. In this case we have only one.

try {
    const result = await hat.hatData().update(records);
    
    if (result.parsedBody) {
        // result.parsedBody contains an array of HatRecords<T> with the updated location data.
    }
} catch (error) {
  // Failed to update the records...
}

Delete Data

Parameters Type
recordsIds Array

Response:

  • A successful response message

Example:

const recordIds = ["c14b8f73-157f-40f1-9c77-985d9dea50d2", "d52b8f73-151f-40f1-9c77-932d9dea5daa"];

try {
    const result = await hat.hatData().delete(recordIds);
    
    if (result.parsedBody) {
        // result.parsedBody contains a successful response message.
        // In this case the result will be {message: "All records deleted"}.
    }
} catch (error) {
  // Failed to delete records...
}

Read Data

The are 2 ways to fetch data:

With default options:

Parameters Type
namespace string
endpoint string

Response

  • Array<HatRecord<T>>

Example:

const namespace = "testhatapp";
const endpoint = "locations";

try{
    const result = await hat.hatData().getAllDefault(namespace, endpoint);
    
    if (result.parsedBody) {
        // result.parsedBody contains an Array of HatRecord<Location>.
    }
} catch (error) {
    // Failed to fetch the data
}

With custom options:

Example:

const options = {
    ordering: "descending",
    orderBy: "lastUpdated"
};
const namespace = "testhatapp";
const endpoint = "locations";

try{
   const result = await hat.hatData().getAll(namespace, endpoint, options);
   
   if (result.parsedBody) {
       // result.parsedBody contains an Array of HatRecords<Location>, ordered by the last updated date.
   }
} catch (error) {
    // Failed to fetch the data
}

Data Debits

Get all the Data Debits

The are 2 ways to fetch data debits:

With default options:

Response:

Example:

try {
const result = await hat.dataDebits().getAllDefault();

if (result.parsedBody) {
    // result.parsedBody contains an array of Data Debits.
}
} catch (error) {
  // Failed to fetch Data Debits.
}

With custom options:

Parameters Type
options Object

Response:

Example:

// In custom options you can specify the following parameters: "ordering", "orderBy", "take", "skip"
const options = {
    ordering: "descending",
    orderBy: "name"
};

try {
    const result = await hat.dataDebits().getAll(options);
    
    if (result.parsedBody) {
        // result.parsedBody contains an array of Data Debits.
    }
} catch (error) {
  // Failed to fetch Data Debits.
}

Get a Data debit with a specific ID

Parameters Type
DataDebitId string

Response: DataDebit: The Data Debit object.

Example:

const result = await hat.dataDebits().getById("your-data-debit-id");

if (result.parsedBody) {
    // result.parsedBody contains the data debit.
}

Get Data debit values

Parameters Type
DataDebitId string

Response:

  • DataDebitValues: The data debit values bundle.

Response type:

interface DataDebitValues<T> {
  bundle: { [endpoint: string]: Array<HatRecord<T>> };
}

Example:

try {
    const result = await hat.dataDebits().getDataDebitValues("your-data-debit-id");
    
    if (result.parsedBody) {
        // result.parsedBody contains the bundle.
    }
} catch (error) {
  // Failed to get Data Debit values...
}

License

This work is licensed under the Mozilla Public License Version 2.0. Please read the LICENSE file for further details.