Define PaymentResponse.prototype.retry() method (#720)

marcoscaceres · web-flow · commit ee56f254b6b3 · 2018-06-21T12:10:49.000-04:00
Sets foundation for the method, which is then expanded upon by
other pull requests.
diff --git a/index.html b/index.html
@@ -666,9 +666,8 @@ <h2>
                     <var>paymentMethod</var>.<a data-lt=
                     "PaymentMethodData.supportedMethods">supportedMethods</a>.
                     If it returns false, then throw a <a>RangeError</a>
-                    exception and terminate this algorithm. Optionally, inform
-                    the developer that the payment method identifier is
-                    invalid.
+                    exception. Optionally, inform the developer that the
+                    payment method identifier is invalid.
                   </li>
                   <li>If the <a data-lt="PaymentMethodData.data">data</a>
                   member of <var>paymentMethod</var> is missing, let
@@ -842,6 +841,8 @@ <h2>
           <li>Set <var>request</var>.<a>[[\serializedMethodData]]</a> to <var>
             serializedMethodData</var>.
           </li>
+          <li>Set <var>request</var>.<a>[[\response]]</a> to null.
+          </li>
           <li>Set the value of <var>request</var>'s <a data-lt=
           "PaymentRequest.shippingOption">shippingOption</a> attribute to <var>
             selectedShippingOption</var>.
@@ -900,9 +901,9 @@ <h2>
         <ol class="algorithm">
           <li data-tests=
           "payment-request-show-method-manual.https.html, show-method-postmessage-manual.https.html">
-          If the method was not <a>triggered by user activation</a>, return a
-          promise rejected with a "<a>SecurityError</a>" <a>DOMException</a>
-          and terminate this algorithm.
+          If the method was not <a>triggered by user activation</a>, return <a>
+            a promise rejected with</a> with a "<a>SecurityError</a>"
+            <a>DOMException</a>.
           </li>
           <li>Let <var>request</var> be the <a>context object</a>.
           </li>
@@ -1120,10 +1121,14 @@ <h2>
         <ol class="algorithm">
           <li>Let <var>request</var> be the <a>context object</a>.
           </li>
+          <li>If <var>request</var>.<a>[[\response]]</a> is not null, and <var>
+            request</var>.<a>[[\response]]</a>.<a>[[\retryPromise]]</a> is not
+            null, return <a>a promise rejected with</a> an
+            "<a>InvalidStateError</a>" <a>DOMException</a>.
+          </li>
           <li>If the value of <var>request</var>.<a>[[\state]]</a> is not
-          "<a>interactive</a>" then return a promise rejected with a
-          "<a>InvalidStateError</a>" <a>DOMException</a> and terminate this
-          algorithm.
+          "<a>interactive</a>" then return <a>a promise rejected with</a> an
+          "<a>InvalidStateError</a>" <a>DOMException</a>.
           </li>
           <li>Let <var>promise</var> be <a>a new promise</a>.
           </li>
@@ -1180,8 +1185,9 @@ <h2>
           then return <a>a promise rejected with</a> an
           "<a>InvalidStateError</a>" <a>DOMException</a>.
           </li>
-          <li>Optionally, at the <a>user agent</a>'s discretion, return a
-          promise rejected with a "<a>NotAllowedError</a>" <a>DOMException</a>.
+          <li>Optionally, at the <a>user agent</a>'s discretion, return <a>a
+          promise rejected with</a> a "<a>NotAllowedError</a>"
+          <a>DOMException</a>.
             <p class="note" data-link-for="PaymentRequest">
               This allows user agents to apply heuristics to detect and prevent
               abuse of the <a>canMakePayment()</a> method for fingerprinting
@@ -1443,6 +1449,15 @@ <h2>
               accepts the payment request.
             </td>
           </tr>
+          <tr>
+            <td>
+              <dfn>[[\response]]</dfn>
+            </td>
+            <td>
+              Null, or the <a>PaymentResponse</a> instantiated by this
+              <a>PaymentRequest</a>.
+            </td>
+          </tr>
         </table>
       </section>
     </section>
@@ -3150,12 +3165,83 @@ <h2>
           readonly attribute DOMString? payerPhone;
 
           Promise&lt;void&gt; complete(optional PaymentComplete result = "unknown");
+          Promise&lt;void&gt; retry();
         };
       </pre>
       <p class="note">
         A <a>PaymentResponse</a> is returned when a user has selected a payment
         method and approved a payment request.
       </p>
