feat(providers): add Maqsam WhatsApp chat provider

apps/api/src/app/integrations/dtos/credentials.dto.ts

@@ -236,4 +236,9 @@ export class CredentialsDto implements ICredentials {
   @IsOptional()
   @IsString()
   AppIOBaseUrl?: string;
+
+  @ApiPropertyOptional()
+  @IsString()
+  @IsOptional()
+  accessSecret?: string;
 }

apps/worker/src/app/workflow/usecases/send-message/send-message-chat.usecase.ts

@@ -297,15 +297,23 @@ export class SendMessageChat extends SendMessageBase {
         Object.values(ChatProviderIdEnum).includes(chan.providerId as ChatProviderIdEnum)
       ) || [];
 
-    // Add WhatsApp Business if subscriber has phone
+    // Add WhatsApp APIs if subscriber has phone
     if (subscriber.phone) {
-      // @ts-expect-error - Adding WhatsApp channel without _integrationId
+      // @ts-expect-error - Adding WhatsApp Business channel without _integrationId
       chatChannels.push({
         providerId: ChatProviderIdEnum.WhatsAppBusiness,
         credentials: {
           phoneNumber: subscriber.phone,
         },
       });
+
+      // @ts-expect-error - Adding Maqsam WhatsApp channel without _integrationId
+      chatChannels.push({
+        providerId: ChatProviderIdEnum.MaqsamWhatsApp,
+        credentials: {
+          phoneNumber: subscriber.phone,
+        },
+      })
     }
 
     return chatChannels;

libs/application-generic/src/factories/chat/chat.factory.ts

@@ -3,6 +3,7 @@ import { ChatWebhookHandler } from './handlers/chat-webhook.handler';
 import { DiscordHandler } from './handlers/discord.handler';
 import { GetstreamChatHandler } from './handlers/getstream.handler';
 import { GrafanaOnCallHandler } from './handlers/grafana-on-call.handler';
+import { MaqsamWhatsAppHandler } from './handlers/maqsam.handler';
 import { MattermostHandler } from './handlers/mattermost.handler';
 import { MSTeamsHandler } from './handlers/msteams.handler';
 import { NovuSlackHandler } from './handlers/novu-slack.handler';
