@aloma.io/integration-sdk 3.0.0-10

package/README.md

@@ -0,0 +1,9 @@
+# nodejs - Aloma Integration SDK
+
+## Prerequisites
+
+* You can find the `REGISTRATION_TOKEN` in your aloma workspace in the integration section.
+
+## Integration Examples
+
+See `examples` directory.

package/examples/hello-world/Containerfile

@@ -0,0 +1,17 @@
+FROM node:16-alpine3.18
+
+ENV NODE_ENV production
+
+WORKDIR /connector/
+
+COPY ./package.json ./
+COPY ./entrypoint.sh ./
+COPY ./src ./src
+
+RUN set -e; adduser -S -u 1111 connector
+
+RUN set -e; apk add --no-cache git; yarn config set --home enableTelemetry 0; chmod 755 /connector/entrypoint.sh; cd /connector/; yarn install; rm -rf package.json; rm -rf yarn.lock; 
+
+USER connector
+
+ENTRYPOINT ["/connector/entrypoint.sh"]

package/examples/hello-world/entrypoint.sh

@@ -0,0 +1,5 @@
+#!/bin/sh -e
+
+cd /connector/
+
+exec node src/index.js $@

package/examples/hello-world/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "hello-world",
+  "version": "1.0.0",
+  "description": "",
+  "author": "aloma.io",
+  "license": "Apache-2.0",
+  "scripts": {},
+  "dependencies": {
+    "@aloma.io/integration-sdk": "^3"
+  }
+}

package/examples/hello-world/src/controller/index.js

@@ -0,0 +1,14 @@
+class Controller
+{
+  setConfig({newTask, config})
+  {
+    // blank
+  }
+  
+  async hello(args)
+  {
+    return "world";
+  }
+}
+
+module.exports = {Controller}

package/examples/hello-world/src/index.js

@@ -0,0 +1,29 @@
+const {Connector}  = require('@aloma-io/integration-sdk');
+const {Controller} = require('./controller');
+
+const connector    = new Connector({id: 'TODO your connector id', version: '1.0.0'});
+const controller   = new Controller();
+
+connector.configure()
+  // types are the calls available in the step, these are typescript definitions
+  .types
+  (`
+    declare function hello(arg: {}): any;
+  `)
+  // resolvers hold the calls
+  .resolvers
+  ({
+    hello: async (args) => 
+    {
+      return controller.hello(args);
+    },
+  })
+  // main will be called once the connector is connected
+  .main(({newTask, config}) =>
+  {
+    // the config might have changed, so the connector should be able to deal with multiple setConfigs over it's lifetime
+    controller.setConfig({newTask, config});
+  });  
+
+// start the connector
+connector.run();

package/examples/kitchen-sink/01-hello-world.js

@@ -0,0 +1,26 @@
+const {Connector}  = require('@aloma-io/integration-sdk');
+
+const connector    = new Connector({id: 'TODO your connector id', version: '1.0.0'});
+
+connector.configure()
+  // types are the calls available in the step, these are typescript definitions
+  .types
+  (`
+    declare function hello(arg: {}): any;
+  `)
+  // resolvers hold the calls
+  .resolvers
+  ({
+    hello: async (args) => 
+    {
+      return "world";
+    },
+  })
+  // main will be called once the connector is connected
+  .main(({newTask, config}) =>
+  {
+    // the config might have changed, so the connector should be able to deal with multiple setConfigs over it's lifetime
+  });  
+
+// start the connector
+connector.run();

package/examples/kitchen-sink/02-config.js

@@ -0,0 +1,54 @@
+const {Connector}  = require('@aloma-io/integration-sdk');
+
+const connector    = new Connector({id: 'TODO your connector id', version: '1.0.0'});
+
+connector.configure()
+  // these config fields can be configured from the aloma ui. these require a private and a public key which the connector will generate on start
+  .config({fields: 
+  {
+    // this is then available from config.type
+    type: {
+      // name and placeholder for ui configuration
+      name: 'Database Type',
+      placeholder: 'e.g. mysql, pg, tedious',
+      // type
+      type: 'line',
+      // this is an unencrypted value, by default everything is encrypted
+      plain: true
+    },
+    user: {
+      name: 'User',
+      placeholder: 'e.g. john',
+      type: 'line',
+      plain: true,
+      // this is marked as optional in the ui, so does not have to be provided, everything else is mandatory
+      optional: true
+    },
+    // this is encrypted in the ui via public key, can only be decrypted by the connector having the private key
+    password: {
+      name: 'Password',
+      placeholder: 'e.g. x3gsadg',
+      type: 'line',
+      optional: true
+    },
+ 
+  }})
+  .types
+  (`
+    declare function hello(arg: {}): any;
+  `)
+  .resolvers
+  ({
+    hello: async (args) => 
+    {
+      return "world";
+    },
+  })
+  .main(({newTask, config}) =>
+  {
+    console.log(config.type)
+    console.log(config.password)
+    console.log(config.user)
+  });  
+
+connector.run();

package/examples/kitchen-sink/03-oauth.js

