@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,288 @@
+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_order_webhook_data';
+
+type WebhookData = {
+  id: string;
+  storeId: string;
+};
+
+const getNewOrderEventSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    order_id: data.order_id || data.id || 'N/A',
+    store_id: data.store_id || 'N/A',
+    customer_id: data.customer_id || 'N/A',
+    customer_email: data.customer_email || 'N/A',
+    order_total: data.order_total || 0,
+    currency: data.currency || 'USD',
+    order_status: data.order_status || 'pending',
+    created_at: data.created_at || request.fired_at || 'N/A',
+    items_count: data.items_count || 0,
+    shipping_total: data.shipping_total || 0,
+    tax_total: data.tax_total || 0,
+    discount_total: data.discount_total || 0,
+  };
+};
+
+const extractOrderItems = (items: any[]): any => {
+  if (!items || !Array.isArray(items)) return [];
+  
+  return items.map(item => ({
+    product_id: item.product_id || 'N/A',
+    product_title: item.product_title || 'N/A',
+    product_variant_id: item.product_variant_id || 'N/A',
+    quantity: item.quantity || 1,
+    price: item.price || 0,
+    total: item.total || 0,
+    category: item.category || 'N/A',
+    tags: item.tags || [],
+  }));
+};
+
+const extractOrderAddress = (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 assessOrderValue = (data: any): string => {
+  const orderTotal = data.order_total || 0;
+  
+  if (orderTotal >= 500) return 'High Value';
+  if (orderTotal >= 100) return 'Medium Value';
+  if (orderTotal >= 50) return 'Standard Value';
+  return 'Low Value';
+};
+
+const identifyOrderOpportunities = (data: any): string[] => {
+  const opportunities = [];
+  
+  if (data.order_status === 'fulfilled') {
+    opportunities.push('Order fulfilled - follow-up opportunity');
+  }
+  
+  if (data.order_status === 'shipped') {
+    opportunities.push('Order shipped - delivery tracking opportunity');
+  }
+  
+  if (data.items_count > 1) {
+    opportunities.push('Multiple items - cross-sell opportunity');
+  }
+  
+  if (data.order_total > 100) {
+    opportunities.push('High-value order - VIP treatment opportunity');
+  }
+  
+  if (data.shipping_total > 0) {
+    opportunities.push('Shipping paid - loyalty program opportunity');
+  }
+  
+  return opportunities.length > 0 ? opportunities : ['Standard order processing'];
+};
+
+const calculateOrderMetrics = (data: any): any => {
+  const orderTotal = data.order_total || 0;
+  const shippingTotal = data.shipping_total || 0;
+  const taxTotal = data.tax_total || 0;
+  const discountTotal = data.discount_total || 0;
+  
+  return {
+    subtotal: orderTotal - shippingTotal - taxTotal + discountTotal,
+    net_revenue: orderTotal - discountTotal,
+    profit_margin: orderTotal > 0 ? ((orderTotal - discountTotal) / orderTotal) * 100 : 0,
+    average_item_value: data.items_count > 0 ? orderTotal / data.items_count : 0,
+    shipping_percentage: orderTotal > 0 ? (shippingTotal / orderTotal) * 100 : 0,
+  };
+};
+
+export const mailChimpNewOrderTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'new_order',
+  displayName: 'New Order',
+  description: 'Fires when a new order is created in the connected store',
+  aiMetadata: {
+    description: 'Fires when a new e-commerce order is created in the selected connected Mailchimp store. The event carries the order id, customer, total, currency, status, and line items.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    store_id: mailchimpCommon.mailChimpStoreIdDropdown,
+  },
+  sampleData: {
+    type: 'order',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: 'order_123',
+      order_id: 'order_123',
+      store_id: 'store_456',
+      customer_id: 'customer_789',
+      customer_email: 'customer@example.com',
+      order_total: 299.99,
+      currency: 'USD',
+      order_status: 'pending',
+      created_at: '2024-01-15T10:30:00Z',
+      items_count: 3,
+      shipping_total: 15.99,
+      tax_total: 24.00,
+      discount_total: 25.00,
+      items: [
+        {
+          product_id: 'prod_001',
+          product_title: 'Premium Widget',
+          product_variant_id: 'var_001',
+          quantity: 2,
+          price: 89.99,
+          total: 179.98,
+          category: 'Widgets',
+          tags: ['premium', 'bestseller'],
+        },
+        {
+          product_id: 'prod_002',
+          product_title: 'Standard Widget',
+          product_variant_id: 'var_002',
+          quantity: 1,
+          price: 119.99,
+          total: 119.99,
+          category: 'Widgets',
+          tags: ['standard'],
+        },
+      ],
+      shipping_address: {
+        address1: '123 Main St',
+        address2: 'Suite 100',
+        city: 'Anytown',
+        province: 'California',
+        province_code: 'CA',
+        postal_code: '12345',
+        country: 'United States',
+        country_code: 'US',
+      },
+      billing_address: {
+        address1: '123 Main St',
+        address2: 'Suite 100',
+        city: 'Anytown',
+        province: 'California',
+        province_code: 'CA',
+        postal_code: '12345',
+        country: 'United States',
+        country_code: 'US',
+      },
+      customer: {
+        first_name: 'John',
+        last_name: 'Doe',
+        company: 'Example Corp',
+        phone: '+1-555-0123',
+      },
+    },
+  },
+
+  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.store_id!,
+        token: accessToken,
+        webhookUrl: context.webhookUrl!,
+        events: { 
+          order: true,
+          customer: true,
+        },
+      });
+
+      await context.store?.put<WebhookData>(WEBHOOK_DATA_STORE_KEY, {
+        id: enabledWebhookId,
+        storeId: context.propsValue.store_id!,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to enable new order 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.storeId,
+        webhookId: webhookData.id,
+      });
+    } catch (error: any) {
+      console.error(`Failed to disable new order webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as any;
+
+      if (request === undefined || request.type !== 'order') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'new_order',
+        event_category: 'Order Creation',
+        processed_at: new Date().toISOString(),
+        order_summary: getNewOrderEventSummary(request),
+        business_context: {
+          order_management: true,
+          ecommerce_tracking: true,
+          revenue_tracking: true,
+          customer_engagement: true,
+        },
+        order_insights: {
+          order_value: assessOrderValue(request.data),
+          order_items: extractOrderItems(request.data?.items),
+          shipping_address: extractOrderAddress(request.data?.shipping_address),
+          billing_address: extractOrderAddress(request.data?.billing_address),
+          automation_opportunities: identifyOrderOpportunities(request.data),
+          financial_metrics: calculateOrderMetrics(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing new order webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});

package/src/lib/triggers/new-segment-tag-subscriber-trigger.ts

@@ -0,0 +1,286 @@
+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_segment_tag_subscriber_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+  segmentId?: string;
+  tagName?: string;
+};
+
+const getSegmentTagEventSummary = (request: any): any => {
+  const data = request.data || {};
+  return {
+    subscriber_id: data.id || 'N/A',
+    list_id: data.list_id || 'N/A',
+    email: data.email || 'N/A',
+    segment_id: data.segment_id || 'N/A',
+    segment_name: data.segment_name || 'N/A',
+    tag_name: data.tag_name || 'N/A',
+    tag_category: data.tag_category || 'N/A',
+    event_type: data.event_type || 'segment_join',
+    timestamp: data.timestamp || request.fired_at || 'N/A',
+    merge_fields: data.merges || {},
+    member_rating: data.member_rating || 0,
+    vip_status: data.vip || false,
+    language: data.language || 'en',
+  };
+};
+
+const extractSegmentInfo = (data: any): any => {
+  return {
+    segment_id: data.segment_id || 'N/A',
+    segment_name: data.segment_name || 'N/A',
+    segment_type: data.segment_type || 'static',
+    segment_match: data.segment_match || 'any',
+    segment_conditions: data.segment_conditions || [],
+    segment_count: data.segment_count || 0,
+    segment_created: data.segment_created || 'N/A',
+    segment_updated: data.segment_updated || 'N/A',
+  };
+};
+
+const extractTagInfo = (data: any): any => {
+  return {
+    tag_name: data.tag_name || 'N/A',
+    tag_category: data.tag_category || 'N/A',
+    tag_color: data.tag_color || 'N/A',
+    tag_count: data.tag_count || 0,
+    tag_created: data.tag_created || 'N/A',
+    tag_updated: data.tag_updated || 'N/A',
+    tag_notes: data.tag_notes || 'N/A',
+  };
+};
+
+const assessSegmentEngagement = (data: any): string => {
+  const rating = data.member_rating || 0;
+  const isVip = data.vip || false;
+  const segmentCount = data.segment_count || 0;
+  
+  if (isVip || rating >= 4) return 'High Engagement';
+  if (rating >= 2 || segmentCount > 1) return 'Medium Engagement';
+  return 'New to Segment';
+};
+
+const identifySegmentOpportunities = (data: any): string[] => {
+  const opportunities = [];
+  
+  if (data.event_type === 'segment_join') {
+    opportunities.push('New segment member - welcome series opportunity');
+  }
+  
+  if (data.event_type === 'tag_added') {
+    opportunities.push('New tag applied - targeted content opportunity');
+  }
+  
+  if (data.member_rating >= 4) {
+    opportunities.push('High engagement - premium content opportunity');
+  }
+  
+  if (data.vip) {
+    opportunities.push('VIP member - exclusive segment opportunity');
+  }
+  
+  if (data.segment_type === 'dynamic') {
+    opportunities.push('Dynamic segment - automated targeting opportunity');
+  }
+  
+  return opportunities.length > 0 ? opportunities : ['Standard segment engagement'];
+};
+
+const calculateSegmentMetrics = (data: any): any => {
+  return {
+    segment_member_count: data.segment_count || 0,
+    segment_growth_rate: data.growth_rate || 0,
+    segment_engagement_score: data.engagement_score || 0,
+    segment_activity_level: data.activity_level || 'low',
+    segment_retention_rate: data.retention_rate || 0,
+    segment_conversion_rate: data.conversion_rate || 0,
+  };
+};
+
+const getEventCategory = (eventType: string): string => {
+  switch (eventType) {
+    case 'segment':
+      return 'Segment Membership';
+    case 'tag':
+      return 'Tag Application';
+    case 'profile':
+      return 'Profile Update';
+    case 'subscribe':
+      return 'New Subscription';
+    default:
+      return 'Unknown Event';
+  }
+};
+
+export const mailChimpNewSegmentTagSubscriberTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'new_segment_tag_subscriber',
+  displayName: 'New Segment Tag Subscriber',
+  description: 'Fires when a subscriber joins a specific segment or tag',
+  aiMetadata: {
+    description: 'Fires when a subscriber in the selected audience (list) joins a segment or is given a tag; an optional segment ID or tag name narrows it to a specific segment/tag, otherwise it monitors all of them. The event carries the subscriber email and segment/tag details.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+    segment_id: Property.ShortText({
+      displayName: 'Segment ID (Optional)',
+      description: 'The specific segment ID to monitor. Leave empty to monitor all segments.',
+      required: false,
+    }),
+    tag_name: Property.ShortText({
+      displayName: 'Tag Name (Optional)',
+      description: 'The specific tag name to monitor. Leave empty to monitor all tags.',
+      required: false,
+    }),
+  },
+  sampleData: {
+    type: 'segment_tag',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      email: 'subscriber@example.com',
+      segment_id: 'segment_123',
+      segment_name: 'High Value Customers',
+      segment_type: 'static',
+      segment_match: 'all',
+      segment_conditions: [
+        {
+          condition_type: 'EmailAddress',
+          op: 'is',
+          field: 'EMAIL',
+          value: 'subscriber@example.com',
+        },
+      ],
+      segment_count: 150,
+      segment_created: '2024-01-01T00:00:00Z',
+      segment_updated: '2024-01-15T10:30:00Z',
+      tag_name: 'premium',
+      tag_category: 'customer_type',
+      tag_color: '#FF6B6B',
+      tag_count: 75,
+      tag_created: '2024-01-01T00:00:00Z',
+      tag_updated: '2024-01-15T10:30:00Z',
+      tag_notes: 'Premium customer segment',
+      event_type: 'segment_join',
+      timestamp: '2024-01-15T10:30:00Z',
+      merges: {
+        EMAIL: 'subscriber@example.com',
+        FNAME: 'John',
+        LNAME: 'Doe',
+        COMPANY: 'Example Corp',
+        PHONE: '+1-555-0123',
+        INTERESTS: 'Premium,High-Value',
+      },
+      member_rating: 5,
+      vip: true,
+      language: 'en',
+      growth_rate: 0.15,
+      engagement_score: 0.85,
+      activity_level: 'high',
+      retention_rate: 0.92,
+      conversion_rate: 0.08,
+    },
+  },
+
+  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,
+        },
+      });
+
+      await context.store?.put<WebhookData>(WEBHOOK_DATA_STORE_KEY, {
+        id: enabledWebhookId,
+        listId: context.propsValue.list_id as string,
+        segmentId: context.propsValue.segment_id,
+        tagName: context.propsValue.tag_name,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to enable segment tag subscriber 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 segment tag subscriber webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as any;
+
+      if (request === undefined || !['segment', 'tag', 'profile', 'subscribe'].includes(request.type)) {
+        return [];
+      }
+
+      const webhookData = await context.store?.get<WebhookData>(WEBHOOK_DATA_STORE_KEY);
+      if (webhookData) {
+        if (webhookData.segmentId && request.data?.segment_id !== webhookData.segmentId) {
+          return [];
+        }
+        if (webhookData.tagName && request.data?.tag_name !== webhookData.tagName) {
+          return [];
+        }
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'segment_tag_subscriber',
+        event_category: getEventCategory(request.type),
+        processed_at: new Date().toISOString(),
+        segment_tag_summary: getSegmentTagEventSummary(request),
+        business_context: {
+          audience_segmentation: true,
+          targeted_marketing: true,
+          automation_trigger: true,
+          customer_insights: true,
+        },
+        segment_tag_insights: {
+          segment_info: extractSegmentInfo(request.data),
+          tag_info: extractTagInfo(request.data),
+          engagement_level: assessSegmentEngagement(request.data),
+          automation_opportunities: identifySegmentOpportunities(request.data),
+          segment_metrics: calculateSegmentMetrics(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing segment tag subscriber webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});