@moonbase.sh/storefront-api 3.1.0 → 3.3.0

package/README.md

@@ -76,6 +76,40 @@ const redeemed = await client.vouchers.redeem('MY-CODE')
 console.log(redeemed)
 ```
 
+### Enroll a customer in a group
+
+Merchant-owned customer lists that have been opened to public sign-ups can be
+named by ID on sign-up, on a newsletter subscription, and on an order:
+
+```ts
+await client.identity.signUp('Jane', 'jane@example.com', 'password', null, true, true, true, {
+  groupIds: ['newsletter-2026'],
+})
+
+await client.communications.subscribe({ email: 'jane@example.com', groupIds: ['newsletter-2026'] })
+
+// On an order, after it has been pushed and before it is paid. Additive: each
+// call adds to what the order already carries.
+await client.orders.joinGroups(order.id, ['buyers-2026'])
+```
+
+None of those three report which groups were applied. An ID naming a list that
+is closed, deleted, rule-driven or another tenant's is skipped in silence, so a
+stale ID can never fail a registration or a sale. IDs are matched lowercase and
+at most five per request are applied.
+
+For a customer who is already signed in, joining is a request of its own, and it
+is the one that does report failure:
+
+```ts
+await client.groups.join('beta') // throws NotFoundError if it isn't joinable
+```
+
+Every reason it can be refused (no such group, deleted, closed, a segment,
+another tenant's) arrives as the same `NotFoundError`, so that a signed-in
+customer cannot use it to enumerate a merchant's group IDs. Joining twice
+succeeds and changes nothing.
+
 ## Inventory flow
 
 Most inventory endpoints require an authenticated user:
@@ -97,7 +131,7 @@ while (page.hasMore && page.next) {
 
 ## Endpoint groups
 
-`client.storefront`, `client.identity`, `client.orders`, `client.vouchers`, `client.inventory`, `client.activationRequests`, `client.vendor`.
+`client.storefront`, `client.identity`, `client.orders`, `client.vouchers`, `client.inventory`, `client.activationRequests`, `client.vendor`, `client.communications`, `client.groups`.
 
 ## Image renditions
 
@@ -122,7 +156,17 @@ host — is returned untouched and logs a warning, since it will be served at fu
 
 ## Token storage and logging
 
-By default, credentials are stored in localStorage (or in-memory if localStorage is unavailable).
+By default, credentials are stored in localStorage, falling back to memory only when localStorage
+cannot be reached at all. Even that check sits inside a `try`, because reading
+`window.localStorage` itself throws in Firefox when the buyer has blocked cookies and site data.
+
+Reachability, not writability, is the test on purpose: an origin that is merely full is still
+holding the buyer's existing session, so it is used rather than discarded. Individual reads and
+writes that fail degrade to an in-memory copy and warn through the configured logger. The session
+stays valid for that page load; it just doesn't survive a reload, and
+`client.tokenStore.isPersistent` goes false once that has happened if you want to tell the buyer.
+A failure to *persist* credentials is never reported as a failure to sign in, so a locked-down
+browser can't strand someone in a sign-in loop.
 
 You can inject your own storage/logger implementations:
 

package/dist/index.cjs

@@ -49,9 +49,11 @@ __export(index_exports, {
   SubscriptionStatus: () => SubscriptionStatus,
   TokenStore: () => TokenStore,
   imageWidths: () => imageWidths,
+  isLocalStorageAvailable: () => isLocalStorageAvailable,
   isPromotionDisplay: () => isPromotionDisplay,
   isTransformableImageUrl: () => isTransformableImageUrl,
   maxImageDimension: () => maxImageDimension,
+  normalizeGroupIds: () => normalizeGroupIds,
   objectToQuery: () => objectToQuery,
   parseOffSiteReferrer: () => parseOffSiteReferrer,
   problemDetailsSchema: () => problemDetailsSchema,
@@ -489,6 +491,19 @@ var ActivationRequestEndpoints = class {
   }
 };
 
+// src/utils/groups.ts
+function normalizeGroupIds(groupIds) {
+  if (!groupIds)
+    return void 0;
+  const normalized = [];
+  for (const groupId of groupIds) {
+    const trimmed = groupId == null ? void 0 : groupId.trim().toLowerCase();
+    if (trimmed && !normalized.includes(trimmed))
+      normalized.push(trimmed);
+  }
+  return normalized.length > 0 ? normalized : void 0;
+}
+
 // src/communications/schemas.ts
 var schemas_exports4 = {};
 __export(schemas_exports4, {
@@ -522,7 +537,8 @@ var CommunicationsEndpoints = class {
         email: input.email,
         name: ((_a = input.name) == null ? void 0 : _a.trim()) || null,
         newsletter: (_b = input.newsletter) != null ? _b : true,
-        productUpdates: (_c = input.productUpdates) != null ? _c : true
+        productUpdates: (_c = input.productUpdates) != null ? _c : true,
+        groupIds: normalizeGroupIds(input.groupIds)
       }
     });
     return response.data;
@@ -564,6 +580,37 @@ var CommunicationsEndpoints = class {
   }
 };
 
+// src/groups/endpoints.ts
+var GroupEndpoints = class {
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Joins the signed-in customer to a merchant-owned group that has been opened
+   * to public sign-ups.
+   *
+   * The one group call that reports failure. Group IDs sent along with sign-up,
+   * a newsletter subscription or a checkout are passengers on a request that
+   * wanted something else, so an unusable one is skipped rather than allowed to
+   * fail the account, the subscription or the sale. Here joining *is* the
+   * request, so it throws.
+   *
+   * Every reason it can fail (no such group, deleted, closed, a segment, a
+   * system group, another tenant's) arrives as the same `NotFoundError`, so
+   * that a customer of one tenant can't enumerate that merchant's group IDs.
+   *
+   * Idempotent: joining a group the customer is already in succeeds and changes
+   * nothing.
+   */
+  async join(groupId) {
+    await this.api.authenticatedFetch(
+      `/api/customer/groups/${encodeURIComponent(groupId)}/join`,
+      null,
+      { method: "POST" }
+    );
+  }
+};
+
 // src/utils/errors.ts
 var NotAuthorizedError = class extends Error {
   constructor() {
@@ -757,17 +804,17 @@ var IdentityEndpoints = class {
       throw new NotFoundError("User not found");
     if (response.status >= 400)
       await handleResponseProblem(response, this.logger);
+    let identity;
     try {
-      const data = await response.json();
-      const user = identitySchema.parse(data);
-      this.tokenStore.setUser(user);
-      return userSchema.parse(user);
+      identity = identitySchema.parse(await response.json());
     } catch (err) {
       this.logger.warn("Could not sign in user", { email, response, err });
       throw new MoonbaseError("Bad response", "Could not sign in user", response.status);
     }
+    this.tokenStore.setUser(identity);
+    return userSchema.parse(identity);
   }
-  async signUp(name, email, password, address, acceptedPrivacyPolicy, acceptedTermsAndConditions, communicationOptIn) {
+  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}`, {
       method: "POST",
@@ -782,7 +829,8 @@ var IdentityEndpoints = class {
         password,
         address,
         acceptedPrivacyPolicy,
-        acceptedTermsAndConditions
+        acceptedTermsAndConditions,
+        groupIds: normalizeGroupIds(options == null ? void 0 : options.groupIds)
       })
     });
     if (response.status >= 400)
@@ -792,14 +840,15 @@ var IdentityEndpoints = class {
       const parsed = pendingActivationSchema.parse(data);
       return { status: "activation-pending", email: parsed.email };
     }
