feat(ads): catalogs, reach and frequency, the ad archive and account settings

README.md

@@ -211,7 +211,7 @@ 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` |
+| `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` |
 | `knowledge`  | `list`, `create`, `update`, `delete`, `sync`, `search` |
 | `validate`   | `post`, `length`, `media` |
 

src/fopost/models.py

@@ -100,6 +100,26 @@
     "LeadPageSubscription",
     "LeadsFeedPage",
     "NetworkAd",
+    "AdActivity",
+    "AdActivityResult",
+    "AdLabel",
+    "AdLibraryEntry",
+    "AdLibraryPage",
+    "AdStudy",
+    "CatalogBatchResult",
+    "CatalogProduct",
+    "CatalogProductsPage",
+    "HighDemandPeriod",
+    "IosCampaignLimits",
+    "PartnershipCreator",
+    "ProductCatalog",
+    "ProductCatalogsResult",
+    "ProductFeed",
+    "ProductFeedUpload",
+    "ProductSet",
+    "ReachFrequencyPrediction",
+    "ReachFrequencyResult",
+    "ValueRuleSet",
     "ReachEstimate",
 ]
 
@@ -1099,6 +1119,198 @@ class LeadPageSubscription(FopostModel):
     backfilled: int = 0
 
 
+# ─── Product catalogs ──────────────────────────────────────────────
+
+
+class ProductCatalog(FopostModel):
+    """A product catalog on the connection's business portfolio, read live."""
+
+    id: str
+    name: str
+    vertical: str | None = None
+    product_count: int | None = None
+
+
+class ProductCatalogsResult(FopostModel):
+    catalogs: list[ProductCatalog] = []
+    workspace_id: str | None = None
+
+
+class CatalogProduct(FopostModel):
+    id: str
+    #: Your own key for the product.
+    retailer_id: str
+    name: str
+    description: str | None = None
+    availability: str | None = None
+    condition: str | None = None
+    #: Minor units of ``currency``.
+    price_minor: int | None = None
+    currency: str | None = None
+    image_url: str | None = None
+    url: str | None = None
+
+
+class CatalogProductsPage(FopostModel):
+    products: list[CatalogProduct] = []
+    next_cursor: str | None = None
+
+
+class CatalogBatchResult(FopostModel):
+    handles: list[str] = []
+    #: Products sent in this batch.
+    accepted: int = 0
+
+
+class ProductFeed(FopostModel):
+    id: str
+    name: str
+    #: Set when the network fetches the file on a schedule.
+    url: str | None = None
+    schedule: str | None = None
+    created_at: str | None = None
+
+
+class ProductFeedUpload(FopostModel):
+    id: str
+    started_at: str | None = None
+    ended_at: str | None = None
+    status: str | None = None
+    error_count: int | None = None
+    warning_count: int | None = None
+
+
+class ProductSet(FopostModel):
+    """The slice of a catalog one catalog ad runs from."""
+
+    id: str
+    name: str
+    product_count: int | None = None
+    #: The network's own product-set filter.
+    filter: dict[str, Any] | None = None
+
+
+# ─── Reach and frequency ───────────────────────────────────────────
+
+
+class ReachFrequencyPrediction(FopostModel):
+    id: str
+    name: str | None = None
+    status: str | None = None
+    reach: int | None = None
+    impressions: int | None = None
+    frequency_cap: int | None = None
+    #: Account currency, minor units.
+    budget_minor: int | None = None
+    start_at: str | None = None
+    end_at: str | None = None
+    #: True once the prediction holds inventory.
+    reserved: bool = False
+
+
+class ReachFrequencyResult(FopostModel):
+    predictions: list[ReachFrequencyPrediction] = []
+    workspace_id: str | None = None
+
+
+# ─── Ad Library ────────────────────────────────────────────────────
+
+
+class AdLibraryEntry(FopostModel):
+    """One public archive entry. Read live on every search and stored nowhere."""
+
+    id: str
+    page_id: str | None = None
+    page_name: str | None = None
+    bodies: list[str] = []
+    titles: list[str] = []
+    link_urls: list[str] = []
+    snapshot_url: str | None = None
+    publisher_platforms: list[str] = []
+    started_at: str | None = None
+    ended_at: str | None = None
+    #: Only on the archive's disclosure entries.
+    currency: str | None = None
+    spend_lower: int | None = None
+    spend_upper: int | None = None
+    impressions_lower: int | None = None
+    impressions_upper: int | None = None
+
+
+class AdLibraryPage(FopostModel):
+    entries: list[AdLibraryEntry] = []
+    next_cursor: str | None = None
+
+
+# ─── Partnership ads ───────────────────────────────────────────────
+
+
+class PartnershipCreator(FopostModel):
+    """A creator who allowlisted this advertiser for partnership ads."""
+
+    id: str
+    username: str | None = None
+    name: str | None = None
+    status: str | None = None
+    permissions: list[str] = []
+
+
+# ─── Ad account settings ───────────────────────────────────────────
+
+
+class AdActivity(FopostModel):
+    id: str
+    event_type: str | None = None
+    actor_name: str | None = None
+    object_name: str | None = None
+    object_type: str | None = None
+    extra_data: str | None = None
+    created_at: str | None = None
+
+
+class AdActivityResult(FopostModel):
+    activity: list[AdActivity] = []
+    workspace_id: str | None = None
+
+
+class AdLabel(FopostModel):
+    id: str
+    name: str
+    created_at: str | None = None
+
+
+class AdStudy(FopostModel):
+    id: str
+    name: str
+    description: str | None = None
+    type: str | None = None
+    status: str | None = None
+    start_at: str | None = None
+    end_at: str | None = None
+
+
+class IosCampaignLimits(FopostModel):
+    #: How many iOS 14 campaigns the account may run at once.
+    limit: int | None = None
+    used: int | None = None
+    app_id: str | None = None
+
+
+class HighDemandPeriod(FopostModel):
+    id: str
+    start_at: str | None = None
+    end_at: str | None = None
+    budget_value: float | None = None
+    budget_value_type: str | None = None
+
+
+class ValueRuleSet(FopostModel):
+    id: str
+    name: str
+    status: str | None = None
+    rules: list[dict[str, Any]] = []
+
+
 class ContentSignal(FopostModel):
     level: Literal["info", "warn"] | str
     code: str