@miranda0808/maya-codex 0.1.0

package/payload/tools/integrations/ga4.md

@@ -0,0 +1,126 @@
+# Google Analytics 4 (GA4)
+
+Web analytics platform for tracking user behavior, conversions, and marketing performance.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Data API for reports, Admin API for configuration |
+| MCP | ✓ | Available via Google Analytics MCP server |
+| CLI | - | Use gcloud for some operations |
+| SDK | ✓ | gtag.js, Google Analytics SDK for mobile |
+
+## Authentication
+
+- **Type**: OAuth 2.0 or Service Account
+- **Scopes**: `https://www.googleapis.com/auth/analytics.readonly` (read), `https://www.googleapis.com/auth/analytics.edit` (write)
+- **Setup**: Create credentials in Google Cloud Console
+
+## Common Agent Operations
+
+### Run a report (Data API)
+
+```bash
+POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runReport
+
+{
+  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
+  "dimensions": [{"name": "sessionSource"}],
+  "metrics": [{"name": "sessions"}, {"name": "conversions"}]
+}
+```
+
+### Get real-time data
+
+```bash
+POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runRealtimeReport
+
+{
+  "dimensions": [{"name": "country"}],
+  "metrics": [{"name": "activeUsers"}]
+}
+```
+
+### List conversion events
+
+```bash
+GET https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents
+```
+
+### Create a conversion event
+
+```bash
+POST https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents
+
+{
+  "eventName": "purchase"
+}
+```
+
+## Client-Side Tracking
+
+### Send custom event (gtag.js)
+
+```javascript
+gtag('event', 'signup_completed', {
+  'method': 'email',
+  'plan': 'free'
+});
+```
+
+### Send event via Measurement Protocol
+
+```bash
+POST https://www.google-analytics.com/mp/collect?measurement_id={measurement_id}&api_secret={api_secret}
+
+{
+  "client_id": "client_123",
+  "events": [{
+    "name": "purchase",
+    "params": {
+      "value": 99.99,
+      "currency": "USD"
+    }
+  }]
+}
+```
+
+## Key Dimensions & Metrics
+
+### Common Dimensions
+- `sessionSource` - Traffic source
+- `sessionMedium` - Traffic medium
+- `sessionCampaignName` - Campaign name
+- `landingPage` - Entry page
+- `deviceCategory` - Device type
+- `country` - User country
+
+### Common Metrics
+- `sessions` - Total sessions
+- `activeUsers` - Active users
+- `newUsers` - New users
+- `conversions` - Conversion events
+- `engagementRate` - Engaged sessions rate
+- `averageSessionDuration` - Session duration
+
+## When to Use
+
+- Tracking website traffic and user behavior
+- Measuring marketing campaign performance
+- Setting up conversion tracking
+- Analyzing user journeys and funnels
+- Attribution modeling
+
+## Rate Limits
+
+- Data API: 10 requests per second per property
+- Admin API: Varies by endpoint
+- Measurement Protocol: 1M hits/day for free tier
+
+## Relevant Skills
+
+- analytics-tracking
+- ab-test-setup
+- seo-audit
+- page-cro

package/payload/tools/integrations/google-ads.md

