veryfront 0.0.49 → 0.0.51

package/dist/integrations/mailchimp/files/ai/tools/get-list.ts

@@ -0,0 +1,51 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { getList } from "../../lib/mailchimp-client.ts";
+
+export default tool({
+  id: "get-list",
+  description: "Get details of a specific Mailchimp audience list by its ID.",
+  inputSchema: z.object({
+    listId: z.string().describe("The ID of the audience list to retrieve"),
+  }),
+  async execute({ listId }) {
+    const list = await getList(listId);
+
+    return {
+      id: list.id,
+      webId: list.web_id,
+      name: list.name,
+      dateCreated: list.date_created,
+      listRating: list.list_rating,
+      permissionReminder: list.permission_reminder,
+      subscribeUrlShort: list.subscribe_url_short,
+      subscribeUrlLong: list.subscribe_url_long,
+      contact: {
+        company: list.contact.company,
+        address1: list.contact.address1,
+        city: list.contact.city,
+        state: list.contact.state,
+        zip: list.contact.zip,
+        country: list.contact.country,
+      },
+      campaignDefaults: {
+        fromName: list.campaign_defaults.from_name,
+        fromEmail: list.campaign_defaults.from_email,
+        subject: list.campaign_defaults.subject,
+        language: list.campaign_defaults.language,
+      },
+      stats: {
+        memberCount: list.stats.member_count,
+        totalContacts: list.stats.total_contacts,
+        unsubscribeCount: list.stats.unsubscribe_count,
+        cleanedCount: list.stats.cleaned_count,
+        memberCountSinceSend: list.stats.member_count_since_send,
+        unsubscribeCountSinceSend: list.stats.unsubscribe_count_since_send,
+        cleanedCountSinceSend: list.stats.cleaned_count_since_send,
+        campaignCount: list.stats.campaign_count,
+        openRate: list.stats.open_rate,
+        clickRate: list.stats.click_rate,
+      },
+    };
+  },
+});

package/dist/integrations/mailchimp/files/ai/tools/list-campaigns.ts

@@ -0,0 +1,46 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listCampaigns } from "../../lib/mailchimp-client.ts";
+
+export default tool({
+  id: "list-campaigns",
+  description:
+    "List email campaigns from Mailchimp. Can filter by status (save, paused, schedule, sending, sent).",
+  inputSchema: z.object({
+    status: z
+      .enum(["save", "paused", "schedule", "sending", "sent"])
+      .optional()
+      .describe("Filter campaigns by status"),
+    limit: z.number().min(1).max(50).default(20).describe("Maximum number of campaigns to return"),
+  }),
+  async execute({ status, limit }) {
+    const campaigns = await listCampaigns({
+      status,
+      count: limit,
+    });
+
+    return campaigns.map((campaign) => ({
+      id: campaign.id,
+      webId: campaign.web_id,
+      type: campaign.type,
+      status: campaign.status,
+      title: campaign.settings.title,
+      subject: campaign.settings.subject_line,
+      fromName: campaign.settings.from_name,
+      listName: campaign.recipients.list_name,
+      emailsSent: campaign.emails_sent,
+      sendTime: campaign.send_time,
+      createdAt: campaign.create_time,
+      archiveUrl: campaign.archive_url,
+      reportSummary: campaign.report_summary
+        ? {
+            opens: campaign.report_summary.opens,
+            uniqueOpens: campaign.report_summary.unique_opens,
+            openRate: campaign.report_summary.open_rate,
+            clicks: campaign.report_summary.clicks,
+            clickRate: campaign.report_summary.click_rate,
+          }
+        : undefined,
+    }));
+  },
+});

package/dist/integrations/mailchimp/files/ai/tools/list-lists.ts

@@ -0,0 +1,46 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listLists } from "../../lib/mailchimp-client.ts";
+
+export default tool({
+  id: "list-lists",
+  description: "List all audience lists (mailing lists) in Mailchimp with their statistics.",
+  inputSchema: z.object({
+    limit: z.number().min(1).max(50).default(20).describe("Maximum number of lists to return"),
+  }),
+  async execute({ limit }) {
+    const lists = await listLists({
+      count: limit,
+    });
+
+    return lists.map((list) => ({
+      id: list.id,
+      webId: list.web_id,
+      name: list.name,
+      dateCreated: list.date_created,
+      listRating: list.list_rating,
+      subscribeUrl: list.subscribe_url_short,
+      contact: {
+        company: list.contact.company,
+        city: list.contact.city,
+        state: list.contact.state,
+        country: list.contact.country,
+      },
+      campaignDefaults: {
+        fromName: list.campaign_defaults.from_name,
+        fromEmail: list.campaign_defaults.from_email,
+        subject: list.campaign_defaults.subject,
+        language: list.campaign_defaults.language,
+      },
+      stats: {
+        memberCount: list.stats.member_count,
+        totalContacts: list.stats.total_contacts,
+        unsubscribeCount: list.stats.unsubscribe_count,
+        cleanedCount: list.stats.cleaned_count,
+        campaignCount: list.stats.campaign_count,
+        openRate: list.stats.open_rate,
+        clickRate: list.stats.click_rate,
+      },
+    }));
+  },
+});

