veryfront 0.0.48 → 0.0.50

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,
+    };
+  },
+});

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

@@ -0,0 +1,64 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { getRetention } from "../../lib/mixpanel-client.ts";
+
+export default tool({
+  id: "get-retention",
+  description:
+    "Analyze user retention cohorts in Mixpanel. Understand how many users return after performing an initial event.",
+  inputSchema: z.object({
+    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')",
+    ),
+    event: z.string().describe(
+      "The event to analyze retention for (e.g., 'App Opened', 'Sign Up')",
+    ),
+    retentionType: z.enum(["birth", "compounded"]).optional().default("birth")
+      .describe(
+        "Retention type: 'birth' (first time users) or 'compounded' (all users who did the event)",
+      ),
+  }),
+  async execute({ from, to, event, retentionType }) {
+    const retention = await getRetention(from, to, event, retentionType);
+
+    return {
+      event,
+      retentionType,
+      dateRange: {
+        from,
+        to,
+      },
+      cohorts: retention.map((cohort) => ({
+        date: cohort.date,
+        initialCount: cohort.count,
+        retention: cohort.retention.map((r) => ({
+          day: r.day,
+          count: r.count,
+          rate: `${(r.rate * 100).toFixed(2)}%`,
+        })),
+      })),
+      summary: {
+        totalCohorts: retention.length,
+        averageDay1Retention: retention.length > 0
+          ? `${(
+            retention.reduce((sum, c) => {
+              const day1 = c.retention.find((r) => r.day === 1);
+              return sum + (day1 ? day1.rate : 0);
+            }, 0) / retention.length * 100
+          ).toFixed(2)}%`
+          : "N/A",
+        averageDay7Retention: retention.length > 0
+          ? `${(
+            retention.reduce((sum, c) => {
+              const day7 = c.retention.find((r) => r.day === 7);
+              return sum + (day7 ? day7.rate : 0);
+            }, 0) / retention.length * 100
+          ).toFixed(2)}%`
+          : "N/A",
+      },
+    };
+  },
+});

package/dist/integrations/mixpanel/files/ai/tools/list-cohorts.ts

@@ -0,0 +1,46 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listCohorts } from "../../lib/mixpanel-client.ts";
+
+export default tool({
+  id: "list-cohorts",
+  description:
+    "List all user cohorts defined in your Mixpanel project. Cohorts are saved user segments based on properties or behaviors.",
+  inputSchema: z.object({
+    includeHidden: z.boolean().optional().default(false).describe(
+      "Include hidden cohorts in the results (defaults to false)",
+    ),
+  }),
+  async execute({ includeHidden }) {
+    const allCohorts = await listCohorts();
+
+    // Filter by visibility if needed
+    const cohorts = includeHidden
+      ? allCohorts
+      : allCohorts.filter((c) => c.is_visible);
+
+    return {
+      total: cohorts.length,
+      cohorts: cohorts.map((cohort) => ({
+        id: cohort.id,
+        name: cohort.name,
+        description: cohort.description,
+        count: cohort.count,
+        created: cohort.created,
+        isVisible: cohort.is_visible,
+        projectId: cohort.project_id,
+      })),
+      summary: {
+        totalUsers: cohorts.reduce((sum, c) => sum + c.count, 0),
+        largestCohort: cohorts.length > 0
+          ? cohorts.reduce((max, c) => (c.count > max.count ? c : max))
+            .name
+          : "N/A",
+        smallestCohort: cohorts.length > 0
+          ? cohorts.reduce((min, c) => (c.count < min.count ? c : min))
+            .name
+          : "N/A",
+      },
+    };
+  },
+});

package/dist/integrations/mixpanel/files/ai/tools/query-events.ts

@@ -0,0 +1,43 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { queryEvents, getDateRange } from "../../lib/mixpanel-client.ts";
+
+export default tool({
+  id: "query-events",
+  description:
+    "Query and export event data from Mixpanel. Retrieve events within a date range, optionally filtered by event name.",
+  inputSchema: z.object({
+    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')",
+    ),
+    event: z.string().optional().describe(
+      "Optional: Filter by specific event name (e.g., 'Page Viewed'). If not provided, returns all events.",
+    ),
+    limit: z.number().optional().default(100).describe(
+      "Maximum number of events to return (defaults to 100)",
+    ),
+  }),
+  async execute({ from, to, event, limit }) {
+    const events = await queryEvents(from, to, event);
+
+    // Limit results
+    const limitedEvents = events.slice(0, limit);
+
+    return {
+      total: events.length,
+      returned: limitedEvents.length,
+      dateRange: {
+        from,
+        to,
+      },
+      eventFilter: event || "all",
+      events: limitedEvents.map((e) => ({
+        event: e.event,
+        properties: e.properties,
+      })),
+    };
+  },
+});

