agrs-sequelize-sdk 1.4.51 → 1.4.53

package/tarzo-skalio-integration-docs.md

@@ -1,691 +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.
+# 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.