codymaster 7.0.2 → 7.0.3

package/skills/cm-ads-tracker/references/platforms-api.md

@@ -0,0 +1,238 @@
+# Platform Server-Side APIs Reference
+
+## Why Server-Side APIs Matter
+
+Browser-side pixels face increasing signal loss due to:
+- Ad blockers (15-40% of users block tracking scripts)
+- iOS 14+ and browser privacy restrictions (Safari ITP, Firefox ETP)
+- Cookie deprecation timeline
+
+Server-side APIs (CAPI, Events API) send events directly from your server to the platform — bypassing browser restrictions entirely. Combined with browser pixels and deduplication via event_id, this gives you the best possible signal quality.
+
+Typical uplift from adding server-side APIs:
+- Meta CAPI: +10-20% more matched conversions
+- TikTok Events API: +8-15% uplift
+- Google Enhanced Conversions: +15-25% conversion recovery
+
+---
+
+## 1. Meta Conversions API (CAPI)
+
+### Setup Methods (choose one)
+
+**Option A: Via Server-Side GTM (recommended for non-developers)**
+- Set up GTM Server-Side container (hosted on Google Cloud or Stape.io)
+- Route website events through server GTM → server GTM sends to Meta CAPI
+- No backend code changes needed
+
+**Option B: Direct API Integration (for developers)**
+- Endpoint: https://graph.facebook.com/v18.0/{pixel_id}/events
+- Authentication: System User Access Token from Meta Business Manager
+- Server sends HTTP POST for each conversion event
+
+### Required Fields for Every CAPI Event
+
+```
+{
+  "data": [{
+    "event_name": "Purchase",         // Standard Meta event name
+    "event_time": 1703123456,         // Unix timestamp (server time)
+    "event_id": "uuid-generated-at-conversion",  // CRITICAL for dedup
+    "action_source": "website",       // Required
+    "event_source_url": "https://yoursite.com/thank-you",
+    "user_data": {
+      "em": ["sha256_of_lowercase_email"],    // Hashed email
+      "ph": ["sha256_of_digitsonly_phone"],   // Hashed phone
+      "client_ip_address": "123.456.789.0",   // Server-detected IP
+      "client_user_agent": "Mozilla/5.0...",  // From request headers
+      "fbp": "_fb.1.1234567890.abcdefg",     // _fbp cookie value
+      "fbc": "fb.1.1234567890.AbCdEfGhIj"   // _fbc cookie value (from fbclid)
+    },
+    "custom_data": {
+      "value": 500000,
+      "currency": "VND",
+      "content_ids": ["PROD-123"],
+      "content_type": "product",
+      "contents": [{"id": "PROD-123", "quantity": 1, "item_price": 500000}],
+      "num_items": 1,
+      "order_id": "ORDER-20240101-001"
+    }
+  }],
+  "access_token": "EAAxxxxxxxxxxxx"
+}
+```
+
+### Deduplication Logic
+
+When your browser pixel AND CAPI both fire for the same conversion:
+- Both include identical `event_id` value
+- Meta's system receives both events within 48-hour window
+- Meta matches them by event_id and counts as ONE conversion
+- You see "Matched events" count in Events Manager
+
+The `event_id` MUST be:
+- Generated ONCE per conversion (not per request)
+- Identical in both browser dataLayer.push() and CAPI payload
+- Unique across all conversions (use UUID v4)
+
+### How to Get CAPI Access Token
+
+1. Go to Meta Business Manager → Events Manager
+2. Select your Pixel → Settings
+3. Scroll to "Conversions API"
+4. Click "Generate Access Token" (or use System User token from Business Settings)
+5. Copy token — treat it as a secret (never expose in browser-side code)
+
+### Testing CAPI Events
+
+Use Meta's Test Events tool in Events Manager → Test Events tab.
+Set test_event_code in payload during development:
+Add "test_event_code": "TEST12345" to the payload root (not inside data array).
+
+---
+
+## 2. TikTok Events API
+
+### Setup Methods
+
+**Option A: Via Server-Side GTM with TikTok template**
+- Use community TikTok Events API GTM server-side template
+- Route events through server GTM
+
+**Option B: Direct API Integration**
+- Endpoint: https://business-api.tiktok.com/open_api/v1.3/event/track/
+- Authentication: Access Token from TikTok Events Manager
+
+### Required Fields for Every Events API Event
+
+```
+{
+  "pixel_code": "CXXXXXXXXXX",
+  "event": "CompletePayment",           // TikTok standard event name
+  "event_id": "uuid-generated-at-conversion",  // For dedup with pixel
+  "timestamp": "2024-01-15T10:30:00+07:00",
+  "context": {
+    "page": {
+      "url": "https://yoursite.com/thank-you",
+      "referrer": "https://yoursite.com/checkout"
+    },
+    "user": {
+      "email": "sha256_of_lowercase_email",
+      "phone_number": "sha256_of_digits_only_phone"
+    },
+    "ip": "123.456.789.0",
+    "user_agent": "Mozilla/5.0..."
+  },
+  "properties": {
+    "value": 500000,
+    "currency": "VND",
+    "content_ids": ["PROD-123"],
+    "content_type": "product",
+    "contents": [
+      {
+        "content_id": "PROD-123",
+        "content_name": "Product Name",
+        "content_type": "product",
+        "quantity": 1,
+        "price": 500000
+      }
+    ]
+  }
+}
+```
+
+Authentication header: "Access-Token: [your access token]"
+Content-Type: application/json
+
+### Getting TikTok Events API Access Token
+
+1. TikTok Ads Manager → Assets → Events
+2. Select your Pixel → Set Up Web Events → Events API
+3. Generate Access Token
+4. Store securely server-side
+
+### TikTok Deduplication
+
+Works identically to Meta: same event_id sent from both pixel and Events API.
+TikTok matches within 48-hour window.
+
+---
+
+## 3. Google Enhanced Conversions
+
+### How It Works
+
+Unlike Meta CAPI and TikTok Events API (which are standalone APIs), Google Enhanced Conversions supplements your existing Google Ads conversion tag with hashed user data.
+
+The existing GTM Google Ads tag is enhanced with a user_data object containing:
+- email_address (raw — Google hashes it)
+- phone_number (raw — with country code prefix e.g. "+84912345678")
+- address.first_name, address.last_name, address.country, address.postal_code
+
+IMPORTANT: Google hashes the data itself (unlike Meta/TikTok where you pre-hash).
+Do NOT SHA256 hash for Enhanced Conversions — pass raw data.
+
+### Setup in GTM
+
+In your existing Google Ads Conversion Tracking tag:
+1. Scroll to "Enhanced conversions"
+2. Enable "Include user-provided data from your website"
+3. Under "User-provided data variable", create a new variable:
+   - Type: User-Provided Data
+   - Enter email variable: [DataLayer variable for email]
+   - Enter phone variable: [DataLayer variable for phone]
+
+The DataLayer push should include raw (unhashed) email and phone:
+email: "customer@email.com"
+phone: "+84912345678"
+
+Or if privacy is a concern: pre-hash with SHA256 and mark as "sha256_email_address" in the enhanced conversions config.
+
+### Google Tag API (Server-Side Enhanced Conversions)
+
+For server-side Enhanced Conversions via the Google Ads API:
+- Use the Google Ads API ConversionUploadService
+- Send click conversion with hashed user identifiers
+- Match window: same as your conversion window setting
+
+---
+
+## 4. Attribution Accuracy Benchmark
+
+After implementing pixel + server-side API for all platforms, expect:
+
+| Scenario | Pixel Only | Pixel + CAPI/Events API |
+|---|---|---|
+| iOS 14+ users | 30-50% signal loss | Full signal recovery |
+| Ad blocker users | 0% tracking | 80-90% recovery |
+| Overall conversion match rate | 60-70% | 85-95% |
+| ROAS accuracy | Understated by 20-40% | Near-accurate |
+
+### Validating Server-Side Setup
+
+**Meta:** Events Manager → Pixel → Overview → Check "Event match quality" score
+- Score 6-7: Good
+- Score 8+: Excellent
+- Below 5: Missing user_data fields (em, ph, fbp, fbc)
+
+**TikTok:** Ads Manager → Assets → Events → Pixel → Data Details
+- Check "Match rate" percentage
+- Target: 60%+ match rate
+
+**Google:** Google Ads → Conversions → View column "Enhanced conv." count
+- Compare with standard conversion count
+- Uplift of 15-25% is typical and expected
+
+---
+
+## 5. Priority Implementation Order
+
+If budget/time is limited, implement in this order:
+
+1. Browser pixels via GTM (Phase B) — covers 60-70% of users
+2. First-touch cookie + UTM tracking — attribution clarity
+3. Meta CAPI — highest ROI platform, biggest uplift from server-side
+4. Google Enhanced Conversions — easy to add, 15-25% uplift
+5. TikTok Events API — add once other platforms are stable
+
+Never implement CAPI without also keeping the browser pixel — you need both for deduplication to work. If you only have CAPI, you lose browser-generated signals like fbp cookie.

