arkaos 4.26.0 → 4.28.0

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

@@ -0,0 +1,148 @@
+# Stripe
+
+Payment processing, subscriptions, and billing for internet businesses.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Comprehensive REST API |
+| MCP | ✓ | Available via Stripe MCP server |
+| CLI | ✓ | `stripe` CLI for testing and webhooks |
+| SDK | ✓ | Official SDKs for most languages |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `Authorization: Bearer sk_live_xxx` or `sk_test_xxx`
+- **Keys**: Secret key (server), Publishable key (client)
+
+## Common Agent Operations
+
+### List customers
+
+```bash
+GET https://api.stripe.com/v1/customers?limit=10
+```
+
+### Get customer by email
+
+```bash
+GET https://api.stripe.com/v1/customers?email=user@example.com
+```
+
+### Get subscription
+
+```bash
+GET https://api.stripe.com/v1/subscriptions/{subscription_id}
+```
+
+### List subscriptions for customer
+
+```bash
+GET https://api.stripe.com/v1/subscriptions?customer={customer_id}
+```
+
+### Create checkout session
+
+```bash
+POST https://api.stripe.com/v1/checkout/sessions
+
+customer={customer_id}
+&line_items[0][price]={price_id}
+&line_items[0][quantity]=1
+&mode=subscription
+&success_url=https://example.com/success
+&cancel_url=https://example.com/cancel
+```
+
+### Create customer portal session
+
+```bash
+POST https://api.stripe.com/v1/billing_portal/sessions
+
+customer={customer_id}
+&return_url=https://example.com/account
+```
+
+### List recent invoices
+
+```bash
+GET https://api.stripe.com/v1/invoices?customer={customer_id}&limit=10
+```
+
+### Get payment intent
+
+```bash
+GET https://api.stripe.com/v1/payment_intents/{payment_intent_id}
+```
+
+## Webhook Events
+
+Key events to handle:
+
+| Event | When | Action |
+|-------|------|--------|
+| `checkout.session.completed` | Successful checkout | Provision access |
+| `customer.subscription.created` | New subscription | Update user record |
+| `customer.subscription.updated` | Plan change | Update entitlements |
+| `customer.subscription.deleted` | Cancellation | Revoke access |
+| `invoice.payment_failed` | Payment failed | Notify user, retry |
+| `invoice.paid` | Invoice paid | Confirm payment |
+
+### Verify webhook signature
+
+```javascript
+const event = stripe.webhooks.constructEvent(
+  payload,
+  sig,
+  webhookSecret
+);
+```
+
+## CLI Commands
+
+```bash
+# Listen to webhooks locally
+stripe listen --forward-to localhost:3000/webhooks
+
+# Trigger test events
+stripe trigger checkout.session.completed
+
+# List recent events
+stripe events list --limit 10
+
+# Get resource
+stripe customers retrieve cus_xxx
+```
+
+## Key Objects
+
+- **Customer** - User billing profile
+- **Subscription** - Recurring billing
+- **Price** - Pricing configuration
+- **Product** - What you sell
+- **Invoice** - Billing document
+- **PaymentIntent** - One-time payment
+- **Checkout Session** - Hosted payment page
+
+## When to Use
+
+- Processing payments
+- Managing subscriptions
+- Creating checkout flows
+- Handling billing portal
+- Querying customer data
+- Revenue analytics
+
+## Rate Limits
+
+- 100 read requests per second
+- 100 write requests per second
+- Higher limits available on request
+
+## Relevant Skills
+
+- pricing
+- referrals (Stripe-integrated affiliate tools)
+- analytics (revenue tracking)

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

