@moonbase.sh/storefront-api 3.10.0 → 3.12.0

package/README.md

@@ -24,7 +24,8 @@ Configuration notes:
 
 - `endpoint`: your Moonbase storefront URL.
 - `includeManifests`: include downloadable file manifests when available.
-- `persistUtm`: store detected UTM values and ad click IDs in localStorage instead of sessionStorage.
+- `persistUtm`: in `@moonbase.sh/vue`, keep the attribution a visitor arrived with in localStorage, across visits, instead of sessionStorage for the tab. Only with the visitor's consent (see `attributionConsent`); a refusal removes it.
+- `attributionConsent`: in `@moonbase.sh/vue`, whether the visitor has agreed to marketing cookies. `false` keeps the UTM tags, referrer and the ad platforms a click came from (`adClicks`) but not the ad click IDs themselves, and records a tagged arrival on the order only with the first thing put in the cart; `true` keeps the click IDs too. Left out, it follows the store's own setting in Moonbase, which the catalog reports for this visitor as `cookieConsentRequired`. Change it later with `setAttributionConsent()`.
 
 ## Common usage
 
@@ -211,6 +212,11 @@ from TikTok) go to the API under those names, and the rest as `utm_*`.
 in from the tags and click IDs it has already picked up, unless you pass your own
 `utm`.
 
+A click ID identifies the visitor's click, so only send one once the visitor has
+agreed to marketing cookies, where the law asks for that. `withoutClickIds(utm)`
+drops their values and keeps the platforms they came from in `adClicks` (sent as
+`utm_ad_click`), which still counts the visit as an ad click.
+
 ## Inventory flow
 
 Most inventory endpoints require an authenticated user:

package/dist/index.cjs