package/skills/cm-ads-tracker/templates/capi-payload.md

@@ -0,0 +1,79 @@
+# Facebook/Meta CAPI Server-Side Template
+
+## Required Payload Fields
+
+```json
+{
+  "data": [{
+    "event_name": "Purchase",
+    "event_time": 1700000000,
+    "event_id": "uuid-same-as-pixel-event-id",
+    "action_source": "website",
+    "event_source_url": "https://example.com/thank-you",
+    "user_data": {
+      "em": ["sha256_hashed_email"],
+      "ph": ["sha256_hashed_phone_digits_only"],
+      "client_ip_address": "1.2.3.4",
+      "client_user_agent": "Mozilla/5.0...",
+      "fbp": "_fbp cookie value",
+      "fbc": "fb.1.timestamp.fbclid_value"
+    },
+    "custom_data": {
+      "value": 299000,
+      "currency": "VND",
+      "order_id": "ORD-12345",
+      "content_ids": ["prod_001", "prod_002"],
+      "content_type": "product",
+      "num_items": 2
+    }
+  }]
+}
+```
+
+## API Endpoint
+
+```
+POST https://graph.facebook.com/v21.0/{PIXEL_ID}/events?access_token={CAPI_ACCESS_TOKEN}
+```
+
+## Deduplication
+
+Both browser Pixel and CAPI send the SAME `event_id`. Meta matches within 48h and counts once.
+
+## Enhanced Matching Priority (hash with SHA256)
+
+1. `em` — email (lowercase, trim whitespace)
+2. `ph` — phone (digits only, include country code)
+3. `fn` — first name (lowercase)
+4. `ln` — last name (lowercase)
+5. `fbp` — Facebook browser cookie
+6. `fbc` — Facebook click ID cookie
+
+## TikTok Events API Equivalent
+
+```
+POST https://business-api.tiktok.com/open_api/v1.3/event/track/
+Headers: Access-Token: {TIKTOK_ACCESS_TOKEN}
+```
+
+```json
+{
+  "pixel_code": "TIKTOK_PIXEL_ID",
+  "event": "CompletePayment",
+  "event_id": "same-uuid-as-pixel",
+  "timestamp": "2025-01-15T10:30:00+07:00",
+  "context": {
+    "user_agent": "Mozilla/5.0...",
+    "ip": "1.2.3.4"
+  },
+  "properties": {
+    "value": 299000,
+    "currency": "VND",
+    "content_id": "prod_001",
+    "content_type": "product",
+    "contents": [
+      {"content_id": "prod_001", "content_name": "Product A", "quantity": 1, "price": 299000}
+    ]
+  }
+}
+```

