[Dotdigital] Add actions for Add Contact to List, Remove Contact From List, and Enrol Contact

packages/destination-actions/src/destinations/dotdigital/__tests__/index.test.ts

@@ -0,0 +1,43 @@
+import nock from 'nock'
+import { createTestIntegration } from '@segment/actions-core'
+import Definition from '../index'
+
+const testDestination = createTestIntegration(Definition)
+
+describe('Dotdigital', () => {
+  describe('testAuthentication', () => {
+    it('should validate valid api key', async () => {
+      nock('https://r1-api.dotdigital.com')
+        .get('/v2/data-fields/')
+        .matchHeader('Authorization', 'Basic YXBpX3VzZXJuYW1lOmFwaV9wYXNzd29yZA==')
+        .reply(200)
+
+      const settings = {
+        api_host: 'https://r1-api.dotdigital.com',
+        username: 'api_username',
+        password: 'api_password'
+      }
+      await expect(testDestination.testAuthentication(settings)).resolves.not.toThrowError()
+      expect(nock.isDone()).toBe(true)
+    })
+
+    it('should not validate invalid api key', async () => {
+      nock('https://r1-api.dotdigital.com')
+        .get('/v2/data-fields/')
+        .matchHeader('Authorization', 'Basic YXBpX3VzZXJuYW1lOmFwaV9wYXNzd29yZA==')
+        .reply(401, {
+          message:
+            "Authorization has been denied for this request."
+        })
+
+      const settings = {
+        api_host: 'https://r1-api.dotdigital.com',
+        username: 'api_username',
+        password: 'api_password'
+      }
+
+      await expect(testDestination.testAuthentication(settings)).rejects.toThrowError()
+      expect(nock.isDone()).toBe(true)
+    })
+  })
+})

packages/destination-actions/src/destinations/dotdigital/addContactToList/__tests__/index.test.ts

@@ -0,0 +1,76 @@
+import nock from 'nock'
+import { createTestEvent, createTestIntegration } from '@segment/actions-core'
+import Destination from '../../index'
+
+const testDestination = createTestIntegration(Destination)
+
+export const settings = {
+  api_host: 'https://r1-api.dotdigital.com',
+  username: 'api_username',
+  password: 'api_password'
+}
+
+describe('Add Contact To List', () => {
+  it('should add contact to list with email identifier', async () => {
+    // Mock upsertContact function
+    nock(settings.api_host)
+      .patch(`/contacts/v3/email/[email protected]?merge-option=overwrite`)
+      .reply(200, { contactId: 123 })
+
+    const event = createTestEvent({
+      type: 'identify',
+      context: {
+        traits: {
+          email: '[email protected]'
+        }
+      }
+    })
+
+    const mapping = {
+      listId: 123456,
+      channelIdentifier: 'email',
+      emailIdentifier: {
+        '@path': '$.context.traits.email'
+      }
+    }
+    await expect(
+      testDestination.testAction('addContactToList', {
+        event,
+        mapping,
+        settings
+      })
+    ).resolves.not.toThrowError()
+  })
+
+  it('should add contact to list with mobile number identifier', async () => {
+    // Mock upsertContact  function
+    nock(settings.api_host)
+      .patch(`/contacts/v3/mobile-number/1234567890?merge-option=overwrite`)
+      .reply(200, { contactId: 123 })
+
+    const event = createTestEvent({
+      type: 'identify',
+      context: {
+        traits: {
+          phone: '1234567890'
+        }
+      }
+    })
+
+    const mapping = {
+      listId: 123456,
+      channelIdentifier: 'mobile-number',
+      mobileNumberIdentifier: {
+        '@path': '$.context.traits.phone'
+      }
+    }
+
+    await expect(
+      testDestination.testAction('addContactToList', {
+        event,
+        mapping,
+        settings
+      })
+    ).resolves.not.toThrowError()
+  })
+})

packages/destination-actions/src/destinations/dotdigital/addContactToList/index.ts

