postboost 1.0.0 → 1.8.0

data/lib/postboost/api/analytics_api.rb

@@ -0,0 +1,425 @@
+=begin
+#PostBoost API
+
+#The PostBoost REST API lets you publish, schedule, and analyze social media posts across 12+ platforms from a single integration. No OAuth apps to maintain — PostBoost handles platform authorization for you.  ## Base URL All workspace-scoped endpoints are prefixed with `/{workspaceUuid}`. Panel/admin endpoints are prefixed with `/panel`.  ## Plan access Every workspace-scoped endpoint returns `403` when the workspace's plan does not include API access (capability `api`).  ## Dates and times Post dates and times (`date`, `time`, `accounts_schedule`) are read in the request's `timezone` when one is given, otherwise in the workspace timezone.  ## Authentication All requests require a Bearer token in the `Authorization` header. Generate tokens in your PostBoost dashboard under **Settings → Access Tokens**.  ``` Authorization: Bearer YOUR_API_TOKEN ``` 
+
+The version of the OpenAPI document: 1.8.0
+Contact: hi@postboost.co
+Generated by: https://openapi-generator.tech
+Generator version: 7.9.0
+
+=end
+
+require 'cgi'
+
+module PostBoost
+  class AnalyticsApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Get account analytics
+    # Analytics for one account. `type` selects one of the tabs the account supports (listed in `tabs` of the response); returns `422` when the account does not support analytics.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param account_uuid [String] UUID of the social media account.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :period Preset reporting period. Ignored when `date_from` and `date_to` are given. (default to 'this_month')
+    # @option opts [Date] :date_from Start of a custom range (Y-m-d). Required with `date_to`; the range may span at most 366 days.
+    # @option opts [Date] :date_to End of a custom range (Y-m-d). Required with `date_from`; must not be before it.
+    # @option opts [String] :type Analytics tab. Defaults to the account's default tab.
+    # @option opts [Integer] :page Page for list-style tabs (for example per-post metrics). (default to 1)
+    # @option opts [Integer] :per_page 
+    # @option opts [String] :sort_by 
+    # @option opts [String] :sort_dir  (default to 'desc')
+    # @return [AccountAnalytics]
+    def get_account_analytics(workspace_uuid, account_uuid, opts = {})
+      data, _status_code, _headers = get_account_analytics_with_http_info(workspace_uuid, account_uuid, opts)
+      data
+    end
+
+    # Get account analytics
+    # Analytics for one account. `type` selects one of the tabs the account supports (listed in `tabs` of the response); returns `422` when the account does not support analytics.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param account_uuid [String] UUID of the social media account.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :period Preset reporting period. Ignored when `date_from` and `date_to` are given. (default to 'this_month')
+    # @option opts [Date] :date_from Start of a custom range (Y-m-d). Required with `date_to`; the range may span at most 366 days.
+    # @option opts [Date] :date_to End of a custom range (Y-m-d). Required with `date_from`; must not be before it.
+    # @option opts [String] :type Analytics tab. Defaults to the account's default tab.
+    # @option opts [Integer] :page Page for list-style tabs (for example per-post metrics). (default to 1)
+    # @option opts [Integer] :per_page 
+    # @option opts [String] :sort_by 
+    # @option opts [String] :sort_dir  (default to 'desc')
+    # @return [Array<(AccountAnalytics, Integer, Hash)>] AccountAnalytics data, response status code and response headers
+    def get_account_analytics_with_http_info(workspace_uuid, account_uuid, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_account_analytics ...'
+      end
+      # verify the required parameter 'workspace_uuid' is set
+      if @api_client.config.client_side_validation && workspace_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'workspace_uuid' when calling AnalyticsApi.get_account_analytics"
+      end
+      # verify the required parameter 'account_uuid' is set
+      if @api_client.config.client_side_validation && account_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'account_uuid' when calling AnalyticsApi.get_account_analytics"
+      end
+      allowable_values = ["this_week", "last_week", "this_month", "last_month", "last_3_months", "this_year"]
+      if @api_client.config.client_side_validation && opts[:'period'] && !allowable_values.include?(opts[:'period'])
+        fail ArgumentError, "invalid value for \"period\", must be one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'page'].nil? && opts[:'page'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"page"]" when calling AnalyticsApi.get_account_analytics, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'per_page'].nil? && opts[:'per_page'] > 50
+        fail ArgumentError, 'invalid value for "opts[:"per_page"]" when calling AnalyticsApi.get_account_analytics, must be smaller than or equal to 50.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'per_page'].nil? && opts[:'per_page'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"per_page"]" when calling AnalyticsApi.get_account_analytics, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'sort_by'].nil? && opts[:'sort_by'].to_s.length > 64
+        fail ArgumentError, 'invalid value for "opts[:"sort_by"]" when calling AnalyticsApi.get_account_analytics, the character length must be smaller than or equal to 64.'
+      end
+
+      allowable_values = ["asc", "desc"]
+      if @api_client.config.client_side_validation && opts[:'sort_dir'] && !allowable_values.include?(opts[:'sort_dir'])
+        fail ArgumentError, "invalid value for \"sort_dir\", must be one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/{workspaceUuid}/analytics/accounts/{accountUuid}'.sub('{' + 'workspaceUuid' + '}', CGI.escape(workspace_uuid.to_s)).sub('{' + 'accountUuid' + '}', CGI.escape(account_uuid.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'period'] = opts[:'period'] if !opts[:'period'].nil?
+      query_params[:'date_from'] = opts[:'date_from'] if !opts[:'date_from'].nil?
+      query_params[:'date_to'] = opts[:'date_to'] if !opts[:'date_to'].nil?
+      query_params[:'type'] = opts[:'type'] if !opts[:'type'].nil?
+      query_params[:'page'] = opts[:'page'] if !opts[:'page'].nil?
+      query_params[:'per_page'] = opts[:'per_page'] if !opts[:'per_page'].nil?
+      query_params[:'sort_by'] = opts[:'sort_by'] if !opts[:'sort_by'].nil?
+      query_params[:'sort_dir'] = opts[:'sort_dir'] if !opts[:'sort_dir'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AccountAnalytics'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_account_analytics",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_account_analytics\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get analytics summary
+    # Cross-platform summary (followers, growth, posts, leaderboard, posting streak) over every account that supports analytics, for a preset period or a custom date range.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :period Preset reporting period. Ignored when &#x60;date_from&#x60; and &#x60;date_to&#x60; are given. (default to 'this_month')
+    # @option opts [Date] :date_from Start of a custom range (Y-m-d). Required with &#x60;date_to&#x60;; the range may span at most 366 days.
+    # @option opts [Date] :date_to End of a custom range (Y-m-d). Required with &#x60;date_from&#x60;; must not be before it.
+    # @return [AnalyticsSummary]
+    def get_analytics_summary(workspace_uuid, opts = {})
+      data, _status_code, _headers = get_analytics_summary_with_http_info(workspace_uuid, opts)
+      data
+    end
+
+    # Get analytics summary
+    # Cross-platform summary (followers, growth, posts, leaderboard, posting streak) over every account that supports analytics, for a preset period or a custom date range.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :period Preset reporting period. Ignored when &#x60;date_from&#x60; and &#x60;date_to&#x60; are given. (default to 'this_month')
+    # @option opts [Date] :date_from Start of a custom range (Y-m-d). Required with &#x60;date_to&#x60;; the range may span at most 366 days.
+    # @option opts [Date] :date_to End of a custom range (Y-m-d). Required with &#x60;date_from&#x60;; must not be before it.
+    # @return [Array<(AnalyticsSummary, Integer, Hash)>] AnalyticsSummary data, response status code and response headers
+    def get_analytics_summary_with_http_info(workspace_uuid, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_analytics_summary ...'
+      end
+      # verify the required parameter 'workspace_uuid' is set
+      if @api_client.config.client_side_validation && workspace_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'workspace_uuid' when calling AnalyticsApi.get_analytics_summary"
+      end
+      allowable_values = ["this_week", "last_week", "this_month", "last_month", "last_3_months", "this_year"]
+      if @api_client.config.client_side_validation && opts[:'period'] && !allowable_values.include?(opts[:'period'])
+        fail ArgumentError, "invalid value for \"period\", must be one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/{workspaceUuid}/analytics'.sub('{' + 'workspaceUuid' + '}', CGI.escape(workspace_uuid.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'period'] = opts[:'period'] if !opts[:'period'].nil?
+      query_params[:'date_from'] = opts[:'date_from'] if !opts[:'date_from'].nil?
+      query_params[:'date_to'] = opts[:'date_to'] if !opts[:'date_to'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AnalyticsSummary'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_analytics_summary",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_analytics_summary\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get best posting times
+    # The next recommended date and time per account, on or after `from` (never in the past), within the next 14 days.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :accounts Account UUIDs. Defaults to every account in the workspace.
+    # @option opts [Date] :from Earliest date to recommend (Y-m-d). Defaults to now.
+    # @option opts [String] :timezone Timezone for &#x60;from&#x60; and the returned times. Defaults to the workspace timezone.
+    # @return [BestPostingTimes]
+    def get_best_posting_times(workspace_uuid, opts = {})
+      data, _status_code, _headers = get_best_posting_times_with_http_info(workspace_uuid, opts)
+      data
+    end
+
+    # Get best posting times
+    # The next recommended date and time per account, on or after &#x60;from&#x60; (never in the past), within the next 14 days.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :accounts Account UUIDs. Defaults to every account in the workspace.
+    # @option opts [Date] :from Earliest date to recommend (Y-m-d). Defaults to now.
+    # @option opts [String] :timezone Timezone for &#x60;from&#x60; and the returned times. Defaults to the workspace timezone.
+    # @return [Array<(BestPostingTimes, Integer, Hash)>] BestPostingTimes data, response status code and response headers
+    def get_best_posting_times_with_http_info(workspace_uuid, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_best_posting_times ...'
+      end
+      # verify the required parameter 'workspace_uuid' is set
+      if @api_client.config.client_side_validation && workspace_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'workspace_uuid' when calling AnalyticsApi.get_best_posting_times"
+      end
+      # resource path
+      local_var_path = '/{workspaceUuid}/analytics/best-times'.sub('{' + 'workspaceUuid' + '}', CGI.escape(workspace_uuid.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'accounts[]'] = @api_client.build_collection_param(opts[:'accounts'], :multi) if !opts[:'accounts'].nil?
+      query_params[:'from'] = opts[:'from'] if !opts[:'from'].nil?
+      query_params[:'timezone'] = opts[:'timezone'] if !opts[:'timezone'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'BestPostingTimes'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_best_posting_times",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_best_posting_times\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get post analytics
+    # Engagement metrics for a published post across its accounts (also works for trashed posts), with totals, trends and the best-performing account.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param post_uuid [String] UUID of the post.
+    # @param [Hash] opts the optional parameters
+    # @return [PostAnalytics]
+    def get_post_analytics_0(workspace_uuid, post_uuid, opts = {})
+      data, _status_code, _headers = get_post_analytics_0_with_http_info(workspace_uuid, post_uuid, opts)
+      data
+    end
+
+    # Get post analytics
+    # Engagement metrics for a published post across its accounts (also works for trashed posts), with totals, trends and the best-performing account.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param post_uuid [String] UUID of the post.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(PostAnalytics, Integer, Hash)>] PostAnalytics data, response status code and response headers
+    def get_post_analytics_0_with_http_info(workspace_uuid, post_uuid, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_post_analytics_0 ...'
+      end
+      # verify the required parameter 'workspace_uuid' is set
+      if @api_client.config.client_side_validation && workspace_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'workspace_uuid' when calling AnalyticsApi.get_post_analytics_0"
+      end
+      # verify the required parameter 'post_uuid' is set
+      if @api_client.config.client_side_validation && post_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'post_uuid' when calling AnalyticsApi.get_post_analytics_0"
+      end
+      # resource path
+      local_var_path = '/{workspaceUuid}/posts/{postUuid}/analytics'.sub('{' + 'workspaceUuid' + '}', CGI.escape(workspace_uuid.to_s)).sub('{' + 'postUuid' + '}', CGI.escape(post_uuid.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'PostAnalytics'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_post_analytics_0",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_post_analytics_0\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get posting times heatmap
+    # Engagement scores per weekday and hour, merged across the given accounts (all accounts when none is given), in the requested timezone. Also returns up to three recommended slots.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :accounts Account UUIDs. Defaults to every account in the workspace.
+    # @option opts [String] :timezone Timezone the grid is expressed in. Defaults to the workspace timezone.
+    # @return [PostingTimes]
+    def get_posting_times(workspace_uuid, opts = {})
+      data, _status_code, _headers = get_posting_times_with_http_info(workspace_uuid, opts)
+      data
+    end
+
+    # Get posting times heatmap
+    # Engagement scores per weekday and hour, merged across the given accounts (all accounts when none is given), in the requested timezone. Also returns up to three recommended slots.
+    # @param workspace_uuid [String] UUID of the workspace.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :accounts Account UUIDs. Defaults to every account in the workspace.
+    # @option opts [String] :timezone Timezone the grid is expressed in. Defaults to the workspace timezone.
+    # @return [Array<(PostingTimes, Integer, Hash)>] PostingTimes data, response status code and response headers
+    def get_posting_times_with_http_info(workspace_uuid, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_posting_times ...'
+      end
+      # verify the required parameter 'workspace_uuid' is set
+      if @api_client.config.client_side_validation && workspace_uuid.nil?
+        fail ArgumentError, "Missing the required parameter 'workspace_uuid' when calling AnalyticsApi.get_posting_times"
+      end
+      # resource path
+      local_var_path = '/{workspaceUuid}/analytics/posting-times'.sub('{' + 'workspaceUuid' + '}', CGI.escape(workspace_uuid.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'accounts[]'] = @api_client.build_collection_param(opts[:'accounts'], :multi) if !opts[:'accounts'].nil?
+      query_params[:'timezone'] = opts[:'timezone'] if !opts[:'timezone'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'PostingTimes'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_posting_times",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_posting_times\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end