@divyacon/piece-mailchimp 0.0.0-stage → 0.1.0

package/src/lib/common/types.ts

@@ -0,0 +1,410 @@
+export enum MailChimpWebhookType {
+  /**
+   * triggers when a list subscriber is added.
+   */
+  SUBSCRIBE = 'subscribe',
+
+  /**
+   * triggers when a list member unsubscribes.
+   */
+  UNSUBSCRIBE = 'unsubscribe',
+
+  /**
+   * triggers when a subscriber's profile is updated.
+   */
+  PROFILE = 'profile',
+
+  /**
+   * triggers when a subscriber's email address is cleaned from the list.
+   */
+  CLEANED = 'cleaned',
+
+  /**
+   * triggers when a subscriber's email address is changed.
+   */
+  UP_EMAIL = 'upemail',
+
+  /**
+   * triggers when a campaign is sent or cancelled.
+   */
+  CAMPAIGN = 'campaign',
+
+  /**
+   * triggers when a subscriber's email address is changed.
+   */
+  PENDING = 'pending',
+
+  /**
+   * transactional
+   */
+  TRANSACTIONAL = 'transactional',
+
+  /**
+   * triggers when a subscriber clicks a link in a campaign.
+   */
+  CLICK = 'click',
+
+  /**
+   * triggers when a subscriber opens an email in a campaign.
+   */
+  OPEN = 'open',
+}
+
+export enum MailChimpEmailType {
+  HTML = 'html',
+  TEXT = 'text',
+}
+
+export type MailChimpWebhookRequest<Type extends MailChimpWebhookType, Data> = {
+  type: Type;
+  fired_at: string;
+  data: Data;
+};
+
+export type MailChimpSubscribeWebhookData = {
+  id: string;
+  list_id: string;
+  email: string;
+  email_type: MailChimpEmailType;
+  ip_opt: string;
+  ip_signup: string;
+  merges: Record<string, string>;
+};
+
+export type MailChimpSubscribeWebhookRequest = MailChimpWebhookRequest<
+  MailChimpWebhookType.SUBSCRIBE,
+  MailChimpSubscribeWebhookData
+>;
+
+export type MailChimpClickWebhookData = {
+  id: string;
+  list_id: string;
+  campaign_id: string;
+  email: string;
+  url: string;
+  ip: string;
+  user_agent: string;
+  timestamp?: string;
+  link_id?: string;
+  click_count?: number;
+  is_first_click?: boolean;
+};
+
+export type MailChimpClickWebhookRequest = MailChimpWebhookRequest<
+  MailChimpWebhookType.CLICK,
+  MailChimpClickWebhookData
+>;
+
+export type MailChimpOpenWebhookData = {
+  id: string;
+  list_id: string;
+  campaign_id: string;
+  email: string;
+  ip: string;
+  user_agent: string;
+  timestamp: string;
+};
+
+export type MailChimpOpenWebhookRequest = MailChimpWebhookRequest<
+  MailChimpWebhookType.OPEN,
+  MailChimpOpenWebhookData
+>;
+
+export type MailChimpCampaignWebhookData = {
+  id: string;
+  list_id: string;
+  campaign_id: string;
+  campaign_title: string;
+  campaign_subject: string;
+  campaign_send_time: string;
+  campaign_status: string;
+};
+
+export type MailChimpCampaignWebhookRequest = MailChimpWebhookRequest<
+  MailChimpWebhookType.CAMPAIGN,
+  MailChimpCampaignWebhookData
+>;
+
+// Extended Mailchimp API types since the official @types/mailchimp__mailchimp_marketing package is incomplete
+
+export interface MailchimpClient {
+  setConfig(config: MailchimpConfig): void;
+  campaigns: MailchimpCampaignsApi;
+  lists: MailchimpListsApi;
+  reports: MailchimpReportsApi;
+  searchCampaigns: MailchimpSearchCampaignsApi;
+  ecommerce: MailchimpEcommerceApi;
+}
+
+export interface MailchimpSearchCampaignsApi {
+  search(params: any): Promise<any>;
+}
+
+export interface MailchimpEcommerceApi {
+  getAllStoreCustomers(storeId: string, opts?: any): Promise<any>;
+  stores(opts?: any): Promise<any>;
+}
+
+export interface MailchimpConfig {
+  accessToken: string;
+  server: string;
+}
+
+export interface MailchimpCampaignsApi {
+  create(data: CampaignCreateData): Promise<Campaign>;
+  get(campaignId: string, opts?: CampaignGetOptions): Promise<Campaign>;
+  update(campaignId: string, data: Partial<CampaignCreateData>): Promise<Campaign>;
+  remove(campaignId: string): Promise<void>;
+  send(campaignId: string): Promise<void>;
+  setContent(campaignId: string, content: CampaignContentData): Promise<any>;
+  list(opts?: any): Promise<any>;
+}
+
+export interface MailchimpListsApi {
+  createList(data: any): Promise<any>;
+  deleteListMember(listId: string, subscriberHash: string): Promise<void>;
+  addListMember(listId: string, data: any): Promise<any>;
+  updateListMember(listId: string, subscriberHash: string, data: any): Promise<any>;
+  setListMember(listId: string, subscriberHash: string, data: any, opts?: any): Promise<any>;
+  batchListMembers(listId: string, data: any, opts?: any): Promise<any>;
+  getAllLists(options?: any): Promise<any>;
+  tagSearch(listId: string, opts?: any): Promise<any>;
+  updateListMemberTags(listId: string, subscriberHash: string, data: any): Promise<any>;
+  createSegment(listId: string, data: CreateSegmentData): Promise<Segment>;
+  createListMemberEvent(listId: string, subscriberHash: string, data: CreateListMemberEventData): Promise<void>;
+}
+
+export interface CreateSegmentData {
+  name: string;
+  static_segment?: string[];
+}
+
+export interface Segment {
+  id: number;
+  name: string;
+  list_id: string;
+  type: string;
+  created_at: string;
+  updated_at: string;
+  member_count: number;
+}
+
+export interface CreateListMemberEventData {
+  name: string;
+  properties?: Record<string, unknown>;
+  occurred_at?: string;
+}
+
+export interface MailchimpReportsApi {
+  getCampaignReport(campaignId: string, opts?: CampaignReportOptions): Promise<CampaignReport>;
+  getAllCampaignReports(opts?: any): Promise<any>;
+}
+
+export interface CampaignCreateData {
+  type: string;
+  recipients: {
+    list_id: string;
+  };
+  settings: {
+    subject_line: string;
+    title: string;
+    from_name: string;
+    from_email: string;
+    reply_to: string;
+    to_name?: string;
+  };
+}
+
+export interface CampaignContentData {
+  html?: string;
+  plain_text?: string;
+  url?: string;
+  template?: {
+    id: string;
+    sections?: Record<string, any>;
+  };
+}
+
+export interface CampaignGetOptions {
+  fields?: string;
+  exclude_fields?: string;
+}
+
+export interface CampaignReportOptions {
+  fields?: string;
+  exclude_fields?: string;
+}
+
+export interface CampaignReport {
+  id: string;
+  campaign_title: string;
+  type: string;
+  list_id: string;
+  list_is_active: boolean;
+  list_name: string;
+  subject_line: string;
+  preview_text?: string;
+  emails_sent: number;
+  abuse_reports: number;
+  unsubscribed: number;
+  send_time?: string;
+  rss_last_send?: string;
+  bounces?: {
+    hard_bounces: number;
+    soft_bounces: number;
+    syntax_errors: number;
+  };
+  forwards?: {
+    forwards_count: number;
+    forwards_opens: number;
+  };
+  opens?: {
+    opens_total: number;
+    unique_opens: number;
+    open_rate: number;
+    last_open?: string;
+    proxy_excluded_opens?: number;
+    proxy_excluded_unique_opens?: number;
+    proxy_excluded_open_rate?: number;
+  };
+  clicks?: {
+    clicks_total: number;
+    unique_clicks: number;
+    unique_subscriber_clicks: number;
+    click_rate: number;
+    last_click?: string;
+  };
+  facebook_likes?: {
+    recipient_likes: number;
+    unique_likes: number;
+    facebook_likes: number;
+  };
+  industry_stats?: {
+    type: string;
+    open_rate: number;
+    click_rate: number;
+    bounce_rate: number;
+    unopen_rate: number;
+    unsub_rate: number;
+    abuse_rate: number;
+  };
+  list_stats?: {
+    sub_rate: number;
+    unsub_rate: number;
+    open_rate: number;
+    proxy_excluded_open_rate: number;
+    click_rate: number;
+  };
+  ab_split?: {
+    a?: {
+      bounces: number;
+      abuse_reports: number;
+      unsubs: number;
+      recipient_clicks: number;
+      forwards: number;
+      forwards_opens: number;
+      opens: number;
+      last_open?: string;
+      unique_opens: number;
+    };
+    b?: {
+      bounces: number;
+      abuse_reports: number;
+      unsubs: number;
+      recipient_clicks: number;
+      forwards: number;
+      forwards_opens: number;
+      opens: number;
+      last_open?: string;
+      unique_opens: number;
+    };
+  };
+  timewarp?: Array<{
+    gmt_offset: number;
+    opens: number;
+    last_open?: string;
+    unique_opens: number;
+    clicks: number;
+    last_click?: string;
+    unique_clicks: number;
+    bounces: number;
+  }>;
+  timeseries?: Array<{
+    timestamp: string;
+    emails_sent: number;
+    unique_opens: number;
+    proxy_excluded_unique_opens: number;
+    recipients_clicks: number;
+  }>;
+  share_report?: {
+    share_url: string;
+    share_password: string;
+  };
+  ecommerce?: {
+    total_orders: number;
+    total_spent: number;
+    total_revenue: number;
+    currency_code: string;
+  };
+  delivery_status?: {
+    enabled: boolean;
+    can_cancel: boolean;
+    status: string;
+    emails_sent: number;
+    emails_canceled: number;
+  };
+  _links?: Array<{
+    rel: string;
+    href: string;
+    method: string;
+  }>;
+}
+
+export interface Campaign {
+  id: string;
+  web_id: number;
+  parent_campaign_id?: string;
+  type: string;
+  create_time: string;
+  archive_url: string;
+  long_archive_url?: string;
+  status: string;
+  emails_sent: number;
+  send_time?: string;
+  content_type: string;
+  needs_block_refresh?: boolean;
+  resendable?: boolean;
+  recipients: {
+    list_id: string;
+    list_is_active: boolean;
+    list_name: string;
+    segment_text: string;
+    recipient_count: number;
+  };
+  settings: {
+    subject_line: string;
+    title: string;
+    from_name: string;
+    reply_to: string;
+    to_name: string;
+    content_type: string;
+    content_url?: string;
+    template_id?: number;
+  };
+  variate_settings?: any;
+  tracking?: any;
+  rss_opts?: any;
+  ab_split_opts?: any;
+  social_card?: any;
+  report_summary?: any;
+  delivery_status?: any;
+  resend_shortcut_eligibility?: any;
+  resend_shortcut_usage?: any;
+  _links: Array<{
+    rel: string;
+    href: string;
+    method: string;
+    targetSchema?: string;
+    schema?: string;
+  }>;
+}

