whop_sdk 0.0.39 → 0.0.41

data/rbi/whop_sdk/resources/ad_groups.rbi

@@ -2,121 +2,308 @@
 
 module WhopSDK
   module Resources
-    # Ad groups
+    # An Ad Group sits inside an
+    # [ad campaign](/api-reference/beta/ad-campaigns/ad-campaign) and controls
+    # delivery for [ads](/api-reference/beta/ads/ad). It sets the audience,
+    # placements, schedule, budget, and optimization goal for its ads.
+    #
+    # Use the Ad Groups API to create ad groups in campaigns, list or retrieve
+    # targeting and delivery settings, update budgets or targeting, delete groups that
+    # should stop running, and pause or resume delivery.
     class AdGroups
-      # Retrieves a single ad group by its unique identifier.
-      #
-      # Required permissions:
-      #
-      # - `ad_campaign:basic:read`
+      # Creates an ad group (ad set) in a campaign.
+      sig do
+        params(
+          ad_campaign_id: String,
+          audiences: T.anything,
+          bid_type: WhopSDK::AdGroupCreateParams::BidType::OrSymbol,
+          budget_amount: Float,
+          budget_type: WhopSDK::AdGroupCreateParams::BudgetType::OrSymbol,
+          conversion_event:
+            T.nilable(
+              T.any(
+                WhopSDK::AdGroupCreateParams::ConversionEvent::OrSymbol,
+                String
+              )
+            ),
+          conversion_location:
+            WhopSDK::AdGroupCreateParams::ConversionLocation::OrSymbol,
+          demographics: T.anything,
+          desired_cost_per_result: Float,
+          devices: T.anything,
+          dynamic_creative: T::Boolean,
+          ends_at: String,
+          frequency_cap: T.anything,
+          languages: T::Array[String],
+          message_apps:
+            T::Array[WhopSDK::AdGroupCreateParams::MessageApp::OrSymbol],
+          minimum_daily_spend: Float,
+          optimization_goal: String,
+          placements: T.anything,
+          regions: T.anything,
+          starts_at: String,
+          status: WhopSDK::AdGroupCreateParams::Status::OrSymbol,
+          title: String,
+          request_options: WhopSDK::RequestOptions::OrHash
+        ).returns(WhopSDK::AdGroup)
+      end
+      def create(
+        # The ad campaign to create the ad group in.
+        ad_campaign_id:,
+        # Saved-audience targeting: { include, exclude } arrays of audience IDs.
+        # Incompatible with demographics.automatic (Advantage+).
+        audiences: nil,
+        # Bid strategy.
+        bid_type: nil,
+        # Ad-set budget in dollars (ABO only; omit under CBO).
+        budget_amount: nil,
+        # Whether the budget is daily or lifetime.
+        budget_type: nil,
+        # The pixel event optimized for. A standard event, or any custom pixel event name.
+        conversion_event: nil,
+        # Where results happen: website (conversions), profile (IG/FB engagement),
+        # messaging (DM), on_ad (engagement on the ad, surface follows the optimization
+        # goal), or the lead destinations (instant_forms, instant_forms_and_messenger,
+        # website_and_instant_forms). The lead form itself is set on the ad.
+        conversion_location: nil,
+        # Demographic targeting: { automatic, minimum_age, maximum_age, gender }.
+        demographics: nil,
+        # Target/cap cost for average_target / maximum_target.
+        desired_cost_per_result: nil,
+        # Device targeting: { platforms, operating_systems: [{ os, minimum_version }] }.
+        devices: nil,
+        # Run Meta dynamic (Advantage+) creative for this ad set. Set at creation;
+        # immutable afterward.
+        dynamic_creative: nil,
+        # Schedule end, ISO 8601.
+        ends_at: nil,
+        # { maximum_impressions, per_days } — only valid for reach optimization.
+        frequency_cap: nil,
+        # Languages to target as ISO 639 codes (e.g. en, es). Empty/omitted = all
+        # languages.
+        languages: nil,
+        # Required when conversion_location is messaging: which apps to message on.
+        # Combinations map to the matching Meta destination.
+        message_apps: nil,
+        # Daily spend floor within the budget.
+        minimum_daily_spend: nil,
+        # What the ad group optimizes for (e.g. conversions, link_clicks, reach).
+        optimization_goal: nil,
+        # 'automatic' (Advantage+) or a list of { platform, positions }. Omit positions to
+        # target all of a platform's.
+        #
+        # Valid positions per platform:
+        #
+        # - `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`,
+        #   `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`,
+        #   `facebook_reels_overlay`, `biz_disco_feed`
+        # - `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`,
+        #   `profile_feed`, `profile_reels`, `ig_search`
+        # - `messenger`: `story`
+        # - `audience_network`: `classic`, `rewarded_video`
+        # - `threads`: `threads_stream`
+        # - `whatsapp`: `status`
+        placements: nil,
+        # Geo targeting: { include / exclude: { countries (ISO 3166-1), regions
+        # (states/provinces as ISO 3166-2, e.g. US-CA), cities (keyed), zips } }.
+        regions: nil,
+        # Schedule start, ISO 8601.
+        starts_at: nil,
+        # Initial status (default: active).
+        status: nil,
+        # The display name of the ad group.
+        title: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves a single ad group.
       sig do
         params(
           id: String,
+          stats_from: String,
+          stats_to: String,
+          time_zone: String,
           request_options: WhopSDK::RequestOptions::OrHash
-        ).returns(WhopSDK::Models::AdGroupRetrieveResponse)
+        ).returns(WhopSDK::AdGroup)
       end
       def retrieve(
-        # The unique identifier of the ad group.
+        # The ad group ID.
         id,
+        # Start of the stats window.
+        stats_from: nil,
+        # End of the stats window.
+        stats_to: nil,
+        # IANA timezone the stats window is interpreted in. Defaults to UTC.
+        time_zone: nil,
         request_options: {}
       )
       end
 