@@ -54,6 +54,7 @@ __export(index_exports, {
   SubscriptionStatus: () => SubscriptionStatus,
   TokenStore: () => TokenStore,
   accessTokenLifetime: () => accessTokenLifetime,
+  adClicksOf: () => adClicksOf,
   imageWidths: () => imageWidths,
   isLocalStorageAvailable: () => isLocalStorageAvailable,
   isPromotionDisplay: () => isPromotionDisplay,
@@ -66,7 +67,8 @@ __export(index_exports, {
   promotionDisplays: () => promotionDisplays,
   resolveUtm: () => resolveUtm,
   schemas: () => schemas_exports12,
-  utmToObject: () => utmToObject
+  utmToObject: () => utmToObject,
+  withoutClickIds: () => withoutClickIds
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -117,6 +119,7 @@ var MarketingConsentType = /* @__PURE__ */ ((MarketingConsentType2) => {
   return MarketingConsentType2;
 })(MarketingConsentType || {});
 function utmToObject(utm) {
+  var _a;
   return Object.entries({
     utm_source: utm == null ? void 0 : utm.source,
     utm_medium: utm == null ? void 0 : utm.medium,
@@ -129,7 +132,8 @@ function utmToObject(utm) {
     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
+    ttclid: utm == null ? void 0 : utm.ttclid,
+    utm_ad_click: ((_a = utm == null ? void 0 : utm.adClicks) == null ? void 0 : _a.length) ? utm.adClicks.join(",") : void 0
   }).filter(([_, value]) => value !== void 0).reduce((obj, [key, value]) => ({
     ...obj,
     [key]: value
@@ -500,7 +504,11 @@ var storefrontSchema = import_zod3.z.object({
   // Promotions need to be optional since we may still have old, cached representations in browsers
   promotions: storefrontPromotionsSchema.optional(),
   // Depending on circumstances, we may have a tax estimate available
-  estimatedTax: taxEstimateSchema.optional()
+  estimatedTax: taxEstimateSchema.optional(),
+  // Whether the storefront has to wait for this visitor's cookie consent before it keeps ad click
+  // IDs or remembers their visit: the store's setting, for the country the visit comes from.
+  // Optional for older backends and cached catalogs, which count as asking.
+  cookieConsentRequired: import_zod3.z.boolean().optional()
 });
 
 // src/activationRequests/models.ts
@@ -1295,7 +1303,7 @@ var ProductEndpoints = class {
 var import_zod15 = require("zod");
 
 // package.json
-var version = "3.10.0";
+var version = "3.12.0";
 
 // src/utils/client.ts
 function buildClientHeader(sdk) {
@@ -1451,6 +1459,10 @@ var MoonbaseApi = class {
 var schemas_exports8 = {};
 __export(schemas_exports8, {
   milestoneProgressSchema: () => milestoneProgressSchema,
+  pendingPlanChangeSchema: () => pendingPlanChangeSchema,
+  pricingOptionSchema: () => pricingOptionSchema,
+  subscriptionPlanOptionSchema: () => subscriptionPlanOptionSchema,
+  subscriptionPlanOptionsSchema: () => subscriptionPlanOptionsSchema,
   subscriptionSchema: () => subscriptionSchema
 });
 var import_zod14 = require("zod");
@@ -1660,6 +1672,33 @@ var milestoneProgressSchema = import_zod14.z.object({
   toNormalizedCycleNumber: import_zod14.z.number(),
   events: import_zod14.z.record(import_zod14.z.coerce.number(), milestoneProgressEventSchema.array())
 });
+var pricingOptionSchema = import_zod14.z.object({
+  id: import_zod14.z.string(),
+  name: import_zod14.z.string(),
+  cycleLength: import_zod14.z.nativeEnum(CycleLength)
+});
+var pendingPlanChangeSchema = import_zod14.z.object({
+  option: pricingOptionSchema,
+  // The renewal that starts the new plan and charges `nextTotal`.
+  takesEffectAt: import_zod14.z.coerce.date(),
+  nextTotal: orderTotalSchema,
+  // Whether everything the subscription gets off now (discount, offer, coupons) still applies on the new plan.
+  keepsDiscount: import_zod14.z.boolean(),
+  scheduledAt: import_zod14.z.coerce.date()
+});
+var subscriptionPlanOptionSchema = import_zod14.z.object({
+  option: pricingOptionSchema,
+  // What the next renewal charges on this plan. For the plan it is on, its normal renewal.
+  nextTotal: orderTotalSchema,
+  takesEffectAt: import_zod14.z.coerce.date(),
+  keepsDiscount: import_zod14.z.boolean(),
+  current: import_zod14.z.boolean(),
+  scheduled: import_zod14.z.boolean()
+});
+var subscriptionPlanOptionsSchema = import_zod14.z.object({
+  unavailable: import_zod14.z.string().nullish(),
+  plans: subscriptionPlanOptionSchema.array()
+});
 var subscriptionSchema = import_zod14.z.object({
   id: import_zod14.z.string(),
   status: import_zod14.z.nativeEnum(SubscriptionStatus),
@@ -1674,6 +1713,10 @@ var subscriptionSchema = import_zod14.z.object({
   paymentMethod: import_zod14.z.string().optional(),
   milestoneProgress: milestoneProgressSchema.nullish(),
   embeddedUpdatePaymentUrl: import_zod14.z.string().optional(),
+  // Older backends send neither, and one this version can't read is dropped rather than failing
+  // the whole subscription.
+  pricingOption: pricingOptionSchema.nullish().catch(void 0),
+  pendingChange: pendingPlanChangeSchema.nullish().catch(void 0),
   content: import_zod14.z.discriminatedUnion("type", [
     import_zod14.z.object({
       type: import_zod14.z.literal("Product"),
@@ -1717,6 +1760,38 @@ var SubscriptionEndpoints = class {
     });
     return response.data;
   }
+  /**
+   * The plans the subscription can switch to when its current period ends, each with what the
+   * next renewal would charge on it. The plan it is on comes first. When it can't switch,
+   * `unavailable` says why, ready to show to the customer.
+   */
+  async getPlanOptions(subscriptionId) {
+    const response = await this.api.authenticatedFetch(`/api/customer/inventory/subscriptions/${subscriptionId}/plan-options`, subscriptionPlanOptionsSchema);
+    return response.data;
+  }
+  /**
+   * Switches the subscription to another plan when its current period ends. Nothing is charged
+   * now: the next renewal charges the new plan and starts its cycle. Until then the customer can
+   * switch again, and passing the plan it is on keeps that plan. Returns the updated subscription,
+   * with the switch in `pendingChange`.
+   */
+  async changePlan(subscriptionId, variationId) {
+    const response = await this.api.authenticatedFetch(`/api/customer/inventory/subscriptions/${subscriptionId}/plan-change`, subscriptionSchema, {
+      method: "POST",
+      body: { variationId }
+    });
+    return response.data;
+  }
+  /**
+   * Keeps the subscription on its current plan, dropping a switch scheduled with `changePlan`.
+   * Returns the updated subscription.
+   */
+  async cancelPlanChange(subscriptionId) {
+    const response = await this.api.authenticatedFetch(`/api/customer/inventory/subscriptions/${subscriptionId}/plan-change`, subscriptionSchema, {
+      method: "DELETE"
+    });
+    return response.data;
+  }
   async renew(subscriptionId, returnUrl, embedded) {
     const response = await this.api.authenticatedFetch(`/api/customer/inventory/subscriptions/${subscriptionId}/renew?redirect=false&return=${returnUrl}&embedded=${embedded ? "true" : "false"}`, import_zod15.z.object({
       location: import_zod15.z.string()
@@ -2989,6 +3064,31 @@ var ImageUtils = class _ImageUtils {
 };
 
 // src/utils/utm.ts
+var clickIdPlatforms = [
+  ["gclid", "google"],
+  ["gbraid", "google"],
+  ["wbraid", "google"],
+  ["msclkid", "microsoft"],
+  ["fbclid", "meta"],
+  ["ttclid", "tiktok"]
+];
+var adPlatformOrder = ["google", "microsoft", "meta", "tiktok"];
+function adClicksOf(utm) {
+  var _a;
+  if (!utm)
+    return void 0;
+  const platforms = new Set((_a = utm.adClicks) != null ? _a : []);
+  for (const [key, platform] of clickIdPlatforms) {
+    if (utm[key])
+      platforms.add(platform);
+  }
+  const ordered = adPlatformOrder.filter((platform) => platforms.has(platform));
+  return ordered.length > 0 ? ordered : void 0;
+}
+function withoutClickIds(utm) {
+  const { gclid: _gclid, gbraid: _gbraid, wbraid: _wbraid, msclkid: _msclkid, fbclid: _fbclid, ttclid: _ttclid, ...rest } = utm;
+  return { ...rest, adClicks: adClicksOf(utm) };
+}
 function parseOffSiteReferrer(rawReferrer, currentOrigin) {
   if (!rawReferrer)
     return void 0;
@@ -3003,7 +3103,7 @@ function parseOffSiteReferrer(rawReferrer, currentOrigin) {
 }
 function resolveUtm(cached, fresh) {
   const freshHasUtm = !!(fresh.source || fresh.medium || fresh.campaign || fresh.term || fresh.content);
-  const freshHasClickId = !!(fresh.gclid || fresh.gbraid || fresh.wbraid || fresh.fbclid || fresh.msclkid || fresh.ttclid);
+  const freshHasClickId = !!adClicksOf(fresh);
   const freshIsExternalArrival = freshHasUtm || freshHasClickId || !!fresh.referrer;
   if (freshIsExternalArrival)
     return fresh;
@@ -3066,6 +3166,7 @@ var MoonbaseClient = class {
   SubscriptionStatus,
   TokenStore,
   accessTokenLifetime,
+  adClicksOf,
   imageWidths,
   isLocalStorageAvailable,
   isPromotionDisplay,
@@ -3078,5 +3179,6 @@ var MoonbaseClient = class {
   promotionDisplays,
   resolveUtm,
   schemas,
-  utmToObject
+  utmToObject,
+  withoutClickIds
 });