@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

package/src/lib/actions/add-subscriber-to-tag.ts

@@ -0,0 +1,66 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { MailchimpClient } from '../common/types';
+import { mailchimpAuth } from '../..';
+import mailchimp from '@mailchimp/mailchimp_marketing';
+
+export const addSubscriberToTag = createAction({
+  auth: mailchimpAuth,
+  name: 'add_subscriber_to_tag',
+  displayName: 'Add Subscriber to Tag',
+  description: 'Add a subscriber to a specific tag in your Mailchimp audience.',
+  audience: 'both',
+  aiMetadata: { description: 'Activates a tag on a subscriber, identified by email within a given audience (list); the tag is created if it does not already exist. Use to segment or label a contact. Idempotent: re-applying an already-active tag leaves the member state unchanged.', idempotent: true },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    email: Property.ShortText({
+      displayName: 'Email Address',
+      description: 'The email address of the subscriber to add to the tag',
+      required: true,
+    }),
+    tag_name: Property.ShortText({
+      displayName: 'Tag Name',
+      description: 'The name of the tag to add the subscriber to',
+      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);
+
+      mailchimp.setConfig({
+        accessToken: accessToken,
+        server: serverPrefix,
+      });
+
+      const client = mailchimp as unknown as MailchimpClient;
+
+      const result = await client.lists.updateListMemberTags(
+        list_id as string,
+        subscriberHash,
+        {
+          tags: [
+            {
+              name: tag_name,
+              status: 'active',
+            },
+          ],
+        }
+      );
+
+      return {
+        success: true,
+        message: `Successfully added subscriber ${email} to tag ${tag_name}`,
+        data: result,
+      };
+    } catch (error: any) {
+      console.error('Error adding subscriber to tag:', error);
+      throw new Error(`Failed to add subscriber to tag: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/archive-subscriber.ts

@@ -0,0 +1,64 @@
+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';
+import crypto from 'crypto';
+
+export const archiveSubscriber = createAction({
+  auth: mailchimpAuth,
+  name: 'archive_subscriber',
+  displayName: 'Archive Subscriber',
+  description: 'Archive an existing audience member',
+  audience: 'both',
+  aiMetadata: { description: 'Archives a member from an audience (list); the identifier accepts an MD5 hash of the lowercase email, the raw email (auto-hashed), or a contact_id. Use to remove a contact from active sending while preserving their record. Idempotent: archiving an already-archived or absent member converges to the same state.', idempotent: true },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    subscriber_hash: Property.ShortText({
+      displayName: 'Subscriber Hash or Email',
+      description: 'MD5 hash of the lowercase email address, email address, or contact_id',
+      required: 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 {
+      let subscriberHash = context.propsValue.subscriber_hash;
+      
+      // If it looks like an email, convert to MD5 hash
+      if (subscriberHash.includes('@')) {
+        subscriberHash = crypto.createHash('md5').update(subscriberHash.toLowerCase()).digest('hex');
+      }
+
+      await client.lists.deleteListMember(context.propsValue.list_id!, subscriberHash);
+
+      return {
+        success: true,
+        message: 'Subscriber archived successfully',
+        list_id: context.propsValue.list_id,
+        subscriber_hash: subscriberHash,
+        archived_at: new Date().toISOString(),
+      };
+    } catch (error: any) {
+      if (error.status === 404) {
+        return {
+          success: false,
+          error: 'Subscriber not found',
+          message: 'The subscriber could not be found in the specified list.',
+          detail: error.detail || 'The requested resource could not be found',
+        };
+      }
+      
+      throw new Error(`Failed to archive subscriber: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

package/src/lib/actions/create-audience.ts

@@ -0,0 +1,192 @@
+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 createAudience = createAction({
+  auth: mailchimpAuth,
+  name: 'create_audience',
+  displayName: 'Create Audience',
+  description: 'Create a new audience (list) in your Mailchimp account',
+  audience: 'both',
+  aiMetadata: { description: 'Creates a new audience (list) in the Mailchimp account, including the required physical contact address, permission reminder, and default campaign sender settings. Use to provision a brand-new list to hold subscribers. Not idempotent: each call creates a separate audience even with identical input.', idempotent: false },
+  props: {
+    name: Property.ShortText({
+      displayName: 'List Name',
+      description: 'The name of the list',
+      required: true,
+    }),
+    company: Property.ShortText({
+      displayName: 'Company',
+      description: 'Company name for list contact information',
+      required: true,
+    }),
+    address1: Property.ShortText({
+      displayName: 'Address Line 1',
+      description: 'Street address for list contact information',
+      required: true,
+    }),
+    address2: Property.ShortText({
+      displayName: 'Address Line 2',
+      description: 'Additional address information (optional)',
+      required: false,
+    }),
+    city: Property.ShortText({
+      displayName: 'City',
+      description: 'City for list contact information',
+      required: true,
+    }),
+    state: Property.ShortText({
+      displayName: 'State/Province',
+      description: 'State or province for list contact information',
+      required: false,
+    }),
+    zip: Property.ShortText({
+      displayName: 'ZIP/Postal Code',
+      description: 'ZIP or postal code for list contact information',
+      required: false,
+    }),
+    country: Property.ShortText({
+      displayName: 'Country',
+      description: 'Country for list contact information',
+      required: true,
+    }),
+    phone: Property.ShortText({
+      displayName: 'Phone',
+      description: 'Phone number for list contact information (optional)',
+      required: false,
+    }),
+    permission_reminder: Property.LongText({
+      displayName: 'Permission Reminder',
+      description: 'The permission reminder for the list',
+      required: true,
+      defaultValue: 'You are receiving this email because you signed up for updates from us.',
+    }),
+    from_name: Property.ShortText({
+      displayName: 'Default From Name',
+      description: 'Default from name for campaigns',
+      required: true,
+    }),
+    from_email: Property.ShortText({
+      displayName: 'Default From Email',
+      description: 'Default from email address for campaigns',
+      required: true,
+    }),
+    subject: Property.ShortText({
+      displayName: 'Default Subject',
+      description: 'Default subject line for campaigns',
+      required: true,
+    }),
+    language: Property.ShortText({
+      displayName: 'Language',
+      description: 'Default language for campaigns (e.g., "en", "es", "fr")',
+      required: true,
+      defaultValue: 'en',
+    }),
+    email_type_option: Property.Checkbox({
+      displayName: 'Email Type Option',
+      description: 'Whether the list supports multiple email formats (HTML/plain text)',
+      required: false,
+      defaultValue: true,
+    }),
+    use_archive_bar: Property.Checkbox({
+      displayName: 'Use Archive Bar',
+      description: 'Whether campaigns use the Archive Bar in archives by default',
+      required: false,
+      defaultValue: false,
+    }),
+    notify_on_subscribe: Property.ShortText({
+      displayName: 'Notify on Subscribe',
+      description: 'Email address to send subscribe notifications to (optional)',
+      required: false,
+    }),
+    notify_on_unsubscribe: Property.ShortText({
+      displayName: 'Notify on Unsubscribe',
+      description: 'Email address to send unsubscribe notifications to (optional)',
+      required: false,
+    }),
+    double_optin: Property.Checkbox({
+      displayName: 'Double Opt-in',
+      description: 'Whether to require subscriber confirmation via email',
+      required: false,
+      defaultValue: false,
+    }),
+    marketing_permissions: Property.Checkbox({
+      displayName: 'Marketing Permissions',
+      description: 'Whether the list has marketing permissions (GDPR) enabled',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  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 listData = {
+        name: context.propsValue.name,
+        contact: {
+          company: context.propsValue.company,
+          address1: context.propsValue.address1,
+          address2: context.propsValue.address2 || '',
+          city: context.propsValue.city,
+          state: context.propsValue.state || '',
+          zip: context.propsValue.zip || '',
+          country: context.propsValue.country,
+          phone: context.propsValue.phone || '',
+        },
+        permission_reminder: context.propsValue.permission_reminder,
+        campaign_defaults: {
+          from_name: context.propsValue.from_name,
+          from_email: context.propsValue.from_email,
+          subject: context.propsValue.subject,
+          language: context.propsValue.language,
+        },
+        email_type_option: context.propsValue.email_type_option,
+        use_archive_bar: context.propsValue.use_archive_bar,
+        notify_on_subscribe: context.propsValue.notify_on_subscribe || '',
+        notify_on_unsubscribe: context.propsValue.notify_on_unsubscribe || '',
+        double_optin: context.propsValue.double_optin,
+        marketing_permissions: context.propsValue.marketing_permissions,
+      };
+
+      const list = await client.lists.createList(listData);
+
+      return {
+        success: true,
+        id: list.id,
+        web_id: list.web_id,
+        name: list.name,
+        contact: list.contact,
+        permission_reminder: list.permission_reminder,
+        use_archive_bar: list.use_archive_bar,
+        campaign_defaults: list.campaign_defaults,
+        notify_on_subscribe: list.notify_on_subscribe,
+        notify_on_unsubscribe: list.notify_on_unsubscribe,
+        date_created: list.date_created,
+        list_rating: list.list_rating,
+        email_type_option: list.email_type_option,
+        subscribe_url_short: list.subscribe_url_short,
+        subscribe_url_long: list.subscribe_url_long,
+        beamer_address: list.beamer_address,
+        visibility: list.visibility,
+        double_optin: list.double_optin,
+        has_welcome: list.has_welcome,
+        marketing_permissions: list.marketing_permissions,
+        modules: list.modules,
+        stats: list.stats,
+        _links: list._links,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to create list: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

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

@@ -0,0 +1,155 @@
+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, CampaignCreateData, CampaignContentData } from '../common/types';
+
+export const createCampaign = createAction({
+  auth: mailchimpAuth,
+  name: 'create_campaign',
+  displayName: 'Create Campaign',
+  description: 'Create a new Mailchimp campaign',
+  audience: 'both',
+  aiMetadata: { description: 'Creates a new draft campaign of a chosen type (regular, plain-text, A/B, RSS, or variate) targeting an audience (list), and optionally sets its content from inline HTML, a hosted URL, or a template depending on the selected content type. Use to set up a campaign for later sending; this does not send it. Not idempotent: each call creates a distinct campaign.', idempotent: false },
+  props: {
+    campaign_type: Property.StaticDropdown({
+      displayName: 'Campaign Type',
+      description: 'The type of campaign to create',
+      required: true,
+      options: {
+        options: [
+          { label: 'Regular', value: 'regular' },
+          { label: 'Plain Text', value: 'plaintext' },
+          { label: 'A/B Test', value: 'ab' },
+          { label: 'RSS', value: 'rss' },
+          { label: 'Variate', value: 'variate' },
+        ],
+      },
+    }),
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    subject_line: Property.ShortText({
+      displayName: 'Subject Line',
+      description: 'The subject line for the campaign',
+      required: true,
+    }),
+    title: Property.ShortText({
+      displayName: 'Campaign Title',
+      description: 'The title of the campaign',
+      required: true,
+    }),
+    from_name: Property.ShortText({
+      displayName: 'From Name',
+      description: 'The name that will appear in the "From" field',
+      required: true,
+    }),
+    from_email: Property.ShortText({
+      displayName: 'From Email',
+      description: 'The email address that will appear in the "From" field',
+      required: true,
+    }),
+    reply_to: Property.ShortText({
+      displayName: 'Reply To Email',
+      description: 'The email address that will receive replies',
+      required: true,
+    }),
+    to_name: Property.ShortText({
+      displayName: 'To Name',
+      description: 'The name that will appear in the "To" field (e.g., *|FNAME|*)',
+      required: false,
+    }),
+    content_type: Property.StaticDropdown({
+      displayName: 'Content Type',
+      description: 'How the campaign content is put together',
+      required: true,
+      options: {
+        options: [
+          { label: 'Template', value: 'template' },
+          { label: 'HTML', value: 'html' },
+          { label: 'URL', value: 'url' },
+          { label: 'Multichannel', value: 'multichannel' },
+        ],
+      },
+    }),
+    content_url: Property.ShortText({
+      displayName: 'Content URL',
+      description: 'The URL where the campaign content is hosted (required if content_type is "url")',
+      required: false,
+    }),
+    template_id: Property.ShortText({
+      displayName: 'Template ID',
+      description: 'The ID of the template to use (required if content_type is "template")',
+      required: false,
+    }),
+    html_content: Property.LongText({
+      displayName: 'HTML Content',
+      description: 'The HTML content for the campaign (required if content_type is "html")',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const accessToken = getAccessTokenOrThrow(context.auth);
+    const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+
+    try {
+      const client = mailchimp as unknown as MailchimpClient;
+      client.setConfig({
+        accessToken: accessToken,
+        server: server,
+      });
+
+      const campaignData: CampaignCreateData = {
+        type: context.propsValue.campaign_type,
+        recipients: {
+          list_id: context.propsValue.list_id as string,
+        },
+        settings: {
+          subject_line: context.propsValue.subject_line,
+          title: context.propsValue.title,
+          from_name: context.propsValue.from_name,
+          from_email: context.propsValue.from_email,
+          reply_to: context.propsValue.reply_to,
+          to_name: context.propsValue.to_name || '',
+        },
+      };
+
+
+
+      const campaign = await client.campaigns.create(campaignData);
+
+      // Set campaign content based on content type
+      const contentData: CampaignContentData = {};
+      
+      if (context.propsValue.content_type === 'html' && context.propsValue.html_content) {
+        contentData.html = context.propsValue.html_content;
+      } else if (context.propsValue.content_type === 'url' && context.propsValue.content_url) {
+        contentData.url = context.propsValue.content_url;
+      } else if (context.propsValue.content_type === 'template' && context.propsValue.template_id) {
+        contentData.template = {
+          id: context.propsValue.template_id,
+        };
+      }
+
+      // Set content if any content data is provided
+      if (Object.keys(contentData).length > 0) {
+        await client.campaigns.setContent(campaign.id, contentData);
+      }
+
+      return {
+        success: true,
+        campaign_id: campaign.id,
+        campaign_web_id: campaign.web_id,
+        campaign_title: campaign.settings?.title,
+        campaign_subject: campaign.settings?.subject_line,
+        campaign_status: campaign.status,
+        campaign_type: campaign.type,
+        created_at: campaign.create_time,
+        archive_url: campaign.archive_url,
+        _links: campaign._links || [],
+      };
+    } catch (error: any) {
+      console.error('Error creating campaign:', error);
+      throw new Error(`Failed to create campaign: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

package/src/lib/actions/create-custom-event.ts

@@ -0,0 +1,63 @@
+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 createCustomEvent = createAction({
+  auth: mailchimpAuth,
+  name: 'create_custom_event',
+  displayName: 'Create Custom Event',
+  description: 'Log a custom event for an existing subscriber, for use in automations and segmentation',
+  audience: 'both',
+  aiMetadata: { description: 'Records a named event (with optional properties) against an existing subscriber, identified by email, in an audience (list). Use to feed subscriber behavior into automations or segments. Not idempotent: each call logs a new, distinct event occurrence.', idempotent: false },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    email: Property.ShortText({
+      displayName: 'Email Address',
+      description: 'The email address of the subscriber to log the event for',
+      required: true,
+    }),
+    name: Property.ShortText({
+      displayName: 'Event Name',
+      description: 'The name of the event (lowercase letters, numbers, and underscores only, e.g. "purchased_item")',
+      required: true,
+    }),
+    properties: Property.Object({
+      displayName: 'Properties',
+      description: 'Optional key/value data to attach to the event',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { list_id, email, name, properties } = context.propsValue;
+    const accessToken = getAccessTokenOrThrow(context.auth);
+    const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+    const subscriberHash = mailchimpCommon.getMD5EmailHash(email);
+
+    const client = mailchimp as unknown as MailchimpClient;
+    client.setConfig({
+      accessToken: accessToken,
+      server: server,
+    });
+
+    try {
+      // Docs: https://mailchimp.com/developer/marketing/api/list-member-events/add-event/
+      await client.lists.createListMemberEvent(list_id as string, subscriberHash, {
+        name,
+        ...(properties ? { properties } : {}),
+      });
+
+      return {
+        success: true,
+        message: `Successfully created event "${name}" for ${email}`,
+        list_id,
+        email,
+        name,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to create custom event: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

package/src/lib/actions/create-tag.ts

@@ -0,0 +1,51 @@
+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 createTag = createAction({
+  auth: mailchimpAuth,
+  name: 'create_tag',
+  displayName: 'Create Tag',
+  description: 'Create a new tag in a Mailchimp audience',
+  audience: 'both',
+  aiMetadata: { description: 'Creates a new tag on an audience (list) so it can later be applied to subscribers. Use to set up a tag ahead of tagging contacts. Not idempotent: calling again with the same name creates a duplicate tag.', idempotent: false },
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    name: Property.ShortText({
+      displayName: 'Tag Name',
+      description: 'The name of the tag to create',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { list_id, name } = 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 {
+      // Tags are static segments with no members yet.
+      // Docs: https://mailchimp.com/developer/marketing/api/list-segments/add-segment/
+      const segment = await client.lists.createSegment(list_id as string, {
+        name,
+        static_segment: [],
+      });
+
+      return {
+        success: true,
+        message: `Successfully created tag "${name}"`,
+        tag: segment,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to create tag: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});

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

@@ -0,0 +1,68 @@
+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, CampaignGetOptions } from '../common/types';
+
+export const findCampaign = createAction({
+  auth: mailchimpAuth,
+  name: 'find_campaign',
+  displayName: 'Find Campaign',
+  description: 'Search all campaigns for the specified query terms',
+  audience: 'both',
+  aiMetadata: { description: 'Searches all campaigns in the account by a free-text query (matching titles, subject lines, and related fields) and returns the matches. Use to locate a campaign by name or wording before reading or acting on it. Read-only and idempotent; a query is required.', idempotent: true },
+  props: {
+    query: Property.ShortText({
+      displayName: 'Search Query',
+      description: 'Search terms to find campaigns',
+      required: true,
+    }),
+    fields: Property.LongText({
+      displayName: 'Fields',
+      description: 'Comma-separated list of fields to return',
+      required: false,
+    }),
+    exclude_fields: Property.LongText({
+      displayName: 'Exclude Fields',
+      description: 'Comma-separated list of fields to exclude',
+      required: false,
+    }),
+  },
+  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 searchParams: any = {
+        query: context.propsValue.query,
+      };
+
+      if (context.propsValue.fields) {
+        searchParams.fields = context.propsValue.fields.split(',').map(f => f.trim());
+      }
+
+      if (context.propsValue.exclude_fields) {
+        searchParams.exclude_fields = context.propsValue.exclude_fields.split(',').map(f => f.trim());
+      }
+
+      const searchResult = await client.searchCampaigns.search(searchParams);
+
+      return {
+        success: true,
+        query: context.propsValue.query,
+        results: searchResult.results,
+        total_items: searchResult.total_items,
+        _links: searchResult._links,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to search campaigns: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+});