@@ -0,0 +1,62 @@
+import { ActionDefinition, DynamicFieldResponse, RequestClient, PayloadValidationError } from '@segment/actions-core'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { DotdigitalContactApi, DotdigitalListsApi, DotdigitalDataFieldsApi } from '../api'
+import { contactIdentifier } from '../input-fields'
+
+const action: ActionDefinition<Settings, Payload> = {
+  title: 'Add Contact to List',
+  description: '',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    ...contactIdentifier,
+    listId: {
+      label: 'List',
+      description: `The list to add the contact to.`,
+      type: 'number',
+      required: true,
+      dynamic: true
+    },
+    dataFields: {
+      label: 'Data Fields',
+      description: `An object containing key/value pairs for any data fields assigned to this contact, custom data fields needs to exists in Dotdigital.`,
+      type: 'object',
+      required: false,
+      defaultObjectUI: 'keyvalue:only',
+      additionalProperties: false,
+      dynamic: true
+    }
+  },
+  dynamicFields: {
+    listId: async (request: RequestClient, { settings }): Promise<DynamicFieldResponse> => {
+      return new DotdigitalListsApi(settings, request).getLists()
+    },
+    dataFields: {
+      __keys__: async (request, { settings }) => {
+        return new DotdigitalDataFieldsApi(settings, request).getDataFields()
+      }
+    }
+  },
+
+  perform: async (request, { settings, payload }) => {
+    const contactApi = new DotdigitalContactApi(settings, request)
+    const dataFieldsApi = new DotdigitalDataFieldsApi(settings, request)
+    const { channelIdentifier, emailIdentifier, mobileNumberIdentifier, listId } = payload
+    const identifierValue = channelIdentifier === 'email' ? emailIdentifier : mobileNumberIdentifier
+
+    if (!listId) {
+      throw new PayloadValidationError('List id is required')
+    }
+
+    if (!identifierValue) {
+      throw new PayloadValidationError(
+        channelIdentifier === 'email' ? 'Email address is required' : 'Mobile number is required'
+      )
+    }
+
+    await dataFieldsApi.validateDataFields(payload)
+    return contactApi.upsertContact(payload)
+  }
+}
+
+export default action

packages/destination-actions/src/destinations/dotdigital/api/dotdigital-api.ts

@@ -0,0 +1,89 @@
+import { APIError, RequestClient, ModifiedResponse } from '@segment/actions-core'
+import type { Settings } from '../generated-types'
+
+abstract class DotdigitalApi {
+  private readonly apiUrl: string
+  private readonly client: RequestClient
+
+  protected constructor(settings: Settings, client: RequestClient) {
+    this.apiUrl = settings.api_host
+    this.client = client
+  }
+
+  /**
+   * Generic GET method
+   * @param endpoint - The API endpoint to call.
+   * @param params - An object containing query parameters.
+   *
+   * @returns A promise that resolves to a DecoratedResponse.
+   */
+  protected async get<T>(endpoint: string, params?: T): Promise<ModifiedResponse> {
+    try {
+      const url = new URL(`${this.apiUrl}${endpoint}`)
+      if (params) {
+        url.search = new URLSearchParams(params).toString();
+      }
+      return await this.client(`${url}`, {
+        method: 'GET'
+      })
+    } catch (error) {
+      throw (error as APIError) ?? 'GET request failed'
+    }
+  }
+
+  /**
+   * Generic POST method
+   * @param endpoint - The API endpoint to call.
+   * @param data - The data to send in the client body.
+   *
+   * @returns A promise that resolves to a DecoratedResponse.
+   */
+  protected async post<T>(endpoint: string, data: T): Promise<ModifiedResponse> {
+    try {
+      return await this.client(`${this.apiUrl}${endpoint}`, {
+        method: 'POST',
+        body: JSON.stringify(data),
+        headers: { 'Content-Type': 'application/json' }
+      })
+    } catch (error) {
+      throw (error as APIError) ?? 'POST request failed'
+    }
+  }
+
+  /**
+   * Generic DELETE method
+   * @param endpoint - The API endpoint to call.
+   *
+   * @returns A promise that resolves to a DecoratedResponse.
+   */
+  protected async delete(endpoint: string): Promise<ModifiedResponse> {
+    try {
+      return await this.client(`${this.apiUrl}${endpoint}`, {
+        method: 'DELETE'
+      })
+    } catch (error) {
+      throw (error as APIError) ?? 'DELETE request failed'
+    }
+  }
+
+  /**
+   * Generic PATCH method
+   * @param endpoint - The API endpoint to call.
+   * @param data - The data to send in the client body.
+   *
+   * @returns A promise that resolves to a DecoratedResponse.
+   */
+  protected async patch<T>(endpoint: string, data: T): Promise<ModifiedResponse> {
+    try {
+      return await this.client(`${this.apiUrl}${endpoint}`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+        headers: { 'Content-Type': 'application/json' }
+      })
+    } catch (error) {
+      throw (error as APIError) ?? 'PATCH request failed'
+    }
+  }
+}
+
+export default DotdigitalApi

