@moonbase.sh/storefront-api 3.6.0 → 3.8.0

package/README.md

@@ -24,7 +24,7 @@ Configuration notes:
 
 - `endpoint`: your Moonbase storefront URL.
 - `includeManifests`: include downloadable file manifests when available.
-- `persistUtm`: store detected UTM values in localStorage instead of sessionStorage.
+- `persistUtm`: store detected UTM values and ad click IDs in localStorage instead of sessionStorage.
 
 ## Common usage
 
@@ -172,6 +172,38 @@ refused with `CaptchaRequiredError` (a `MoonbaseError`). A site with a
 Content-Security-Policy has to allow the store's `https://<account-id>.moonbase.sh`
 in `frame-src`.
 
+### Where a customer came from
+
+Pass the UTM tags, ad click IDs and referrer the visitor arrived with, the same
+shape orders take, so the merchant can see how the customer was acquired:
+
+```ts
+import { parseOffSiteReferrer } from '@moonbase.sh/storefront-api'
+
+const params = new URLSearchParams(window.location.search)
+
+await client.identity.signUp('Jane', 'jane@example.com', 'password', null, true, true, true, {
+  utm: {
+    source: params.get('utm_source') || undefined,
+    campaign: params.get('utm_campaign') || undefined,
+    // Click IDs ad platforms add to the link, often with no UTM tags beside them.
+    gclid: params.get('gclid') || undefined,
+    fbclid: params.get('fbclid') || undefined,
+    msclkid: params.get('msclkid') || undefined,
+    ttclid: params.get('ttclid') || undefined,
+    // The referring site's host only, and nothing when the visitor came from this site.
+    referrer: parseOffSiteReferrer(document.referrer, window.location.origin),
+  },
+})
+```
+
+Fields left out are not sent. The click IDs (`gclid`, `gbraid` and `wbraid` from
+Google Ads, `fbclid` from Meta, `msclkid` from Microsoft Advertising and `ttclid`
+from TikTok) go to the API under those names, and the rest as `utm_*`.
+`useAuth().signUp` in `@moonbase.sh/vue`, and so the storefront widget, fills this
+in from the tags and click IDs it has already picked up, unless you pass your own
+`utm`.
+
 ## Inventory flow
 
 Most inventory endpoints require an authenticated user:
