feat(ads): support a second ad network

README.md

@@ -211,9 +211,9 @@ except FopostError as err:
 | `contacts`   | `list`, `get`, `create`, `update`, `delete`, `conversations`, `import_csv`, `list_fields`, `create_field`, `update_field`, `delete_field`, `conversation_analytics` |
 | `broadcasts` | `list`, `get`, `create`, `update`, `delete`, `send`, `cancel`, `recipients` |
 | `sequences`  | `list`, `get`, `create`, `update`, `delete`, `enroll`, `unenroll`, `enrollments` |
-| `ads`        | `list`, `external`, `boostable`, `connections`, `sources`, `authorize_meta`, `delete_connection`, `boost`, `create`, `refresh`, `set_status`, `delete`, `audiences`, `create_audience`, `search_targeting`, `lead_forms`, `create_lead_form`, `leads`, `account_tree`, `create_campaign`, `get_campaign`, `update_campaign`, `delete_campaign`, `duplicate_campaign`, `create_ad_set`, `get_ad_set`, `update_ad_set`, `delete_ad_set`, `duplicate_ad_set`, `create_network_ad`, `get_network_ad`, `update_network_ad`, `delete_network_ad`, `duplicate_network_ad`, `bulk_set_status`, `creatives`, `create_creative`, `get_creative`, `delete_creative`, `get_audience`, `update_audience`, `delete_audience`, `add_audience_users`, `estimate_reach`, `insights`, `ad_insights`, `get_lead_form`, `archive_lead_form`, `leads_feed`, `lead_pages`, `subscribe_lead_page`, `unsubscribe_lead_page`, `goals`, `catalogs`, `create_catalog`, `get_catalog`, `update_catalog`, `delete_catalog`, `catalog_products`, `write_catalog_products`, `product_feeds`, `create_product_feed`, `delete_product_feed`, `feed_uploads`, `start_feed_upload`, `product_sets`, `create_product_set`, `update_product_set`, `delete_product_set`, `reach_frequency`, `create_reach_frequency`, `get_reach_frequency`, `reserve_reach_frequency`, `cancel_reach_frequency`, `library`, `partnership_creators`, `request_partnership`, `revoke_partnership`, `account_activity`, `labels`, `create_label`, `update_label`, `delete_label`, `apply_label`, `studies`, `create_study`, `get_study`, `delete_study`, `ios_campaign_limits`, `high_demand_periods`, `create_high_demand_period`, `delete_high_demand_period`, `value_rule_sets`, `create_value_rule_set`, `delete_value_rule_set` |
+| `ads`        | `list`, `external`, `boostable`, `connections`, `sources`, `providers`, `authorize`, `delete_connection`, `boost`, `create`, `refresh`, `set_status`, `delete`, `audiences`, `create_audience`, `search_targeting`, `lead_forms`, `create_lead_form`, `leads`, `account_tree`, `create_campaign`, `get_campaign`, `update_campaign`, `delete_campaign`, `duplicate_campaign`, `create_ad_set`, `get_ad_set`, `update_ad_set`, `delete_ad_set`, `duplicate_ad_set`, `create_network_ad`, `get_network_ad`, `update_network_ad`, `delete_network_ad`, `duplicate_network_ad`, `bulk_set_status`, `creatives`, `create_creative`, `get_creative`, `delete_creative`, `get_audience`, `update_audience`, `delete_audience`, `add_audience_users`, `add_audience_companies`, `estimate_reach`, `insights`, `ad_insights`, `get_lead_form`, `archive_lead_form`, `leads_feed`, `lead_pages`, `subscribe_lead_page`, `unsubscribe_lead_page`, `goals`, `catalogs`, `create_catalog`, `get_catalog`, `update_catalog`, `delete_catalog`, `catalog_products`, `write_catalog_products`, `product_feeds`, `create_product_feed`, `delete_product_feed`, `feed_uploads`, `start_feed_upload`, `product_sets`, `create_product_set`, `update_product_set`, `delete_product_set`, `reach_frequency`, `create_reach_frequency`, `get_reach_frequency`, `reserve_reach_frequency`, `cancel_reach_frequency`, `library`, `partnership_creators`, `request_partnership`, `revoke_partnership`, `account_activity`, `labels`, `create_label`, `update_label`, `delete_label`, `apply_label`, `studies`, `create_study`, `get_study`, `delete_study`, `ios_campaign_limits`, `high_demand_periods`, `create_high_demand_period`, `delete_high_demand_period`, `value_rule_sets`, `create_value_rule_set`, `delete_value_rule_set`, `bid_pricing`, `supply_forecast`, `conversion_rules`, `create_conversion_rule`, `get_conversion_rule`, `update_conversion_rule`, `delete_conversion_rule`, `attach_conversion_rule`, `detach_conversion_rule`, `conversion_metrics`, `send_conversion_events` |
 | `knowledge`  | `list`, `create`, `update`, `delete`, `sync`, `search` |