package/dist/integrations/mailchimp/files/ai/tools/list-members.ts

@@ -0,0 +1,58 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listMembers } from "../../lib/mailchimp-client.ts";
+
+export default tool({
+  id: "list-members",
+  description:
+    "List subscribers/members in a Mailchimp audience list. Can filter by subscription status.",
+  inputSchema: z.object({
+    listId: z.string().describe("The ID of the audience list to get members from"),
+    status: z
+      .enum(["subscribed", "unsubscribed", "cleaned", "pending", "transactional"])
+      .optional()
+      .describe("Filter members by subscription status"),
+    limit: z.number().min(1).max(50).default(20).describe("Maximum number of members to return"),
+  }),
+  async execute({ listId, status, limit }) {
+    const members = await listMembers(listId, {
+      status,
+      count: limit,
+    });
+
+    return members.map((member) => ({
+      id: member.id,
+      emailAddress: member.email_address,
+      uniqueEmailId: member.unique_email_id,
+      contactId: member.contact_id,
+      fullName: member.full_name,
+      status: member.status,
+      emailType: member.email_type,
+      vip: member.vip,
+      language: member.language,
+      memberRating: member.member_rating,
+      lastChanged: member.last_changed,
+      timestampSignup: member.timestamp_signup,
+      timestampOpt: member.timestamp_opt,
+      ipSignup: member.ip_signup,
+      ipOpt: member.ip_opt,
+      stats: {
+        avgOpenRate: member.stats.avg_open_rate,
+        avgClickRate: member.stats.avg_click_rate,
+      },
+      mergeFields: member.merge_fields,
+      tags: member.tags.map((tag) => ({
+        id: tag.id,
+        name: tag.name,
+      })),
+      location: member.location
+        ? {
+            countryCode: member.location.country_code,
+            timezone: member.location.timezone,
+            latitude: member.location.latitude,
+            longitude: member.location.longitude,
+          }
+        : undefined,
+    }));
+  },
+});

package/dist/integrations/mailchimp/files/app/api/auth/mailchimp/callback/route.ts

@@ -0,0 +1,11 @@
+/**
+ * Mailchimp OAuth Callback
+ */
+
+import { createOAuthCallbackHandler, mailchimpConfig, memoryTokenStore } from "veryfront/oauth";
+
+export const GET = createOAuthCallbackHandler(mailchimpConfig, {
+  tokenStore: memoryTokenStore,
+  onSuccess: () => "/",
+  onError: () => "/",
+});

package/dist/integrations/mailchimp/files/app/api/auth/mailchimp/route.ts

@@ -0,0 +1,7 @@
+/**
+ * Mailchimp OAuth Init
+ */
+
+import { createOAuthInitHandler, mailchimpConfig } from "veryfront/oauth";
+
+export const GET = createOAuthInitHandler(mailchimpConfig);

package/dist/integrations/mailchimp/files/lib/mailchimp-client.ts

