agrs-sequelize-sdk 1.4.18 → 1.4.21

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-PIXELS-FOLLOWUP.md

@@ -0,0 +1,85 @@
+# Platform column normalization — follow-on work
+
+## Tables skipped from the 2026-05-17 platform rollout
+
+The following 4 tables were intentionally OMITTED from the 2026-05-17 platform-column
+rollout because each already has a `platform` column of type VARCHAR with
+capitalized values (e.g. "Facebook"). Adding an ENUM column with the same name
+would either fail outright or destructively override existing data.
+
+| Table                          | Existing column type | Existing values seen                                   |
+|--------------------------------|----------------------|--------------------------------------------------------|
+| `Pixels`                       | varchar              | "Facebook", "Tiktok", "Taboola", "Outbrain", "Yahoo"   |
+| `CampaignCreationLogs`         | varchar(50)          | "Facebook", "fb", NULL                                 |
+| `CampaignCreationLogsV2`       | varchar(50)          | "Facebook", "fb", NULL                                 |
+| `rsoc_feed_campaigns`          | varchar              | "Facebook", "fb"                                       |
+
+The rest of the rollout uses lowercase short codes: `fb`, `tt`, `snp`.
+
+## Why we did not "just add another column"
+
+A naive `addColumn("platform")` collides with the existing column name. A naive
+`UPDATE` to lowercase the values would touch production data and is destructive.
+Both violate the safety constraint of this rollout (additive only).
+
+## Recommended path (separate plan)
+
+For each of the 4 tables:
+
+1. Add a new column `platform_code` ENUM('fb','tt','snp','tab','out','yh') NOT NULL DEFAULT 'fb'
+2. Backfill in a single transaction. Example for Pixels:
+   ```sql
+   UPDATE "Pixels" SET platform_code = CASE platform
+     WHEN 'Facebook' THEN 'fb'
+     WHEN 'Tiktok'   THEN 'tt'
+     WHEN 'Taboola'  THEN 'tab'
+     WHEN 'Outbrain' THEN 'out'
+     WHEN 'Yahoo'    THEN 'yh'
+     ELSE 'fb'
+   END;
+   ```
+   For CampaignCreationLogs / CampaignCreationLogsV2 / rsoc_feed_campaigns the
+   backfill is simpler:
+   ```sql
+   UPDATE "CampaignCreationLogs" SET platform_code = CASE LOWER(COALESCE(platform, 'fb'))
+     WHEN 'facebook' THEN 'fb'
+     WHEN 'fb'       THEN 'fb'
+     WHEN 'tiktok'   THEN 'tt'
+     WHEN 'tt'       THEN 'tt'
+     ELSE 'fb'
+   END;
+   ```
+3. Update server code to read `platform_code` for new logic; leave the legacy
+   `platform` column untouched for backward compat.
+4. Eventually deprecate the legacy `platform` column and rename `platform_code`
+   → `platform` once all callers have migrated. That happens in a separate,
+   later cleanup plan.
+
+## Until then
+
+The dashboard's platform adapter (created in the Phase 0 backend plan) MUST
+normalize legacy `platform` values when comparing to the canonical fb/tt/snp
+codes. Example normalizer:
+
+```javascript
+function normalizeLegacyPlatform(legacy) {
+  if (!legacy) return "fb";
+  const map = {
+    Facebook: "fb",
+    facebook: "fb",
+    FB: "fb",
+    fb: "fb",
+    Tiktok: "tt",
+    TikTok: "tt",
+    tiktok: "tt",
+    tt: "tt",
+    Snapchat: "snp",
+    snapchat: "snp",
+    snp: "snp",
+    Taboola: "tab",
+    Outbrain: "out",
+    Yahoo: "yh",
+  };
+  return map[legacy] || "fb";
+}
+```

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-ad.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("Ad", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("Ad", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_Ad_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-adaccount.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("AdAccount", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("AdAccount", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_AdAccount_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-adperformance.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("AdPerformance", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("AdPerformance", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_AdPerformance_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-adset.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("AdSet", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("AdSet", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_AdSet_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-adsetperformance.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("AdSetPerformance", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("AdSetPerformance", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_AdSetPerformance_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-aiarticleretryqueue.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("ai_article_retry_queue", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("ai_article_retry_queue", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_ai_article_retry_queue_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-aicampaignqueue.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("ai_campaign_queue", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("ai_campaign_queue", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_ai_campaign_queue_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-article.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("articles", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("articles", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_articles_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-campaign.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("Campaign", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("Campaign", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_Campaign_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-codefuelcampaign.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("CodefuelCampaigns", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("CodefuelCampaigns", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_CodefuelCampaigns_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-dynamicfeed.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("dynamic_feeds", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("dynamic_feeds", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_dynamic_feeds_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-facebookretryqueue.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("facebook_retry_queue", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("facebook_retry_queue", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_facebook_retry_queue_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-pages.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("Pages", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("Pages", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_Pages_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-17-add-platform-to-presets.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    await queryInterface.addColumn("Presets", "platform", {
+      type: Sequelize.ENUM("fb", "tt", "snp"),
+      allowNull: false,
+      defaultValue: "fb",
+      comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+    });
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.removeColumn("Presets", "platform");
+    await queryInterface.sequelize.query(
+      'DROP TYPE IF EXISTS "enum_Presets_platform";'
+    );
+  },
+};

package/.worktrees/tt-snp-adset-ad-tables/migrations/2026-05-18-create-tt-snp-adset-ad-tables.js

@@ -0,0 +1,309 @@
+"use strict";
+
+// Additive migration — creates four new tables to mirror TikTok ad groups/ads
+// and Snapchat ad squads/ads in the local DB. No FKs to existing tables;
+// loose coupling keeps platform isolation. Reporting joins to canonical_insights
+// at the MV layer (see dashboard migration 004-multi-platform-ad-level.sql).
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    // ----- TikTok Ad Groups -----
+    await queryInterface.createTable("tiktok_adgroups", {
+      adgroup_id: {
+        type: Sequelize.BIGINT,
+        primaryKey: true,
+        allowNull: false,
+      },
+      adgroup_name: {
+        type: Sequelize.STRING(255),
+        allowNull: false,
+      },
+      campaign_id: {
+        type: Sequelize.BIGINT,
+        allowNull: false,
+        comment:
+          "TikTok campaign_id; loose FK to tiktok_campaigns (no DB-level constraint)",
+      },
+      ad_account_id: {
+        type: Sequelize.STRING(64),
+        allowNull: false,
+      },
+      placement_type: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "PLACEMENT_TYPE_AUTOMATIC / PLACEMENT_TYPE_NORMAL",
+      },
+      budget_mode: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      budget: {
+        type: Sequelize.DECIMAL(12, 6),
+        allowNull: true,
+      },
+      bid_type: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      bid_price: {
+        type: Sequelize.DECIMAL(12, 6),
+        allowNull: true,
+      },
+      optimize_goal: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      operation_status: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "ENABLE or DISABLE (TikTok native)",
+      },
+      schedule_start_time: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      schedule_end_time: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      created_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+    });
+
+    await queryInterface.addIndex("tiktok_adgroups", ["campaign_id"]);
+    await queryInterface.addIndex("tiktok_adgroups", ["ad_account_id"]);
+    await queryInterface.addIndex("tiktok_adgroups", ["operation_status"]);
+
+    // ----- TikTok Ads -----
+    await queryInterface.createTable("tiktok_ads", {
+      ad_id: {
+        type: Sequelize.BIGINT,
+        primaryKey: true,
+        allowNull: false,
+      },
+      ad_name: {
+        type: Sequelize.STRING(255),
+        allowNull: false,
+      },
+      adgroup_id: {
+        type: Sequelize.BIGINT,
+        allowNull: false,
+        comment:
+          "TikTok adgroup_id; loose FK to tiktok_adgroups (no DB-level constraint)",
+      },
+      campaign_id: {
+        type: Sequelize.BIGINT,
+        allowNull: false,
+      },
+      ad_account_id: {
+        type: Sequelize.STRING(64),
+        allowNull: false,
+      },
+      ad_format: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "SINGLE_VIDEO, SINGLE_IMAGE, etc.",
+      },
+      identity_id: {
+        type: Sequelize.STRING(64),
+        allowNull: true,
+        comment: "TikTok identity (Page equivalent)",
+      },
+      landing_page_url: {
+        type: Sequelize.TEXT,
+        allowNull: true,
+      },
+      display_name: {
+        type: Sequelize.STRING(255),
+        allowNull: true,
+      },
+      operation_status: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "ENABLE or DISABLE (TikTok native)",
+      },
+      created_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+    });
+
+    await queryInterface.addIndex("tiktok_ads", ["adgroup_id"]);
+    await queryInterface.addIndex("tiktok_ads", ["campaign_id"]);
+    await queryInterface.addIndex("tiktok_ads", ["operation_status"]);
+
+    // ----- Snapchat Ad Squads -----
+    await queryInterface.createTable("snapchat_ad_squads", {
+      id: {
+        type: Sequelize.STRING(36),
+        primaryKey: true,
+        allowNull: false,
+        comment: "Snapchat ad squad UUID",
+      },
+      name: {
+        type: Sequelize.STRING(255),
+        allowNull: false,
+      },
+      campaign_id: {
+        type: Sequelize.STRING(36),
+        allowNull: false,
+        comment: "Snapchat campaign UUID; loose FK to snapchat_campaigns",
+      },
+      ad_account_id: {
+        type: Sequelize.STRING(36),
+        allowNull: false,
+      },
+      status: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "ACTIVE or PAUSED (Snap native)",
+      },
+      type: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "SNAP_ADS",
+      },
+      bid_strategy: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      optimization_goal: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      billing_event: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+      },
+      placement_v2: {
+        type: Sequelize.JSONB,
+        allowNull: true,
+        comment: "Snap placement_v2 config (e.g. {config:'AUTOMATIC', ...})",
+      },
+      daily_budget_micro: {
+        type: Sequelize.BIGINT,
+        allowNull: true,
+      },
+      bid_micro: {
+        type: Sequelize.BIGINT,
+        allowNull: true,
+      },
+      targeting: {
+        type: Sequelize.JSONB,
+        allowNull: true,
+      },
+      start_time: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      end_time: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      created_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+    });
+
+    await queryInterface.addIndex("snapchat_ad_squads", ["campaign_id"]);
+    await queryInterface.addIndex("snapchat_ad_squads", ["ad_account_id"]);
+    await queryInterface.addIndex("snapchat_ad_squads", ["status"]);
+
+    // ----- Snapchat Ads -----
+    await queryInterface.createTable("snapchat_ads", {
+      id: {
+        type: Sequelize.STRING(36),
+        primaryKey: true,
+        allowNull: false,
+        comment: "Snapchat ad UUID",
+      },
+      name: {
+        type: Sequelize.STRING(255),
+        allowNull: false,
+      },
+      ad_squad_id: {
+        type: Sequelize.STRING(36),
+        allowNull: false,
+        comment: "Snapchat ad squad UUID; loose FK to snapchat_ad_squads",
+      },
+      ad_account_id: {
+        type: Sequelize.STRING(36),
+        allowNull: false,
+      },
+      creative_id: {
+        type: Sequelize.STRING(36),
+        allowNull: false,
+      },
+      status: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "ACTIVE or PAUSED (Snap native)",
+      },
+      type: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "SNAP_AD",
+      },
+      review_status: {
+        type: Sequelize.STRING(50),
+        allowNull: true,
+        comment: "Mirrors Plan Q Ad.review_status (e.g. PENDING_REVIEW, APPROVED)",
+      },
+      pending_review_since: {
+        type: Sequelize.DATE,
+        allowNull: true,
+        comment: "Timestamp when ad first entered pending review (Plan Q)",
+      },
+      created_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: Sequelize.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: Sequelize.DATE,
+        allowNull: false,
+      },
+    });
+
+    await queryInterface.addIndex("snapchat_ads", ["ad_squad_id"]);
+    await queryInterface.addIndex("snapchat_ads", ["ad_account_id"]);
+    await queryInterface.addIndex("snapchat_ads", ["status"]);
+  },
+
+  down: async (queryInterface) => {
+    await queryInterface.dropTable("snapchat_ads");
+    await queryInterface.dropTable("snapchat_ad_squads");
+    await queryInterface.dropTable("tiktok_ads");
+    await queryInterface.dropTable("tiktok_adgroups");
+  },
+};