@lightspeed/online-payments-sdk 1.5.0 → 1.6.1

package/README.md

@@ -1 +1,92 @@
-# Process payments with Lightspeed Payments
+# Lightspeed Online Payments SDK
+
+`@lightspeed/online-payments-sdk` is a browser SDK for mounting Lightspeed Payments widgets (Stripe and Adyen) in web applications.
+
+## Installation
+
+```sh
+npm install @lightspeed/online-payments-sdk
+```
+
+## Quick start
+
+```ts
+import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
+
+const controller = await LightspeedPayments.v1.mountPaymentWidget(sessionToken, {
+  mountPoint: document.getElementById('payment-widget')!,
+});
+
+controller.unmount();
+```
+
+## Compatibility
+
+- TypeScript/JavaScript
+- Browser runtime (requires `window`)
+
+## Theming
+
+The SDK supports custom themes. If no theme is specified, Stripe defaults are used.
+
+### Available themes
+
+- default (no `theme` value)
+- `invoicing`
+- `dark`
+
+```ts
+import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
+
+await LightspeedPayments.v1.mountPaymentWidget(paymentSession, {
+  mountPoint: document.getElementById('payment-widget')!,
+  theme: 'dark',
+});
+```
+
+### Container styling
+
+For dark mode, the SDK styles the mount element you pass in `mountPoint`. If you style a parent wrapper, use `THEME_COLORS`.
+
+```ts
+import {THEME_COLORS} from '@lightspeed/online-payments-sdk';
+```
+
+## Documentation
+
+- Datadog logging reference: `packages/lsp-online-payments-sdk/docs/DATADOG_LOGGING.md`
+
+## Development
+
+Run SDK checks (same order as CI):
+
+```sh
+npm run lint --workspace @lightspeed/online-payments-sdk
+npm run typecheck --workspace @lightspeed/online-payments-sdk
+npm run test --workspace @lightspeed/online-payments-sdk
+```
+
+Build package:
+
+```sh
+npm run build --workspace @lightspeed/online-payments-sdk
+```
+
+Inspect publish contents:
+
+```sh
+npm pack --dry-run
+```
+
+## Publishing and release flow
+
+Publishing is handled by CircleCI (not manual local publish).
+
+- Release path runs on `main` and `release/*`.
+- CircleCI runs quality gates (`lint`, `typecheck`, unit tests, build, e2e).
+- `verify_package_version` compares local `package.json` version with npm.
+- If local version is not higher, publish is skipped.
+- If local version is higher, the workflow pauses at manual approval (`pause_workflow`).
+- A human must approve before the `release` job runs `npm publish`.
+
+In practice: bump `version` in `packages/lsp-online-payments-sdk/package.json`, merge to `main`, then approve the release hold in CircleCI.

package/dist/cjs/v1/EventBroadcaster.js

