swell-js 5.9.3 → 5.10.0

package/README.md

@@ -13,7 +13,49 @@ Universal JavaScript client for Swell's Frontend API, providing client-safe acce
 
 **About Swell**
 
-[Swell](https://www.swell.is) is a customizable, API-first platform for powering modern B2C/B2B shopping experiences and marketplaces. Build and connect anything using your favorite technologies, and provide admins with an easy to use dashboard.
+[Swell](https://www.swell.is) is an ecommerce platform with subscriptions and B2B pricing built in. Run your store on a Swell theme, or [go headless](https://www.swell.is/headless-commerce) with its APIs.
+
+## Checkout payments
+
+Besides `createElements`, `tokenize` and `handleRedirect` (see the documentation), `swell.payment` offers helpers a checkout page needs:
+
+- `tokenize({ card: { createIntent: false } })` stores a Stripe card without authorizing it now. `tokenize({ card: { paymentMethod: 'pm_…' } })` authorizes a Stripe card the shopper already has (a saved card, a wallet's payment method) with an intent and 3-D Secure, like a new card, before the order is submitted. Both reuse the cart's intent while it still matches the card and amount.
+- Saferpay card and TWINT (`twint`) redirect to the Saferpay payment page from `tokenize` and come back through `handleRedirect`; iDEAL returns through `handleRedirect({ ideal })` too.
+- Stripe iDEAL needs no element: `tokenize({ ideal: {} })` without `createElements` redirects to the iDEAL page, where the shopper picks the bank, and returns through `handleRedirect({ ideal })`.
+- `handleAsyncRedirect(order)` sends the shopper to the gateway when a submitted order waits for an asynchronous payment.
+- Stripe card and iDEAL can render through the Stripe [Payment Element](https://docs.stripe.com/payments/payment-element) instead of the split elements: pass `paymentElement: true` to both `createElements` and `tokenize`. Stripe draws the whole form (fields, labels, errors) and takes its look from `appearance` ([Appearance API](https://docs.stripe.com/elements/appearance-api)). The element mounts into `#payment-element` unless `elementId` is set; `options` go to `elements.create('payment')` over the defaults `layout: 'tabs'`, `fields.billingDetails: 'never'` (billing details come from the cart) and no Apple Pay / Google Pay. `tokenize` re-reads the cart and updates the amount before `elements.submit()`, so a changed cart total needs no extra call.
+
+```js
+const card = {
+  paymentElement: true,
+  appearance: {
+    theme: 'stripe',
+    labels: 'floating',
+    variables: { colorPrimary: '#111' },
+  },
+  elementId: 'card-payment-element',
+  onChange: (event) => setComplete(event.complete),
+  onSuccess: () => submitOrder(),
+  onError: (error) => showError(error.message),
+};
+
+await swell.payment.createElements({ card });
+// on "Pay": validates, creates the PaymentMethod and the intent, stores them on the cart
+await swell.payment.tokenize({ card });
+
+// iDEAL: the same flag; tokenize redirects to the bank and returns through handleRedirect({ ideal })
+await swell.payment.createElements({
+  ideal: {
+    paymentElement: true,
+    appearance,
+    elementId: 'ideal-payment-element',
+  },
+});
+```
+
+## Deprecated
+
+- `swell.app` (app components rendered by swell-js) is deprecated and will be removed in the next major version. Apps render their components through [`@swell/apps-sdk/components`](https://www.npmjs.com/package/@swell/apps-sdk) instead; hosted checkout mounts payment components at the place `checkout.payment.methods`.
 
 ## Documentation
 

package/dist/api.mjs

@@ -1,21 +1,21 @@
-import methods$5 from './card.mjs';
+import methods$6 from './card.mjs';
 import { getCookie, setCookie } from './cookie.mjs';
-import methods$4 from './cache.mjs';
-import methods$3 from './cart.mjs';
-import methods$6 from './account.mjs';
-import { j as isFunction, l as loadScript, e as isObject, v as vaultRequest, k as isEmpty, d as defaultMethods, x as trimEnd, y as utils, z as trimStart, A as trimBoth, b as toSnake, o as base64Encode, i as isServer, t as toCamel } from './index.76eb52e5.mjs';
+import methods$5 from './cache.mjs';
+import methods$4 from './cart.mjs';
+import methods$7 from './account.mjs';
+import { j as isFunction, l as loadScript, e as isObject, v as vaultRequest, k as isEmpty, d as defaultMethods, i as isServer, x as trimEnd, y as utils, z as trimStart, A as trimBoth, b as toSnake, o as base64Encode, t as toCamel } from './index.76eb52e5.mjs';
 import { Q as stringifyQuery } from './find.ba551a2e.mjs';
 import 'deepmerge';
 import 'fast-case';
-import methods$7 from './products.mjs';
-import methods$8 from './categories.mjs';
-import methods$9 from './attributes.mjs';
-import methods$a from './subscriptions.mjs';
-import methods$b from './content.mjs';
-import methods$c from './settings.mjs';
+import methods$8 from './products.mjs';
+import methods$9 from './categories.mjs';
+import methods$a from './attributes.mjs';
+import methods$b from './subscriptions.mjs';
+import methods$c from './content.mjs';
+import methods$d from './settings.mjs';
 import PaymentController from './payment.mjs';
-import methods$d from './locale.mjs';
-import methods$e, { isCurrencyCode } from './currency.mjs';
+import methods$e from './locale.mjs';
+import methods$f, { isCurrencyCode } from './currency.mjs';
 import './round.c68b8be5.mjs';
 
 class AppComponent {
@@ -81,7 +81,7 @@ class AppComponent {
   }
 
   async updateCart(data) {
-    const cart = await methods$3(this.api, this.options).update(data);
+    const cart = await methods$4(this.api, this.options).update(data);
 
     this.setProps({ cart });
   }
@@ -122,6 +122,10 @@ class AppComponent {
   }
 }
 
+/**
+ * @deprecated Payment components are mounted by `@swell/apps-sdk/components`
+ * at the host place `checkout.payment.methods`.
+ */
 class AppPaymentComponent extends AppComponent {
   constructor(app, component, api, options) {
     super(app, component, api, options);
@@ -171,6 +175,7 @@ class AppPaymentComponent extends AppComponent {
   }
 }
 
+/** @deprecated Use `@swell/apps-sdk/components` instead. */
 class App {
   constructor(app, api, options) {
     this.app = app;
@@ -279,6 +284,13 @@ class App {
   }
 }
 
+let deprecationWarned = false;
+
+/**
+ * @deprecated App components are rendered by `@swell/apps-sdk/components`
+ * (`createComponents().mount()`); this module will be removed in the next
+ * major version.
+ */
 class AppController {
   #apps = new Map();
 
@@ -287,7 +299,15 @@ class AppController {
     this.options = options;
   }
 
+  /** @deprecated Use `@swell/apps-sdk/components` instead. */
   async load(appId) {
+    if (!deprecationWarned) {
+      deprecationWarned = true;
+      console.warn(
+        'swell.app is deprecated: render app components with @swell/apps-sdk/components',
+      );
+    }
+
     const loadedApp = this.#apps.get(appId);
 
     if (loadedApp) {
@@ -317,7 +337,7 @@ class AppController {
   }
 }
 
-function methods$2(api) {
+function methods$3(api) {
   const { get, list } = defaultMethods(api, '/invoices', ['list', 'get']);
   return {
     get: (id, ...args) => {
@@ -328,7 +348,7 @@ function methods$2(api) {
   };
 }
 
-function methods$1(api, opt) {
+function methods$2(api, opt) {
   return {
     /**
      * Get the decoded session as an object of session values
@@ -355,7 +375,7 @@ function methods$1(api, opt) {
   };
 }
 
-function methods(api, _opt) {
+function methods$1(api, _opt) {
   return {
     /**
      * Make a request to an app function and greceiveet a response
@@ -424,6 +444,85 @@ function methods(api, _opt) {
   };
 }
 
+const PURPOSES = ['analytics', 'marketing', 'sale_of_data'];
+
+/**
+ * The page the shopper landed on, which the consent call sends along: the
+ * first URL of this document and its referrer. Read when needed, so nothing
+ * is kept before the shopper answers.
+ *
+ * @returns {{url: string, referrer: string} | undefined}
+ */
+function getLanding() {
+  if (isServer()) {
+    return undefined;
+  }
+
+  let url = window.location.href;
+
+  try {
+    const [navigation] = window.performance.getEntriesByType('navigation');
+    if (navigation?.name) {
+      url = navigation.name;
+    }
+  } catch {
+    // Navigation timing is not available
+  }
+
+  return { url, referrer: window.document.referrer || '' };
+}
+
+function methods(api) {
+  // Calls run one after another. Consent tools fire several events for one
+  // answer, and the first call may set the visitor cookie that the next one
+  // has to send: in parallel, each would start a visitor of its own.
+  let queue = Promise.resolve();
+
+  return {
+    /**
+     * Records the shopper's consent for attribution, from the storefront's
+     * consent banner. Purposes left out stay as they are.
+     *
+     * Calls the storefront's own origin, so that Swell sees the page's
+     * cookies and sets the visitor cookie on the storefront's domain.
+     *
+     * @param {{analytics?: boolean, marketing?: boolean, sale_of_data?: boolean}} consent
+     */
+    set(consent = {}) {
+      if (isServer()) {
+        return Promise.reject(new Error('consent.set() runs in the browser'));
+      }
+
+      const data = {};
+
+      for (const purpose of PURPOSES) {
+        // camelCase clients pass saleOfData
+        const camel = purpose.replace(/_(\w)/g, (_m, c) => c.toUpperCase());
+        const value = consent[purpose] ?? consent[camel];
+
+        if (typeof value === 'boolean') {
+          data[purpose] = value;
+        }
+      }
+
+      const result = queue.then(() =>
+        api.request(
+          'put',
+          '/session/consent',
+          { ...data, landing: getLanding() },
+          undefined,
+          { fullUrl: `${window.location.origin}/api/session/consent` },
+        ),
+      );
+
+      // A failed call doesn't hold back the next one
+      queue = result.catch(() => undefined);
+
+      return result;
+    },
+  };
+}
+
 /**
  * @template {'snake' | 'camel'} C
  * @typedef {import('../types').InitOptions<C>} InitOptions<C>
@@ -455,7 +554,7 @@ function swell(initStore = undefined, initKey, initOptions = {}) {
   const api = {};
 
   Object.assign(api, {
-    version: '5.9.3',
+    version: '5.10.0',
     options,
     request,
 
@@ -509,39 +608,41 @@ function swell(initStore = undefined, initKey, initOptions = {}) {
       return api.request('delete', url, data);
     },
 
-    cache: methods$4(options),
+    cache: methods$5(options),
 
-    card: methods$5(options),
+    card: methods$6(options),
 
-    cart: methods$3(api, options),
+    cart: methods$4(api, options),
 
-    account: methods$6(api),
+    account: methods$7(api),
 
     app: new AppController(api, options),
 
-    products: methods$7(api, options),
+    products: methods$8(api, options),
 
-    categories: methods$8(api),
+    categories: methods$9(api),
 
-    attributes: methods$9(api),
+    attributes: methods$a(api),
 
-    subscriptions: methods$a(api),
+    subscriptions: methods$b(api),
 
-    invoices: methods$2(api),
+    invoices: methods$3(api),
 
-    content: methods$b(api, options),
+    content: methods$c(api, options),
 
-    settings: methods$c(api, options),
+    settings: methods$d(api, options),
 
     payment: new PaymentController(api, options),
 
-    locale: methods$d(api, options),
+    locale: methods$e(api, options),
+
+    currency: methods$f(api, options),
 
-    currency: methods$e(api, options),
+    session: methods$2(api, options),
 
-    session: methods$1(api, options),
+    functions: methods$1(api),
 
-    functions: methods(api),
+    consent: methods(api),
 
     utils,
 
@@ -615,6 +716,13 @@ function swell(initStore = undefined, initKey, initOptions = {}) {
       reqHeaders['X-Session'] = session;
     }
 
+    // The storefront's visitor, for attribution: the cookie is on the
+    // storefront's domain and doesn't reach the store's API host
+    const visitor = allOptions.getCookie('swell-visitor');
+    if (visitor) {
+      reqHeaders['X-Visitor'] = visitor;
+    }
+
     if (locale) {
       reqHeaders['X-Locale'] = locale;
     }