agrs-sequelize-sdk 1.4.19 → 1.4.22

package/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");
+  },
+};

package/models/AICampaignQueue.js

@@ -98,6 +98,12 @@ module.exports = (sequelize, DataTypes) => {
           field: "platform",
           comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
         },
+        group_id: {
+          type: DataTypes.UUID,
+          allowNull: true,
+          field: "group_id",
+          comment: "Groups rows created by a single multi-platform fanout request",
+        },
       },
       {
         tableName: "ai_campaign_queue",
@@ -127,6 +133,9 @@ module.exports = (sequelize, DataTypes) => {
           {
             fields: ["preset_id"],
           },
+          {
+            fields: ["group_id"],
+          },
         ],
       }
     );

package/models/Ad.js

@@ -139,6 +139,18 @@ module.exports = (sequelize, DataTypes) => {
         defaultValue: "fb",
         comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
       },
+      review_status: {
+        type: DataTypes.STRING,
+        allowNull: true,
+        comment:
+          "Local review status mirror (e.g. PENDING_REVIEW after copy/URL edit on Snap). Cleared by status sync.",
+      },
+      pending_review_since: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        comment:
+          "Timestamp when ad was optimistically flipped to PENDING_REVIEW after a triggering edit. Cleared when upstream review settles.",
+      },
     },
     {
       tableName: "Ad",

package/models/AdPerformance.js

@@ -88,6 +88,10 @@ module.exports = (sequelize, DataTypes) => {
         {
           fields: ["AdID"], // Index on AdID for faster join
         },
+        {
+          name: "AdPerformance_platform_Date_idx",
+          fields: ["platform", "Date"],
+        },
       ],
     }
   );

package/models/AdsetPerformance.js

@@ -115,6 +115,11 @@ module.exports = (sequelize, DataTypes) => {
           fields: ["AdSetID", "Date"],
           // Composite unique index to ensure one record per AdSet per date
         },
+        {
+          name: "AdSetPerformance_platform_Date_idx",
+          fields: ["platform", "Date"],
+          // Composite index for platform-scoped date range queries
+        },
       ],
     }
   );

package/models/CampaignCreationLog.js

@@ -114,6 +114,13 @@ module.exports = (sequelize, DataTypes) => {
         allowNull: true,
         comment: "Platform (e.g., Facebook)",
       },
