New Integration: Amplitude

Description

Add Amplitude integration to sync product analytics events, user data, cohorts, and behavioral data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github-analytics/ - Analytics-oriented integration
• integrations/linear/ - Project management integration
• integrations/hubspot/ - For user/contact data sync reference

Required Files Structure

integrations/amplitude/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Amplitude API utilities
│   ├── account-create.ts # API key setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Amplitude API Integration

OAuth Setup

• Use API Key + Secret Key authentication
• Keys available from Amplitude project settings
• HTTP API V2 (V1 is deprecated)
• Base URL: https://amplitude.com/api/2

Key Endpoints

• POST /2/events - Track events (HTTP API V2)
• GET /2/export - Export raw event data (date-range based)
• GET /2/users/{user_id}/events - Get user events
• GET /2/usersearch - Search for users
• GET /2/useractivity - Get user activity
• GET /2/cohorts - List cohorts
• GET /2/cohorts/{id} - Get cohort details
• GET /2/annotations - List annotations
• GET /2/charts/{id}/query - Query chart data
• GET /2/taxonomy/event-types - List event types

Events to Track

1. Events - All tracked product analytics events
2. User Activity - User sessions, actions, and behavioral data
3. Cohorts - User cohort membership and updates
4. Annotations - Project annotations and notes
5. Charts/Reports - Saved chart and dashboard data

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement API Key + Secret authentication in account-create.ts
• Create API utilities in utils.ts with Amplitude HTTP API V2 client
• Implement sync logic in schedule.ts for events, users, cohorts
• Convert Amplitude analytics data to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Use HTTP API V2 (V1 is deprecated)
• Export API returns gzipped JSON for large data sets
• Date-range based export supports incremental syncing
• Rate limits vary by API endpoint and plan
• Supports both US and EU data centers
• Taxonomy API provides metadata about event types and properties
• Batch event upload supports up to 10 events per request (standard) or 1000+ (batch endpoint)

Resources

• Amplitude API Documentation
• Amplitude SDKs
• Amplitude Developers Portal
• Amplitude API Postman Collection

Labels

enhancement, integration, new-feature

Start by comparing integrations/github-analytics/, integrations/linear/, and integrations/hubspot/, especially the integrations/github/src/index.ts pattern. Then work through the required integrations/amplitude/ files and the listed Amplitude API endpoints, defining how authentication, incremental sync, activity formatting, rate limiting, and data-center support fit together. Done means the integration structure, documentation, README entry, and requested events, users, cohorts, annotations, and chart data are covered.