@aloma.io/integration-sdk 3.8.10 → 3.8.12

package/.prettierrc.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  bracketSpacing: false,
+  bracketSameLine: false,
+  singleQuote: true,
+  arrowParens: 'always', //x => x
+  trailingComma: 'es5',
+  printWidth: 120,
+};

package/build/builder/index.d.mts

@@ -1,5 +1,5 @@
-import "dotenv/config";
-import RuntimeContext from "./runtime-context.mjs";
+import 'dotenv/config';
+import RuntimeContext from './runtime-context.mjs';
 export declare const TARGET_DIR: string;
 /**
  * a configuration field
@@ -22,23 +22,19 @@ export type ConfigField = {
     /**
      * the type of the field
      */
-    type: 
-    /**
-     * a multiline text field
-     */
-    "multiline"
+    type: 'multiline'
     /**
      * a single line text field
      */
-     | "line"
+     | 'line'
     /**
      * a number field
      */
-     | "number"
+     | 'number'
     /**
      * a boolean text field
      */
-     | "boolean";
+     | 'boolean';
     /**
      * if true, the field is optional, otherwise a value is required
      */
@@ -127,7 +123,7 @@ declare type OAuth = {
     /**
      * milliseconds to automatically refresh the token, if a refresh_token is available
      *
-    * @default 4 * 60 * 60 * 1000 // 4 hours
+     * @default 4 * 60 * 60 * 1000 // 4 hours
      */
     tokenRefreshPeriod?: number;
     /**

package/build/builder/index.mjs

@@ -1,10 +1,10 @@
-import "dotenv/config";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { notEmpty } from "../internal/util/index.mjs";
-import RuntimeContext from "./runtime-context.mjs";
-const DIR_OFFSET = "/../../../../../";
+import 'dotenv/config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { notEmpty } from '../internal/util/index.mjs';
+import RuntimeContext from './runtime-context.mjs';
+const DIR_OFFSET = '/../../../../../';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const TARGET_DIR = `${__dirname}${DIR_OFFSET}`;
 /**
@@ -12,7 +12,7 @@ export const TARGET_DIR = `${__dirname}${DIR_OFFSET}`;
  */
 export class Builder {
     data = {
-        controller: "./build/.controller.json",
+        controller: './build/.controller.json',
     };
     /**
      * configure properties of the connector
@@ -49,23 +49,22 @@ export class Builder {
         await this.loadDescriptor();
         await this.checkIcon();
         // @ts-ignore
-        const Controller = (await import(TARGET_DIR + "build/controller/index.mjs"))
-            .default;
+        const Controller = (await import(TARGET_DIR + 'build/controller/index.mjs')).default;
         return new RuntimeContext(new Controller(), this.data);
     }
     async checkIcon() {
         const data = this.data;
-        data.icon = TARGET_DIR + "build/logo.png";
+        data.icon = TARGET_DIR + 'build/logo.png';
     }
     async loadDescriptor() {
-        notEmpty(this.data.controller, "controller");
+        notEmpty(this.data.controller, 'controller');
         const content = fs.readFileSync(this.data.controller, {
-            encoding: "utf-8",
+            encoding: 'utf-8',
         });
         const { text, methods, connectorId, version } = JSON.parse(content);
         this.data.types = text;
         this.data.methods = methods;
-        notEmpty((this.data.id = connectorId), "id");
-        notEmpty((this.data.version = version), "version");
+        notEmpty((this.data.id = connectorId), 'id');
+        notEmpty((this.data.version = version), 'version');
     }
 }

package/build/builder/runtime-context.d.mts

@@ -1,4 +1,4 @@
-import { AbstractController } from "../controller/index.mjs";
+import { AbstractController } from '../controller/index.mjs';
 export default class RuntimeContext {
     private controller;
     private data;

package/build/builder/runtime-context.mjs

@@ -1,6 +1,6 @@
-import fs from "node:fs";
-import { AbstractController } from "../controller/index.mjs";
-import { Connector } from "../internal/index.mjs";
+import fs from 'node:fs';
+import { AbstractController } from '../controller/index.mjs';
+import { Connector } from '../internal/index.mjs';
 export default class RuntimeContext {
     controller;
     data;
@@ -11,13 +11,13 @@ export default class RuntimeContext {
     async start() {
         const controller = this.controller;
         if (!(controller instanceof AbstractController)) {
-            throw new Error("the controller needs to extend AbstractController");
+            throw new Error('the controller needs to extend AbstractController');
         }
         const data = this.data;
         let icon;
         try {
             if (data.icon) {
-                icon = fs.readFileSync(data.icon).toString("base64");
+                icon = fs.readFileSync(data.icon).toString('base64');
             }
         }
         catch (e) {
@@ -31,13 +31,7 @@ export default class RuntimeContext {
         });
         const configuration = connector.configure().config(data.config || {});
         const resolvers = {};
-        const methods = [
-            ...data.methods,
-            "__autocomplete",
-            "__endpoint",
-            "__configQuery",
-            "__default",
-        ];
+        const methods = [...data.methods, '__autocomplete', '__endpoint', '__configQuery', '__default'];
         methods.forEach((method) => {
             resolvers[method] = async (args) => {
                 if (!methods.includes(method))
@@ -53,12 +47,13 @@ export default class RuntimeContext {
             configuration.oauth(data.auth?.oauth);
         }
         let healthInterval;
-        configuration.main(async ({ newTask, updateTask, config, oauth, getClient, getBlob, getBlobContent, createBlob, healthCheck, }) => {
+        configuration.main(async ({ newTask, updateTask, config, oauth, getClient, getBlob, getBlobContent, createBlob, healthCheck }) => {
             try {
                 clearInterval(healthInterval);
                 await controller._doStop();
                 await controller._doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob);
-                healthInterval = setInterval(() => healthCheck(controller), 30000);
+                healthInterval = setInterval(() => healthCheck(controller), 30000).unref();
+                await healthCheck(controller);
             }
             catch (e) {
                 console.log(e);
@@ -70,7 +65,7 @@ export default class RuntimeContext {
             await controller._doStop(true);
             process.exit(0);
         };
-        process.on("SIGTERM", term);
-        process.on("SIGINT", term);
+        process.on('SIGTERM', term);
+        process.on('SIGINT', term);
     }
 }

package/build/cli.mjs

@@ -1,23 +1,23 @@
 #!/usr/bin/env node
-import { Command } from "commander";
-import ChildProcess from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import util from "node:util";
-import { TARGET_DIR } from "./builder/index.mjs";
-import { notEmpty } from "./internal/util/index.mjs";
-import JWE from "./internal/util/jwe/index.mjs";
-import parseTypes from "./transform/index.mjs";
+import { Command } from 'commander';
+import ChildProcess from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import util from 'node:util';
+import { TARGET_DIR } from './builder/index.mjs';
+import { notEmpty } from './internal/util/index.mjs';
+import JWE from './internal/util/jwe/index.mjs';
+import parseTypes from './transform/index.mjs';
 const exec = util.promisify(ChildProcess.exec);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const files = [
-    { name: "index.mts", dir: "src/controller" },
-    { name: "index.mts", dir: "src" },
-    { name: "package.json", dir: "" },
-    { name: "Containerfile", dir: "" },
-    { name: "entrypoint.sh", dir: "" },
-    { name: "tsconfig.json", dir: "" },
+    { name: 'index.mts', dir: 'src/controller' },
+    { name: 'index.mts', dir: 'src' },
+    { name: 'package.json', dir: '' },
+    { name: 'Containerfile', dir: '' },
+    { name: 'entrypoint.sh', dir: '' },
+    { name: 'tsconfig.json', dir: '' },
 ];
 const extract = ({ target, name, connectorId }) => {
     const source = `${__dirname}/../template/connector/`;
@@ -29,11 +29,11 @@ const extract = ({ target, name, connectorId }) => {
             fs.mkdirSync(`${target}/${dir}`, { recursive: true });
         }
         const content = fs.readFileSync(`${source}/${dir}/${name}`, {
-            encoding: "utf-8",
+            encoding: 'utf-8',
         });
         fs.writeFileSync(`${target}/${dir}/${name}`, content);
     });
-    const content = JSON.parse(fs.readFileSync(`${target}/package.json`, { encoding: "utf-8" }));
+    const content = JSON.parse(fs.readFileSync(`${target}/package.json`, { encoding: 'utf-8' }));
     content.name = name;
     content.connectorId = connectorId;
     fs.writeFileSync(`${target}/package.json`, JSON.stringify(content, null, 2));
@@ -56,28 +56,28 @@ PUBLIC_KEY=${pub}
 };
 const program = new Command();
 program
-    .name("npx @aloma.io/integration-sdk")
-    .description("aloma.io integration sdk")
-    .version("0.8.0")
+    .name('npx @aloma.io/integration-sdk')
+    .description('aloma.io integration sdk')
+    .version('0.8.0')
     .showHelpAfterError();
 program
-    .command("create")
-    .description("Create a new connector project")
-    .argument("<name>", "name of the project")
-    .requiredOption("--connector-id <id>", "id of the connector")
+    .command('create')
+    .description('Create a new connector project')
+    .argument('<name>', 'name of the project')
+    .requiredOption('--connector-id <id>', 'id of the connector')
     .action(async (name, options) => {
-    name = name.replace(/[\/\.]/gi, "");
+    name = name.replace(/[\/\.]/gi, '');
     if (!name)
-        throw new Error("name is empty");
+        throw new Error('name is empty');
     const target = `${process.cwd()}/${name}`;
     fs.mkdirSync(target);
-    console.log("Creating connector ...");
+    console.log('Creating connector ...');
     extract({ ...options, target, name });
-    console.log("Generating keys ...");
+    console.log('Generating keys ...');
     await generateKeys({ target });
-    console.log("Installing dependencies ...");
+    console.log('Installing dependencies ...');
     await exec(`cd ${target}; yarn`);
-    console.log("Building ...");
+    console.log('Building ...');
     await exec(`cd ${target}; yarn build`);
     console.log(`
 Success!
@@ -87,8 +87,8 @@ Success!
 3.) Start the connector with cd ./${name}/; yarn start`);
 });
 program
-    .command("build")
-    .description("Build the current connector project")
+    .command('build')
+    .description('Build the current connector project')
     .action(async (str, options) => {
     const { stdout, stderr } = await exec(`rm -rf build; mkdir -p build; `);
     try {
@@ -99,22 +99,22 @@ program
     }
     if (stdout)
         console.log(stdout);
-    new Extractor().extract("./src/controller/index.mts", "./build/.controller.json");
+    new Extractor().extract('./src/controller/index.mts', './build/.controller.json');
 });
 class Extractor {
     async extract(source, target) {
-        notEmpty(source, "source");
+        notEmpty(source, 'source');
         fs.readFileSync(source);
         const { text, methods } = await parseTypes(source);
-        const packageJson = JSON.parse(fs.readFileSync(TARGET_DIR + "package.json", {
-            encoding: "utf-8",
+        const packageJson = JSON.parse(fs.readFileSync(TARGET_DIR + 'package.json', {
+            encoding: 'utf-8',
         }));
         fs.writeFileSync(target, JSON.stringify({
             text,
             methods,
             connectorId: packageJson.connectorId,
             version: packageJson.version,
-        }), { encoding: "utf-8" });
+        }), { encoding: 'utf-8' });
     }
 }
 program.parse();

package/build/controller/index.d.mts

@@ -1,21 +1,65 @@
-import Fetcher from "../internal/fetcher/fetcher.mjs";
+import Fetcher from '../internal/fetcher/fetcher.mjs';
+import { OAuth } from '../internal/fetcher/oauth-fetcher.mjs';
 export declare abstract class AbstractController {
+    /**
+     * connector configuration
+     */
     protected config: {
         [key: string]: any;
     };
+    /**
+     * @deprecated
+     */
     protected client: any;
+    /**
+     * oauth data, if the connector is using oauth
+     */
+    protected oauth?: OAuth;
+    /**
+     * invoked, when the controller is started
+     */
     protected start(): Promise<void>;
+    /**
+     * invoked, when the controller is stopped
+     * @param isShutdown true if the controller is stopped due to shutdown
+     */
     protected stop(isShutdown?: boolean): Promise<void>;
     protected configQuery(arg: any): Promise<any>;
+    /**
+     * autocomplete configuration options
+     *
+     * e.g. if this connector is connected to a system which has multiple entities with dynamic attributes, like deals, ...
+     * then this method should return the possible attributes of the entity when invoked like
+     * ```javascript
+     * autocomplete({entity: 'deal'})
+     * ```
+     * @param arg
+     * @returns
+     */
     protected autocomplete(arg: any): Promise<any>;
+    /**
+     * called, when the remote public method is not found on the controller
+     * @param arg
+     */
     protected fallback(arg: any): Promise<any>;
     protected endpoint(arg: any): Promise<any>;
+    /**
+     * create a new task
+     * @param name name of the task
+     * @param data data of the task
+     */
     protected newTask(name: string, data: any): Promise<string>;
     protected getClient({ baseUrl, onResponse, customize, }: {
         baseUrl?: string;
         onResponse?: (response: any) => void;
         customize?: (request: any) => void;
     }): Fetcher;
+    /**
+     * update a task
+     * @param name name of the task
+     * @param data partial data of the task to update
+     * @returns taskId
+     */
     protected updateTask(name: string, data: any): Promise<string>;
     protected createBlob({ content, name, size, mimetype, meta, taskId, }: {
         content: string;
@@ -25,6 +69,10 @@ export declare abstract class AbstractController {
         meta?: any;
         taskId?: string;
     }): Promise<string>;
+    /**
+     * get the metadata of a blob by id
+     * @param id blob id
+     */
     protected getBlob(id: string): Promise<{
         name?: string;
         id: any;
@@ -32,13 +80,21 @@ export declare abstract class AbstractController {
         mimetype?: string;
         meta?: any;
     }>;
+    /**
+     * get the content of a blob by id as base64
+     * @param id blob id
+     */
     protected getBlobContent(id: string): Promise<string>;
+    /**
+     * health check, will be called periodically
+     * throw an error if unhealthy with a message describing what needs to be fixed
+     */
     protected healthCheck(): Promise<any>;
     __endpoint(arg: any): Promise<any | null>;
     __configQuery(arg: any): Promise<any | null>;
     __autocomplete(arg: any): Promise<any | null>;
     __default(arg: any): Promise<any | null>;
     __healthCheck(): Promise<any>;
-    _doStart(config: any, client: any, newTask: any, updateTask: any, getClient: any, getBlob: any, getBlobContent: any, createBlob: any): Promise<void>;
+    _doStart(config: any, oauth: any, newTask: any, updateTask: any, getClient: any, getBlob: any, getBlobContent: any, createBlob: any): Promise<void>;
     _doStop(isShutdown?: boolean): Promise<void>;
 }

package/build/controller/index.mjs

@@ -1,38 +1,93 @@
 export class AbstractController {
+    /**
+     * connector configuration
+     */
     config = {};
+    /**
+     * @deprecated
+     */
     client;
+    /**
+     * oauth data, if the connector is using oauth
+     */
+    oauth;
+    /**
+     * invoked, when the controller is started
+     */
     async start() { }
+    /**
+     * invoked, when the controller is stopped
+     * @param isShutdown true if the controller is stopped due to shutdown
+     */
     async stop(isShutdown = false) { }
     configQuery(arg) {
         return Promise.resolve({});
     }
+    /**
+     * autocomplete configuration options
+     *
+     * e.g. if this connector is connected to a system which has multiple entities with dynamic attributes, like deals, ...
+     * then this method should return the possible attributes of the entity when invoked like
+     * ```javascript
+     * autocomplete({entity: 'deal'})
+     * ```
+     * @param arg
+     * @returns
+     */
     autocomplete(arg) {
         return Promise.resolve({});
     }
+    /**
+     * called, when the remote public method is not found on the controller
+     * @param arg
+     */
     fallback(arg) {
-        throw new Error("method not found");
+        throw new Error('method not found');
     }
     async endpoint(arg) {
-        throw new Error("method not found");
+        throw new Error('method not found');
     }
+    /**
+     * create a new task
+     * @param name name of the task
+     * @param data data of the task
+     */
     async newTask(name, data) {
-        throw new Error("not implemented");
+        throw new Error('not implemented');
     }
     getClient({ baseUrl, onResponse, customize, }) {
-        throw new Error("not implemented");
-    }
+        throw new Error('not implemented');
+    }
+    /**
+     * update a task
+     * @param name name of the task
+     * @param data partial data of the task to update
+     * @returns taskId
+     */
     async updateTask(name, data) {
-        throw new Error("not implemented");
+        throw new Error('not implemented');
     }
     async createBlob({ content, name, size, mimetype, meta, taskId, }) {
-        throw new Error("not implemented");
+        throw new Error('not implemented');
     }
+    /**
+     * get the metadata of a blob by id
+     * @param id blob id
+     */
     async getBlob(id) {
-        throw new Error("not implemented");
+        throw new Error('not implemented');
     }
+    /**
+     * get the content of a blob by id as base64
+     * @param id blob id
+     */
     async getBlobContent(id) {
-        throw new Error("not implemented");
+        throw new Error('not implemented');
     }
+    /**
+     * health check, will be called periodically
+     * throw an error if unhealthy with a message describing what needs to be fixed
+     */
     async healthCheck() {
         // blank, throw an error if unhealthy
     }
@@ -51,9 +106,11 @@ export class AbstractController {
     async __healthCheck() {
         return this.healthCheck();
     }
-    async _doStart(config, client, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob) {
+    async _doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob) {
+        console.dir(config, { depth: null });
         this.config = config;
-        this.client = client;
+        this.client = oauth;
+        this.oauth = oauth;
         this.newTask = newTask;
         this.updateTask = updateTask;
         this.getClient = getClient;

package/build/index.d.mts

@@ -1,2 +1,2 @@
-export * from "./builder/index.mjs";
-export * from "./controller/index.mjs";
+export * from './builder/index.mjs';
+export * from './controller/index.mjs';

package/build/index.mjs

@@ -1,2 +1,2 @@
-export * from "./builder/index.mjs";
-export * from "./controller/index.mjs";
+export * from './builder/index.mjs';
+export * from './controller/index.mjs';

package/build/internal/connector/config.d.mts

@@ -1,5 +1,5 @@
-import { Config } from "../websocket/config.mjs";
-export declare const makeConfig: ({ id, version, name, introspect, configSchema, icon, }: {
+import { Config } from '../websocket/config.mjs';
+export declare const makeConfig: ({ id, version, name, introspect, configSchema, icon }: {
     id: any;
     version: any;
     name: any;

package/build/internal/connector/config.mjs

@@ -1,13 +1,13 @@
-import JWE from "../util/jwe/index.mjs";
-import { Config } from "../websocket/config.mjs";
-export const makeConfig = async ({ id, version, name, introspect, configSchema, icon, }) => {
+import JWE from '../util/jwe/index.mjs';
+import { Config } from '../websocket/config.mjs';
+export const makeConfig = async ({ id, version, name, introspect, configSchema, icon }) => {
     const config = new Config({
         id: id,
         version: version,
         name: process.env.HOSTNAME || name,
         registrationToken: process.env.REGISTRATION_TOKEN,
-        endpoint: process.env.DEVICE_ENDPOINT || "https://connect.aloma.io/",
-        wsEndpoint: process.env.WEBSOCKET_ENDPOINT || "wss://connect.aloma.io/transport/",
+        endpoint: process.env.DEVICE_ENDPOINT || 'https://connect.aloma.io/',
+        wsEndpoint: process.env.WEBSOCKET_ENDPOINT || 'wss://connect.aloma.io/transport/',
         privateKey: process.env.PRIVATE_KEY,
         publicKey: process.env.PUBLIC_KEY,
         introspect,
@@ -21,15 +21,15 @@ export const makeConfig = async ({ id, version, name, introspect, configSchema,
         catch (e) {
             const haveKey = !!process.env.PRIVATE_KEY;
             const jwe = new JWE({});
-            var text = "Please double check the env variables";
+            var text = 'Please double check the env variables';
             if (!haveKey) {
                 await jwe.newPair();
                 text =
-                    "fresh keys generated, set environment variables: \n\nPRIVATE_KEY: " +
+                    'fresh keys generated, set environment variables: \n\nPRIVATE_KEY: ' +
                         (await jwe.exportPrivateAsBase64()) +
-                        "\n\nPUBLIC_KEY: " +
+                        '\n\nPUBLIC_KEY: ' +
                         (await jwe.exportPublicAsBase64()) +
-                        "\n";
+                        '\n';
             }
             console.log(`
 Error:
@@ -43,7 +43,7 @@ ${text}
                     resolve(null);
                 }, 2 * 60 * 1000);
             });
-            throw new Error("could not start");
+            throw new Error('could not start');
         }
     }
     return config;

package/build/internal/connector/index.d.mts

@@ -1,10 +1,10 @@
-import { Dispatcher } from "../dispatcher/index.mjs";
+import { Dispatcher } from '../dispatcher/index.mjs';
 export declare class Connector {
     id: any;
     version: any;
     name: any;
     icon: any;
-    dispatcher?: Dispatcher;
+    dispatcher: Dispatcher;
     constructor({ version, id, name, icon }: {
         version: any;
         id: any;

package/build/internal/connector/index.mjs

@@ -1,7 +1,7 @@
-import { Dispatcher } from "../dispatcher/index.mjs";
-import { makeConfig } from "./config.mjs";
-import { makeMetrics } from "./metrics.mjs";
-import { makeServer } from "./server/index.mjs";
+import { Dispatcher } from '../dispatcher/index.mjs';
+import { makeConfig } from './config.mjs';
+import { makeMetrics } from './metrics.mjs';
+import { makeServer } from './server/index.mjs';
 export class Connector {
     id;
     version;