package/src/lib/triggers/email-opened-trigger.ts

@@ -0,0 +1,216 @@
+import { createTrigger, TriggerStrategy, Property } from '@agnocon/pieces-framework';
+import { getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { mailchimpCommon } from '../common';
+import { MailChimpOpenWebhookRequest } from '../common/types';
+import { mailchimpAuth } from '../..';
+
+const WEBHOOK_DATA_STORE_KEY = 'mail_chimp_email_opened_webhook_data';
+
+type WebhookData = {
+  id: string;
+  listId: string;
+};
+
+const getEmailOpenEventSummary = (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',
+    campaign_id: data.campaign_id || 'N/A',
+    ip_address: data.ip || 'N/A',
+    user_agent: data.user_agent || 'N/A',
+    timestamp: data.timestamp || request.fired_at || 'N/A',
+    location_data: extractLocationData(data),
+    device_info: extractDeviceInfo(data.user_agent),
+    engagement_metrics: calculateEngagementMetrics(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 calculateEngagementMetrics = (data: any): any => {
+  return {
+    open_count: data.open_count || 1,
+    is_first_open: data.is_first_open || false,
+    open_rate: data.open_rate || 0,
+    engagement_score: data.member_rating || 0,
+    vip_status: data.vip || false,
+  };
+};
+
+const assessEngagementLevel = (data: any): string => {
+  const rating = data.member_rating || 0;
+  const isVip = data.vip || false;
+  const openCount = data.open_count || 1;
+  
+  if (isVip || rating >= 4) return 'High';
+  if (rating >= 2 || openCount > 1) return 'Medium';
+  return 'Low';
+};
+
+const identifyAutomationOpportunities = (data: any): string[] => {
+  const opportunities = [];
+  
+  if (data.is_first_open) {
+    opportunities.push('First-time opener - welcome series opportunity');
+  }
+  
+  if (data.member_rating && data.member_rating >= 4) {
+    opportunities.push('High engagement - upsell opportunity');
+  }
+  
+  if (data.vip) {
+    opportunities.push('VIP subscriber - exclusive content opportunity');
+  }
+  
+  return opportunities.length > 0 ? opportunities : ['Standard engagement tracking'];
+};
+
+export const mailChimpEmailOpenedTrigger = createTrigger({
+  auth: mailchimpAuth,
+  name: 'email_opened',
+  displayName: 'Email Opened',
+  description: 'Fires when a recipient opens a an email in a specific campaign',
+  aiMetadata: {
+    description: 'Fires when a recipient in the selected audience (list) opens a campaign email. The event carries the subscriber email, campaign id, and client/location metadata.',
+  },
+  type: TriggerStrategy.WEBHOOK,
+  props: {
+    list_id: mailchimpCommon.mailChimpListIdDropdown,
+  },
+  sampleData: {
+    type: 'open',
+    fired_at: '2024-01-15T10:30:00Z',
+    data: {
+      id: '8a25ff1d98',
+      list_id: 'a6b5da1054',
+      campaign_id: 'campaign_123',
+      email: 'user@example.com',
+      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',
+      open_count: 1,
+      is_first_open: true,
+      open_rate: 0.85,
+      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: { 
+          open: 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 email opened 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 email opened webhook: ${error.message || JSON.stringify(error)}`);
+    }
+  },
+
+  async run(context): Promise<unknown[]> {
+    try {
+      const request = context.payload.body as MailChimpOpenWebhookRequest;
+
+      if (!request || request.type !== 'open') {
+        return [];
+      }
+
+      const enhancedRequest = {
+        ...request,
+        trigger_type: 'email_opened',
+        event_category: 'Email Engagement',
+        processed_at: new Date().toISOString(),
+        open_summary: getEmailOpenEventSummary(request),
+        business_context: {
+          email_engagement: true,
+          performance_tracking: true,
+          subscriber_behavior: true,
+          automation_trigger: true,
+        },
+        engagement_insights: {
+          device_type: extractDeviceInfo(request.data?.user_agent).device_type,
+          location: extractLocationData(request.data),
+          engagement_level: assessEngagementLevel(request.data),
+          automation_potential: identifyAutomationOpportunities(request.data),
+        },
+      };
+
+      return [enhancedRequest];
+    } catch (error: any) {
+      console.error(`Error processing email opened webhook: ${error.message || JSON.stringify(error)}`);
+      return [];
+    }
+  },
+});