+      <section>
+        <h2>
+          <dfn>retry()</dfn> method
+        </h2>
+        <p data-tests="payment-response/retry-method-manual.https.html">
+          The <a>retry()</a> method MUST act as follows:
+        </p>
+        <ol class="algorithm">
+          <li>Let <var>response</var> be the <a>context object</a>.
+          </li>
+          <li>Let <var>request</var> be
+          <var>response</var>.<a>[[\request]]</a>.
+          </li>
+          <li>Let <var>document</var> be <var>request</var>'s <a data-cite=
+          "!HTML#concept-relevant-global">relevant global object</a>'s
+          <a data-cite="!HTML#concept-document-window">associated Document</a>.
+          </li>
+          <li data-tests=
+          "payment-response/rejects_if_not_active-manual.https.html">If
+          <var>document</var> is not <a data-cite="!HTML#fully-active">fully
+          active</a>, then return <a>a promise rejected with</a> an
+          "<a>AbortError</a>" <a>DOMException</a>.
+          </li>
+          <li>If <var>response</var>.<a>[[\complete]]</a> is true, return <a>a
+          promise rejected with</a> an "<a>InvalidStateError</a>"
+          <a>DOMException</a>.
+          </li>
+          <li>If <var>response</var>.<a>[[\retryPromise]]</a> is not null,
+          return <a>a promise rejected with</a> an "<a>InvalidStateError</a>"
+          <a>DOMException</a>.
+          </li>
+          <li>Set <var>request</var>.<a>[[\state]]</a> to "<a>interactive</a>".
+          </li>
+          <li>Let <var>retryPromise</var> be <a>a new promise</a>.
+          </li>
+          <li>Set <var>response</var>.<a>[[\retryPromise]]</a> to
+          <var>retryPromise</var>.
+          </li>
+          <li>In the payments UI, indicate to the end-user that something is
+          wrong with the user-provided data of the payment response.
+          </li>
+          <li data-tests=
+          "payment-request/payment-response/rejects_if_not_active-manual.https.html">
+          If <var>document</var> stops being <a data-cite="!HTML#fully-active">
+            fully active</a> while the user interface is being shown, or no
+            longer is by the time this step is reached, then:
+            <ol>
+              <li>Close down the user interface.
+              </li>
+              <li>Set the <a>user agent</a>'s <a>payment request is showing</a>
+              boolean to false.
+              </li>
+              <li>Reject <var>retryPromise</var> with an "<a>AbortError</a>"
+              <a>DOMException</a>.
+              </li>
+            </ol>
+          </li>
+          <li>Finally, when <var>retryPromise</var> settles, set
+          <var>response</var>.<a>[[\retryPromise]]</a> to null.
+          </li>
+          <li>Return <var>retryPromise</var>.
+            <p class="note">
+              The <var>retryPromise</var> will later be resolved or rejected by
+              either the <a>user accepts the payment request algorithm</a> or
+              the <a>user aborts the payment request algorithm</a>, which are
+              triggered through interaction with the user interface.
+            </p>
+          </li>
+        </ol>
+      </section>
       <section>
         <h2>
           <dfn>toJSON()</dfn> method
@@ -3321,19 +3407,27 @@ <h2>
           </li>
           <li>Let <var>promise</var> be <a>a new promise</a>.
           </li>
-          <li>If <var>response</var>.<a>[[\completeCalled]]</a> is true, reject
+          <li>If <var>response</var>.<a>[[\complete]]</a> is true, reject <var>
+            promise</var> with an "<a>InvalidStateError</a>"
+            <a>DOMException</a>.
+          </li>
+          <li data-tests=
+          "payment-request/payment-response/retry-method-manual.https.html">If
+          <var>response</var>.<a>[[\retryPromise]]</a> is not null, reject
           <var>promise</var> with an "<a>InvalidStateError</a>"
           <a>DOMException</a>.
           </li>
-          <li>Otherwise, set <var>response</var>.<a>[[\completeCalled]]</a> to
-          true.
+          <li>Otherwise, set <var>response</var>.<a>[[\complete]]</a> to true.
           </li>
           <li>Return <var>promise</var> and perform the remaining steps <a>in
           parallel</a>.
           </li>
           <li>Close down any remaining user interface. The <a>user agent</a>
           MAY use the value <var>result</var> to influence the user experience.
           </li>
+          <li>Set the <a>user agent</a>'s <a>payment request is showing</a>
+          boolean to false.
+          </li>
           <li>Resolve <var>promise</var> with undefined.
           </li>
         </ol>
@@ -3357,11 +3451,30 @@ <h2>
           </tr>
           <tr>
             <td>
-              <dfn>[[\completeCalled]]</dfn>
+              <dfn>[[\complete]]</dfn>
             </td>
             <td>
