@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

package/src/lib/triggers/link-clicked-trigger.ts

@@ -0,0 +1,244 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { MailChimpClickWebhookRequest } from '../common/types';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_link_clicked_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getLinkClickEventSummary = (request: MailChimpClickWebhookRequest): any => {
+  const data = request.data || {};
+  return {
+    email: data.email || 'N/A',
+    subscriber_id: data.id || 'N/A',
+    list_id: data.list_id || 'N/A',
+    campaign_id: data.campaign_id || 'N/A',
+    url: data.url || 'N/A',
+    ip_address: data.ip || 'N/A',
+    user_agent: data.user_agent || 'N/A',
+    timestamp: data.timestamp || request.fired_at || 'N/A',
+    click_data: {
+      url: data.url || 'N/A',
+      link_id: data.link_id || 'N/A',
+      click_count: data.click_count || 1,
+      is_first_click: data.is_first_click || false,
+    },
+    location_data: extractLocationData(data),
+    device_info: extractDeviceInfo(data.user_agent),
+    engagement_metrics: calculateClickMetrics(data),
+  };
+};
+
+const extractLocationData = (data: any): any => {
+  return {
+    ip_address: data.ip || 'N/A',
+    country: data.country || 'N/A',
+    region: data.region || 'N/A',
+    city: data.city || 'N/A',
+    timezone: data.timezone || 'N/A',
+    latitude: data.latitude || 'N/A',
+    longitude: data.longitude || 'N/A',
+  };
+};
+
+const extractDeviceInfo = (userAgent: string): any => {
+  if (!userAgent) return { device_type: 'Unknown', browser: 'Unknown', os: 'Unknown' };
+  
+  const isMobile = /Mobile|Android|iPhone|iPad|Windows Phone/i.test(userAgent);
+  const isTablet = /iPad|Android(?=.*\bMobile\b)(?=.*\bSafari\b)/i.test(userAgent);
+  
+  let deviceType = 'Desktop';
+  if (isTablet) deviceType = 'Tablet';
+  else if (isMobile) deviceType = 'Mobile';
+  
+  return {
+    device_type: deviceType,
+    user_agent: userAgent,
+    is_mobile: isMobile,
+    is_tablet: isTablet,
+    is_desktop: !isMobile && !isTablet,
+  };
+};
+
+const calculateClickMetrics = (data: any): any => {
+  return {
+    click_count: data.click_count || 1,
+    is_first_click: data.is_first_click || false,
+    click_rate: data.click_rate || 0,
+    engagement_score: data.member_rating || 0,
+    vip_status: data.vip || false,
+    link_engagement: data.url ? 'High' : 'Low',
+  };
+};
+
+const assessClickEngagementLevel = (data: any): string => {
+  const rating = data.member_rating || 0;
+  const isVip = data.vip || false;
+  const clickCount = data.click_count || 1;
+  
+  if (isVip || rating >= 4) return 'High';
+  if (rating >= 2 || clickCount > 1) return 'Medium';
+  return 'Low';
+};
+
+const identifyClickAutomationOpportunities = (data: any): string[] => {
+  const opportunities = [];
+  
+  if (data.is_first_click) {
+    opportunities.push('First-time clicker - conversion funnel opportunity');
+  }
+  
+  if (data.member_rating && data.member_rating >= 4) {
+    opportunities.push('High engagement - product recommendation opportunity');
+  }
+  
+  if (data.vip) {
+    opportunities.push('VIP subscriber - exclusive offer opportunity');
+  }
+  
+  if (data.url && data.url.includes('product')) {
+    opportunities.push('Product page click - purchase intent opportunity');
+  }
+  
+  return opportunities.length > 0 ? opportunities : ['Standard click tracking'];
+};
+
+const assessConversionPotential = (data: any): string => {
+  if (data.url?.includes('product') || data.url?.includes('shop')) {
+    return 'High - Product page engagement';
+  }
+  if (data.url?.includes('checkout') || data.url?.includes('cart')) {
+    return 'Very High - Purchase intent';
+  }
+  if (data.url?.includes('signup') || data.url?.includes('register')) {
+    return 'High - Registration intent';
+  }
+  return 'Medium - General engagement';
+};
+
+export const mailChimpLinkClickedTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'link_clicked',
+  displayName: 'Link Clicked',
+  description: 'Fires when a recipient clicks a specified link in a campaign',
+  aiMetadata: {
+    description: 'Fires when a recipient in the selected audience (list) clicks a link in a campaign email. The event carries the subscriber email, campaign id, clicked URL, and client/location metadata.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'click',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      campaign_id: 'campaign_123',
+      email: 'user@example.com',
+      url: 'https://example.com/product-page',
+      link_id: 'link_456',
+      ip: '192.168.1.100',
+      user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      timestamp: '2024-01-15T10:30:00Z',
+      click_count: 1,
+      is_first_click: true,
+      click_rate: 0.25,
+      member_rating: 4,
+      vip: false,
+      country: 'US',
+      region: 'CA',
+      city: 'San Francisco',
+      timezone: 'America/Los_Angeles',
+      latitude: 37.7749,
+      longitude: -122.4194,
+    },
+  },
+
+  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: { 
+          click: 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 link clicked 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 link clicked webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as MailChimpClickWebhookRequest;
+
+      if (!request || request.type !== 'click') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'link_clicked',
+        event_category: 'Link Engagement',
+        processed_at: new Date().toISOString(),
+        click_summary: getLinkClickEventSummary(request),
+        business_context: {
+          link_engagement: true,
+          conversion_tracking: true,
+          subscriber_behavior: true,
+          automation_trigger: true,
+        },
+        click_insights: {
+          device_type: extractDeviceInfo(request.data?.user_agent).device_type,
+          location: extractLocationData(request.data),
+          engagement_level: assessClickEngagementLevel(request.data),
+          automation_potential: identifyClickAutomationOpportunities(request.data),
+          conversion_opportunity: assessConversionPotential(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing link clicked webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/src/lib/triggers/new-campaign-trigger.ts

@@ -0,0 +1,149 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { MailChimpCampaignWebhookRequest } from '../common/types';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_campaign_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getCampaignEventSummary = (request: MailChimpCampaignWebhookRequest): any => {
+  const data = request.data;
+  return {
+    campaign_id: data.campaign_id,
+    campaign_title: data.campaign_title,
+    campaign_subject: data.campaign_subject,
+    campaign_send_time: data.campaign_send_time,
+    campaign_status: data.campaign_status,
+    list_id: data.list_id,
+    subscriber_id: data.id,
+    event_timestamp: request.fired_at,
+    campaign_type: inferCampaignType(data),
+    delivery_status: assessDeliveryStatus(data),
+  };
+};
+
+const inferCampaignType = (data: any): string => {
+  if (data.campaign_title?.toLowerCase().includes('welcome')) return 'Welcome Series';
+  if (data.campaign_title?.toLowerCase().includes('newsletter')) return 'Newsletter';
+  if (data.campaign_title?.toLowerCase().includes('promo')) return 'Promotional';
+  if (data.campaign_title?.toLowerCase().includes('abandoned')) return 'Abandoned Cart';
+  return 'Standard Campaign';
+};
+
+const assessDeliveryStatus = (data: any): string => {
+  const status = data.campaign_status || '';
+  if (status === 'sent') return 'Delivered';
+  if (status === 'sending') return 'In Progress';
+  if (status === 'scheduled') return 'Scheduled';
+  if (status === 'paused') return 'Paused';
+  if (status === 'canceled') return 'Canceled';
+  return 'Unknown';
+};
+
+// Note: Campaign webhook data doesn't include performance metrics
+// These would need to be fetched separately via the campaigns API if needed
+
+export const mailChimpNewCampaignTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'new_campaign',
+  displayName: 'New Campaign',
+  description: 'Fires when a new campaign is created or sent',
+  aiMetadata: {
+    description: 'Fires on a campaign event tied to the selected audience (list) — when a campaign is created or sent. The event carries the campaign id, title, subject, send time, and status.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'campaign',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      campaign_id: 'campaign_123',
+      campaign_title: 'Welcome Campaign',
+      campaign_subject: 'Welcome to our newsletter',
+      campaign_send_time: '2024-01-15T10:30:00Z',
+      campaign_status: 'sent',
+    },
+  },
+
+  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: { 
+          campaign: 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 campaign 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 campaign webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as MailChimpCampaignWebhookRequest;
+
+      if (!request || request.type !== 'campaign') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'campaign_event',
+        event_category: 'Campaign Activity',
+        processed_at: new Date().toISOString(),
+        campaign_summary: getCampaignEventSummary(request),
+        campaign_insights: {
+          campaign_type: inferCampaignType(request.data),
+          delivery_status: assessDeliveryStatus(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing campaign webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/src/lib/triggers/new-customer-trigger.ts

@@ -0,0 +1,230 @@
+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_new_customer_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getNewCustomerEventSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    customer_id: data.customer_id || data.id || 'N/A',
+    store_id: data.store_id || 'N/A',
+    email: data.email || 'N/A',
+    first_name: data.first_name || 'N/A',
+    last_name: data.last_name || 'N/A',
+    company: data.company || 'N/A',
+    phone: data.phone || 'N/A',
+    address: data.address || 'N/A',
+    created_at: data.created_at || request.fired_at || 'N/A',
+    customer_type: data.customer_type || 'new',
+    has_orders: data.orders_count > 0,
+    total_spent: data.total_spent || 0,
+    orders_count: data.orders_count || 0,
+  };
+};
+
+const extractCustomerAddress = (address: any): any => {
+  if (!address) return null;
+  
+  return {
+    street_address: {
+      primary: address.address1 || 'N/A',
+      secondary: address.address2 || 'N/A',
+    },
+    city: address.city || 'N/A',
+    state_province: {
+      name: address.province || 'N/A',
+      code: address.province_code || 'N/A',
+    },
+    postal_code: address.postal_code || 'N/A',
+    country: {
+      name: address.country || 'N/A',
+      code: address.country_code || 'N/A',
+    },
+    full_address: [
+      address.address1,
+      address.address2,
+      address.city,
+      address.province,
+      address.postal_code,
+      address.country,
+    ].filter(Boolean).join(', '),
+  };
+};
+
+const assessCustomerValue = (data: any): string => {
+  const totalSpent = data.total_spent || 0;
+  const ordersCount = data.orders_count || 0;
+  
+  if (totalSpent >= 1000 || ordersCount >= 10) return 'High Value';
+  if (totalSpent >= 100 || ordersCount >= 3) return 'Medium Value';
+  return 'New Customer';
+};
+
+const identifyCustomerOpportunities = (data: any): string[] => {
+  const opportunities = [];
+  
+  if (data.orders_count === 0) {
+    opportunities.push('First-time customer - welcome series opportunity');
+  }
+  
+  if (data.total_spent > 0) {
+    opportunities.push('Returning customer - loyalty program opportunity');
+  }
+  
+  if (data.company) {
+    opportunities.push('Business customer - B2B marketing opportunity');
+  }
+  
+  if (data.address) {
+    opportunities.push('Geographic targeting opportunity');
+  }
+  
+  return opportunities.length > 0 ? opportunities : ['Standard customer onboarding'];
+};
+
+const assessMarketingPotential = (data: any): string => {
+  if (data.opt_in_status && data.member_rating >= 4) {
+    return 'High - Opted in with high engagement';
+  }
+  if (data.opt_in_status) {
+    return 'Medium - Opted in for marketing';
+  }
+  if (data.company) {
+    return 'Medium - Business customer potential';
+  }
+  return 'Low - Limited marketing consent';
+};
+
+export const mailChimpNewCustomerTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'new_customer',
+  displayName: 'New Customer',
+  description: 'Fires when a new customer is added to a connected store',
+  aiMetadata: {
+    description: 'Fires when a new e-commerce customer is added to a connected Mailchimp store. The event carries the customer id, email, name, and store/order context.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'customer',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: 'customer_123',
+      customer_id: 'customer_123',
+      store_id: 'store_456',
+      email: 'customer@example.com',
+      first_name: 'John',
+      last_name: 'Doe',
+      company: 'Example Corp',
+      phone: '+1-555-0123',
+      address: {
+        address1: '123 Main St',
+        address2: 'Suite 100',
+        city: 'Anytown',
+        province: 'California',
+        province_code: 'CA',
+        postal_code: '12345',
+        country: 'United States',
+        country_code: 'US',
+      },
+      created_at: '2024-01-15T10:30:00Z',
+      customer_type: 'new',
+      orders_count: 0,
+      total_spent: 0,
+      opt_in_status: true,
+      tags: ['new-customer', 'ecommerce'],
+      member_rating: 5,
+      vip: false,
+    },
+  },
+
+  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: { 
+          customer: 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 new customer 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 new customer webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as any;
+
+      if (!request || request.type !== 'customer') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'new_customer',
+        event_category: 'Customer Registration',
+        processed_at: new Date().toISOString(),
+        customer_summary: getNewCustomerEventSummary(request),
+        business_context: {
+          customer_acquisition: true,
+          ecommerce_tracking: true,
+          onboarding_automation: true,
+          customer_segmentation: true,
+        },
+        customer_insights: {
+          customer_value: assessCustomerValue(request.data),
+          address_details: extractCustomerAddress(request.data?.address),
+          automation_opportunities: identifyCustomerOpportunities(request.data),
+          marketing_potential: assessMarketingPotential(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing new customer webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});