claude-flow-novice 2.10.5 → 2.10.7

package/claude-assets/skills/cfn-marketing-ad-campaigns/SKILL.md

@@ -0,0 +1,392 @@
+# CFN Marketing Ad Campaigns Skill
+
+**Version:** 1.0.0
+**Status:** Production
+**Platform Support:** Google Ads, Meta Ads, LinkedIn Ads
+
+## Purpose
+
+Multi-platform paid advertising campaign management skill. Enables creation, budget control, bid strategy optimization, and performance monitoring for digital advertising campaigns across major platforms.
+
+## Core Operations
+
+### 1. Create Campaign
+Create new advertising campaign with budget constraints and targeting parameters.
+
+**Script:** `operations/create-campaign.sh`
+
+**Parameters:**
+- `--platform` (required): google_ads | meta_ads | linkedin_ads
+- `--campaign-name` (required): Campaign display name
+- `--daily-budget` (required): Daily spend limit (USD)
+- `--lifetime-budget` (required): Total campaign budget (USD)
+- `--target-audience` (required): JSON audience definition
+- `--start-date` (optional): YYYY-MM-DD format (default: immediate)
+- `--end-date` (optional): YYYY-MM-DD format (default: ongoing)
+- `--bid-strategy` (optional): Bidding strategy (default: enhanced_cpc)
+
+**Budget Validation:**
+- Daily budget: $1 - $500 maximum
+- Lifetime budget: $10 - $5,000 maximum
+- Exit code 3 on budget violation
+
+**Example:**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/create-campaign.sh \
+  --platform google_ads \
+  --campaign-name "Q4 Product Launch" \
+  --daily-budget 150 \
+  --lifetime-budget 3000 \
+  --target-audience '{"age":"25-44","interests":["technology","business"],"locations":["US","CA"]}' \
+  --bid-strategy maximize_conversions
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "status": "active",
+  "daily_budget": 150,
+  "lifetime_budget": 3000,
+  "budget_remaining": 3000,
+  "start_date": "2025-10-29",
+  "platform": "google_ads"
+}
+```
+
+---
+
+### 2. Set Budget
+Update campaign budget allocation with validation.
+
+**Script:** `operations/set-budget.sh`
+
+**Parameters:**
+- `--campaign-id` (required): Campaign identifier
+- `--daily-budget` (optional): New daily budget (USD)
+- `--lifetime-budget` (optional): New lifetime budget (USD)
+- At least one budget parameter required
+
+**Budget Validation:**
+- Daily budget: $1 - $500 maximum
+- Lifetime budget: $10 - $5,000 maximum
+- Cannot decrease lifetime budget below current spend
+- Exit code 3 on budget violation
+
+**Example:**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/set-budget.sh \
+  --campaign-id cmp_a1b2c3d4 \
+  --daily-budget 200 \
+  --lifetime-budget 4000
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "daily_budget": {
+    "previous": 150,
+    "updated": 200
+  },
+  "lifetime_budget": {
+    "previous": 3000,
+    "updated": 4000
+  },
+  "budget_remaining": 3850
+}
+```
+
+---
+
+### 3. Update Bid Strategy
+Modify campaign bidding strategy for optimization.
+
+**Script:** `operations/update-bid-strategy.sh`
+
+**Parameters:**
+- `--campaign-id` (required): Campaign identifier
+- `--bid-strategy` (required): Strategy type
+
+**Supported Strategies:**
+- `manual_cpc`: Manual cost-per-click bidding
+- `enhanced_cpc`: Automated CPC with conversion optimization
+- `maximize_conversions`: Automated bidding to maximize conversions
+- `target_cpa`: Target cost per acquisition
+- `target_roas`: Target return on ad spend
+
+**Example:**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/update-bid-strategy.sh \
+  --campaign-id cmp_a1b2c3d4 \
+  --bid-strategy target_cpa
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "bid_strategy": {
+    "previous": "enhanced_cpc",
+    "updated": "target_cpa"
+  },
+  "estimated_impact": {
+    "cpa_change": "-15%",
+    "conversion_volume": "+8%"
+  },
+  "status": "active"
+}
+```
+
+---
+
+### 4. Pause/Resume Campaign
+Control campaign active status.
+
+**Script:** `operations/pause-campaign.sh`
+
+**Parameters:**
+- `--campaign-id` (required): Campaign identifier
+- `--action` (required): pause | resume
+
+**Example (Pause):**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/pause-campaign.sh \
+  --campaign-id cmp_a1b2c3d4 \
+  --action pause
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "status": "paused",
+  "paused_at": "2025-10-29T14:30:00Z",
+  "budget_remaining": 2850
+}
+```
+
+**Example (Resume):**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/pause-campaign.sh \
+  --campaign-id cmp_a1b2c3d4 \
+  --action resume
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "status": "active",
+  "resumed_at": "2025-10-29T15:45:00Z",
+  "budget_remaining": 2850
+}
+```
+
+---
+
+### 5. Get Campaign Performance
+Fetch performance metrics and analytics.
+
+**Script:** `operations/get-campaign-performance.sh`
+
+**Parameters:**
+- `--campaign-id` (required): Campaign identifier
+- `--date-range` (optional): last_7_days | last_30_days | custom (default: last_7_days)
+- `--start-date` (optional): YYYY-MM-DD (required if date-range=custom)
+- `--end-date` (optional): YYYY-MM-DD (required if date-range=custom)
+- `--metrics` (optional): Comma-separated metric list (default: all)
+
+**Available Metrics:**
+- impressions: Ad view count
+- clicks: Click count
+- conversions: Conversion count
+- spend: Total spend (USD)
+- ctr: Click-through rate (%)
+- cpa: Cost per acquisition (USD)
+- roas: Return on ad spend (ratio)
+
+**Example:**
+```bash
+./.claude/skills/cfn-marketing-ad-campaigns/operations/get-campaign-performance.sh \
+  --campaign-id cmp_a1b2c3d4 \
+  --date-range last_30_days \
+  --metrics impressions,clicks,conversions,spend,cpa,roas
+```
+
+**Response:**
+```json
+{
+  "campaign_id": "cmp_a1b2c3d4",
+  "date_range": {
+    "start": "2025-09-29",
+    "end": "2025-10-29"
+  },
+  "metrics": {
+    "impressions": 45230,
+    "clicks": 1876,
+    "conversions": 142,
+    "spend": 1150.00,
+    "ctr": 4.15,
+    "cpa": 8.10,
+    "roas": 3.85
+  },
+  "budget": {
+    "total": 4000,
+    "spent": 1150,
+    "remaining": 2850
+  },
+  "status": "active"
+}
+```
+
+---
+
+## Technical Implementation
+
+### Environment Variables
+```bash
+N8N_BASE_URL="https://your-n8n-instance.com"
+N8N_API_KEY="your-api-key"
+```
+
+### Budget Validation (Enforced)
+All budget operations validate against limits:
+
+```bash
+DAILY_MAX=500
+LIFETIME_MAX=5000
+
+if (( $(echo "$DAILY_BUDGET > $DAILY_MAX" | bc -l) )); then
+  echo '{"error": "Daily budget exceeds maximum ($500)", "code": "BUDGET_EXCEEDED"}' >&2
+  exit 3
+fi
+```
+
+### Exit Codes
+- `0`: Success
+- `1`: Validation error (invalid parameters)
+- `2`: API error (network/platform failure)
+- `3`: Budget violation
+
+### Error Response Format
+```json
+{
+  "error": "Error description",
+  "code": "ERROR_CODE",
+  "details": {
+    "field": "field_name",
+    "constraint": "constraint_description"
+  }
+}
+```
+
+---
+
+## Integration Example
+
+```bash
+#!/bin/bash
+# Create campaign and monitor performance
+
+CAMPAIGN_ID=$(
+  ./.claude/skills/cfn-marketing-ad-campaigns/operations/create-campaign.sh \
+    --platform google_ads \
+    --campaign-name "Black Friday Sale" \
+    --daily-budget 250 \
+    --lifetime-budget 5000 \
+    --target-audience '{"age":"25-54","interests":["shopping","deals"]}' \
+    --bid-strategy maximize_conversions | jq -r '.campaign_id'
+)
+
+echo "Campaign created: $CAMPAIGN_ID"
+
+# Wait 7 days
+sleep 604800
+
+# Check performance
+./.claude/skills/cfn-marketing-ad-campaigns/operations/get-campaign-performance.sh \
+  --campaign-id "$CAMPAIGN_ID" \
+  --date-range last_7_days
+
+# Adjust budget if performing well
+ROAS=$(get-campaign-performance.sh --campaign-id "$CAMPAIGN_ID" | jq -r '.metrics.roas')
+
+if (( $(echo "$ROAS > 4.0" | bc -l) )); then
+  echo "Strong performance, increasing budget"
+  ./.claude/skills/cfn-marketing-ad-campaigns/operations/set-budget.sh \
+    --campaign-id "$CAMPAIGN_ID" \
+    --daily-budget 350
+fi
+```
+
+---
+
+## Testing
+
+### Mock Data Setup
+```bash
+# Set test environment
+export N8N_BASE_URL="http://localhost:5678"
+export N8N_API_KEY="test-key-12345"
+
+# Test campaign creation
+./.claude/skills/cfn-marketing-ad-campaigns/operations/create-campaign.sh \
+  --platform google_ads \
+  --campaign-name "Test Campaign" \
+  --daily-budget 50 \
+  --lifetime-budget 500 \
+  --target-audience '{"test":true}'
+```
+
+### Budget Validation Tests
+```bash
+# Test daily budget violation
+./.claude/skills/cfn-marketing-ad-campaigns/operations/create-campaign.sh \
+  --platform google_ads \
+  --campaign-name "Over Budget Test" \
+  --daily-budget 600 \
+  --lifetime-budget 1000 \
+  --target-audience '{}'
+# Expected: Exit code 3, error message
+
+# Test lifetime budget violation
+./.claude/skills/cfn-marketing-ad-campaigns/operations/set-budget.sh \
+  --campaign-id test_campaign \
+  --lifetime-budget 6000
+# Expected: Exit code 3, error message
+```
+
+---
+
+## Security Considerations
+
+1. **API Key Protection**: Never log N8N_API_KEY
+2. **Input Validation**: All parameters sanitized before API calls
+3. **Budget Limits**: Hard-coded maximum limits prevent overspending
+4. **Rate Limiting**: Respect platform API rate limits
+5. **Audit Logging**: All budget changes logged to stderr
+
+---
+
+## Maintenance
+
+**Dependencies:**
+- bash 4.0+
+- jq 1.6+
+- curl 7.0+
+- bc (for budget calculations)
+
+**Update Frequency:** Monthly platform API compatibility checks
+
+**Support Contact:** cfn-marketing-team@example.com
+
+---
+
+## Changelog
+
+**v1.0.0** (2025-10-29)
+- Initial release
+- 5 core operations
+- Budget validation enforcement
+- Multi-platform support (Google Ads, Meta Ads, LinkedIn Ads)

package/claude-assets/skills/cfn-marketing-ad-campaigns/operations/create-campaign.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+# CFN Marketing Ad Campaigns - Create Campaign Operation
+# Creates new advertising campaign with budget validation
+
+set -euo pipefail
+
+# Budget limits (hard-coded)
+DAILY_MIN=1
+DAILY_MAX=500
+LIFETIME_MIN=10
+LIFETIME_MAX=5000
+
+# Default values
+BID_STRATEGY="enhanced_cpc"
+START_DATE=$(date +%Y-%m-%d)
+END_DATE=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --platform)
+      PLATFORM="$2"
+      shift 2
+      ;;
+    --campaign-name)
+      CAMPAIGN_NAME="$2"
+      shift 2
+      ;;
+    --daily-budget)
+      DAILY_BUDGET="$2"
+      shift 2
+      ;;
+    --lifetime-budget)
+      LIFETIME_BUDGET="$2"
+      shift 2
+      ;;
+    --target-audience)
+      TARGET_AUDIENCE="$2"
+      shift 2
+      ;;
+    --start-date)
+      START_DATE="$2"
+      shift 2
+      ;;
+    --end-date)
+      END_DATE="$2"
+      shift 2
+      ;;
+    --bid-strategy)
+      BID_STRATEGY="$2"
+      shift 2
+      ;;
+    *)
+      echo '{"error": "Unknown parameter: '"$1"'", "code": "INVALID_PARAMETER"}' >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required parameters
+if [[ -z "${PLATFORM:-}" ]]; then
+  echo '{"error": "Missing required parameter: --platform", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+if [[ -z "${CAMPAIGN_NAME:-}" ]]; then
+  echo '{"error": "Missing required parameter: --campaign-name", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+if [[ -z "${DAILY_BUDGET:-}" ]]; then
+  echo '{"error": "Missing required parameter: --daily-budget", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+if [[ -z "${LIFETIME_BUDGET:-}" ]]; then
+  echo '{"error": "Missing required parameter: --lifetime-budget", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+if [[ -z "${TARGET_AUDIENCE:-}" ]]; then
+  echo '{"error": "Missing required parameter: --target-audience", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+# Validate platform
+case "$PLATFORM" in
+  google_ads|meta_ads|linkedin_ads)
+    ;;
+  *)
+    echo '{"error": "Invalid platform: '"$PLATFORM"'. Supported: google_ads, meta_ads, linkedin_ads", "code": "INVALID_PLATFORM"}' >&2
+    exit 1
+    ;;
+esac
+
+# Validate budget - daily
+if (( $(echo "$DAILY_BUDGET < $DAILY_MIN" | bc -l) )); then
+  echo '{"error": "Daily budget below minimum ($'"$DAILY_MIN"')", "code": "BUDGET_TOO_LOW", "details": {"field": "daily_budget", "min": '"$DAILY_MIN"', "provided": '"$DAILY_BUDGET"'}}' >&2
+  exit 3
+fi
+
+if (( $(echo "$DAILY_BUDGET > $DAILY_MAX" | bc -l) )); then
+  echo '{"error": "Daily budget exceeds maximum ($'"$DAILY_MAX"')", "code": "BUDGET_EXCEEDED", "details": {"field": "daily_budget", "max": '"$DAILY_MAX"', "provided": '"$DAILY_BUDGET"'}}' >&2
+  exit 3
+fi
+
+# Validate budget - lifetime
+if (( $(echo "$LIFETIME_BUDGET < $LIFETIME_MIN" | bc -l) )); then
+  echo '{"error": "Lifetime budget below minimum ($'"$LIFETIME_MIN"')", "code": "BUDGET_TOO_LOW", "details": {"field": "lifetime_budget", "min": '"$LIFETIME_MIN"', "provided": '"$LIFETIME_BUDGET"'}}' >&2
+  exit 3
+fi
+
+if (( $(echo "$LIFETIME_BUDGET > $LIFETIME_MAX" | bc -l) )); then
+  echo '{"error": "Lifetime budget exceeds maximum ($'"$LIFETIME_MAX"')", "code": "BUDGET_EXCEEDED", "details": {"field": "lifetime_budget", "max": '"$LIFETIME_MAX"', "provided": '"$LIFETIME_BUDGET"'}}' >&2
+  exit 3
+fi
+
+# Validate lifetime >= daily
+if (( $(echo "$LIFETIME_BUDGET < $DAILY_BUDGET" | bc -l) )); then
+  echo '{"error": "Lifetime budget must be >= daily budget", "code": "BUDGET_CONSTRAINT_VIOLATION", "details": {"lifetime": '"$LIFETIME_BUDGET"', "daily": '"$DAILY_BUDGET"'}}' >&2
+  exit 1
+fi
+
+# Validate target audience JSON
+if ! echo "$TARGET_AUDIENCE" | jq empty 2>/dev/null; then
+  echo '{"error": "Invalid JSON in --target-audience", "code": "INVALID_JSON"}' >&2
+  exit 1
+fi
+
+# Validate bid strategy
+case "$BID_STRATEGY" in
+  manual_cpc|enhanced_cpc|maximize_conversions|target_cpa|target_roas)
+    ;;
+  *)
+    echo '{"error": "Invalid bid strategy: '"$BID_STRATEGY"'", "code": "INVALID_BID_STRATEGY"}' >&2
+    exit 1
+    ;;
+esac
+
+# Validate environment variables
+if [[ -z "${N8N_BASE_URL:-}" ]]; then
+  echo '{"error": "N8N_BASE_URL environment variable not set", "code": "MISSING_ENV_VAR"}' >&2
+  exit 2
+fi
+
+if [[ -z "${N8N_API_KEY:-}" ]]; then
+  echo '{"error": "N8N_API_KEY environment variable not set", "code": "MISSING_ENV_VAR"}' >&2
+  exit 2
+fi
+
+# Build request payload
+PAYLOAD=$(jq -n \
+  --arg platform "$PLATFORM" \
+  --arg name "$CAMPAIGN_NAME" \
+  --argjson daily "$DAILY_BUDGET" \
+  --argjson lifetime "$LIFETIME_BUDGET" \
+  --argjson audience "$TARGET_AUDIENCE" \
+  --arg start "$START_DATE" \
+  --arg end "$END_DATE" \
+  --arg strategy "$BID_STRATEGY" \
+  '{
+    platform: $platform,
+    campaign_name: $name,
+    daily_budget: $daily,
+    lifetime_budget: $lifetime,
+    target_audience: $audience,
+    start_date: $start,
+    end_date: (if $end == "" then null else $end end),
+    bid_strategy: $strategy
+  }'
+)
+
+# Make API request
+RESPONSE=$(curl -s -w "\n%{http_code}" \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -d "$PAYLOAD" \
+  "$N8N_BASE_URL/webhook/ad-campaigns/create" 2>/dev/null || echo -e "\n000")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+# Handle response
+case "$HTTP_CODE" in
+  200|201)
+    # Success - parse and format response
+    CAMPAIGN_ID=$(echo "$BODY" | jq -r '.campaign_id // "cmp_'$(date +%s)'"')
+
+    echo "$BODY" | jq \
+      --arg id "$CAMPAIGN_ID" \
+      --arg status "active" \
+      --argjson daily "$DAILY_BUDGET" \
+      --argjson lifetime "$LIFETIME_BUDGET" \
+      --argjson remaining "$LIFETIME_BUDGET" \
+      --arg start "$START_DATE" \
+      --arg platform "$PLATFORM" \
+      '{
+        campaign_id: (.campaign_id // $id),
+        status: (.status // $status),
+        daily_budget: (.daily_budget // $daily),
+        lifetime_budget: (.lifetime_budget // $lifetime),
+        budget_remaining: (.budget_remaining // $remaining),
+        start_date: (.start_date // $start),
+        end_date: (.end_date // null),
+        platform: (.platform // $platform),
+        bid_strategy: .bid_strategy
+      }'
+    exit 0
+    ;;
+  400)
+    echo '{"error": "Bad request - invalid campaign parameters", "code": "API_BAD_REQUEST", "details": '"${BODY:-null}"'}' >&2
+    exit 2
+    ;;
+  401)
+    echo '{"error": "Authentication failed - check N8N_API_KEY", "code": "API_AUTH_FAILED"}' >&2
+    exit 2
+    ;;
+  429)
+    echo '{"error": "Rate limit exceeded - try again later", "code": "API_RATE_LIMIT"}' >&2
+    exit 2
+    ;;
+  000)
+    echo '{"error": "Network error - unable to reach N8N instance", "code": "NETWORK_ERROR"}' >&2
+    exit 2
+    ;;
+  *)
+    echo '{"error": "Unexpected API response", "code": "API_ERROR", "http_code": '"$HTTP_CODE"', "details": '"${BODY:-null}"'}' >&2
+    exit 2
+    ;;
+esac