@@ -0,0 +1,267 @@
+import { getAccessToken } from "./token-store.ts";
+
+// Mailchimp API base URL - note that the actual server prefix is obtained from metadata
+let MAILCHIMP_BASE_URL = "https://us1.api.mailchimp.com/3.0";
+
+interface MailchimpResponse<T> {
+  [key: string]: unknown;
+}
+
+interface MailchimpCampaign {
+  id: string;
+  web_id: number;
+  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;
+  recipients: {
+    list_id: string;
+    list_name: string;
+    segment_text?: string;
+  };
+  settings: {
+    subject_line: string;
+    preview_text?: string;
+    title: string;
+    from_name: string;
+    reply_to: string;
+  };
+  tracking: {
+    opens: boolean;
+    html_clicks: boolean;
+    text_clicks: boolean;
+  };
+  report_summary?: {
+    opens: number;
+    unique_opens: number;
+    open_rate: number;
+    clicks: number;
+    subscriber_clicks: number;
+    click_rate: number;
+  };
+}
+
+interface MailchimpList {
+  id: string;
+  web_id: number;
+  name: string;
+  contact: {
+    company: string;
+    address1: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+  };
+  permission_reminder: string;
+  campaign_defaults: {
+    from_name: string;
+    from_email: string;
+    subject: string;
+    language: string;
+  };
+  stats: {
+    member_count: number;
+    total_contacts: number;
+    unsubscribe_count: number;
+    cleaned_count: number;
+    member_count_since_send: number;
+    unsubscribe_count_since_send: number;
+    cleaned_count_since_send: number;
+    campaign_count: number;
+    open_rate: number;
+    click_rate: number;
+  };
+  date_created: string;
+  list_rating: number;
+  subscribe_url_short: string;
+  subscribe_url_long: string;
+}
+
+interface MailchimpMember {
+  id: string;
+  email_address: string;
+  unique_email_id: string;
+  contact_id: string;
+  full_name: string;
+  web_id: number;
+  email_type: string;
+  status: "subscribed" | "unsubscribed" | "cleaned" | "pending" | "transactional";
+  merge_fields: Record<string, unknown>;
+  stats: {
+    avg_open_rate: number;
+    avg_click_rate: number;
+  };
+  ip_signup?: string;
+  timestamp_signup?: string;
+  ip_opt?: string;
+  timestamp_opt?: string;
+  member_rating: number;
+  last_changed: string;
+  language: string;
+  vip: boolean;
+  email_client?: string;
+  location?: {
+    latitude: number;
+    longitude: number;
+    gmtoff: number;
+    dstoff: number;
+    country_code: string;
+    timezone: string;
+  };
+  tags: Array<{ id: number; name: string }>;
+}
+
+interface MailchimpMetadata {
+  dc: string;
+  role: string;
+  accountname: string;
+  user_id: string;
+  login: {
+    email: string;
+    avatar?: string;
+    login_id: string;
+    login_name: string;
+    login_email: string;
+  };
+}
+
+// Initialize the API base URL with the correct datacenter
+async function initializeBaseUrl() {
+  const token = await getAccessToken();
+  if (!token) return;
+
+  try {
+    // Get metadata to determine the correct datacenter
+    const response = await fetch("https://login.mailchimp.com/oauth2/metadata", {
+      headers: {
+        Authorization: `OAuth ${token}`,
+      },
+    });
+
+    if (response.ok) {
+      const metadata = (await response.json()) as MailchimpMetadata;
+      MAILCHIMP_BASE_URL = `https://${metadata.dc}.api.mailchimp.com/3.0`;
+    }
+  } catch (error) {
+    // Fallback to us1 if metadata fetch fails
+    console.error("Failed to fetch Mailchimp metadata:", error);
+  }
+}
+
+async function mailchimpFetch<T>(
+  endpoint: string,
+  options: RequestInit = {},
+): Promise<T> {
+  const token = await getAccessToken();
+  if (!token) {
+    throw new Error("Not authenticated with Mailchimp. Please connect your account.");
+  }
+
+  // Initialize base URL if not done yet
+  if (MAILCHIMP_BASE_URL === "https://us1.api.mailchimp.com/3.0") {
+    await initializeBaseUrl();
+  }
+
+  const response = await fetch(`${MAILCHIMP_BASE_URL}${endpoint}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(
+      `Mailchimp API error: ${response.status} ${(error as { detail?: string }).detail || response.statusText}`,
+    );
+  }
+
+  return response.json();
+}
+
+export async function listCampaigns(options?: {
+  status?: "save" | "paused" | "schedule" | "sending" | "sent";
+  count?: number;
+  offset?: number;
+}): Promise<MailchimpCampaign[]> {
+  const params = new URLSearchParams();
+  if (options?.status) params.set("status", options.status);
+  if (options?.count) params.set("count", options.count.toString());
+  if (options?.offset) params.set("offset", options.offset.toString());
+
+  const queryString = params.toString();
+  const response = await mailchimpFetch<{ campaigns: MailchimpCampaign[] }>(
+    `/campaigns${queryString ? `?${queryString}` : ""}`,
+  );
+  return response.campaigns;
+}
+
+export async function getCampaign(campaignId: string): Promise<MailchimpCampaign> {
+  return mailchimpFetch<MailchimpCampaign>(`/campaigns/${campaignId}`);
+}
+
+export async function listLists(options?: {
+  count?: number;
+  offset?: number;
+}): Promise<MailchimpList[]> {
+  const params = new URLSearchParams();
+  if (options?.count) params.set("count", options.count.toString());
+  if (options?.offset) params.set("offset", options.offset.toString());
+
+  const queryString = params.toString();
+  const response = await mailchimpFetch<{ lists: MailchimpList[] }>(
+    `/lists${queryString ? `?${queryString}` : ""}`,
+  );
+  return response.lists;
+}
+
+export async function getList(listId: string): Promise<MailchimpList> {
+  return mailchimpFetch<MailchimpList>(`/lists/${listId}`);
+}
+
+export async function listMembers(
+  listId: string,
+  options?: {
+    status?: "subscribed" | "unsubscribed" | "cleaned" | "pending" | "transactional";
+    count?: number;
+    offset?: number;
+  },
+): Promise<MailchimpMember[]> {
+  const params = new URLSearchParams();
+  if (options?.status) params.set("status", options.status);
+  if (options?.count) params.set("count", options.count.toString());
+  if (options?.offset) params.set("offset", options.offset.toString());
+
+  const queryString = params.toString();
+  const response = await mailchimpFetch<{ members: MailchimpMember[] }>(
+    `/lists/${listId}/members${queryString ? `?${queryString}` : ""}`,
+  );
+  return response.members;
+}
+
+export async function getMetadata(): Promise<MailchimpMetadata> {
+  const token = await getAccessToken();
+  if (!token) {
+    throw new Error("Not authenticated with Mailchimp. Please connect your account.");
+  }
+
+  const response = await fetch("https://login.mailchimp.com/oauth2/metadata", {
+    headers: {
+      Authorization: `OAuth ${token}`,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Mailchimp metadata: ${response.statusText}`);
+  }
+
+  return response.json();
+}

