arkaos 4.26.0 → 4.28.0

package/departments/marketing/tools/integrations/meta-ads.md

@@ -0,0 +1,147 @@
+# Meta Ads (Facebook/Instagram)
+
+Advertising platform for Facebook, Instagram, Messenger, and Audience Network.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Marketing API for campaigns, audiences, reporting |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | ✓ | Official SDKs for Python, PHP, Node.js |
+
+## Authentication
+
+- **Type**: OAuth 2.0 Access Token
+- **Header**: Access token as query parameter
+- **Setup**: Create app in Meta Business Suite, generate System User token
+
+## Common Agent Operations
+
+### Get ad accounts
+
+```bash
+GET https://graph.facebook.com/v18.0/me/adaccounts?access_token={access_token}&fields=id,name,account_status
+```
+
+### Get campaigns
+
+```bash
+GET https://graph.facebook.com/v18.0/act_{ad_account_id}/campaigns?access_token={access_token}&fields=id,name,status,objective,daily_budget
+```
+
+### Get campaign insights
+
+```bash
+GET https://graph.facebook.com/v18.0/{campaign_id}/insights?access_token={access_token}&fields=impressions,clicks,spend,actions,cost_per_action_type&date_preset=last_30d
+```
+
+### Get ad sets
+
+```bash
+GET https://graph.facebook.com/v18.0/act_{ad_account_id}/adsets?access_token={access_token}&fields=id,name,status,targeting,daily_budget,bid_amount
+```
+
+### Get ads
+
+```bash
+GET https://graph.facebook.com/v18.0/{ad_set_id}/ads?access_token={access_token}&fields=id,name,status,creative
+```
+
+### Create campaign
+
+```bash
+POST https://graph.facebook.com/v18.0/act_{ad_account_id}/campaigns
+
+access_token={access_token}
+&name=Campaign Name
+&objective=CONVERSIONS
+&status=PAUSED
+&special_ad_categories=[]
+```
+
+### Update campaign status
+
+```bash
+POST https://graph.facebook.com/v18.0/{campaign_id}
+
+access_token={access_token}
+&status=ACTIVE
+```
+
+### Get custom audiences
+
+```bash
+GET https://graph.facebook.com/v18.0/act_{ad_account_id}/customaudiences?access_token={access_token}&fields=id,name,approximate_count
+```
+
+### Create lookalike audience
+
+```bash
+POST https://graph.facebook.com/v18.0/act_{ad_account_id}/customaudiences
+
+access_token={access_token}
+&name=Lookalike - Top Customers
+&subtype=LOOKALIKE
+&origin_audience_id={source_audience_id}
+&lookalike_spec={"type":"similarity","country":"US"}
+```
+
+## Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `impressions` | Ad impressions |
+| `clicks` | All clicks |
+| `spend` | Amount spent |
+| `reach` | Unique people reached |
+| `frequency` | Avg impressions per person |
+| `cpm` | Cost per 1000 impressions |
+| `cpc` | Cost per click |
+| `actions` | Conversions array |
+| `cost_per_action_type` | CPA by action |
+
+## Campaign Objectives
+
+- `AWARENESS` - Brand awareness
+- `TRAFFIC` - Website traffic
+- `ENGAGEMENT` - Post engagement
+- `LEADS` - Lead generation
+- `APP_PROMOTION` - App installs
+- `SALES` - Conversions/catalog sales
+
+## Targeting Options
+
+```json
+{
+  "geo_locations": {
+    "countries": ["US"],
+    "cities": [{"key": "2420379"}]
+  },
+  "age_min": 25,
+  "age_max": 45,
+  "genders": [1, 2],
+  "interests": [{"id": "6003139266461", "name": "Marketing"}],
+  "behaviors": [{"id": "6002714895372"}]
+}
+```
+
+## When to Use
+
+- Creating/managing Facebook and Instagram ads
+- Audience targeting and lookalikes
+- Campaign performance analysis
+- Retargeting setup
+
+## Rate Limits
+
+- 200 calls/hour per ad account
+- 60 calls/hour for marketing API
+- Use batch requests for efficiency
+
+## Relevant Skills
+
+- ads
+- analytics
+- cro

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

