Merge pull request #123 from tago-io/feat/new-analysis-services

Support to new Action Services through SDK

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tago-io/sdk",
-  "version": "11.2.7",
+  "version": "11.3.0",
   "description": "TagoIO SDK for JavaScript in the browser and Node.js",
   "author": "TagoIO Inc.",
   "homepage": "https://tago.io",

src/modules/Services/AWS-SQS.ts

@@ -0,0 +1,83 @@
+import TagoIOModule, { GenericModuleParams } from "../../common/TagoIOModule";
+import { Data } from "../../types";
+
+interface AWSCredentials {
+  /**
+   * AWS region, e.g., us-east-1
+   */
+  aws_region: string;
+  /**
+   * SQS queue URL
+   */
+  queue_url: string;
+  /**
+   * AWS Access Key ID
+   */
+  access_key_id: string;
+  /**
+   * AWS Secret Access Key
+   */
+  secret_access_key: string;
+}
+
+interface AWSSQSData {
+  /**
+   * SQS secret or AWS credentials
+   */
+  sqs_secret: string | AWSCredentials;
+  /**
+   * Message to be sent to SQS
+   */
+  data?: Partial<Data> | Partial<Data>[];
+}
+
+class AWSSQS extends TagoIOModule<GenericModuleParams> {
+  /**
+   * Send a message to Amazon SQS
+   *
+   * @param sqsData - The AWS SQS object containing all necessary information
+   * @returns A promise that resolves to a success message
+   *
+   * @remarks
+   * This method requires valid AWS credentials and SQS queue information.
+   * For enhanced security, it's strongly recommended to store these credentials
+   * using TagoIO Secrets rather than hardcoding them.
+   *
+   * @see {@link https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html} for AWS SQS documentation
+   * @see {@link https://help.tago.io/portal/en/kb/articles/secrets} for TagoIO Secrets usage
+   *
+   * @example
+   * ```typescript
+   * const environment = Utils.envToJson(context.environment);
+   * const sqsService = new Services({ token: context.token }).aws_sqs;
+   * const result = await sqsService.sendMessage({
+   *   sqs_secret: environment.AWS_SQS_TAGOIO_SECRET,
+   *   data: { variable: "temperature", value: 1 }
+   * });
+   * console.log(result);
+   * ```
+   */
+  public async sendMessage(sqsData: AWSSQSData): Promise<string> {
+    try {
+      if (typeof sqsData.sqs_secret === "string") {
+        JSON.parse(sqsData.sqs_secret);
+      }
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error("SQS Secret is not a valid JSON");
+      }
+    }
+
+    const dataList = Array.isArray(sqsData.data) ? sqsData.data : [sqsData.data];
+
+    const result = await this.doRequest<string>({
+      path: "/analysis/services/queue-sqs/send",
+      method: "POST",
+      body: { ...sqsData, dataList, batch_enabled: true, data: undefined },
+    });
+
+    return result;
+  }
+}
+
+export default AWSSQS;

src/modules/Services/Email.ts

