Make API response accessible on returned API structs

Makes an API response struct containing niceties like the raw response
body, status, and request ID accessible via API resource structs
returned from client functions. For example:

    customer, err := customer.New(params)
    fmt.Printf("request ID = %s\n", customer.LastResponse.RequestID)

This is a feature that already exists in other language API libraries
and which is requested occasionally here, usually for various situations
involving more complex usage or desire for better observability.

-- Implementation

We introduce a few new types to make this work:

* `APIResponse`: Represents a response from the Stripe API and includes
  things like request ID, status, and headers. I elected to create my
  own object instead of reusing `http.Response` because it gives us a
  little more flexibility, and hides many of myriad of fields exposed by
  the `http` version, which will hopefully give us a little more API
  stability/forward compatibility.

* `APIResource`: A struct that contains `LastResponse` and is meant to
  represent any type that can we returned from a Stripe API endpoint. A
  coupon is an `APIResource` and so is a list object. This struct is
  embedded in response structs where appropriate across the whole API
  surface area (e.g. `Coupon`, `ListMeta`, etc.).

* `LastResponseGetter`: A very basic interface to an object that looks
  like an `APIResource`. This isn't strictly necessary, but gives us
  slightly more flexibility around the API and makes backward
  compatibility a little bit better for non-standard use cases (see the
  section on that below).

`stripe.Do` and other backend calls all start taking objects which are
`LastResponseGetter` instead of `interface{}`. This provides us with some
type safety around forgetting to include an embedded `APIResource` on
structs that should have it by making the compiler balk.

As `stripe.Do` finishes running a request, it generates an `APIResponse`
object and sets it onto the API resource type it's deserializing and
returning (e.g. a `Coupon`).

Errors also embed `APIResource` and similarly get access to the same set
of fields as response resources, although in their case some of the
fields provided in `APIResponse` are duplicates of what they had
already (see "Caveats" below).

-- Backwards compatibility

This is a minor breaking change in that backend implementations methods
like `Do` now take `LastResponseGetter` instead of `interface{}`, which
is more strict.

The good news though is that:

* Very few users should be using any of these even if they're
  technically public. The resource-specific clients packages tend to do
  all the work.

* Users who are broken should have a very easy time updating code.
  Mostly this will just involve adding `APIResource` to structs that were
  being passed in.

-- Naming

* `APIResponse`: Went with this instead of `StripeResponse` as we see in
  some other libraries because the linter will complain that it
  "stutters" when used outside of the package (meaning, uses the same
  word twice in a row), i.e. `stripe.StripeResponse`. `APIResponse`
  sorts nicely with `APIResource` though, so I think it's okay.

* `LastResponse`: Copied the "last" convention from other API libraries
  like stripe-python.

