Auto-Pagination Proposal

[chanks]

Proposal of how auto-pagination might be implemented, using #196 as a base since I wanted to make sure to maintain the error behavior. We introduce iterator classes that simply wrap the existing API request logic and call it as they're iterated over.

Notes:

• Two iterator types (PageIterator and ItemIterator) depending on whether the calling user wants to iterate over pages of items or the items themselves.
  • The default returned from list methods is ItemIterator, but you can call #pages on it to use a PageIterator instead.
• PageIterator and ItemIterator call the API lazily - if you break iteration early, you won't incur unnecessary API calls.
• PageIterator and ItemIterator both include Enumerable, so many of the methods that work on any other Ruby collection object (filter, map, etc) will also work on these iterators.
• PageIterator and ItemIterator each support manual iteration via get_next and has_next? methods, in case the caller wants to implement something more complicated and simple iteration isn't a good fit.
• I considered nesting these directly under Square instead of Square::Internal since they're part of a public API, but wanted to avoid polluting that namespace, and we don't expect users to use these type names directly in their code like they do the public error types, so I think it's fine.
• The added tests demonstrate the usage and are runnable with ruby -Itest test/square/internal/iterators/test_item_iterator.rb