@@ -27,6 +28,7 @@ export class ChatFactory implements IChatFactory {
     new GetstreamChatHandler(),
     new RocketChatHandler(),
     new WhatsAppBusinessHandler(),
+    new MaqsamWhatsAppHandler(),
   ];
 
   getHandler(integration: Pick<IntegrationEntity, 'credentials' | 'channel' | 'providerId' | 'configurations'>) {

libs/application-generic/src/factories/chat/handlers/maqsam.handler.ts

@@ -0,0 +1,15 @@
+import { MaqsamWhatsAppProvider } from '@novu/providers';
+import { ChannelTypeEnum, ChatProviderIdEnum, ICredentials } from '@novu/shared';
+import { BaseChatHandler } from './base.handler';
+
+export class MaqsamWhatsAppHandler extends BaseChatHandler {
+  constructor() {
+    super(ChatProviderIdEnum.MaqsamWhatsApp, ChannelTypeEnum.CHAT);
+  }
+
+  buildProvider(credentials: ICredentials) {
+    const config: { accessKey: string, accessSecret: string } = { accessKey: credentials.accessKey, accessSecret: credentials.accessSecret };
+
+    this.provider = new MaqsamWhatsAppProvider(config);
+  }
+}

libs/dal/src/repositories/integration/integration.schema.ts

@@ -70,6 +70,7 @@ const integrationSchema = new Schema<IntegrationDBModel>(
       AppIOSubscriptionId: Schema.Types.String,
       AppIOBearerToken: Schema.Types.String,
       AppIOOriginalSignature: Schema.Types.String,
+      accessSecret: Schema.Types.String,
     },
     configurations: {
       inboundWebhookEnabled: Schema.Types.Boolean,

libs/internal-sdk/src/models/components/providersidenum.ts

@@ -87,6 +87,7 @@ export const ProvidersIdEnum = {
   WhatsappBusiness: "whatsapp-business",
   ChatWebhook: "chat-webhook",
   NovuSlack: "novu-slack",
+  MaqsamWhatsApp: 'maqsam-whatsapp',
 } as const;
 /**
  * Provider ID of the job

packages/framework/src/schemas/providers/chat/index.ts

@@ -15,4 +15,5 @@ export const chatProviderSchemas = {
   slack: slackProviderSchemas,
   'whatsapp-business': genericProviderSchemas,
   zulip: genericProviderSchemas,
+  'maqsam-whatsapp': genericProviderSchemas,
 } as const satisfies Record<ChatProviderIdEnum, { output: JsonSchema }>;

packages/framework/src/shared.ts

@@ -175,6 +175,7 @@ export enum ChatProviderIdEnum {
   RocketChat = 'rocket-chat',
   WhatsAppBusiness = 'whatsapp-business',
   ChatWebhook = 'chat-webhook',
+  MaqsamWhatsApp = 'maqsam-whatsapp',
 }
 
 export enum PushProviderIdEnum {

packages/providers/src/lib/chat/index.ts

@@ -2,6 +2,7 @@ export * from './chat-webhook/chat-webhook.provider';
 export * from './discord/discord.provider';
 export * from './getstream/getstream.provider';
 export * from './grafana-on-call/grafana-on-call.provider';
+export * from './maqsam-whatsapp/maqsam-whatsapp.provider';
 export * from './mattermost/mattermost.provider';
 export * from './msTeams/msTeams.provider';
 export * from './rocket-chat/rocket-chat.provider';

packages/providers/src/lib/chat/maqsam-whatsapp/maqsam-whatsapp.provider.spec.ts

@@ -0,0 +1,140 @@
+import { IChatOptions } from '@novu/stateless';
+import { nanoid } from 'nanoid';
+import { expect, test } from 'vitest';
+import { axiosSpy } from '../../../utils/test/spy-axios';
+import { MaqsamWhatsAppProvider } from './maqsam-whatsapp.provider';
+
+const mockProviderConfig = {
+  accessKey: 'my-access-key',
+  accessSecret: 'my-access-secret',
+};
+
+const buildResponse = (messageId: string) => {
+  return {
+    data: {
+      message_id: messageId,
+      message_status: 'submitted',
+    },
+  };
+};
+
+test('should trigger maqsam library correctly with template message', async () => {
+  const messageId = nanoid();
+
+  const { mockPost, axiosMockSpy } = axiosSpy(buildResponse(messageId));
+
+  const provider = new MaqsamWhatsAppProvider(mockProviderConfig);
+
+  const options: IChatOptions = {
+    phoneNumber: '+111111111',
+    content: 'Template message',
+    customData: {
+      templateId: '123',
+      templateVariables: {
+        name: 'John',
+        company: 'Acme',
+      },
+    },
+  };
+
+  const res = await provider.sendMessage(options);
+
+  expect(mockPost).toHaveBeenCalled();
+  expect(mockPost).toHaveBeenCalledWith('https://api.maqsam.com/v2/whatsapp/messages/send_message', {
+    RecipientPhone: options.phoneNumber,
+    TemplateId: options.customData?.templateId,
+    TemplateVariables: options.customData?.templateVariables,
+  });
+
+  const token = Buffer.from(`${mockProviderConfig.accessKey}:${mockProviderConfig.accessSecret}`).toString('base64');
+
+  expect(axiosMockSpy).toHaveBeenCalledWith({
+    headers: {
+      Authorization: `Basic ${token}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+  });
+
+  expect(res.id).toBe(messageId);
+});
+
+test('should trigger maqsam library correctly with template message with _passthrough', async () => {
+  const messageId = nanoid();
+
+  const { mockPost, axiosMockSpy } = axiosSpy(buildResponse(messageId));
+
+  const provider = new MaqsamWhatsAppProvider(mockProviderConfig);
+
+  const options: IChatOptions = {
+    phoneNumber: '+111111111',
+    content: 'Template message',
+    customData: {
+      templateId: '123',
+      templateVariables: {
+        name: 'John',
+        company: 'Acme',
+      },
+    },
+  };
+
+  const res = await provider.sendMessage(options, {
+    _passthrough: {
+      query: {
+        RecipientPhone: '+111111111',
+        TemplateId: '123',
+        TemplateVariables: JSON.stringify({
+          name: 'John',
+          company: 'Acme',
+        }),
+      },
+    },
+  });
+
+  expect(mockPost).toHaveBeenCalled();
+  expect(mockPost).toHaveBeenCalledWith('https://api.maqsam.com/v2/whatsapp/messages/send_message', {
+      RecipientPhone: '+111111111',
+      TemplateId: '123',
+      TemplateVariables: {
+        name: 'John',
+        company: 'Acme',
+      },
+  });
+
+  const token = Buffer.from(`${mockProviderConfig.accessKey}:${mockProviderConfig.accessSecret}`).toString('base64');
+
+  expect(axiosMockSpy).toHaveBeenCalledWith({
+    headers: {
+      Authorization: `Basic ${token}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+  });
+
+  expect(res.id).toBe(messageId);
+});
+
+test('should throw error when message status is not submitted', async () => {
+  const messageId = nanoid();
+
+  axiosSpy({
+    data: {
+      message_id: messageId,
+      message_status: 'failed',
+    },
+  });
+
+  const provider = new MaqsamWhatsAppProvider(mockProviderConfig);
+
+  const options: IChatOptions = {
+    phoneNumber: '+111111111',
+    content: 'Template message',
+    customData: {
+      templateId: '123',
+      templateVariables: {
+        name: 'John',
+        company: 'Acme',
+      },
+    },
+  };
+
+  await expect(provider.sendMessage(options)).rejects.toThrow('Maqsam Chat failed:');
+});

packages/providers/src/lib/chat/maqsam-whatsapp/maqsam-whatsapp.provider.ts

@@ -0,0 +1,64 @@
+import {
+  ChannelTypeEnum,
+  IChatOptions,
+  IChatProvider,
+  ISendMessageSuccessResponse,
+  PhoneData,
+} from "@novu/stateless";
+import Axios, { AxiosInstance } from 'axios';
+import { BaseProvider, CasingEnum } from "../../../base.provider";
+import { WithPassthrough } from "../../../utils/types";
+import { ISendMessageFailureRes, ISendMessageRes } from "./types/maqsam-whatsapp.types";
+
+export class MaqsamWhatsAppProvider extends BaseProvider implements IChatProvider {
+  id = "maqsam-whatsapp";
+  channelType = ChannelTypeEnum.CHAT as ChannelTypeEnum.CHAT;
+  protected casing: CasingEnum = CasingEnum.CAMEL_CASE;
+
+  private readonly axiosClient: AxiosInstance;
+  private readonly baseUrl = 'https://api.maqsam.com/v2/whatsapp/messages/send_message';
+
+  constructor(private config: {
+    accessKey: string;
+    accessSecret: string;
+  }) {
+    super();
+
+    const token = Buffer.from(`${this.config.accessKey}:${this.config.accessSecret}`).toString('base64');
+
+    this.axiosClient = Axios.create({
+          headers: {
+            Authorization: `Basic ${token}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
+          },
+        });
+  }
+
+  private defineMessagePayload(options: IChatOptions) {
+    return {
+      RecipientPhone: (options.channelData as PhoneData).endpoint.phoneNumber,
+      TemplateId: options.customData?.templateId,
+      TemplateVariables: options.customData?.templateVariables,
+    }
+  }
+
+  async sendMessage(
+    options: IChatOptions,
+    bridgeProviderData: WithPassthrough<Record<string, unknown>> = {},
+  ): Promise<ISendMessageSuccessResponse> {
+    const payload = this.transform(bridgeProviderData, this.defineMessagePayload(options));
+
+    const { data } = await this.axiosClient.post<ISendMessageRes | ISendMessageFailureRes>(this.baseUrl, 
+      payload.body,
+    );
+
+    if ('conversationId' in data && data.conversationId) {
+      return {
+        id: data.conversationId,
+        date: new Date().toISOString(),
+      };
+    }
+
+    throw new Error(`Maqsam Chat failed: ${JSON.stringify(data || {})}`);
+  }
+}

packages/providers/src/lib/chat/maqsam-whatsapp/types/maqsam-whatsapp.types.ts

@@ -0,0 +1,10 @@
+export interface ISendMessageRes {
+  conversationId: string;
+  messageStatus: string;
+  result: string;
+}
+
+export interface ISendMessageFailureRes {
+  error: string
+  message: string
+}

packages/shared/src/consts/providers/channels/chat.ts

@@ -4,6 +4,7 @@ import {
   chatWebhookConfig,
   getstreamConfig,
   grafanaOnCallConfig,
+  maqsamWhatsAppChatConfig,
   msTeamsConfig,
   rocketChatConfig,
   slackConfigLegacy,
@@ -109,4 +110,13 @@ export const chatProviders: IProviderConfig[] = [
     logoFileName: { light: 'chat-webhook.svg', dark: 'chat-webhook.svg' },
     betaVersion: true,
   },
+  {
+    id: ChatProviderIdEnum.MaqsamWhatsApp,
+    displayName: 'Maqsam WhatsApp',
+    channel: ChannelTypeEnum.CHAT,
+    credentials: maqsamWhatsAppChatConfig,
+    docReference: 'https://portal.maqsam.com/docs/v2/whatsapp',
+    logoFileName: { light: 'maqsam-whatsapp.svg', dark: 'maqsam-whatsapp.svg' },
+    betaVersion: true,
+  }
 ];

packages/shared/src/consts/providers/credentials/provider-credentials.ts

@@ -926,6 +926,21 @@ export const maqsamConfig: IConfigCredential[] = [
   ...smsConfigBase,
 ];
 
+export const maqsamWhatsAppChatConfig: IConfigCredential[] = [
+  {
+    key: CredentialsKeyEnum.AccessKey,
+    displayName: 'Access Key',
+    type: 'string',
+    required: true,
+  },
+  {
+    key: CredentialsKeyEnum.AccessSecret,
+    displayName: 'Access Secret',
+    type: 'string',
+    required: true,
+  }
+];
+
 export const smsCentralConfig: IConfigCredential[] = [
   {
     key: CredentialsKeyEnum.User,

packages/shared/src/consts/providers/credentials/secure-credentials.ts

@@ -7,4 +7,5 @@ export const secureCredentials: CredentialsKeyEnum[] = [
   CredentialsKeyEnum.Token,
   CredentialsKeyEnum.Password,
   CredentialsKeyEnum.ServiceAccount,
+  CredentialsKeyEnum.AccessSecret
 ];

packages/shared/src/entities/integration/credential.interface.ts

@@ -53,4 +53,5 @@ export interface ICredentials {
   AppIOOriginalSignature?: string;
   servicePlanId?: string;
   tenantId?: string;
+  accessSecret?: string;
 }