arkaos 4.26.0 → 4.28.0

package/departments/marketing/tools/composio/README.md

@@ -0,0 +1,105 @@
+# Composio Quick Start
+
+Get MCP access to 500+ marketing tools through a single integration.
+
+## Prerequisites
+
+- Node.js 18+
+- Claude Code installed
+
+## Install
+
+```bash
+npx @composio/mcp@latest setup
+```
+
+Verify by running `/mcp` in Claude Code — `composio` should appear in the server list.
+
+## Connect a Tool
+
+When you ask the agent to use a Composio-backed tool for the first time, it will provide a Connect Link. Open the link in your browser, authorize the app, and you're set. The connection persists across sessions.
+
+```
+You: "Get my top HubSpot contacts"
+Agent: "Please connect HubSpot first: https://app.composio.dev/connect/..."
+# Click the link → authorize → return to Claude Code
+Agent: "Here are your top contacts: ..."
+```
+
+## Usage Examples
+
+### Pull CRM contacts
+
+```
+"Show me my 10 most recent HubSpot contacts with their deal stages"
+```
+
+### Get ad performance
+
+```
+"What's my Meta Ads spend and ROAS for the last 7 days?"
+```
+
+### Write to a spreadsheet
+
+```
+"Add a row to my 'Campaign Tracker' Google Sheet with today's LinkedIn Ads metrics"
+```
+
+### Cross-tool workflow
+
+```
+"Find Salesforce leads from this week and post a summary in Slack #new-leads"
+```
+
+## Available Marketing Tools
+
+See [marketing-tools.md](marketing-tools.md) for the full list of Composio toolkits mapped to marketing use cases.
+
+Key tools with new MCP access (no native MCP server in this repo):
+- **HubSpot** — contacts, deals, companies, lists
+- **Salesforce** — SOQL queries, leads, opportunities
+- **Meta Ads** — campaigns, ad sets, insights
+- **LinkedIn Ads** — campaigns, analytics
+- **Google Sheets** — read, write, create spreadsheets
+- **Slack** — messages, channels
+- **Notion** — pages, databases
+- **Klaviyo** — profiles, lists, campaigns
+- **ActiveCampaign** — contacts, automations
+
+## Troubleshooting
+
+### "Tool not found" error
+
+The tool may not be connected yet. Ask the agent to connect it, or run:
+
+```bash
+npx composio apps list
+```
+
+### Expired authentication
+
+OAuth tokens expire. If a tool stops working, re-authenticate:
+
+```bash
+npx composio connections list    # Find the connection
+npx composio connections remove {id}  # Remove it
+# Then ask the agent to use the tool again to trigger re-auth
+```
+
+### Rate limit errors
+
+Composio has its own rate limits (free: 20K calls/mo, 10 req/sec). If you hit them:
+- Reduce request frequency
+- Upgrade your Composio plan
+- Use native CLI tools for high-volume operations
+
+### MCP server not appearing
+
+Re-run the setup command:
+
+```bash
+npx @composio/mcp@latest setup
+```
+
+Then restart Claude Code.

package/departments/marketing/tools/composio/marketing-tools.md

