@rawdash/connector-mailchimp 0.0.1

package/dist/index.js

@@ -0,0 +1,652 @@
+// ../../connector-shared/dist/index.js
+var HTTP_CLIENT_VERSION = "0.0.0";
+var DEFAULT_USER_AGENT = `rawdash-connector/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+function connectorUserAgent(connectorId) {
+  return `rawdash-connector-${connectorId}/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+}
+function parseEpoch(value, unit) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (unit === "iso") {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+  }
+  if (typeof value === "string" && value.trim() === "") {
+    return null;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    return null;
+  }
+  const result = unit === "s" ? n * 1e3 : n;
+  return Number.isFinite(result) ? result : null;
+}
+
+// src/mailchimp.ts
+import {
+  BaseConnector,
+  defineConfigFields,
+  defineConnectorDoc,
+  defineResources,
+  makeChunkedCursorGuard,
+  paginateChunked,
+  schemasFromResources,
+  selectActivePhases
+} from "@rawdash/core";
+import { z } from "zod";
+var configFields = defineConfigFields(
+  z.object({
+    apiKey: z.object({ $secret: z.string() }).meta({
+      label: "API key",
+      description: "Mailchimp Marketing API key. The data-center suffix after the dash (e.g. `-us1`) selects the API host. Create one at Profile -> Extras -> API keys.",
+      placeholder: "abc123...-us1",
+      secret: true
+    }),
+    resources: z.array(z.enum(["campaigns", "lists", "automations", "campaign_stats"])).nonempty().optional().meta({
+      label: "Resources",
+      description: "Which Mailchimp resources to sync. Omit to sync all of them."
+    })
+  })
+);
+var doc = defineConnectorDoc({
+  displayName: "Mailchimp",
+  category: "marketing",
+  brandColor: "#FFE01B",
+  tagline: "Sync Mailchimp campaigns, audiences (lists), automations, and per-campaign engagement stats for marketing email analytics.",
+  vendor: {
+    name: "Mailchimp",
+    apiDocs: "https://mailchimp.com/developer/marketing/api/",
+    website: "https://mailchimp.com"
+  },
+  auth: {
+    summary: "A Mailchimp Marketing API key. The data-center suffix after the dash (e.g. `-us1`) selects the API host the connector talks to.",
+    setup: [
+      "In Mailchimp, open Profile -> Extras -> API keys and create a new API key.",
+      "Copy the full key including the trailing data-center suffix (e.g. `abc123...-us1`); the suffix selects the API host.",
+      'Store the key as a secret and reference it from config as `apiKey: secret("MAILCHIMP_API_KEY")`.'
+    ]
+  },
+  rateLimit: "Mailchimp allows up to 10 simultaneous connections per account; per-endpoint rate limits are not advertised, so the connector keeps to sequential paginated requests.",
+  limitations: [
+    "Per-campaign report stats are rewritten on every sync because the /reports endpoint has no `since` filter.",
+    "Automations are synced as entities only; per-workflow open/click counts are out of scope.",
+    "Member-level data, ecommerce stores, and landing pages are out of scope."
+  ]
+});
+var mailchimpCredentials = {
+  apiKey: {
+    description: "Mailchimp Marketing API key (with data-center suffix)",
+    auth: "required"
+  }
+};
+var PHASE_ORDER = [
+  "campaigns",
+  "lists",
+  "automations",
+  "campaign_stats"
+];
+var isMailchimpSyncCursor = makeChunkedCursorGuard(PHASE_ORDER);
+var CAMPAIGN_ENTITY = "mailchimp_campaign";
+var LIST_ENTITY = "mailchimp_list";
+var AUTOMATION_ENTITY = "mailchimp_automation";
+var CAMPAIGN_STATS_METRIC = "mailchimp_campaign_stats";
+var PAGE_SIZE = 500;
+var idString = z.string().min(1);
+var campaignSchema = z.object({
+  id: idString,
+  status: z.string().nullish(),
+  type: z.string().nullish(),
+  create_time: z.string().nullish(),
+  send_time: z.string().nullish(),
+  emails_sent: z.number().nullish(),
+  recipients: z.object({
+    list_id: z.string().nullish(),
+    list_name: z.string().nullish()
+  }).nullish(),
+  settings: z.object({
+    subject_line: z.string().nullish(),
+    title: z.string().nullish(),
+    from_name: z.string().nullish(),
+    reply_to: z.string().nullish()
+  }).nullish()
+});
+var listSchema = z.object({
+  id: idString,
+  name: z.string().nullish(),
+  date_created: z.string().nullish(),
+  list_rating: z.number().nullish(),
+  stats: z.object({
+    member_count: z.number().nullish(),
+    unsubscribe_count: z.number().nullish(),
+    cleaned_count: z.number().nullish(),
+    open_rate: z.number().nullish(),
+    click_rate: z.number().nullish(),
+    campaign_count: z.number().nullish()
+  }).nullish()
+});
+var automationSchema = z.object({
+  id: idString,
+  create_time: z.string().nullish(),
+  start_time: z.string().nullish(),
+  status: z.string().nullish(),
+  emails_sent: z.number().nullish(),
+  recipients: z.object({
+    list_id: z.string().nullish(),
+    list_name: z.string().nullish()
+  }).nullish(),
+  settings: z.object({
+    title: z.string().nullish(),
+    from_name: z.string().nullish(),
+    reply_to: z.string().nullish()
+  }).nullish()
+});
+var reportSchema = z.object({
+  id: idString,
+  campaign_title: z.string().nullish(),
+  type: z.string().nullish(),
+  list_id: z.string().nullish(),
+  emails_sent: z.number().nullish(),
+  unsubscribed: z.number().nullish(),
+  send_time: z.string().nullish(),
+  opens: z.object({
+    opens_total: z.number().nullish(),
+    unique_opens: z.number().nullish(),
+    open_rate: z.number().nullish()
+  }).nullish(),
+  clicks: z.object({
+    clicks_total: z.number().nullish(),
+    unique_clicks: z.number().nullish(),
+    click_rate: z.number().nullish()
+  }).nullish(),
+  bounces: z.object({
+    hard_bounces: z.number().nullish(),
+    soft_bounces: z.number().nullish(),
+    syntax_errors: z.number().nullish()
+  }).nullish()
+});
+var mailchimpResources = defineResources({
+  [CAMPAIGN_ENTITY]: {
+    shape: "entity",
+    description: "Campaigns (regular, plaintext, A/B, RSS, etc.) with status, type, subject line, sender, audience, send time, and total emails sent.",
+    endpoint: "GET /campaigns",
+    fields: [
+      {
+        name: "status",
+        description: "Campaign status (save, paused, schedule, sending, sent)."
+      },
+      {
+        name: "type",
+        description: "Campaign type (regular, plaintext, absplit, rss, etc.)."
+      },
+      { name: "subjectLine", description: "Email subject line." },
+      { name: "title", description: "Internal campaign title." },
+      { name: "fromName", description: "Sender display name." },
+      { name: "replyTo", description: "Reply-to email address." },
+      {
+        name: "listId",
+        description: "Audience (list) id the campaign targets."
+      },
+      { name: "listName", description: "Audience (list) display name." },
+      {
+        name: "createTime",
+        description: "When the campaign was created (Unix ms)."
+      },
+      {
+        name: "sendTime",
+        description: "When the campaign was sent (Unix ms)."
+      },
+      { name: "emailsSent", description: "Total emails sent." }
+    ],
+    responses: { campaigns: z.array(campaignSchema) }
+  },
+  [LIST_ENTITY]: {
+    shape: "entity",
+    description: "Audiences (lists) with member counts, engagement rates, and lifetime campaign count.",
+    endpoint: "GET /lists",
+    fields: [
+      { name: "name", description: "Audience name." },
+      { name: "memberCount", description: "Number of subscribed members." },
+      {
+        name: "unsubscribeCount",
+        description: "Number of unsubscribed members."
+      },
+      { name: "cleanedCount", description: "Number of cleaned addresses." },
+      {
+        name: "openRate",
+        description: "Lifetime open rate as a fraction (0 to 1)."
+      },
+      {
+        name: "clickRate",
+        description: "Lifetime click rate as a fraction (0 to 1)."
+      },
+      {
+        name: "campaignCount",
+        description: "Number of campaigns sent to the audience."
+      },
+      { name: "listRating", description: "Mailchimp star rating (0 to 5)." },
+      {
+        name: "createdAt",
+        description: "When the audience was created (Unix ms)."
+      }
+    ],
+    responses: { lists: z.array(listSchema) }
+  },
+  [AUTOMATION_ENTITY]: {
+    shape: "entity",
+    description: "Automations (classic email workflows) with status, title, sender, audience, and lifetime emails sent.",
+    endpoint: "GET /automations",
+    fields: [
+      {
+        name: "status",
+        description: "Automation status (save, paused, sending)."
+      },
+      { name: "title", description: "Automation title." },
+      { name: "fromName", description: "Sender display name." },
+      { name: "replyTo", description: "Reply-to email address." },
+      {
+        name: "listId",
+        description: "Audience (list) id the automation targets."
+      },
+      { name: "listName", description: "Audience (list) display name." },
+      {
+        name: "emailsSent",
+        description: "Total emails sent over the workflow lifetime."
+      },
+      {
+        name: "createTime",
+        description: "When the automation was created (Unix ms)."
+      },
+      {
+        name: "startTime",
+        description: "When the automation was started (Unix ms)."
+      }
+    ],
+    responses: { automations: z.array(automationSchema) }
+  },
+  [CAMPAIGN_STATS_METRIC]: {
+    shape: "metric",
+    description: "Per-campaign engagement stats (sent, opens, clicks, bounces, unsubscribes) timestamped at the campaign send time.",
+    endpoint: "GET /reports",
+    unit: "emails",
+    notes: "One sample per campaign; value is the sent count, and every other counter is exposed in attributes. The scope is cleared and rewritten on every sync because the /reports endpoint has no `since` filter.",
+    dimensions: [
+      { name: "campaignId", description: "Campaign id." },
+      { name: "campaignTitle", description: "Campaign internal title." },
+      { name: "campaignType", description: "Campaign type." },
+      { name: "listId", description: "Audience (list) id." },
+      { name: "opensTotal", description: "Total opens." },
+      { name: "uniqueOpens", description: "Unique opens." },
+      { name: "openRate", description: "Open rate as a fraction (0 to 1)." },
+      { name: "clicksTotal", description: "Total clicks." },
+      { name: "uniqueClicks", description: "Unique clicks." },
+      { name: "clickRate", description: "Click rate as a fraction (0 to 1)." },
+      { name: "hardBounces", description: "Number of hard bounces." },
+      { name: "softBounces", description: "Number of soft bounces." },
+      { name: "unsubscribed", description: "Number of unsubscribes." }
+    ],
+    responses: { campaign_stats: z.array(reportSchema) }
+  }
+});
+function isoToMs(value) {
+  return parseEpoch(value ?? null, "iso");
+}
+function isoToMsOrZero(value) {
+  return isoToMs(value) ?? 0;
+}
+function nullableNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function counterValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function dataCenterFromApiKey(apiKey) {
+  const dash = apiKey.lastIndexOf("-");
+  if (dash === -1 || dash === apiKey.length - 1) {
+    throw new Error(
+      "Mailchimp API key is missing the data-center suffix (e.g. `-us1`)."
+    );
+  }
+  const dc = apiKey.slice(dash + 1);
+  if (!/^[a-z]{1,4}\d{1,3}$/i.test(dc)) {
+    throw new Error(
+      `Mailchimp API key data-center suffix "${dc}" is not in the expected shape (e.g. "us1", "us21").`
+    );
+  }
+  return dc;
+}
+function encodeBasicAuth(username, password) {
+  const raw = `${username}:${password}`;
+  if (typeof btoa === "function") {
+    return `Basic ${btoa(raw)}`;
+  }
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor) {
+    return `Basic ${bufferCtor.from(raw).toString("base64")}`;
+  }
+  throw new Error("No base64 encoder available in this runtime");
+}
+function nextOffsetCursor(currentOffset, pageSize) {
+  return String(currentOffset + pageSize);
+}
+function offsetFromPage(page) {
+  if (page === null) {
+    return 0;
+  }
+  const n = Number(page);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+var id = "mailchimp";
+var MailchimpConnector = class _MailchimpConnector extends BaseConnector {
+  static id = id;
+  static resources = mailchimpResources;
+  static schemas = schemasFromResources(mailchimpResources);
+  static create(input, ctx) {
+    const parsed = configFields.parse(input);
+    return new _MailchimpConnector(
+      { resources: parsed.resources },
+      { apiKey: parsed.apiKey },
+      ctx
+    );
+  }
+  id = id;
+  credentials = mailchimpCredentials;
+  get baseUrl() {
+    const dc = dataCenterFromApiKey(this.creds.apiKey);
+    return `https://${dc}.api.mailchimp.com/3.0`;
+  }
+  buildHeaders() {
+    return {
+      // Mailchimp accepts any username with the API key as the password.
+      Authorization: encodeBasicAuth("rawdash", this.creds.apiKey),
+      Accept: "application/json",
+      "User-Agent": connectorUserAgent("mailchimp")
+    };
+  }
+  async fetchList(path, resource, params, signal) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null || value === "") {
+        continue;
+      }
+      url.searchParams.set(key, String(value));
+    }
+    const res = await this.get(url.toString(), {
+      resource,
+      headers: this.buildHeaders(),
+      signal
+    });
+    return res.body;
+  }
+  // -------------------------------------------------------------------------
+  // campaigns - GET /campaigns
+  // -------------------------------------------------------------------------
+  async fetchCampaignsPage(page, options, signal) {
+    const offset = offsetFromPage(page);
+    const body = await this.fetchList(
+      "/campaigns",
+      "campaigns",
+      {
+        count: PAGE_SIZE,
+        offset,
+        // Ascending send time keeps the offset cursor stable across pages.
+        sort_field: "send_time",
+        sort_dir: "ASC",
+        ...options.since ? { since_send_time: options.since } : {}
+      },
+      signal
+    );
+    const campaigns = body.campaigns ?? [];
+    const next = campaigns.length < PAGE_SIZE ? null : nextOffsetCursor(offset, PAGE_SIZE);
+    return { items: campaigns, next };
+  }
+  async writeCampaigns(storage, items) {
+    for (const campaign of items) {
+      const settings = campaign.settings ?? {};
+      const recipients = campaign.recipients ?? {};
+      const attributes = {
+        status: campaign.status ?? null,
+        type: campaign.type ?? null,
+        subjectLine: settings.subject_line ?? null,
+        title: settings.title ?? null,
+        fromName: settings.from_name ?? null,
+        replyTo: settings.reply_to ?? null,
+        listId: recipients.list_id ?? null,
+        listName: recipients.list_name ?? null,
+        createTime: isoToMs(campaign.create_time),
+        sendTime: isoToMs(campaign.send_time),
+        emailsSent: nullableNumber(campaign.emails_sent)
+      };
+      const updatedAt = isoToMs(campaign.send_time) ?? isoToMsOrZero(campaign.create_time);
+      await storage.entity({
+        type: CAMPAIGN_ENTITY,
+        id: campaign.id,
+        attributes,
+        updated_at: updatedAt
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // lists - GET /lists
+  // -------------------------------------------------------------------------
+  async fetchListsPage(page, options, signal) {
+    const offset = offsetFromPage(page);
+    const body = await this.fetchList(
+      "/lists",
+      "lists",
+      {
+        count: PAGE_SIZE,
+        offset,
+        sort_field: "date_created",
+        sort_dir: "ASC",
+        ...options.since ? { since_date_created: options.since } : {}
+      },
+      signal
+    );
+    const lists = body.lists ?? [];
+    const next = lists.length < PAGE_SIZE ? null : nextOffsetCursor(offset, PAGE_SIZE);
+    return { items: lists, next };
+  }
+  async writeLists(storage, items) {
+    for (const list of items) {
+      const stats = list.stats ?? {};
+      const attributes = {
+        name: list.name ?? null,
+        memberCount: nullableNumber(stats.member_count),
+        unsubscribeCount: nullableNumber(stats.unsubscribe_count),
+        cleanedCount: nullableNumber(stats.cleaned_count),
+        openRate: nullableNumber(stats.open_rate),
+        clickRate: nullableNumber(stats.click_rate),
+        campaignCount: nullableNumber(stats.campaign_count),
+        listRating: nullableNumber(list.list_rating),
+        createdAt: isoToMs(list.date_created)
+      };
+      await storage.entity({
+        type: LIST_ENTITY,
+        id: list.id,
+        attributes,
+        // Lists have no updated_at in the API; stamp with sync time so newer
+        // syncs win on conflict.
+        updated_at: Date.now()
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // automations - GET /automations
+  // -------------------------------------------------------------------------
+  async fetchAutomationsPage(page, signal) {
+    const offset = offsetFromPage(page);
+    const body = await this.fetchList(
+      "/automations",
+      "automations",
+      {
+        count: PAGE_SIZE,
+        offset
+      },
+      signal
+    );
+    const automations = body.automations ?? [];
+    const next = automations.length < PAGE_SIZE ? null : nextOffsetCursor(offset, PAGE_SIZE);
+    return { items: automations, next };
+  }
+  async writeAutomations(storage, items) {
+    for (const automation of items) {
+      const settings = automation.settings ?? {};
+      const recipients = automation.recipients ?? {};
+      const attributes = {
+        status: automation.status ?? null,
+        title: settings.title ?? null,
+        fromName: settings.from_name ?? null,
+        replyTo: settings.reply_to ?? null,
+        listId: recipients.list_id ?? null,
+        listName: recipients.list_name ?? null,
+        emailsSent: nullableNumber(automation.emails_sent),
+        createTime: isoToMs(automation.create_time),
+        startTime: isoToMs(automation.start_time)
+      };
+      const updatedAt = isoToMs(automation.start_time) ?? isoToMs(automation.create_time) ?? Date.now();
+      await storage.entity({
+        type: AUTOMATION_ENTITY,
+        id: automation.id,
+        attributes,
+        updated_at: updatedAt
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // campaign_stats - GET /reports (metric, one sample per campaign)
+  // -------------------------------------------------------------------------
+  async fetchReportsPage(page, signal) {
+    const offset = offsetFromPage(page);
+    const body = await this.fetchList(
+      "/reports",
+      "campaign_stats",
+      {
+        count: PAGE_SIZE,
+        offset
+      },
+      signal
+    );
+    const reports = body.reports ?? [];
+    const next = reports.length < PAGE_SIZE ? null : nextOffsetCursor(offset, PAGE_SIZE);
+    return { items: reports, next };
+  }
+  async writeCampaignStats(storage, items) {
+    for (const report of items) {
+      const ts = isoToMs(report.send_time);
+      if (ts === null) {
+        continue;
+      }
+      const opens = report.opens ?? {};
+      const clicks = report.clicks ?? {};
+      const bounces = report.bounces ?? {};
+      const sent = counterValue(report.emails_sent);
+      await storage.metric({
+        name: CAMPAIGN_STATS_METRIC,
+        ts,
+        value: sent,
+        attributes: {
+          campaignId: report.id,
+          campaignTitle: report.campaign_title ?? null,
+          campaignType: report.type ?? null,
+          listId: report.list_id ?? null,
+          sent,
+          opensTotal: counterValue(opens.opens_total),
+          uniqueOpens: counterValue(opens.unique_opens),
+          openRate: nullableNumber(opens.open_rate),
+          clicksTotal: counterValue(clicks.clicks_total),
+          uniqueClicks: counterValue(clicks.unique_clicks),
+          clickRate: nullableNumber(clicks.click_rate),
+          hardBounces: counterValue(bounces.hard_bounces),
+          softBounces: counterValue(bounces.soft_bounces),
+          unsubscribed: counterValue(report.unsubscribed)
+        }
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Scope clearing (idempotency)
+  // -------------------------------------------------------------------------
+  async clearScopeOnFirstPage(storage, phase, isFull) {
+    if (phase === "campaign_stats") {
+      await storage.metrics([], { names: [CAMPAIGN_STATS_METRIC] });
+      return;
+    }
+    if (!isFull) {
+      return;
+    }
+    const entityType = ENTITY_TYPE_BY_PHASE[phase];
+    if (entityType) {
+      await storage.entities([], { types: [entityType] });
+    }
+  }
+  async writePhase(storage, phase, items) {
+    switch (phase) {
+      case "campaigns":
+        await this.writeCampaigns(storage, items);
+        return;
+      case "lists":
+        await this.writeLists(storage, items);
+        return;
+      case "automations":
+        await this.writeAutomations(storage, items);
+        return;
+      case "campaign_stats":
+        await this.writeCampaignStats(storage, items);
+        return;
+    }
+  }
+  async sync(options, storage, signal) {
+    const cursor = isMailchimpSyncCursor(options.cursor) ? options.cursor : void 0;
+    const isFull = options.mode === "full";
+    const phases = selectActivePhases(
+      (r) => r,
+      PHASE_ORDER,
+      this.settings.resources
+    );
+    return paginateChunked({
+      phases,
+      cursor,
+      signal,
+      logger: this.logger,
+      fetchPage: async (phase, page, sig) => {
+        switch (phase) {
+          case "campaigns":
+            return this.fetchCampaignsPage(page, options, sig);
+          case "lists":
+            return this.fetchListsPage(page, options, sig);
+          case "automations":
+            return this.fetchAutomationsPage(page, sig);
+          case "campaign_stats":
+            return this.fetchReportsPage(page, sig);
+        }
+      },
+      writeBatch: async (phase, items, page) => {
+        if (page === null) {
+          await this.clearScopeOnFirstPage(storage, phase, isFull);
+        }
+        await this.writePhase(storage, phase, items);
+      }
+    });
+  }
+};
+var ENTITY_TYPE_BY_PHASE = {
+  campaigns: CAMPAIGN_ENTITY,
+  lists: LIST_ENTITY,
+  automations: AUTOMATION_ENTITY
+};
+
+// src/index.ts
+var index_default = MailchimpConnector;
+export {
+  MailchimpConnector,
+  configFields,
+  index_default as default,
+  doc,
+  id,
+  mailchimpResources as resources
+};
+//# sourceMappingURL=index.js.map