@moonbase.sh/storefront-api 3.2.0 → 3.3.1

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
 

package/dist/index.cjs

@@ -53,6 +53,7 @@ __export(index_exports, {
   isPromotionDisplay: () => isPromotionDisplay,
   isTransformableImageUrl: () => isTransformableImageUrl,
   maxImageDimension: () => maxImageDimension,
+  normalizeGroupIds: () => normalizeGroupIds,
   objectToQuery: () => objectToQuery,
   parseOffSiteReferrer: () => parseOffSiteReferrer,
   problemDetailsSchema: () => problemDetailsSchema,
@@ -490,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, {
@@ -523,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;
@@ -565,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() {
@@ -768,7 +814,7 @@ var IdentityEndpoints = class {
     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",
@@ -783,7 +829,8 @@ var IdentityEndpoints = class {
         password,
         address,
         acceptedPrivacyPolicy,
-        acceptedTermsAndConditions
+        acceptedTermsAndConditions,
+        groupIds: normalizeGroupIds(options == null ? void 0 : options.groupIds)
       })
     });
     if (response.status >= 400)
@@ -1505,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
@@ -2481,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);
@@ -2523,6 +2593,7 @@ var MoonbaseClient = class {
   isPromotionDisplay,
   isTransformableImageUrl,
   maxImageDimension,
+  normalizeGroupIds,
   objectToQuery,
   parseOffSiteReferrer,
   problemDetailsSchema,

package/dist/index.d.cts

@@ -1123,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;
@@ -1139,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;
@@ -1631,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;
@@ -1639,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;
@@ -2692,17 +2733,17 @@ declare const milestoneProgressSchema: z.ZodObject<{
     fromNormalizedCycleNumber: z.ZodNumber;
     toCycleNumber: z.ZodNumber;
     toNormalizedCycleNumber: z.ZodNumber;
-    events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
+    events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         milestoneId: z.ZodString;
         fulfilled: z.ZodBoolean;
         afterCycleNumber: z.ZodNumber;
         afterNormalizedCycleNumber: z.ZodNumber;
         message: z.ZodOptional<z.ZodString>;
-    }, {
+    } & {
         type: z.ZodLiteral<"CouponCodeMilestone">;
         code: z.ZodOptional<z.ZodString>;
         redeemed: z.ZodOptional<z.ZodBoolean>;
-    }>, "strip", z.ZodTypeAny, {
+    }, "strip", z.ZodTypeAny, {
         type: "CouponCodeMilestone";
         milestoneId: string;
         fulfilled: boolean;
@@ -2720,15 +2761,15 @@ declare const milestoneProgressSchema: z.ZodObject<{
         code?: string | undefined;
         message?: string | undefined;
         redeemed?: boolean | undefined;
-    }>, z.ZodObject<z.objectUtil.extendShape<{
+    }>, z.ZodObject<{
         milestoneId: z.ZodString;
         fulfilled: z.ZodBoolean;
         afterCycleNumber: z.ZodNumber;
         afterNormalizedCycleNumber: z.ZodNumber;
         message: z.ZodOptional<z.ZodString>;
-    }, {
+    } & {
         type: z.ZodLiteral<"PerpetualLicenseConversionMilestone">;
-    }>, "strip", z.ZodTypeAny, {
+    }, "strip", z.ZodTypeAny, {
         type: "PerpetualLicenseConversionMilestone";
         milestoneId: string;
         fulfilled: boolean;
@@ -2931,17 +2972,17 @@ declare const subscriptionSchema: z.ZodObject<{
         fromNormalizedCycleNumber: z.ZodNumber;
         toCycleNumber: z.ZodNumber;
         toNormalizedCycleNumber: z.ZodNumber;
-        events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
+        events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             milestoneId: z.ZodString;
             fulfilled: z.ZodBoolean;
             afterCycleNumber: z.ZodNumber;
             afterNormalizedCycleNumber: z.ZodNumber;
             message: z.ZodOptional<z.ZodString>;
-        }, {
+        } & {
             type: z.ZodLiteral<"CouponCodeMilestone">;
             code: z.ZodOptional<z.ZodString>;
             redeemed: z.ZodOptional<z.ZodBoolean>;
-        }>, "strip", z.ZodTypeAny, {
+        }, "strip", z.ZodTypeAny, {
             type: "CouponCodeMilestone";
             milestoneId: string;
             fulfilled: boolean;
@@ -2959,15 +3000,15 @@ declare const subscriptionSchema: z.ZodObject<{
             code?: string | undefined;
             message?: string | undefined;
             redeemed?: boolean | undefined;
-        }>, z.ZodObject<z.objectUtil.extendShape<{
+        }>, z.ZodObject<{
             milestoneId: z.ZodString;
             fulfilled: z.ZodBoolean;
             afterCycleNumber: z.ZodNumber;
             afterNormalizedCycleNumber: z.ZodNumber;
             message: z.ZodOptional<z.ZodString>;
-        }, {
+        } & {
             type: z.ZodLiteral<"PerpetualLicenseConversionMilestone">;
-        }>, "strip", z.ZodTypeAny, {
+        }, "strip", z.ZodTypeAny, {
             type: "PerpetualLicenseConversionMilestone";
             milestoneId: string;
             fulfilled: boolean;
@@ -13027,7 +13068,7 @@ declare const completedOrderSchema: z.ZodObject<{
         validUntil?: string | undefined;
     } | undefined;
 }>;
-declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.objectUtil.extendShape<{
+declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -14408,9 +14449,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Open>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Open;
     currency: string;
@@ -14954,7 +14995,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -16335,9 +16376,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.PaymentProcessing>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.PaymentProcessing;
     currency: string;
@@ -16881,7 +16922,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -18262,9 +18303,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Paid>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Paid;
     currency: string;
@@ -18808,7 +18849,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -20189,9 +20230,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Failed>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Failed;
     currency: string;
@@ -24189,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 {
@@ -46932,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.
  *
@@ -47072,6 +47149,7 @@ declare class MoonbaseClient {
     storefront: StorefrontEndpoints;
     identity: IdentityEndpoints;
     communications: CommunicationsEndpoints;
+    groups: GroupEndpoints;
     vouchers: VoucherEndpoints;
     activationRequests: ActivationRequestEndpoints;
     inventory: InventoryEndpoints;
@@ -47079,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, isLocalStorageAvailable, 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

@@ -1123,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;
@@ -1139,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;
@@ -1631,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;
@@ -1639,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;
@@ -2692,17 +2733,17 @@ declare const milestoneProgressSchema: z.ZodObject<{
     fromNormalizedCycleNumber: z.ZodNumber;
     toCycleNumber: z.ZodNumber;
     toNormalizedCycleNumber: z.ZodNumber;
-    events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
+    events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         milestoneId: z.ZodString;
         fulfilled: z.ZodBoolean;
         afterCycleNumber: z.ZodNumber;
         afterNormalizedCycleNumber: z.ZodNumber;
         message: z.ZodOptional<z.ZodString>;
-    }, {
+    } & {
         type: z.ZodLiteral<"CouponCodeMilestone">;
         code: z.ZodOptional<z.ZodString>;
         redeemed: z.ZodOptional<z.ZodBoolean>;
-    }>, "strip", z.ZodTypeAny, {
+    }, "strip", z.ZodTypeAny, {
         type: "CouponCodeMilestone";
         milestoneId: string;
         fulfilled: boolean;
@@ -2720,15 +2761,15 @@ declare const milestoneProgressSchema: z.ZodObject<{
         code?: string | undefined;
         message?: string | undefined;
         redeemed?: boolean | undefined;
-    }>, z.ZodObject<z.objectUtil.extendShape<{
+    }>, z.ZodObject<{
         milestoneId: z.ZodString;
         fulfilled: z.ZodBoolean;
         afterCycleNumber: z.ZodNumber;
         afterNormalizedCycleNumber: z.ZodNumber;
         message: z.ZodOptional<z.ZodString>;
-    }, {
+    } & {
         type: z.ZodLiteral<"PerpetualLicenseConversionMilestone">;
-    }>, "strip", z.ZodTypeAny, {
+    }, "strip", z.ZodTypeAny, {
         type: "PerpetualLicenseConversionMilestone";
         milestoneId: string;
         fulfilled: boolean;
@@ -2931,17 +2972,17 @@ declare const subscriptionSchema: z.ZodObject<{
         fromNormalizedCycleNumber: z.ZodNumber;
         toCycleNumber: z.ZodNumber;
         toNormalizedCycleNumber: z.ZodNumber;
-        events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<z.objectUtil.extendShape<{
+        events: z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             milestoneId: z.ZodString;
             fulfilled: z.ZodBoolean;
             afterCycleNumber: z.ZodNumber;
             afterNormalizedCycleNumber: z.ZodNumber;
             message: z.ZodOptional<z.ZodString>;
-        }, {
+        } & {
             type: z.ZodLiteral<"CouponCodeMilestone">;
             code: z.ZodOptional<z.ZodString>;
             redeemed: z.ZodOptional<z.ZodBoolean>;
-        }>, "strip", z.ZodTypeAny, {
+        }, "strip", z.ZodTypeAny, {
             type: "CouponCodeMilestone";
             milestoneId: string;
             fulfilled: boolean;
@@ -2959,15 +3000,15 @@ declare const subscriptionSchema: z.ZodObject<{
             code?: string | undefined;
             message?: string | undefined;
             redeemed?: boolean | undefined;
-        }>, z.ZodObject<z.objectUtil.extendShape<{
+        }>, z.ZodObject<{
             milestoneId: z.ZodString;
             fulfilled: z.ZodBoolean;
             afterCycleNumber: z.ZodNumber;
             afterNormalizedCycleNumber: z.ZodNumber;
             message: z.ZodOptional<z.ZodString>;
-        }, {
+        } & {
             type: z.ZodLiteral<"PerpetualLicenseConversionMilestone">;
-        }>, "strip", z.ZodTypeAny, {
+        }, "strip", z.ZodTypeAny, {
             type: "PerpetualLicenseConversionMilestone";
             milestoneId: string;
             fulfilled: boolean;
@@ -13027,7 +13068,7 @@ declare const completedOrderSchema: z.ZodObject<{
         validUntil?: string | undefined;
     } | undefined;
 }>;
-declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.objectUtil.extendShape<{
+declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -14408,9 +14449,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Open>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Open;
     currency: string;
@@ -14954,7 +14995,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -16335,9 +16376,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.PaymentProcessing>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.PaymentProcessing;
     currency: string;
@@ -16881,7 +16922,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -18262,9 +18303,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Paid>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Paid;
     currency: string;
@@ -18808,7 +18849,7 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl?: string | undefined;
     hostedCheckoutUrl?: string | undefined;
     embeddedCheckoutUrl?: string | undefined;
-}>, z.ZodObject<z.objectUtil.extendShape<{
+}>, z.ZodObject<{
     id: z.ZodString;
     currency: z.ZodString;
     total: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -20189,9 +20230,9 @@ declare const orderSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<z.obje
     checkoutUrl: z.ZodOptional<z.ZodString>;
     hostedCheckoutUrl: z.ZodOptional<z.ZodString>;
     embeddedCheckoutUrl: z.ZodOptional<z.ZodString>;
-}, {
+} & {
     status: z.ZodLiteral<OrderStatus.Failed>;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     status: OrderStatus.Failed;
     currency: string;
@@ -24189,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 {
@@ -46932,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.
  *
@@ -47072,6 +47149,7 @@ declare class MoonbaseClient {
     storefront: StorefrontEndpoints;
     identity: IdentityEndpoints;
     communications: CommunicationsEndpoints;
+    groups: GroupEndpoints;
     vouchers: VoucherEndpoints;
     activationRequests: ActivationRequestEndpoints;
     inventory: InventoryEndpoints;
@@ -47079,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, isLocalStorageAvailable, 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() {
@@ -709,7 +754,7 @@ var IdentityEndpoints = class {
     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)
@@ -1446,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
@@ -2422,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);
@@ -2463,6 +2532,7 @@ export {
   isPromotionDisplay,
   isTransformableImageUrl,
   maxImageDimension,
+  normalizeGroupIds,
   objectToQuery,
   parseOffSiteReferrer,
   problemDetailsSchema,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonbase.sh/storefront-api",
   "type": "module",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "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",