Add incentives examples

[dorasun]

Change-Id: I57fa8a776fb8a1cbd43f6c1d3a1a71c3c63bdd19

[bobhancockg]

Code Vetting & Review Recommendations

Overall, the implementation for adding incentive examples (apply_incentive.rb and fetch_incentive.rb) is well-structured. Below are recommended improvements to align with google-ads-ruby repository standards, fix documentation indexing tags, ensure type safety, and standardize monetary formatting.

---

1. examples/incentives/apply_incentive.rb

• Default Parameter Value: Add country_code = nil to the method signature so calling apply_incentive(customer_id, incentive_id) programmatically works without explicitly passing nil:

  def apply_incentive(customer_id, incentive_id, country_code = nil)

• Type Safety for selected_incentive_id: Explicitly call .to_i on incentive_id when constructing request_args for protobuf field type safety (int64):

  request_args = {
    customer_id: customer_id,
    selected_incentive_id: incentive_id.to_i
  }

• CLI Default Initializers & Validation: Initialize options[:incentive_id] = 'INSERT_INCENTIVE_ID_HERE' at the top of if __FILE__ == $0 to match the doc comments, and update argument validation accordingly:

  options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
  options[:incentive_id] = 'INSERT_INCENTIVE_ID_HERE'

  if options[:customer_id].nil? ||
      options[:customer_id] == 'INSERT_CUSTOMER_ID_HERE' ||
      options[:incentive_id].nil? ||
      options[:incentive_id] == 'INSERT_INCENTIVE_ID_HERE'
    puts 'Missing required arguments. See usage:'
    puts 'Customer ID and Incentive ID are required.'
    exit 1
  end

---

2. examples/incentives/fetch_incentive.rb

• Documentation Region Tags: Add # [START fetch_incentive] and # [END fetch_incentive] region tags around the main method so Google Developers documentation (devsite) can automatically index the code snippet.
• Standardize Currency Formatting in format_money: Simplify calculation to cleanly format zero, fractional, and negative currency values with standard 2 decimal places:

  def format_money(money)
    return 'N/A' if money.nil?
  
    amount = money.units.to_f + (money.nanos.to_f / 1_000_000_000.0)
    sprintf('%.2f %s', amount, money.currency_code)
  end

• CLI Option Placeholder & Check: Initialize options[:email] = 'INSERT_EMAIL_HERE' and validate against INSERT_EMAIL_HERE in if __FILE__ == $0.

[bobhancockg]

Sanitize Customer ID in method & use .compact: Hyphens are only stripped when passed via CLI flags (-C), failing if called directly in Ruby code. Also simplify request hash building with .compact.

[bobhancockg]

Print OptionParser banner on missing args: Output the full OptionParser usage banner (puts opts) instead of just a generic one-liner error.

[bobhancockg]

Add fallback for non-CYO offers & DRY loop: If an offer type is not cyo_incentives, the script silently prints nothing. Add an else branch and iterate over [low_offer, medium_offer, high_offer].

[bobhancockg]

Defensive Coding: Handle potential nil/empty proto fields in format_money: Guard against nil values in money.units, money.nanos, and money.currency_code.

[bobhancockg]

Usability: Print OptionParser banner on missing email: Display the command line options (puts opts) when INSERT_EMAIL_HERE is left unchanged.