@@ -0,0 +1,91 @@
+# Composio Marketing Tools
+
+Detailed mapping of Composio toolkits to marketing use cases. Organized by the same categories as [REGISTRY.md](../REGISTRY.md).
+
+## CRM
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `HUBSPOT` | OAuth 2.0 | Get/create contacts, list deals by stage, get company info, manage lists, search contacts by property | Deep |
+| `SALESFORCE` | OAuth 2.0 | Run SOQL queries, get/create leads, list opportunities, get account details, update records | Deep |
+
+## Email & SMS
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `ACTIVECAMPAIGN` | API Key | Get contacts, list automations, add contacts to lists, get campaign stats | Medium |
+| `KLAVIYO` | API Key | Get profiles, list segments, get campaign metrics, add to lists | Medium |
+| `MAILCHIMP` | OAuth 2.0 | Get audiences, list campaigns, get campaign reports, add subscribers | Deep |
+| `GMAIL` | OAuth 2.0 | Send emails, search inbox, read messages, manage labels | Deep |
+
+## Advertising
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `FACEBOOKADS` | OAuth 2.0 | Get campaign insights, list ad sets, get ad performance, read audience data | Medium |
+| `LINKEDIN` | OAuth 2.0 | Get campaign analytics, list campaigns, get company page stats | Medium |
+| `GOOGLEADS` | OAuth 2.0 | Get campaign performance, list ad groups, keyword stats | Medium |
+
+## Productivity & Collaboration
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `GOOGLESHEETS` | OAuth 2.0 | Read/write cells, create sheets, format ranges, append rows | Deep |
+| `SLACK` | OAuth 2.0 | Send messages, read channels, upload files, search messages | Deep |
+| `NOTION` | OAuth 2.0 | Read/create pages, query databases, update blocks, search | Deep |
+| `AIRTABLE` | OAuth 2.0 | List/create/update records, query views, manage tables | Deep |
+
+## Commerce
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `SHOPIFY` | OAuth 2.0 | Get products, list orders, get customer data, inventory levels | Deep |
+
+## Analytics
+
+| Composio Toolkit | Auth | Key Marketing Actions | Depth |
+|-----------------|------|----------------------|-------|
+| `GOOGLEANALYTICS` | OAuth 2.0 | Run reports, get real-time data, list properties | Medium |
+
+## Coverage Depth Guide
+
+- **Deep** — 20+ actions, covers most common operations, suitable for daily use
+- **Medium** — 5-20 actions, covers core read operations and some writes
+- **Shallow** — Under 5 actions, basic read-only access
+
+## Coverage vs. Native Tools
+
+This table shows where Composio adds value compared to what's already in the MarketingSkills registry:
+
+| Tool | Native MCP | Native CLI | Composio MCP | Recommendation |
+|------|:----------:|:----------:|:------------:|----------------|
+| HubSpot | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Salesforce | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Meta Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| LinkedIn Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Google Sheets | - | - | ✓ | **Use Composio** — only MCP option |
+| Slack | - | - | ✓ | **Use Composio** — only MCP option |
+| Notion | - | - | ✓ | **Use Composio** — only MCP option |
+| Airtable | - | - | ✓ | **Use Composio** — only MCP option |
+| ActiveCampaign | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Klaviyo | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Shopify | - | ✓ | ✓ | **Use Composio** — adds MCP access |
+| Gmail | - | - | ✓ | **Use Composio** — only MCP option |
+| GA4 | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
+| Stripe | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
+| Mailchimp | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
+| Google Ads | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
+
+## Toolkit Reference
+
+Each Composio toolkit name maps to its `TOOL_NAME` identifier used in the Composio platform. When searching for available actions, use these exact names:
+
+```bash
+# List all actions for a toolkit
+npx composio actions list --app HUBSPOT
+
+# Search for specific actions
+npx composio actions list --app FACEBOOKADS --search "insights"
+```
+
+For the full integration guide including setup, pricing, and limitations, see [composio.md](../integrations/composio.md).

package/departments/marketing/tools/integrations/activecampaign.md