@@ -0,0 +1,137 @@
+# Mixpanel
+
+Product analytics platform for tracking user behavior and retention.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Ingestion API, Query API, Data Export |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | ✓ | JavaScript, iOS, Android, Python, etc. |
+
+## Authentication
+
+- **Ingestion**: Project token (public)
+- **Query API**: Service Account (username:secret as Basic auth)
+- **Export**: API Secret
+
+## Common Agent Operations
+
+### Track event (Ingestion API)
+
+```bash
+POST https://api.mixpanel.com/track
+
+{
+  "event": "signup_completed",
+  "properties": {
+    "token": "{project_token}",
+    "distinct_id": "user_123",
+    "plan": "pro",
+    "time": 1705312800
+  }
+}
+```
+
+### Set user profile
+
+```bash
+POST https://api.mixpanel.com/engage
+
+{
+  "$token": "{project_token}",
+  "$distinct_id": "user_123",
+  "$set": {
+    "$email": "user@example.com",
+    "$name": "John Doe",
+    "plan": "pro"
+  }
+}
+```
+
+### Query events (Query API)
+
+```bash
+POST https://mixpanel.com/api/2.0/insights
+
+{
+  "project_id": {project_id},
+  "bookmark_id": null,
+  "params": {
+    "events": [{"event": "signup_completed"}],
+    "time_range": {
+      "from_date": "2024-01-01",
+      "to_date": "2024-01-31"
+    }
+  }
+}
+```
+
+### Get funnel data
+
+```bash
+GET https://mixpanel.com/api/2.0/funnels?funnel_id={funnel_id}&from_date=2024-01-01&to_date=2024-01-31
+```
+
+### Export raw events
+
+```bash
+GET https://data.mixpanel.com/api/2.0/export?from_date=2024-01-01&to_date=2024-01-01
+```
+
+### Get retention data
+
+```bash
+GET https://mixpanel.com/api/2.0/retention?from_date=2024-01-01&to_date=2024-01-31&retention_type=birth&born_event=signup_completed
+```
+
+## JavaScript SDK
+
+```javascript
+// Initialize
+mixpanel.init('YOUR_TOKEN');
+
+// Identify user
+mixpanel.identify('user_123');
+
+// Set user properties
+mixpanel.people.set({
+  '$email': 'user@example.com',
+  'plan': 'pro'
+});
+
+// Track event
+mixpanel.track('Feature Used', {
+  'feature_name': 'export'
+});
+```
+
+## Key Concepts
+
+- **Events** - User actions (signup, purchase, etc.)
+- **Properties** - Attributes on events
+- **User Profiles** - Persistent user data
+- **Cohorts** - Saved user segments
+- **Funnels** - Conversion sequences
+- **Retention** - User return patterns
+
+## When to Use
+
+- Tracking product usage events
+- Analyzing conversion funnels
+- Measuring feature adoption
+- Retention analysis
+- User segmentation
+
+## Rate Limits
+
+- Ingestion: No hard limit (batch recommended)
+- Query API: Varies by plan
+
+## Relevant Skills
+
+- analytics
+- ab-testing
+- onboarding

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

