@lightspeed/online-payments-sdk 1.6.0 → 1.6.2

package/README.md

@@ -1 +1,101 @@
-# 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`
+- Sandbox releases (testing unreleased builds in a real app): `packages/lsp-online-payments-sdk/docs/sandbox-releases.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.
+
+### Sandbox releases
+
+To test unreleased SDK changes inside a real app without touching the production
+package on public npm, publish a **sandbox** build to GitHub Packages: push a
+`sandbox/*` branch and approve the `hold_sandbox` step in CircleCI. Consuming an
+app requires no `import` changes — just an `.npmrc` scope + a `package.json`
+alias. See `docs/sandbox-releases.md` for the full publish and consume steps.

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: {

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

@@ -25,7 +25,7 @@ exports.ACH_TERMS_TEXT = {
      */
     EXPANDED_TERMS_PARAGRAPHS: [
         'By providing your bank account details and confirming this payment, you authorize the merchant to debit your account for the amount shown.',
-        'If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it.',
+        'If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it. For returns due to insufficient funds or uncollected funds, the merchant may retry the debit up to two additional times. If you save your bank account, you authorize Stripe and Lightspeed to access your account status and balance information, where available, before submitting current or future ACH payments. A balance check does not guarantee that an ACH payment will be completed.',
         'You also authorize the merchant to credit your account as necessary to correct any erroneous debits.',
         'You may revoke authorization at any time by contacting the merchant, allowing up to thirty (30) days for processing.\nYou confirm that you are an authorized signer on the account and that sufficient funds will be available for each payment.\nACH payments may take up to five (5) business days to complete, and you may be responsible for fees if a payment is returned.',
     ],

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.6.0';
+exports.SDK_VERSION = '1.6.2';

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
  */

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: {

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

@@ -20,7 +20,7 @@ export declare const ACH_TERMS_TEXT: {
      * Each entry is a separate paragraph rendered when the user expands
      * "these terms". Kept as plain text — HTML structure is built in code.
      */
-    readonly EXPANDED_TERMS_PARAGRAPHS: readonly ["By providing your bank account details and confirming this payment, you authorize the merchant to debit your account for the amount shown.", "If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it.", "You also authorize the merchant to credit your account as necessary to correct any erroneous debits.", "You may revoke authorization at any time by contacting the merchant, allowing up to thirty (30) days for processing.\nYou confirm that you are an authorized signer on the account and that sufficient funds will be available for each payment.\nACH payments may take up to five (5) business days to complete, and you may be responsible for fees if a payment is returned."];
+    readonly EXPANDED_TERMS_PARAGRAPHS: readonly ["By providing your bank account details and confirming this payment, you authorize the merchant to debit your account for the amount shown.", "If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it. For returns due to insufficient funds or uncollected funds, the merchant may retry the debit up to two additional times. If you save your bank account, you authorize Stripe and Lightspeed to access your account status and balance information, where available, before submitting current or future ACH payments. A balance check does not guarantee that an ACH payment will be completed.", "You also authorize the merchant to credit your account as necessary to correct any erroneous debits.", "You may revoke authorization at any time by contacting the merchant, allowing up to thirty (30) days for processing.\nYou confirm that you are an authorized signer on the account and that sufficient funds will be available for each payment.\nACH payments may take up to five (5) business days to complete, and you may be responsible for fees if a payment is returned."];
     /**
      * Final paragraph containing a link to the Privacy Policy.
      * The link text and URL are defined separately so translators only

package/dist/v1/stripe/terms.js

@@ -22,7 +22,7 @@ export var ACH_TERMS_TEXT = {
      */
     EXPANDED_TERMS_PARAGRAPHS: [
         'By providing your bank account details and confirming this payment, you authorize the merchant to debit your account for the amount shown.',
-        'If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it.',
+        'If you choose to save your bank account for future payments, this authorization will also apply to any amounts now or hereafter due and payable, including amounts previously invoiced, accrued, outstanding, or otherwise payable, in addition to current, and future payment obligations owed for products or services provided by the merchant, until you cancel it. For returns due to insufficient funds or uncollected funds, the merchant may retry the debit up to two additional times. If you save your bank account, you authorize Stripe and Lightspeed to access your account status and balance information, where available, before submitting current or future ACH payments. A balance check does not guarantee that an ACH payment will be completed.',
         'You also authorize the merchant to credit your account as necessary to correct any erroneous debits.',
         'You may revoke authorization at any time by contacting the merchant, allowing up to thirty (30) days for processing.\nYou confirm that you are an authorized signer on the account and that sufficient funds will be available for each payment.\nACH payments may take up to five (5) business days to complete, and you may be responsible for fees if a payment is returned.',
     ],

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.6.0";
+export declare const SDK_VERSION = "1.6.2";

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.6.0';
+export var SDK_VERSION = '1.6.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed/online-payments-sdk",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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"
   }
 }