@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

package/src/lib/actions/remove-subscriber-from-tag.ts

@@ -0,0 +1,94 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { mailchimpAuth } from '../..';
+
+export const removeSubscriberFromTag = createAction({
+  auth: mailchimpAuth,
+  name: 'remove_subscriber_from_tag',
+  displayName: 'Remove Subscriber from Tag',
+  description: 'Remove a subscriber from a specific tag in your Mailchimp audience.',
+  audience: 'both',
+  aiMetadata: { description: 'Deactivates a tag on a subscriber, identified by email within a given audience (list). Use to un-segment or un-label a contact. Idempotent: removing a tag the member does not have leaves the state unchanged.', idempotent: true },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    email: Property.ShortText({
+      displayName: 'Email Address',
+      description: 'The email address of the subscriber to remove from the tag',
+      required: true,
+    }),
+    tag_name: Property.ShortText({
+      displayName: 'Tag Name',
+      description: 'The name of the tag to remove the subscriber from',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { list_id, email, tag_name } = context.propsValue;
+    const accessToken = getAccessTokenOrThrow(context.auth);
+
+    try {
+      const serverPrefix = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+      const subscriberHash = mailchimpCommon.getMD5EmailHash(email);
+
+      const url = `https://${serverPrefix}.api.mailchimp.com/3.0/lists/${list_id}/members/${subscriberHash}/tags`;
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${accessToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          tags: [
+            {
+              name: tag_name,
+              status: 'inactive',
+            },
+          ],
+        }),
+      });
+
+      if (!response.ok) {
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        
+        try {
+          const errorText = await response.text();
+          if (errorText && errorText.trim()) {
+            const errorData = JSON.parse(errorText);
+            errorMessage = errorData.detail || errorData.title || errorData.message || errorText;
+          }
+        } catch (parseError) {
+          const errorText = await response.text();
+          if (errorText && errorText.trim()) {
+            errorMessage = errorText;
+          }
+        }
+
+        throw new Error(`Failed to remove subscriber from tag: ${errorMessage}`);
+      }
+
+      let result;
+      try {
+        const responseText = await response.text();
+        if (responseText && responseText.trim()) {
+          result = JSON.parse(responseText);
+        } else {
+          result = { success: true };
+        }
+      } catch (parseError) {
+        result = { success: true };
+      }
+
+      return {
+        success: true,
+        message: `Successfully removed subscriber ${email} from tag ${tag_name}`,
+        data: result,
+        _links: result._links || [],
+      };
+    } catch (error: any) {
+      console.error('Error removing subscriber from tag:', error);
+      throw new Error(`Failed to remove subscriber from tag: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/send-campaign.ts

@@ -0,0 +1,42 @@
+import { createAction } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { mailchimpAuth } from '../..';
+import mailchimp from '@mailchimp/mailchimp_marketing';
+import { MailchimpClient } from '../common/types';
+
+export const sendCampaign = createAction({
+  auth: mailchimpAuth,
+  name: 'send_campaign',
+  displayName: 'Send Campaign',
+  description: 'Send a draft campaign to the subscribers in its audience, segment, or tag',
+  audience: 'both',
+  aiMetadata: { description: 'Sends an existing draft campaign to its configured recipients immediately (RSS campaigns follow their schedule instead). Use once the campaign is fully set up; there is no undo, so confirm the campaign content and audience beforehand. Not idempotent: calling again on an already-sent campaign fails.', idempotent: false },
+  props: {
+    campaign_id: mailchimpCommon.mailChimpDraftCampaignIdDropdown,
+  },
+  async run(context) {
+    const { campaign_id } = context.propsValue;
+    const accessToken = getAccessTokenOrThrow(context.auth);
+    const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+
+    const client = mailchimp as unknown as MailchimpClient;
+    client.setConfig({
+      accessToken: accessToken,
+      server: server,
+    });
+
+    try {
+      // Docs: https://mailchimp.com/developer/marketing/api/campaigns/send-campaign/
+      await client.campaigns.send(campaign_id as string);
+
+      return {
+        success: true,
+        message: 'Campaign sent successfully',
+        campaign_id,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to send campaign: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

package/src/lib/actions/unsubscribe-email.ts

@@ -0,0 +1,91 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { mailchimpAuth } from '../..';
+import mailchimp from '@mailchimp/mailchimp_marketing';
+import { MailchimpClient } from '../common/types';
+
+export const unsubscribeEmail = createAction({
+  auth: mailchimpAuth,
+  name: 'unsubscribe_email',
+  displayName: 'Unsubscribe Email',
+  description: 'Unsubscribe an email address from an audience',
+  audience: 'both',
+  aiMetadata: { description: 'Sets an email address to unsubscribed status within an audience (list) via a batch upsert; with "update existing" on, it changes an existing member, otherwise it can add the address as unsubscribed. Use to opt a contact out of a specific audience. Idempotent: repeating converges to the same unsubscribed state.', idempotent: true },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    email_address: Property.ShortText({
+      displayName: 'Email Address',
+      description: 'Email address to unsubscribe',
+      required: true,
+    }),
+    skip_merge_validation: Property.Checkbox({
+      displayName: 'Skip Merge Validation',
+      description: 'Accept member data without merge field values even if required',
+      required: false,
+      defaultValue: false,
+    }),
+    skip_duplicate_check: Property.Checkbox({
+      displayName: 'Skip Duplicate Check',
+      description: 'Ignore duplicates in the request',
+      required: false,
+      defaultValue: false,
+    }),
+    update_existing: Property.Checkbox({
+      displayName: 'Update Existing',
+      description: 'Change existing members subscription status',
+      required: false,
+      defaultValue: true,
+    }),
+  },
+  async run(context) {
+    const accessToken = getAccessTokenOrThrow(context.auth);
+    const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+    
+    const client = mailchimp as unknown as MailchimpClient;
+    client.setConfig({
+      accessToken: accessToken,
+      server: server,
+    });
+
+    try {
+      const batchData = {
+        members: [
+          {
+            email_address: context.propsValue.email_address,
+            status: 'unsubscribed',
+          },
+        ],
+        update_existing: context.propsValue.update_existing,
+      };
+
+      const queryParams: any = {};
+      if (context.propsValue.skip_merge_validation) {
+        queryParams.skip_merge_validation = true;
+      }
+      if (context.propsValue.skip_duplicate_check) {
+        queryParams.skip_duplicate_check = true;
+      }
+
+      const result = await client.lists.batchListMembers(
+        context.propsValue.list_id!,
+        batchData,
+        queryParams
+      );
+
+      return {
+        success: true,
+        message: `Email ${context.propsValue.email_address} has been unsubscribed`,
+        new_members: result.new_members,
+        updated_members: result.updated_members,
+        errors: result.errors,
+        total_created: result.total_created,
+        total_updated: result.total_updated,
+        error_count: result.error_count,
+        _links: result._links,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to unsubscribe email: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

package/src/lib/actions/update-subscriber-status.ts

@@ -0,0 +1,53 @@
+import { mailchimpCommon } from '../common';
+import mailchimp from '@mailchimp/mailchimp_marketing';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { mailchimpAuth } from '../..';
+
+export const updateSubscriberInList = createAction({
+  auth: mailchimpAuth,
+  name: 'update_member_in_list',
+  displayName: 'Update Member in an Audience (List)',
+  description: 'Update a member in an existing Mailchimp audience (list)',
+  audience: 'both',
+  aiMetadata: { description: 'Updates the subscription status (subscribed, unsubscribed, cleaned, pending, transactional) of an existing member in an audience (list), identified by email. Use to change a known contact\'s status; the member must already exist, or the call fails. Idempotent: setting the same status repeatedly converges to that state.', idempotent: true },
+  props: {
+    email: Property.ShortText({
+      displayName: 'Email',
+      description: 'Email of the new contact',
+      required: true,
+    }),
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    status: Property.StaticDropdown<
+      'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional'
+    >({
+      displayName: 'Status',
+      required: true,
+      options: {
+        options: [
+          { label: 'Subscribed', value: 'subscribed' },
+          { label: 'Unsubscribed', value: 'unsubscribed' },
+          { label: 'Cleaned', value: 'cleaned' },
+          { label: 'Pending', value: 'pending' },
+          { label: 'Transactional', value: 'transactional' },
+        ],
+      },
+    }),
+  },
+  async run(context) {
+    const { list_id, email, status } = context.propsValue;
+    const access_token = context.auth.access_token;
+    const mailChimpServerPrefix =
+      await mailchimpCommon.getMailChimpServerPrefix(access_token);
+    mailchimp.setConfig({
+      accessToken: access_token,
+      server: mailChimpServerPrefix,
+    });
+    return await mailchimp.lists.updateListMember(
+      list_id as string,
+      email!,
+      {
+        status: status!,
+      }
+    );
+  },
+});

package/src/lib/common/index.ts

@@ -0,0 +1,267 @@
+import { Property, OAuth2PropertyValue } from '@agnocon/pieces-framework';
+import {
+  HttpRequest,
+  HttpMethod,
+  httpClient,
+} from '@agnocon/pieces-common';
+import mailchimp from '@mailchimp/mailchimp_marketing';
+import { AuthenticationType } from '@agnocon/pieces-common';
+import crypto from 'crypto';
+import { mailchimpAuth } from '../..';
+
+export const mailchimpCommon = {
+  mailChimpListIdDropdown: Property.Dropdown<string,true,typeof mailchimpAuth>({
+    auth: mailchimpAuth,
+    displayName: 'Audience',
+    refreshers: [],
+    description: 'Audience you want to add the contact to',
+    required: true,
+    options: async ({ auth }) => {
+      if (!auth) {
+        return {
+          disabled: true,
+          options: [],
+          placeholder: 'Please select a connection',
+        };
+      }
+
+      const authProp = auth as OAuth2PropertyValue;
+      const listResponse = (await mailchimpCommon.getUserLists(
+        authProp
+      )) as any;
+
+      const options = listResponse.lists.map((list: any) => ({
+        label: list.name,
+        value: list.id,
+      }));
+
+      return {
+        disabled: false,
+        options,
+      };
+    },
+  }),
+  getUserLists: async (authProp: OAuth2PropertyValue) => {
+    const access_token = authProp.access_token;
+    const mailChimpServerPrefix =
+      await mailchimpCommon.getMailChimpServerPrefix(access_token!);
+    mailchimp.setConfig({
+      accessToken: access_token,
+      server: mailChimpServerPrefix,
+    });
+
+    // mailchimp types are not complete this is from the docs.
+    return await (mailchimp as any).lists.getAllLists({
+      fields: ['lists.id', 'lists.name', 'total_items'],
+      count: 1000,
+    });
+  },
+
+  mailChimpCampaignIdDropdown: Property.Dropdown<string,true,typeof mailchimpAuth >({
+    auth: mailchimpAuth,
+    displayName: 'Campaign',
+    refreshers: [],
+    description: 'Select the campaign to get information for',
+    required: true,
+    options: async ({ auth }) => {
+      if (!auth) {
+        return {
+          disabled: true,
+          options: [],
+          placeholder: 'Please select a connection',
+        };
+      }
+
+      const authProp = auth as OAuth2PropertyValue;
+      const campaignResponse = (await mailchimpCommon.getUserCampaigns(
+        authProp
+      )) as any;
+
+      const options = campaignResponse.campaigns.map((campaign: any) => ({
+        label: `${campaign.settings?.title || campaign.id} (${campaign.status})`,
+        value: campaign.id,
+      }));
+
+      return {
+        disabled: false,
+        options,
+      };
+    },
+  }),
+
+  getUserCampaigns: async (authProp: OAuth2PropertyValue, options?: { status?: string }) => {
+    const access_token = authProp.access_token;
+    const mailChimpServerPrefix =
+      await mailchimpCommon.getMailChimpServerPrefix(access_token!);
+    mailchimp.setConfig({
+      accessToken: access_token,
+      server: mailChimpServerPrefix,
+    });
+
+    // Get campaigns with essential fields for dropdown
+    return await (mailchimp as any).campaigns.list({
+      fields: ['campaigns.id', 'campaigns.settings.title', 'campaigns.status', 'total_items'],
+      count: 1000,
+      ...(options?.status ? { status: options.status } : {}),
+    });
+  },
+
+  mailChimpDraftCampaignIdDropdown: Property.Dropdown<string,true,typeof mailchimpAuth >({
+    auth: mailchimpAuth,
+    displayName: 'Campaign',
+    refreshers: [],
+    description: 'Select the draft campaign to send',
+    required: true,
+    options: async ({ auth }) => {
+      if (!auth) {
+        return {
+          disabled: true,
+          options: [],
+          placeholder: 'Please select a connection',
+        };
+      }
+
+      const authProp = auth as OAuth2PropertyValue;
+      // Mailchimp only accepts the send action on campaigns in "save" (draft) status.
+      const campaignResponse = (await mailchimpCommon.getUserCampaigns(
+        authProp,
+        { status: 'save' }
+      )) as any;
+
+      const options = campaignResponse.campaigns.map((campaign: any) => ({
+        label: `${campaign.settings?.title || campaign.id}`,
+        value: campaign.id,
+      }));
+
+      return {
+        disabled: false,
+        options,
+      };
+    },
+  }),
+
+  mailChimpStoreIdDropdown: Property.Dropdown<string,true,typeof mailchimpAuth >({
+    auth: mailchimpAuth,
+    displayName: 'Store',
+    refreshers: [],
+    description: 'Select the e-commerce store',
+    required: true,
+    options: async ({ auth }) => {
+      if (!auth) {
+        return {
+          disabled: true,
+          options: [],
+          placeholder: 'Please select a connection',
+        };
+      }
+
+      const authProp = auth as OAuth2PropertyValue;
+      const storeResponse = (await mailchimpCommon.getUserStores(
+        authProp
+      )) as any;
+
+      const options = storeResponse.stores.map((store: any) => ({
+        label: `${store.name} (${store.id})`,
+        value: store.id,
+      }));
+
+      return {
+        disabled: false,
+        options,
+      };
+    },
+  }),
+
+  getUserStores: async (authProp: OAuth2PropertyValue) => {
+    const access_token = authProp.access_token;
+    const mailChimpServerPrefix =
+      await mailchimpCommon.getMailChimpServerPrefix(access_token!);
+    mailchimp.setConfig({
+      accessToken: access_token,
+      server: mailChimpServerPrefix,
+    });
+
+    // Get stores with essential fields for dropdown
+    return await (mailchimp as any).ecommerce.stores({
+      fields: ['stores.id', 'stores.name', 'total_items'],
+      count: 1000,
+    });
+  },
+  getMailChimpServerPrefix: async (access_token: string) => {
+    const mailChimpMetaDataRequest: HttpRequest<{ dc: string }> = {
+      method: HttpMethod.GET,
+      url: 'https://login.mailchimp.com/oauth2/metadata',
+      headers: {
+        Authorization: `OAuth ${access_token}`,
+      },
+    };
+    return (await httpClient.sendRequest(mailChimpMetaDataRequest)).body['dc'];
+  },
+  enableWebhookRequest: async ({
+    server,
+    token,
+    listId,
+    webhookUrl,
+    events,
+  }: EnableTriggerRequestParams): Promise<string> => {
+    const response = await httpClient.sendRequest<EnableTriggerResponse>({
+      method: HttpMethod.POST,
+      url: `https://${server}.api.mailchimp.com/3.0/lists/${listId}/webhooks`,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token,
+      },
+      body: {
+        url: webhookUrl,
+        events,
+        sources: {
+          user: true,
+          admin: true,
+          api: true,
+        },
+      },
+    });
+
+    const { id: webhookId } = response.body;
+    return webhookId;
+  },
+  disableWebhookRequest: async ({
+    server,
+    token,
+    listId,
+    webhookId,
+  }: DisableTriggerRequestParams): Promise<void> => {
+    await httpClient.sendRequest<EnableTriggerResponse>({
+      method: HttpMethod.DELETE,
+      url: `https://${server}.api.mailchimp.com/3.0/lists/${listId}/webhooks/${webhookId}`,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token,
+      },
+    });
+  },
+  getMD5EmailHash: (email: string) => {
+    return crypto.createHash('md5').update(email.toLowerCase()).digest('hex');
+  },
+};
+
+type TriggerRequestParams = {
+  server: string;
+  token: string;
+  listId: string;
+};
+
+type EnableTriggerRequestParams = TriggerRequestParams & {
+  webhookUrl: string;
+  events: object;
+};
+
+type DisableTriggerRequestParams = TriggerRequestParams & {
+  webhookId: string;
+};
+
+type EnableTriggerResponse = {
+  id: string;
+  url: string;
+  list_id: string;
+};