package/skills/cm-ads-tracker/templates/datalayer-push.js

@@ -0,0 +1,104 @@
+// DataLayer Push Templates — CM Ads Tracker v2
+// Copy and customize these for your project.
+// Developer writes ONE push per event. GTM does the rest.
+
+// ═══════════════════════════════════════════
+// PURCHASE (E-commerce, Courses, SaaS)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_purchase',
+  event_id: '[UUID generated server-side — same value sent to CAPI]',
+  transaction_id: '[order_id]',
+  value: 0, // numeric order total — NOT string
+  currency: 'VND', // ISO 4217 code
+  content_type: 'product',
+  content_ids: ['product_id_1', 'product_id_2'],
+  contents: [
+    { content_id: 'id', content_name: 'name', content_type: 'product', quantity: 1, price: 0 }
+  ],
+  num_items: 1,
+  email_hashed: '[SHA256(lowercase(email))]',
+  phone_hashed: '[SHA256(digits-only phone)]'
+});
+
+// ═══════════════════════════════════════════
+// LEAD / FORM SUBMIT  (Lead Gen, B2B, Education)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_lead',
+  event_id: '[UUID]',
+  lead_id: '[unique lead identifier]',
+  content_name: '[form_name or page_name]',
+  value: 0, // lead_value_if_known — optional
+  currency: 'VND',
+  email_hashed: '[SHA256(lowercase(email))]',
+  phone_hashed: '[SHA256(digits-only phone)]'
+});
+
+// ═══════════════════════════════════════════
+// VIEW CONTENT (Product/Service page)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_view_content',
+  event_id: '[UUID]',
+  content_ids: ['product_id'],
+  content_type: 'product',
+  content_name: '[Product Name]',
+  value: 0,
+  currency: 'VND'
+});
+
+// ═══════════════════════════════════════════
+// ADD TO CART
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_add_to_cart',
+  event_id: '[UUID]',
+  content_ids: ['product_id'],
+  content_type: 'product',
+  content_name: '[Product Name]',
+  value: 0,
+  currency: 'VND',
+  quantity: 1
+});
+
+// ═══════════════════════════════════════════
+// INITIATE CHECKOUT
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_initiate_checkout',
+  event_id: '[UUID]',
+  value: 0,
+  currency: 'VND',
+  num_items: 1,
+  content_ids: ['product_id_1']
+});
+
+// ═══════════════════════════════════════════
+// REGISTRATION / SIGNUP
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_registration',
+  event_id: '[UUID]',
+  status: 'complete',
+  email_hashed: '[SHA256]',
+  phone_hashed: '[SHA256]'
+});
+
+// ═══════════════════════════════════════════
+// PHONE CALL CLICK
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_phone_call',
+  event_id: '[UUID]',
+  phone_number: '[phone number clicked]'
+});
+
+// ═══════════════════════════════════════════
+// SEARCH
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_search',
+  event_id: '[UUID]',
+  search_string: '[user search query]'
+});

