mercadopago-sdk 1.2.0 → 2.0.3

data/README.md

@@ -8,152 +8,80 @@ This library provides developers with a simple set of bindings to help you integ
 
 ## 💡 Requirements
 
-The SDK Supports Ruby from version v0 
+Ruby version **2.3 or greater**.
 
 ## 📲 Installation 
 
-First time using Mercado Pago? Create your [Mercado Pago account](https://www.mercadopago.com), if you don’t have one already.
-
-1. Run ```gem install mercadopago-sdk```
-
-2. Copy the access_token in the [credentials](https://www.mercadopago.com/mlb/account/credentials) section of the page and replace YOUR_ACCESS_TOKEN with it.
-
-Thats all, you have Mercado Pago SDK installed.
-
-```ruby
-preference = $mp.get_preference('PREFERENCE_ID')
-
-puts $preferenceResult
-```
+Run ```gem install mercadopago-sdk```
 
 ## 🌟 Getting Started
-  
-  Simple usage looks like:
-
-```ruby
-require 'mercadopago.rb'
-
-$mp = MercadoPago.new('YOUR_ACCESS_TOKEN')
-
-preference_data = {
-	"items": [
-		{
-			"title": "testCreate", 
-			"quantity": 1, 
-			"unit_price": 10.2, 
-			"currency_id": "ARS"
-		}
-preference = $mp.create_preference(preference_data)
-
-puts preference
-```
-
-#### Update an existent Checkout preference
-
-```ruby
-preferenceDataToUpdate = Hash["items" => Array(Array["title"=>"testUpdated", "quantity"=>1, "unit_price"=>2])]
-
-preferenceUpdate = $mp.update_preference("PREFERENCE_ID", preferenceDataToUpdate)
-
-puts preferenceUpdate
-```
-
-### Payments/Collections
-
-#### Search for payments
-
-```ruby    
-filters = Array["id"=>null, "external_reference"=>null]
-
-searchResult = $mp.search_payment(filters)
 
-puts searchResult
-```
-
-#### Get payment data
-
-```ruby
-paymentInfo = $mp.get_payment("ID")
-
-puts paymentInfo
-```
+First time using Mercado Pago? Create your [Mercado Pago account](https://www.mercadopago.com).
 
-### Cancel (only for pending payments)
+Copy your `Access Token` in the [credentials panel](https://www.mercadopago.com/developers/panel/credentials) and replace the text `YOUR_ACCESS_TOKEN` with it.
 
-```ruby
-result = $mp.cancel_payment("ID");
-
-// Show result
-puts result
-```
+### Simple usage
 
-### Refund (only for accredited payments)
+To generate a `card token` read the [Checkout API](https://www.mercadopago.com/developers/en/guides/online-payments/checkout-api/introduction) documentation.
 
 ```ruby
-result = $mp.refund_payment("ID");
-
-// Show result
-puts result
+require 'mercadopago'
+
+sdk = Mercadopago::SDK.new('YOUR_ACCESS_TOKEN')
+
+payment_data = {
+  transaction_amount: 100,
+  token: 'CARD_TOKEN',
+  description: 'Payment description',
+  payment_method_id: 'visa',
+  installments: 1,
+  payer: {
+    email: 'test_user_123456@testuser.com'
+  }
+}
+result = sdk.payment.create(payment_data)
+payment = result[:response]
+
+puts payment
 ```
 
-<a name="custom-checkout"></a>
-## Customized checkout
-
-### Configure your credentials
+### Per-request configuration
 
-* Get your **ACCESS_TOKEN** in the following address:
-    * Argentina: [https://www.mercadopago.com/mla/account/credentials](https://www.mercadopago.com/mla/account/credentials)
-    * Brazil: [https://www.mercadopago.com/mlb/account/credentials](https://www.mercadopago.com/mlb/account/credentials)
-    * Mexico: [https://www.mercadopago.com/mlm/account/credentials](https://www.mercadopago.com/mlm/account/credentials)
-    * Venezuela: [https://www.mercadopago.com/mlv/account/credentials](https://www.mercadopago.com/mlv/account/credentials)
-    * Colombia: [https://www.mercadopago.com/mco/account/credentials](https://www.mercadopago.com/mco/account/credentials)
+All methods that make API calls accept an optional `RequestOptions` object. This can be used to configure some special options of the request, such as changing credentials or custom headers.
 
 ```ruby
-require 'mercadopago.rb'
+require 'mercadopago'
 
-$mp = MercadoPago.new('ACCESS_TOKEN')
-```
+request_options = Mercadopago::RequestOptions.new(access_token: 'YOUR_ACCESS_TOKEN')
+# ...
 
-### Create payment
-
-```ruby
-$mp.post ("/v1/payments", payment_data);
+result = sdk.payment.create(payment_data, request_options: request_options)
+payment = result[:response]
 ```
 
-### Create customer
+## 📚 Documentation 
 
-```ruby
-$mp.post ("/v1/customers", Hash["email" => "email@test.com"]);
-```
+Visit our Dev Site for further information regarding:
+ - [APIs](https://www.mercadopago.com/developers/en/reference)
+ - [Checkout Pro](https://www.mercadopago.com/developers/en/guides/online-payments/checkout-pro/introduction)
+ - [Checkout API](https://www.mercadopago.com/developers/en/guides/online-payments/checkout-api/introduction)
+ - [Web Tokenize Checkout](https://www.mercadopago.com/developers/en/guides/online-payments/web-tokenize-checkout/introduction)
 
 Check our official code reference to explore all available functionalities.
 
-```ruby
-$mp.get ("/v1/customers/CUSTOMER_ID");
-```
+## 🤝 Contributing
 
-If you require technical support, please contact our support team at [developers.mercadopago.com](https://developers.mercadopago.com)
+All contributions are welcome, ranging from people wanting to triage issues, others wanting to write documentation, to people wanting to contribute code.
 
-## 🏻 License 
+Please read and follow our [contribution guidelines](CONTRIBUTING.md). Contributions not following this guidelines will be disregarded. The guidelines are in place to make all of our lives easier and make contribution a consistent process for everyone.
 
-```ruby
-// Get a resource, with optional URL params. Also you can disable authentication for public APIs
-$mp.get ("/resource/uri", [params], [authenticate=true])
+## ❤️ Support
 
-// Create a resource with "data" and optional URL params.
-$mp.post ("/resource/uri", data, [params])
+If you require technical support, please contact our support team at [developers.mercadopago.com](https://developers.mercadopago.com).
 
-// Update a resource with "data" and optional URL params.
-$mp.put ("/resource/uri", data, [params])
+## 🏻 License
 
-// Delete a resource with optional URL params.
-$mp.delete ("/resource/uri", [params])
 ```
-
- For example, if you want to get the Sites list (no params and no authentication):
-
-```ruby
-$sites = $mp.get ("/sites", null, false)
-
-puts $sites
+MIT license. Copyright (c) 2021 - Mercado Pago / Mercado Libre
+For more information, see the LICENSE file.
 ```

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
@@ -6,4 +8,4 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-task :default => :test
+task default: :test

data/docs/CODE_OF_CONDUCT_md.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>CODE_OF_CONDUCT - RDoc Documentation</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+  var index_rel_prefix = "./";
+</script>
+
+<script src="./js/navigation.js" defer></script>
+<script src="./js/search.js" defer></script>
+<script src="./js/search_index.js" defer></script>
+<script src="./js/searcher.js" defer></script>
+<script src="./js/darkfish.js" defer></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+<body id="top" role="document" class="file">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+<div class="nav-section">
+  <h3>Table of Contents</h3>
+
+  <ul class="link-list" role="directory">
+    <li><a href="#label-Contributor+Covenant+Code+of+Conduct">Contributor Covenant Code of Conduct</a>
+    <li><a href="#label-Our+Pledge">Our Pledge</a>
+    <li><a href="#label-Our+Standards">Our Standards</a>
+    <li><a href="#label-Our+Responsibilities">Our Responsibilities</a>
+    <li><a href="#label-Scope">Scope</a>
+    <li><a href="#label-Enforcement">Enforcement</a>
+    <li><a href="#label-Attribution">Attribution</a>
+  </ul>
+</div>
+
+
+  <div id="project-metadata">
+    
+<div id="fileindex-section" class="nav-section">
+  <h3>Pages</h3>
+
+  <ul class="link-list">
+    <li><a href="./CODE_OF_CONDUCT_md.html">CODE_OF_CONDUCT</a>
+    <li><a href="./CODING_GUIDELINES_md.html">CODING_GUIDELINES</a>
+    <li><a href="./CONTRIBUTING_md.html">CONTRIBUTING</a>
+    <li><a href="./LICENSE_txt.html">LICENSE</a>
+    <li><a href="./README_md.html">README</a>
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-label="Page CODE_OF_CONDUCT.md">
+
+<h1 id="label-Contributor+Covenant+Code+of+Conduct">Contributor Covenant Code of Conduct<span><a href="#label-Contributor+Covenant+Code+of+Conduct">&para;</a> <a href="#top">&uarr;</a></span></h1>
+
+<h2 id="label-Our+Pledge">Our Pledge<span><a href="#label-Our+Pledge">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>
+
+<h2 id="label-Our+Standards">Our Standards<span><a href="#label-Our+Standards">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Examples of behavior that contributes to creating a positive environment include:</p>
+<ul><li>
+<p>Using welcoming and inclusive language</p>
+</li><li>
+<p>Being respectful of differing viewpoints and experiences</p>
+</li><li>
+<p>Gracefully accepting constructive criticism</p>
+</li><li>
+<p>Focusing on what is best for the community</p>
+</li><li>
+<p>Showing empathy towards other community members</p>
+</li></ul>
+
+<p>Examples of unacceptable behavior by participants include:</p>
+<ul><li>
+<p>The use of sexualized language or imagery and unwelcome sexual attention or advances</p>
+</li><li>
+<p>Trolling, insulting/derogatory comments, and personal or political attacks</p>
+</li><li>
+<p>Public or private harassment</p>
+</li><li>
+<p>Publishing others&#39; private information, such as a physical or electronic  address, without explicit permission</p>
+</li><li>
+<p>Other conduct which could reasonably be considered inappropriate in a  professional setting</p>
+</li></ul>
+
+<h2 id="label-Our+Responsibilities">Our Responsibilities<span><a href="#label-Our+Responsibilities">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p>
+
+<p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>
+
+<h2 id="label-Scope">Scope<span><a href="#label-Scope">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>
+
+<h2 id="label-Enforcement">Enforcement<span><a href="#label-Enforcement">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at danilo.elias@mercadolivre.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p>
+
+<p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project&#39;s leadership.</p>
+
+<h2 id="label-Attribution">Attribution<span><a href="#label-Attribution">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>This Code of Conduct is adapted from the <a href="https://contributor-covenant.org">Contributor Covenant</a>, version 1.4, available at <a href="https://contributor-covenant.org/version/1/4/">contributor-covenant.org/version/1/4</a></p>
+
+</main>
+
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="https://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.3.0.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+

data/docs/CODING_GUIDELINES_md.html

@@ -0,0 +1,188 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>CODING_GUIDELINES - RDoc Documentation</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+  var index_rel_prefix = "./";
+</script>
+
+<script src="./js/navigation.js" defer></script>
+<script src="./js/search.js" defer></script>
+<script src="./js/search_index.js" defer></script>
+<script src="./js/searcher.js" defer></script>
+<script src="./js/darkfish.js" defer></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+<body id="top" role="document" class="file">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+<div class="nav-section">
+  <h3>Table of Contents</h3>
+
+  <ul class="link-list" role="directory">
+    <li><a href="#label-Coding+Guidelines">Coding Guidelines</a>
+    <li><a href="#label-Language+Guidelines">Language Guidelines</a>
+    <li><a href="#label-Code+Guidelines">Code Guidelines</a>
+    <li><a href="#label-Comment+Guidelines">Comment Guidelines</a>
+    <li><a href="#label-Branching+Guidelines">Branching Guidelines</a>
+    <li><a href="#label-Git+Guidelines">Git Guidelines</a>
+  </ul>
+</div>
+
+
+  <div id="project-metadata">
+    
+<div id="fileindex-section" class="nav-section">
+  <h3>Pages</h3>
+
+  <ul class="link-list">
+    <li><a href="./CODE_OF_CONDUCT_md.html">CODE_OF_CONDUCT</a>
+    <li><a href="./CODING_GUIDELINES_md.html">CODING_GUIDELINES</a>
+    <li><a href="./CONTRIBUTING_md.html">CONTRIBUTING</a>
+    <li><a href="./LICENSE_txt.html">LICENSE</a>
+    <li><a href="./README_md.html">README</a>
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-label="Page CODING_GUIDELINES.md">
+
+<h1 id="label-Coding+Guidelines">Coding Guidelines<span><a href="#label-Coding+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h1>
+
+<p>The Mercado Pago Ruby SDK is a collaborative effort from the start. The SDK team thinks that contributions from different developer will enrich it&#39;s feature set and make it more relevant to the community.</p>
+
+<p>However; absorbing all contributions as-is, while expedient, might lead to difficulties in maintenance of the codebase is left unchecked. Collaborative codebases often establish guidelines for contributors to ensure code remains maintainable over time. The effort to maintain the SDK is no different in this regard so a bit of guidance is in order.</p>
+
+<p>The purpose of this guide is to set a baseline for contributions. These guidelines are not intended to limit the tools at your disposal nor to rewire the way you think but rather to encourage good neighbor behavior.</p>
+
+<h2 id="label-Language+Guidelines">Language Guidelines<span><a href="#label-Language+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>We use <strong>english</strong> language. This is to be consistent everywhere, and to be considerate with developers that do not speak our native language.</p>
+
+<p>Therefore: source code, comments, documentation, commit messages, review comments, and any other kind of contribution <em>MUST</em> use english language.</p>
+
+<p>Typos are unavoidable, but try to reduce them by using a spellchecker. Most IDEs can be configured to run one automatically.</p>
+
+<h2 id="label-Code+Guidelines">Code Guidelines<span><a href="#label-Code+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h2>
+<ul><li>
+<p>Set your IDE to follow the <a href="https://editorconfig.org/">.editorconfig</a> in each repository.</p>
+</li><li>
+<p>Follow the <a href="https://github.com/rubocop/ruby-style-guide">RuboCop Ruby Style Guide</a>.</p>
+</li></ul>
+
+<p>Generally speaking, be conscious when contributing and try following the same style that the code in the SDK already has. If you have any doubts, just ask us!</p>
+
+<p>This rules will be enforced automatically when making a pull requests, and checks will fail if you do not follow them, resulting in your contribution being automatically rejected until fixed.</p>
+
+<h2 id="label-Comment+Guidelines">Comment Guidelines<span><a href="#label-Comment+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Comments in code are a hard thing to write, not because the words are difficult to produce but because it is hard to make relevant comments. Too much of it and people do not read comments (and it obfuscates code reading) and too little of it gives you no recourse but to read large portions of codebase to get insight as to what a feature/codeblock is doing. Both situations are undesirable and efforts should be made at all time to have a please comment reading experience</p>
+
+<p>As a general rule you would have to comment on decisions you made while coding that are not part of any specification.</p>
+
+<p>In particular you should always comment any decision that:</p>
+<ul><li>
+<p>Departs from common wisdom or convention (The <strong>why&#39;s</strong> are necessary).</p>
+</li><li>
+<p>Takes a significant amount of time to produce. A good rule of thumb here is that if you spent more than 1 hour thinking on how to produce a fragment of code that took 2 minutes of wrist time to write you should document your thinking to aid reader and allow for validation.</p>
+</li><li>
+<p>Need to preserve properties of the implementation. This is the case of performance sensitive portions of the codebase, goroutines synchronization, implementations of security primitives, congestion control algorithms, etc.</p>
+</li></ul>
+
+<p>As a general rule of what not to comment you should avoid:</p>
+<ul><li>
+<p>Commenting on structure of programs that is already part of a convention, specified or otherwise.</p>
+</li><li>
+<p>Having pedantic explanations of behavior that can be found by immediate examination of the surrounding code artifacts.</p>
+</li><li>
+<p>Commenting on behavior you cannot attest.</p>
+</li></ul>
+
+<h3 id="label-Branching+Guidelines">Branching Guidelines<span><a href="#label-Branching+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h3>
+
+<p>Currently <code>master</code> is our only long term branch, below a few suggestions of short term branches naming:</p>
+<ul><li>
+<p><code>hotfix/something-needs-fix</code>: Small routine patches in code to features already there.</p>
+</li><li>
+<p><code>feature/something-new</code>: A new feature or a change in a existent feature. Beware of breaking changes that would require a major version bump.</p>
+</li><li>
+<p><code>doc/improves-documentation-for-this-feature</code>: If you add or change documentation with no impact to the source code.</p>
+</li></ul>
+
+<h3 id="label-Git+Guidelines">Git Guidelines<span><a href="#label-Git+Guidelines">&para;</a> <a href="#top">&uarr;</a></span></h3>
+
+<p>All commits <strong>SHOULD</strong> follow the <a href="https://chris.beams.io/posts/git-commit">seven rules of a great Git commit message</a>:</p>
+<ol><li>
+<p>Separate subject from body with a blank line.</p>
+</li><li>
+<p>Limit the subject line to 72 characters.</p>
+</li><li>
+<p>Capitalize the subject line.</p>
+</li><li>
+<p>Do not end the subject line with a period.</p>
+</li><li>
+<p>Use the imperative mood in the subject line.</p>
+</li><li>
+<p>Wrap the body at 72 characters.</p>
+</li><li>
+<p>Use the body to explain what and why vs. how.</p>
+</li></ol>
+
+<p>Commits such as “fix tests”, “now it&#39;s working” and many other common messages we find usually in code <strong>WON&#39;T</strong> be accepted.</p>
+
+<p>Ideally we would like to enforce these rules, but we are realistic and understand that it might be a big change for some people. So unless deviating heavily from what was stated we might accept your commits even if not following these rules perfectly.</p>
+
+<p>Please avoid taking to much time to deliver code, and always <a href="https://git-scm.com/docs/git-rebase">rebase</a> your code to avoid reverse merge commits.</p>
+
+<p>When reviewing, check if the PR adheres to <a href="https://github.com/rubocop/ruby-style-guide">RuboCop Ruby Style Guide</a>.</p>
+
+</main>
+
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="https://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.3.0.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+