packages/destination-actions/src/destinations/dotdigital/api/index.ts

@@ -0,0 +1,4 @@
+export { default as DotdigitalContactApi } from './resources/dotdigital-contact-api'
+export { default as DotdigitalListsApi } from './resources/dotdigital-lists-api'
+export { default as DotdigitalEnrolmentAPi } from './resources/dotdigital-enrolment-api'
+export { default as DotdigitalDataFieldsApi } from './resources/dotdigital-datafields-api'

packages/destination-actions/src/destinations/dotdigital/api/resources/dotdigital-contact-api.ts

@@ -0,0 +1,85 @@
+import {
+  APIError,
+  ModifiedResponse,
+  RequestClient
+} from '@segment/actions-core';
+import type { Settings } from '../../generated-types';
+import DotdigitalApi from '../dotdigital-api';
+import { Contact, ChannelIdentifier, Identifiers, ChannelProperties } from '../types'
+import type { Payload } from '../../addContactToList/generated-types'
+
+class DotdigitalContactApi extends DotdigitalApi {
+  constructor(settings: Settings, client: RequestClient) {
+    super(settings, client);
+  }
+
+  /**
+   * Fetches a contact from Dotdigital API.
+   *
+   * @param contactIdentifier - The type of identifier (e.g., email, mobile number).
+   * @param identifierValue - The value of the identifier.
+   *
+   * @returns A promise that resolves to a ContactResponse.
+   */
+  async getContact(
+    contactIdentifier: string,
+    identifierValue: string | undefined
+  ): Promise<Contact> {
+    try {
+      const response: ModifiedResponse = await this.get(`/contacts/v3/${contactIdentifier}/${identifierValue}`);
+      return JSON.parse(response.content) as Contact;
+    } catch (error) {
+      throw error as APIError ?? 'Failed to fetch contact';
+    }
+  }
+
+  /**
+   * Fetches a contact from Dotdigital API via means of Patch.
+   *
+   * @param channelIdentifier - The identifier of the contact channel.
+   * @param _data - The data to be sent in the request body.
+   *
+   * @returns A promise that resolves to a ContactResponse.
+   */
+    async fetchOrCreateContact<T>(channelIdentifier: ChannelIdentifier, _data: T): Promise<Contact> {
+      const [[contactIdentifier, identifierValue]] = Object.entries(channelIdentifier);
+      try {
+        const response: ModifiedResponse = await this.patch(`/contacts/v3/${contactIdentifier}/${identifierValue}`, _data);
+        return JSON.parse(response.content) as Contact;
+      } catch (error) {
+        throw error as APIError ?? 'Failed to update contact';
+      }
+    }
+
+  /**
+   * Creates or updates a contact .
+   * @param {Payload} payload - The event payload.
+   * @returns {Promise<Contact>} A promise resolving to the contact data.
+   */
+  public async upsertContact(payload: Payload): Promise<Contact> {
+    const { channelIdentifier, emailIdentifier, mobileNumberIdentifier, listId, dataFields } = payload
+    const identifierValue = channelIdentifier === 'email' ? emailIdentifier : mobileNumberIdentifier
+    const identifiers:Identifiers = {}
+    if (emailIdentifier) identifiers.email = emailIdentifier
+    if (mobileNumberIdentifier) identifiers.mobileNumber = mobileNumberIdentifier
+
+    const channelProperties:ChannelProperties = {}
+    if (emailIdentifier) channelProperties.email = { status: 'subscribed', emailType: 'html', optInType: 'single' }
+    if (mobileNumberIdentifier) channelProperties.sms = { status: 'subscribed' }
+
+    const data = {
+      identifiers,
+      channelProperties,
+      lists: [listId],
+      dataFields: dataFields
+    }
+
+    const response: ModifiedResponse = await this.patch(
+      `/contacts/v3/${channelIdentifier}/${identifierValue}?merge-option=overwrite`,
+      data
+    )
+    return JSON.parse(response.content) as Contact
+  }
+}
+
+export default DotdigitalContactApi