+    let identity;
     try {
-      const identity = identitySchema.parse(data);
-      this.tokenStore.setUser(identity);
-      return { status: "signed-in", user: userSchema.parse(identity) };
+      identity = identitySchema.parse(data);
     } catch (err) {
       this.logger.warn("Could not sign up user", { email, response, err });
       throw new MoonbaseError("Bad response", "Could not sign up user", response.status);
     }
+    this.tokenStore.setUser(identity);
+    return { status: "signed-in", user: userSchema.parse(identity) };
   }
   async signOut() {
     this.tokenStore.clear();
@@ -1079,6 +1128,15 @@ var MoonbaseApi = class {
       status: response.status,
       duration: finishedAt.getTime() - startedAt.getTime()
     });
+    if (response.type === "opaqueredirect" || response.status === 0) {
+      const err = new MoonbaseError(
+        "Unexpected redirect",
+        `The Moonbase API redirected ${path}, which the SDK is not configured to follow`,
+        response.status
+      );
+      this.reportRequestProblem(path, request, response, err);
+      throw err;
+    }
     if (response.status >= 400) {
       try {
         await handleResponseProblem(response, this.logger);
@@ -1494,6 +1552,28 @@ var OrderEndpoints = class {
     const response = await this.api.fetch(`/api/customer/orders/${orderId}/coupons`, openOrderSchema, { method: "DELETE" });
     return response.data;
   }
+  /**
+   * Records merchant-owned customer groups the buyer should join once this order
+   * completes. The order has to exist server-side first, so call it after a
+   * `pushContent`, and before the payment rather than after: the enrollment
+   * rides on the order until the payment webhook settles it.
+   *
+   * Additive rather than a replacement: each call adds to what the order already
+   * carries, and the accumulated set is capped server-side. Groups the merchant
+   * has not opened to public sign-ups are skipped in silence, so a stale ID in a
+   * checkout form can never fail a sale.
+   *
+   * Kept apart from the marketing opt-in on purpose: a checkout can offer both
+   * independently, and merging them would opt a buyer who only asked to join a
+   * list into email they never asked for.
+   */
+  async joinGroups(orderId, groupIds) {
+    const response = await this.api.fetch(`/api/customer/orders/${orderId}/groups`, openOrderSchema, {
+      method: "POST",
+      body: { groupIds: normalizeGroupIds(groupIds) }
+    });
+    return response.data;
+  }
 };
 
 // src/storefront/endpoints.ts
@@ -1543,28 +1623,81 @@ var ConsoleLogger = class {
 };
 
 // src/utils/store.ts
+function isLocalStorageAvailable() {
+  try {
+    return typeof window !== "undefined" && !!window.localStorage;
+  } catch (e) {
+    return false;
+  }
+}
 var LocalStorageStore = class {
+  constructor(onDegraded) {
+    this.onDegraded = onDegraded;
+    // Values whose write to localStorage failed. Read back in preference to
+    // localStorage so the rest of the session sees what it just wrote.
+    this.fallback = /* @__PURE__ */ new Map();
+    this.degraded = false;
+  }
+  get isDegraded() {
+    return this.degraded;
+  }
   get(key) {
-    const item = localStorage.getItem(key);
-    if (item) {
-      return JSON.parse(item);
+    if (this.fallback.has(key))
+      return this.fallback.get(key);
+    try {
+      const item = localStorage.getItem(key);
+      if (item) {
+        return JSON.parse(item);
+      }
+      return null;
+    } catch (err) {
+      this.reportDegraded(err);
+      return null;
     }
-    return null;
   }
   set(key, item) {
-    localStorage.setItem(key, JSON.stringify(item));
+    try {
+      localStorage.setItem(key, JSON.stringify(item));
+      this.fallback.delete(key);
+    } catch (err) {
+      this.reportDegraded(err);
+      this.fallback.set(key, item);
+    }
   }
   remove(key) {
-    localStorage.removeItem(key);
+    try {
+      localStorage.removeItem(key);
+      this.fallback.delete(key);
+      return;
+    } catch (err) {
+      this.reportDegraded(err);
+    }
+    this.fallback.set(key, null);
+    try {
+      localStorage.setItem(key, "");
+    } catch (e) {
+    }
   }
   listen(key, callback) {
-    if (typeof window !== "undefined") {
-      window.addEventListener("storage", (event) => {
-        if (event.key === key) {
-          callback(event.newValue ? JSON.parse(event.newValue) : null);
-        }
-      });
-    }
+    if (typeof window === "undefined")
+      return;
+    window.addEventListener("storage", (event) => {
+      if (event.key !== key)
+        return;
+      this.fallback.delete(key);
+      try {
+        callback(event.newValue ? JSON.parse(event.newValue) : null);
+      } catch (err) {
+        console.warn(`Moonbase could not parse the stored value for ${key}`, err);
+      }
+    });
+  }
+  reportDegraded(err) {
+    var _a;
+    if (this.degraded)
+      return;
+    this.degraded = true;
+    (_a = this.onDegraded) == null ? void 0 : _a.call(this, err);
   }
 };
 var InMemoryStore = class {
@@ -1602,8 +1735,11 @@ var _TokenStore = class _TokenStore {
     this.tokens = null;
     this.refreshTimeoutId = null;
     this.refreshPromise = null;
-    var _a;
-    this.store = (_a = configuration.store) != null ? _a : typeof window !== "undefined" && localStorage ? new LocalStorageStore() : new InMemoryStore();
+    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 = {
@@ -1618,18 +1754,17 @@ var _TokenStore = class _TokenStore {
       return this.tokens;
     return null;
   }
+  get isPersistent() {
+    return this.store instanceof LocalStorageStore && !this.store.isDegraded;
+  }
   async getAccessToken() {
     var _a, _b, _c;
-    if (this.isExpired) {
-      if (this.refreshPromise) {
-        const tokens2 = await this.refreshPromise;
-        return (_a = tokens2 == null ? void 0 : tokens2.accessToken) != null ? _a : null;
-      }
-      this.refreshPromise = this.refreshTokens();
-      const tokens = await this.refreshPromise;
-      return (_b = tokens == null ? void 0 : tokens.accessToken) != null ? _b : null;
+    if (!this.isExpired) {
+      return ((_a = this.tokens) == null ? void 0 : _a.accessToken) || null;
     }
-    return ((_c = this.tokens) == null ? void 0 : _c.accessToken) || null;
+    const pending = (_b = this.refreshPromise) != null ? _b : this.startRefresh();
+    const tokens = await pending;
+    return (_c = tokens == null ? void 0 : tokens.accessToken) != null ? _c : null;
   }
   setUser(user) {
     const identity = user;
@@ -1654,7 +1789,7 @@ var _TokenStore = class _TokenStore {
       if (this.refreshTimeoutId != null)
         window.clearTimeout(this.refreshTimeoutId);
       this.refreshTimeoutId = window.setTimeout(() => {
-        this.refreshPromise = this.refreshTokens();
+        this.startRefresh().catch((err) => this.logger.warn("Could not refresh access token", err));
       }, 10 * 60 * 1e3);
     }
     return this.tokens;
@@ -1669,10 +1804,25 @@ var _TokenStore = class _TokenStore {
   get isExpired() {
     return this.tokens != null && this.tokens.expiresAt < /* @__PURE__ */ new Date();
   }
+  /**
+   * Start a refresh and hold it so concurrent callers join it rather than firing
+   * their own. The slot is cleared as soon as it settles: a retained promise
+   * would hand every later expiry the same stale access token, and a rejected one
+   * that stayed put would re-throw on every subsequent request (including the
+   * anonymous ones) for the rest of the session.
+   */
+  startRefresh() {
+    const pending = this.refreshTokens().finally(() => {
+      if (this.refreshPromise === pending)
+        this.refreshPromise = null;
+    });
+    this.refreshPromise = pending;
+    return pending;
+  }
   async refreshTokens() {
     if (!this.tokens)
       throw new Error("No tokens found to refresh");
-    const response = await fetch(`${this.configuration.endpoint}/api/customer/identity/refresh?token=${this.tokens.refreshToken}`, {
+    const response = await fetch(`${this.configuration.endpoint}/api/customer/identity/refresh?token=${encodeURIComponent(this.tokens.refreshToken)}`, {
       method: "POST",
       headers: {
         "Accept": "application/json",
@@ -1694,12 +1844,18 @@ var _TokenStore = class _TokenStore {
   }
   handleStorageUpdate(updatedTokens) {
     this.tokens = updatedTokens;
-    if (this.refreshTimeoutId != null)
+    if (this.refreshTimeoutId != null && typeof window !== "undefined")
       window.clearTimeout(this.refreshTimeoutId);
     if (this.tokens) {
       this.tokens.expiresAt = new Date(this.tokens.expiresAt);
     }
   }
+  warnAboutStorage(err) {
+    this.logger.warn(
+      "Moonbase could not persist credentials to localStorage: this browser is blocking or has exhausted site storage. Sign-in will work for this page load but will not survive a reload.",
+      err
+    );
+  }
 };
 _TokenStore.storageKey = "moonbase_auth";
 var TokenStore = _TokenStore;
@@ -2394,6 +2550,7 @@ var MoonbaseClient = class {
     this.storefront = new StorefrontEndpoints(this.api, this.configuration);
     this.identity = new IdentityEndpoints(this.api, this.tokenStore, this.logger);
     this.communications = new CommunicationsEndpoints(this.api);
+    this.groups = new GroupEndpoints(this.api);
     this.vouchers = new VoucherEndpoints(this.api);
     this.orders = new OrderEndpoints(this.api);
     this.inventory = new InventoryEndpoints(this.api, this.configuration);
@@ -2432,9 +2589,11 @@ var MoonbaseClient = class {
   SubscriptionStatus,
   TokenStore,
   imageWidths,
+  isLocalStorageAvailable,
   isPromotionDisplay,
   isTransformableImageUrl,
   maxImageDimension,
+  normalizeGroupIds,
   objectToQuery,
   parseOffSiteReferrer,
   problemDetailsSchema,

package/dist/index.d.cts

@@ -26,12 +26,47 @@ interface IStore {
     set: <TItem>(key: string, item: TItem) => void;
     remove: (key: string) => void;
     listen: <TItem>(key: string, callback: (item: TItem | null) => void) => void;
+    /**
+     * True once any storage operation has failed and the store has fallen back to
+     * memory. Optional so custom stores don't have to implement it.
+     */
+    readonly isDegraded?: boolean;
 }
+/**
+ * Whether `localStorage` can be reached at all.
+ *
+ * Deliberately *not* a write probe. Writability is not the right question here,
+ * because `LocalStorageStore` degrades per operation when a write fails, so a
+ * storage that reads fine but is at quota is still worth using: it is holding the
+ * buyer's existing session, and refusing it would throw away a perfectly readable
+ * sign-in and send them back to the login form. The only thing that makes
+ * `localStorage` unusable is not being able to touch it, which is what Firefox
+ * does (`SecurityError` from the property getter) when the buyer has blocked
+ * cookies and site data. That is why even the truthiness check sits inside a
+ * `try`.
+ */
+declare function isLocalStorageAvailable(): boolean;
+/**
+ * `localStorage`-backed store that degrades to memory instead of throwing.
+ *
+ * Storage can start failing at any point in a session, not just at construction:
+ * the origin hits quota, an extension clears site data, the profile's storage
+ * file goes corrupt. Since this is where the auth tokens live, an unhandled
+ * throw here surfaces as a failed sign-in for a buyer whose credentials were
+ * accepted. So every operation falls back to an in-memory copy. The session
+ * keeps working; it just stops surviving a reload.
+ */
 declare class LocalStorageStore implements IStore {
+    private readonly onDegraded?;
+    private readonly fallback;
+    private degraded;
+    constructor(onDegraded?: ((err: unknown) => void) | undefined);
+    get isDegraded(): boolean;
     get<TItem>(key: string): TItem | null;
     set<TItem>(key: string, item: TItem): void;
     remove(key: string): void;
     listen<TItem>(key: string, callback: (item: TItem | null) => void): void;
+    private reportDegraded;
 }
 declare class InMemoryStore implements IStore {
     private readonly store;
@@ -47,6 +82,7 @@ type IdentityWithExpiry = Identity & {
 };
 interface ITokenStore {
     get user(): User | null;
+    get isPersistent(): boolean;
     getAccessToken: () => Promise<string | null>;
     setUser: (user: Identity | User) => User | null;
     clear: () => void;
@@ -57,15 +93,26 @@ declare class TokenStore implements ITokenStore {
     private refreshTimeoutId;
     private refreshPromise;
     private readonly store;
+    private readonly logger;
     static readonly storageKey = "moonbase_auth";
     constructor(configuration: MoonbaseConfiguration);
     get user(): User | null;
+    get isPersistent(): boolean;
     getAccessToken(): Promise<string | null>;
     setUser(user: Identity | User): IdentityWithExpiry | null;
     clear(): null;
     private get isExpired();
+    /**
+     * Start a refresh and hold it so concurrent callers join it rather than firing
+     * their own. The slot is cleared as soon as it settles: a retained promise
+     * would hand every later expiry the same stale access token, and a rejected one
+     * that stayed put would re-throw on every subsequent request (including the
+     * anonymous ones) for the rest of the session.
+     */
+    private startRefresh;
     private refreshTokens;
     private handleStorageUpdate;
+    private warnAboutStorage;
 }
 
 type HttpMethods = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
@@ -1076,6 +1123,13 @@ interface SubscribeInput {
     name?: string | null;
     newsletter?: boolean;
     productUpdates?: boolean;
+    /**
+     * Merchant-owned customer groups to enroll the subscriber into. Applied on
+     * the same terms as the opt-in beside them: on a tenant that requires double
+     * opt-in they land when the confirmation link is clicked, not here. Groups the
+     * merchant has not opened to public sign-ups are skipped in silence.
+     */
+    groupIds?: string[];
 }
 interface CommunicationPreferencesInput {
     newsletter: boolean;
@@ -1092,6 +1146,29 @@ declare class CommunicationsEndpoints {
     unsubscribe(email: string, token: string): Promise<void>;
 }
 
+declare class GroupEndpoints {
+    private api;
+    constructor(api: MoonbaseApi);
+    /**
+     * Joins the signed-in customer to a merchant-owned group that has been opened
+     * to public sign-ups.
+     *
+     * The one group call that reports failure. Group IDs sent along with sign-up,
+     * a newsletter subscription or a checkout are passengers on a request that
+     * wanted something else, so an unusable one is skipped rather than allowed to
+     * fail the account, the subscription or the sale. Here joining *is* the
+     * request, so it throws.
+     *
+     * Every reason it can fail (no such group, deleted, closed, a segment, a
+     * system group, another tenant's) arrives as the same `NotFoundError`, so
+     * that a customer of one tenant can't enumerate that merchant's group IDs.
+     *
+     * Idempotent: joining a group the customer is already in succeeds and changes
+     * nothing.
+     */
+    join(groupId: string): Promise<void>;
+}
+
 declare const addressSchema: z.ZodObject<{
     countryCode: z.ZodString;
     streetAddress1: z.ZodString;
@@ -1584,6 +1661,17 @@ type SignUpResult = {
     status: 'activation-pending';
     email: string;
 };
+interface SignUpOptions {
+    /**
+     * Merchant-owned customer groups to enroll the new account into.
+     *
+     * Only groups the merchant has opened to public sign-ups are applied, and the
+     * response does not say which ones were: an ID naming a group that is closed,
+     * deleted, rule-driven or another tenant's is skipped in silence, so a stale
+     * ID left in a form can never fail a registration.
+     */
+    groupIds?: string[];
+}
 
 declare class IdentityEndpoints {
     private api;
@@ -1592,7 +1680,7 @@ declare class IdentityEndpoints {
     constructor(api: MoonbaseApi, tokenStore: ITokenStore, logger: ILogger);
     get(): Promise<User>;
     signIn(email: string, password: string): Promise<User>;
-    signUp(name: string, email: string, password: string, address: Address | null | undefined, acceptedPrivacyPolicy: boolean, acceptedTermsAndConditions: boolean, communicationOptIn?: boolean): Promise<SignUpResult>;
+    signUp(name: string, email: string, password: string, address: Address | null | undefined, acceptedPrivacyPolicy: boolean, acceptedTermsAndConditions: boolean, communicationOptIn?: boolean, options?: SignUpOptions): Promise<SignUpResult>;
     signOut(): Promise<void>;
     update(name: string | null, email: string, emailConfirmationToken?: string, communicationPreferences?: CommunicationPreferences): Promise<{
         needsEmailConfirmationToken: boolean;
@@ -24142,6 +24230,22 @@ declare class OrderEndpoints {
     addCouponCode(orderId: string, code: string): Promise<OpenOrder>;
     removeCouponCode(orderId: string, code: string): Promise<OpenOrder>;
     clearCouponCodes(orderId: string): Promise<OpenOrder>;
+    /**
+     * Records merchant-owned customer groups the buyer should join once this order
+     * completes. The order has to exist server-side first, so call it after a
+     * `pushContent`, and before the payment rather than after: the enrollment
+     * rides on the order until the payment webhook settles it.
+     *
+     * Additive rather than a replacement: each call adds to what the order already
+     * carries, and the accumulated set is capped server-side. Groups the merchant
+     * has not opened to public sign-ups are skipped in silence, so a stale ID in a
+     * checkout form can never fail a sale.
+     *
+     * Kept apart from the marketing opt-in on purpose: a checkout can offer both
+     * independently, and merging them would opt a buyer who only asked to join a
+     * list into email they never asked for.
+     */
+    joinGroups(orderId: string, groupIds: string[]): Promise<OpenOrder>;
 }
 
 declare class StorefrontEndpoints {
@@ -46885,6 +46989,26 @@ declare class MoonbaseError extends Error {
     constructor(title: string, detail: string | undefined, status?: number | undefined, errors?: Record<string, string> | undefined);
 }
 
+/**
+ * Cleans up merchant-authored group IDs before they go on the wire.
+ *
+ * Deliberately normalizes without validating. The server sanitizes these itself,
+ * dropping IDs that are too long, malformed, closed, or belonging to another
+ * tenant, and capping the request at five. It does so in silence, so the
+ * endpoints can't be used to enumerate a tenant's groups. Re-implementing those
+ * rules here would only mean a merchant's typo disappears in the one place they
+ * can't see it, so anything that survives trimming is sent and the server has
+ * the last word.
+ *
+ * Lowercasing is the exception, and it earns its place by making the de-dupe
+ * correct: group IDs are lowercase server-side, so `VIP` and `vip` are one
+ * group and should only cost one of the five slots.
+ *
+ * Returns `undefined` rather than `[]` when nothing survives, so the field is
+ * omitted from the request body entirely for every caller not using this.
+ */
+declare function normalizeGroupIds(groupIds?: readonly string[] | null): string[] | undefined;
+
 /**
  * Builds URLs for on-the-fly renditions of images stored in Moonbase's asset CDN.
  *
@@ -47025,6 +47149,7 @@ declare class MoonbaseClient {
     storefront: StorefrontEndpoints;
     identity: IdentityEndpoints;
     communications: CommunicationsEndpoints;
+    groups: GroupEndpoints;
     vouchers: VoucherEndpoints;
     activationRequests: ActivationRequestEndpoints;
     inventory: InventoryEndpoints;
@@ -47032,4 +47157,4 @@ declare class MoonbaseClient {
     orders: OrderEndpoints;
 }
 
-export { type Activation, ActivationMethod, type ActivationRequest, ActivationRequestFulfillmentType, ActivationRequestStatus, ActivationStatus, type Address, Architecture, type BundleLineItem, type CartCatalog, type CartOrder, type CartTotal, type CartTotalCondition, CartUtils, type CommunicationPreferences, type CommunicationPreferencesInput, type CommunicationPreferencesView, type CompletedOrder, ConnectableAccountProvider, type ConnectedAccount, ConsoleLogger, CycleLength, type Discount, DiscountUtils, type Download, type DownloadManifest, type ILogger, type IRecurrence, type IStore, type ITokenStore, type Identity, type ImageFit, type ImageFormat, type ImageTransform, ImageUtils, InMemoryStore, type License, LicenseStatus, type LineItem, type LineItemTotal, LocalStorageStore, LogLevel, MarketingConsentType, type MilestoneProgress, type Money, type MoneyCollection, MoneyCollectionUtils, MoonbaseApi, MoonbaseClient, type MoonbaseConfiguration, MoonbaseError, NotAuthenticatedError, NotAuthorizedError, NotFoundError, type OfferCondition, type OfferConditionContext, type OfferProgress, type OfferScope, OfferUtils, type OpenOrder, type Order, OrderStatus, type OrderTotal, type OwnedProduct, type Page, Platform, type PricingTier, type PricingVariation, type ProblemDetails, type ProductLineItem, type PromotionDisplay, type Quantifiable, type RawPropertyArray, type RawPropertyObject, type RawPropertyValue, type SignUpResult, type SingleOrMultiple, type Storefront, type StorefrontBundle, type StorefrontOffer, type StorefrontOfferTarget, type StorefrontProduct, type StorefrontPromotion, type StorefrontPromotionCta, type StorefrontPromotionTarget, type SubscribeInput, type SubscribeResponse, type Subscription, SubscriptionStatus, type TaxEstimate, TokenStore, type UrchinTrackingModule, type User, type UserAccountConfirmed, type UserAccountConfirmedStatus, type Vendor, type Voucher, imageWidths, isPromotionDisplay, isTransformableImageUrl, maxImageDimension, objectToQuery, parseOffSiteReferrer, problemDetailsSchema, promotionDisplays, resolveUtm, schemas, utmToObject };
+export { type Activation, ActivationMethod, type ActivationRequest, ActivationRequestFulfillmentType, ActivationRequestStatus, ActivationStatus, type Address, Architecture, type BundleLineItem, type CartCatalog, type CartOrder, type CartTotal, type CartTotalCondition, CartUtils, type CommunicationPreferences, type CommunicationPreferencesInput, type CommunicationPreferencesView, type CompletedOrder, ConnectableAccountProvider, type ConnectedAccount, ConsoleLogger, CycleLength, type Discount, DiscountUtils, type Download, type DownloadManifest, type ILogger, type IRecurrence, type IStore, type ITokenStore, type Identity, type ImageFit, type ImageFormat, type ImageTransform, ImageUtils, InMemoryStore, type License, LicenseStatus, type LineItem, type LineItemTotal, LocalStorageStore, LogLevel, MarketingConsentType, type MilestoneProgress, type Money, type MoneyCollection, MoneyCollectionUtils, MoonbaseApi, MoonbaseClient, type MoonbaseConfiguration, MoonbaseError, NotAuthenticatedError, NotAuthorizedError, NotFoundError, type OfferCondition, type OfferConditionContext, type OfferProgress, type OfferScope, OfferUtils, type OpenOrder, type Order, OrderStatus, type OrderTotal, type OwnedProduct, type Page, Platform, type PricingTier, type PricingVariation, type ProblemDetails, type ProductLineItem, type PromotionDisplay, type Quantifiable, type RawPropertyArray, type RawPropertyObject, type RawPropertyValue, type SignUpOptions, type SignUpResult, type SingleOrMultiple, type Storefront, type StorefrontBundle, type StorefrontOffer, type StorefrontOfferTarget, type StorefrontProduct, type StorefrontPromotion, type StorefrontPromotionCta, type StorefrontPromotionTarget, type SubscribeInput, type SubscribeResponse, type Subscription, SubscriptionStatus, type TaxEstimate, TokenStore, type UrchinTrackingModule, type User, type UserAccountConfirmed, type UserAccountConfirmedStatus, type Vendor, type Voucher, imageWidths, isLocalStorageAvailable, isPromotionDisplay, isTransformableImageUrl, maxImageDimension, normalizeGroupIds, objectToQuery, parseOffSiteReferrer, problemDetailsSchema, promotionDisplays, resolveUtm, schemas, utmToObject };

package/dist/index.d.ts

@@ -26,12 +26,47 @@ interface IStore {
     set: <TItem>(key: string, item: TItem) => void;
     remove: (key: string) => void;
     listen: <TItem>(key: string, callback: (item: TItem | null) => void) => void;
+    /**
+     * True once any storage operation has failed and the store has fallen back to
+     * memory. Optional so custom stores don't have to implement it.
+     */
+    readonly isDegraded?: boolean;
 }
+/**
+ * Whether `localStorage` can be reached at all.
+ *
+ * Deliberately *not* a write probe. Writability is not the right question here,
+ * because `LocalStorageStore` degrades per operation when a write fails, so a
+ * storage that reads fine but is at quota is still worth using: it is holding the
+ * buyer's existing session, and refusing it would throw away a perfectly readable
+ * sign-in and send them back to the login form. The only thing that makes
+ * `localStorage` unusable is not being able to touch it, which is what Firefox
+ * does (`SecurityError` from the property getter) when the buyer has blocked
+ * cookies and site data. That is why even the truthiness check sits inside a
+ * `try`.
+ */
+declare function isLocalStorageAvailable(): boolean;
+/**
+ * `localStorage`-backed store that degrades to memory instead of throwing.
+ *
+ * Storage can start failing at any point in a session, not just at construction:
+ * the origin hits quota, an extension clears site data, the profile's storage
+ * file goes corrupt. Since this is where the auth tokens live, an unhandled
+ * throw here surfaces as a failed sign-in for a buyer whose credentials were
+ * accepted. So every operation falls back to an in-memory copy. The session
+ * keeps working; it just stops surviving a reload.
+ */
 declare class LocalStorageStore implements IStore {
+    private readonly onDegraded?;
+    private readonly fallback;
+    private degraded;
+    constructor(onDegraded?: ((err: unknown) => void) | undefined);
+    get isDegraded(): boolean;
     get<TItem>(key: string): TItem | null;
     set<TItem>(key: string, item: TItem): void;
     remove(key: string): void;
     listen<TItem>(key: string, callback: (item: TItem | null) => void): void;
+    private reportDegraded;
 }
 declare class InMemoryStore implements IStore {
     private readonly store;
@@ -47,6 +82,7 @@ type IdentityWithExpiry = Identity & {
 };
 interface ITokenStore {
     get user(): User | null;
+    get isPersistent(): boolean;
     getAccessToken: () => Promise<string | null>;
     setUser: (user: Identity | User) => User | null;
     clear: () => void;
@@ -57,15 +93,26 @@ declare class TokenStore implements ITokenStore {
     private refreshTimeoutId;
     private refreshPromise;
     private readonly store;
+    private readonly logger;
     static readonly storageKey = "moonbase_auth";
     constructor(configuration: MoonbaseConfiguration);
     get user(): User | null;
+    get isPersistent(): boolean;
     getAccessToken(): Promise<string | null>;
     setUser(user: Identity | User): IdentityWithExpiry | null;
     clear(): null;
     private get isExpired();
+    /**
+     * Start a refresh and hold it so concurrent callers join it rather than firing
+     * their own. The slot is cleared as soon as it settles: a retained promise
+     * would hand every later expiry the same stale access token, and a rejected one
+     * that stayed put would re-throw on every subsequent request (including the
+     * anonymous ones) for the rest of the session.
+     */
+    private startRefresh;
     private refreshTokens;
     private handleStorageUpdate;
+    private warnAboutStorage;
 }
 
 type HttpMethods = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
@@ -1076,6 +1123,13 @@ interface SubscribeInput {
     name?: string | null;
     newsletter?: boolean;
     productUpdates?: boolean;
+    /**
+     * Merchant-owned customer groups to enroll the subscriber into. Applied on
+     * the same terms as the opt-in beside them: on a tenant that requires double
+     * opt-in they land when the confirmation link is clicked, not here. Groups the
+     * merchant has not opened to public sign-ups are skipped in silence.
+     */
+    groupIds?: string[];
 }
 interface CommunicationPreferencesInput {
     newsletter: boolean;
@@ -1092,6 +1146,29 @@ declare class CommunicationsEndpoints {
     unsubscribe(email: string, token: string): Promise<void>;
 }
 
+declare class GroupEndpoints {
+    private api;
+    constructor(api: MoonbaseApi);
+    /**
+     * Joins the signed-in customer to a merchant-owned group that has been opened
+     * to public sign-ups.
+     *
+     * The one group call that reports failure. Group IDs sent along with sign-up,
+     * a newsletter subscription or a checkout are passengers on a request that
+     * wanted something else, so an unusable one is skipped rather than allowed to
+     * fail the account, the subscription or the sale. Here joining *is* the
+     * request, so it throws.
+     *
+     * Every reason it can fail (no such group, deleted, closed, a segment, a
+     * system group, another tenant's) arrives as the same `NotFoundError`, so
+     * that a customer of one tenant can't enumerate that merchant's group IDs.
+     *
+     * Idempotent: joining a group the customer is already in succeeds and changes
+     * nothing.
+     */
+    join(groupId: string): Promise<void>;
+}
+
 declare const addressSchema: z.ZodObject<{
     countryCode: z.ZodString;
     streetAddress1: z.ZodString;
@@ -1584,6 +1661,17 @@ type SignUpResult = {
     status: 'activation-pending';
     email: string;
 };
+interface SignUpOptions {
+    /**
+     * Merchant-owned customer groups to enroll the new account into.
+     *
+     * Only groups the merchant has opened to public sign-ups are applied, and the
+     * response does not say which ones were: an ID naming a group that is closed,
+     * deleted, rule-driven or another tenant's is skipped in silence, so a stale
+     * ID left in a form can never fail a registration.
+     */
+    groupIds?: string[];
+}
 
 declare class IdentityEndpoints {
     private api;
@@ -1592,7 +1680,7 @@ declare class IdentityEndpoints {
     constructor(api: MoonbaseApi, tokenStore: ITokenStore, logger: ILogger);
     get(): Promise<User>;
     signIn(email: string, password: string): Promise<User>;
-    signUp(name: string, email: string, password: string, address: Address | null | undefined, acceptedPrivacyPolicy: boolean, acceptedTermsAndConditions: boolean, communicationOptIn?: boolean): Promise<SignUpResult>;
+    signUp(name: string, email: string, password: string, address: Address | null | undefined, acceptedPrivacyPolicy: boolean, acceptedTermsAndConditions: boolean, communicationOptIn?: boolean, options?: SignUpOptions): Promise<SignUpResult>;
     signOut(): Promise<void>;
     update(name: string | null, email: string, emailConfirmationToken?: string, communicationPreferences?: CommunicationPreferences): Promise<{
         needsEmailConfirmationToken: boolean;
@@ -24142,6 +24230,22 @@ declare class OrderEndpoints {
     addCouponCode(orderId: string, code: string): Promise<OpenOrder>;
     removeCouponCode(orderId: string, code: string): Promise<OpenOrder>;
     clearCouponCodes(orderId: string): Promise<OpenOrder>;
+    /**
+     * Records merchant-owned customer groups the buyer should join once this order
+     * completes. The order has to exist server-side first, so call it after a
+     * `pushContent`, and before the payment rather than after: the enrollment
+     * rides on the order until the payment webhook settles it.
+     *
+     * Additive rather than a replacement: each call adds to what the order already
+     * carries, and the accumulated set is capped server-side. Groups the merchant
+     * has not opened to public sign-ups are skipped in silence, so a stale ID in a
+     * checkout form can never fail a sale.
+     *
+     * Kept apart from the marketing opt-in on purpose: a checkout can offer both
+     * independently, and merging them would opt a buyer who only asked to join a
+     * list into email they never asked for.
+     */
+    joinGroups(orderId: string, groupIds: string[]): Promise<OpenOrder>;
 }
 
 declare class StorefrontEndpoints {
@@ -46885,6 +46989,26 @@ declare class MoonbaseError extends Error {
     constructor(title: string, detail: string | undefined, status?: number | undefined, errors?: Record<string, string> | undefined);
 }
 
+/**
+ * Cleans up merchant-authored group IDs before they go on the wire.
+ *
+ * Deliberately normalizes without validating. The server sanitizes these itself,
+ * dropping IDs that are too long, malformed, closed, or belonging to another
+ * tenant, and capping the request at five. It does so in silence, so the
+ * endpoints can't be used to enumerate a tenant's groups. Re-implementing those
+ * rules here would only mean a merchant's typo disappears in the one place they
+ * can't see it, so anything that survives trimming is sent and the server has
+ * the last word.
+ *
+ * Lowercasing is the exception, and it earns its place by making the de-dupe
+ * correct: group IDs are lowercase server-side, so `VIP` and `vip` are one
+ * group and should only cost one of the five slots.
+ *
+ * Returns `undefined` rather than `[]` when nothing survives, so the field is
+ * omitted from the request body entirely for every caller not using this.
+ */
+declare function normalizeGroupIds(groupIds?: readonly string[] | null): string[] | undefined;
+
 /**
  * Builds URLs for on-the-fly renditions of images stored in Moonbase's asset CDN.
  *
@@ -47025,6 +47149,7 @@ declare class MoonbaseClient {
     storefront: StorefrontEndpoints;
     identity: IdentityEndpoints;
     communications: CommunicationsEndpoints;
+    groups: GroupEndpoints;
     vouchers: VoucherEndpoints;
     activationRequests: ActivationRequestEndpoints;
     inventory: InventoryEndpoints;
@@ -47032,4 +47157,4 @@ declare class MoonbaseClient {
     orders: OrderEndpoints;
 }
 
-export { type Activation, ActivationMethod, type ActivationRequest, ActivationRequestFulfillmentType, ActivationRequestStatus, ActivationStatus, type Address, Architecture, type BundleLineItem, type CartCatalog, type CartOrder, type CartTotal, type CartTotalCondition, CartUtils, type CommunicationPreferences, type CommunicationPreferencesInput, type CommunicationPreferencesView, type CompletedOrder, ConnectableAccountProvider, type ConnectedAccount, ConsoleLogger, CycleLength, type Discount, DiscountUtils, type Download, type DownloadManifest, type ILogger, type IRecurrence, type IStore, type ITokenStore, type Identity, type ImageFit, type ImageFormat, type ImageTransform, ImageUtils, InMemoryStore, type License, LicenseStatus, type LineItem, type LineItemTotal, LocalStorageStore, LogLevel, MarketingConsentType, type MilestoneProgress, type Money, type MoneyCollection, MoneyCollectionUtils, MoonbaseApi, MoonbaseClient, type MoonbaseConfiguration, MoonbaseError, NotAuthenticatedError, NotAuthorizedError, NotFoundError, type OfferCondition, type OfferConditionContext, type OfferProgress, type OfferScope, OfferUtils, type OpenOrder, type Order, OrderStatus, type OrderTotal, type OwnedProduct, type Page, Platform, type PricingTier, type PricingVariation, type ProblemDetails, type ProductLineItem, type PromotionDisplay, type Quantifiable, type RawPropertyArray, type RawPropertyObject, type RawPropertyValue, type SignUpResult, type SingleOrMultiple, type Storefront, type StorefrontBundle, type StorefrontOffer, type StorefrontOfferTarget, type StorefrontProduct, type StorefrontPromotion, type StorefrontPromotionCta, type StorefrontPromotionTarget, type SubscribeInput, type SubscribeResponse, type Subscription, SubscriptionStatus, type TaxEstimate, TokenStore, type UrchinTrackingModule, type User, type UserAccountConfirmed, type UserAccountConfirmedStatus, type Vendor, type Voucher, imageWidths, isPromotionDisplay, isTransformableImageUrl, maxImageDimension, objectToQuery, parseOffSiteReferrer, problemDetailsSchema, promotionDisplays, resolveUtm, schemas, utmToObject };
+export { type Activation, ActivationMethod, type ActivationRequest, ActivationRequestFulfillmentType, ActivationRequestStatus, ActivationStatus, type Address, Architecture, type BundleLineItem, type CartCatalog, type CartOrder, type CartTotal, type CartTotalCondition, CartUtils, type CommunicationPreferences, type CommunicationPreferencesInput, type CommunicationPreferencesView, type CompletedOrder, ConnectableAccountProvider, type ConnectedAccount, ConsoleLogger, CycleLength, type Discount, DiscountUtils, type Download, type DownloadManifest, type ILogger, type IRecurrence, type IStore, type ITokenStore, type Identity, type ImageFit, type ImageFormat, type ImageTransform, ImageUtils, InMemoryStore, type License, LicenseStatus, type LineItem, type LineItemTotal, LocalStorageStore, LogLevel, MarketingConsentType, type MilestoneProgress, type Money, type MoneyCollection, MoneyCollectionUtils, MoonbaseApi, MoonbaseClient, type MoonbaseConfiguration, MoonbaseError, NotAuthenticatedError, NotAuthorizedError, NotFoundError, type OfferCondition, type OfferConditionContext, type OfferProgress, type OfferScope, OfferUtils, type OpenOrder, type Order, OrderStatus, type OrderTotal, type OwnedProduct, type Page, Platform, type PricingTier, type PricingVariation, type ProblemDetails, type ProductLineItem, type PromotionDisplay, type Quantifiable, type RawPropertyArray, type RawPropertyObject, type RawPropertyValue, type SignUpOptions, type SignUpResult, type SingleOrMultiple, type Storefront, type StorefrontBundle, type StorefrontOffer, type StorefrontOfferTarget, type StorefrontProduct, type StorefrontPromotion, type StorefrontPromotionCta, type StorefrontPromotionTarget, type SubscribeInput, type SubscribeResponse, type Subscription, SubscriptionStatus, type TaxEstimate, TokenStore, type UrchinTrackingModule, type User, type UserAccountConfirmed, type UserAccountConfirmedStatus, type Vendor, type Voucher, imageWidths, isLocalStorageAvailable, isPromotionDisplay, isTransformableImageUrl, maxImageDimension, normalizeGroupIds, objectToQuery, parseOffSiteReferrer, problemDetailsSchema, promotionDisplays, resolveUtm, schemas, utmToObject };

package/dist/index.js

@@ -431,6 +431,19 @@ var ActivationRequestEndpoints = class {
   }
 };
 
+// src/utils/groups.ts
+function normalizeGroupIds(groupIds) {
+  if (!groupIds)
+    return void 0;
+  const normalized = [];
+  for (const groupId of groupIds) {
+    const trimmed = groupId == null ? void 0 : groupId.trim().toLowerCase();
+    if (trimmed && !normalized.includes(trimmed))
+      normalized.push(trimmed);
+  }
+  return normalized.length > 0 ? normalized : void 0;
+}
+
 // src/communications/schemas.ts
 var schemas_exports4 = {};
 __export(schemas_exports4, {
@@ -464,7 +477,8 @@ var CommunicationsEndpoints = class {
         email: input.email,
         name: ((_a = input.name) == null ? void 0 : _a.trim()) || null,
         newsletter: (_b = input.newsletter) != null ? _b : true,
-        productUpdates: (_c = input.productUpdates) != null ? _c : true
+        productUpdates: (_c = input.productUpdates) != null ? _c : true,
+        groupIds: normalizeGroupIds(input.groupIds)
       }
     });
     return response.data;
@@ -506,6 +520,37 @@ var CommunicationsEndpoints = class {
   }
 };
 
+// src/groups/endpoints.ts
+var GroupEndpoints = class {
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Joins the signed-in customer to a merchant-owned group that has been opened
+   * to public sign-ups.
+   *
+   * The one group call that reports failure. Group IDs sent along with sign-up,
+   * a newsletter subscription or a checkout are passengers on a request that
+   * wanted something else, so an unusable one is skipped rather than allowed to
+   * fail the account, the subscription or the sale. Here joining *is* the
+   * request, so it throws.
+   *
+   * Every reason it can fail (no such group, deleted, closed, a segment, a
+   * system group, another tenant's) arrives as the same `NotFoundError`, so
+   * that a customer of one tenant can't enumerate that merchant's group IDs.
+   *
+   * Idempotent: joining a group the customer is already in succeeds and changes
+   * nothing.
+   */
+  async join(groupId) {
+    await this.api.authenticatedFetch(
+      `/api/customer/groups/${encodeURIComponent(groupId)}/join`,
+      null,
+      { method: "POST" }
+    );
+  }
+};
+
 // src/utils/errors.ts
 var NotAuthorizedError = class extends Error {
   constructor() {
@@ -699,17 +744,17 @@ var IdentityEndpoints = class {
       throw new NotFoundError("User not found");
     if (response.status >= 400)
       await handleResponseProblem(response, this.logger);
+    let identity;
     try {
-      const data = await response.json();
-      const user = identitySchema.parse(data);
-      this.tokenStore.setUser(user);
-      return userSchema.parse(user);
+      identity = identitySchema.parse(await response.json());
     } catch (err) {
       this.logger.warn("Could not sign in user", { email, response, err });
       throw new MoonbaseError("Bad response", "Could not sign in user", response.status);
     }
+    this.tokenStore.setUser(identity);
+    return userSchema.parse(identity);
   }
-  async signUp(name, email, password, address, acceptedPrivacyPolicy, acceptedTermsAndConditions, communicationOptIn) {
+  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}`, {
       method: "POST",
@@ -724,7 +769,8 @@ var IdentityEndpoints = class {
         password,
         address,
         acceptedPrivacyPolicy,
-        acceptedTermsAndConditions
+        acceptedTermsAndConditions,
+        groupIds: normalizeGroupIds(options == null ? void 0 : options.groupIds)
       })
     });
     if (response.status >= 400)
@@ -734,14 +780,15 @@ var IdentityEndpoints = class {
       const parsed = pendingActivationSchema.parse(data);
       return { status: "activation-pending", email: parsed.email };
     }
+    let identity;
     try {
-      const identity = identitySchema.parse(data);
-      this.tokenStore.setUser(identity);
-      return { status: "signed-in", user: userSchema.parse(identity) };
+      identity = identitySchema.parse(data);
     } catch (err) {
       this.logger.warn("Could not sign up user", { email, response, err });
       throw new MoonbaseError("Bad response", "Could not sign up user", response.status);
     }
+    this.tokenStore.setUser(identity);
+    return { status: "signed-in", user: userSchema.parse(identity) };
   }
   async signOut() {
     this.tokenStore.clear();
@@ -1021,6 +1068,15 @@ var MoonbaseApi = class {
       status: response.status,
       duration: finishedAt.getTime() - startedAt.getTime()
     });
+    if (response.type === "opaqueredirect" || response.status === 0) {
+      const err = new MoonbaseError(
+        "Unexpected redirect",
+        `The Moonbase API redirected ${path}, which the SDK is not configured to follow`,
+        response.status
+      );
+      this.reportRequestProblem(path, request, response, err);
+      throw err;
+    }
     if (response.status >= 400) {
       try {
         await handleResponseProblem(response, this.logger);
@@ -1436,6 +1492,28 @@ var OrderEndpoints = class {
     const response = await this.api.fetch(`/api/customer/orders/${orderId}/coupons`, openOrderSchema, { method: "DELETE" });
     return response.data;
   }
+  /**
+   * Records merchant-owned customer groups the buyer should join once this order
+   * completes. The order has to exist server-side first, so call it after a
+   * `pushContent`, and before the payment rather than after: the enrollment
+   * rides on the order until the payment webhook settles it.
+   *
+   * Additive rather than a replacement: each call adds to what the order already
+   * carries, and the accumulated set is capped server-side. Groups the merchant
+   * has not opened to public sign-ups are skipped in silence, so a stale ID in a
+   * checkout form can never fail a sale.
+   *
+   * Kept apart from the marketing opt-in on purpose: a checkout can offer both
+   * independently, and merging them would opt a buyer who only asked to join a
+   * list into email they never asked for.
+   */
+  async joinGroups(orderId, groupIds) {
+    const response = await this.api.fetch(`/api/customer/orders/${orderId}/groups`, openOrderSchema, {
+      method: "POST",
+      body: { groupIds: normalizeGroupIds(groupIds) }
+    });
+    return response.data;
+  }
 };
 
 // src/storefront/endpoints.ts
@@ -1485,28 +1563,81 @@ var ConsoleLogger = class {
 };
 
 // src/utils/store.ts
+function isLocalStorageAvailable() {
+  try {
+    return typeof window !== "undefined" && !!window.localStorage;
+  } catch (e) {
+    return false;
+  }
+}
 var LocalStorageStore = class {
+  constructor(onDegraded) {
+    this.onDegraded = onDegraded;
+    // Values whose write to localStorage failed. Read back in preference to
+    // localStorage so the rest of the session sees what it just wrote.
+    this.fallback = /* @__PURE__ */ new Map();
+    this.degraded = false;
+  }
+  get isDegraded() {
+    return this.degraded;
+  }
   get(key) {
-    const item = localStorage.getItem(key);
-    if (item) {
-      return JSON.parse(item);
+    if (this.fallback.has(key))
+      return this.fallback.get(key);
+    try {
+      const item = localStorage.getItem(key);
+      if (item) {
+        return JSON.parse(item);
+      }
+      return null;
+    } catch (err) {
+      this.reportDegraded(err);
+      return null;
     }
-    return null;
   }
   set(key, item) {
-    localStorage.setItem(key, JSON.stringify(item));
+    try {
+      localStorage.setItem(key, JSON.stringify(item));
+      this.fallback.delete(key);
+    } catch (err) {
+      this.reportDegraded(err);
+      this.fallback.set(key, item);
+    }
   }
   remove(key) {
-    localStorage.removeItem(key);
+    try {
+      localStorage.removeItem(key);
+      this.fallback.delete(key);
+      return;
+    } catch (err) {
+      this.reportDegraded(err);
+    }
+    this.fallback.set(key, null);
+    try {
+      localStorage.setItem(key, "");
+    } catch (e) {
+    }
   }
   listen(key, callback) {
-    if (typeof window !== "undefined") {
-      window.addEventListener("storage", (event) => {
-        if (event.key === key) {
-          callback(event.newValue ? JSON.parse(event.newValue) : null);
-        }
-      });
-    }
+    if (typeof window === "undefined")
+      return;
+    window.addEventListener("storage", (event) => {
+      if (event.key !== key)
+        return;
+      this.fallback.delete(key);
+      try {
+        callback(event.newValue ? JSON.parse(event.newValue) : null);
+      } catch (err) {
+        console.warn(`Moonbase could not parse the stored value for ${key}`, err);
+      }
+    });
+  }
+  reportDegraded(err) {
+    var _a;
+    if (this.degraded)
+      return;
+    this.degraded = true;
+    (_a = this.onDegraded) == null ? void 0 : _a.call(this, err);
   }
 };
 var InMemoryStore = class {
@@ -1544,8 +1675,11 @@ var _TokenStore = class _TokenStore {
     this.tokens = null;
     this.refreshTimeoutId = null;
     this.refreshPromise = null;
-    var _a;
-    this.store = (_a = configuration.store) != null ? _a : typeof window !== "undefined" && localStorage ? new LocalStorageStore() : new InMemoryStore();
+    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 = {
@@ -1560,18 +1694,17 @@ var _TokenStore = class _TokenStore {
       return this.tokens;
     return null;
   }
+  get isPersistent() {
+    return this.store instanceof LocalStorageStore && !this.store.isDegraded;
+  }
   async getAccessToken() {
     var _a, _b, _c;
-    if (this.isExpired) {
-      if (this.refreshPromise) {
-        const tokens2 = await this.refreshPromise;
-        return (_a = tokens2 == null ? void 0 : tokens2.accessToken) != null ? _a : null;
-      }
-      this.refreshPromise = this.refreshTokens();
-      const tokens = await this.refreshPromise;
-      return (_b = tokens == null ? void 0 : tokens.accessToken) != null ? _b : null;
+    if (!this.isExpired) {
+      return ((_a = this.tokens) == null ? void 0 : _a.accessToken) || null;
     }
-    return ((_c = this.tokens) == null ? void 0 : _c.accessToken) || null;
+    const pending = (_b = this.refreshPromise) != null ? _b : this.startRefresh();
+    const tokens = await pending;
+    return (_c = tokens == null ? void 0 : tokens.accessToken) != null ? _c : null;
   }
   setUser(user) {
     const identity = user;
@@ -1596,7 +1729,7 @@ var _TokenStore = class _TokenStore {
       if (this.refreshTimeoutId != null)
         window.clearTimeout(this.refreshTimeoutId);
       this.refreshTimeoutId = window.setTimeout(() => {
-        this.refreshPromise = this.refreshTokens();
+        this.startRefresh().catch((err) => this.logger.warn("Could not refresh access token", err));
       }, 10 * 60 * 1e3);
     }
     return this.tokens;
@@ -1611,10 +1744,25 @@ var _TokenStore = class _TokenStore {
   get isExpired() {
     return this.tokens != null && this.tokens.expiresAt < /* @__PURE__ */ new Date();
   }
+  /**
+   * Start a refresh and hold it so concurrent callers join it rather than firing
+   * their own. The slot is cleared as soon as it settles: a retained promise
+   * would hand every later expiry the same stale access token, and a rejected one
+   * that stayed put would re-throw on every subsequent request (including the
+   * anonymous ones) for the rest of the session.
+   */
+  startRefresh() {
+    const pending = this.refreshTokens().finally(() => {
+      if (this.refreshPromise === pending)
+        this.refreshPromise = null;
+    });
+    this.refreshPromise = pending;
+    return pending;
+  }
   async refreshTokens() {
     if (!this.tokens)
       throw new Error("No tokens found to refresh");
-    const response = await fetch(`${this.configuration.endpoint}/api/customer/identity/refresh?token=${this.tokens.refreshToken}`, {
+    const response = await fetch(`${this.configuration.endpoint}/api/customer/identity/refresh?token=${encodeURIComponent(this.tokens.refreshToken)}`, {
       method: "POST",
       headers: {
         "Accept": "application/json",
@@ -1636,12 +1784,18 @@ var _TokenStore = class _TokenStore {
   }
   handleStorageUpdate(updatedTokens) {
     this.tokens = updatedTokens;
-    if (this.refreshTimeoutId != null)
+    if (this.refreshTimeoutId != null && typeof window !== "undefined")
       window.clearTimeout(this.refreshTimeoutId);
     if (this.tokens) {
       this.tokens.expiresAt = new Date(this.tokens.expiresAt);
     }
   }
+  warnAboutStorage(err) {
+    this.logger.warn(
+      "Moonbase could not persist credentials to localStorage: this browser is blocking or has exhausted site storage. Sign-in will work for this page load but will not survive a reload.",
+      err
+    );
+  }
 };
 _TokenStore.storageKey = "moonbase_auth";
 var TokenStore = _TokenStore;
@@ -2336,6 +2490,7 @@ var MoonbaseClient = class {
     this.storefront = new StorefrontEndpoints(this.api, this.configuration);
     this.identity = new IdentityEndpoints(this.api, this.tokenStore, this.logger);
     this.communications = new CommunicationsEndpoints(this.api);
+    this.groups = new GroupEndpoints(this.api);
     this.vouchers = new VoucherEndpoints(this.api);
     this.orders = new OrderEndpoints(this.api);
     this.inventory = new InventoryEndpoints(this.api, this.configuration);
@@ -2373,9 +2528,11 @@ export {
   SubscriptionStatus,
   TokenStore,
   imageWidths,
+  isLocalStorageAvailable,
   isPromotionDisplay,
   isTransformableImageUrl,
   maxImageDimension,
+  normalizeGroupIds,
   objectToQuery,
   parseOffSiteReferrer,
   problemDetailsSchema,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonbase.sh/storefront-api",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Package to let you build storefronts with Moonbase.sh as payment and delivery provider",
   "author": "Tobias Lønnerød Madsen <m@dsen.tv>",
   "license": "MIT",