package/skills/cm-ads-tracker/templates/gtm-variables.js

@@ -0,0 +1,56 @@
+// GTM Variables — Full Configuration Reference
+// Create ALL of these in GTM > Variables > User-Defined Variables
+
+// ═══════ DataLayer Variables ═══════
+// Variable Name           | Type              | DataLayer Variable Name
+// DL - event_id           | Data Layer Variable | event_id
+// DL - order_id           | Data Layer Variable | transaction_id
+// DL - order_value        | Data Layer Variable | value
+// DL - currency           | Data Layer Variable | currency
+// DL - content_ids        | Data Layer Variable | content_ids
+// DL - content_type       | Data Layer Variable | content_type
+// DL - content_name       | Data Layer Variable | content_name
+// DL - email_hashed       | Data Layer Variable | email_hashed
+// DL - phone_hashed       | Data Layer Variable | phone_hashed
+
+// ═══════ First-Touch Cookie Variables ═══════
+// Variable Name           | Type              | Cookie / Key
+// FTC - source            | 1st-Party Cookie  | Cookie: _ftc, key: src
+// FTC - medium            | 1st-Party Cookie  | Cookie: _ftc, key: med
+// FTC - campaign          | 1st-Party Cookie  | Cookie: _ftc, key: cmp
+
+// ═══════ URL Parameters ═══════
+// Variable Name           | Type              | Query Parameter
+// URL - utm_source        | URL               | utm_source
+// URL - utm_medium        | URL               | utm_medium
+// URL - utm_campaign      | URL               | utm_campaign
+// URL - fbclid            | URL               | fbclid
+// URL - ttclid            | URL               | ttclid
+// URL - gclid             | URL               | gclid
+
+// ═══════ First-Touch Cookie Capture (Custom HTML Tag) ═══════
+// Trigger: All Pages
+// Fire once: Only if _ftc cookie does NOT exist
+<script>
+(function(){
+  if (document.cookie.indexOf('_ftc=') !== -1) return;
+  var params = new URLSearchParams(window.location.search);
+  var ftc = {
+    src: params.get('utm_source') || '',
+    med: params.get('utm_medium') || '',
+    cmp: params.get('utm_campaign') || '',
+    cnt: params.get('utm_content') || '',
+    trm: params.get('utm_term') || '',
+    fbclid: params.get('fbclid') || '',
+    ttclid: params.get('ttclid') || '',
+    gclid: params.get('gclid') || '',
+    ref: document.referrer ? new URL(document.referrer).hostname : '',
+    ts: new Date().toISOString()
+  };
+  var expiry = new Date();
+  expiry.setDate(expiry.getDate() + 90);
+  document.cookie = '_ftc=' + encodeURIComponent(JSON.stringify(ftc))
+    + ';expires=' + expiry.toUTCString()
+    + ';path=/;SameSite=Lax';
+})();
+</script>