@@ -0,0 +1,337 @@
+# ActiveCampaign
+
+Email marketing automation platform with CRM, contacts, deals pipeline, tags, automations, and campaign management.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API v3 for contacts, deals, automations, campaigns, tags |
+| MCP | - | Not available |
+| CLI | ✓ | [activecampaign.js](../clis/activecampaign.js) |
+| SDK | ✓ | Python, PHP, Node.js, Ruby |
+
+## Authentication
+
+- **Type**: API Token
+- **Header**: `Api-Token: {api_token}`
+- **Base URL**: `https://{yourAccountName}.api-us1.com/api/3`
+- **Get key**: Settings > Developer tab in your ActiveCampaign account
+- **Note**: Each user has a unique API key. Base URL is account-specific (found in Settings > Developer).
+
+## Common Agent Operations
+
+### Get current user
+
+```bash
+GET https://{account}.api-us1.com/api/3/users/me
+```
+
+### List contacts
+
+```bash
+GET https://{account}.api-us1.com/api/3/contacts?limit=20&offset=0
+
+# Search by email
+GET https://{account}.api-us1.com/api/3/contacts?email=user@example.com
+
+# Search by name
+GET https://{account}.api-us1.com/api/3/contacts?search=Jane
+```
+
+### Create contact
+
+```bash
+POST https://{account}.api-us1.com/api/3/contacts
+
+{
+  "contact": {
+    "email": "user@example.com",
+    "firstName": "Jane",
+    "lastName": "Doe",
+    "phone": "+15551234567"
+  }
+}
+```
+
+### Update contact
+
+```bash
+PUT https://{account}.api-us1.com/api/3/contacts/{contactId}
+
+{
+  "contact": {
+    "firstName": "Updated",
+    "lastName": "Name"
+  }
+}
+```
+
+### Sync contact (create or update)
+
+```bash
+POST https://{account}.api-us1.com/api/3/contact/sync
+
+{
+  "contact": {
+    "email": "user@example.com",
+    "firstName": "Jane",
+    "lastName": "Doe"
+  }
+}
+```
+
+### Delete contact
+
+```bash
+DELETE https://{account}.api-us1.com/api/3/contacts/{contactId}
+```
+
+### List all lists
+
+```bash
+GET https://{account}.api-us1.com/api/3/lists?limit=20&offset=0
+```
+
+### Create list
+
+```bash
+POST https://{account}.api-us1.com/api/3/lists
+
+{
+  "list": {
+    "name": "Newsletter",
+    "stringid": "newsletter",
+    "sender_url": "https://example.com",
+    "sender_reminder": "You signed up for our newsletter."
+  }
+}
+```
+
+### Subscribe contact to list
+
+```bash
+POST https://{account}.api-us1.com/api/3/contactLists
+
+{
+  "contactList": {
+    "list": "1",
+    "contact": "1",
+    "status": 1
+  }
+}
+```
+
+### Unsubscribe contact from list
+
+```bash
+POST https://{account}.api-us1.com/api/3/contactLists
+
+{
+  "contactList": {
+    "list": "1",
+    "contact": "1",
+    "status": 2
+  }
+}
+```
+
+### List campaigns
+
+```bash
+GET https://{account}.api-us1.com/api/3/campaigns?limit=20&offset=0
+```
+
+### List deals
+
+```bash
+GET https://{account}.api-us1.com/api/3/deals?limit=20&offset=0
+
+# Filter by pipeline stage
+GET https://{account}.api-us1.com/api/3/deals?filters[stage]=1
+```
+
+### Create deal
+
+```bash
+POST https://{account}.api-us1.com/api/3/deals
+
+{
+  "deal": {
+    "title": "New Enterprise Deal",
+    "value": 50000,
+    "currency": "usd",
+    "group": "1",
+    "stage": "1",
+    "owner": "1",
+    "contact": "1"
+  }
+}
+```
+
+### Update deal
+
+```bash
+PUT https://{account}.api-us1.com/api/3/deals/{dealId}
+
+{
+  "deal": {
+    "stage": "2",
+    "value": 75000
+  }
+}
+```
+
+### List automations
+
+```bash
+GET https://{account}.api-us1.com/api/3/automations?limit=20&offset=0
+```
+
+### Add contact to automation
+
+```bash
+POST https://{account}.api-us1.com/api/3/contactAutomations
+
+{
+  "contactAutomation": {
+    "contact": "1",
+    "automation": "1"
+  }
+}
+```
+
+### List tags
+
+```bash
+GET https://{account}.api-us1.com/api/3/tags?limit=20&offset=0
+```
+
+### Create tag
+
+```bash
+POST https://{account}.api-us1.com/api/3/tags
+
+{
+  "tag": {
+    "tag": "VIP Customer",
+    "tagType": "contact"
+  }
+}
+```
+
+### Add tag to contact
+
+```bash
+POST https://{account}.api-us1.com/api/3/contactTags
+
+{
+  "contactTag": {
+    "contact": "1",
+    "tag": "1"
+  }
+}
+```
+
+### List pipelines (deal groups)
+
+```bash
+GET https://{account}.api-us1.com/api/3/dealGroups?limit=20&offset=0
+```
+
+### List webhooks
+
+```bash
+GET https://{account}.api-us1.com/api/3/webhooks?limit=20&offset=0
+```
+
+### Create webhook
+
+```bash
+POST https://{account}.api-us1.com/api/3/webhooks
+
+{
+  "webhook": {
+    "name": "Contact Updated",
+    "url": "https://example.com/webhook",
+    "events": ["subscribe", "unsubscribe"],
+    "sources": ["public", "admin", "api", "system"]
+  }
+}
+```
+
+## API Pattern
+
+ActiveCampaign uses REST with resource wrapping (e.g., `{ "contact": {...} }`). Responses include the resource object plus metadata. Related resources are managed via junction endpoints (e.g., `/contactLists`, `/contactTags`, `/contactAutomations`). The base URL is account-specific. Pagination uses `limit` and `offset` parameters.
+
+## Key Metrics
+
+### Contact Fields
+- `email` - Email address
+- `firstName`, `lastName` - Name fields
+- `phone` - Phone number
+- `cdate` - Creation date
+- `udate` - Last updated date
+- `deals` - Related deals count
+
+### Deal Fields
+- `title` - Deal name
+- `value` - Deal value in cents
+- `currency` - Currency code
+- `stage` - Pipeline stage ID
+- `group` - Pipeline (deal group) ID
+- `owner` - Assigned user ID
+- `status` - 0 (open), 1 (won), 2 (lost)
+
+### Campaign Metrics
+- `sends` - Total sends
+- `opens` - Opens count
+- `clicks` - Clicks count
+- `uniqueopens` - Unique opens
+- `uniquelinks` - Unique clicks
+
+## Parameters
+
+### Contact List Status
+- `1` - Subscribed (active)
+- `2` - Unsubscribed
+
+### Deal Status
+- `0` - Open
+- `1` - Won
+- `2` - Lost
+
+### Tag Types
+- `contact` - Contact tags
+- `deal` - Deal tags
+
+### Common Query Parameters
+- `limit` - Results per page (default 20)
+- `offset` - Skip N results
+- `search` - Text search
+- `email` - Filter contacts by email
+- `filters[stage]` - Filter deals by stage
+- `filters[owner]` - Filter deals by owner
+
+## When to Use
+
+- Marketing automation with complex conditional workflows
+- CRM with deal pipeline management
+- Contact management with tagging and segmentation
+- Email campaign creation and tracking
+- Triggering automations based on external events
+- B2B sales pipeline tracking integrated with marketing
+
+## Rate Limits
+
+- 5 requests per second per account
+- Rate limit applies across all API users on the same account
+- 429 responses include `Retry-After` header
+
+## Relevant Skills
+
+- emails
+- lifecycle-marketing
+- crm-integration
+- sales-pipeline
+- marketing-automation