@@ -0,0 +1,159 @@
+# Google Ads
+
+Pay-per-click advertising platform for search, display, and video campaigns.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Google Ads API for campaign management |
+| MCP | ✓ | Available via Google Ads MCP server |
+| CLI | - | Use gcloud or API scripts |
+| SDK | ✓ | Client libraries for multiple languages |
+
+## Authentication
+
+- **Type**: OAuth 2.0
+- **Scopes**: `https://www.googleapis.com/auth/adwords`
+- **Setup**: Create credentials in Google Cloud Console, link to Google Ads account
+- **Headers**: `developer-token`, `login-customer-id` (for MCC)
+
+## Common Agent Operations
+
+### Get account info
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT customer.id, customer.descriptive_name FROM customer"
+}
+```
+
+### List campaigns
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT campaign.id, campaign.name, campaign.status, campaign_budget.amount_micros FROM campaign ORDER BY campaign.id"
+}
+```
+
+### Get campaign performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS"
+}
+```
+
+### Get ad group performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT ad_group.name, metrics.impressions, metrics.clicks, metrics.conversions FROM ad_group WHERE segments.date DURING LAST_7_DAYS"
+}
+```
+
+### Get keyword performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks, metrics.average_cpc FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 50"
+}
+```
+
+### Pause campaign
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaigns:mutate
+
+{
+  "operations": [{
+    "update": {
+      "resourceName": "customers/{customer_id}/campaigns/{campaign_id}",
+      "status": "PAUSED"
+    },
+    "updateMask": "status"
+  }]
+}
+```
+
+### Update budget
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaignBudgets:mutate
+
+{
+  "operations": [{
+    "update": {
+      "resourceName": "customers/{customer_id}/campaignBudgets/{budget_id}",
+      "amountMicros": "50000000"
+    },
+    "updateMask": "amountMicros"
+  }]
+}
+```
+
+## Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `metrics.impressions` | Ad impressions |
+| `metrics.clicks` | Clicks |
+| `metrics.cost_micros` | Cost in micros (divide by 1M) |
+| `metrics.conversions` | Conversions |
+| `metrics.conversions_value` | Conversion value |
+| `metrics.average_cpc` | Average cost per click |
+| `metrics.ctr` | Click-through rate |
+| `metrics.conversion_rate` | Conversion rate |
+
+## Campaign Types
+
+- `SEARCH` - Search network text ads
+- `DISPLAY` - Display network
+- `SHOPPING` - Product shopping ads
+- `VIDEO` - YouTube video ads
+- `PERFORMANCE_MAX` - AI-optimized across channels
+- `DEMAND_GEN` - Discovery/Demand Gen
+
+## GAQL (Google Ads Query Language)
+
+```sql
+SELECT
+  campaign.name,
+  metrics.clicks,
+  metrics.conversions
+FROM campaign
+WHERE
+  campaign.status = 'ENABLED'
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.conversions DESC
+LIMIT 10
+```
+
+## When to Use
+
+- Managing search advertising campaigns
+- Analyzing campaign performance
+- Adjusting budgets and bids
+- Keyword research and management
+- Conversion tracking analysis
+
+## Rate Limits
+
+- 15,000 operations per day (basic)
+- Higher limits with developer token levels
+
+## Relevant Skills
+
+- paid-ads
+- analytics-tracking
+- page-cro

package/payload/tools/integrations/google-search-console.md

@@ -0,0 +1,147 @@
+# Google Search Console
+
+Free tool for monitoring website search performance and indexing.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Search Analytics API, URL Inspection API |
+| MCP | - | Not available |
+| CLI | - | Use gcloud or API scripts |
+| SDK | ✓ | Google API client libraries |
+
+## Authentication
+
+- **Type**: OAuth 2.0 or Service Account
+- **Scopes**: `https://www.googleapis.com/auth/webmasters.readonly`
+- **Setup**: Create credentials in Google Cloud Console
+
+## Common Agent Operations
+
+### Get search analytics
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["query"],
+  "rowLimit": 100
+}
+```
+
+### Get performance by page
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["page"],
+  "rowLimit": 50
+}
+```
+
+### Get performance by country
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["country", "query"],
+  "rowLimit": 100
+}
+```
+
+### Inspect URL
+
+```bash
+POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
+
+{
+  "inspectionUrl": "https://example.com/page",
+  "siteUrl": "https://example.com/"
+}
+```
+
+### List sitemaps
+
+```bash
+GET https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/sitemaps
+
+Authorization: Bearer {access_token}
+```
+
+### Submit sitemap
+
+```bash
+PUT https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/sitemaps/{sitemap_url}
+
+Authorization: Bearer {access_token}
+```
+
+### Request indexing
+
+```bash
+POST https://indexing.googleapis.com/v3/urlNotifications:publish
+
+{
+  "url": "https://example.com/new-page",
+  "type": "URL_UPDATED"
+}
+```
+
+## Dimensions
+
+- `query` - Search query
+- `page` - Page URL
+- `country` - Country code
+- `device` - Device type (MOBILE, DESKTOP, TABLET)
+- `date` - Date
+- `searchAppearance` - Search result type
+
+## Metrics
+
+- `clicks` - Clicks from search
+- `impressions` - Search impressions
+- `ctr` - Click-through rate
+- `position` - Average position
+
+## Filters
+
+```json
+{
+  "dimensionFilterGroups": [{
+    "filters": [{
+      "dimension": "query",
+      "operator": "contains",
+      "expression": "keyword"
+    }]
+  }]
+}
+```
+
+## When to Use
+
+- Analyzing search performance
+- Finding keyword opportunities
+- Monitoring indexing status
+- Submitting new pages for indexing
+- Identifying crawl issues
+- Tracking position changes
+
+## Rate Limits
+
+- 200 queries per minute
+- 1,200 requests per minute
+
+## Relevant Skills
+
+- seo-audit
+- programmatic-seo
+- analytics-tracking

package/payload/tools/integrations/hotjar.md

@@ -0,0 +1,147 @@
+# Hotjar
+
+Behavior analytics platform with heatmaps, session recordings, and surveys for understanding user experience.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Surveys, Responses, Sites, Heatmaps, Recordings |
+| MCP | - | Not available |
+| CLI | ✓ | [hotjar.js](../clis/hotjar.js) |
+| SDK | ✓ | JavaScript tracking snippet, Identify API, Events API |
+
+## Authentication
+
+- **Type**: OAuth 2.0 Client Credentials
+- **Token endpoint**: `POST https://api.hotjar.io/v1/oauth/token`
+- **Header**: `Authorization: Bearer {access_token}`
+- **Get credentials**: Hotjar Dashboard > Integrations > API
+- **Token expiry**: 3600 seconds (1 hour)
+
+### Token Request
+
+```bash
+POST https://api.hotjar.io/v1/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
+```
+
+### Token Response
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+## Common Agent Operations
+
+### List Sites
+
+```bash
+GET https://api.hotjar.io/v1/sites
+
+Authorization: Bearer {access_token}
+```
+
+### List Surveys
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/surveys
+
+Authorization: Bearer {access_token}
+```
+
+### Get Survey Responses
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/surveys/{survey_id}/responses?limit=100
+
+Authorization: Bearer {access_token}
+```
+
+Supports cursor-based pagination with `cursor` and `limit` parameters.
+
+### List Heatmaps
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/heatmaps
+
+Authorization: Bearer {access_token}
+```
+
+### List Recordings
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/recordings
+
+Authorization: Bearer {access_token}
+```
+
+### List Forms
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/forms
+
+Authorization: Bearer {access_token}
+```
+
+## Key Metrics
+
+### Survey Response Data
+- `response_id` - Unique response identifier
+- `answers` - Array of question/answer pairs
+- `created_at` - Response timestamp
+- `device_type` - Desktop, mobile, tablet
+
+### Heatmap Data
+- `url` - Page URL
+- `click_count` - Total clicks tracked
+- `visitors` - Unique visitors
+- `created_at` - Heatmap creation date
+
+### Recording Data
+- `recording_id` - Unique recording ID
+- `duration` - Session duration
+- `pages_visited` - Pages in session
+- `device` - Device information
+
+## Parameters
+
+### Survey Responses
+- `limit` - Results per page (default: 100)
+- `cursor` - Pagination cursor from previous response
+- `sort` - Sort order (default: created_at desc)
+
+### Recordings
+- `limit` - Results per page
+- `cursor` - Pagination cursor
+- `date_from` - Start date filter
+- `date_to` - End date filter
+
+## When to Use
+
+- Analyzing user behavior patterns on landing pages
+- Collecting qualitative feedback via on-site surveys
+- Identifying UX issues through session recordings
+- Understanding scroll depth and engagement via heatmaps
+- Validating CRO hypotheses with user behavior data
+- Form abandonment analysis
+
+## Rate Limits
+
+- 3000 requests/minute (50 per second)
+- Rate limited by source IP address
+- Cursor-based pagination for large result sets
+
+## Relevant Skills
+
+- page-cro
+- ab-test-setup
+- analytics-tracking
+- ux-audit
+- landing-page