-| `ads`        | `list`, `external`, `boostable`, `connections`, `sources`, `authorize_meta`, `delete_connection`, `boost`, `create`, `refresh`, `set_status`, `delete`, `audiences`, `create_audience`, `search_targeting`, `lead_forms`, `create_lead_form`, `leads`, `account_tree`, `create_campaign`, `get_campaign`, `update_campaign`, `delete_campaign`, `duplicate_campaign`, `create_ad_set`, `get_ad_set`, `update_ad_set`, `delete_ad_set`, `duplicate_ad_set`, `create_network_ad`, `get_network_ad`, `update_network_ad`, `delete_network_ad`, `duplicate_network_ad`, `bulk_set_status`, `creatives`, `create_creative`, `get_creative`, `delete_creative`, `get_audience`, `update_audience`, `delete_audience`, `add_audience_users`, `estimate_reach`, `insights`, `ad_insights`, `get_lead_form`, `archive_lead_form`, `leads_feed`, `lead_pages`, `subscribe_lead_page`, `unsubscribe_lead_page` |
+| `ads`        | `list`, `external`, `boostable`, `connections`, `sources`, `providers`, `authorize`, `delete_connection`, `boost`, `create`, `refresh`, `set_status`, `delete`, `audiences`, `create_audience`, `search_targeting`, `lead_forms`, `create_lead_form`, `leads`, `account_tree`, `create_campaign`, `get_campaign`, `update_campaign`, `delete_campaign`, `duplicate_campaign`, `create_ad_set`, `get_ad_set`, `update_ad_set`, `delete_ad_set`, `duplicate_ad_set`, `create_network_ad`, `get_network_ad`, `update_network_ad`, `delete_network_ad`, `duplicate_network_ad`, `bulk_set_status`, `creatives`, `create_creative`, `get_creative`, `delete_creative`, `get_audience`, `update_audience`, `delete_audience`, `add_audience_users`, `add_audience_companies`, `estimate_reach`, `insights`, `ad_insights`, `get_lead_form`, `archive_lead_form`, `leads_feed`, `lead_pages`, `subscribe_lead_page`, `unsubscribe_lead_page`, `bid_pricing`, `supply_forecast`, `conversion_rules`, `create_conversion_rule`, `get_conversion_rule`, `update_conversion_rule`, `delete_conversion_rule`, `attach_conversion_rule`, `detach_conversion_rule`, `conversion_metrics`, `send_conversion_events` |
 | `google_business` | `get_location`, `update_location`, `get_attributes`, `update_attributes`, `get_menus`, `replace_menus`, `get_services`, `replace_services`, `list_media`, `add_media`, `delete_media`, `list_place_actions`, `create_place_action`, `update_place_action`, `delete_place_action`, `get_verification_options`, `start_verification`, `complete_verification`, `get_performance`, `get_search_keywords`, `assign` |
 | `validate`   | `post`, `length`, `media` |
 | `activity`   | `list` |

src/fopost/__init__.py

@@ -50,6 +50,8 @@
     AdIdentity,
     AdInsights,
     AdInsightsReport,
+    AdLibraryPage,
+    AdProvider,
     AdSet,
     AdSetNode,
     AdSource,
@@ -58,6 +60,7 @@
     Audience,
     AudienceFilter,
     AudiencesResult,
+    BidPricing,
     BlueskyLanguages,
     BoostablePost,
     Broadcast,
@@ -76,6 +79,8 @@
     ContentSignal,
     ConversationAnalytics,
     ConversationAnalyticsRow,
+    ConversionMetrics,
+    ConversionRule,
     Delivery,
     DiscordChannel,
     DiscordIdentity,
@@ -162,6 +167,7 @@
     SlackMember,
     SocialAccount,
     SparkPost,
+    SupplyForecast,
     TargetingOption,
     TelegramBotCommand,
     TelegramBotCommands,
@@ -206,6 +212,8 @@
     "AdConnection",
     "AdCreative",
     "AdInsights",
+    "AdLibraryPage",
+    "AdProvider",
     "AdInsightsReport",
     "AdSet",
     "AdSetNode",
@@ -370,5 +378,9 @@
     "LeadPageSubscription",
     "LeadsFeedPage",
     "NetworkAd",
+    "BidPricing",
+    "ConversionMetrics",
+    "ConversionRule",
     "ReachEstimate",
+    "SupplyForecast",
 ]

src/fopost/models.py

@@ -1093,10 +1093,24 @@ class AdConnection(FopostModel):
     workspace_id: str | None = None
 
 
+class AdProvider(FopostModel):
+    """An ad network from the API's registry. ``configured`` false cannot be connected yet."""
+
+    id: str
+    name: str
+    logo: str | None = None
+    configured: bool = False
+    connect_methods: list[str] = []
+    capabilities: dict[str, bool] = {}
+    targeting_facets: list[str] = []
+    tracking_macros: list[dict[str, Any]] = []
+
+
 class AdSource(FopostModel):
     """A connection with the ad accounts and Pages its grant reaches."""
 
     connection_id: str
+    provider: str | None = None
     name: str
     workspace_id: str | None = None
     ad_accounts: list[dict[str, Any]] = []
@@ -1334,6 +1348,49 @@ class ReachEstimate(FopostModel):
     ready: bool = False
 
 
+class BidPricing(FopostModel):
+    """What the auction costs, in minor units of the ad account currency."""
+
+    currency: str | None = None
+    suggested_bid_minor: int | None = None
+    min_bid_minor: int | None = None
+    max_bid_minor: int | None = None
+    daily_budget_floor_minor: int | None = None
+
+
+class SupplyForecast(FopostModel):
+    """What an audience would deliver at a budget, over the network's own window."""
+
+    currency: str | None = None
+    impressions: int | None = None
+    clicks: int | None = None
+    spend_minor: int | None = None
+    window_days: int | None = None
+    ready: bool = False
+
+
+class ConversionRule(FopostModel):
+    id: str
+    name: str
+    type: str | None = None
+    attribution: str | None = None
+    post_click_window_days: int = 30
+    view_through_window_days: int = 7
+    value_minor: int | None = None
+    currency: str | None = None
+    enabled: bool = True
+    created_at: str | None = None
+    campaign_ids: list[str] = []
+
+
+class ConversionMetrics(FopostModel):
+    conversions: int = 0
+    post_click_conversions: int = 0
+    view_through_conversions: int = 0
+    value_minor: int = 0
+    cost_per_conversion_minor: int | None = None
+
+
 class LeadFormDetail(LeadForm):
     page_id: str | None = None
     privacy_policy_url: str | None = None