@hailer/app-sdk 1.0.0

package/README.md

@@ -0,0 +1,12 @@
+# Hailer apps SDK
+
+## Building
+```bash
+npm run build
+```
+
+## Documentation
+Create a docs folder with typedoc
+```bash
+npm run docs
+```

package/lib/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_API_VERSION = 1;
+export declare const DEFAULT_ALLOWED_URLS: string[];
+export declare const DEFAULT_BACKEND_URL = "https://api.hailer.com";
+/** Map of which backend to use depending on which frontend is hosting the app frame, be sure to fall back to production backend if no match */
+export declare const publicBackendMap: {
+    [host: string]: string;
+};

package/lib/constants.js

@@ -0,0 +1,12 @@
+// Changing this will be a breaking change
+export const DEFAULT_API_VERSION = 1;
+export const DEFAULT_ALLOWED_URLS = ['https://app.hailer.com', 'https://next.hailer.com', 'https://testapp.hailer.biz', 'https://app.hailer.biz'];
+export const DEFAULT_BACKEND_URL = 'https://api.hailer.com';
+/** Map of which backend to use depending on which frontend is hosting the app frame, be sure to fall back to production backend if no match */
+export const publicBackendMap = {
+    'https://app.hailer.com': DEFAULT_BACKEND_URL,
+    'https://next.hailer.com': DEFAULT_BACKEND_URL,
+    'https://app.hailer.biz': 'https://api.hailer.biz',
+    'https://testapp.hailer.biz': 'https://testapi.hailer.biz',
+    'https://localhost:9443': 'http://localhost:1337',
+};

package/lib/hailer-api.d.ts

@@ -0,0 +1,74 @@
+import { User } from './modules/user';
+import { Activity } from './modules/activity';
+import { Network } from './modules/network';
+import { ApiVersion, HailerApiInfo, HailerSettings, HailerSignal } from './types';
+import { Ui } from './modules/ui';
+import { Insight } from './modules/insight';
+import { Process } from './modules/process';
+import { HailerApiPublic } from './modules/public';
+import { Workflow } from './modules/workflow';
+export interface Options {
+    /** When connected is called the host is ready to receive calls */
+    connected?: () => void;
+    /** Callback when app is determined to be outside of Hailer, as a standalone app */
+    outside?: (config?: any) => void;
+    /** Callback on errors, defaults to printing errors in console */
+    error?: (error: Error) => void;
+    /** Callback called on app init and when permissions have changed */
+    permissions?: () => void;
+    /** Callback called on app init and when settings have changed */
+    settings?: (data: HailerSettings) => void;
+    /** Callback called on app init and when config has changed */
+    config?: (config: any) => void;
+    /** Will be called each time a subscribed signal is emitted from Hailer frontend. To subscribe to signals, add them to options.subscribedSignals[] */
+    signals?: (signal: HailerSignal) => void;
+    /** Urls the sdk is allowed to connect to. Defaults to all Hailer instances*/
+    allowedUrls?: string[];
+    /** The signals we want the Hailer frontend to pass to the app. If an empty array is provided, all signals will be passed. */
+    subscribedSignals?: string[];
+    /** Api version to be used in the app by default */
+    apiVersion?: ApiVersion;
+    /** Public backend Api url. Defaults to https://api.hailer.com */
+    publicBackendUrl?: string;
+}
+export declare class HailerApi {
+    options: Options;
+    user: User;
+    activity: Activity;
+    insight: Insight;
+    network: Network;
+    process: Process;
+    workflow: Workflow;
+    /** All public endpoints, which can be accessed while not logged in to Hailer. */
+    public: HailerApiPublic;
+    /** User interface commands */
+    ui: Ui;
+    /** Url of the Hailer instance hosting the API */
+    private hostUrl?;
+    private appId?;
+    private client;
+    private apiVersion;
+    private settings?;
+    private config?;
+    private subscribedSignals?;
+    private timer?;
+    /**
+     * Hailer API state
+     *
+     * ```
+     * true // outside hailer
+     * false // logged into hailer
+     * null // state not yet detected
+     * ```
+     */
+    private outside;
+    /**
+     * Create a Hailer API client for inteacting with Hailer. **NOTE** This only works when inside Hailer.
+     *
+     * This should be run after window is initialized for example in ***onMount*** in Svelte or in ***useEffect*** in React
+     */
+    constructor(options?: Options);
+    private createEventListener;
+    info(): HailerApiInfo;
+    request(op: string, args: any[]): Promise<any>;
+}

package/lib/hailer-api.js