@@ -0,0 +1,113 @@
+# Nitrosend
+
+AI-native email platform that combines transactional and marketing email in one stack, controlled entirely through AI assistants via MCP. No traditional dashboard required — build sequences, campaigns, and automations by prompting.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API available |
+| MCP | ✓ | Full MCP support — primary integration method |
+| CLI | - | Not available |
+| SDK | - | Use MCP or API directly |
+
+## Authentication
+
+- **Type**: API Key
+- **MCP Setup**: Add Nitrosend MCP server to your Claude Code / AI assistant config
+- **BYO Infrastructure**: Optionally bring your own SendGrid, Postmark, SES, or Resend keys
+- **Get access**: Sign up at nitrosend.com — free tier includes 8K emails initially, then 500/month
+
+## Pricing
+
+| Plan | Cost | Volume |
+|------|------|--------|
+| Free | $0 | 8K initially, then 500/mo |
+| Hobby | $20/mo | 25,000/mo |
+| Pro | $100/mo | 150,000/mo |
+| Scale | $300/mo | 500,000/mo |
+| BYO | $60/mo | Unlimited (your infrastructure) |
+
+Unlimited contacts on all plans — pay per email sent, not per subscriber.
+
+## What Makes It Different
+
+- **AI-first**: Designed to be controlled by Claude, ChatGPT, Codex, Cursor, Gemini, Windsurf — not a human clicking through a dashboard
+- **Unified transactional + marketing**: Single platform for both, on separate infrastructure
+- **Automatic optimization**: Continuously tests subject lines, send times, and content based on engagement
+- **Auto-configured deliverability**: DKIM, SPF, DMARC, and dedicated IP warmup handled automatically
+- **Migration-friendly**: Import from Mailchimp, Klaviyo, ActiveCampaign, HubSpot
+
+## Common Agent Operations (via MCP)
+
+### Create an email sequence
+
+```
+"Create a 5-email onboarding sequence for new SaaS trial users.
+Email 1: Welcome + what to do first (send immediately)
+Email 2: Key feature highlight (day 2)
+Email 3: Use case / success story (day 4)
+Email 4: Check-in + support offer (day 7)
+Email 5: Upgrade prompt (day 12)"
+```
+
+Nitrosend builds the sequence, timing, and sends — no manual setup in a dashboard.
+
+### Send a transactional email
+
+```
+"Send a password reset email to user@example.com with a reset link valid for 1 hour."
+```
+
+### Create a campaign
+
+```
+"Create a re-engagement campaign for subscribers who haven't opened in 90 days.
+Subject line variants: [A] 'We miss you', [B] 'Still interested in [topic]?'
+Test both, send winner to remaining list after 4 hours."
+```
+
+### Check sequence performance
+
+```
+"Show me open rates, click rates, and unsubscribes for the onboarding sequence."
+```
+
+### Import a list
+
+```
+"Import this CSV of 2,000 subscribers from our Mailchimp export."
+```
+
+## Deliverability Setup
+
+Nitrosend handles this automatically on signup:
+- DKIM signing
+- SPF record configuration
+- DMARC policy
+- Dedicated IP provisioning (Pro+)
+- IP warmup schedule
+
+For BYO plan users: bring your own SendGrid, Postmark, SES, or Resend account and Nitrosend routes through your infrastructure.
+
+## When to Use
+
+- Building email sequences via AI without touching a dashboard
+- Teams already using Claude Code or other AI coding tools as their primary workflow
+- Combining transactional (password resets, receipts) and marketing (nurture, campaigns) in one place
+- Rapid sequence prototyping — describe the sequence, get it built
+- Migrating from Mailchimp/Klaviyo and wanting AI control going forward
+
+## When to Use Something Else
+
+- **Customer.io** — if you need complex event-based branching logic and behavioral triggers
+- **Klaviyo** — if you're in e-commerce and need deep Shopify integration
+- **Resend** — if you need transactional-only and prefer a pure API/code approach
+- **Kit** — if you're a creator or newsletter-first
+
+## Relevant Skills
+
+- emails
+- onboarding
+- churn-prevention
+- lead-magnets

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