* `LastResponseGetter`: Given an "-er" name per Go convention around
  small interfaces that are basically one liners -- e.g. `Reader`,
  `Writer, `Formatter`, `CloseNotifier`, etc. I can see the argument
  that this maybe should just be `APIResourceInterface` or something
  like that in case we start adding new things, but I figure at that
  point we can either rename it, or create a parent interface that
  encapsulates it:

    ``` go
    type APIResourceInterface interface {
        LastResponseGetter
    }
    ```

-- Caveats

* We only set the last response for top-level returned objects. For
  example, an `InvoiceItem` is an API resource, but if it's returned
  under an `Invoice`, only `Invoice` has a non-nil `LastResponse`. The
  same applies for all resources under list objects. I figure that doing
  it this way is more performant and makes a little bit more intuitive
  sense. Users should be able to work around it if they need to.

* There is some duplication between `LastResponse` and some other fields
  that already existed on `stripe.Error` because the latter was already
  exposing some of this information, e.g. `RequestID`. I figure this is
  okay: it's nice that `stripe.Error` is a `LastResponseGetter` for
  consistency with other API resources. The duplication is a little
  unfortunate, but not that big of a deal.

account.go

@@ -458,6 +458,7 @@ type AccountTOSAcceptance struct {
 // Account is the resource representing your Stripe account.
 // For more details see https://stripe.com/docs/api/#account.
 type Account struct {
+	APIResource
 	BusinessProfile  *AccountBusinessProfile `json:"business_profile"`
 	BusinessType     AccountBusinessType     `json:"business_type"`
 	Capabilities     *AccountCapabilities    `json:"capabilities"`

accountlink.go

@@ -31,6 +31,7 @@ type AccountLinkParams struct {
 // AccountLink is the resource representing an account link.
 // For more details see https://stripe.com/docs/api/#account_links.
 type AccountLink struct {
+	APIResource
 	Created   int64  `json:"created"`
 	ExpiresAt int64  `json:"expires_at"`
 	Object    string `json:"object"`

applepaydomain.go

@@ -8,6 +8,7 @@ type ApplePayDomainParams struct {
 
 // ApplePayDomain is the resource representing a Stripe ApplePayDomain object
 type ApplePayDomain struct {
+	APIResource
 	Created    int64  `json:"created"`
 	Deleted    bool   `json:"deleted"`
 	DomainName string `json:"domain_name"`

balance.go

@@ -24,6 +24,7 @@ type BalanceParams struct {
 // Balance is the resource representing your Stripe balance.
 // For more details see https://stripe.com/docs/api/#balance.
 type Balance struct {
+	APIResource
 	Available       []*Amount `json:"available"`
 	ConnectReserved []*Amount `json:"connect_reserved"`
 	Livemode        bool      `json:"livemode"`

balancetransaction.go

@@ -126,6 +126,7 @@ type BalanceTransactionListParams struct {
 // BalanceTransaction is the resource representing the balance transaction.
 // For more details see https://stripe.com/docs/api/#balance.
 type BalanceTransaction struct {
+	APIResource
 	Amount            int64                               `json:"amount"`
 	AvailableOn       int64                               `json:"available_on"`
 	Created           int64                               `json:"created"`

bankaccount.go

@@ -141,6 +141,7 @@ func (p *BankAccountListParams) AppendTo(body *form.Values, keyParts []string) {
 
 // BankAccount represents a Stripe bank account.
 type BankAccount struct {
+	APIResource
 	Account            *Account                     `json:"account"`
 	AccountHolderName  string                       `json:"account_holder_name"`
 	AccountHolderType  BankAccountAccountHolderType `json:"account_holder_type"`

bitcoinreceiver.go

@@ -16,6 +16,7 @@ type BitcoinReceiverListParams struct {
 // BitcoinReceiver is the resource representing a Stripe bitcoin receiver.
 // For more details see https://stripe.com/docs/api/#bitcoin_receivers
 type BitcoinReceiver struct {
+	APIResource
 	Active                bool                    `json:"active"`
 	Amount                int64                   `json:"amount"`
 	AmountReceived        int64                   `json:"amount_received"`

capability.go

@@ -55,6 +55,7 @@ type CapabilityRequirements struct {
 // Capability is the resource representing a Stripe capability.
 // For more details see https://stripe.com/docs/api/capabilities
 type Capability struct {
+	APIResource
 	Account      *Account                `json:"account"`
 	ID           string                  `json:"id"`
 	Object       string                  `json:"object"`

card.go

@@ -197,6 +197,8 @@ func (p *CardListParams) AppendTo(body *form.Values, keyParts []string) {
 // Card is the resource representing a Stripe credit/debit card.
 // For more details see https://stripe.com/docs/api#cards.
 type Card struct {
+	APIResource
+
 	AddressCity            string                      `json:"address_city"`
 	AddressCountry         string                      `json:"address_country"`
 	AddressLine1           string                      `json:"address_line1"`

charge.go

@@ -458,6 +458,7 @@ type ChargeTransferData struct {
 // Charge is the resource representing a Stripe charge.
 // For more details see https://stripe.com/docs/api#charges.
 type Charge struct {
+	APIResource
 	Amount                    int64                       `json:"amount"`
 	AmountRefunded            int64                       `json:"amount_refunded"`
 	Application               *Application                `json:"application"`

checkout_session.go

@@ -163,6 +163,7 @@ type CheckoutSessionShippingAddressCollection struct {
 // CheckoutSession is the resource representing a Stripe checkout session.
 // For more details see https://stripe.com/docs/api/checkout/sessions/object
 type CheckoutSession struct {
+	APIResource
 	CancelURL                 string                                    `json:"cancel_url"`
 	ClientReferenceID         string                                    `json:"client_reference_id"`
 	Customer                  *Customer                                 `json:"customer"`

countryspec.go

@@ -13,6 +13,7 @@ type VerificationFieldsList struct {
 // CountrySpec is the resource representing the rules required for a Stripe account.
 // For more details see https://stripe.com/docs/api/#country_specs.
 type CountrySpec struct {
+	APIResource
 	DefaultCurrency                Currency                                        `json:"default_currency"`
 	ID                             string                                          `json:"id"`
 	SupportedBankAccountCurrencies map[Currency][]Country                          `json:"supported_bank_account_currencies"`

coupon.go

@@ -38,6 +38,7 @@ type CouponListParams struct {
 // Coupon is the resource representing a Stripe coupon.
 // For more details see https://stripe.com/docs/api#coupons.
 type Coupon struct {
+	APIResource
 	AmountOff        int64             `json:"amount_off"`
 	Created          int64             `json:"created"`
 	Currency         Currency          `json:"currency"`

creditnote.go

@@ -128,6 +128,7 @@ type CreditNoteTaxAmount struct {
 // CreditNote is the resource representing a Stripe credit note.
 // For more details see https://stripe.com/docs/api/credit_notes/object.
 type CreditNote struct {
+	APIResource
 	Amount                     int64                       `json:"amount"`
 	Created                    int64                       `json:"created"`
 	Currency                   Currency                    `json:"currency"`

customer.go

@@ -92,6 +92,7 @@ type CustomerListParams struct {
 // Customer is the resource representing a Stripe customer.
 // For more details see https://stripe.com/docs/api#customers.
 type Customer struct {
+	APIResource
 	Address             Address                  `json:"address"`
 	Balance             int64                    `json:"balance"`
 	Created             int64                    `json:"created"`

customerbalancetransaction.go

@@ -39,6 +39,7 @@ type CustomerBalanceTransactionListParams struct {
 // CustomerBalanceTransaction is the resource representing a customer balance transaction.
 // For more details see https://stripe.com/docs/api/customers/customer_balance_transaction_object
 type CustomerBalanceTransaction struct {
+	APIResource
 	Amount        int64                          `json:"amount"`
 	Created       int64                          `json:"created"`
 	CreditNote    *CreditNote                    `json:"credit_note"`

discount.go

@@ -8,6 +8,7 @@ type DiscountParams struct {
 // Discount is the resource representing a Stripe discount.
 // For more details see https://stripe.com/docs/api#discounts.
 type Discount struct {
+	APIResource
 	Coupon       *Coupon `json:"coupon"`
 	Customer     string  `json:"customer"`
 	Deleted      bool    `json:"deleted"`

dispute.go

@@ -87,6 +87,7 @@ type DisputeListParams struct {
 // Dispute is the resource representing a Stripe dispute.
 // For more details see https://stripe.com/docs/api#disputes.
 type Dispute struct {
+	APIResource
 	Amount              int64                 `json:"amount"`
 	BalanceTransactions []*BalanceTransaction `json:"balance_transactions"`
 	Charge              *Charge               `json:"charge"`

ephemeralkey.go

@@ -14,6 +14,8 @@ type EphemeralKeyParams struct {
 // EphemeralKey is the resource representing a Stripe ephemeral key. This is used by Mobile SDKs
 // to for example manage a Customer's payment methods.
 type EphemeralKey struct {
+	APIResource
+
 	AssociatedObjects []struct {
 		ID   string `json:"id"`
 		Type string `json:"type"`

error.go

@@ -171,6 +171,8 @@ const (
 // Error is the response returned when a call is unsuccessful.
 // For more details see  https://stripe.com/docs/api#errors.
 type Error struct {
+	APIResource
+
 	ChargeID    string      `json:"charge,omitempty"`
 	Code        ErrorCode   `json:"code,omitempty"`
 	DeclineCode DeclineCode `json:"decline_code,omitempty"`

event.go

@@ -9,6 +9,7 @@ import (
 // Event is the resource representing a Stripe event.
 // For more details see https://stripe.com/docs/api#events.
 type Event struct {
+	APIResource
 	Account         string        `json:"account"`
 	Created         int64         `json:"created"`
 	Data            *EventData    `json:"data"`

exchangerate.go

@@ -3,6 +3,7 @@ package stripe
 // ExchangeRate is the resource representing the currency exchange rates at
 // a given time.
 type ExchangeRate struct {
+	APIResource
 	ID    string               `json:"id"`
 	Rates map[Currency]float64 `json:"rates"`
 }

fee.go

@@ -20,6 +20,7 @@ type ApplicationFeeListParams struct {
 // ApplicationFee is the resource representing a Stripe application fee.
 // For more details see https://stripe.com/docs/api#application_fees.
 type ApplicationFee struct {
+	APIResource
 	Account                *Account            `json:"account"`
 	Amount                 int64               `json:"amount"`
 	AmountRefunded         int64               `json:"amount_refunded"`

feerefund.go

@@ -22,6 +22,7 @@ type FeeRefundListParams struct {
 // FeeRefund is the resource representing a Stripe application fee refund.
 // For more details see https://stripe.com/docs/api#fee_refunds.
 type FeeRefund struct {
+	APIResource
 	Amount             int64               `json:"amount"`
 	BalanceTransaction *BalanceTransaction `json:"balance_transaction"`
 	Created            int64               `json:"created"`

file.go

@@ -65,6 +65,7 @@ type FileListParams struct {
 // File is the resource representing a Stripe file.
 // For more details see https://stripe.com/docs/api#file_object.
 type File struct {
+	APIResource
 	Created  int64         `json:"created"`
 	ID       string        `json:"id"`
 	Filename string        `json:"filename"`

filelink.go

@@ -23,6 +23,7 @@ type FileLinkListParams struct {
 // FileLink is the resource representing a Stripe file link.
 // For more details see https://stripe.com/docs/api#file_links.
 type FileLink struct {
+	APIResource
 	Created   int64             `json:"created"`
 	Expired   bool              `json:"expired"`
 	ExpiresAt int64             `json:"expires_at"`

invoice.go

@@ -209,6 +209,7 @@ type InvoiceVoidParams struct {
 // Invoice is the resource representing a Stripe invoice.
 // For more details see https://stripe.com/docs/api#invoice_object.
 type Invoice struct {
+	APIResource
 	AccountCountry               string                   `json:"account_country"`
 	AccountName                  string                   `json:"account_name"`
 	AmountDue                    int64                    `json:"amount_due"`

invoiceitem.go

@@ -40,6 +40,7 @@ type InvoiceItemListParams struct {
 // InvoiceItem is the resource represneting a Stripe invoice item.
 // For more details see https://stripe.com/docs/api#invoiceitems.
 type InvoiceItem struct {
+	APIResource
 	Amount            int64             `json:"amount"`
 	Currency          Currency          `json:"currency"`
 	Customer          *Customer         `json:"customer"`

issuing_authorization.go

@@ -223,6 +223,7 @@ type IssuingAuthorizationVerificationData struct {
 
 // IssuingAuthorization is the resource representing a Stripe issuing authorization.
 type IssuingAuthorization struct {
+	APIResource
 	Amount              int64                                   `json:"amount"`
 	Approved            bool                                    `json:"approved"`
 	AuthorizationMethod IssuingAuthorizationAuthorizationMethod `json:"authorization_method"`

issuing_card.go

@@ -212,6 +212,7 @@ type IssuingCardListParams struct {
 
 // IssuingCardDetails is the resource representing issuing card details.
 type IssuingCardDetails struct {
+	APIResource
 	Card     *IssuingCard `json:"card"`
 	CVC      string       `json:"cvc"`
 	ExpMonth *string      `form:"exp_month"`
@@ -286,6 +287,7 @@ type IssuingCardSpendingControls struct {
 
 // IssuingCard is the resource representing a Stripe issuing card.
 type IssuingCard struct {
+	APIResource
 	Billing           *IssuingBilling              `json:"billing"`
 	Brand             string                       `json:"brand"`
 	Cardholder        *IssuingCardholder           `json:"cardholder"`

issuing_cardholder.go

@@ -214,6 +214,8 @@ type IssuingCardholderSpendingControls struct {
 
 // IssuingCardholder is the resource representing a Stripe issuing cardholder.
 type IssuingCardholder struct {
+	APIResource
+
 	Billing          *IssuingBilling                    `json:"billing"`
 	Company          *IssuingCardholderCompany          `json:"company"`
 	Created          int64                              `json:"created"`

issuing_dispute.go

@@ -84,6 +84,7 @@ type IssuingDisputeEvidence struct {
 
 // IssuingDispute is the resource representing an issuing dispute.
 type IssuingDispute struct {
+	APIResource
 	Amount      int64                   `json:"amount"`
 	Created     int64                   `json:"created"`
 	Currency    Currency                `json:"currency"`

issuing_transaction.go

@@ -30,6 +30,7 @@ type IssuingTransactionListParams struct {
 
 // IssuingTransaction is the resource representing a Stripe issuing transaction.
 type IssuingTransaction struct {
+	APIResource
 	Amount             int64                  `json:"amount"`
 	Authorization      *IssuingAuthorization  `json:"authorization"`
 	BalanceTransaction *BalanceTransaction    `json:"balance_transaction"`

loginlink.go

@@ -11,6 +11,7 @@ type LoginLinkParams struct {
 // LoginLink is the resource representing a login link for Express accounts.
 // For more details see https://stripe.com/docs/api#login_link_object
 type LoginLink struct {
+	APIResource
 	Created int64  `json:"created"`
 	URL     string `json:"url"`
 }

mandate.go

@@ -94,6 +94,7 @@ type MandateSingleUse struct {
 
 // Mandate is the resource representing a Mandate.
 type Mandate struct {
+	APIResource
 	CustomerAcceptance   *MandateCustomerAcceptance   `json:"customer_acceptance"`
 	ID                   string                       `json:"id"`
 	Livemode             bool                         `json:"livemode"`

oauth.go

@@ -111,6 +111,8 @@ type OAuthTokenParams struct {
 // OAuthToken is the value of the OAuthToken from OAuth flow.
 // https://stripe.com/docs/connect/oauth-reference#post-token
 type OAuthToken struct {
+	APIResource
+
 	Livemode     bool           `json:"livemode"`
 	Scope        OAuthScopeType `json:"scope"`
 	StripeUserID string         `json:"stripe_user_id"`
@@ -125,5 +127,6 @@ type OAuthToken struct {
 // Deauthorize is the value of the return from deauthorizing.
 // https://stripe.com/docs/connect/oauth-reference#post-deauthorize
 type Deauthorize struct {
+	APIResource
 	StripeUserID string `json:"stripe_user_id"`
 }

order.go

@@ -123,6 +123,7 @@ type DeliveryEstimate struct {
 // Order is the resource representing a Stripe charge.
 // For more details see https://stripe.com/docs/api#orders.
 type Order struct {
+	APIResource
 	Amount                 int64             `json:"amount"`
 	AmountReturned         int64             `json:"amount_returned"`
 	Application            string            `json:"application"`

orderreturn.go

@@ -12,6 +12,7 @@ type OrderReturnParams struct {
 // OrderReturn is the resource representing an order return.
 // For more details see https://stripe.com/docs/api#order_returns.
 type OrderReturn struct {
+	APIResource
 	Amount   int64        `json:"amount"`
 	Created  int64        `json:"created"`
 	Currency Currency     `json:"currency"`

params.go

@@ -70,6 +70,7 @@ func (f Filters) AppendTo(body *form.Values, keyParts []string) {
 // of List iterators. The Count property is only populated if the
 // total_count include option is passed in (see tests for example).
 type ListMeta struct {
+	APIResource
 	HasMore    bool   `json:"has_more"`
 	TotalCount uint32 `json:"total_count"`
 	URL        string `json:"url"`

paymentintent.go

@@ -292,6 +292,7 @@ type PaymentIntentTransferData struct {
 // PaymentIntent is the resource representing a Stripe payout.
 // For more details see https://stripe.com/docs/api#payment_intents.
 type PaymentIntent struct {
+	APIResource
 	Amount                    int64                              `json:"amount"`
 	AmountCapturable          int64                              `json:"amount_capturable"`
 	AmountReceived            int64                              `json:"amount_received"`

paymentmethod.go

@@ -234,6 +234,7 @@ type PaymentMethodSepaDebit struct {
 
 // PaymentMethod is the resource representing a PaymentMethod.
 type PaymentMethod struct {
+	APIResource
 	AUBECSDebit    *PaymentMethodAUBECSDebit `json:"au_becs_debit"`
 	BillingDetails *BillingDetails           `json:"billing_details"`
 	Card           *PaymentMethodCard        `json:"card"`

paymentsource.go

@@ -87,6 +87,7 @@ func SourceParamsFor(obj interface{}) (*SourceParams, error) {
 // The Type should indicate which object is fleshed out (eg. BitcoinReceiver or Card)
 // For more details see https://stripe.com/docs/api#retrieve_charge
 type PaymentSource struct {
+	APIResource
 	BankAccount     *BankAccount      `json:"-"`
 	BitcoinReceiver *BitcoinReceiver  `json:"-"`
 	Card            *Card             `json:"-"`

payout.go

@@ -108,6 +108,7 @@ type PayoutListParams struct {
 // Payout is the resource representing a Stripe payout.
 // For more details see https://stripe.com/docs/api#payouts.
 type Payout struct {
+	APIResource
 	Amount                    int64               `json:"amount"`
 	ArrivalDate               int64               `json:"arrival_date"`
 	Automatic                 bool                `json:"automatic"`

person.go

@@ -164,6 +164,7 @@ type PersonVerification struct {
 // Person is the resource representing a Stripe person.
 // For more details see https://stripe.com/docs/api#persons.
 type Person struct {
+	APIResource
 	Account          string              `json:"account"`
 	Address          *AccountAddress     `json:"address"`
 	AddressKana      *AccountAddress     `json:"address_kana"`

plan.go

@@ -68,6 +68,7 @@ const (
 // Plan is the resource representing a Stripe plan.
 // For more details see https://stripe.com/docs/api#plans.
 type Plan struct {
+	APIResource
 	Active          bool                `json:"active"`
 	AggregateUsage  string              `json:"aggregate_usage"`
 	Amount          int64               `json:"amount"`

product.go

@@ -51,6 +51,7 @@ type PackageDimensions struct {
 // Product is the resource representing a Stripe product.
 // For more details see https://stripe.com/docs/api#products.
 type Product struct {
+	APIResource
 	Active              bool               `json:"active"`
 	Attributes          []string           `json:"attributes"`
 	Caption             string             `json:"caption"`

radar_earlyfraudwarning.go

@@ -39,6 +39,7 @@ type RadarEarlyFraudWarningList struct {
 // RadarEarlyFraudWarning is the resource representing an early fraud warning. For
 // more details see https://stripe.com/docs/api/early_fraud_warnings/object.
 type RadarEarlyFraudWarning struct {
+	APIResource
 	Actionable bool                            `json:"actionable"`
 	Charge     *Charge                         `json:"charge"`
 	Created    int64                           `json:"created"`