@moonbase.sh/storefront 3.8.2 → 3.10.0

package/README.md

@@ -66,6 +66,18 @@ The widget renders directly into the host page's DOM and inherits its viewport.
 
 Hosts that ship a fixed-width legacy mobile viewport (for example Wix's classic mobile sites use `<meta name="viewport" content="width=320, user-scalable=yes">`) cause the browser to upscale every CSS pixel on the page. The widget auto-detects this and counter-scales itself with CSS `zoom` to remain readable; opt out with `disableViewportCompensation: true` if you want the widget to match the host's upscaled density. On Wix specifically, mounting the widget into a contained element via `target` is also an option — it switches the drawer from a viewport overlay to an in-flow component and sidesteps the upscale entirely.
 
+### 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.
+
+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.
+
 ## Trigger intents
 
 Use intent methods to open specific views or execute actions:
@@ -488,6 +500,45 @@ Available events include:
 - `checkout-closed`
 - `checkout-completed`
 
+`signed-in` and `signed-up` fire on the page where the customer signs in, including through a link in an email. `signed-out` also fires when the session ends without anyone signing out on the page: in another tab, or elsewhere (for example a password change on another device), which the widget finds out when it next renews the token.
+
+## Calling your own API
+
+`Moonbase.getAccessToken()` resolves to the signed-in customer's access token, or `null` when nobody is signed in. Send it to your own API to act on the customer's behalf. It's renewed first when it's about to run out, so call it for each request rather than keeping a copy.
+
+```ts
+const token = await Moonbase.getAccessToken()
+const response = await fetch('https://api.example.com/presets', {
+  headers: token ? { Authorization: `Bearer ${token}` } : {},
+})
+```
+
+The token is a JWT signed with your account's key. Verify it on your server against the JWK Set at `https://<account-id>.moonbase.sh/api/key/jwks`, and check all of:
+
+- the `typ` header is `at+jwt` and the algorithm is `RS256`
+- the issuer (`iss`) is your Account ID
+- the audience (`aud`) is `https://moonbase.sh`
+- the expiry (`exp`) is present and hasn't passed
+
+License tokens are signed with the same key and issuer, so a check that skips the audience or the expiry accepts a license file as a sign-in. The customer's ID is the `sub` claim. With [jose](https://github.com/panva/jose):
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+const jwks = createRemoteJWKSet(new URL('https://acme.moonbase.sh/api/key/jwks'))
+
+const { payload } = await jwtVerify(token, jwks, {
+  typ: 'at+jwt',
+  algorithms: ['RS256'],
+  issuer: 'acme',
+  audience: 'https://moonbase.sh',
+  requiredClaims: ['exp'],
+})
+// payload.sub is the customer's ID
+```
+
+Don't read the widget's `localStorage` entry yourself: it holds the refresh token as well, which must never leave the browser.
+
 ## Integrations
 
 The widget can forward its commerce and auth events to common marketing/analytics SDKs without any extra glue code. Enable a provider by passing its config in `integrations`:

package/dist/moonbase.d.ts

@@ -202,6 +202,7 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     setup(url: string, options?: DeepPartial<MoonbaseOptions>): Promise<void>;
     configure(options: DeepPartial<MoonbaseOptions>): void;
     on<TEvent extends MoonbaseEvent>(eventType: TEvent, callback: (event: MoonbaseEventArgs[TEvent]) => void): void;
+    getAccessToken(): Promise<string | null>;
     private handleLocationIntent;
     sign_in(parameters?: MoonbaseIntentArgs['sign_in']): void;
     sign_up(parameters?: MoonbaseIntentArgs['sign_up']): void;
@@ -236,6 +237,13 @@ export declare type MoonbaseInstance = MoonbaseInstanceIntents & {
     setup: (url: string, options: DeepPartial<MoonbaseOptions>) => Promise<void>;
     configure: (options: DeepPartial<MoonbaseOptions>) => void;
     on: <TEvent extends MoonbaseEvent>(eventType: TEvent, callback: (event: MoonbaseEventArgs[TEvent]) => void) => void;
+    /**
+     * The signed-in customer's access token, for calling your own API on their behalf, or
+     * null when nobody is signed in. Renewed first when it is about to run out, so it is
+     * always good for at least the next half minute. Verify it on your server with your
+     * account's public key, at `/api/key/jwks` on your Moonbase address.
+     */
+    getAccessToken: () => Promise<string | null>;
 };
 
 declare type MoonbaseInstanceIntents = {