@@ -0,0 +1,163 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Client } from '@wishcore/wish-rpc';
+import { User } from './modules/user';
+import { Activity } from './modules/activity';
+import { Network } from './modules/network';
+import { Ui } from './modules/ui';
+import { Insight } from './modules/insight';
+import { Process } from './modules/process';
+import { DEFAULT_ALLOWED_URLS, DEFAULT_API_VERSION, DEFAULT_BACKEND_URL, publicBackendMap } from './constants';
+import { HailerApiPublic } from './modules/public';
+import { Workflow } from './modules/workflow';
+export class HailerApi {
+    /**
+     * Create a Hailer API client for inteacting with Hailer. **NOTE** This only works when inside Hailer.
+     *
+     * This should be run after window is initialized for example in ***onMount*** in Svelte or in ***useEffect*** in React
+     */
+    constructor(options = {}) {
+        var _a, _b;
+        this.options = options;
+        /**
+         * Hailer API state
+         *
+         * ```
+         * true // outside hailer
+         * false // logged into hailer
+         * null // state not yet detected
+         * ```
+         */
+        this.outside = null;
+        const allowedUrls = (_a = options.allowedUrls) !== null && _a !== void 0 ? _a : DEFAULT_ALLOWED_URLS;
+        this.apiVersion = (_b = options.apiVersion) !== null && _b !== void 0 ? _b : DEFAULT_API_VERSION;
+        this.subscribedSignals = options.subscribedSignals;
+        this.client = new Client(msg => {
+            if (this.hostUrl) {
+                parent.postMessage(JSON.stringify(msg), this.hostUrl);
+            }
+        });
+        this.user = new User(this.client);
+        this.activity = new Activity(this.client);
+        this.insight = new Insight(this.client);
+        this.network = new Network(this.client);
+        this.process = new Process(this.client);
+        this.workflow = new Workflow(this.client);
+        this.public = new HailerApiPublic(this.options);
+        this.ui = new Ui(this.client);
+        const registerMessage = JSON.stringify({ op: 'register', args: [] });
+        // If we are not in Iframe set location to outside, else wait 100ms for response to register to check if we are in Hailer
+        if (window.location === window.parent.location) {
+            // Pick a backend to use for public requests, unless it is set
+            if (!this.options.publicBackendUrl) {
+                this.options.publicBackendUrl = DEFAULT_BACKEND_URL;
+            }
+            this.public.app.config().then(config => {
+                // CSM app assumes we are inside hailer when config is called... breaks the thing...
+                // this.options.config?.(config);
+                var _a, _b;
+                this.outside = true;
+                (_b = (_a = this.options).outside) === null || _b === void 0 ? void 0 : _b.call(_a, config);
+            }).catch(error => {
+                var _a, _b;
+                (_b = (_a = this.options).error) === null || _b === void 0 ? void 0 : _b.call(_a, error);
+                console.error('Failed to get app configuration in Public App.', error);
+            });
+        }
+        else {
+            // if in a frame, try register to Hailer by sending register to all allowed urls
+            allowedUrls.forEach(url => parent.postMessage(registerMessage, url));
+            this.timer = setTimeout(() => {
+                var _a, _b;
+                this.outside = true;
+                (_b = (_a = this.options).outside) === null || _b === void 0 ? void 0 : _b.call(_a);
+            }, 100);
+        }
+        this.createEventListener();
+    }
+    createEventListener() {
+        window.addEventListener('message', (event) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const data = event.data;
+            try {
+                const msg = JSON.parse(data);
+                if (msg.op === 'register') {
+                    if (this.appId) {
+                        console.error('App Id is already set...! Are you using hot-reload?');
+                        return;
+                    }
+                    clearTimeout(this.timer);
+                    this.appId = msg.data.appId;
+                    // Set host url now that we have a response
+                    this.hostUrl = event.origin;
+                    // Pick a backend to use for public requests, unless it is set
+                    if (!this.options.publicBackendUrl) {
+                        this.options.publicBackendUrl = publicBackendMap[this.hostUrl] || DEFAULT_BACKEND_URL;
+                    }
+                    // Register listeners for config and settings
+                    this.client.request('v1.ui.settings', [], (error, data, end) => {
+                        var _a, _b;
+                        if (error) {
+                            console.log('ui.settings error:', error, data);
+                            return;
+                        }
+                        (_b = (_a = this.options).settings) === null || _b === void 0 ? void 0 : _b.call(_a, data);
+                    });
+                    this.client.request('v1.config', [], (error, data, end) => {
+                        var _a, _b;
+                        if (error) {
+                            console.log('config error:', error, data);
+                            return;
+                        }
+                        (_b = (_a = this.options).config) === null || _b === void 0 ? void 0 : _b.call(_a, data);
+                    });
+                    // Register subscribed signals
+                    if (this.subscribedSignals) {
+                        this.client.request('v1.signals', [this.subscribedSignals], (error, data, end) => {
+                            var _a, _b;
+                            if (error) {
+                                console.log('signals error:', error, data);
+                                return;
+                            }
+                            if (data) {
+                                (_b = (_a = this.options).signals) === null || _b === void 0 ? void 0 : _b.call(_a, data);
+                            }
+                        });
+                    }
+                    this.outside = false;
+                    // Call connected callback
+                    (_b = (_a = this.options).connected) === null || _b === void 0 ? void 0 : _b.call(_a);
+                    return;
+                }
+                // bail out unless appId is set, as the app is not properly registered
+                if (!this.appId) {
+                    return;
+                }
+                this.client.messageReceived(msg);
+            }
+            catch (error) {
+                console.error('Error handling message:', error);
+            }
+        }));
+    }
+    info() {
+        return {
+            hostUrl: this.hostUrl,
+            config: this.config,
+            outside: this.outside,
+        };
+    }
+    // TODO: This is here for development and debugging, might be removed later
+    request(op, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.client.requestAsync(op, args);
+        });
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { HailerApi } from './hailer-api';
+export * from './types';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { HailerApi } from './hailer-api';
+export * from './types';