-      # Updates an existing ad group.
-      #
-      # Required permissions:
-      #
-      # - `ad_campaign:update`
-      # - `ad_campaign:basic:read`
+      # Updates an ad group's editable fields. Only the keys you send are changed.
       sig do
         params(
           id: String,
-          budget: T.nilable(Float),
-          budget_type:
-            T.nilable(WhopSDK::AdGroupUpdateParams::BudgetType::OrSymbol),
-          config: T.nilable(WhopSDK::AdGroupUpdateParams::Config::OrHash),
-          daily_budget: T.nilable(Float),
-          name: T.nilable(String),
-          platform_config:
-            T.nilable(WhopSDK::AdGroupUpdateParams::PlatformConfig::OrHash),
-          status: T.nilable(WhopSDK::AdGroupUpdateParams::Status::OrSymbol),
+          audiences: T.anything,
+          bid_type: WhopSDK::AdGroupUpdateParams::BidType::OrSymbol,
+          budget_amount: Float,
+          budget_type: WhopSDK::AdGroupUpdateParams::BudgetType::OrSymbol,
+          conversion_event:
+            T.nilable(
+              T.any(
+                WhopSDK::AdGroupUpdateParams::ConversionEvent::OrSymbol,
+                String
+              )
+            ),
+          conversion_location:
+            WhopSDK::AdGroupUpdateParams::ConversionLocation::OrSymbol,
+          demographics: T.anything,
+          desired_cost_per_result: Float,
+          devices: T.anything,
+          ends_at: String,
+          frequency_cap: T.anything,
+          languages: T::Array[String],
+          message_apps:
+            T::Array[WhopSDK::AdGroupUpdateParams::MessageApp::OrSymbol],
+          minimum_daily_spend: Float,
+          optimization_goal: String,
+          placements: T.anything,
+          regions: T.anything,
+          starts_at: String,
+          status: WhopSDK::AdGroupUpdateParams::Status::OrSymbol,
+          title: String,
           request_options: WhopSDK::RequestOptions::OrHash
-        ).returns(WhopSDK::Models::AdGroupUpdateResponse)
+        ).returns(WhopSDK::AdGroup)
       end
       def update(
-        # The unique identifier of the ad group to update.
+        # The ad group ID.
         id,
-        # Budget amount in dollars.
-        budget: nil,
-        # The budget type for an ad campaign or ad group.
+        # Saved-audience targeting: { include, exclude } arrays of audience IDs.
+        # Incompatible with demographics.automatic (Advantage+).
+        audiences: nil,
+        # Bid strategy.
+        bid_type: nil,
+        # Ad-set budget in dollars (ABO only; omit under CBO).
+        budget_amount: nil,
+        # Whether the budget is daily or lifetime.
         budget_type: nil,
-        # Unified ad group configuration (bidding, optimization, targeting).
-        config: nil,
-        # Daily budget in dollars.
-        daily_budget: nil,
-        # Human-readable ad group name.
-        name: nil,
-        # Platform-specific ad group configuration.
-        platform_config: nil,
-        # The status of an external ad group.
+        # The pixel event optimized for. A standard event, or any custom pixel event name.
+        conversion_event: nil,
+        # Where results happen: website (conversions), profile (IG/FB engagement),
+        # messaging (DM), on_ad (engagement on the ad, surface follows the optimization
+        # goal), or the lead destinations (instant_forms, instant_forms_and_messenger,
+        # website_and_instant_forms). The lead form itself is set on the ad.
+        conversion_location: nil,
+        # Demographic targeting: { automatic, minimum_age, maximum_age, gender }.
+        demographics: nil,
+        # Target/cap cost for average_target / maximum_target.
+        desired_cost_per_result: nil,
+        # Device targeting: { platforms, operating_systems: [{ os, minimum_version }] }.
+        devices: nil,
+        # Schedule end, ISO 8601.
+        ends_at: nil,
+        # { maximum_impressions, per_days } — only valid for reach optimization.
+        frequency_cap: nil,
+        # Languages to target as ISO 639 codes (e.g. en, es). Empty/omitted = all
+        # languages.
+        languages: nil,
+        # Required when conversion_location is messaging: which apps to message on.
+        # Combinations map to the matching Meta destination.
+        message_apps: nil,
+        # Daily spend floor within the budget.
+        minimum_daily_spend: nil,
+        # What the ad group optimizes for (e.g. conversions, link_clicks, reach).
+        optimization_goal: nil,
+        # 'automatic' (Advantage+) or a list of { platform, positions }. Omit positions to
+        # target all of a platform's.
+        #
+        # Valid positions per platform:
+        #
+        # - `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`,
+        #   `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`,
+        #   `facebook_reels_overlay`, `biz_disco_feed`
+        # - `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`,
+        #   `profile_feed`, `profile_reels`, `ig_search`
+        # - `messenger`: `story`
+        # - `audience_network`: `classic`, `rewarded_video`
+        # - `threads`: `threads_stream`
+        # - `whatsapp`: `status`
+        placements: nil,
+        # Geo targeting: { include / exclude: { countries (ISO 3166-1), regions
+        # (states/provinces as ISO 3166-2, e.g. US-CA), cities (keyed), zips } }.
+        regions: nil,
+        # Schedule start, ISO 8601.
+        starts_at: nil,
+        # Initial status (default: active).
         status: nil,
+        # The display name of the ad group.
+        title: nil,
         request_options: {}
       )
       end
 