+      platform_code: {
+        type: DataTypes.ENUM("fb", "tt", "snp"),
+        allowNull: false,
+        defaultValue: "fb",
+        comment:
+          "Canonical ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+      },
       bid_strategy: {
         type: DataTypes.STRING(100),
         allowNull: true,
@@ -262,6 +269,11 @@ module.exports = (sequelize, DataTypes) => {
           fields: ["page_code"],
           comment: "For page code filtering",
         },
+        {
+          name: "idx_campaign_logs_platform_code",
+          fields: ["platform_code"],
+          comment: "For canonical platform filtering",
+        },
         {
           fields: ["process_id"],
         },

package/models/CampaignCreationLogV2.js

@@ -109,6 +109,13 @@ module.exports = (sequelize, DataTypes) => {
         type: DataTypes.STRING(50),
         allowNull: true,
       },
+      platform_code: {
+        type: DataTypes.ENUM("fb", "tt", "snp"),
+        allowNull: false,
+        defaultValue: "fb",
+        comment:
+          "Canonical ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+      },
       language: {
         type: DataTypes.STRING(50),
         allowNull: true,
@@ -277,6 +284,7 @@ module.exports = (sequelize, DataTypes) => {
         { fields: ["account_id", "status"] },
         { fields: ["vertical", "feed_provider"] },
         { fields: ["details"], using: "gin" },
+        { fields: ["platform_code"] },
       ],
     }
   );

package/models/CanonicalInsights.js

@@ -0,0 +1,68 @@
+module.exports = (sequelize, DataTypes) => {
+  const CanonicalInsights = sequelize.define(
+    "CanonicalInsights",
+    {
+      id: {
+        type: DataTypes.BIGINT,
+        primaryKey: true,
+        autoIncrement: true,
+      },
+      platform: {
+        type: DataTypes.ENUM("fb", "tt", "snp"),
+        allowNull: false,
+        comment: "Ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+      },
+      entity_type: {
+        type: DataTypes.ENUM("campaign", "adset", "ad"),
+        allowNull: false,
+      },
+      entity_id: {
+        type: DataTypes.STRING(64),
+        allowNull: false,
+      },
+      date: {
+        type: DataTypes.DATEONLY,
+        allowNull: false,
+      },
+      impressions: {
+        type: DataTypes.BIGINT,
+        defaultValue: 0,
+      },
+      clicks: {
+        type: DataTypes.BIGINT,
+        defaultValue: 0,
+      },
+      spend: {
+        type: DataTypes.DECIMAL(14, 4),
+        defaultValue: 0,
+      },
+      conversions: {
+        type: DataTypes.BIGINT,
+        defaultValue: 0,
+      },
+      revenue: {
+        type: DataTypes.DECIMAL(14, 4),
+        defaultValue: 0,
+      },
+      raw_payload: {
+        type: DataTypes.JSONB,
+        allowNull: true,
+      },
+    },
+    {
+      tableName: "canonical_insights",
+      indexes: [
+        {
+          unique: true,
+          name: "canonical_insights_unique_per_entity_date",
+          fields: ["platform", "entity_type", "entity_id", "date"],
+        },
+        {
+          fields: ["platform", "date"],
+        },
+      ],
+    }
+  );
+
+  return CanonicalInsights;
+};

package/models/RSOCFeedCampaign.js

@@ -160,6 +160,12 @@ module.exports = (sequelize, DataTypes) => {
         type: DataTypes.STRING,
         allowNull: false,
       },
+      platform_code: {
+        type: DataTypes.ENUM("fb", "tt", "snp"),
+        allowNull: false,
+        defaultValue: "fb",
+        comment: "Canonical ad platform identifier: fb=Facebook, tt=TikTok, snp=Snapchat",
+      },
       mediaBuyer: {
         type: DataTypes.STRING,
         allowNull: true,

package/models/SnapchatAd.js

@@ -0,0 +1,69 @@
+module.exports = (sequelize, DataTypes) =>
+  sequelize.define(
+    "SnapchatAd",
+    {
+      id: {
+        type: DataTypes.STRING(36),
+        primaryKey: true,
+        comment: "Snapchat ad UUID",
+      },
+      name: {
+        type: DataTypes.STRING(255),
+        allowNull: false,
+      },
+      ad_squad_id: {
+        type: DataTypes.STRING(36),
+        allowNull: false,
+        comment: "Snapchat ad squad UUID; loose FK to snapchat_ad_squads",
+      },
+      ad_account_id: {
+        type: DataTypes.STRING(36),
+        allowNull: false,
+      },
+      creative_id: {
+        type: DataTypes.STRING(36),
+        allowNull: false,
+      },
+      status: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+        comment: "ACTIVE or PAUSED (Snap native)",
+      },
+      type: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+        comment: "SNAP_AD",
+      },
+      review_status: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+        comment: "Mirrors Plan Q Ad.review_status (e.g. PENDING_REVIEW, APPROVED)",
+      },
+      pending_review_since: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        comment: "Timestamp when ad first entered pending review (Plan Q)",
+      },
+      created_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+    },
+    {
+      tableName: "snapchat_ads",
+      timestamps: false,
+      indexes: [
+        { fields: ["ad_squad_id"] },
+        { fields: ["ad_account_id"] },
+        { fields: ["status"] },
+      ],
+    },
+  );

package/models/SnapchatAdSquad.js

@@ -0,0 +1,92 @@
+module.exports = (sequelize, DataTypes) =>
+  sequelize.define(
+    "SnapchatAdSquad",
+    {
+      id: {
+        type: DataTypes.STRING(36),
+        primaryKey: true,
+        comment: "Snapchat ad squad UUID",
+      },
+      name: {
+        type: DataTypes.STRING(255),
+        allowNull: false,
+      },
+      campaign_id: {
+        type: DataTypes.STRING(36),
+        allowNull: false,
+        comment: "Snapchat campaign UUID; loose FK to snapchat_campaigns",
+      },
+      ad_account_id: {
+        type: DataTypes.STRING(36),
+        allowNull: false,
+      },
+      status: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+        comment: "ACTIVE or PAUSED (Snap native)",
+      },
+      type: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+        comment: "SNAP_ADS",
+      },
+      bid_strategy: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+      },
+      optimization_goal: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+      },
+      billing_event: {
+        type: DataTypes.STRING(50),
+        allowNull: true,
+      },
+      placement_v2: {
+        type: DataTypes.JSONB,
+        allowNull: true,
+        comment: "Snap placement_v2 config (e.g. {config:'AUTOMATIC', ...})",
+      },
+      daily_budget_micro: {
+        type: DataTypes.BIGINT,
+        allowNull: true,
+      },
+      bid_micro: {
+        type: DataTypes.BIGINT,
+        allowNull: true,
+      },
+      targeting: {
+        type: DataTypes.JSONB,
+        allowNull: true,
+      },
+      start_time: {
+        type: DataTypes.DATE,
+        allowNull: true,
+      },
+      end_time: {
+        type: DataTypes.DATE,
+        allowNull: true,
+      },
+      created_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+      updated_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+      },
+      synced_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+    },
+    {
+      tableName: "snapchat_ad_squads",
+      timestamps: false,
+      indexes: [
+        { fields: ["campaign_id"] },
+        { fields: ["ad_account_id"] },
+        { fields: ["status"] },
+      ],
+    },
+  );