agrs-sequelize-sdk 1.4.27 → 1.4.28

package/tarzo-skalio-integration-docs.md

@@ -0,0 +1,691 @@
+# Tarzo ↔ Skalio Integration — Full Technical Documentation
+
+## 🎯 Goal & Introduction
+
+The goal of this task is to integrate **Tarzo** (platform.tarzo.io) as a new feed provider inside our **Skalio** dashboard, allowing us to launch Facebook campaigns directly from Skalio into Tarzo without using any official API (since Tarzo does not have one). Instead, we reverse-engineered Tarzo's internal API endpoints and authentication mechanism to operate as a normal logged-in user.
+
+**What we want to achieve:**
+1. **Campaign Creation** — Create Tarzo campaigns from Skalio the same way we do for other feed providers (Predicto, Mine, Compado, etc.), using the same Skalio form, naming conventions, and presets.
+2. **Policy Center Sync** — Fetch policy review statuses (approved, in_review, pending, rejected reasons, notes) from Tarzo and reflect them in Skalio's Campaign Logs page.
+3. **Performance Reporting** — Fetch revenue, ad clicks, conversions, and other feed-provider metrics from Tarzo by campaign ID, and merge them with the spend data we already pull from Facebook — exactly as we do for other RSOC feeds.
+4. **Ad Account & Page Sync** — Pull the list of Tarzo ad accounts and Facebook pages into Skalio so they are selectable when creating a Tarzo campaign.
+
+**Technical approach:** All communication is server-to-server. The Tarzo user's JWT token (extracted from localStorage on login) is stored securely on our backend. Every API call to Tarzo uses this token in the `Authorization` header. The token auto-refreshes on every response. No browser scraping is needed — all endpoints are standard JSON REST calls.
+
+> **Important:** When making requests to Tarzo's system, do not reference our system name, do not mention "API integration", and behave exactly as a regular logged-in Tarzo user would.
+
+---
+
+## Table of Contents
+1. Architecture Overview
+2. Tarzo Authentication
+3. Tarzo API Reference — Campaign Creation
+4. Tarzo API Reference — Policy Center
+5. Tarzo API Reference — Performance / Reporting
+6. Skalio System Overview
+7. Skalio Internal API Reference
+8. Field Mapping: Skalio → Tarzo
+9. Campaign Naming Convention Mapping
+10. New Skalio Feed Provider Entry ("Tarzo - RSOC")
+11. Performance Data Fetch Strategy
+12. Policy Center Integration Strategy
+13. Ad Accounts & Facebook Pages Sync
+14. Implementation Checklist
+
+---
+
+## 1. Architecture Overview
+
+The integration works as follows: Skalio acts as the orchestrator. When a user creates a campaign in Skalio with "Tarzo - RSOC" selected as the feed provider, Skalio's backend must:
+
+1. Use the Tarzo user's JWT token (stored in a secure backend config, not exposed to the frontend) to authenticate against Tarzo's internal API at `https://prod.tarzo.click/api/v1`
+2. Pre-check channel availability via `GET /api/v1/channel-management/available`
+3. POST a campaign payload to `POST /api/v1/facebook/creator/campaign/create`
+4. Store the returned Tarzo campaign ID mapped to the Skalio campaign ID
+5. Periodically sync policy status via `GET /api/v1/compliance/feed`
+6. Periodically sync performance data via `GET /api/v1/facebook/hometalk/campaigns/report/campaign?campaignId=...`
+
+No browser-side scraping is needed. All communication is server-to-server using the stored JWT token.
+
+---
+
+## 2. Tarzo Authentication
+
+**Token source:** The JWT is stored in Tarzo's browser localStorage under the key "authorization". For your integration, a Tarzo account must be set up as a service account, and the token should be extracted once (at login time) and stored securely on your backend. The token auto-refreshes: every response from Tarzo's API includes a refreshed authorization header — your backend must update the stored token on every response.
+
+**How to authenticate every request:**
+```
+Authorization: <jwt_token>
+Content-Type: application/json
+Accept: application/json
+```
+
+**All requests go to:** `https://prod.tarzo.click/api/v1/<endpoint>`
+
+**Session validation:** `GET /api/v1/auth/iam` — call this to validate the token and get user info (firstName, id). These are used in campaign naming.
+
+**Token refresh logic:**
+- On each response, check if an `authorization` header is returned
+- If yes, update the stored token with the new value
+- If a `deauthorization` header is returned, the session has expired — re-login required
+
+---
+
+## 3. Tarzo API Reference — Campaign Creation
+
+### Pre-flight Checks
+
+**Check available Tarzo channels:**
+```
+GET /api/v1/channel-management/available?revenueSource=hometalk
+GET /api/v1/channel-management/available?revenueSource=hometalk&integrationId=<integration_id>
+```
+Returns remaining channel count. Abort if zero.
+
+**Get ad accounts:**
+```
+GET /api/v1/facebook/accounts?revenueSource=hometalk
+```
+Returns the list of ad account objects. Each has an id and a display code (e.g. "D-1", "R-1920").
+
+**Get integrations:**
+```
+GET /api/v1/integration-management?revenueSource=hometalk&enabled=true&network=facebook
+```
+Returns integration objects including integration ID (needed for domain filtering and the campaign payload).
+
+**Get domains:**
+```
+GET /api/v1/domain-management?revenueSource=hometalk&network=facebook
+GET /api/v1/domain-management?revenueSource=hometalk&integrationId=<id>
+```
+Returns available Tarzo domains (e.g. https://www.upgradedhome.com/dcg).
+
+**Get topics / offers:**
+```
+GET /api/v1/backoffice/offers
+```
+Returns all topics/verticals (e.g. "internet-providers", "roof-replacement").
+
+### Initialize Article (Hometalk)
+
+This must be done before campaign creation. It reserves a Tarzo channel and returns an article ID.
+
+```
+POST /api/v1/hometalk/assets/initialize-article
+Content-Type: application/json
+
+{
+  "offer": "internet-providers",
+  "domain": "https://www.upgradedhome.com/dcg",
+  "language": "en",
+  "keyword": "<main keyword, max 80 chars, English only>",
+  "articleContent": "<optional comma-separated extra keywords>",
+  "terms": []
+}
+```
+Returns: An article/channel ID used in the campaign creation URL.
+
+### Create Campaign
+
+```
+POST /api/v1/facebook/creator/campaign/create/<articleId>
+Content-Type: application/json
+
+{
+  "campaigns": [
+    {
+      "campaign": {
+        "name": "ww-en-fb-tz-tsuf-147-internet-providers-464-[5G Internet Guide]-488",
+        "freeText": "",
+        "accountId": "act_1234567890",
+        "objective": "OUTCOME_SALES",
+        "campaignType": "website",
+        "specialAdCategories": [],
+        "budget": 5,
+        "budgetType": "daily",
+        "isAdvantagePlus": false
+      },
+      "adSets": [
+        {
+          "budget": 5,
+          "countries": [],
+          "regions": [],
+          "language": "en",
+          "device": "",
+          "platforms": ["facebook", "instagram"],
+          "placements": [],
+          "os": "",
+          "pixelId": "<facebook_pixel_id>",
+          "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
+          "bidAmount": "",
+          "pixelEvent": "PURCHASE",
+          "optimizationGoal": "OFFSITE_CONVERSIONS",
+          "adType": "SINGLE",
+          "startTime": null,
+          "attributionSpec": "",
+          "ageTargeting": { "min": 18, "max": 65 },
+          "genders": [],
+          "ads": [
+            {
+              "status": "ACTIVE",
+              "targetUrl": "https://...",
+              "urlTag": "",
+              "displayUrl": "",
+              "pageId": "<facebook_page_id>",
+              "pageCredentials": false,
+              "primaryText": "...",
+              "headlineText": "...",
+              "description": "",
+              "cta": "LEARN_MORE",
+              "selectedCreatives": ["<creative_id>"],
+              "translationLanguage": ""
+            }
+          ]
+        }
+      ],
+      "hometalk": {
+        "offer": "internet-providers",
+        "keyword": "<main keyword>",
+        "articleContent": "",
+        "domain": "https://www.upgradedhome.com/dcg",
+        "language": "en",
+        "terms": []
+      }
+    }
+  ]
+}
+```
+
+**If article was not pre-initialized:** Use `POST /api/v1/facebook/creator/campaign/create` (no trailing ID).
+
+**Duplicate an existing campaign:**
+```
+POST /api/v1/facebook/creator/campaign/duplicate/<baseCampaignId>
+Body: { "campaigns": [...] }
+```
+
+### Tarzo Campaign Field Reference
+
+**Campaign-level fields:**
+
+| Field | Type | Allowed Values |
+|---|---|---|
+| objective | enum | OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION |
+| campaignType | enum | website, app, website-and-app, messaging-app, calls |
+| specialAdCategories | array | [], ["HOUSING"], ["EMPLOYMENT"], ["FINANCIAL_PRODUCTS_SERVICES"] |
+| budgetType | enum | daily, lifetime |
+| budget | number | Any positive number |
+| isAdvantagePlus | boolean | false (default) |
+
+**Ad Set-level fields:**
+
+| Field | Type | Allowed Values / Notes |
+|---|---|---|
+| bidStrategy | enum | LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS |
+| optimizationGoal | enum | OFFSITE_CONVERSIONS (default), LINK_CLICKS, IMPRESSIONS, LANDING_PAGE_VIEWS |
+| platforms | array | facebook, instagram, messenger, audience_network |
+| adType | enum | SINGLE, FLEXIBLE — NO Carousel support |
+| countries | array | ISO country codes, or empty array for Worldwide |
+| genders | array | ["male"], ["female"], or [] for all |
+| ageTargeting | object | { "min": 18, "max": 65 } |
+| device | string | "desktop", "mobile", or "" for all |
+| os | string | OS filter string or empty |
+| pixelEvent | enum | PURCHASE (default) |
+
+**Ad-level fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| cta | enum | LEARN_MORE, WATCH_MORE, WATCH_VIDEO, SHOP_NOW, SIGN_UP, GET_OFFER, APPLY_NOW, GET_QUOTE, SEE_MORE, BOOK_NOW, CONTACT_US, CALLS |
+| headlineText | string | Min 10, max 100 chars |
+| description | string | Optional, min 20 max 250 chars |
+| selectedCreatives | array | Creative IDs from Tarzo's library |
+
+**Special categories constraint:** Cannot use HOUSING, EMPLOYMENT, or FINANCIAL_PRODUCTS_SERVICES when targeting Worldwide (empty countries). Enforce this in Skalio before sending.
+
+---
+
+## 4. Tarzo API Reference — Policy Center
+
+### Fetch policy data (paginated)
+```
+GET /api/v1/compliance/feed
+  ?revenueSource=hometalk
+  &network=facebook
+  &search=
+  &status=<allowed|in_review|pending|unknown>
+  &integrationId=
+  &sortBy=
+  &offset=0
+  &limit=25
+  &users[]=<userId>
+  &createdAt.from=<ISO date>
+  &createdAt.to=<ISO date>
+  &lastCheckedAt.from=<ISO date>
+  &lastCheckedAt.to=<ISO date>
+```
+
+### Get policy totals
+```
+GET /api/v1/compliance/feed/totals
+  ?revenueSource=hometalk
+  &network=facebook
+  &search=
+  &status=
+  &integrationId=
+```
+
+### Export policy data (up to 25,000 rows)
+```
+POST /api/v1/compliance/feed/export
+Body: same filters as the GET endpoint (JSON)
+```
+
+### Policy record fields returned:
+
+| Field | Notes |
+|---|---|
+| adId | Tarzo's internal Ad ID |
+| adStatus | Active/Paused status |
+| status | allowed, approved, manual-approved, in_review, pending, unknown |
+| campaignId | Tarzo campaign ID |
+| campaignName | Full Tarzo campaign name |
+| adAccountId | Facebook Ad Account ID |
+| reason | Policy rejection reason |
+| notes | Additional notes from reviewer |
+| adName | Name of the ad |
+| headline | Ad headline |
+| adsManagerLink | Link to Facebook Ads Manager |
+| lastCheck | Timestamp of last policy check |
+| createdAt | Record creation timestamp |
+| user | Which Tarzo user created this ad |
+
+---
+
+## 5. Tarzo API Reference — Performance / Reporting
+
+All endpoints return: revenue, spend (cost), conversions, feedProviderConversions, feedProviderCpa, networkClicks, impressions, networkRpc, feedProviderSearches, netProfit, roi, roas, ctr, cpc, cpm, rpc, cr, facebookRpc, results.
+
+### All campaigns dashboard list
+```
+GET /api/v1/facebook/hometalk/campaigns/report
+  ?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=25&offset=0&search=&sortBy=&status=&ruleHits=&lastActivity=
+```
+
+### Dashboard totals (all campaigns)
+```
+GET /api/v1/facebook/hometalk/campaigns/report/totals
+  ?from=YYYY-MM-DD&to=YYYY-MM-DD&search=&status=&ruleHits=&lastActivity=&bidStrategy=
+```
+
+### Single campaign performance by day
+```
+GET /api/v1/facebook/hometalk/campaigns/report/campaign
+  ?campaignId=<tarzo_campaign_id>&from=YYYY-MM-DD&to=YYYY-MM-DD
+```
+
+### Totals for a specific campaign
+```
+GET /api/v1/facebook/hometalk/campaigns/report/totals
+  ?campaignId=<tarzo_campaign_id>&from=YYYY-MM-DD&to=YYYY-MM-DD
+```
+
+### Ad set performance
+```
+GET /api/v1/facebook/hometalk/adsets/report
+  ?campaignIds[]=<tarzo_campaign_id>&from=YYYY-MM-DD&to=YYYY-MM-DD&search=
+```
+
+### Ad-level performance
+```
+GET /api/v1/facebook/hometalk/ads/report
+  ?campaignIds[]=<tarzo_campaign_id>&from=YYYY-MM-DD&to=YYYY-MM-DD&search=
+```
+
+### CSV export (max 25,000 rows)
+```
+POST /api/v1/facebook/{entityType}s/export
+entityType: campaign | adset | ad
+Body: filter params as JSON
+```
+
+### Get single campaign details
+```
+GET /api/v1/facebook/campaigns/campaign/<campaignId>
+```
+
+---
+
+## 6. Skalio System Overview
+
+**Framework:** Next.js (React, Recoil state management, MUI components, Zod validation, Axios HTTP client)
+**Base URL:** https://www.skalio.io
+**Internal API base:** All frontend calls go to /api/... (Next.js API routes, server-side)
+**Auth:** Cookie-based session (Next.js middleware)
+
+### Navigation structure:
+- Performance — main campaign performance table
+- Keywords Performance — keyword-level performance
+- Country Breakdown — geo performance
+- Create > Campaigns — general campaign creator
+- Create > Facebook Campaigns — main Facebook creator at /dashboard/facebook
+- Create > Articles — article management
+- Create > Campaign Creation Logs — same as /dashboard/campaign-logs
+- File Manager — media/creative assets
+- Rules Automation — automated rules engine
+- Research — research tools
+- Assets — asset management
+- Generate — AI generation tools
+- Tier2 Business Manager — multi-account management
+
+### Campaign creation modes (3 tabs):
+- **Use Existing** — re-use an existing campaign structure (adds Campaign Name search at top)
+- **AI Campaign** — AI-assisted campaign creation
+- **Create New** — manual creation (the primary flow)
+
+### Create New form fields:
+| Field | Notes |
+|---|---|
+| Platform | Facebook (fixed for this page) |
+| Media Buyer | Buyer code (e.g. "tsuf", "mark") |
+| Feed Provider | Dropdown from Feed table |
+| Vertical | Topic/vertical slug |
+| Country | Single or multi country, or empty for WW |
+| Language | ISO language code |
+| Notes | Free text, maps to freeText in campaign |
+| Ad Title | Maps to headlineText in ad |
+| Keywords | Main keyword + additional keywords |
+| Campaign Name Preview | Auto-generated: agrs-{feed}-fb-tp-{country}-{language}-{vertical}-{ddmm} |
+
+---
+
+## 7. Skalio Internal API Reference
+
+### Campaign Management
+| Endpoint | Method | Description |
+|---|---|---|
+| /api/facebook/campaign/create | POST | Create campaign record in Skalio DB |
+| /api/facebook/campaign/read | GET | Read campaign by ID |
+| /api/facebook/campaign/readBatchCampaign | GET | Read multiple campaigns |
+| /api/facebook/campaign/readcampaignHirarchi | GET | Full hierarchy (campaign+adsets+ads) |
+| /api/facebook/campaign/update | PUT | Update campaign |
+| /api/facebook/campaign/delete | DELETE | Delete campaign |
+| /api/facebook/campaign/duplicate | POST | Duplicate campaign |
+| /api/facebook/campaign/publish | POST | Publish to Facebook |
+| /api/facebook/campaign/restore | POST | Restore deleted campaign |
+
+### Ad Set Management
+| Endpoint | Method | Description |
+|---|---|---|
+| /api/facebook/adset/create | POST | Create ad set |
+| /api/facebook/adset/read | GET | Read ad set |
+| /api/facebook/adset/readAll | GET | Read all ad sets |
+| /api/facebook/adset/readAllFromCampaignId | GET | Read by campaign ID |
+| /api/facebook/adset/update | PUT | Update ad set |
+| /api/facebook/adset/delete | DELETE | Delete ad set |
+| /api/facebook/adset/duplicate | POST | Duplicate ad set |
+| /api/facebook/adset/publish | POST | Publish to Facebook |
+| /api/facebook/adset/restore | POST | Restore ad set |
+
+### Ad Management
+| Endpoint | Method | Description |
+|---|---|---|
+| /api/facebook/ad/create | POST | Create ad |
+| /api/facebook/ad/read | GET | Read ad |
+| /api/facebook/ad/update | PUT | Update ad |
+| /api/facebook/ad/delete | DELETE | Delete ad |
+| /api/facebook/ad/duplicate | POST | Duplicate ad |
+| /api/facebook/ad/publish | POST | Publish to Facebook |
+| /api/newFiles/uploadToFacebook | POST | Upload media to Facebook |
+| /api/newFiles/getAdMedia | GET | Get media for single ad |
+| /api/newFiles/getAdsMedia | GET | Get media for multiple ads |
+
+### Feed Campaign Lifecycle
+| Endpoint | Method | Description |
+|---|---|---|
+| /api/feedCampaign/publishDraftCampaign | POST | KEY: Publishes draft to feed provider. This is where Tarzo integration code goes. |
+| /api/feedCampaign/duplicate | POST | Duplicate a feed campaign |
+
+### Performance
+| Endpoint | Method | Params |
+|---|---|---|
+| /api/performance/campaign/bydate | GET | page, rowsPerPage, sort, date_range, ad_account, campaign_name, ad_status |
+| /api/performance/campaign/byid | GET | feed, buyer, daterange, filterCampaignByIds, created_times, filterByDate, sortByIds, sortByDate, pageByIds, rowsPerPageByIds, adAccount, campaignName, createdTime, adStatus, country, vertical, roi_range, cost_range, ctr_range, rpc_range, cpa_range |
+| /api/performance/campaign/totals | GET | dates, ad_account, campaign_name, ad_status |
+| /api/performance/campaign/draftbyid | GET | Performance for draft campaigns |
+
+### Static / Reference Data
+| Endpoint | Method | Description |
+|---|---|---|
+| /api/static/Feed/findAll | GET | All feed providers |
+| /api/static/Feed/create | POST | Create new feed provider |
+| /api/static/adAccount/findAll | GET | All ad accounts |
+| /api/static/adAccount/create | POST | Create ad account |
+| /api/static/adAccount/update | PUT | Update ad account |
+| /api/static/adAccount/bulk-create | POST | Bulk create ad accounts |
+| /api/static/Pages/findAll | GET | All Facebook pages |
+| /api/static/Pages/create | POST | Create page |
+| /api/static/Pages/update | PUT | Update page |
+| /api/static/Pages/bulk-create | POST | Bulk create pages |
+| /api/static/Buyers/findAll | GET | All media buyers |
+| /api/static/channel/findAll | GET | All channels |
+| /api/static/channel/create | POST | Create channel |
+| /api/static/channel/update | PUT | Update channel |
+| /api/static/channel/bulk-create | POST | Bulk create channels |
+| /api/configuration/getAdConfiguration | GET | Ad-level config. Params: campaignIds, adSetId, adIds |
+| /api/configuration/getAdsetsConfiguration | GET | Adset-level config. Params: campaignIds, adSetIds |
+
+---
+
+## 8. Field Mapping: Skalio → Tarzo
+
+### Campaign Creation Form
+
+| Skalio Field | Skalio Value Example | Tarzo Field | Tarzo Value |
+|---|---|---|---|
+| platform | "Facebook" | network | "facebook" |
+| feed | "Tarzo - RSOC" | revenueSource | "hometalk" |
+| buyer | "tsuf" | Used in campaign name | Name segment |
+| vertical | "internet-providers" | hometalk.offer | "internet-providers" |
+| country | ["us"] or [] for WW | adSets[].countries | ["US"] or [] |
+| language | ["en"] | hometalk.language | "en" |
+| notes | "test campaign" | campaign.freeText | "test campaign" |
+| adTitle | "5G Internet Guide" | headlineText + in name | "[5G Internet Guide]" |
+| keywords[0] | "5g internet providers" | hometalk.keyword | "5g internet providers" |
+| keywords[1..n] | Additional keywords | hometalk.articleContent | Comma-separated string |
+
+### Bid Strategy Mapping
+
+| Skalio Preset Label | Tarzo bidStrategy value |
+|---|---|
+| "Lowest Cost" / "LC" | LOWEST_COST_WITHOUT_CAP |
+| "Bid Cap" / "BC" | LOWEST_COST_WITH_BID_CAP |
+| "Cost Cap" / "CC" | COST_CAP |
+| "Target ROAS" / "TROAS" | LOWEST_COST_WITH_MIN_ROAS |
+
+### Objective Mapping
+
+| Skalio Objective | Tarzo objective |
+|---|---|
+| Sales | OUTCOME_SALES |
+| Traffic | OUTCOME_TRAFFIC |
+| Leads | OUTCOME_LEADS |
+| Engagement | OUTCOME_ENGAGEMENT |
+| Awareness | OUTCOME_AWARENESS |
+| App Promotion | OUTCOME_APP_PROMOTION |
+
+---
+
+## 9. Campaign Naming Convention Mapping
+
+### Skalio naming format:
+```
+agrs-{feed}-fb-{buyer}-{country}-{language}-{vertical}-{ddmm}
+```
+Example from live preview: agrs-{feed}-fb-tp-{country}-{language}-{vertical}-0604
+
+Where:
+- agrs = system prefix (always fixed)
+- {feed} = feed provider code (propose "tz" for Tarzo)
+- fb = platform
+- {buyer} = media buyer short code (e.g. "tsuf")
+- {country} = ISO code, "mix" (multi-country), or "ww" (worldwide)
+- {language} = language code
+- {vertical} = vertical slug
+- {ddmm} = campaign creation date
+
+### Tarzo naming format:
+```
+{country_prefix}-{language}-{platform}-{feed_code}-{buyer_code}-{account_last3}-{topic}-{channel_last3}-[{article_title}]-{user_last3}
+```
+Example: ww-en-fb-tz-tsuf-147-internet-providers-464-[5G Internet Guide]-488
+
+Where:
+- ww-en = worldwide + English (0 countries = "ww-en", 1 country = country code, 2+ = "mc-en")
+- fb = facebook
+- tz = Tarzo feed code (fixed)
+- tsuf = buyer/account prefix
+- 147 = last 3 digits of Facebook ad account ID
+- internet-providers = topic slug
+- 464 = last 3 digits of article/channel ID (returned from initialize-article)
+- [5G Internet Guide] = article title in square brackets
+- 488 = last 3 digits of the Tarzo user ID (from /auth/iam)
+
+**Rule:** Use Tarzo's naming format in the campaign.name field sent to Tarzo. Store Skalio's own campaign name separately and link both via the Tarzo campaign ID.
+
+---
+
+## 10. New Skalio Feed Provider Entry
+
+To add Tarzo as a feed provider in Skalio:
+
+```
+POST /api/static/Feed/create
+Body:
+{
+  "feedName": "Tarzo - RSOC",
+  "feedType": "rsoc",
+  "platform": "Facebook",
+  "feedCode": "tz",
+  "revenueSource": "hometalk",
+  "network": "facebook"
+}
+```
+
+The Feed Provider dropdown is populated from GET /api/static/Feed/findAll — once the record is created, it appears automatically.
+
+When Tarzo is selected, the publishDraftCampaign handler must detect feedType: "rsoc" + revenueSource: "hometalk" and route to Tarzo's API.
+
+---
+
+## 11. Performance Data Fetch Strategy
+
+**Approach:** Skalio fetches cost/spend from Facebook (existing flow). Tarzo provides revenue and feed-provider metrics only.
+
+**Recommended sync:** Every 3 hours per campaign, or on-demand.
+
+**Fetch per campaign:**
+```
+GET /api/v1/facebook/hometalk/campaigns/report/campaign
+  ?campaignId=<tarzo_id>&from=<date>&to=<date>
+```
+
+### Performance Column Mapping
+
+| Skalio Column | Tarzo Field | Notes |
+|---|---|---|
+| Revenue | revenue | From Tarzo |
+| Cost | — | From Facebook (existing flow) |
+| Ad Clicks | networkClicks | Tarzo's "ad clicks" metric |
+| Conversions | feedProviderConversions | Feed-level conversions |
+| RPC | networkRpc | Feed provider RPC |
+| CPA | feedProviderCpa | Feed-level CPA |
+| TS RPC | networkRpc | Same field |
+| TS CPA | feedProviderCpa | Same field |
+| CTR % | ctr | From Tarzo |
+| CPC | cpc | From Tarzo |
+| CR % | cr | Conversion rate |
+| Net Profit | revenue - cost | Calculated |
+| ROI | (revenue - cost) / cost * 100 | Calculated |
+
+---
+
+## 12. Policy Center Integration Strategy
+
+**Approach:** Daily sync job fetches policy data from Tarzo and stores in Skalio campaign_logs table, keyed by Tarzo adId and campaignId.
+
+**Fetch:**
+```
+GET /api/v1/compliance/feed
+  ?revenueSource=hometalk&network=facebook&offset=0&limit=100
+  (paginate until all records fetched)
+```
+
+### Mapping to Skalio Campaign Logs
+
+| Skalio Column | Tarzo Policy Field |
+|---|---|
+| Campaign Name | campaignName |
+| Status | adStatus (Active/Paused) |
+| Policy Status | status (allowed, in_review, pending, etc.) |
+| Account | adAccountId |
+| Feed | "Tarzo - RSOC" (hardcoded) |
+| Ad | adId |
+| Campaign Details | reason + notes |
+| User | user |
+
+Match records to Skalio campaigns using the campaignId stored at creation time.
+
+---
+
+## 13. Ad Accounts & Facebook Pages Sync
+
+**Fetch Tarzo ad accounts:**
+```
+GET /api/v1/facebook/accounts?revenueSource=hometalk
+```
+Returns accounts with id (act_XXXXXXX format) and display name (e.g. "D-1").
+
+**Store in Skalio:**
+```
+POST /api/static/adAccount/bulk-create
+Body: { accounts: [{accountId: "act_123...", name: "D-1", feedProvider: "tarzo"}, ...] }
+```
+
+**Facebook Pages:** Page IDs are standard Facebook page IDs. Use Skalio's existing page list (GET /api/static/Pages/findAll). When Tarzo is selected as feed provider, show the page selector — the same page IDs work in both systems.
+
+---
+
+## 14. Implementation Checklist
+
+### Backend
+
+- [ ] Create tarzo.service.ts with: base URL (https://prod.tarzo.click/api/v1), token management (read/refresh on every response), and all endpoint wrappers from sections 3–5
+- [ ] Add Tarzo JWT token to secure env/secrets storage; implement auto-refresh logic on every response
+- [ ] Create "Tarzo - RSOC" feed record via POST /api/static/Feed/create
+- [ ] Extend /api/feedCampaign/publishDraftCampaign — add Tarzo branch: detect revenueSource "hometalk", call initialize-article first, then create campaign, save returned Tarzo campaign ID against Skalio campaign ID
+- [ ] Sync Tarzo ad accounts via GET /api/v1/facebook/accounts?revenueSource=hometalk → store with feedProvider: "tarzo" tag
+- [ ] Extend /api/performance/campaign/byid — when feed = "tarzo-rsoc", fetch revenue metrics from Tarzo and merge with Facebook cost data
+- [ ] Create policy sync cron job: call GET /api/v1/compliance/feed paginated → write to campaign_logs table
+- [ ] Fetch and cache Tarzo domain list (GET /api/v1/domain-management?revenueSource=hometalk)
+- [ ] Enforce validation: block HOUSING/EMPLOYMENT/FINANCIAL special categories when countries is empty (Worldwide)
+- [ ] Add tarzo_campaign_id column to Skalio campaigns table
+
+### Frontend
+
+- [ ] "Tarzo - RSOC" will appear in Feed Provider dropdown automatically once DB record is created
+- [ ] Show Tarzo-specific fields when Tarzo is selected: Domain selector, Article Content Query (max 80 chars, English), Terms (optional)
+- [ ] Add Facebook Page selector when Tarzo is feed provider (required for ad creation)
+- [ ] Show only Tarzo-tagged ad accounts when Tarzo is feed
+- [ ] Show Tarzo channel availability count (from channel-management/available) before submit
+- [ ] Update Campaign Name Preview to show Tarzo naming format alongside Skalio format
+- [ ] Map Tarzo policy statuses in Campaign Logs: allowed = green, in_review = yellow, pending = orange, unknown = grey
+- [ ] Add "Tarzo" filter option in Performance page Feed dropdown
+
+### Still to confirm
+
+1. **Creative upload to Tarzo** — The upload endpoint is likely POST /api/v1/creatives/library/save/v2 (multipart). Confirm exact field names by capturing a network request when clicking "Upload Media" in the Tarzo Creatives Library. Recommended approach: pre-upload creatives via Tarzo UI, store creative IDs in Skalio, expose a Tarzo Creative selector in the form.
+2. **Tarzo service account** — Confirm which Tarzo account to use as the service account for the integration.
+3. **tarzo_campaign_id storage** — Confirm schema changes to store Tarzo campaign ID linked to Skalio campaign ID.
+4. **Keywords sync** — Planned for a later phase. Tarzo has keyword-level data available via the ads/report endpoint.