@aloma.io/integration-sdk 3.8.2 → 3.8.3

package/build/builder/index.d.mts

@@ -1,17 +1,70 @@
 import "dotenv/config";
 import RuntimeContext from "./runtime-context.mjs";
 export declare const TARGET_DIR: string;
+/**
+ * a configuration field
+ */
 export type ConfigField = {
+    /**
+     * the name of the field
+     */
     name: string;
+    /**
+     * a description about the field
+     *
+     * supports markdown
+     */
     description?: string;
+    /**
+     * a placeholder for the field
+     */
     placeholder?: string;
-    type: "multiline" | "text" | "number" | "boolean";
+    /**
+     * the type of the field
+     */
+    type: 
+    /**
+     * a multiline text field
+     */
+    "multiline"
+    /**
+     * a single line text field
+     */
+     | "text"
+    /**
+     * a number field
+     */
+     | "number"
+    /**
+     * a boolean text field
+     */
+     | "boolean";
+    /**
+     * if true, the field is optional, otherwise a value is required
+     */
     optional?: boolean;
+    /**
+     * if true, the field will NOT be encrypted
+     */
     plain?: boolean;
 } | undefined;
+/**
+ * connector configuration
+ */
 declare type Config = {
+    /**
+     * a short summary about the connector
+     */
     summary?: string;
+    /**
+     * a longer description about the connector, including further reference or setup instructions
+     *
+     * supports markdown
+     */
     description?: string;
+    /**
+     * fields that can be configured by the user in the ui
+     */
     fields?: {
         authorizationURL?: ConfigField;
         tokenURL?: ConfigField;
@@ -21,40 +74,105 @@ declare type Config = {
         [key: string]: ConfigField;
     };
 };
+/**
+ * connector options
+ */
 declare type Options = {
+    /**
+     * if an endpoint is enabled for sending data to the connector
+     */
     endpoint?: {
+        /**
+         * if the endpoint is enabled
+         */
         enabled: boolean;
+        /**
+         * if true, the endpoint is required to operate the connector and not visible in the ui
+         */
         required?: boolean;
     };
 };
+/**
+ * OAuth configuration
+ *
+ * @see https://oauth.net/2/
+ */
 declare type OAuth = {
     /**
-     * preferred via process.env.OAUTH_CLIENT_ID
+     * oauth2 client id
+     *
+     * NOTE: preferred via process.env.OAUTH_CLIENT_ID
      */
     clientId?: string;
     /**
-     * preferred via process.env.OAUTH_CLIENT_SECRET
+     * oauth2 client secret
+     *
+     * NOTE: preferred via process.env.OAUTH_CLIENT_SECRET
      */
     clientSecret?: string;
     /**
      * @example https://example.com/oauth2/v2/auth?client_id={{clientId}}&redirect_uri={{redirectURI}}&scope={{scope}}&response_type=code
      */
     authorizationURL?: string;
+    /**
+     * oauth2 token url
+     * @example https://example.com/oauth2/v2/token
+     */
     tokenURL?: string;
+    /**
+     * oauth2 scope
+     * @example openid offline_access
+     */
     scope?: string;
+    /**
+     * milliseconds to automatically refresh the token, if a refresh_token is available
+     *
+    * @default 4 * 60 * 60 * 1000 // 4 hours
+     */
     tokenRefreshPeriod?: number;
+    /**
+     * if true, the clientId and clientSecret are sent to the tokenURL as basic auth header
+     */
     useAuthHeader?: boolean;
+    /**
+     * additional token arguments
+     */
     additionalTokenArgs?: {
+        /**
+         * oauth2 grant type
+         */
         grant_type?: string;
     };
 };
+/**
+ * a builder for creating a connector
+ */
 export declare class Builder {
     private data;
+    /**
+     * configure properties of the connector
+     * @param arg
+     * @returns
+     */
     config(arg: Config): Builder;
+    /**
+     * configure additional options of the connector
+     * @param arg
+     * @returns
+     */
     options(arg: Options): Builder;
+    /**
+     * configure the authentication of the connector
+     * @param arg
+     * @returns
+     */
     auth(arg: {
         oauth?: OAuth;
     }): Builder;
+    /**
+     * build the connector
+     * @returns
+     */
     build(): Promise<RuntimeContext>;
     private checkIcon;
     private loadDescriptor;

package/build/builder/index.mjs

@@ -7,22 +7,44 @@ import RuntimeContext from "./runtime-context.mjs";
 const DIR_OFFSET = "/../../../../../";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const TARGET_DIR = `${__dirname}${DIR_OFFSET}`;
+/**
+ * a builder for creating a connector
+ */
 export class Builder {
     data = {
         controller: "./build/.controller.json",
     };
+    /**
+     * configure properties of the connector
+     * @param arg
+     * @returns
+     */
     config(arg) {
         this.data.config = arg;
         return this;
     }
+    /**
+     * configure additional options of the connector
+     * @param arg
+     * @returns
+     */
     options(arg) {
         this.data.options = arg;
         return this;
     }
+    /**
+     * configure the authentication of the connector
+     * @param arg
+     * @returns
+     */
     auth(arg) {
         this.data.auth = arg;
         return this;
     }
+    /**
+     * build the connector
+     * @returns
+     */
     async build() {
         await this.loadDescriptor();
         await this.checkIcon();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloma.io/integration-sdk",
-  "version": "3.8.2",
+  "version": "3.8.3",
   "description": "",
   "author": "aloma.io",
   "license": "Apache-2.0",

package/src/builder/index.mts

@@ -11,18 +11,72 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export const TARGET_DIR = `${__dirname}${DIR_OFFSET}`;
 
+/**
+ * a configuration field
+ */
 export type ConfigField = {
+  /**
+   * the name of the field
+   */
   name: string;
+  /**
+   * a description about the field
+   *
+   * supports markdown
+   */
   description?: string;
+  /**
+   * a placeholder for the field
+   */
   placeholder?: string;
-  type: "multiline" | "text" | "number" | "boolean";
+  /**
+   * the type of the field
+   */
+  type:
+  /**
+   * a multiline text field
+   */
+  "multiline"
+  /**
+   * a single line text field
+   */
+  | "text"
+  /**
+   * a number field
+   */
+  | "number"
+  /**
+   * a boolean text field
+   */
+  | "boolean";
+  /**
+   * if true, the field is optional, otherwise a value is required
+   */
   optional?: boolean;
+  /**
+   * if true, the field will NOT be encrypted
+   */
   plain?: boolean;
 } | undefined;
 
+/**
+ * connector configuration
+ */
 declare type Config = {
+  /**
+   * a short summary about the connector
+   */
   summary?: string;
+  /**
+   * a longer description about the connector, including further reference or setup instructions
+   *
+   * supports markdown
+   */
   description?: string;
+
+  /**
+   * fields that can be configured by the user in the ui
+   */
   fields?: {
     authorizationURL?: ConfigField;
     tokenURL?: ConfigField;
@@ -33,17 +87,42 @@ declare type Config = {
   };
 };
 
+/**
+ * connector options
+ */
 declare type Options = {
-  endpoint?: {enabled: boolean, required?: boolean};
+  /**
+   * if an endpoint is enabled for sending data to the connector
+   */
+  endpoint?: {
+    /**
+     * if the endpoint is enabled
+     */
+    enabled: boolean,
+    /**
+     * if true, the endpoint is required to operate the connector and not visible in the ui
+     */
+    required?: boolean
+  };
 };
 
+/**
+ * OAuth configuration
+ *
+ * @see https://oauth.net/2/
+ */
 declare type OAuth = {
   /**
-   * preferred via process.env.OAUTH_CLIENT_ID
+   * oauth2 client id
+   *
+   * NOTE: preferred via process.env.OAUTH_CLIENT_ID
    */
   clientId?: string;
+
   /**
-   * preferred via process.env.OAUTH_CLIENT_SECRET
+   * oauth2 client secret
+   *
+   * NOTE: preferred via process.env.OAUTH_CLIENT_SECRET
    */
   clientSecret?: string;
 
@@ -51,35 +130,85 @@ declare type OAuth = {
    * @example https://example.com/oauth2/v2/auth?client_id={{clientId}}&redirect_uri={{redirectURI}}&scope={{scope}}&response_type=code
    */
   authorizationURL?: string;
+
+  /**
+   * oauth2 token url
+   * @example https://example.com/oauth2/v2/token
+   */
   tokenURL?: string;
+  /**
+   * oauth2 scope
+   * @example openid offline_access
+   */
   scope?: string;
+
+  /**
+   * milliseconds to automatically refresh the token, if a refresh_token is available
+   *
+  * @default 4 * 60 * 60 * 1000 // 4 hours
+   */
   tokenRefreshPeriod?: number;
+
+  /**
+   * if true, the clientId and clientSecret are sent to the tokenURL as basic auth header
+   */
   useAuthHeader?: boolean;
-  additionalTokenArgs?: {grant_type?: string}
+
+  /**
+   * additional token arguments
+   */
+  additionalTokenArgs?: {
+    /**
+     * oauth2 grant type
+     */
+    grant_type?: string
+  }
 };
 
+/**
+ * a builder for creating a connector
+ */
 export class Builder {
   private data: any = {
     controller: "./build/.controller.json",
   };
 
+  /**
+   * configure properties of the connector
+   * @param arg
+   * @returns
+   */
   config(arg: Config): Builder {
     this.data.config = arg;
 
     return this;
   }
 
+  /**
+   * configure additional options of the connector
+   * @param arg
+   * @returns
+   */
   options(arg: Options): Builder {
     this.data.options = arg;
 
     return this;
   }
 
+  /**
+   * configure the authentication of the connector
+   * @param arg
+   * @returns
+   */
   auth(arg: {oauth?: OAuth}): Builder {
     this.data.auth = arg;
     return this;
   }
 
+  /**
+   * build the connector
+   * @returns
+   */
   async build(): Promise<RuntimeContext> {
     await this.loadDescriptor();
     await this.checkIcon();