@@ -33,6 +33,9 @@ var EventBroadcaster = /** @class */ (function () {
         if ('paymentMethodType' in event && event.paymentMethodType) {
             externalEvent.paymentMethodType = event.paymentMethodType;
         }
+        if ('saveCheckboxChecked' in event && event.saveCheckboxChecked !== undefined) {
+            externalEvent.saveCheckboxChecked = event.saveCheckboxChecked;
+        }
         return externalEvent;
     };
     EventBroadcaster.prototype.registerMiddleware = function (middleware) {

package/dist/cjs/v1/stripe/shared.js

@@ -93,9 +93,11 @@ function initStripe(context, theme) {
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
+ * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
  */
-function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName) {
+function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, showCardMandate) {
     if (hideNameField === void 0) { hideNameField = false; }
+    if (showCardMandate === void 0) { showCardMandate = false; }
     var options = __assign(__assign(__assign({ wallets: {
             applePay: 'never',
             googlePay: 'never',
@@ -106,9 +108,7 @@ function createPaymentElementOptions(defaultValues, theme, hideNameField, busine
                 name: 'never', // prevent duplicate Name field on the form when using ACH (only when address element is present)
             },
         },
-    })), { terms: {
-            usBankAccount: 'never', // Hide Stripe's default T&Cs (shown for ACH payments)
-        } }), (businessName && { business: { name: businessName } }));
+    })), { terms: __assign({ usBankAccount: 'never' }, (showCardMandate && businessName && { card: 'always' })) }), (businessName && { business: { name: businessName } }));
     if (defaultValues) {
         options.defaultValues = {
             billingDetails: {
@@ -222,17 +222,22 @@ function createPaymentElement(elements, options, mountElement, eventBroadcaster)
  * When addressElement is provided (payment form): emits "Complete" only when BOTH elements are complete,
  * and "Incomplete" when at least one element becomes incomplete.
  * When addressElement is not provided (MOTO form): emits based on payment element completion only.
+ * Also includes the current save-payment-method checkbox state (when present) on every Change event,
+ * and emits a Change event when that checkbox state changes.
  */
 function setupChangeEventHandler(paymentElement, eventBroadcaster, addressElement) {
     var paymentComplete = false;
     var addressComplete = !addressElement; // If no address element, consider it complete
     var previousComplete = null;
     var previousMethodType;
+    var previousSaveCheckboxState; // Track save checkbox state
     var emitChangeEvent = function () {
         var complete = paymentComplete && addressComplete;
         previousComplete = complete;
-        eventBroadcaster.publish(__assign({ status: 'Change', code: complete ? 'Complete' : 'Incomplete' }, (previousMethodType && {
+        eventBroadcaster.publish(__assign(__assign({ status: 'Change', code: complete ? 'Complete' : 'Incomplete' }, (previousMethodType && {
             paymentMethodType: previousMethodType,
+        })), (previousSaveCheckboxState !== undefined && {
+            saveCheckboxChecked: previousSaveCheckboxState,
         })));
     };
     paymentElement.on('change', function (event) {
@@ -244,7 +249,15 @@ function setupChangeEventHandler(paymentElement, eventBroadcaster, addressElemen
         if (methodType !== undefined) {
             previousMethodType = methodType;
         }
-        if (completenessChanged || methodTypeChanged) {
+        // Check for save checkbox state from Stripe's value object
+        // The value object may contain a `savePaymentMethod` property
+        var saveCheckboxChanged = false;
+        if (event.value && typeof event.value === 'object' && 'savePaymentMethod' in event.value) {
+            var saveCheckboxState = event.value.savePaymentMethod;
+            saveCheckboxChanged = previousSaveCheckboxState !== saveCheckboxState;
+            previousSaveCheckboxState = saveCheckboxState;
+        }
+        if (completenessChanged || methodTypeChanged || saveCheckboxChanged) {
             emitChangeEvent();
         }
     });

package/dist/cjs/v1/stripe/widgets/payment.js

@@ -43,7 +43,7 @@ var shared_1 = require("../shared");
  */
 function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, addressOptions, _b, addressElement, addressContainer, paymentOptions, _c, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, addressOptions, _b, addressElement, addressContainer, productMetadata, isPartnerProduct, showCardMandate, paymentOptions, _c, paymentElement, paymentContainer, customTermsContainer;
         return __generator(this, function (_d) {
             switch (_d.label) {
                 case 0: return [4 /*yield*/, (0, shared_1.initStripe)(session.context, theme)];
@@ -51,7 +51,13 @@ function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValu
                     _a = _d.sent(), stripe = _a.stripe, elements = _a.elements;
                     addressOptions = (0, shared_1.createAddressElementOptions)(defaultValues);
                     _b = (0, shared_1.createAddressElement)(elements, addressOptions, mountElement), addressElement = _b.element, addressContainer = _b.container;
-                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, true, session.context.businessName);
+                    productMetadata = session.metadata.product;
+                    isPartnerProduct = typeof productMetadata === 'string' &&
+                        productMetadata.startsWith('partner:');
+                    showCardMandate = session.metadata.sessionType === 'payment-with-save' &&
+                        !!session.context.businessName &&
+                        isPartnerProduct;
+                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, true, session.context.businessName, showCardMandate);
                     _c = (0, shared_1.createPaymentElement)(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _c.element, paymentContainer = _c.container, customTermsContainer = _c.customTermsContainer;
                     // Setup change handler that emits Complete only when both elements are complete
                     (0, shared_1.setupChangeEventHandler)(paymentElement, eventBroadcaster, addressElement);

package/dist/cjs/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // This file is auto-generated during the build process
 // DO NOT EDIT MANUALLY - Version is extracted from package.json
-exports.SDK_VERSION = '1.5.0';
+exports.SDK_VERSION = '1.6.1';

package/dist/v1/EventBroadcaster.d.ts

@@ -23,13 +23,15 @@ export type ChangeEvent = BaseEvent & {
     status: 'Change';
     code: 'Complete' | 'Incomplete';
     paymentMethodType?: string;
+    saveCheckboxChecked?: boolean;
 };
 export type ErrorResultEvent = BaseEvent & {
     code: SupportedErrorCodes;
     status: 'Error';
 };
 export type InternalEvent = SucceededResultEvent | PendingResultEvent | DeclinedResultEvent | ErrorResultEvent | ReadyEvent | ChangeEvent;
-export type Event = Omit<InternalEvent, 'loggingEnrichment'>;
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+export type Event = DistributiveOmit<InternalEvent, 'loggingEnrichment'>;
 export type EventHandler = (result: Event) => void;
 export type EventMiddleware = (event: InternalEvent) => InternalEvent | void;
 export type EventListeners = Partial<Record<`on${Status}`, EventHandler>>;
@@ -42,3 +44,4 @@ export declare class EventBroadcaster {
     applyMiddlewares(event: InternalEvent): Event;
     publish(event: InternalEvent): void;
 }
+export {};

package/dist/v1/EventBroadcaster.js

@@ -30,6 +30,9 @@ var EventBroadcaster = /** @class */ (function () {
         if ('paymentMethodType' in event && event.paymentMethodType) {
             externalEvent.paymentMethodType = event.paymentMethodType;
         }
+        if ('saveCheckboxChecked' in event && event.saveCheckboxChecked !== undefined) {
+            externalEvent.saveCheckboxChecked = event.saveCheckboxChecked;
+        }
         return externalEvent;
     };
     EventBroadcaster.prototype.registerMiddleware = function (middleware) {

package/dist/v1/stripe/shared.d.ts

@@ -22,8 +22,9 @@ export declare function initStripe(context: StripeContext, theme?: PaymentWidget
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
+ * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
  */
-export declare function createPaymentElementOptions(defaultValues?: DefaultValues, theme?: PaymentWidgetTheme, hideNameField?: boolean, businessName?: string): StripePaymentElementOptions;
+export declare function createPaymentElementOptions(defaultValues?: DefaultValues, theme?: PaymentWidgetTheme, hideNameField?: boolean, businessName?: string, showCardMandate?: boolean): StripePaymentElementOptions;
 /**
  * Create address element options
  */
@@ -41,6 +42,8 @@ export declare function createPaymentElement(elements: StripeElements, options:
  * When addressElement is provided (payment form): emits "Complete" only when BOTH elements are complete,
  * and "Incomplete" when at least one element becomes incomplete.
  * When addressElement is not provided (MOTO form): emits based on payment element completion only.
+ * Also includes the current save-payment-method checkbox state (when present) on every Change event,
+ * and emits a Change event when that checkbox state changes.
  */
 export declare function setupChangeEventHandler(paymentElement: StripePaymentElement, eventBroadcaster: EventBroadcaster, addressElement?: StripeAddressElement | null): void;
 /**

package/dist/v1/stripe/shared.js

@@ -81,9 +81,11 @@ export function initStripe(context, theme) {
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
+ * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
  */
-export function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName) {
+export function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, showCardMandate) {
     if (hideNameField === void 0) { hideNameField = false; }
+    if (showCardMandate === void 0) { showCardMandate = false; }
     var options = __assign(__assign(__assign({ wallets: {
             applePay: 'never',
             googlePay: 'never',
@@ -94,9 +96,7 @@ export function createPaymentElementOptions(defaultValues, theme, hideNameField,
                 name: 'never', // prevent duplicate Name field on the form when using ACH (only when address element is present)
             },
         },
-    })), { terms: {
-            usBankAccount: 'never', // Hide Stripe's default T&Cs (shown for ACH payments)
-        } }), (businessName && { business: { name: businessName } }));
+    })), { terms: __assign({ usBankAccount: 'never' }, (showCardMandate && businessName && { card: 'always' })) }), (businessName && { business: { name: businessName } }));
     if (defaultValues) {
         options.defaultValues = {
             billingDetails: {
@@ -210,17 +210,22 @@ export function createPaymentElement(elements, options, mountElement, eventBroad
  * When addressElement is provided (payment form): emits "Complete" only when BOTH elements are complete,
  * and "Incomplete" when at least one element becomes incomplete.
  * When addressElement is not provided (MOTO form): emits based on payment element completion only.
+ * Also includes the current save-payment-method checkbox state (when present) on every Change event,
+ * and emits a Change event when that checkbox state changes.
  */
 export function setupChangeEventHandler(paymentElement, eventBroadcaster, addressElement) {
     var paymentComplete = false;
     var addressComplete = !addressElement; // If no address element, consider it complete
     var previousComplete = null;
     var previousMethodType;
+    var previousSaveCheckboxState; // Track save checkbox state
     var emitChangeEvent = function () {
         var complete = paymentComplete && addressComplete;
         previousComplete = complete;
-        eventBroadcaster.publish(__assign({ status: 'Change', code: complete ? 'Complete' : 'Incomplete' }, (previousMethodType && {
+        eventBroadcaster.publish(__assign(__assign({ status: 'Change', code: complete ? 'Complete' : 'Incomplete' }, (previousMethodType && {
             paymentMethodType: previousMethodType,
+        })), (previousSaveCheckboxState !== undefined && {
+            saveCheckboxChecked: previousSaveCheckboxState,
         })));
     };
     paymentElement.on('change', function (event) {
@@ -232,7 +237,15 @@ export function setupChangeEventHandler(paymentElement, eventBroadcaster, addres
         if (methodType !== undefined) {
             previousMethodType = methodType;
         }
-        if (completenessChanged || methodTypeChanged) {
+        // Check for save checkbox state from Stripe's value object
+        // The value object may contain a `savePaymentMethod` property
+        var saveCheckboxChanged = false;
+        if (event.value && typeof event.value === 'object' && 'savePaymentMethod' in event.value) {
+            var saveCheckboxState = event.value.savePaymentMethod;
+            saveCheckboxChanged = previousSaveCheckboxState !== saveCheckboxState;
+            previousSaveCheckboxState = saveCheckboxState;
+        }
+        if (completenessChanged || methodTypeChanged || saveCheckboxChanged) {
             emitChangeEvent();
         }
     });

package/dist/v1/stripe/widgets/payment.js

@@ -40,7 +40,7 @@ import { initStripe, createPaymentElementOptions, createAddressElementOptions, c
  */
 export function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, addressOptions, _b, addressElement, addressContainer, paymentOptions, _c, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, addressOptions, _b, addressElement, addressContainer, productMetadata, isPartnerProduct, showCardMandate, paymentOptions, _c, paymentElement, paymentContainer, customTermsContainer;
         return __generator(this, function (_d) {
             switch (_d.label) {
                 case 0: return [4 /*yield*/, initStripe(session.context, theme)];
@@ -48,7 +48,13 @@ export function mountPaymentWidget(mountElement, session, eventBroadcaster, defa
                     _a = _d.sent(), stripe = _a.stripe, elements = _a.elements;
                     addressOptions = createAddressElementOptions(defaultValues);
                     _b = createAddressElement(elements, addressOptions, mountElement), addressElement = _b.element, addressContainer = _b.container;
-                    paymentOptions = createPaymentElementOptions(defaultValues, theme, true, session.context.businessName);
+                    productMetadata = session.metadata.product;
+                    isPartnerProduct = typeof productMetadata === 'string' &&
+                        productMetadata.startsWith('partner:');
+                    showCardMandate = session.metadata.sessionType === 'payment-with-save' &&
+                        !!session.context.businessName &&
+                        isPartnerProduct;
+                    paymentOptions = createPaymentElementOptions(defaultValues, theme, true, session.context.businessName, showCardMandate);
                     _c = createPaymentElement(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _c.element, paymentContainer = _c.container, customTermsContainer = _c.customTermsContainer;
                     // Setup change handler that emits Complete only when both elements are complete
                     setupChangeEventHandler(paymentElement, eventBroadcaster, addressElement);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.5.0";
+export declare const SDK_VERSION = "1.6.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // This file is auto-generated during the build process
 // DO NOT EDIT MANUALLY - Version is extracted from package.json
-export var SDK_VERSION = '1.5.0';
+export var SDK_VERSION = '1.6.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed/online-payments-sdk",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Process online-payments with Lightspeed Payments",
   "author": "Lightspeed Commerce Inc.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -32,18 +32,18 @@
     "@eslint/js": "^9.33.0",
     "@types/jest": "^30.0.0",
     "gts": "^6.0.2",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "jest-junit": "^16.0.0",
-    "rollup": "^4.53.3",
-    "ts-jest": "^29.4.5",
+    "rollup": "^4.62.2",
+    "ts-jest": "^29.4.11",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.47.0"
+    "typescript-eslint": "^8.63.0"
   },
   "dependencies": {
-    "@adyen/adyen-web": "^6.25.1",
-    "@datadog/browser-logs": "^6.24.1",
+    "@adyen/adyen-web": "^6.40.1",
+    "@datadog/browser-logs": "^6.33.0",
     "@stripe/stripe-js": "^7.9.0"
   }
 }