-      # Returns a paginated list of ad groups scoped by campaign or company, with
-      # optional filtering by status and creation date.
-      #
-      # Required permissions:
-      #
-      # - `ad_campaign:basic:read`
+      # Lists ad groups for the account, newest first.
       sig do
         params(
-          after: T.nilable(String),
-          before: T.nilable(String),
-          campaign_id: T.nilable(String),
-          company_id: T.nilable(String),
-          created_after: T.nilable(Time),
-          created_before: T.nilable(Time),
-          first: T.nilable(Integer),
-          last: T.nilable(Integer),
-          query: T.nilable(String),
-          status: T.nilable(WhopSDK::AdGroupListParams::Status::OrSymbol),
+          account_id: String,
+          ad_campaign_id: String,
+          after: String,
+          before: String,
+          created_after: String,
+          created_before: String,
+          direction: WhopSDK::AdGroupListParams::Direction::OrSymbol,
+          first: Integer,
+          last: Integer,
+          order: WhopSDK::AdGroupListParams::Order::OrSymbol,
+          query: String,
+          stats_from: String,
+          stats_to: String,
+          status: String,
+          time_zone: String,
           request_options: WhopSDK::RequestOptions::OrHash
-        ).returns(
-          WhopSDK::Internal::CursorPage[WhopSDK::Models::AdGroupListResponse]
-        )
+        ).returns(WhopSDK::Internal::CursorPage[WhopSDK::AdGroup])
       end
       def list(
-        # Returns the elements in the list that come after the specified cursor.
+        # Account whose ad groups to list. Defaults to the authenticated account.
+        account_id: nil,
+        # Filter to ad groups in this campaign.
+        ad_campaign_id: nil,
+        # Cursor to fetch the page after (from page_info.end_cursor).
         after: nil,
-        # Returns the elements in the list that come before the specified cursor.
+        # Cursor to fetch the page before (from page_info.start_cursor).
         before: nil,
-        # Filter by campaign. Provide exactly one of campaign_id or company_id.
-        campaign_id: nil,
-        # Filter by company. Provide exactly one of campaign_id or company_id.
-        company_id: nil,
         # Only return ad groups created after this timestamp.
         created_after: nil,
         # Only return ad groups created before this timestamp.
         created_before: nil,
-        # Returns the first _n_ elements from the list.
+        # The sort direction. Defaults to desc.
+        direction: nil,
+        # The number of ad groups to return.
         first: nil,
-        # Returns the last _n_ elements from the list.
+        # The number of ad groups to return from the end of the range.
         last: nil,
-        # Case-insensitive substring match against the ad group name.
+        # The field to sort by. Defaults to created_at. Stat columns (spend, impressions,
+        # …) rank over the stats_from/stats_to window across the whole list, not just the
+        # current page. results, cost_per_result and return_on_ad_spend rank by the same
+        # Whop pixel-attributed values the response reports.
+        order: nil,
+        # Filter ad groups by a title or ID substring.
         query: nil,
-        # The status of an external ad group.
+        # Start of the stats window. Defaults to all-time.
+        stats_from: nil,
+        # End of the stats window. Defaults to now.
+        stats_to: nil,
+        # Filter to a status (active, paused, in_review, rejected).
         status: nil,
+        # IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare
+        # stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to
+        # UTC.
+        time_zone: nil,
         request_options: {}
       )
       end
 
