@daktela/daktela-connector 1.0.0

package/.env.example

@@ -0,0 +1,2 @@
+INSTANCE="my.daktela.com"
+ACCESS_TOKEN="5f4dcc3b5aa765d61d8327deb882cf99"

package/CHANGELOG.md

@@ -0,0 +1,2 @@
+# 1.0.0
+Initial Version of the library.

package/README.md

@@ -0,0 +1,71 @@
+# Daktela V6 JavaScript Connector
+
+Daktela V6 JavaScript Connector is a library that connects your JavaScript application and your Daktela instance through REST API.
+Complete documentation of Daktela API is available on following link: https://customer.daktela.com/apihelp/v6/global/general-information.
+
+## Setup
+
+The connector requires following prerequisites:
+
+* Instance URL (e.g. my.daktela.com).
+* Access token to access protected Daktela API endpoints.
+
+The only dependency of this library is HTTP client `Axios` (https://axios-http.com/).
+
+## Usage
+
+`DaktelaConnector` is a class that allows you to send CRUD requests on your Daktela server.
+Beside `instance` and `accessToken` you can pass `options` object with following parameters:
+
+* `cookieAuth` (boolean) - whether authorize requests via Cookie header or via query parameters. Default value is authorization via cookies.
+* `userAgent` (string) - HTTP User-Agent header.
+* `timeout` {number} - requests' timeout. Default value is `0` (no timeout).
+
+Once `DaktelaConnector` is initalized you can call HTTP GET, POST, PUT and DELETE requests via provided methods. 
+
+Response is an instance of `DaktelaResponse` which contains:
+
+* `status` (number) - status code of a HTTP request.
+* `data` (object or array) - returned data.
+* `total` (number) - total number of rows (in case of GET reponse contains multiple objects). 
+
+An request may throw `DaktelaError`. The class contains originally thrown error as well as `status` code and `apiError` returned by Daktela API.
+
+In `options` argument of HTTP GET method `get` you can specify optional arguments of the Daktela API like `fields`, `sort`, `pagination`, `filters` or `filter`.
+To build `sort`, `pagination` or `filters` use functions `Sort`, `Pagination`, `FilterSimple` predefined by the library.
+
+Other way is to directly pass Axios's `params` argument which overrides Daktela API parameters and is available in all methods (`get`, `post`, `put`, `delete`).
+
+## Example
+
+```js
+require('dotenv').config();
+const Daktela = require('daktela-connector');
+let daktela = new Daktela.DaktelaConnector(process.env.INSTANCE, process.env.ACCESS_TOKEN);
+
+//...
+
+// login request
+try {
+    const r = await daktela.post('login', {
+        username: 'user_1',
+        password: 'password_1',
+    });
+    console.log(r.data);
+} catch (e) {
+    console.log(e);
+}
+
+// filter tickets
+try {
+    const r = await daktela.get('tickets', {
+        pagination: Daktela.Pagination(3),
+        fields: ['name', 'title', 'category', 'user'],
+        sort: Daktela.Sort('edited', Daktela.SortDescending),
+        filters: [Daktela.FilterSimple('stage', 'eq', 'OPEN')]
+    });
+    console.log(r.data);
+} catch (e) {
+  console.log(e);
+}
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@daktela/daktela-connector",
+  "version": "1.0.0",
+  "description": "Daktela's JavaScript SDK",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Daktela/daktela-v6-js-connector.git"
+  },
+  "author": "Martin Sach",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/Daktela/daktela-v6-js-connector/issues"
+  },
+  "homepage": "https://github.com/Daktela/daktela-v6-js-connector#readme",
+  "dependencies": {
+    "axios": "^1.6.3"
+  },
+  "devDependencies": {
+    "dotenv": "^16.3.1",
+    "jest": "^29.7.0"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/src/index.js

@@ -0,0 +1,316 @@
+const axios = require('axios');
+
+/**
+ * Default number of rows to be returned.
+ */
+const PaginationTake = 100;
+
+/**
+ * Default number of rows to be skipped.
+ */
+const PaginationSkip = 0;
+
+/**
+ * Asceding direction of sorting.
+ */
+const SortAscending = 'asc';
+
+/**
+ * Descending direcion of sorting.
+ */
+const SortDescending = 'desc';
+
+/**
+ * Logical AND of Daktela filter.
+ */
+const FilterLogicAnd = 'and';
+
+/**
+ * Logical OR of Daktela filter.
+ */
+const FilterLogicOr = 'or';
+
+/**
+ * Build Daktela's pagination object.
+ * 
+ * @param {number} [take=PaginationTake]   Number of rows to be returned.
+ * @param {number} [skip=PaginationSkip]   Number of rows to be skipped.
+ * @return {Object}
+ */
+const Pagination = function (take = PaginationTake, skip = PaginationSkip) {
+    return {
+        take: take,
+        skip: skip
+    };
+};
+
+/**
+ * Builds Daktela's Sort object.
+ * 
+ * @param {string} field    Name of field to sort rows by.
+ * @param {string} dir      Direction of sorting (allowed values are 'asc' or 'desc'). Defined constants are @see SortAscending and @see SortDescending.
+ * @return {Object}
+ */
+const Sort = function (field, dir) {
+    return {
+        field: field,
+        dir: dir
+    };
+};
+
+/**
+ * Builds Daktela's simple filter.
+ *
+ * @param {string} field    Name of the field. 
+ * @param {string} operator Operator of the filter.
+ * @param {string} value    Value use for filtering.
+ * @return {Object}
+ */
+const FilterSimple = function (field, operator, value) {
+    return {
+        field: field,
+        operator: operator,
+        value: value
+    };
+};
+
+/**
+ * A class representing Daktela response.
+ * 
+ * @property {number}           status Status code of the request.
+ * @property {Object|Array}     data Returned data (can be object or array).
+ * @property {number|undefined} total Total number of rows.
+ */
+class DaktelaResponse {
+    /**
+     * @param {axios.AxiosResponse} response 
+     */
+    constructor(response) {
+        var body = response.data;
+        this.status = response.status;
+        const result = body.result ?? null;
+        this.data = result;
+        if (result !== null && Array.isArray(result.data)) {
+            this.data = result.data;
+        }
+        if (result !== null && result.total !== null) {
+            this.total = result.total;
+        }
+    }
+};
+
+/**
+ * A class representing Daktela error.
+ * 
+ * @property {number|undefined} status Status code of the request.
+ * @property {Object|undefined} apiError Error returned by Daktela API.
+ */
+class DaktelaError extends Error {
+    /**
+     * @param {Error} prevError Original error thrown during request.
+     */
+    constructor(prevError) {
+        super(prevError.message);
+        this.name = 'DaktelaError';
+        this.prevError = prevError;
+        this.status = null;
+        this.apiError = null;
+        if (prevError.response) {
+            this.status = prevError.response.status;
+            if (prevError.response.data.error) {
+                this.apiError = prevError.response.data.error;
+            }
+        }
+    }
+}
+
+/**
+ * Daktela connector. Use its HTTP methods (get, post, put, delete) to send requests to Daktela API.
+ *
+ * @param {string}  url                 Target Daktela instance (e. g. my.daktela.com).
+ * @param {string}  [accessToken=null]  Access token.
+ * @param {Object}  [options={}]        Options of the connector. See below.
+ * @param {boolean} options.cookieAuth  Authorize requests via Cookie header. Default value is true. Otherwise access token will be passed as query parameter.
+ * @param {string}  options.userAgent   User agent header.
+ * @param {number}  options.timeout     Specifies the number of milliseconds before the request times out. Default is 0 (no timout)
+ */
+const DaktelaConnector = function DaktelaConnector(url, accessToken = null, options = {}) {
+    if (!url.startsWith('https://')) {
+        url = 'https://' + url;
+    }
+    if (!url.endsWith('/')) {
+        url += '/';
+    }
+    this.cookieAuth = options.cookieAuth ?? true;
+    var headers = {};
+    if (this.cookieAuth && accessToken != null) {
+        headers['Cookie'] = 'c_user=' + accessToken;
+    }
+    if (options.userAgent !== null) {
+        headers['User-Agent'] = options.userAgent;
+    }
+    this.api = axios.create({
+        baseURL: url + 'api/v6/',
+        headers: headers,
+        timeout: Number.isInteger(options.timeout) && options.timeout >= 0 ? options.timeout : 0
+    });
+    this.accessToken = accessToken;
+};
+
+/**
+ * Checks whether given item is an object or not.
+ * 
+ * @param {any} item 
+ * @return {boolean}
+ */
+function isObject(item) {
+    return (typeof item === 'object' && !Array.isArray(item) && item !== null);
+}
+
+/**
+ * Builds Axios' `config` parameter.
+ * 
+ * @param {Object|null} options Options of the request.
+ * @return {Object}
+ */
+DaktelaConnector.prototype.buildRequestParams = function (options) {
+    let params = {};
+    if (isObject(options)) {
+        if (isObject(options.params)) {
+            params = options.params;
+        } else {
+            params = {};
+            if (Array.isArray(options.fields)) {
+                params.fields = options.fields;
+            }
+            if (Array.isArray(options.sort) || isObject(options.sort)) {
+                params.sort = options.sort;
+            }
+            if (isObject(options.pagination)) {
+                params.take = options.pagination.take ?? PaginationTake;
+                params.skip = options.pagination.skip ?? PaginationSkip;
+            }
+            if (Array.isArray(options.filters)) {
+                params.filter = {
+                    logic: FilterLogicAnd,
+                    filters: options.filters
+                };
+            }
+            if (isObject(options.filter)) {
+                if (isObject(params.filter)) {
+                    params.filter.filters.push(options.filter);
+                } else {
+                    params.filter = options.filter;
+                }
+            }
+        }
+    }
+    if (!this.cookieAuth && this.accessToken !== null) {
+        params.accessToken = this.accessToken;
+    }
+    return {
+        params: params
+    };
+};
+
+/**
+ * 
+ * @param {Object|null} options 
+ * @return 
+ */
+DaktelaConnector.prototype.enrichWithAccessToken = function (params) {
+    return this.buildRequestParams({
+        params: params
+    });
+};
+
+/**
+ * HTTP GET method.
+ *
+ * @param {string}                  endpoint            Target endpoint (e.g. 'activities' or 'activities/activity_xxx').
+ * @param {Object}                  [options=null]      Options of the request. See below.
+ * @param {Object}                  options.params      Params of the Axios library. Useful to directly pass query params to the request. This value overrides all other options (i.e.: pagination, filter, sort).
+ * @param {Array<string>}           options.fields      List of fields to be returned in response.
+ * @param {Array<Object>|Object}    options.sort        List of Daktela's sorts. Use @function Sort to build single sort.
+ * @param {Object}                  options.pagination  Pagination of the request. Use @function Pagination to build Daktela pagignation.
+ * @param {Array<Object>}           options.filters     List of simple filters (i.e. filters merged by AND condition). Use @see SimpleFilter to build simple Daktela filter. You can combine list of simple filters and custom filter object in one request.
+ * @param {Object}                  options.filter      Object containing custom filter. You can combine list of simple filters and custom filter object in one request.
+ * @throws {DaktelaError}
+ * @return {Promise<DaktelaResponse>}
+ */
+DaktelaConnector.prototype.get = async function (endpoint, options = null) {
+    try {
+        const response = await this.api.get(endpoint, this.buildRequestParams(options));
+        return new DaktelaResponse(response);
+    } catch (error) {
+        throw new DaktelaError(error);
+    }
+};
+
+/**
+ * HTTP POST method.
+ * 
+ * @param {string} endpoint         Target endpoint (e.g. 'activities' or 'tickets').
+ * @param {Object} payload          Data payload of the request.
+ * @param {Object} [params=null]    Params of the Axios library. Useful to directly pass query params to the request.
+ * @throws {DaktelaError}
+ * @return {Promise<DaktelaResponse>}
+ */
+DaktelaConnector.prototype.post = async function (endpoint, payload, params = null) {
+    try {
+        const response = await this.api.post(endpoint, payload, this.enrichWithAccessToken(params));
+        return new DaktelaResponse(response);
+    } catch (error) {
+        throw new DaktelaError(error);
+    }
+};
+
+/**
+ * HTTP PUT method.
+ * 
+ * @param {string} endpoint         Target endpoint (e.g. 'activities/activity_xxx' or 'tickets/123').
+ * @param {Object} payload          Data payload of the request.
+ * @param {Object} [params=null]    Params of the Axios library. Useful to directly pass query params to the request.
+ * @throws {DaktelaError}
+ * @return {Promise<DaktelaResponse>}
+ */
+DaktelaConnector.prototype.put = async function (endpoint, payload, params = null) {
+    try {
+        const response = await this.api.put(endpoint, payload, this.enrichWithAccessToken(params));
+        return new DaktelaResponse(response);
+    } catch (error) {
+        throw new DaktelaError(error);
+    }
+};
+
+/**
+ * HTTP DELETE method.
+ * 
+ * @param {string} endpoint         Target endpoint (e.g. 'activities/activity_xxx' or 'tickets/123').
+ * @param {Object} [params=null]    Params of the Axios library. Useful to directly pass query params to the request.
+ * @throws {DaktelaError}
+ * @return {Promise<DaktelaResponse>}
+ */
+DaktelaConnector.prototype.delete = async function (endpoint, params = null) {
+    try {
+        const response = await this.api.delete(endpoint, this.enrichWithAccessToken(params));
+        return new DaktelaResponse(response);
+    } catch (error) {
+        throw new DaktelaError(error);
+    }
+};
+
+module.exports = {
+    DaktelaConnector,
+    DaktelaResponse,
+    DaktelaError,
+    PaginationTake,
+    PaginationSkip,
+    Pagination,
+    SortAscending,
+    SortDescending,
+    Sort,
+    FilterLogicAnd,
+    FilterLogicOr,
+    FilterSimple
+};

package/test/test.js

@@ -0,0 +1,217 @@
+require('dotenv').config();
+const Daktela = require('daktela-connector');
+const daktela = new Daktela.DaktelaConnector(process.env.INSTANCE, process.env.ACCESS_TOKEN);
+const currentDateTime = Date.now();
+
+test('Pagination test', () => {
+    let pagination = Daktela.Pagination();
+    expect(pagination.take).toBe(Daktela.PaginationTake);
+    expect(pagination.skip).toBe(Daktela.PaginationSkip);
+
+    let take = 321;
+    pagination = Daktela.Pagination(take);
+    expect(pagination.take).toBe(take);
+    expect(pagination.skip).toBe(Daktela.PaginationSkip);
+
+    take = 567;
+    skip = 250;
+    pagination = Daktela.Pagination(take, skip);
+
+    expect(pagination.take).toBe(take);
+    expect(pagination.skip).toBe(skip);
+});
+
+test('Sort test', () => {
+    const field = 'field_xxx';
+    let sort = Daktela.Sort(field, Daktela.SortAscending);
+
+    expect(sort.field).toBe(field);
+    expect(sort.dir).toBe(Daktela.SortAscending);
+});
+
+test('Filter test', () => {
+    const field = 'field_yyy';
+    const operator = 'neq';
+    const value = 'test_zzz';
+    let filter = Daktela.FilterSimple(field, operator, value);
+
+    expect(filter.field).toBe(field);
+    expect(filter.operator).toBe(operator);
+    expect(filter.value).toBe(value);
+});
+
+test('Build params test', () => {
+    const fields = ['a', 'b'];
+    const take = 50;
+    let options = {
+        params: {
+            xxx: 'yyy'
+        },
+        fields: fields,
+        sort: [
+            Daktela.Sort('edited', Daktela.SortDescending),
+            Daktela.Sort('title', Daktela.SortAscending)
+        ],
+        pagination: Daktela.Pagination(take)
+    };
+    let params = daktela.buildRequestParams(options);
+    expect(params.params.xxx).toBe('yyy');
+    expect(params.params.fields).toBe(undefined);
+    expect(params.params.accessToken).toBe(undefined);
+
+    options.params = undefined;
+    params = daktela.buildRequestParams(options);
+    expect(params.params.fields).toBe(fields);
+    expect(params.params.sort.length).toBe(2);
+    expect(params.params.sort[0].field).toBe('edited');
+    expect(params.params.sort[0].dir).toBe('desc');
+    expect(params.params.sort[1].field).toBe('title');
+    expect(params.params.sort[1].dir).toBe('asc');
+    expect(params.params.take).toBe(take);
+    expect(params.params.skip).toBe(Daktela.PaginationSkip);
+
+    const filters = [
+        Daktela.FilterSimple('firstname', 'eq', 'John'),
+        Daktela.FilterSimple('lastname', 'neq', 'Doe')
+    ];
+    options = {
+        filters: filters
+    };
+    params = daktela.buildRequestParams(options);
+    expect(params.params.filter.logic).toBe(Daktela.FilterLogicAnd);
+    expect(params.params.filter.filters.length).toBe(2);
+    expect(params.params.filter.filters[0].field).toBe('firstname');
+    expect(params.params.filter.filters[0].operator).toBe('eq');
+    expect(params.params.filter.filters[0].value).toBe('John');
+    expect(params.params.filter.filters[1].field).toBe('lastname');
+    expect(params.params.filter.filters[1].operator).toBe('neq');
+    expect(params.params.filter.filters[1].value).toBe('Doe');
+
+    const filter = {
+        logic: Daktela.FilterLogicOr,
+        filters: [
+            Daktela.FilterSimple('edited', 'lte', '2023-12-31')
+        ]
+    };
+    options = {
+        filter: filter
+    };
+    params = daktela.buildRequestParams(options);
+    expect(params.params.filter.logic).toBe(Daktela.FilterLogicOr);
+    expect(params.params.filter.filters.length).toBe(1);
+    expect(params.params.filter.filters[0].field).toBe('edited');
+    expect(params.params.filter.filters[0].operator).toBe('lte');
+    expect(params.params.filter.filters[0].value).toBe('2023-12-31');
+
+    options = {
+        filters: filters,
+        filter: filter
+    };
+    params = daktela.buildRequestParams(options);
+    expect(params.params.filter.logic).toBe(Daktela.FilterLogicAnd);
+    expect(params.params.filter.filters.length).toBe(3);
+    expect(params.params.filter.filters[0].field).toBe('firstname');
+    expect(params.params.filter.filters[0].operator).toBe('eq');
+    expect(params.params.filter.filters[0].value).toBe('John');
+    expect(params.params.filter.filters[1].field).toBe('lastname');
+    expect(params.params.filter.filters[1].operator).toBe('neq');
+    expect(params.params.filter.filters[1].value).toBe('Doe');
+    expect(params.params.filter.filters[2].logic).toBe(Daktela.FilterLogicOr);
+    expect(params.params.filter.filters[2].filters.length).toBe(1);
+    expect(params.params.filter.filters[2].filters[0].field).toBe('edited');
+    expect(params.params.filter.filters[2].filters[0].operator).toBe('lte');
+    expect(params.params.filter.filters[2].filters[0].value).toBe('2023-12-31');
+
+    const daktela2 = new Daktela.DaktelaConnector(process.env.INSTANCE, process.env.ACCESS_TOKEN, {
+        cookieAuth: false
+    });
+    params = daktela2.buildRequestParams({sort: Daktela.Sort('created', Daktela.SortAscending)});
+    expect(params.params.accessToken).toBe(process.env.ACCESS_TOKEN);
+    expect(params.params.sort.field).toBe('created');
+    expect(params.params.sort.dir).toBe(Daktela.SortAscending);
+});
+
+test('Initial request test', async () => {
+    const daktela2 = new Daktela.DaktelaConnector(process.env.INSTANCE);
+    const r = await daktela2.get('whoim');
+    expect(r.status).toBe(200);
+    expect(r.total).toBe(undefined);
+    expect(r.data.version).not.toBe(null);
+    expect(r.data.user).not.toBe(undefined);
+    expect(r.data.user).toBe(null);
+});
+
+test('Access token test', async () => {
+    const r = await daktela.get('whoim');
+    expect(r.status).toBe(200);
+    expect(r.data.user).not.toBe(null);
+    expect(r.data.user._sys.accessToken).toBe(process.env.ACCESS_TOKEN);
+});
+
+test('Exception test', async () => {
+    expect(daktela.get('xxx')).rejects.toThrow(Daktela.DaktelaError);
+    expect(daktela.get('tickets/xxx')).rejects.toThrow(Daktela.DaktelaError);
+    expect(daktela.post('login', {
+        'username': 'xyz',
+        'password': '-123'
+    })).rejects.toThrow(Daktela.DaktelaError);
+});
+
+describe('CRUD test', () => {
+    const name = 'name_' + currentDateTime;
+    const title = 'title_' + currentDateTime;
+
+    test('POST request test', async () => {
+        const r = await daktela.post('statuses', {
+            name: name,
+            title: title
+        });
+        expect(r.status).toBe(201);
+        expect(r.data.name).toBe(name);
+        expect(r.data.title).toBe(title);
+    });
+
+    test('GET request test', async () => {
+        const r = await daktela.get('statuses/' + name);
+        expect(r.status).toBe(200);
+        expect(r.data.title).toBe(title);
+    });
+
+    test('GET all request test', async () => {
+        const r = await daktela.get('statuses', {
+            filters: [Daktela.FilterSimple('name', 'eq', name)]
+        });
+        expect(r.status).toBe(200);
+        expect(r.total).toBe(1);
+        expect(r.data[0].name).toBe(name);
+        expect(r.data[0].title).toBe(title);
+    });
+
+    test('PUT request test', async () => {
+        const description = 'test XXX';
+        const r = await daktela.put('statuses/' + name, {
+            description: description
+        });
+        expect(r.status).toBe(200);
+        expect(r.data.name).toBe(name);
+        expect(r.data.description).toBe(description);
+    });
+
+    test('DELETE request test', async () => {
+        const r = await daktela.delete('statuses/' + name);
+        expect(r.status).toBe(204);
+        expect(r.data).toBe(null);
+    });
+});
+
+test('Filter tickets from README', async () => {
+    const take = 3;
+    const r = await daktela.get('tickets', {
+        pagination: Daktela.Pagination(take),
+        fields: ['name', 'title', 'category', 'user'],
+        sort: Daktela.Sort('edited', Daktela.SortDescending),
+        filters: [Daktela.FilterSimple('stage', 'eq', 'OPEN')]
+    });
+    expect(r.status).toBe(200);
+    expect(r.data.length).toBe(take);
+});