@@ -0,0 +1,145 @@
+# Supermetrics
+
+Marketing data pipeline that connects 200+ marketing platforms. Pulls data from ad platforms, analytics, social, SEO, email, and more into a single query interface.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Query any connected data source, manage accounts |
+| MCP | ✓ | [Claude connector](https://claude.com/connectors/supermetrics) |
+| CLI | ✓ | [supermetrics.js](../clis/supermetrics.js) |
+| SDK | - | REST API only |
+
+## Authentication
+
+- **Type**: API Key
+- **Query param**: `api_key={api_key}` or **Header**: `x-api-key: {api_key}`
+- **Get key**: Supermetrics Hub > API settings at https://hub.supermetrics.com
+
+## Common Agent Operations
+
+### Query a Data Source
+
+```bash
+POST https://api.supermetrics.com/enterprise/v2/query/data/json
+
+{
+  "ds_id": "GA4",
+  "ds_accounts": "123456789",
+  "date_range_type": "last_28_days",
+  "fields": [
+    { "name": "sessions" },
+    { "name": "pageviews" },
+    { "name": "date" }
+  ]
+}
+```
+
+### Query with Filters
+
+```bash
+POST https://api.supermetrics.com/enterprise/v2/query/data/json
+
+{
+  "ds_id": "AW",
+  "ds_accounts": "123-456-7890",
+  "date_range_type": "last_month",
+  "fields": [
+    { "name": "campaign_name" },
+    { "name": "clicks" },
+    { "name": "impressions" },
+    { "name": "cost" }
+  ],
+  "max_rows": 100
+}
+```
+
+### List Available Data Sources
+
+```bash
+GET https://api.supermetrics.com/enterprise/v2/datasources
+```
+
+### List Connected Accounts
+
+```bash
+GET https://api.supermetrics.com/enterprise/v2/datasources/accounts?ds_id=GA4
+```
+
+### List Teams
+
+```bash
+GET https://api.supermetrics.com/enterprise/v2/teams
+```
+
+### List Users
+
+```bash
+GET https://api.supermetrics.com/enterprise/v2/users
+```
+
+## Key Metrics
+
+### Data Source IDs
+- `GA4` - Google Analytics 4
+- `GA4_PAID` - Google Analytics (paid)
+- `AW` - Google Ads
+- `FB` - Facebook Ads
+- `LI` - LinkedIn Ads
+- `TW_ADS` - Twitter Ads
+- `IG_IA` - Instagram
+- `FB_IA` - Facebook Pages
+- `GSC` - Google Search Console
+- `SE` - Semrush
+- `MC` - Mailchimp
+- `HubSpot` - HubSpot
+
+### Date Range Values
+- `last_28_days` - Last 28 days
+- `last_month` - Previous calendar month
+- `this_month` - Current month to date
+- `custom` - Custom range (requires `start_date` and `end_date`)
+
+## Parameters
+
+### Query
+- `ds_id` - Data source identifier (required)
+- `ds_accounts` - Account ID for the data source (required)
+- `date_range_type` - Date range preset or "custom" (required)
+- `fields` - Array of field objects with `name` property (required)
+- `filter` - Filter expression for narrowing results
+- `max_rows` - Maximum number of rows to return
+- `start_date` - Start date for custom range (YYYY-MM-DD)
+- `end_date` - End date for custom range (YYYY-MM-DD)
+
+### Common Fields by Source
+- **GA4**: `sessions`, `pageviews`, `users`, `bounce_rate`, `date`, `source`, `medium`, `page_path`
+- **Google Ads**: `campaign_name`, `clicks`, `impressions`, `cost`, `conversions`, `ctr`, `cpc`
+- **Facebook Ads**: `campaign_name`, `impressions`, `clicks`, `spend`, `reach`, `cpm`, `cpc`
+- **LinkedIn Ads**: `campaign_name`, `impressions`, `clicks`, `cost`, `conversions`
+- **GSC**: `query`, `clicks`, `impressions`, `ctr`, `position`, `page`
+
+## When to Use
+
+- Pulling cross-platform marketing data into a single report
+- Comparing performance across ad platforms (Google, Meta, LinkedIn, TikTok)
+- Aggregating analytics data from multiple sources
+- Automating marketing reporting workflows
+- Building unified dashboards across marketing channels
+- Extracting SEO data alongside paid media metrics
+
+## Rate Limits
+
+- Rate limits vary by plan
+- Enterprise API: typically 100 requests/minute
+- Query results may be paginated for large datasets
+- Recommended: use `max_rows` to control response size
+
+## Relevant Skills
+
+- analytics
+- ads
+- seo-audit
+- content-strategy
+- social

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

@@ -0,0 +1,161 @@
+# TikTok Ads
+
+Advertising platform for TikTok's short-form video audience.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Marketing API for campaigns, audiences, reporting |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | ✓ | Python SDK available |
+
+## Authentication
+
+- **Type**: Access Token
+- **Header**: `Access-Token: {access_token}`
+- **Setup**: Create app in TikTok for Business, get access token
+
+## Common Agent Operations
+
+### Get advertiser info
+
+```bash
+GET https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_ids=["{advertiser_id}"]
+
+Access-Token: {access_token}
+```
+
+### Get campaigns
+
+```bash
+GET https://business-api.tiktok.com/open_api/v1.3/campaign/get/?advertiser_id={advertiser_id}&page=1&page_size=20
+
+Access-Token: {access_token}
+```
+
+### Get campaign report
+
+```bash
+POST https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/
+
+Access-Token: {access_token}
+
+{
+  "advertiser_id": "{advertiser_id}",
+  "report_type": "BASIC",
+  "dimensions": ["campaign_id"],
+  "metrics": ["spend", "impressions", "clicks", "conversion"],
+  "data_level": "AUCTION_CAMPAIGN",
+  "start_date": "2024-01-01",
+  "end_date": "2024-01-31"
+}
+```
+
+### Create campaign
+
+```bash
+POST https://business-api.tiktok.com/open_api/v1.3/campaign/create/
+
+Access-Token: {access_token}
+
+{
+  "advertiser_id": "{advertiser_id}",
+  "campaign_name": "Campaign Name",
+  "objective_type": "CONVERSIONS",
+  "budget_mode": "BUDGET_MODE_DAY",
+  "budget": 100
+}
+```
+
+### Update campaign status
+
+```bash
+POST https://business-api.tiktok.com/open_api/v1.3/campaign/status/update/
+
+Access-Token: {access_token}
+
+{
+  "advertiser_id": "{advertiser_id}",
+  "campaign_ids": ["{campaign_id}"],
+  "opt_status": "ENABLE"
+}
+```
+
+### Get ad groups
+
+```bash
+GET https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={advertiser_id}&campaign_ids=["{campaign_id}"]
+
+Access-Token: {access_token}
+```
+
+### Get audiences
+
+```bash
+GET https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/?advertiser_id={advertiser_id}
+
+Access-Token: {access_token}
+```
+
+## Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `spend` | Amount spent |
+| `impressions` | Ad impressions |
+| `clicks` | Clicks |
+| `ctr` | Click-through rate |
+| `cpc` | Cost per click |
+| `cpm` | Cost per 1000 impressions |
+| `conversion` | Conversions |
+| `cost_per_conversion` | CPA |
+| `video_play_actions` | Video views |
+| `video_watched_6s` | 6s views |
+
+## Campaign Objectives
+
+- `REACH` - Brand awareness
+- `TRAFFIC` - Website traffic
+- `VIDEO_VIEWS` - Video views
+- `LEAD_GENERATION` - Lead forms
+- `CONVERSIONS` - Website conversions
+- `APP_PROMOTION` - App installs
+
+## Targeting Options
+
+### Demographics
+- Age ranges
+- Gender
+- Languages
+- Locations
+
+### Interests & Behavior
+- Interest categories
+- Video interactions
+- Creator interactions
+- Hashtag interactions
+
+### Custom Audiences
+- Customer file uploads
+- Website visitors (pixel)
+- App activity
+- Engagement audiences
+
+## When to Use
+
+- Reaching younger demographics (18-34)
+- Video-first advertising
+- Viral/creative campaigns
+- App promotion
+
+## Rate Limits
+
+- 10 requests/second
+- 100,000 requests/day
+
+## Relevant Skills
+
+- ads
+- analytics

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

@@ -0,0 +1,144 @@
+# Tolt
+
+Affiliate program management for SaaS, with Stripe and Paddle integration.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API for affiliates, referrals, payouts |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | - | JavaScript snippet for tracking |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `Authorization: Bearer {api_key}`
+- **Get key**: Settings > API in Tolt dashboard
+
+## Common Agent Operations
+
+### List affiliates
+
+```bash
+GET https://api.tolt.io/v1/affiliates
+```
+
+### Get affiliate
+
+```bash
+GET https://api.tolt.io/v1/affiliates/{affiliate_id}
+```
+
+### Create affiliate
+
+```bash
+POST https://api.tolt.io/v1/affiliates
+
+{
+  "email": "affiliate@example.com",
+  "name": "John Doe"
+}
+```
+
+### List referrals
+
+```bash
+GET https://api.tolt.io/v1/referrals?affiliate_id={affiliate_id}
+```
+
+### Get referral by customer
+
+```bash
+GET https://api.tolt.io/v1/referrals?customer_id={stripe_customer_id}
+```
+
+### List commissions
+
+```bash
+GET https://api.tolt.io/v1/commissions?affiliate_id={affiliate_id}
+```
+
+### Get payout history
+
+```bash
+GET https://api.tolt.io/v1/payouts?affiliate_id={affiliate_id}
+```
+
+### Update affiliate
+
+```bash
+PATCH https://api.tolt.io/v1/affiliates/{affiliate_id}
+
+{
+  "commission_rate": 30,
+  "payout_method": "paypal",
+  "paypal_email": "affiliate@paypal.com"
+}
+```
+
+## JavaScript Tracking
+
+### Install snippet
+
+```html
+<script src="https://cdn.tolt.io/tolt.js" data-tolt="YOUR_PUBLIC_KEY"></script>
+```
+
+### Track signup
+
+```javascript
+window.tolt.signup(stripeCustomerId);
+```
+
+### Identify existing customer
+
+```javascript
+window.tolt.identify(stripeCustomerId);
+```
+
+## Webhook Events
+
+| Event | When |
+|-------|------|
+| `affiliate.created` | New affiliate registered |
+| `affiliate.approved` | Affiliate approved |
+| `referral.created` | New referral tracked |
+| `referral.converted` | Referral converted to customer |
+| `commission.created` | Commission earned |
+| `payout.completed` | Payout sent |
+
+## Key Features
+
+- **Stripe native** - Automatic commission tracking
+- **Paddle support** - Works with Paddle billing
+- **Affiliate dashboard** - White-labeled portal
+- **Payout automation** - PayPal and Wise payouts
+- **Custom commission tiers** - Different rates per affiliate
+
+## Key Objects
+
+- **Affiliate** - Partner in your program
+- **Referral** - Tracked conversion
+- **Commission** - Earned affiliate payment
+- **Payout** - Processed payment to affiliate
+- **Program** - Campaign configuration
+
+## When to Use
+
+- Setting up SaaS affiliate programs
+- Managing affiliate relationships
+- Tracking Stripe or Paddle-based referrals
+- Processing affiliate payouts
+- Building affiliate dashboards
+
+## Rate Limits
+
+- 100 requests per minute
+- Higher limits on enterprise plans
+
+## Relevant Skills
+
+- referrals
+- pricing