package/dist/integrations/mixpanel/files/ai/tools/track-event.ts

@@ -0,0 +1,41 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { trackEvent } from "../../lib/mixpanel-client.ts";
+
+export default tool({
+  id: "track-event",
+  description:
+    "Track a custom event in Mixpanel. Capture user actions, page views, or any custom analytics event with properties.",
+  inputSchema: z.object({
+    event: z.string().describe(
+      "Event name (e.g., 'Button Clicked', 'Page Viewed', 'Purchase Completed')",
+    ),
+    distinctId: z.string().describe(
+      "Unique identifier for the user or session (e.g., user ID, email, or anonymous ID)",
+    ),
+    properties: z.record(z.unknown()).optional().describe(
+      "Additional properties to attach to the event (e.g., {product_id: '123', price: 29.99, category: 'electronics'})",
+    ),
+  }),
+  async execute({ event, distinctId, properties }) {
+    const result = await trackEvent(event, properties || {}, distinctId);
+
+    if (result.status === 1) {
+      return {
+        success: true,
+        event: {
+          name: event,
+          distinctId,
+          properties: properties || {},
+          timestamp: new Date().toISOString(),
+        },
+        message: "Event tracked successfully",
+      };
+    } else {
+      return {
+        success: false,
+        error: result.error || "Failed to track event",
+      };
+    }
+  },
+});

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