package/departments/marketing/tools/integrations/adobe-analytics.md

@@ -0,0 +1,156 @@
+# Adobe Analytics
+
+Enterprise analytics platform for cross-channel measurement and attribution.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Reporting API 2.0, Data Insertion API |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | ✓ | AppMeasurement.js, Mobile SDKs, Launch |
+
+## Authentication
+
+- **Type**: OAuth 2.0 (Service Account JWT)
+- **Setup**: Create integration in Adobe Developer Console
+- **Header**: `Authorization: Bearer {access_token}`
+
+## Common Agent Operations
+
+### Get report suite info
+
+```bash
+GET https://analytics.adobe.io/api/{company_id}/reportsuites
+
+Authorization: Bearer {access_token}
+x-api-key: {client_id}
+```
+
+### Get dimensions
+
+```bash
+GET https://analytics.adobe.io/api/{company_id}/dimensions?rsid={report_suite_id}
+
+Authorization: Bearer {access_token}
+x-api-key: {client_id}
+```
+
+### Get metrics
+
+```bash
+GET https://analytics.adobe.io/api/{company_id}/metrics?rsid={report_suite_id}
+
+Authorization: Bearer {access_token}
+x-api-key: {client_id}
+```
+
+### Run report
+
+```bash
+POST https://analytics.adobe.io/api/{company_id}/reports
+
+{
+  "rsid": "{report_suite_id}",
+  "globalFilters": [{
+    "type": "dateRange",
+    "dateRange": "2024-01-01T00:00:00/2024-01-31T23:59:59"
+  }],
+  "metricContainer": {
+    "metrics": [
+      {"id": "metrics/visits"},
+      {"id": "metrics/pageviews"},
+      {"id": "metrics/orders"}
+    ]
+  },
+  "dimension": "variables/evar1"
+}
+```
+
+### Get segments
+
+```bash
+GET https://analytics.adobe.io/api/{company_id}/segments?rsid={report_suite_id}
+
+Authorization: Bearer {access_token}
+x-api-key: {client_id}
+```
+
+### Data Insertion (server-side)
+
+```bash
+POST https://{tracking_server}/b/ss/{report_suite_id}/0
+
+<?xml version="1.0" encoding="UTF-8"?>
+<request>
+  <visitorID>user_123</visitorID>
+  <events>event1</events>
+  <eVar1>campaign_name</eVar1>
+  <prop1>page_type</prop1>
+</request>
+```
+
+## AppMeasurement.js
+
+```javascript
+// Initialize
+var s = s_gi('report_suite_id');
+s.trackingServer = 'metrics.example.com';
+
+// Set variables
+s.pageName = 'Home Page';
+s.channel = 'Marketing';
+s.eVar1 = 'campaign_name';
+s.events = 'event1';
+
+// Track page view
+s.t();
+
+// Track link
+s.tl(this, 'o', 'Button Click');
+```
+
+## Key Concepts
+
+- **Report Suite** - Data container
+- **eVars** - Conversion variables (persistent)
+- **props** - Traffic variables (hit-level)
+- **Events** - Success metrics
+- **Segments** - User/visit filters
+- **Calculated Metrics** - Derived metrics
+
+## Common Dimensions
+
+- `variables/page` - Page name
+- `variables/evar1` - Custom conversion variable
+- `variables/prop1` - Custom traffic variable
+- `variables/marketingchannel` - Marketing channel
+- `variables/referringdomain` - Referring domain
+
+## Common Metrics
+
+- `metrics/visits` - Visits
+- `metrics/pageviews` - Page views
+- `metrics/uniquevisitors` - Unique visitors
+- `metrics/orders` - Orders
+- `metrics/revenue` - Revenue
+
+## When to Use
+
+- Enterprise-scale analytics
+- Cross-channel attribution
+- Integration with Adobe Experience Cloud
+- Advanced segmentation
+- Data warehouse exports
+
+## Rate Limits
+
+- 12 requests/second per company
+- 120 requests/minute
+
+## Relevant Skills
+
+- analytics
+- ab-testing
+- ads