@aloma.io/integration-sdk 3.8.11 → 3.8.12

package/src/controller/index.mts

@@ -1,31 +1,71 @@
-import Fetcher from "../internal/fetcher/fetcher.mjs";
+import Fetcher from '../internal/fetcher/fetcher.mjs';
+import { OAuth } from '../internal/fetcher/oauth-fetcher.mjs';
 
 export 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 async start(): Promise<void> {}
 
+  /**
+   * invoked, when the controller is stopped
+   * @param isShutdown true if the controller is stopped due to shutdown
+   */
   protected async stop(isShutdown: boolean = false): Promise<void> {}
 
   protected configQuery(arg: any): Promise<any> {
     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
+   */
   protected autocomplete(arg: any): Promise<any> {
     return Promise.resolve({});
   }
 
+  /**
+   * called, when the remote public method is not found on the controller
+   * @param arg
+   */
   protected fallback(arg: any): Promise<any> {
-    throw new Error("method not found");
+    throw new Error('method not found');
   }
 
   protected async endpoint(arg: any): Promise<any> {
-    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
+   */
   protected async newTask(name: string, data: any): Promise<string> {
-    throw new Error("not implemented");
+    throw new Error('not implemented');
   }
 
   protected getClient({
@@ -37,11 +77,17 @@ export abstract class AbstractController {
     onResponse?: (response: any) => void;
     customize?: (request: any) => void;
   }): Fetcher {
-    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
+   */
   protected async updateTask(name: string, data: any): Promise<string> {
-    throw new Error("not implemented");
+    throw new Error('not implemented');
   }
 
   protected async createBlob({
@@ -59,9 +105,13 @@ export abstract class AbstractController {
     meta?: any;
     taskId?: string;
   }): Promise<string> {
-    throw new Error("not implemented");
+    throw new Error('not implemented');
   }
 
+  /**
+   * get the metadata of a blob by id
+   * @param id blob id
+   */
   protected async getBlob(id: string): Promise<{
     name?: string;
     id;
@@ -69,13 +119,21 @@ export abstract class AbstractController {
     mimetype?: string;
     meta?: any;
   }> {
-    throw new Error("not implemented");
+    throw new Error('not implemented');
   }
 
+  /**
+   * get the content of a blob by id as base64
+   * @param id blob id
+   */
   protected async getBlobContent(id: string): Promise<string> {
-    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
+   */
   protected async healthCheck(): Promise<any> {
     // blank, throw an error if unhealthy
   }
@@ -102,16 +160,18 @@ export abstract class AbstractController {
 
   async _doStart(
     config: any,
-    client: any,
+    oauth: any,
     newTask: any,
     updateTask: any,
     getClient: any,
     getBlob: any,
     getBlobContent: any,
-    createBlob: any,
+    createBlob: any
   ): Promise<void> {
+    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/src/index.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/src/internal/connector/config.mts

@@ -1,22 +1,14 @@
-import JWE from "../util/jwe/index.mjs";
-import { Config } from "../websocket/config.mjs";
+import JWE from '../util/jwe/index.mjs';
+import {Config} from '../websocket/config.mjs';
 
-export const makeConfig = async ({
-  id,
-  version,
-  name,
-  introspect,
-  configSchema,
-  icon,
-}): Promise<Config> => {
+export const makeConfig = async ({id, version, name, introspect, configSchema, icon}): Promise<Config> => {
   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,
@@ -30,16 +22,16 @@ export const makeConfig = async ({
     } 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(`
@@ -55,11 +47,11 @@ ${text}
           () => {
             resolve(null);
           },
-          2 * 60 * 1000,
+          2 * 60 * 1000
         );
       });
 
-      throw new Error("could not start");
+      throw new Error('could not start');
     }
   }
 

package/src/internal/connector/index.mts

@@ -1,15 +1,15 @@
-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: any;
   version: any;
   name: any;
   icon: any;
-  dispatcher?: Dispatcher;
-  constructor({ version, id, name, icon }) {
+  dispatcher!: Dispatcher;
+  constructor({version, id, name, icon}) {
     this.id = id;
     this.version = version;
     this.name = name;
@@ -23,8 +23,7 @@ export class Connector {
   async run() {
     console.log(`Running ${this.name}`);
 
-    const { processPacket, start, introspect, configSchema } =
-      this.dispatcher!.build();
+    const {processPacket, start, introspect, configSchema} = this.dispatcher.build();
 
     const config = await makeConfig({
       id: this.id,
@@ -46,7 +45,7 @@ export class Connector {
       configSchema,
       start,
       processPacket,
-      dispatcher: this.dispatcher!,
+      dispatcher: this.dispatcher,
     });
 
     await server.start();

package/src/internal/connector/metrics.mts

@@ -1,7 +1,7 @@
-import express from "express";
-import PromClient from "prom-client";
+import express from 'express';
+import PromClient from 'prom-client';
 
-export const makeMetrics = async ({ id, name, version }): Promise<void> => {
+export const makeMetrics = async ({id, name, version}): Promise<void> => {
   const newMetrics = () => {
     const metrics = PromClient;
 
@@ -9,7 +9,7 @@ export const makeMetrics = async ({ id, name, version }): Promise<void> => {
       service: name,
       connectorId: id,
       connectorVersion: version,
-      node: process.env.HOSTNAME || "test",
+      node: process.env.HOSTNAME || 'test',
     };
     metrics.register.setDefaultLabels(defaultLabels);
     metrics.collectDefaultMetrics();
@@ -20,9 +20,9 @@ export const makeMetrics = async ({ id, name, version }): Promise<void> => {
   const makeMetricsServer = (metrics) => {
     const app = express();
 
-    app.get("/metrics", async (request, response, next) => {
+    app.get('/metrics', async (request, response, next) => {
       response.status(200);
-      response.set("Content-type", metrics.contentType);
+      response.set('Content-type', metrics.contentType);
       response.send(await metrics.register.metrics());
       response.end();
     });
@@ -30,5 +30,5 @@ export const makeMetrics = async ({ id, name, version }): Promise<void> => {
     return app;
   };
 
-  makeMetricsServer(newMetrics()).listen(4050, "0.0.0.0");
+  makeMetricsServer(newMetrics()).listen(4050, '0.0.0.0');
 };

package/src/internal/connector/server/index.mts

@@ -1,8 +1,8 @@
-import Dispatcher from "../../dispatcher/index.mjs";
-import { Config } from "../../websocket/config.mjs";
-import { WebsocketConnector } from "../../websocket/index.mjs";
-import { onConnect } from "./on-connect/index.mjs";
-import { onMessage } from "./on-message.mjs";
+import Dispatcher from '../../dispatcher/index.mjs';
+import {Config} from '../../websocket/config.mjs';
+import {WebsocketConnector} from '../../websocket/index.mjs';
+import {onConnect} from './on-connect/index.mjs';
+import {onMessage} from './on-message.mjs';
 
 export const makeServer = async ({
   config,
@@ -19,7 +19,7 @@ export const makeServer = async ({
 }): Promise<WebsocketConnector> => {
   const server = new WebsocketConnector({
     config,
-    onConnect: onConnect({ config, configSchema, dispatcher, start }),
+    onConnect: onConnect({config, configSchema, dispatcher, start}),
     onMessage: onMessage(processPacket),
   });
 
@@ -36,16 +36,16 @@ export const makeServer = async ({
     process.exit(0);
   };
 
-  process.on("uncaughtException", (e) => {
+  process.on('uncaughtException', (e) => {
     console.log(e);
   });
 
-  process.on("unhandledRejection", (e) => {
+  process.on('unhandledRejection', (e) => {
     console.log(e);
   });
 
-  process.on("SIGTERM", term);
-  process.on("SIGINT", term);
+  process.on('SIGTERM', term);
+  process.on('SIGINT', term);
 
   return server;
 };

package/src/internal/connector/server/on-connect/decrypt-config.mts

@@ -1,23 +1,23 @@
-export const decryptConfig = async ({ configSchema, config, secrets }) => {
+export const decryptConfig = async ({configSchema, config, secrets}) => {
   const decrypted: any = {};
 
   const fields = configSchema().fields;
 
   const keys = Object.keys(secrets);
-  const jwe = await config.validateKeys("RSA-OAEP-256");
+  const jwe = await config.validateKeys('RSA-OAEP-256');
 
   for (var i = 0; i < keys.length; ++i) {
     const key = keys[i];
     const value = secrets[key];
     if (!value) continue;
 
-    if (fields[key]?.plain || ["endpointUrl"].includes(key)) {
+    if (fields[key]?.plain || ['endpointUrl'].includes(key)) {
       decrypted[key] = value;
     } else {
       try {
         decrypted[key] = await jwe.decrypt(value, config.id());
       } catch (e) {
-        console.log("failed to decrypt key", key, config.id(), e);
+        console.log('failed to decrypt key', key, config.id(), e);
       }
     }
   }

package/src/internal/connector/server/on-connect/finish-oauth.mts

@@ -1,6 +1,6 @@
-import Dispatcher from "../../../dispatcher/index.mjs";
-import { Config } from "../../../websocket/config.mjs";
-import { WebsocketConnector } from "../../../websocket/index.mjs";
+import Dispatcher from '../../../dispatcher/index.mjs';
+import {Config} from '../../../websocket/config.mjs';
+import {WebsocketConnector} from '../../../websocket/index.mjs';
 
 export const patchFinishOAuth = async ({
   dispatcher,
@@ -17,41 +17,30 @@ export const patchFinishOAuth = async ({
     code: string;
     redirectURI: string;
     codeVerifier?: string;
-  }): Promise<{ value: string }> {
-    const tokenURL =
-      process.env.OAUTH_TOKEN_URL ||
-      decrypted.tokenURL ||
-      dispatcher._oauth.tokenURL;
+  }): Promise<{value: string}> {
+    const tokenURL = process.env.OAUTH_TOKEN_URL || decrypted.tokenURL || dispatcher._oauth.tokenURL;
 
-    if (!dispatcher._oauth) throw new Error("oauth not configured");
-    if (!tokenURL && !dispatcher._oauth.finishOAuth)
-      throw new Error("need tokenURL or finishOAuth(arg)");
+    if (!dispatcher._oauth) throw new Error('oauth not configured');
+    if (!tokenURL && !dispatcher._oauth.finishOAuth) throw new Error('need tokenURL or finishOAuth(arg)');
 
     var data = null;
 
     const doFinish = async () => {
-      if (!arg.code || !arg.redirectURI)
-        throw new Error("need code and redirectUri");
+      if (!arg.code || !arg.redirectURI) throw new Error('need code and redirectUri');
 
-      const clientId =
-        decrypted.clientId ||
-        process.env.OAUTH_CLIENT_ID ||
-        dispatcher._oauth.clientId;
+      const clientId = decrypted.clientId || process.env.OAUTH_CLIENT_ID || dispatcher._oauth.clientId;
 
-      if (!clientId) throw new Error("clientId not configured");
+      if (!clientId) throw new Error('clientId not configured');
 
-      const clientSecret =
-        decrypted.clientSecret ||
-        process.env.OAUTH_CLIENT_SECRET ||
-        dispatcher._oauth.clientSecret;
-      if (!clientSecret) throw new Error("clientSecret not configured");
+      const clientSecret = decrypted.clientSecret || process.env.OAUTH_CLIENT_SECRET || dispatcher._oauth.clientSecret;
+      if (!clientSecret) throw new Error('clientSecret not configured');
 
       const additionalTokenArgs = dispatcher._oauth.additionalTokenArgs || {};
       const useAuthHeader = !!dispatcher._oauth.useAuthHeader;
       const useCodeChallenge = !!dispatcher._oauth.useCodeChallenge;
 
       let body = {
-        grant_type: "authorization_code",
+        grant_type: 'authorization_code',
         ...additionalTokenArgs,
         code: arg.code,
         redirect_uri: arg.redirectURI,
@@ -62,8 +51,8 @@ export const patchFinishOAuth = async ({
       }
 
       let headers: any = {
-        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
-        Accept: "application/json",
+        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
+        Accept: 'application/json',
       };
 
       if (useAuthHeader) {
@@ -80,7 +69,7 @@ export const patchFinishOAuth = async ({
       }
 
       const response = await fetch(tokenURL, {
-        method: "POST",
+        method: 'POST',
         body: new URLSearchParams(body),
         headers,
         signal: AbortSignal.timeout(60 * 1000),
@@ -92,16 +81,14 @@ export const patchFinishOAuth = async ({
       if (status === 200) {
         const ret = JSON.parse(text);
         if (ret.error) {
-          throw new Error(
-            `${status} ${ret.error} ${ret.error_description || ""}`,
-          );
+          throw new Error(`${status} ${ret.error} ${ret.error_description || ''}`);
         } else if (ret.access_token) {
-          return { ...ret };
+          return {...ret};
         } else {
-          throw new Error(status + " response has no access_token - " + text);
+          throw new Error(status + ' response has no access_token - ' + text);
         }
       } else {
-        throw new Error(status + " " + text);
+        throw new Error(status + ' ' + text);
       }
     };
 
@@ -115,8 +102,8 @@ export const patchFinishOAuth = async ({
       data = await doFinish();
     }
 
-    const jwe = await config.validateKeys("RSA-OAEP-256");
+    const jwe = await config.validateKeys('RSA-OAEP-256');
 
-    return { value: await jwe.encrypt(data, "none", config.id()) };
+    return {value: await jwe.encrypt(data, 'none', config.id())};
   };
 };

package/src/internal/connector/server/on-connect/index.mts

@@ -1,13 +1,14 @@
-import { init } from "@paralleldrive/cuid2";
-import Dispatcher from "../../../dispatcher/index.mjs";
-import Fetcher from "../../../fetcher/fetcher.mjs";
-import { Config } from "../../../websocket/config.mjs";
-import { decryptConfig } from "./decrypt-config.mjs";
-import { patchFinishOAuth } from "./finish-oauth.mjs";
-import { makeOAuth } from "./make-oauth.mjs";
-import { patchStartOAuth } from "./start-oauth.mjs";
-
-const cuid = init({ length: 32 });
+import { init } from '@paralleldrive/cuid2';
+import { AbstractController } from '../../../../index.mjs';
+import Dispatcher from '../../../dispatcher/index.mjs';
+import Fetcher from '../../../fetcher/fetcher.mjs';
+import { Config } from '../../../websocket/config.mjs';
+import { decryptConfig } from './decrypt-config.mjs';
+import { patchFinishOAuth } from './finish-oauth.mjs';
+import { makeOAuth } from './make-oauth.mjs';
+import { patchStartOAuth } from './start-oauth.mjs';
+
+const cuid = init({length: 32});
 
 export const onConnect = ({
   dispatcher,
@@ -28,8 +29,8 @@ export const onConnect = ({
         config,
       });
 
-      await patchStartOAuth({ dispatcher, decrypted });
-      await patchFinishOAuth({ dispatcher, decrypted, config, transport });
+      await patchStartOAuth({dispatcher, decrypted});
+      await patchFinishOAuth({dispatcher, decrypted, config, transport});
 
       const theOAuth = await makeOAuth({
         config,
@@ -43,10 +44,10 @@ export const onConnect = ({
           const packet = transport.newPacket(
             {},
             (ret) => (ret?.error ? reject(ret.error) : resolve(ret)),
-            `_req-${cuid()}`,
+            `_req-${cuid()}`
           );
 
-          packet.method("connector.blob.get");
+          packet.method('connector.blob.get');
           packet.args({
             id,
           });
@@ -60,10 +61,10 @@ export const onConnect = ({
           const packet = transport.newPacket(
             {},
             (ret) => (ret?.error ? reject(ret.error) : resolve(ret?.content)),
-            `_req-${cuid()}`,
+            `_req-${cuid()}`
           );
 
-          packet.method("connector.blob.get-content");
+          packet.method('connector.blob.get-content');
           packet.args({
             id,
           });
@@ -77,10 +78,10 @@ export const onConnect = ({
           const packet = transport.newPacket(
             {},
             (ret) => (ret?.error ? reject(ret.error) : resolve(ret?.id)),
-            `_req-${cuid()}`,
+            `_req-${cuid()}`
           );
 
-          packet.method("connector.blob.create");
+          packet.method('connector.blob.create');
           packet.args(args);
 
           transport.send(packet);
@@ -95,8 +96,8 @@ export const onConnect = ({
         getBlob,
         getBlobContent,
         createBlob,
-        healthCheck: async (controller) => {
-          let result: any = { ok: true, error: null };
+        healthCheck: async (controller: AbstractController) => {
+          let result: any = {ok: true, error: null};
 
           try {
             if (oauthClient) {
@@ -111,22 +112,21 @@ export const onConnect = ({
 
           const packet = transport.newPacket({});
 
-          packet.method("connector.health.check");
+          packet.method('connector.health.check');
           packet.args(result);
 
           transport.send(packet);
         },
-        getClient: (arg) =>
-          theOAuth ? (oauthClient = theOAuth.getClient(arg)) : new Fetcher(arg),
+        getClient: (arg) => (theOAuth ? (oauthClient = theOAuth.getClient(arg)) : new Fetcher(arg)),
         newTask: (name, data) => {
           return new Promise((resolve, reject) => {
             const packet = transport.newPacket(
               {},
               (ret) => (ret?.error ? reject(ret.error) : resolve(ret)),
-              `_req-${cuid()}`,
+              `_req-${cuid()}`
             );
 
-            packet.method("connector.task.new");
+            packet.method('connector.task.new');
             packet.args({
               name,
               a: data,
@@ -140,10 +140,10 @@ export const onConnect = ({
             const packet = transport.newPacket(
               {},
               (ret) => (ret?.error ? reject(ret.error) : resolve(ret)),
-              `_req-${cuid()}`,
+              `_req-${cuid()}`
             );
 
-            packet.method("connector.task.update");
+            packet.method('connector.task.update');
             packet.args({
               id,
               a: data,