-              true if the <a data-lt="PaymentResponse.complete">complete</a>
-              method has been called and false otherwise.
+              Is true if that the request for payment has completed, or false
+              otherwise.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <dfn>[[\request]]</dfn>
+            </td>
+            <td>
+              The <a>PaymentRequest</a> instance that instantiated this
+              <a>PaymentResponse</a>.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <dfn>[[\retryPromise]]</dfn>
+            </td>
+            <td>
+              Null, or a <a>Promise</a> that resolves when a <a>user accepts
+              the payment request</a> or rejects if the <a>user aborts the
+              payment request</a>.
             </td>
           </tr>
         </table>
@@ -3878,21 +3991,40 @@ <h2>
             further action. The <a>user agent</a> SHOULD ensure that this never
             occurs.
           </li>
-          <li>Let <var>response</var> be a new <a>PaymentResponse</a>.
+          <li>Let <var>isRetry</var> be true if
+          <var>request</var>.<a>[[\response]]</a> is not null, false otherwise.
           </li>
-          <li>Set the <a data-lt="PaymentResponse.requestId">requestId</a>
-          attribute value of <var>response</var> to the value of
-          <var>request</var>.<a>[[\details]]</a>.<a data-lt=
-          "PaymentDetailsInit.id">id</a>.
+          <li>Let <var>response</var> be
+          <var>request</var>.<a>[[\response]]</a> if <var>isRetry</var> is
+          true, or a new <a>PaymentResponse</a> otherwise.
           </li>
-          <li>Set the <a data-lt="PaymentResponse.methodName">methodName</a>
-          attribute value of <var>response</var> to the <a>payment method
-          identifier</a> for the <a>payment method</a> that the user selected
-          to accept the payment.
+          <li>If <var>isRetry</var> if false, initialize the newly created
+          <var>response</var>:
+            <ol>
+              <li>Set <var>response</var>.<a>[[\request]]</a> to
+              <var>request</var>.
+              </li>
+              <li>Set <var>response</var>.<a>[[\retryPromise]]</a> to null.
+              </li>
+              <li>Set <var>response</var>.<a>[[\complete]]</a> to false.
+              </li>
+              <li>Set the <a data-lt="PaymentResponse.requestId">requestId</a>
+              attribute value of <var>response</var> to the value of
+              <var>request</var>.<a>[[\details]]</a>.<a data-lt=
+              "PaymentDetailsInit.id">id</a>.
+              </li>
+              <li>Set <var>request</var>.<a>[[\response]]</a> to
+              <var>response</var>.
+              </li>
+            </ol>
           </li>
           <li>Let <var>handler</var> be the <a>payment handler</a> selected by
           the user.
           </li>
+          <li>Set the <a data-lt="PaymentResponse.methodName">methodName</a>
+          attribute value of <var>response</var> to the <a>payment method
+          identifier</a> of <var>handler</var>.
+          </li>
           <li>Set the <a data-lt="PaymentResponse.details">details</a>
           attribute value of <var>response</var> to an object resulting from
           running the <var>handler</var>'s <a>steps to respond to a payment
@@ -3951,17 +4083,13 @@ <h2>
           "PaymentResponse.payerPhone">payerPhone</a> value, the user agent
           SHOULD format the phone number to adhere to [[!E.164]].
           </li>
-          <li>Set <var>response</var>.<a>[[\completeCalled]]</a> to false.
+          <li>If <var>isRetry</var> is true, resolve
+          <var>response</var>.<a>[[\retryPromise]]</a> with undefined.
+          Otherwise, resolve <var>request</var>.<a>[[\acceptPromise]]</a> with
+          <var>response</var>.
           </li>
           <li>Set <var>request</var>.<a>[[\state]]</a> to "<a>closed</a>".
           </li>
-          <li>Set the <a>user agent</a>'s <a>payment request is showing</a>
-          boolean to false.
-          </li>
-          <li>Resolve the pending promise
-          <var>request</var>.<a>[[\acceptPromise]]</a> with
-          <var>response</var>.
-          </li>
         </ol>
       </section>
       <section>
@@ -3993,8 +4121,21 @@ <h2>
           <li>Set the <a>user agent</a>'s <a>payment request is showing</a>
           boolean to false.
           </li>
-          <li>Reject the promise <var>request</var>.<a>[[\acceptPromise]]</a>
-          with an "<a>AbortError</a>" <a>DOMException</a>.
+          <li>Let <var>error</var> be an "<a>AbortError</a>"
+          <a>DOMException</a>.
+          </li>
+          <li>Let <var>response</var> be
+          <var>request</var>.<a>[[\response]]</a>.
+          </li>
+          <li>If <var>response</var> not null:
+            <ol>
+              <li>Reject <var>response</var>.<a>[[\retryPromise]]</a> with
+              <var>error</var>
+              </li>
+            </ol>
+          </li>
+          <li>Otherwise, reject <var>request</var>.<a>[[\acceptPromise]]</a>
+          with <var>error</var>.
           </li>
         </ol>
       </section>