@@ -0,0 +1,229 @@
+# OneSignal
+
+Push notification, email, SMS, and in-app messaging platform for customer engagement at scale.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Notifications, Users, Segments, Templates, Apps |
+| MCP | - | Not available |
+| CLI | ✓ | [onesignal.js](../clis/onesignal.js) |
+| SDK | ✓ | JavaScript, Node.js, Python, Java, PHP, Ruby, Go, .NET |
+
+## Authentication
+
+- **Type**: REST API Key (Basic Auth)
+- **Header**: `Authorization: Basic {REST_API_KEY}`
+- **App ID**: Required as `app_id` in request bodies
+- **Get credentials**: Dashboard > Settings > Keys & IDs
+- **Security**: HTTPS required, TLS 1.2+ on port 443
+
+## Common Agent Operations
+
+### Send push notification to segment
+
+```bash
+POST https://api.onesignal.com/api/v1/notifications
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+  Content-Type: application/json
+
+{
+  "app_id": "YOUR_APP_ID",
+  "included_segments": ["Subscribed Users"],
+  "headings": { "en": "New Feature!" },
+  "contents": { "en": "Check out our latest update." },
+  "url": "https://example.com/feature"
+}
+```
+
+### Send notification to specific users
+
+```bash
+POST https://api.onesignal.com/api/v1/notifications
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+  Content-Type: application/json
+
+{
+  "app_id": "YOUR_APP_ID",
+  "include_aliases": { "external_id": ["user-123", "user-456"] },
+  "target_channel": "push",
+  "contents": { "en": "You have a new message." }
+}
+```
+
+### Schedule a notification
+
+```bash
+POST https://api.onesignal.com/api/v1/notifications
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+  Content-Type: application/json
+
+{
+  "app_id": "YOUR_APP_ID",
+  "included_segments": ["Subscribed Users"],
+  "contents": { "en": "Scheduled notification" },
+  "send_after": "2025-12-01 12:00:00 GMT-0500"
+}
+```
+
+### List notifications
+
+```bash
+GET https://api.onesignal.com/api/v1/notifications?app_id={APP_ID}&limit=50&offset=0
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+### View a notification
+
+```bash
+GET https://api.onesignal.com/api/v1/notifications/{notification_id}?app_id={APP_ID}
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+### Cancel a scheduled notification
+
+```bash
+DELETE https://api.onesignal.com/api/v1/notifications/{notification_id}?app_id={APP_ID}
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+### List segments
+
+```bash
+GET https://api.onesignal.com/api/v1/apps/{APP_ID}/segments
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+### Create a segment
+
+```bash
+POST https://api.onesignal.com/api/v1/apps/{APP_ID}/segments
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+  Content-Type: application/json
+
+{
+  "name": "Active Users",
+  "filters": [
+    { "field": "session_count", "relation": ">", "value": "5" }
+  ]
+}
+```
+
+### Get user by external ID
+
+```bash
+GET https://api.onesignal.com/api/v1/apps/{APP_ID}/users/by/external_id/{external_id}
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+### Create a user
+
+```bash
+POST https://api.onesignal.com/api/v1/apps/{APP_ID}/users
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+  Content-Type: application/json
+
+{
+  "identity": { "external_id": "user-789" },
+  "subscriptions": [
+    { "type": "Email", "token": "user@example.com" }
+  ],
+  "tags": { "plan": "pro", "signup_source": "organic" }
+}
+```
+
+### List templates
+
+```bash
+GET https://api.onesignal.com/api/v1/templates?app_id={APP_ID}
+
+Headers:
+  Authorization: Basic {REST_API_KEY}
+```
+
+## Key Metrics
+
+### Notification Metrics
+- `successful` - Number of successful deliveries
+- `failed` - Number of failed deliveries
+- `converted` - Users who clicked/converted
+- `remaining` - Notifications still queued
+- `errored` - Count of errors
+- `opened` - Notification open count
+
+### User Metrics
+- `session_count` - Total user sessions
+- `last_active` - Last activity timestamp
+- `tags` - Custom key-value metadata
+- `subscriptions` - Active subscription channels
+
+## Parameters
+
+### Notification Parameters
+- `app_id` - Application ID (required)
+- `included_segments` - Target segments array
+- `excluded_segments` - Excluded segments array
+- `include_aliases` - Target specific users by alias
+- `target_channel` - Channel: `push`, `email`, `sms`
+- `contents` - Message content by language code
+- `headings` - Notification title by language code
+- `url` - Launch URL on click
+- `data` - Custom key-value data payload
+- `send_after` - Scheduled send time (UTC string)
+- `ttl` - Time to live in seconds
+
+### Segment Filter Fields
+- `session_count` - Number of sessions
+- `first_session` - First session date
+- `last_session` - Last session date
+- `tag` - Custom tag value
+- `language` - User language
+- `app_version` - App version
+- `country` - User country code
+
+## When to Use
+
+- Sending push notifications for product updates
+- Triggered notifications based on user behavior
+- Multi-channel messaging (push + email + SMS)
+- Re-engagement campaigns for inactive users
+- Segmenting users for targeted messaging
+- A/B testing notification content
+- Scheduling promotional campaigns
+
+## Rate Limits
+
+- **Free Plan**: 150 notification requests/second per app
+- **Paid Plan**: 6,000 notification requests/second per app
+- **User/Subscription ops**: 1,000 requests/second per app
+- **Burst limit**: No more than 10x total subscribers in 15 minutes
+- **429 response**: Includes `RetryAfter` header with seconds to wait
+
+## Relevant Skills
+
+- push-notifications
+- customer-engagement
+- retention-campaign
+- re-engagement
+- lifecycle-marketing