-      # Soft-deletes an ad group.
-      #
-      # Required permissions:
-      #
-      # - `ad_campaign:update`
+      # Deletes an ad group. Returns true on success.
       sig do
         params(
           id: String,
@@ -124,7 +311,35 @@ module WhopSDK
         ).returns(T::Boolean)
       end
       def delete(
-        # The unique identifier of the ad group to delete.
+        # The ad group ID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Pauses delivery of an ad group.
+      sig do
+        params(
+          id: String,
+          request_options: WhopSDK::RequestOptions::OrHash
+        ).returns(WhopSDK::AdGroup)
+      end
+      def pause(
+        # The ad group ID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Resumes delivery of a paused ad group.
+      sig do
+        params(
+          id: String,
+          request_options: WhopSDK::RequestOptions::OrHash
+        ).returns(WhopSDK::AdGroup)
+      end
+      def unpause(
+        # The ad group ID.
         id,
         request_options: {}
       )

data/rbi/whop_sdk/resources/ad_reports.rbi

@@ -2,11 +2,12 @@
 
 module WhopSDK
   module Resources
-    # Ad reports
     class AdReports
-      # Performance report for an ad campaign, ad group, or ad. Returns aggregate totals
-      # and an optional per-day breakdown. Exactly one of `adCampaignId`, `adGroupId`,
-      # or `adId` must be provided.
+      # Performance report for a company, ad campaigns, ad groups, or ads. Always
+      # returns aggregate `summary` totals summed across the scope. Set `granularity` to
+      # additionally get a time series, or set `breakdown` (`campaign`/`ad_group`/`ad`)
+      # to additionally get per-entity rows inside the requested scope. Exactly one of
+      # `companyId`, `adCampaignIds`, `adGroupIds`, or `adIds` must be provided.
       #
       # Required permissions:
       #
@@ -15,11 +16,14 @@ module WhopSDK
         params(
           from: Time,
           to: Time,
-          ad_campaign_id: T.nilable(String),
-          ad_group_id: T.nilable(String),
-          ad_id: T.nilable(String),
+          ad_campaign_ids: T.nilable(T::Array[String]),
+          ad_group_ids: T.nilable(T::Array[String]),
+          ad_ids: T.nilable(T::Array[String]),
+          breakdown:
+            T.nilable(WhopSDK::AdReportRetrieveParams::Breakdown::OrSymbol),
+          company_id: T.nilable(String),
           currency: T.nilable(String),
-          include_daily: T.nilable(T::Boolean),
+          granularity: T.nilable(WhopSDK::Granularities::OrSymbol),
           request_options: WhopSDK::RequestOptions::OrHash
         ).returns(WhopSDK::Models::AdReportRetrieveResponse)
       end
@@ -28,20 +32,26 @@ module WhopSDK
         from:,
         # Inclusive end of the reporting window.
         to:,
-        # The unique identifier of an ad campaign. Mutually exclusive with `adGroupId` and
-        # `adId`.
-        ad_campaign_id: nil,
-        # The unique identifier of an ad group. Mutually exclusive with `adCampaignId` and
-        # `adId`.
-        ad_group_id: nil,
-        # The unique identifier of an ad. Mutually exclusive with `adCampaignId` and
-        # `adGroupId`.
-        ad_id: nil,
+        # Scope the report to these ad campaigns (max 100); stats are summed across them.
+        # Mutually exclusive with `companyId`, `adGroupIds`, and `adIds`.
+        ad_campaign_ids: nil,
+        # Scope the report to these ad groups (max 100); stats are summed across them.
+        # Mutually exclusive with `companyId`, `adCampaignIds`, and `adIds`.
+        ad_group_ids: nil,
+        # Scope the report to these ads (max 100); stats are summed across them. Mutually
+        # exclusive with `companyId`, `adCampaignIds`, and `adGroupIds`.
+        ad_ids: nil,
+        # Entity level to group an ad report by.
+        breakdown: nil,
+        # The unique identifier of a company. Mutually exclusive with `adCampaignIds`,
+        # `adGroupIds`, and `adIds`. Use with `breakdown` to fan out across every
+        # campaign, ad group, or ad in the company without paging.
+        company_id: nil,
         # ISO 4217 currency code to report `spend` in. Defaults to the company's ads
         # reporting currency.
         currency: nil,
-        # When true, includes a per-day breakdown alongside the summary.
-        include_daily: nil,
+        # Bucket size for external ad stat rows.
+        granularity: nil,
         request_options: {}
       )
       end