@@ -35,15 +35,16 @@ interface TemplateOptions {
 
 interface EmailBase {
   /**
-   * E-mail address to be sent
-   *
-   * example: "myclien@tago.io"
+   * Recipient email address(es)
+   * @example
+   * "client@example.com"
+   * ["client1@example.com", "client2@example.com"]
    */
   to: string | string[];
   /**
-   * Name of origin
-   *
-   * example: "My Run"
+   * Sender name (optional)
+   * If not provided, the default sender name configured in TagoRUN will be used
+   * @example "My Application"
    */
   from?: string;
   /**
@@ -53,7 +54,8 @@ interface EmailBase {
    */
   subject: string;
   /**
-   * Attachment for the e-mail
+   * File attachment for the email (optional)
+   * @see AttachmentOptions
    */
   attachment?: AttachmentOptions;
 }
@@ -74,26 +76,31 @@ interface EmailHTML {
 
 interface EmailWithTemplate {
   /**
-   * E-mail address to be sent
-   *
-   * example: "myclien@tago.io"
+   * Recipient email address(es)
+   * @example
+   * "client@example.com"
+   * ["client1@example.com", "client2@example.com"]
    */
   to: string | string[];
   /**
-   * Name of origin
-   *
-   * example: "My Run"
+   * Sender name (optional)
+   * If not provided, the default sender name configured in TagoRUN will be used
+   * @example "My Application"
    */
   from?: string;
   /**
-   * Attachment for the e-mail
+   * File attachment for the email (optional)
+   * @see AttachmentOptions
    */
   attachment?: AttachmentOptions;
   /**
-   * Use TagoRUN E-Mail Template
+   * TagoRUN Email Template configuration
+   *
+   * Use this to send emails based on pre-defined templates in TagoRUN
    *
-   * Tip: If you use template together with attachment the
-   * back-end will generate a parameter called 'URL';
+   * @see TemplateOptions
+   * @note When using a template with an attachment, a $URL$ variable is automatically
+   *       generated and can be used in the template to reference the attachment
    */
   template?: TemplateOptions;
 }
@@ -133,3 +140,4 @@ class Email extends TagoIOModule<GenericModuleParams> {
 }
 
 export default Email;
+export type { EmailWithTemplate, EmailBase, AttachmentOptions, TemplateOptions, EmailHTML, EmailRawText };

src/modules/Services/SMTP.ts

@@ -0,0 +1,97 @@
+import TagoIOModule, { GenericModuleParams } from "../../common/TagoIOModule";
+import { EmailBase, EmailHTML, EmailRawText, EmailWithTemplate } from "./Email";
+
+type SMTPCredentials = {
+  smtp_secret: string | { smtp_server: string; smtp_port: number; username: string; password: string };
+};
+type SMTPEmailBase = EmailBase & SMTPCredentials;
+type SMTPEmailWithTemplate = EmailWithTemplate & SMTPCredentials;
+type SMTPEmailWithHTML = SMTPEmailBase & EmailHTML;
+type SMTPEmailWithRawText = SMTPEmailBase & EmailRawText;
+
+class SMTP extends TagoIOModule<GenericModuleParams> {
+  /**
+   * Send email using SMTP Integration
+   *
+   * @param email - The email object containing all necessary information
+   * @returns A promise that resolves to a success message
+   *
+   * @remarks
+   * This method requires either a TagoIO SMTP Secret or SMTP credentials.
+   * For enhanced security, it's strongly recommended to use TagoIO Secrets
+   * rather than hardcoding credentials.
+   *
+   * @see {@link https://help.tago.io/portal/en/kb/articles/secrets} for TagoIO Secrets usage
+   *
+   * @example
+   * ```typescript
+   * const environment = Utils.envToJson(context.environment);
+   * const emailService = new Services({ token: context.token }).smtp;
+   * const result = await emailService.send({
+   *   to: "client@company.com",
+   *   subject: "Reports",
+   *   message: "Hello client, it's your report",
+   *   smtp_secret: environment.SMTP_TAGOIO_SECRET
+   * });
+   * console.log(result);
+   * ```
+   *
+   * @example
+   * // Using an array of recipients
+   * const result = await emailService.send({
+   *   to: ["client1@company.com", "client2@company.com"],
+   *   subject: "Reports",
+   *   message: "Hello clients, it's your report",
+   *   smtp_secret: environment.SMTP_TAGOIO_SECRET
+   * });
+   *
+   * @example
+   * // Sending HTML content
+   * const result = await emailService.send({
+   *   to: "client@company.com",
+   *   subject: "Reports",
+   *   html: "<p>Hello client, it's your <strong>report</strong></p>",
+   *   smtp_secret: environment.SMTP_TAGOIO_SECRET
+   * });
+   *
+   * @example
+   * // Using a template
+   * const result = await emailService.send({
+   *   to: "client@company.com",
+   *   template: { name: "my_template" },
+   *   smtp_secret: environment.SMTP_TAGOIO_SECRET
+   * });
+   */
+  public async send(email: SMTPEmailWithRawText): Promise<string>;
+  public async send(email: SMTPEmailWithHTML): Promise<string>;
+  public async send(email: SMTPEmailWithTemplate): Promise<string>;
+  public async send(email: any): Promise<string> {
+    if (email.html && email.message) {
+      console.warn(new Error("HTML field will overwrite message field"));
+    }
+
+    try {
+      if (typeof email.smtp_secret === "string") {
+        JSON.parse(email.smtp_secret);
+      }
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error("SMTP Secret is not a valid JSON");
+      }
+    }
+
+    if (Array.isArray(email.to)) {
+      email.to = email.to.join(",");
+    }
+
+    const result = await this.doRequest<string>({
+      path: "/analysis/services/email-smtp/send",
+      method: "POST",
+      body: email,
+    });
+
+    return result;
+  }
+}
+
+export default SMTP;

src/modules/Services/Sendgrid.ts

@@ -0,0 +1,90 @@
+import TagoIOModule, { GenericModuleParams } from "../../common/TagoIOModule";
+import { EmailBase, EmailHTML, EmailRawText, EmailWithTemplate } from "./Email";
+
+interface SendgridCredentials {
+  sendgrid_api_key: string;
+}
+type SendgridEmailBase = EmailBase & SendgridCredentials;
+type SendgridEmailWithTemplate = EmailWithTemplate & SendgridCredentials;
+type SendgridEmailWithHTML = SendgridEmailBase & EmailHTML;
+type SendgridEmailWithRawText = SendgridEmailBase & EmailRawText;
+
+class Sendgrid extends TagoIOModule<GenericModuleParams> {
+  /**
+   * Send email using Sendgrid integration
+   *
+   * @param email - The email object containing all necessary information
+   * @returns A promise that resolves to a success message
+   *
+   * @remarks
+   * This method requires Sendgrid API key.
+   * For enhanced security, it's strongly recommended to use TagoIO Secrets
+   * rather than hardcoding credentials.
+   *
+   * @see {@link https://help.tago.io/portal/en/kb/articles/secrets} for TagoIO Secrets usage
+   *
+   * @example
+   * ```typescript
+   * const sendgridService = new Services({ token: context.token }).sendgrid;
+   * const result = await sendgridService.send({
+   *   from: "sender@company.com"
+   *   to: "client@company.com",
+   *   subject: "Reports",
+   *   message: "Hello client, it's your report",
+   *   sendgrid_api_key: "YOUR_SENDGRID_API_KEY"
+   * });
+   * console.log(result);
+   * ```
+   *
+   * @example
+   * // Using an array of recipients
+   * const result = await sendgridService.send({
+   *   from: "sender@company.com"
+   *   to: ["client1@company.com", "client2@company.com"],
+   *   subject: "Reports",
+   *   message: "Hello clients, it's your report",
+   *   sendgrid_api_key: "YOUR_SENDGRID_API_KEY"
+   * });
+   *
+   * @example
+   * // Sending HTML content
+   * const result = await sendgridService.send({
+   *   from: "sender@company.com"
+   *   to: "client@company.com",
+   *   subject: "Reports",
+   *   html: "<p>Hello client, it's your <strong>report</strong></p>",
+   *   sendgrid_api_key: "YOUR_SENDGRID_API_KEY"
+   * });
+   *
+   * @example
+   * // Using a template
+   * const result = await sendgridService.send({
+   *   from: "sender@company.com"
+   *   to: "client@company.com",
+   *   template: { name: "my_template" },
+   *   sendgrid_api_key: "YOUR_SENDGRID_API_KEY"
+   * });
+   */
+  public async send(email: SendgridEmailWithRawText): Promise<string>;
+  public async send(email: SendgridEmailWithHTML): Promise<string>;
+  public async send(email: SendgridEmailWithTemplate): Promise<string>;
+  public async send(email: any): Promise<string> {
+    if (email.html && email.message) {
+      console.warn(new Error("HTML field will overwrite message field"));
+    }
+
+    if (Array.isArray(email.to)) {
+      email.to = email.to.join(",");
+    }
+
+    const result = await this.doRequest<string>({
+      path: "/analysis/services/email-sendgrid/send",
+      method: "POST",
+      body: email,
+    });
+
+    return result;
+  }
+}
+
+export default Sendgrid;