[browser-payment-api] Should the payment API be more conversational vs. rigid? (#51)

Partial migration from https://github.com/w3c/webpayments/issues/55:

@dlongley proposed a more conversational shape to the browser payment API here:

http://sites.local/web-payments-browser-api/checkout-api.html#the-checkout-interface

For example:

```javascript
var checkout = new Checkout();
checkout
  .send('paymentItem', paymentItems)  // send line item estimate to UA
  .request('shippingAddress')         // request shippingAddress from UA
  .start()                            // start the checkout UI
  .then(finishCheckout);              // checkout UI has collected the info
```

and @dlongley noted this is how it would work:


With the Checkout API, we want to be able to do things like make shipping options depend on the shipping address selected. What we're exploring essentially works like this:

1. A Checkout object is created by a webpage.
1. A call to `send` the line item estimate is made on the Checkout object. This call essentially just sets "options" that will be read once the checkout is started.
1. A call to `request` shipping address is made on the Checkout object. Again, this call is like setting options as it simply "indicates" that a shipping address is requested. It won't do anything until the checkout is started.
1. A call to start checkout is made on the Checkout object. This returns a Promise that will settle once the user clicks "Buy".
1. The browser UI opens and sees the line item estimate and displays it. It sees that shipping was requested, so it knows to show the user a shipping address selection UI. The "Buy" button will be disabled.
1. The user selects a shipping address and a `shippingAddressChanged` event is dispatched.
1. An event handler may optionally call `request` to request shipping option selection along with a list of possible shipping options (or a Promise that resolves to such a list).
1. Once event dispatching has completed, if `request` was called, it will wait for its Promise to settle and then display the shipping options in the UI, keeping the "Buy" button disabled. Otherwise, there's nothing to wait on and the "Buy" button will be enabled.
1. The user selects a shipping option and a `shippingOptionChanged` event is dispatched.
1. An event handler may optionally call `send` to send updated checkout details such as new calculated line items that include, eg: shipping, tax. Again, this information can be sent as a Promise, to enable the website to generate this information asynchronously. Similarly, `request` can also be called to request other information at this point (that depended on shipping option selection).
1. Once event dispatching has completed, if `request` was called, it will wait for its Promise to settle and then display the UI for whatever was requested this time, keeping the "Buy" button disabled. Otherwise, there's nothing to wait on and the "Buy" button will be enabled.
1. The user clicks "Buy" and the Promise for `checkout.start` resolves.
1. The webpage generates a payment request message and passes it to `checkout.finish`.
1. The browser UI shows the Payment App selection UI to complete the purchase.

So, the question is - do we want this sort of conversational API vs. the more rigid API proposed in the current spec?

---
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/issues/51