@@ -0,0 +1,36 @@
+const {Connector}  = require('@aloma-io/integration-sdk');
+
+const connector    = new Connector({id: 'TODO your connector id', version: '1.0.0'});
+
+connector.configure()
+  // these require a private and a public key which the connector will generate on start
+  // after a connector is added to a workspace it can be connected from the aloma ui
+  .oauth
+  ({
+    // the authorization url, the placeholders {{clientId}}, {{redirectURI}}, {{scope}} will be filled in by aloma
+    authorizationURL: 'https://github.com/login/oauth/authorize?client_id={{clientId}}&redirect_uri={{redirectURI}}&scope={{scope}}&allow_signup=false',
+    tokenURL: 'https://github.com/login/oauth/access_token',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    scope: 'repo, user:email'
+  })
+  .types
+  (`
+    declare function hello(arg: {}): any;
+  `)
+  .resolvers
+  ({
+    hello: async (args) => 
+    {
+      return "world";
+    },
+  })
+  .main(({newTask, config, oauth}) =>
+  {
+    // one can access oauth.accessToken()
+    // one can get a fetch client: oauth.getClient()
+    // the client supports retries and will also do an automatic token refresh if a refresh_token is provided
+    // oauth.getClient().fetch({url, options = {method: 'POST', headers: {}, body: ''})
+  });  
+
+connector.run();

package/index.js

@@ -0,0 +1,3 @@
+const {Connector} = require('./src/')
+
+module.exports = {Connector}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@aloma.io/integration-sdk",
+  "version": "3.0.0-10",
+  "description": "",
+  "author": "aloma.io",
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "./node_modules/typescript/bin/tsc --watch",
+    "build": "./node_modules/typescript/bin/tsc",
+    "test": "./node_modules/mocha/bin/_mocha --recursive",
+    "format": "yarn prettier --write src/"
+  },
+  "main": "./build/index.js",
+  "exports": {
+    ".": {
+      "import": "./build/index.mjs",
+      "require": "./build/index.js"
+    },
+    "./build/*": "./build/*",
+    "./package": "./package.json",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@paralleldrive/cuid2": "^2",
+    "dotenv": "*",
+    "express": "^4",
+    "jose": "^4",
+    "node-fetch": "^2",
+    "prom-client": "^14",
+    "ws": "^8"
+  },
+  "optionalDependencies": {
+    "bufferutil": "^4",
+    "utf-8-validate": "^6"
+  },
+  "devDependencies": {
+    "@ts-ast-parser/core": "^0",
+    "@types/node": "^18",
+    "mocha": "^10",
+    "prettier": "^2",
+    "typescript": "^5"
+  }
+}

package/src/builder/index.mts

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import parseTypes from './transform/index.mjs';
+import RuntimeContext from './runtime-context.mjs';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const notEmpty = (what, name) => {
+  if (!what?.trim()) throw new Error(`${name} cannot be empty`);
+
+  return what;
+};
+
+export class Builder {
+  private data: any = {controller: './build/controller/.controller-for-types.mts'};
+
+  config(arg: any): Builder {
+    this.data.config = arg;
+    
+    return this;
+  }
+
+  options(arg: any): Builder {
+    this.data.options = arg;
+    
+    return this;
+  }
+
+  auth(arg: any): Builder {
+    this.data.auth = arg;
+    return this;
+  }
+
+  async build(): Promise<RuntimeContext> {
+    await this.parsePackageJson();
+    await this.discoverTypes();
+
+    // @ts-ignore
+    const Controller = (await import(__dirname + '/../../../../../build/controller/index.mjs')).default;
+
+    return new RuntimeContext(new Controller(), this.data);
+  }
+
+  private async parsePackageJson()
+  {
+    const data = this.data;
+    
+    const packageJson = JSON.parse(fs.readFileSync(__dirname + '/../../../../../package.json', {encoding: 'utf-8'}));
+    
+    notEmpty(data.id = packageJson.connectorId, 'id');
+    notEmpty(data.version= packageJson.version, 'version');
+  }
+
+  private async discoverTypes() {
+    notEmpty(this.data.controller, 'controller');
+
+    const content = fs.readFileSync(this.data.controller);
+    const {text, methods} = parseTypes(this.data.controller);
+
+    this.data.types   = text;
+    this.data.methods = methods;
+  }
+}

package/src/builder/runtime-context.mts