package/dist/integrations/mixpanel/connector.json

@@ -0,0 +1,96 @@
+{
+  "name": "mixpanel",
+  "displayName": "Mixpanel",
+  "icon": "mixpanel.svg",
+  "description": "Track events, analyze funnels, and understand user behavior with Mixpanel analytics",
+  "auth": {
+    "type": "api-key",
+    "keyName": "MIXPANEL_PROJECT_TOKEN",
+    "requiredApis": [
+      {
+        "name": "Mixpanel API",
+        "enableUrl": "https://mixpanel.com/settings/project"
+      }
+    ]
+  },
+  "envVars": [
+    {
+      "name": "MIXPANEL_PROJECT_TOKEN",
+      "description": "Mixpanel Project Token for event tracking",
+      "required": true,
+      "sensitive": true,
+      "docsUrl": "https://docs.mixpanel.com/docs/tracking-methods/id-management/authentication"
+    },
+    {
+      "name": "MIXPANEL_API_SECRET",
+      "description": "Mixpanel API Secret for data export and query operations",
+      "required": true,
+      "sensitive": true,
+      "docsUrl": "https://developer.mixpanel.com/reference/authentication"
+    },
+    {
+      "name": "MIXPANEL_PROJECT_ID",
+      "description": "Mixpanel Project ID (found in project settings)",
+      "required": true,
+      "sensitive": false,
+      "docsUrl": "https://docs.mixpanel.com/docs/admin/organizations-projects/manage-projects"
+    }
+  ],
+  "tools": [
+    {
+      "id": "track-event",
+      "name": "Track Event",
+      "description": "Track a custom event in Mixpanel with properties",
+      "requiresWrite": true
+    },
+    {
+      "id": "query-events",
+      "name": "Query Events",
+      "description": "Query and export event data from Mixpanel",
+      "requiresWrite": false
+    },
+    {
+      "id": "get-funnel",
+      "name": "Get Funnel",
+      "description": "Retrieve funnel analysis data to understand conversion rates",
+      "requiresWrite": false
+    },
+    {
+      "id": "get-retention",
+      "name": "Get Retention",
+      "description": "Analyze user retention cohorts over time",
+      "requiresWrite": false
+    },
+    {
+      "id": "list-cohorts",
+      "name": "List Cohorts",
+      "description": "List all user cohorts defined in your Mixpanel project",
+      "requiresWrite": false
+    }
+  ],
+  "prompts": [
+    {
+      "id": "event-analysis",
+      "title": "Event analysis",
+      "prompt": "Show me the most important events tracked in my Mixpanel project over the last 7 days and their trends.",
+      "category": "analytics",
+      "icon": "chart"
+    },
+    {
+      "id": "funnel-performance",
+      "title": "Funnel performance",
+      "prompt": "Analyze my key conversion funnels and identify where users are dropping off.",
+      "category": "analytics",
+      "icon": "funnel"
+    },
+    {
+      "id": "retention-insights",
+      "title": "Retention insights",
+      "prompt": "Give me insights about user retention and cohort behavior over the past month.",
+      "category": "analytics",
+      "icon": "users"
+    }
+  ],
+  "suggestedWith": ["slack", "analytics", "monitoring"],
+  "SETUP_GUIDE": "# Mixpanel Integration Setup\n\n## Step 1: Get Your Project Token\n1. Log in to your Mixpanel account at https://mixpanel.com\n2. Navigate to your project settings\n3. Under 'Project Settings', find your **Project Token**\n4. Copy the token and add it as `MIXPANEL_PROJECT_TOKEN` in your .env file\n\n## Step 2: Get Your API Secret\n1. In Mixpanel, go to Settings > Project Settings\n2. Scroll to 'Service Accounts' section\n3. Create a new Service Account or use an existing one\n4. Copy the **API Secret** and add it as `MIXPANEL_API_SECRET` in your .env file\n\n## Step 3: Get Your Project ID\n1. In Mixpanel project settings URL, your Project ID is the number in the URL\n2. Format: https://mixpanel.com/project/YOUR_PROJECT_ID/settings\n3. Copy this ID and add it as `MIXPANEL_PROJECT_ID` in your .env file\n\n## Step 4: Set Up Environment Variables\nAdd these to your `.env` file:\n```\nMIXPANEL_PROJECT_TOKEN=your_project_token_here\nMIXPANEL_API_SECRET=your_api_secret_here\nMIXPANEL_PROJECT_ID=your_project_id_here\n```\n\n## Step 5: Test the Integration\nRun your application and try tracking a test event to verify the setup is working correctly.\n\n## Important Notes\n- **Project Token** is used for tracking events (ingestion)\n- **API Secret** is used for querying and exporting data\n- Keep both credentials secure and never commit them to version control\n- For production deployments, use environment variables or secure secret management\n\n## Useful Resources\n- [Mixpanel API Documentation](https://developer.mixpanel.com/reference/overview)\n- [Event Tracking Guide](https://docs.mixpanel.com/docs/tracking-methods/sdks)\n- [Query API Guide](https://developer.mixpanel.com/reference/query-api)"
+}

