Remove legacy parameter support in invoices.retrieveUpcoming()

[ob-stripe]

r? @rattrayalex-stripe @remi-stripe
cc @stripe/api-libraries @irace-stripe

• Removes support for legacy customer and subscription parameters in invoices.retrieveUpcoming(). All parameters must now be provided in a hash.

• While I was at it, I also noticed that retrieveLines() should really be called listLineItems() because it returns a list object containing a list of line_items.

• I also added listUpcomingLineItems() because I think that's much cleaner than telling users to use listLines() with "upcoming" as the ID.

[remi-stripe]

Flagged a minor comment otherwise LGTM but deferring to alex.

[remi-stripe]

In other libraries we do this by passing upcoming as the id.

[rattrayalex-stripe]

I would actually think this'd be listUpcomingLines...

[rattrayalex-stripe]

I'm also uncomfortable-but-peaceful with an 'upcoming' id if that's what we do in other libs (and if it has not caused user confusion/sadness)

[ob-stripe]

I renamed it listUpcomingLineItems, which is consistent with what we do in .NET: https://stripe.com/docs/api/invoices/upcoming_invoice_lines?lang=dotnet.

We should also add this to other languages because having users pass a magic ID as a string is terrible.

[rattrayalex-stripe]

Thanks for doing this!
Looks great. Would like to settle the question around listLinesUpcoming, then we can ship.

ptal @ob-stripe

[ob-stripe]

@remi-stripe @rattrayalex-stripe Are you both okay with listUpcomingLineItems()?

[rattrayalex-stripe]

I am okay with that!
Per slack, remi is also okay with it.

LGTM

Thanks for this ob!

[ob-stripe]

Cool. I updated the WIP migration guide with the changes here. Pulling this in!