@@ -191,6 +223,14 @@ while (page.hasMore && page.next) {
 }
 ```
 
+A product's release history needs no sign-in. `getReleases` lists its published releases, highest
+version first, each with its version, release notes, publish date and files, and whether the caller
+may download it (`downloadsAllowed`). It pages the same way:
+
+```ts
+const releases = await client.inventory.products.getReleases('my-product')
+```
+
 ## Endpoint groups
 
 `client.storefront`, `client.identity`, `client.orders`, `client.vouchers`, `client.inventory`, `client.activationRequests`, `client.vendor`, `client.communications`, `client.groups`.

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(index_exports, {
   SubscriptionCancellationReason: () => SubscriptionCancellationReason,
   SubscriptionStatus: () => SubscriptionStatus,
   TokenStore: () => TokenStore,
+  accessTokenLifetime: () => accessTokenLifetime,
   imageWidths: () => imageWidths,
   isLocalStorageAvailable: () => isLocalStorageAvailable,
   isPromotionDisplay: () => isPromotionDisplay,
@@ -119,7 +120,13 @@ function utmToObject(utm) {
     utm_campaign: utm == null ? void 0 : utm.campaign,
     utm_term: utm == null ? void 0 : utm.term,
     utm_content: utm == null ? void 0 : utm.content,
-    utm_referrer: utm == null ? void 0 : utm.referrer
+    utm_referrer: utm == null ? void 0 : utm.referrer,
+    gclid: utm == null ? void 0 : utm.gclid,
+    gbraid: utm == null ? void 0 : utm.gbraid,
+    wbraid: utm == null ? void 0 : utm.wbraid,
+    fbclid: utm == null ? void 0 : utm.fbclid,
+    msclkid: utm == null ? void 0 : utm.msclkid,
+    ttclid: utm == null ? void 0 : utm.ttclid
   }).filter(([_, value]) => value !== void 0).reduce((obj, [key, value]) => ({
     ...obj,
     [key]: value
@@ -211,6 +218,7 @@ var schemas_exports = {};
 __export(schemas_exports, {
   downloadSchema: () => downloadSchema,
   manifestSchema: () => manifestSchema,
+  productReleaseSchema: () => productReleaseSchema,
   productSummarySchema: () => productSummarySchema
 });
 var import_zod2 = require("zod");
@@ -273,10 +281,20 @@ var productSummarySchema = import_zod2.z.object({
   downloadsNeedsOwnership: import_zod2.z.boolean(),
   downloadsNeedsGroupMembership: import_zod2.z.boolean(),
   // Whether this caller clears every requirement above, including the group membership the client
-  // can't see for itself.
+  // can't see for itself. False with none of them set means the merchant closed the release to everyone.
   downloadsAllowed: import_zod2.z.boolean(),
   downloads: import_zod2.z.array(downloadSchema).optional()
 });
+var productReleaseSchema = import_zod2.z.object({
+  version: import_zod2.z.string(),
+  description: import_zod2.z.string().nullish(),
+  publishedAt: import_zod2.z.coerce.date(),
+  // Whether this caller may download the release, resolved against its own access control: a
+  // merchant can keep past releases to owners while the current one is open to anyone.
+  downloadsAllowed: import_zod2.z.boolean(),
+  downloads: import_zod2.z.array(downloadSchema),
+  properties: import_zod2.z.record(rawPropertyValueSchema).nullish()
+});
 
 // src/storefront/schemas.ts
 var storefrontProductSchema = import_zod3.z.object({
@@ -460,7 +478,10 @@ var activationRequestSchema = import_zod4.z.object({
     requiresAccount: import_zod4.z.boolean(),
     requiresNewsletterOptIn: import_zod4.z.boolean(),
     numberOfDaysPerProduct: import_zod4.z.number(),
-    numberOfDaysRemaining: import_zod4.z.number()
+    numberOfDaysRemaining: import_zod4.z.number(),
+    // The trial never expires, so the day counts are not worth showing. Absent from a backend that
+    // predates endless trials.
+    endless: import_zod4.z.boolean().default(false)
   }).optional(),
   licenseEligibility: import_zod4.z.object({
     eligible: import_zod4.z.boolean()
@@ -837,8 +858,12 @@ var IdentityEndpoints = class {
     return userSchema.parse(identity);
   }
   async signUp(name, email, password, address, acceptedPrivacyPolicy, acceptedTermsAndConditions, communicationOptIn, options) {
-    const path = `/api/customer/identity/sign-up?scheme=JWT&communicationOptIn=${communicationOptIn ? "true" : "false"}`;
-    const response = await fetch(`${this.api.baseUrl}${path}`, {
+    const query = new URLSearchParams({
+      scheme: "JWT",
+      communicationOptIn: communicationOptIn ? "true" : "false",
+      ...utmToObject(options == null ? void 0 : options.utm)
+    });
+    const response = await fetch(`${this.api.baseUrl}/api/customer/identity/sign-up?${query.toString()}`, {
       method: "POST",
       headers: {
         "Accept": "application/json",
@@ -874,8 +899,13 @@ var IdentityEndpoints = class {
     this.tokenStore.setUser(identity);
     return { status: "signed-in", user: userSchema.parse(identity) };
   }
+  /**
+   * Signs the buyer out here at once, and ends the session on the server so its refresh
+   * token stops working too. Resolves once the server has answered, and never rejects:
+   * the buyer is signed out in this browser whatever happens to that request.
+   */
   async signOut() {
-    this.tokenStore.clear();
+    await this.tokenStore.signOut();
   }
   async update(name, email, emailConfirmationToken, communicationPreferences) {
     const response = await this.api.authenticatedFetch("/api/customer/identity", userSchema, {
@@ -1082,6 +1112,15 @@ var ProductEndpoints = class {
     const response = await this.api.fetch(`/api/customer/inventory/products/${productId}${version2 ? `?version=${version2}${this.configuration.includeManifests ? "&includeManifests=true" : ""}` : this.configuration.includeManifests ? "?includeManifests=true" : ""}`, productSummarySchema);
     return response.data;
   }
+  /**
+   * The product's published releases, highest version first, with their release notes and files,
+   * and whether the caller may download each. Open to anyone who can see the product, signed in or
+   * not. A page can hold fewer releases than its size, so keep following `next` while `hasMore` is set.
+   */
+  async getReleases(productId, nextUrl) {
+    const response = await this.api.fetch(nextUrl || `/api/customer/inventory/products/${productId}/releases${this.configuration.includeManifests ? "?includeManifests=true" : ""}`, paged(productReleaseSchema));
+    return response.data;
+  }
   async getOwned(nextUrl) {
     const response = await this.api.authenticatedFetch(nextUrl || `/api/customer/inventory/products${this.configuration.includeManifests ? "?includeManifests=true" : ""}`, paged(productSummarySchema));
     return response.data;
@@ -1108,7 +1147,7 @@ var ProductEndpoints = class {
 var import_zod14 = require("zod");
 
 // package.json
-var version = "3.6.0";
+var version = "3.8.0";
 
 // src/utils/client.ts
 function buildClientHeader(sdk) {
@@ -1787,24 +1826,36 @@ var InMemoryStore = class {
 };
 
 // src/utils/tokenStore.ts
+var defaultAccessTokenLifetime = 15 * 60 * 1e3;
+var renewBeforeExpiry = 5 * 60 * 1e3;
+var expiryMargin = 30 * 1e3;
+var refreshLockName = "moonbase_auth_refresh";
+function accessTokenLifetime(accessToken) {
+  try {
+    const payload = accessToken.split(".")[1].replaceAll("-", "+").replaceAll("_", "/");
+    const claims = JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+    const lifetime = (Number(claims.exp) - Number(claims.iat)) * 1e3;
+    if (Number.isFinite(lifetime) && lifetime > 0 && lifetime <= 24 * 60 * 60 * 1e3)
+      return lifetime;
+  } catch (e) {
+  }
+  return defaultAccessTokenLifetime;
+}
 var _TokenStore = class _TokenStore {
   constructor(configuration) {
     this.configuration = configuration;
     this.tokens = null;
     this.refreshTimeoutId = null;
     this.refreshPromise = null;
+    this.waitingForVisibility = false;
+    this.sessionEndedListeners = [];
     var _a, _b;
     this.logger = (_a = configuration.logger) != null ? _a : new ConsoleLogger();
     this.store = (_b = configuration.store) != null ? _b : isLocalStorageAvailable() ? new LocalStorageStore((err) => this.warnAboutStorage(err)) : new InMemoryStore();
     if (typeof window !== "undefined" && !configuration.store && !(this.store instanceof LocalStorageStore))
       this.warnAboutStorage();
-    const storedToken = this.store.get(_TokenStore.storageKey);
-    if (storedToken) {
-      this.tokens = {
-        ...storedToken,
-        expiresAt: new Date(storedToken.expiresAt)
-      };
-    }
+    this.tokens = this.readStoredTokens();
+    this.scheduleRefresh();
     this.store.listen(_TokenStore.storageKey, (updatedTokens) => this.handleStorageUpdate(updatedTokens));
   }
   get user() {
@@ -1838,29 +1889,91 @@ var _TokenStore = class _TokenStore {
     } else {
       this.tokens = {
         ...identity,
-        // Hardcoded 15 minutes now, might want to check the JWT tho
-        expiresAt: new Date((/* @__PURE__ */ new Date()).getTime() + 15 * 60 * 1e3)
+        expiresAt: new Date(Date.now() + accessTokenLifetime(identity.accessToken))
       };
     }
     this.store.set(_TokenStore.storageKey, this.tokens);
-    if (typeof window !== "undefined") {
-      if (this.refreshTimeoutId != null)
-        window.clearTimeout(this.refreshTimeoutId);
-      this.refreshTimeoutId = window.setTimeout(() => {
-        this.startRefresh().catch((err) => this.logger.warn("Could not refresh access token", err));
-      }, 10 * 60 * 1e3);
-    }
+    this.scheduleRefresh();
     return this.tokens;
   }
   clear() {
     this.tokens = null;
     this.store.remove(_TokenStore.storageKey);
-    if (this.refreshTimeoutId != null && typeof window !== "undefined")
-      window.clearTimeout(this.refreshTimeoutId);
+    this.scheduleRefresh();
     return null;
   }
+  async signOut() {
+    const tokens = this.tokens;
+    this.clear();
+    if (!tokens)
+      return;
+    try {
+      await fetch(`${this.configuration.endpoint}/api/customer/identity/revoke?token=${encodeURIComponent(tokens.refreshToken)}`, {
+        method: "POST",
+        keepalive: true,
+        headers: {
+          "Accept": "application/json",
+          "Content-Type": "text/plain",
+          "x-mb-cors": "1",
+          "x-mb-client": buildClientHeader(this.configuration.sdk)
+        },
+        body: tokens.accessToken
+      });
+    } catch (err) {
+      this.logger.warn("Could not end the session on the server", err);
+    }
+  }
+  onSessionEnded(listener) {
+    this.sessionEndedListeners.push(listener);
+  }
   get isExpired() {
-    return this.tokens != null && this.tokens.expiresAt < /* @__PURE__ */ new Date();
+    return this.tokens != null && this.tokens.expiresAt.getTime() - expiryMargin < Date.now();
+  }
+  readStoredTokens() {
+    const stored = this.store.get(_TokenStore.storageKey);
+    return stored ? { ...stored, expiresAt: new Date(stored.expiresAt) } : null;
+  }
+  /**
+   * (Re)arms the timer that renews the access token shortly before it runs out, or disarms
+   * it when there is nothing to renew. Every tab arms one, and `refreshTokens` makes sure
+   * only one of them actually renews.
+   */
+  scheduleRefresh() {
+    if (typeof window === "undefined")
+      return;
+    if (this.refreshTimeoutId != null)
+      window.clearTimeout(this.refreshTimeoutId);
+    this.refreshTimeoutId = null;
+    if (!this.tokens)
+      return;
+    const delay = Math.max(0, this.renewalDueAt(this.tokens) - Date.now());
+    this.refreshTimeoutId = window.setTimeout(() => this.renewInBackground(), delay);
+  }
+  renewalDueAt(tokens) {
+    const lead = Math.min(renewBeforeExpiry, accessTokenLifetime(tokens.accessToken) / 3);
+    return tokens.expiresAt.getTime() - lead;
+  }
+  renewInBackground() {
+    var _a;
+    this.refreshTimeoutId = null;
+    if (!this.tokens)
+      return;
+    if (this.renewalDueAt(this.tokens) > Date.now()) {
+      this.scheduleRefresh();
+      return;
+    }
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      if (!this.waitingForVisibility) {
+        this.waitingForVisibility = true;
+        document.addEventListener("visibilitychange", () => {
+          this.waitingForVisibility = false;
+          this.renewInBackground();
+        }, { once: true });
+      }
+      return;
+    }
+    const pending = (_a = this.refreshPromise) != null ? _a : this.startRefresh();
+    pending.catch((err) => this.logger.warn("Could not refresh access token", err));
   }
   /**
    * Start a refresh and hold it so concurrent callers join it rather than firing
@@ -1877,7 +1990,45 @@ var _TokenStore = class _TokenStore {
     this.refreshPromise = pending;
     return pending;
   }
+  /**
+   * A refresh token can be used once: the server answers a second use by revoking the
+   * session, taking it for a stolen token. So refreshes are serialised across every tab of
+   * the origin, and whoever gets the lock second takes up what the first one stored rather
+   * than spending the same refresh token again. The stored copy has to be read, not waited
+   * for: storage events never reach the document that wrote them, so a second client on
+   * the same page would not hear about it.
+   */
   async refreshTokens() {
+    var _a;
+    const spending = (_a = this.tokens) == null ? void 0 : _a.refreshToken;
+    const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+    if (locks == null ? void 0 : locks.request) {
+      let held = false;
+      try {
+        return await locks.request(refreshLockName, () => {
+          held = true;
+          return this.refreshHoldingLock(spending);
+        });
+      } catch (err) {
+        if (held)
+          throw err;
+      }
+    }
+    return await this.refreshHoldingLock(spending);
+  }
+  /**
+   * @param spending The refresh token this refresh set out to use. If the session has moved
+   * on from it while we waited for the lock, someone else has renewed already.
+   */
+  async refreshHoldingLock(spending) {
+    var _a;
+    const stored = this.readStoredTokens();
+    if (stored && stored.refreshToken !== ((_a = this.tokens) == null ? void 0 : _a.refreshToken))
+      this.tokens = stored;
+    if (this.tokens && this.tokens.refreshToken !== spending && !this.isExpired) {
+      this.scheduleRefresh();
+      return this.tokens;
+    }
     if (!this.tokens)
       throw new Error("No tokens found to refresh");
     const response = await fetch(`${this.configuration.endpoint}/api/customer/identity/refresh?token=${encodeURIComponent(this.tokens.refreshToken)}`, {
@@ -1893,6 +2044,13 @@ var _TokenStore = class _TokenStore {
     if (response.status !== 200) {
       if (response.status === 403 || response.status === 404) {
         this.clear();
+        for (const listener of this.sessionEndedListeners) {
+          try {
+            listener();
+          } catch (err) {
+            this.logger.warn("A listener for the end of the session failed", err);
+          }
+        }
         return null;
       }
       throw new MoonbaseError("Unexpected result", `Could not refresh access token, status code ${response.status}`, response.status);
@@ -1903,11 +2061,10 @@ var _TokenStore = class _TokenStore {
   }
   handleStorageUpdate(updatedTokens) {
     this.tokens = updatedTokens;
-    if (this.refreshTimeoutId != null && typeof window !== "undefined")
-      window.clearTimeout(this.refreshTimeoutId);
     if (this.tokens) {
       this.tokens.expiresAt = new Date(this.tokens.expiresAt);
     }
+    this.scheduleRefresh();
   }
   warnAboutStorage(err) {
     this.logger.warn(
@@ -2604,7 +2761,8 @@ function parseOffSiteReferrer(rawReferrer, currentOrigin) {
 }
 function resolveUtm(cached, fresh) {
   const freshHasUtm = !!(fresh.source || fresh.medium || fresh.campaign || fresh.term || fresh.content);
-  const freshIsExternalArrival = freshHasUtm || !!fresh.referrer;
+  const freshHasClickId = !!(fresh.gclid || fresh.gbraid || fresh.wbraid || fresh.fbclid || fresh.msclkid || fresh.ttclid);
+  const freshIsExternalArrival = freshHasUtm || freshHasClickId || !!fresh.referrer;
   if (freshIsExternalArrival)
     return fresh;
   return cached != null ? cached : fresh;
@@ -2663,6 +2821,7 @@ var MoonbaseClient = class {
   SubscriptionCancellationReason,
   SubscriptionStatus,
   TokenStore,
+  accessTokenLifetime,
   imageWidths,
   isLocalStorageAvailable,
   isPromotionDisplay,