package/dist/integrations/mixpanel/files/_env.example

@@ -0,0 +1,11 @@
+# Mixpanel Integration
+# Get your credentials at https://mixpanel.com/settings/project
+
+# Project Token - used for tracking events (ingestion)
+MIXPANEL_PROJECT_TOKEN=your_project_token_here
+
+# API Secret - used for querying and exporting data
+MIXPANEL_API_SECRET=your_api_secret_here
+
+# Project ID - found in your project settings URL
+MIXPANEL_PROJECT_ID=your_project_id_here

package/dist/integrations/mixpanel/files/ai/tools/get-funnel.ts

@@ -0,0 +1,46 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { getFunnel, calculateFunnelConversionRate } from "../../lib/mixpanel-client.ts";
+
+export default tool({
+  id: "get-funnel",
+  description:
+    "Retrieve funnel analysis data from Mixpanel. Analyze conversion rates and user drop-off at each step of a funnel.",
+  inputSchema: z.object({
+    funnelId: z.number().describe(
+      "The numeric ID of the funnel (found in Mixpanel funnel URL or settings)",
+    ),
+    from: z.string().describe(
+      "Start date in YYYY-MM-DD format (e.g., '2024-01-01')",
+    ),
+    to: z.string().describe(
+      "End date in YYYY-MM-DD format (e.g., '2024-01-31')",
+    ),
+  }),
+  async execute({ funnelId, from, to }) {
+    const funnel = await getFunnel(funnelId, from, to);
+
+    const overallConversionRate = calculateFunnelConversionRate(funnel);
+
+    return {
+      funnelId: funnel.funnel_id,
+      name: funnel.name,
+      dateRange: {
+        from,
+        to,
+      },
+      overallConversionRate: `${overallConversionRate.toFixed(2)}%`,
+      steps: funnel.steps.map((step, index) => ({
+        stepNumber: index + 1,
+        event: step.event,
+        count: step.count,
+        overallConversionRate: `${(step.overall_conv_ratio * 100).toFixed(2)}%`,
+        stepConversionRate: `${(step.step_conv_ratio * 100).toFixed(2)}%`,
+        averageTime: step.avg_time
+          ? `${(step.avg_time / 60).toFixed(1)} minutes`
+          : "N/A",
+      })),
+      data: funnel.data,
+    };
+  },
+});