package/lib/modules/activity/kanban.d.ts

@@ -0,0 +1,38 @@
+import { Client } from '@wishcore/wish-rpc';
+import { ActivityKanbanListOptions, KanbanListResponse, KanbanLoadResponse } from '../../types';
+export declare class Kanban {
+    private client;
+    constructor(client: Client);
+    /**
+     * Lists all activities in a kanban grouped by phases
+     *
+     * @param processId the id of the process the kanban relates to
+     * @param options object containing apiVersion option and requestOptions to be passed to the backend endpoint
+     *
+     * @returns activities in kanban list format
+     *
+     * @throws {HailerError} if request fails
+     */
+    list(processId: string, options?: ActivityKanbanListOptions): Promise<KanbanListResponse>;
+    /**
+     * Loads a single activity in kanban format
+     *
+     * @param activityId activityId of the wanted activity
+     * @param options object containing apiVersion option
+     *
+     * @returns activity in kanban format
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    load(activityId: string): Promise<KanbanLoadResponse>;
+    /**
+     * Updates priority of activities in kanban
+     *
+     * @param activityId activityId of the wanted activity
+     * @param priority new priority for the activity
+     * @param options object containing apiVersion option
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    updatePriority(activityId: string, priority: number): Promise<void>;
+}

package/lib/modules/activity/kanban.js

@@ -0,0 +1,77 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { HailerError } from '../../types';
+export class Kanban {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Lists all activities in a kanban grouped by phases
+     *
+     * @param processId the id of the process the kanban relates to
+     * @param options object containing apiVersion option and requestOptions to be passed to the backend endpoint
+     *
+     * @returns activities in kanban list format
+     *
+     * @throws {HailerError} if request fails
+     */
+    list(processId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.kanban.list', [processId, ...options ? [options] : []]);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Loads a single activity in kanban format
+     *
+     * @param activityId activityId of the wanted activity
+     * @param options object containing apiVersion option
+     *
+     * @returns activity in kanban format
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    load(activityId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.kanban.load', [activityId]);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Updates priority of activities in kanban
+     *
+     * @param activityId activityId of the wanted activity
+     * @param priority new priority for the activity
+     * @param options object containing apiVersion option
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    updatePriority(activityId, priority) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.kanban.updatePriority', [{ activityId, priority }]);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+}

package/lib/modules/activity.d.ts

@@ -0,0 +1,83 @@
+import { Client } from '@wishcore/wish-rpc';
+import { ActivityCreateOptions, ActivityListOptions, HailerActivity } from '../types';
+import { Kanban } from './activity/kanban';
+export declare class Activity {
+    private client;
+    kanban: Kanban;
+    constructor(client: Client);
+    /**
+     * Lists all activities from the specified process and phase
+     *
+     * @param processId process from current network
+     * @param phaseId phase in the process specified in processId
+     * @param options options with apiVersion and requestOptions, default values can be found in api.hailer.com/docs v3.activity.list
+     *
+     * @returns List of Hailer activities from process and phase filtered with supplied options
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    list(processId: string, phaseId: string, options?: ActivityListOptions): Promise<HailerActivity[]>;
+    /**
+     * Gets single activity
+     *
+     * @param activityId activity Id of the process specified in processId
+     * @param processId Process where the activityId is
+     * @param phaseId Phase where the activityId is in process specified by processId
+     * @param options options containing apiVersion
+     *
+     * @returns Hailer activity information or undefined if no activity is found
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    get(activityId: string): Promise<HailerActivity | undefined>;
+    /**
+     * Creates activities
+     *
+     * @param processId The process where the activity is created
+     * @param activities new activities as objects
+     * @param activities.name name of the activity
+     * @param activities.fields fields of the activity
+     * @param options optional options with apiVersion and requestOptions to be passed to the backend endpoint
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    create(processId: string, activities: {
+        name: string;
+        fields: {
+            [id: string]: string | number;
+        };
+    }[], options?: ActivityCreateOptions): Promise<HailerActivity[]>;
+    /**
+     * Updates activites
+     *
+     * Each activity has the following parameters
+     * @param activities updated activity objects of an activity to edit
+     * @param activities.name New name of the activity
+     * @param activities.fields change values of fields, null removes current value
+     * @param activities.phaseId New phase of the activity
+     * @param options options containing apiVersion
+     *
+     * @returns The number of updated activities
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    update(activities: {
+        _id: string;
+        name?: string;
+        fields?: {
+            [id: string]: string | number | null;
+        };
+        phaseId?: string;
+    }[]): Promise<number>;
+    /**
+     * Removes activities
+     *
+     * @param activities Ids of activities to be removed
+     * @param options options containing apiVersion
+     *
+     * @returns The number of removed activities
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    remove(activities: string[]): Promise<number>;
+}

package/lib/modules/activity.js

@@ -0,0 +1,130 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { HailerError } from '../types';
+import { Kanban } from './activity/kanban';
+export class Activity {
+    constructor(client) {
+        this.client = client;
+        this.kanban = new Kanban(client);
+    }
+    /**
+     * Lists all activities from the specified process and phase
+     *
+     * @param processId process from current network
+     * @param phaseId phase in the process specified in processId
+     * @param options options with apiVersion and requestOptions, default values can be found in api.hailer.com/docs v3.activity.list
+     *
+     * @returns List of Hailer activities from process and phase filtered with supplied options
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    list(processId, phaseId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.list', [processId, phaseId, options]);
+                return res.activities;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Gets single activity
+     *
+     * @param activityId activity Id of the process specified in processId
+     * @param processId Process where the activityId is
+     * @param phaseId Phase where the activityId is in process specified by processId
+     * @param options options containing apiVersion
+     *
+     * @returns Hailer activity information or undefined if no activity is found
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    get(activityId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Uses the same endpoint as getAll but only returns the activity in question
+                return yield this.client.requestAsync('v1.activity.get', [activityId]);
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Creates activities
+     *
+     * @param processId The process where the activity is created
+     * @param activities new activities as objects
+     * @param activities.name name of the activity
+     * @param activities.fields fields of the activity
+     * @param options optional options with apiVersion and requestOptions to be passed to the backend endpoint
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    create(processId, activities, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.create', [processId, activities, ...options ? [options] : []]);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Updates activites
+     *
+     * Each activity has the following parameters
+     * @param activities updated activity objects of an activity to edit
+     * @param activities.name New name of the activity
+     * @param activities.fields change values of fields, null removes current value
+     * @param activities.phaseId New phase of the activity
+     * @param options options containing apiVersion
+     *
+     * @returns The number of updated activities
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    update(activities) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.update', activities);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+    /**
+     * Removes activities
+     *
+     * @param activities Ids of activities to be removed
+     * @param options options containing apiVersion
+     *
+     * @returns The number of removed activities
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    remove(activities) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const res = yield this.client.requestAsync('v1.activity.remove', activities);
+                return res;
+            }
+            catch (error) {
+                throw new HailerError(error);
+            }
+        });
+    }
+}

package/lib/modules/insight.d.ts

@@ -0,0 +1,27 @@
+import { Client } from '@wishcore/wish-rpc';
+import { InsightData, InsightDoc } from '../types';
+export declare class Insight {
+    private client;
+    constructor(client: Client);
+    /**
+     * Get Insight data
+     *
+     * @param insightId the id of the Insight the data is fetched from
+     * @param options object containing apiVersion option
+     *
+     * @returns data from the Insight
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    data(insightId: string): Promise<InsightData>;
+    /**
+     * Get Insight data
+     *
+     * @param options object containing apiVersion option
+     *
+     * @returns data from the Insight
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    list(): Promise<InsightDoc[]>;
+}