@moonbase.sh/storefront 3.12.0 → 3.13.0

package/README.md

@@ -68,15 +68,18 @@ Hosts that ship a fixed-width legacy mobile viewport (for example Wix's classic
 
 ### Captchas
 
-A merchant can ask customers to solve a captcha before they sign up. With that turned on, the
-widget's sign-up form shows one, drawn in a frame from the store's own
-`https://<account-id>.moonbase.sh`. A site with a Content-Security-Policy only has to allow that
-address in `frame-src`, which it already needs for the checkout overlay, and nothing for the
-captcha provider itself.
+A merchant can ask customers to solve a captcha before they sign up or subscribe to the
+newsletter. With that turned on, the widget's sign-up and subscribe forms show one, drawn in a
+frame from the store's own `https://<account-id>.moonbase.sh`. A site with a
+Content-Security-Policy only has to allow that address in `frame-src`, which it already needs for
+the checkout overlay, and nothing for the captcha provider itself. A newsletter form of your own
+cannot hold the frame, so the widget draws it in the drawer instead (see
+[On a store that asks for a captcha](#on-a-store-that-asks-for-a-captcha)).
 
 Widget versions from before captchas (3.7 and earlier) cannot show one, so while captchas are on,
-signing up from a site pinned to one of those fails. Checkout is unaffected by the widget version:
-it runs in Moonbase's own checkout, which shows its own captcha.
+signing up from a site pinned to one of those fails. The same goes for newsletter sign-ups from a
+site pinned to 3.12 or earlier, which predate the captcha on them. Checkout is unaffected by the
+widget version: it runs in Moonbase's own checkout, which shows its own captcha.
 
 ## Trigger intents
 
@@ -426,10 +429,10 @@ closed, and the widget reports progress on the form itself for you to style:
 
 | `data-moonbase-state` | When |
 | --- | --- |
-| `submitting` | The request is out. The form's submit buttons are disabled until it returns. |
+| `submitting` | The request is out. The form's submit buttons are disabled until it returns, and on a store that asks for a captcha until the visitor has solved it. |
 | `subscribed` | The visitor is on the list. |
 | `confirmation_sent` | Double opt-in: a confirmation email went out, and the visitor is on the list once they click it. |
-| `error` | The server turned the email down, or the request failed. |
+| `error` | The server turned the email down, the request failed, or the visitor closed the captcha unsolved. |
 
 A `[data-moonbase-message]` element inside the form gets the outcome as text, worded as the
 drawer words it, and is made a live region so screen readers announce it. Leave it out to show
@@ -452,6 +455,18 @@ who is subscribed already. With double opt-in on, nearly every sign-up ends in
 `data-moonbase-state` is set in the default mode as well, so a spinner can cover the moment
 before the drawer opens.
 
+### On a store that asks for a captcha
+
+With the captcha on, the store refuses a newsletter sign-up until the visitor has solved it, and
+your form has no room for the challenge. So the drawer opens with the challenge alone, "Confirm
+you're not a robot to finish subscribing", in either mode. It usually solves itself within a
+second or two. Once it is solved, the widget sends the form again: the drawer then shows the
+outcome, or with `data-moonbase-feedback="inline"` closes, and the outcome goes on your form as
+above.
+
+If the visitor closes the drawer without solving it, nothing is sent, and the form ends in
+`error` with "Please confirm you're not a robot." Sending it again opens the challenge again.
+
 ### Reacting in code
 
 Every successful sign-up emits `subscribed`, from these forms and from the drawer's own:

package/dist/moonbase.d.ts

@@ -429,6 +429,13 @@ export declare interface MoonbaseIntentArgs {
         quantity?: number;
         offer_id?: string;
         show_cart?: boolean;
+        /**
+         * The customer's license this purchase upgrades or renews, for a product whose licenses cover
+         * only some releases. Buying it extends that license instead of issuing another, at the price
+         * the storefront quotes for that license. Each license is a cart line of its own, always one
+         * unit. Products only. Left out, the purchase issues a new license.
+         */
+        license_id?: string;
     };
     [MoonbaseIntent.Purchase]: {
         product_id?: string;
@@ -436,12 +443,16 @@ export declare interface MoonbaseIntentArgs {
         variation_id?: string;
         quantity?: number;
         coupon_code?: string;
+        /** The customer's license this purchase upgrades or renews, always one unit. Products only. */
+        license_id?: string;
     } | {
         product_id?: string;
         bundle_id?: string;
         variation_id?: string;
         quantity?: number;
         coupon_code?: string;
+        /** The customer's license this purchase upgrades or renews, always one unit. Products only. */
+        license_id?: string;
     }[];
     [MoonbaseIntent.Checkout]: {
         complete?: boolean;