@@ -0,0 +1,56 @@
+import {AbstractController} from '../controller/index.mjs';
+import {Connector} from '../internal/index.cjs';
+
+export default class RuntimeContext {
+  constructor(private controller: AbstractController, private data: any) {}
+
+  async start(): Promise<void> {
+    const controller = this.controller;
+    
+    if (!(controller instanceof AbstractController)) throw new Error('the controller needs to extend AbstractController');
+    const data:any = this.data;
+    
+    const connector = new Connector({
+      id: data.id,
+      version: data.version,
+      name: `${data.id}/${data.version}`,
+    });
+
+    console.log('setting config', data.config)
+
+    const configuration = connector.configure().config(data.config || {});
+
+    const resolvers: any = {};
+    const methods: string[] = [...data.methods, '__endpoint', '__configQuery', '__default'];
+
+    methods.forEach((method) => {
+      resolvers[method] = async (args) => {
+        if (!methods.includes(method)) throw new Error(`${method} not found`);
+
+        return controller[method](args);
+      };
+    });
+    
+    configuration
+      
+      .types(data.types)
+      .resolvers(resolvers);
+    
+    
+    if (data.options?.endpoint?.enabled)
+    {
+      configuration.endpoint((arg) => controller.__endpoint(arg));
+    }
+      
+      configuration.main(async ({newTask, updateTask, config, oauth, getClient}) => {
+        try {
+          await controller._doStop();
+          await controller._doStart(config, oauth, newTask, updateTask, getClient);
+        } catch (e) {
+          console.log(e);
+        }
+      });
+
+    connector.run();
+  }
+}

package/src/builder/transform/index.mts

@@ -0,0 +1,87 @@
+import {parseFromFiles} from '@ts-ast-parser/core';
+
+const transform = (meta: any) => {
+  if (!meta?.length) throw new Error('metadata is empty');
+  meta = meta[0];
+
+  if (meta.getDeclarations()?.length !== 1) {
+    throw new Error('connector file needs to export default class');
+  }
+
+  const methods = {};
+  const decl = meta.getDeclarations()[0];
+
+  const members = decl.getMethods().filter((member: any) => {
+    return !(
+      member.isStatic() ||
+      member.isInherited() ||
+      member.getKind() !== 'Method' ||
+      member.getModifier() !== 'public' ||
+      member.getName().startsWith('_')
+    );
+  });
+
+  const text = members
+    .map((member: any) => {
+      methods[member.getName()] = true;
+
+      return member
+        .getSignatures()
+        .map((sig: any) => {
+          const docs = sig.getJSDoc().serialize() || [];
+          const desc = docs.find((what: any) => what.kind === 'description')?.value;
+
+          const paramDocs =
+            docs
+              .filter((what: any) => what.kind === 'param')
+              .map((what: any) => {
+                return ` * @param {${what.value.type}} ${what.value.name} - ${what.value.description || ''}`;
+              })
+              .join('\n') || ' *';
+
+          const params = sig
+            .getParameters()
+            .map((param: any) => {
+              const serialized = param.serialize();
+
+              switch (!!param.isNamed()) {
+                case true:
+                  const tmp = param
+                    .getNamedElements()
+                    .map((p) => {
+                      const defaultVal = p.default != null ? ' = ' + p.default : '';
+
+                      return `${p.name}${defaultVal}`;
+                    })
+                    .join('; ');
+                  return `{${tmp}}: ${param.getType().text}`;
+                case false:
+                  return `${param.getName()}: ${param.getType().text}`;
+              }
+            })
+            .join(', ');
+
+          const retVal = sig
+            .getReturnType()
+            .type.text.replace(/^Promise</, '')
+            .replace(/>$/, '');
+
+          return `
+/**
+ * ${desc || ''}
+ *
+${paramDocs}
+ **/    
+declare function ${member.getName()}(${params}): ${retVal};
+      `;
+        })
+        .join('\n');
+    })
+    .join('');
+
+  return {text, methods: Object.keys(methods)};
+};
+
+export default (path: string) => {
+  return transform(parseFromFiles([path]));
+};

package/src/controller/index.mts

@@ -0,0 +1,58 @@
+export abstract class AbstractController {
+  protected config;
+  protected client;
+
+  protected async start(): Promise<void> {}
+
+  protected async stop(): Promise<void> {}
+
+  protected configQuery(arg: any): Promise<any> {
+    return Promise.resolve({});
+  }
+
+  protected fallback(arg: any): Promise<any> {
+    throw new Error('method not found');
+  }
+
+  protected endpoint(arg: any): Promise<any> {
+    throw new Error('method not found');
+  }
+
+  protected async newTask(name: string, data: any): Promise<string> {
+    throw new Error('not implemented');
+  }
+
+  protected getClient({baseUrl}: {baseUrl: string}): Promise<any> {
+    throw new Error('not implemented');
+  }
+
+  protected async updateTask(name: string, data: any): Promise<string> {
+    throw new Error('not implemented');
+  }
+
+  async __endpoint(arg: any): Promise<any | null> {
+    return this.endpoint(arg);
+  }
+
+  async __configQuery(arg: any): Promise<any | null> {
+    return this.configQuery(arg);
+  }
+
+  async __default(arg: any): Promise<any | null> {
+    return this.fallback(arg);
+  }
+
+  async _doStart(config: any, client: any, newTask: any, updateTask: any, getClient: any): Promise<void> {
+    this.config = config;
+    this.client = client;
+    this.newTask = newTask;
+    this.updateTask = updateTask;
+    this.getClient = getClient;
+
+    await this.start();
+  }
+
+  async _doStop(): Promise<void> {
+    await this.stop();
+  }
+}

package/src/index.mts

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