Enrichments

examples/Businesses.md

@@ -95,6 +95,91 @@ When both structured params and `query` are provided:
 - for `limit`, `cursor`, and `include_total`, plain-text values take priority when present
 - if a value is not specified, API defaults are used
 
+### Search businesses with enrichments
+
+`enrichments` can be provided in three formats:
+
+- **Hash (recommended)** — send a structured object with options per enrichment
+- **Array** — enable enrichments without options
+- **String** — enable a single enrichment without options
+
+#### Enrichments as Hash (recommended)
+
+```ruby
+results = client.businessesSearch(
+  filters: {
+    country_code: "US",
+    states: ["CA", "NY"],
+    types: ["restaurant", "cafe"]
+  },
+  limit: 10,
+  fields: ["name", "phone", "website", "rating", "reviews"],
+  enrichments: {
+    "contacts_n_leads" => {
+      "contacts_per_company" => 4,
+      "emails_per_contact" => 2
+    },
+    "company_insights" => {}
+  }
+)
+
+puts results
+```
+
+#### Enrichments as Array
+
+```ruby
+results = client.businessesSearch(
+  filters: { country_code: "US", states: ["NY"] },
+  limit: 10,
+  enrichments: ["contacts_n_leads", "company_insights"]
+)
+
+puts results
+```
+
+#### Enrichments as String
+
+```ruby
+results = client.businessesSearch(
+  filters: { country_code: "US", states: ["NY"] },
+  limit: 10,
+  enrichments: "contacts_n_leads"
+)
+
+puts results
+```
+
+#### Full JSON-style parameters example
+
+```ruby
+params = {
+  filters: {
+    country_code: "US",
+    states: ["CA", "NY"],
+    types: ["restaurant", "cafe"]
+  },
+  limit: 900,
+  cursor: nil,
+  include_total: false,
+  fields: [
+    "name", "types", "address", "country", "website",
+    "phone", "rating", "reviews"
+  ],
+  enrichments: {
+    "contacts_n_leads" => {
+      "contacts_per_company" => 4,
+      "emails_per_contact" => 2
+    },
+    "company_insights" => {}
+  },
+  query: "Find hotels in California and Illinois with rating 4.2+ and status operational. Return fields: name, address, rating and reviews. Limit results to 6. Enrich data with contacts_n_leads. Contact per company set to 8"
+}
+
+results = client.businessesSearch(**params)
+puts results
+```
+
 ### Iterate through all results (auto-pagination)
 
 ```ruby

lib/outscraper.rb

@@ -378,7 +378,7 @@ def company_website_finder(query, fields: '', async_request: false)
         async: async_request
       }).parsed_response['data']
     end
-    
+
     def yellowpages_search(query, location: 'New York, NY', limit: 100, region: nil, enrichment: [], fields: '', async_request: false, ui: nil, webhook: nil)
       enrichment_array = enrichment.is_a?(Array) ? enrichment : [enrichment]
       response = self.class.get('/yellowpages-search', query: {
@@ -412,27 +412,92 @@ def businessesSearch(
       include_total: false,
       cursor: nil,
       fields: nil,
+      enrichments: nil,
+      contacts_per_company: nil,
+      emails_per_contact: nil,
       async_request: false,
       ui: false,
       webhook: nil,
       query: nil
     )
-      payload = {
-        filters: (filters || {}),
-        limit: limit,
-        include_total: include_total,
-        cursor: cursor,
-        fields: fields ? Array(fields) : nil,
-        query: query,
-        async: async_request,
-        ui: ui,
-        webhook: webhook
-      }.compact
+      if contacts_per_company && contacts_per_company < 1
+        raise ArgumentError, 'contacts_per_company must be >= 1'
+      end
+
+      if emails_per_contact && emails_per_contact < 1
+        raise ArgumentError, 'emails_per_contact must be >= 1'
+      end
+
+enrichments_normalized = nil
+
+if enrichments.is_a?(Hash)
+  enrichments_normalized = enrichments
+elsif enrichments.is_a?(Array)
+  enrichments_normalized = enrichments
+elsif enrichments.is_a?(String) || enrichments.is_a?(Symbol)
+  enrichments_normalized = enrichments.to_s
+elsif !enrichments.nil?
+  enrichments_normalized = Array(enrichments)
+end
+
+if !contacts_per_company.nil? || !emails_per_contact.nil?
+  cpp = contacts_per_company || 3
+  epc = emails_per_contact || 1
+
+  case enrichments_normalized
+  when nil
+    enrichments_normalized = { 'contacts_n_leads' => { 'contacts_per_company' => cpp, 'emails_per_contact' => epc } }
+  when Hash
+    enrichments_normalized['contacts_n_leads'] ||= {}
+    enrichments_normalized['contacts_n_leads']['contacts_per_company'] = cpp
+    enrichments_normalized['contacts_n_leads']['emails_per_contact'] = epc
+  when Array
+    unless enrichments_normalized.map(&:to_s).include?('contacts_n_leads')
+      raise ArgumentError, 'contacts_per_company and emails_per_contact require enrichments to include "contacts_n_leads"'
+    end
+    # Expand array to object so we can include options
+    expanded = {}
+    enrichments_normalized.each { |name| expanded[name.to_s] = {} }
+    expanded['contacts_n_leads']['contacts_per_company'] = cpp
+    expanded['contacts_n_leads']['emails_per_contact'] = epc
+    enrichments_normalized = expanded
+  when String
+    unless enrichments_normalized == 'contacts_n_leads'
+      raise ArgumentError, 'contacts_per_company and emails_per_contact require enrichments to include "contacts_n_leads"'
+    end
+    enrichments_normalized = { 'contacts_n_leads' => { 'contacts_per_company' => cpp, 'emails_per_contact' => epc } }
+  else
+    raise ArgumentError, 'Invalid enrichments type'
+  end
+end
+
+payload = {
+  filters: (filters || {}),
+  limit: limit,
+  include_total: include_total,
+  cursor: cursor,
+  fields: fields ? Array(fields) : nil,
+  enrichments: enrichments_normalized,
+  query: query,
+  async: async_request,
+  ui: ui,
+  webhook: webhook
+}.compact
+
+postAPIRequest('/businesses', payload)
 
-      postAPIRequest('/businesses', payload)
     end
 
-    def businessesIterSearch(filters: {}, limit: 10, fields: nil, include_total: false)
+    def businessesIterSearch(
+      filters: {},
+      limit: 10,
+      fields: nil,
+      include_total: false,
+      enrichments: nil,
+      contacts_per_company: nil,
+      emails_per_contact: nil,
+      query: nil
+    )
       cursor = nil
       all_items = []
 
@@ -443,6 +508,10 @@ def businessesIterSearch(filters: {}, limit: 10, fields: nil, include_total: fal
           include_total: include_total,
           cursor: cursor,
           fields: fields,
+          enrichments: enrichments,
+          contacts_per_company: contacts_per_company,
+          emails_per_contact: emails_per_contact,
+          query: query,
           async_request: false
         )
 

lib/outscraper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Outscraper
-  VERSION = "0.3.6"
+  VERSION = "0.3.7"
 end