@@ -0,0 +1,319 @@
+import { getProjectToken, getApiSecret, getProjectId } from "./token-store.ts";
+
+const MIXPANEL_API_BASE = "https://mixpanel.com/api";
+const MIXPANEL_TRACK_BASE = "https://api.mixpanel.com";
+const MIXPANEL_DATA_BASE = "https://data.mixpanel.com/api/2.0";
+
+// Types
+export interface MixpanelEvent {
+  event: string;
+  properties: Record<string, unknown>;
+}
+
+export interface MixpanelEventQuery {
+  event?: string;
+  from_date: string;
+  to_date: string;
+  where?: string;
+  limit?: number;
+}
+
+export interface MixpanelEventResult {
+  event: string;
+  properties: Record<string, unknown>;
+}
+
+export interface MixpanelFunnel {
+  funnel_id: number;
+  name: string;
+  steps: Array<{
+    event: string;
+    count: number;
+    avg_time: number | null;
+    overall_conv_ratio: number;
+    step_conv_ratio: number;
+  }>;
+  data: {
+    series: string[];
+    values: Record<string, number[]>;
+  };
+}
+
+export interface MixpanelRetention {
+  date: string;
+  count: number;
+  retention: Array<{
+    day: number;
+    count: number;
+    rate: number;
+  }>;
+}
+
+export interface MixpanelCohort {
+  id: number;
+  name: string;
+  description: string;
+  count: number;
+  created: string;
+  is_visible: boolean;
+  project_id: number;
+}
+
+interface MixpanelError {
+  error: string;
+  request: string;
+}
+
+// Helper function to create basic auth header
+function getAuthHeader(): string {
+  const apiSecret = getApiSecret();
+  if (!apiSecret) {
+    throw new Error(
+      "Not authenticated with Mixpanel. Please set MIXPANEL_API_SECRET.",
+    );
+  }
+  // Mixpanel uses Basic auth with API secret as username and empty password
+  const credentials = btoa(`${apiSecret}:`);
+  return `Basic ${credentials}`;
+}
+
+// Helper function for Mixpanel API calls with auth
+async function mixpanelFetch<T>(
+  baseUrl: string,
+  endpoint: string,
+  options: RequestInit & { params?: Record<string, string | number | boolean> } = {},
+): Promise<T> {
+  // Build URL with query parameters
+  let url = `${baseUrl}${endpoint}`;
+  if (options.params) {
+    const params = new URLSearchParams();
+    Object.entries(options.params).forEach(([key, value]) => {
+      params.append(key, String(value));
+    });
+    url += `?${params.toString()}`;
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...options.headers as Record<string, string>,
+  };
+
+  // Add auth header for data API calls
+  if (baseUrl === MIXPANEL_DATA_BASE || baseUrl === MIXPANEL_API_BASE) {
+    headers["Authorization"] = getAuthHeader();
+  }
+
+  const response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  if (!response.ok) {
+    let errorMessage = `Mixpanel API error: ${response.status} ${response.statusText}`;
+    try {
+      const errorData = await response.json() as MixpanelError;
+      if (errorData.error) {
+        errorMessage = `Mixpanel API error: ${errorData.error}`;
+      }
+    } catch {
+      // If parsing JSON fails, use default error message
+    }
+    throw new Error(errorMessage);
+  }
+
+  const data = await response.json();
+  return data as T;
+}
+
+// Track event - uses ingestion API with project token
+export async function trackEvent(
+  event: string,
+  properties: Record<string, unknown>,
+  distinctId: string,
+): Promise<{ status: number; error?: string }> {
+  const projectToken = getProjectToken();
+  if (!projectToken) {
+    throw new Error(
+      "Not authenticated with Mixpanel. Please set MIXPANEL_PROJECT_TOKEN.",
+    );
+  }
+
+  const payload = {
+    event,
+    properties: {
+      ...properties,
+      token: projectToken,
+      distinct_id: distinctId,
+      time: Date.now(),
+    },
+  };
+
+  const response = await fetch(`${MIXPANEL_TRACK_BASE}/track`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify([payload]),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    return {
+      status: 0,
+      error: `Failed to track event: ${response.status} ${text}`,
+    };
+  }
+
+  const result = await response.json() as { status: number; error?: string };
+  return result;
+}
+
+// Query events - uses export API
+export async function queryEvents(
+  from: string,
+  to: string,
+  event?: string,
+): Promise<MixpanelEventResult[]> {
+  const projectId = getProjectId();
+  if (!projectId) {
+    throw new Error("Project ID not set. Please set MIXPANEL_PROJECT_ID.");
+  }
+
+  const params: Record<string, string> = {
+    from_date: from,
+    to_date: to,
+  };
+
+  if (event) {
+    params.event = JSON.stringify([event]);
+  }
+
+  const response = await mixpanelFetch<string[]>(
+    MIXPANEL_DATA_BASE,
+    "/export",
+    { params },
+  );
+
+  // Parse JSONL response (each line is a JSON object)
+  const events: MixpanelEventResult[] = [];
+  if (Array.isArray(response)) {
+    for (const line of response) {
+      if (typeof line === "string" && line.trim()) {
+        try {
+          const parsed = JSON.parse(line);
+          events.push({
+            event: parsed.event,
+            properties: parsed.properties,
+          });
+        } catch {
+          // Skip malformed lines
+        }
+      }
+    }
+  }
+
+  return events;
+}
+
+// Get funnel data
+export async function getFunnel(
+  funnelId: number,
+  from: string,
+  to: string,
+): Promise<MixpanelFunnel> {
+  const params: Record<string, string | number> = {
+    funnel_id: funnelId,
+    from_date: from,
+    to_date: to,
+    unit: "day",
+  };
+
+  return mixpanelFetch<MixpanelFunnel>(
+    MIXPANEL_DATA_BASE,
+    "/funnels",
+    { params },
+  );
+}
+
+// Get retention data
+export async function getRetention(
+  from: string,
+  to: string,
+  event: string,
+  retentionType: "birth" | "compounded" = "birth",
+): Promise<MixpanelRetention[]> {
+  const params: Record<string, string> = {
+    from_date: from,
+    to_date: to,
+    retention_type: retentionType,
+    born_event: event,
+    event,
+    unit: "day",
+  };
+
+  const response = await mixpanelFetch<Record<string, MixpanelRetention>>(
+    MIXPANEL_DATA_BASE,
+    "/retention",
+    { params },
+  );
+
+  // Convert object to array
+  return Object.entries(response).map(([date, data]) => ({
+    date,
+    ...data,
+  }));
+}
+
+// List cohorts
+export async function listCohorts(): Promise<MixpanelCohort[]> {
+  const projectId = getProjectId();
+  if (!projectId) {
+    throw new Error("Project ID not set. Please set MIXPANEL_PROJECT_ID.");
+  }
+
+  const response = await mixpanelFetch<MixpanelCohort[]>(
+    MIXPANEL_API_BASE,
+    `/2.0/cohorts/list`,
+    {
+      params: {
+        project_id: projectId,
+      },
+    },
+  );
+
+  return response;
+}
+
+// Helper functions
+export function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function getDateRange(days: number): { from: string; to: string } {
+  const to = new Date();
+  const from = new Date();
+  from.setDate(from.getDate() - days);
+
+  return {
+    from: formatDate(from),
+    to: formatDate(to),
+  };
+}
+
+export function calculateFunnelConversionRate(funnel: MixpanelFunnel): number {
+  if (!funnel.steps || funnel.steps.length < 2) {
+    return 0;
+  }
+
+  const firstStep = funnel.steps[0];
+  const lastStep = funnel.steps[funnel.steps.length - 1];
+
+  if (!firstStep || !lastStep || firstStep.count === 0) {
+    return 0;
+  }
+
+  return (lastStep.count / firstStep.count) * 100;
+}