package/skills/cm-auto-publisher/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cm-auto-publisher
+description: Comprehensive publishing automation skill bridging AI agents (OpenClaw, Manus, Claude) to the Content Factory Router. Uses the Router API to publish markdown articles with rich media to any connected Astro site natively.
+---
+
+# cm-auto-publisher: The Agentic Publishing Skill
+
+> **Goal:** Take unstructured input (links, ideas, raw text), write a highly engaging article following Content Factory rules, and instantly publish it via the Content Factory Router API.
+
+## When to Use
+
+**ALWAYS when:**
+- User provides a link/video and says "Write an article about this and publish it".
+- User says "Draft and push this news to the blog".
+- You have finished drafting an article and need to deploy it to the live site.
+- An automated cron job triggers you to aggregate news and auto-publish.
+
+## The Process
+
+### Phase 1: Content Extraction & Structuring
+1. **Analyze Input:** If given a URL, use `read_url_content` (or your browsing tool) to read the source. If given images or Youtube links, extract them.
+2. **Draft Content:** Write a compelling article in standard Markdown.
+   - Use headings (`##`, `###`).
+   - For YouTube videos, use the Astro component: `<YouTube id="VIDEO_ID" />`.
+   - For images, just use standard markdown: `![Alt text](image_filename.jpg)`.
+
+### Phase 2: Media Preparation
+Identify all external images that need to be published with the article.
+DO NOT try to download them to the local disk using bash commands. The Content Factory Router will handle this.
+Instead, build a `media` array mapping the original URLs to the desired clean filenames.
+
+```json
+"media": [
+  {
+    "url": "https://source.com/raw-image-123.jpg",
+    "filename": "clean-seo-friendly-name.jpg"
+  }
+]
+```
+
+### Phase 3: API Payload Construction
+Construct the JSON payload matching the target site's schema.
+Standard Target: `cody-master` (mapped to `tody-agent/todyle-web`).
+
+```json
+{
+  "site_id": "cody-master",
+  "title": "[Engaging Title]",
+  "description": "[1-2 sentence SEO meta description]",
+  "category": "news", // or "guide", "use-case"
+  "readingTime": "5 min read",
+  "tags": ["AI", "Vibe Coding", "Automation"],
+  "content": "The raw markdown content here...",
+  "media": [ ... ]
+}
+```
+
+### Phase 4: Publish via Router API
+Send the payload to the Cloudflare Worker via a standard `fetch` or `curl` command.
+
+1. **Get the Secret:** Retrieve the API token from the `.env` file or ask the user for the `PUBLISHER_API_KEY`.
+2. **Send POST Request:**
+   Use a local script or curl to send the data to the worker.
+
+```bash
+# Example curl (assuming the payload is saved to payload.json)
+curl -X POST https://content-factory-router.<YOUR-CLOUDFLARE-ACCOUNT>.workers.dev/publish \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <API_KEY>" \
+  -d @payload.json
+```
+
+### Phase 5: Verification
+1. Check the response from the Worker. It should return `{"success": true, "message": "Published...", "commit_sha": "..."}`.
+2. Inform the user that the article has been successfully committed to GitHub and Cloudflare Pages is now building it.
+
+---
+
+## Red Flags - STOP!
+- ❌ **DO NOT** manually create `.mdx` files in `src/content/articles/` and run `git push` if using this skill! Let the Router API handle the Git history and image blob creation to ensure data consistency.
+- ❌ **DO NOT** use `cat` or `echo` to build complex JSON payloads in bash. Save the payload to a `.json` file using your file writing tool, then pass it to `curl`.