@moonbase.sh/storefront 3.9.0 → 3.10.0

package/README.md

@@ -500,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 = {