@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

package/src/lib/triggers/subscribe-trigger.ts

@@ -0,0 +1,159 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { MailChimpSubscribeWebhookRequest } from '../common/types';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_subscribe_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getSubscribeEventSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    email: data.email || 'N/A',
+    subscriber_id: data.id || 'N/A',
+    list_id: data.list_id || 'N/A',
+    email_type: data.email_type || 'html',
+    ip_address: data.ip_opt || data.ip_signup || 'N/A',
+    signup_timestamp: data.timestamp_signup || 'N/A',
+    opt_in_timestamp: data.timestamp_opt || 'N/A',
+    has_merge_fields: !!data.merges,
+    merge_field_count: data.merges ? Object.keys(data.merges).length : 0,
+    merge_fields_summary: data.merges ? {
+      first_name: data.merges.FNAME || 'N/A',
+      last_name: data.merges.LNAME || 'N/A',
+      company: data.merges.COMPANY || 'N/A',
+      phone: data.merges.PHONE || 'N/A',
+      interests: data.merges.INTERESTS || 'N/A',
+      has_address: !!data.merges.ADDRESS,
+    } : null,
+  };
+};
+
+export const mailChimpSubscribeTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'subscribe',
+  displayName: 'Member Subscribed to Audience',
+  description: 'Fires when a new subscriber joins your Mailchimp audience. This trigger captures new subscriptions, opt-ins, and audience growth events with comprehensive subscriber information.',
+  aiMetadata: {
+    description: 'Fires when a contact subscribes (opts in) to the selected Mailchimp audience (list), representing a new or re-activated subscriber. The event carries the subscriber email, merge fields, and signup metadata.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'subscribe',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      email: 'api@mailchimp.com',
+      email_type: 'html',
+      ip_opt: '192.168.1.100',
+      ip_signup: '192.168.1.100',
+      timestamp_signup: '2024-01-15T10:30:00Z',
+      timestamp_opt: '2024-01-15T10:30:00Z',
+      merges: {
+        EMAIL: 'api@mailchimp.com',
+        FNAME: 'Mailchimp',
+        LNAME: 'API',
+        COMPANY: 'Mailchimp Inc',
+        PHONE: '+1-555-0123',
+        INTERESTS: 'Group1,Group2',
+        ADDRESS: {
+          addr1: '675 Ponce de Leon Ave NE',
+          addr2: 'Suite 5000',
+          city: 'Atlanta',
+          state: 'GA',
+          zip: '30308',
+          country: 'US',
+        },
+      },
+      member_rating: 5,
+      vip: false,
+      language: 'en',
+      source: 'api',
+      tags: ['api-signup', 'new-subscriber'],
+    },
+  },
+
+  async onEnable(context): Promise<void> {
+    try {
+      const accessToken = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+
+      const enabledWebhookId = await mailchimpCommon.enableWebhookRequest({
+        server,
+        listId: context.propsValue.list_id as string,
+        token: accessToken,
+        webhookUrl: context.webhookUrl!,
+        events: { 
+          subscribe: true,
+        },
+      });
+
+      await context.store?.put<WebhookData>(WEBHOOK_DATA_STORE_KEY, {
+        id: enabledWebhookId,
+        listId: context.propsValue.list_id as string,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to enable subscribe webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async onDisable(context): Promise<void> {
+    try {
+      const webhookData = await context.store?.get<WebhookData>(WEBHOOK_DATA_STORE_KEY);
+
+      if (webhookData === undefined || webhookData === null) {
+        return;
+      }
+
+      const token = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(token);
+
+      await mailchimpCommon.disableWebhookRequest({
+        server,
+        token,
+        listId: webhookData.listId,
+        webhookId: webhookData.id,
+      });
+    } catch (error: any) {
+      console.error(`Failed to disable subscribe webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as MailChimpSubscribeWebhookRequest;
+
+      if (!request || request.type !== 'subscribe') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'member_subscribed',
+        event_category: 'New Subscription',
+        processed_at: new Date().toISOString(),
+        subscription_summary: getSubscribeEventSummary(request),
+        business_context: {
+          audience_growth: true,
+          new_lead: true,
+          marketing_opportunity: true,
+          engagement_potential: 'high',
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing subscribe webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/src/lib/triggers/subscriber-updated-trigger.ts

@@ -0,0 +1,165 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_subscriber_updated_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getEventCategory = (eventType: string): string => {
+  switch (eventType) {
+    case 'profile':
+      return 'Profile Update';
+    case 'subscribe':
+      return 'New Subscription';
+    case 'upemail':
+      return 'Email Change';
+    case 'cleaned':
+      return 'Email Cleanup';
+    default:
+      return 'Unknown Event';
+  }
+};
+
+const getSubscriberSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    email: data.email || data.new_email || 'N/A',
+    subscriber_id: data.id || 'N/A',
+    list_id: data.list_id || 'N/A',
+    email_type: data.email_type || 'html',
+    member_rating: data.member_rating || 0,
+    vip_status: data.vip ? 'VIP' : 'Standard',
+    language: data.language || 'en',
+    has_merge_fields: !!data.merges,
+    merge_field_count: data.merges ? Object.keys(data.merges).length : 0,
+    last_activity: data.last_changed || data.timestamp_opt || data.timestamp_signup || 'N/A',
+    ip_address: data.ip_opt || data.ip_signup || 'N/A',
+  };
+};
+
+export const mailChimpSubscriberUpdatedTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'subscriber_updated',
+  displayName: 'Subscriber Updated',
+  description: 'Fires when a subscriber profile is updated, including changes to merge fields, interests, or contact information. This trigger captures profile updates, new subscriptions, and subscriber modifications.',
+  aiMetadata: {
+    description: 'Fires on subscriber-record changes in the selected audience (list) — covering profile/merge-field updates, new subscriptions, email-address changes, and cleaned addresses. The event carries the subscriber email, merge fields, and (for email changes) the old and new addresses.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'profile',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      email: 'user@example.com',
+      email_type: 'html',
+      merges: {
+        EMAIL: 'user@example.com',
+        FNAME: 'John',
+        LNAME: 'Doe',
+        COMPANY: 'Example Corp',
+        PHONE: '+1-555-0123',
+        INTERESTS: 'Group1,Group2',
+        ADDRESS: {
+          addr1: '123 Main St',
+          addr2: 'Suite 100',
+          city: 'Anytown',
+          state: 'CA',
+          zip: '12345',
+          country: 'US',
+        },
+      },
+      new_email: 'newuser@example.com',
+      old_email: 'user@example.com',
+      member_rating: 5,
+      vip: false,
+      language: 'en',
+      ip_opt: '192.168.1.100',
+      ip_signup: '192.168.1.100',
+      timestamp_signup: '2024-01-01T09:00:00Z',
+      timestamp_opt: '2024-01-01T09:00:00Z',
+      last_changed: '2024-01-15T10:30:00Z',
+    },
+  },
+
+  async onEnable(context): Promise<void> {
+    try {
+      const accessToken = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+
+      const enabledWebhookId = await mailchimpCommon.enableWebhookRequest({
+        server,
+        listId: context.propsValue.list_id as string,
+        token: accessToken,
+        webhookUrl: context.webhookUrl!,
+        events: { 
+          profile: true, 
+          subscribe: true,
+          upemail: true,
+          cleaned: true,
+        },
+      });
+
+      await context.store?.put<WebhookData>(WEBHOOK_DATA_STORE_KEY, {
+        id: enabledWebhookId,
+        listId: context.propsValue.list_id as string,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to enable subscriber updated webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async onDisable(context): Promise<void> {
+    try {
+      const webhookData = await context.store?.get<WebhookData>(WEBHOOK_DATA_STORE_KEY);
+
+      if (webhookData === undefined || webhookData === null) {
+        return;
+      }
+
+      const token = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(token);
+
+      await mailchimpCommon.disableWebhookRequest({
+        server,
+        token,
+        listId: webhookData.listId,
+        webhookId: webhookData.id,
+      });
+    } catch (error: any) {
+      console.error(`Failed to disable subscriber updated webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as any;
+
+      if (request === undefined || !['profile', 'subscribe', 'upemail', 'cleaned'].includes(request.type)) {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'subscriber_updated',
+        event_category: getEventCategory(request.type),
+        processed_at: new Date().toISOString(),
+        subscriber_summary: getSubscriberSummary(request),
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing subscriber updated webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/src/lib/triggers/unsubscribe-trigger.ts

@@ -0,0 +1,212 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_unsubscribe_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getUnsubscribeEventSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    email: data.email || 'N/A',
+    subscriber_id: data.id || 'N/A',
+    list_id: data.list_id || 'N/A',
+    email_type: data.email_type || 'html',
+    ip_address: data.ip_opt || data.ip_signup || 'N/A',
+    signup_timestamp: data.timestamp_signup || 'N/A',
+    opt_in_timestamp: data.timestamp_opt || 'N/A',
+    unsubscribe_timestamp: request.fired_at || 'N/A',
+    has_merge_fields: !!data.merges,
+    merge_field_count: data.merges ? Object.keys(data.merges).length : 0,
+    merge_fields_summary: data.merges ? {
+      first_name: data.merges.FNAME || 'N/A',
+      last_name: data.merges.LNAME || 'N/A',
+      company: data.merges.COMPANY || 'N/A',
+      phone: data.merges.PHONE || 'N/A',
+      interests: data.merges.INTERESTS || 'N/A',
+      has_address: !!data.merges.ADDRESS,
+    } : null,
+    member_rating: data.member_rating || 0,
+    vip_status: data.vip ? 'VIP' : 'Standard',
+    language: data.language || 'en',
+  };
+};
+
+const calculateSubscriberLifetime = (request: any): string => {
+  const data = request.data || {};
+  const signupTime = data.timestamp_signup ? new Date(data.timestamp_signup) : null;
+  const unsubscribeTime = request.fired_at ? new Date(request.fired_at) : null;
+  
+  if (signupTime && unsubscribeTime) {
+    const diffTime = Math.abs(unsubscribeTime.getTime() - signupTime.getTime());
+    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+    return `${diffDays} days`;
+  }
+  return 'Unknown';
+};
+
+const assessEngagementLevel = (request: any): string => {
+  const data = request.data || {};
+  const rating = data.member_rating || 0;
+  
+  if (rating >= 4) return 'High';
+  if (rating >= 2) return 'Medium';
+  return 'Low';
+};
+
+const identifyChurnFactors = (request: any): string[] => {
+  const factors = [];
+  const data = request.data || {};
+  
+  if (data.member_rating && data.member_rating < 3) {
+    factors.push('Low engagement rating');
+  }
+  
+  if (request.unsubscribe_reason) {
+    factors.push(`Reason: ${request.unsubscribe_reason}`);
+  }
+  
+  if (request.campaign_id) {
+    factors.push('Campaign-specific unsubscribe');
+  }
+  
+  return factors.length > 0 ? factors : ['No specific factors identified'];
+};
+
+export const mailChimpUnsubscriberTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'unsubscribe',
+  displayName: 'Member Unsubscribed from Audience',
+  description: 'Fires when a subscriber unsubscribes from your Mailchimp audience. This trigger captures unsubscribe events, opt-outs, and audience churn with comprehensive subscriber information for retention analysis.',
+  aiMetadata: {
+    description: 'Fires when a contact unsubscribes (opts out) from the selected Mailchimp audience (list). The event carries the subscriber email, merge fields, and, when available, the unsubscribe reason and originating campaign.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'unsubscribe',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      email: 'api@mailchimp.com',
+      email_type: 'html',
+      ip_opt: '192.168.1.100',
+      ip_signup: '192.168.1.100',
+      timestamp_signup: '2024-01-01T09:00:00Z',
+      timestamp_opt: '2024-01-01T09:00:00Z',
+      merges: {
+        EMAIL: 'api@mailchimp.com',
+        FNAME: 'Mailchimp',
+        LNAME: 'API',
+        COMPANY: 'Mailchimp Inc',
+        PHONE: '+1-555-0123',
+        INTERESTS: 'Group1,Group2',
+        ADDRESS: {
+          addr1: '675 Ponce de Leon Ave NE',
+          addr2: 'Suite 5000',
+          city: 'Atlanta',
+          state: 'GA',
+          zip: '30308',
+          country: 'US',
+        },
+      },
+      member_rating: 3,
+      vip: false,
+      language: 'en',
+      source: 'api',
+      tags: ['api-signup', 'churned-subscriber'],
+      unsubscribe_reason: 'too_many_emails',
+      campaign_id: 'campaign_123',
+      campaign_title: 'Weekly Newsletter',
+    },
+  },
+
+  async onEnable(context): Promise<void> {
+    try {
+      const accessToken = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(accessToken);
+
+      const enabledWebhookId = await mailchimpCommon.enableWebhookRequest({
+        server,
+        listId: context.propsValue.list_id as string,
+        token: accessToken,
+        webhookUrl: context.webhookUrl!,
+        events: { 
+          unsubscribe: true,
+          profile: true,
+        },
+      });
+
+      await context.store?.put<WebhookData>(WEBHOOK_DATA_STORE_KEY, {
+        id: enabledWebhookId,
+        listId: context.propsValue.list_id as string,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to enable unsubscribe webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async onDisable(context): Promise<void> {
+    try {
+      const webhookData = await context.store?.get<WebhookData>(WEBHOOK_DATA_STORE_KEY);
+
+      if (webhookData === undefined || webhookData === null) {
+        return;
+      }
+
+      const token = getAccessTokenOrThrow(context.auth);
+      const server = await mailchimpCommon.getMailChimpServerPrefix(token);
+
+      await mailchimpCommon.disableWebhookRequest({
+        server,
+        token,
+        listId: webhookData.listId,
+        webhookId: webhookData.id,
+      });
+    } catch (error: any) {
+      console.error(`Failed to disable unsubscribe webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as any;
+
+      if (request === undefined || request.type !== 'unsubscribe') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'member_unsubscribed',
+        event_category: 'Unsubscribe Event',
+        processed_at: new Date().toISOString(),
+        unsubscribe_summary: getUnsubscribeEventSummary(request),
+        business_context: {
+          audience_churn: true,
+          retention_concern: true,
+          feedback_opportunity: true,
+          re_engagement_potential: 'medium',
+        },
+        retention_insights: {
+          subscriber_lifetime: calculateSubscriberLifetime(request),
+          engagement_level: assessEngagementLevel(request),
+          churn_risk_factors: identifyChurnFactors(request),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing unsubscribe webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.