mencoro 1.0.0

data/lib/mencoro/api/discovery_api.rb

@@ -0,0 +1,360 @@
+=begin
+#Mencoro API
+
+#Public API for Mencoro customers. Authenticate with an API key: `Authorization: Bearer mencoro_sk_...`.
+
+The version of the OpenAPI document: 1.0.0
+Contact: support@mencoro.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.24.0
+
+=end
+
+require 'cgi'
+
+module Mencoro
+  class DiscoveryApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Start a brand discovery job for a project
+    # Minimum role: manager. Starts background discovery of the brands and competitors around a project and answers 202 with the job to poll; it never returns brands inline. The job PROPOSES names: it creates and updates nothing, so neither the brand profile nor the competitor list changes because this endpoint was called. The organization must be active. Unlike keyword and prompt discovery this operation does not require an entitled subscription, matching the application behaviour it mirrors. Ten starts per minute per organization, counted across every key of every member and shared with the same operation in the Mencoro app; a retry carrying an Idempotency-Key already answered is served from the record and does not count. A project whose brand monitoring profile has not been created yet is still accepted and still billed: the job runs grounded on the project name alone, with no website domains, brand names or competitors to work from, and completes normally. Configure the brand profile first if you want the discovery grounded.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param [Hash] opts the optional parameters
+    # @option opts [StartBrandDiscoveryJobRequest] :start_brand_discovery_job_request 
+    # @return [AcceptedJobResource]
+    def start_brand_discovery_job(organization_id, project_id, idempotency_key, opts = {})
+      data, _status_code, _headers = start_brand_discovery_job_with_http_info(organization_id, project_id, idempotency_key, opts)
+      data
+    end
+
+    # Start a brand discovery job for a project
+    # Minimum role: manager. Starts background discovery of the brands and competitors around a project and answers 202 with the job to poll; it never returns brands inline. The job PROPOSES names: it creates and updates nothing, so neither the brand profile nor the competitor list changes because this endpoint was called. The organization must be active. Unlike keyword and prompt discovery this operation does not require an entitled subscription, matching the application behaviour it mirrors. Ten starts per minute per organization, counted across every key of every member and shared with the same operation in the Mencoro app; a retry carrying an Idempotency-Key already answered is served from the record and does not count. A project whose brand monitoring profile has not been created yet is still accepted and still billed: the job runs grounded on the project name alone, with no website domains, brand names or competitors to work from, and completes normally. Configure the brand profile first if you want the discovery grounded.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param [Hash] opts the optional parameters
+    # @option opts [StartBrandDiscoveryJobRequest] :start_brand_discovery_job_request 
+    # @return [Array<(AcceptedJobResource, Integer, Hash)>] AcceptedJobResource data, response status code and response headers
+    def start_brand_discovery_job_with_http_info(organization_id, project_id, idempotency_key, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DiscoveryApi.start_brand_discovery_job ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling DiscoveryApi.start_brand_discovery_job"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling DiscoveryApi.start_brand_discovery_job"
+      end
+      # verify the required parameter 'idempotency_key' is set
+      if @api_client.config.client_side_validation && idempotency_key.nil?
+        fail ArgumentError, "Missing the required parameter 'idempotency_key' when calling DiscoveryApi.start_brand_discovery_job"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/discovery/brands'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.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']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+      header_params[:'Idempotency-Key'] = idempotency_key
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(opts[:'start_brand_discovery_job_request'])
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AcceptedJobResource'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"DiscoveryApi.start_brand_discovery_job",
+        :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(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DiscoveryApi#start_brand_discovery_job\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Start a brand-name alias suggestion job
+    # Minimum role: manager. Starts a background, web-search-grounded job that suggests alias spellings for one entity - a brand, a project or a competitor - described entirely by the body, and answers 202 with the job to poll; it never returns suggestions inline. The entity need not exist: nothing is looked up, nothing is attached and nothing is saved, so the suggestions are the caller's to apply. Names sent in `enteredBrandNames` are excluded from the result. The organization must be active; no subscription is required, matching the application behaviour this mirrors. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count.
+    # @param organization_id [String] 
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_brand_name_suggestion_job_request [StartBrandNameSuggestionJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [AcceptedJobResource]
+    def start_brand_name_suggestion_job(organization_id, idempotency_key, start_brand_name_suggestion_job_request, opts = {})
+      data, _status_code, _headers = start_brand_name_suggestion_job_with_http_info(organization_id, idempotency_key, start_brand_name_suggestion_job_request, opts)
+      data
+    end
+
+    # Start a brand-name alias suggestion job
+    # Minimum role: manager. Starts a background, web-search-grounded job that suggests alias spellings for one entity - a brand, a project or a competitor - described entirely by the body, and answers 202 with the job to poll; it never returns suggestions inline. The entity need not exist: nothing is looked up, nothing is attached and nothing is saved, so the suggestions are the caller&#39;s to apply. Names sent in &#x60;enteredBrandNames&#x60; are excluded from the result. The organization must be active; no subscription is required, matching the application behaviour this mirrors. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count.
+    # @param organization_id [String] 
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_brand_name_suggestion_job_request [StartBrandNameSuggestionJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(AcceptedJobResource, Integer, Hash)>] AcceptedJobResource data, response status code and response headers
+    def start_brand_name_suggestion_job_with_http_info(organization_id, idempotency_key, start_brand_name_suggestion_job_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DiscoveryApi.start_brand_name_suggestion_job ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling DiscoveryApi.start_brand_name_suggestion_job"
+      end
+      # verify the required parameter 'idempotency_key' is set
+      if @api_client.config.client_side_validation && idempotency_key.nil?
+        fail ArgumentError, "Missing the required parameter 'idempotency_key' when calling DiscoveryApi.start_brand_name_suggestion_job"
+      end
+      # verify the required parameter 'start_brand_name_suggestion_job_request' is set
+      if @api_client.config.client_side_validation && start_brand_name_suggestion_job_request.nil?
+        fail ArgumentError, "Missing the required parameter 'start_brand_name_suggestion_job_request' when calling DiscoveryApi.start_brand_name_suggestion_job"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/brand-name-suggestions'.sub('{organizationId}', CGI.escape(organization_id.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']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+      header_params[:'Idempotency-Key'] = idempotency_key
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(start_brand_name_suggestion_job_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AcceptedJobResource'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"DiscoveryApi.start_brand_name_suggestion_job",
+        :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(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DiscoveryApi#start_brand_name_suggestion_job\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Start a keyword discovery job for a project
+    # Minimum role: manager. Starts background keyword discovery from free-text seed input and answers 202 with the job to poll; it never returns keywords inline. The job SUGGESTS keywords - it creates no tracked queries and changes nothing in the project, so a completed job is a list to choose from, not work that has been applied. Queries the project already tracks are excluded from the suggestions automatically; `excludeQueries` adds more on top for this run only. The organization must be active and hold an entitled subscription, because the run spends provider budget. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count. Run tuning is not exposed: the discovery fan-out uses provider defaults.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_keyword_discovery_job_request [StartKeywordDiscoveryJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [AcceptedJobResource]
+    def start_keyword_discovery_job(organization_id, project_id, idempotency_key, start_keyword_discovery_job_request, opts = {})
+      data, _status_code, _headers = start_keyword_discovery_job_with_http_info(organization_id, project_id, idempotency_key, start_keyword_discovery_job_request, opts)
+      data
+    end
+
+    # Start a keyword discovery job for a project
+    # Minimum role: manager. Starts background keyword discovery from free-text seed input and answers 202 with the job to poll; it never returns keywords inline. The job SUGGESTS keywords - it creates no tracked queries and changes nothing in the project, so a completed job is a list to choose from, not work that has been applied. Queries the project already tracks are excluded from the suggestions automatically; &#x60;excludeQueries&#x60; adds more on top for this run only. The organization must be active and hold an entitled subscription, because the run spends provider budget. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count. Run tuning is not exposed: the discovery fan-out uses provider defaults.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_keyword_discovery_job_request [StartKeywordDiscoveryJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(AcceptedJobResource, Integer, Hash)>] AcceptedJobResource data, response status code and response headers
+    def start_keyword_discovery_job_with_http_info(organization_id, project_id, idempotency_key, start_keyword_discovery_job_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DiscoveryApi.start_keyword_discovery_job ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling DiscoveryApi.start_keyword_discovery_job"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling DiscoveryApi.start_keyword_discovery_job"
+      end
+      # verify the required parameter 'idempotency_key' is set
+      if @api_client.config.client_side_validation && idempotency_key.nil?
+        fail ArgumentError, "Missing the required parameter 'idempotency_key' when calling DiscoveryApi.start_keyword_discovery_job"
+      end
+      # verify the required parameter 'start_keyword_discovery_job_request' is set
+      if @api_client.config.client_side_validation && start_keyword_discovery_job_request.nil?
+        fail ArgumentError, "Missing the required parameter 'start_keyword_discovery_job_request' when calling DiscoveryApi.start_keyword_discovery_job"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/discovery/keywords'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.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']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+      header_params[:'Idempotency-Key'] = idempotency_key
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(start_keyword_discovery_job_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AcceptedJobResource'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"DiscoveryApi.start_keyword_discovery_job",
+        :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(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DiscoveryApi#start_keyword_discovery_job\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Start a geo prompt discovery job for a project
+    # Minimum role: manager. Starts background discovery of natural-language prompts - the questions an answer engine gets asked - from free-text seed input, and answers 202 with the job to poll; it never returns prompts inline. The job SUGGESTS prompts: it creates no tracked queries and changes nothing in the project. `country` is required here, unlike keyword discovery, because a prompt is a question asked from somewhere and the provider request has no default for it. Queries the project already tracks are excluded automatically; `excludeQueries` adds more for this run only. The organization must be active and hold an entitled subscription, because the run spends provider budget. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count. Run tuning is not exposed: the discovery fan-out uses provider defaults.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_prompt_discovery_job_request [StartPromptDiscoveryJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [AcceptedJobResource]
+    def start_prompt_discovery_job(organization_id, project_id, idempotency_key, start_prompt_discovery_job_request, opts = {})
+      data, _status_code, _headers = start_prompt_discovery_job_with_http_info(organization_id, project_id, idempotency_key, start_prompt_discovery_job_request, opts)
+      data
+    end
+
+    # Start a geo prompt discovery job for a project
+    # Minimum role: manager. Starts background discovery of natural-language prompts - the questions an answer engine gets asked - from free-text seed input, and answers 202 with the job to poll; it never returns prompts inline. The job SUGGESTS prompts: it creates no tracked queries and changes nothing in the project. &#x60;country&#x60; is required here, unlike keyword discovery, because a prompt is a question asked from somewhere and the provider request has no default for it. Queries the project already tracks are excluded automatically; &#x60;excludeQueries&#x60; adds more for this run only. The organization must be active and hold an entitled subscription, because the run spends provider budget. Ten starts per minute per organization, counted across every key of every member; a retry carrying an Idempotency-Key already answered is served from the record and does not count. Run tuning is not exposed: the discovery fan-out uses provider defaults.
+    # @param organization_id [String] 
+    # @param project_id [String] Must belong to the organization in the path.
+    # @param idempotency_key [String] Repeat it to retry a start whose response was lost; the same key returns the same job instead of starting a second one.
+    # @param start_prompt_discovery_job_request [StartPromptDiscoveryJobRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(AcceptedJobResource, Integer, Hash)>] AcceptedJobResource data, response status code and response headers
+    def start_prompt_discovery_job_with_http_info(organization_id, project_id, idempotency_key, start_prompt_discovery_job_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DiscoveryApi.start_prompt_discovery_job ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling DiscoveryApi.start_prompt_discovery_job"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling DiscoveryApi.start_prompt_discovery_job"
+      end
+      # verify the required parameter 'idempotency_key' is set
+      if @api_client.config.client_side_validation && idempotency_key.nil?
+        fail ArgumentError, "Missing the required parameter 'idempotency_key' when calling DiscoveryApi.start_prompt_discovery_job"
+      end
+      # verify the required parameter 'start_prompt_discovery_job_request' is set
+      if @api_client.config.client_side_validation && start_prompt_discovery_job_request.nil?
+        fail ArgumentError, "Missing the required parameter 'start_prompt_discovery_job_request' when calling DiscoveryApi.start_prompt_discovery_job"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/discovery/prompts'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.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']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+      header_params[:'Idempotency-Key'] = idempotency_key
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(start_prompt_discovery_job_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'AcceptedJobResource'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"DiscoveryApi.start_prompt_discovery_job",
+        :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(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DiscoveryApi#start_prompt_discovery_job\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end