@lightspeed/online-payments-sdk 1.7.2 → 1.7.3

package/README.md

@@ -1,6 +1,11 @@
 # Lightspeed Online Payments SDK
 
-`@lightspeed/online-payments-sdk` is a browser SDK for mounting Lightspeed Payments widgets (Stripe and Adyen) in web applications.
+`@lightspeed/online-payments-sdk` is a browser SDK for displaying Lightspeed Payments widgets in your web application.
+
+This is intended for partners who wish to add payments functionality to an integration with a Lightspeed product.
+
+For onboarding questions, account configuration, or production enablement: contact your Lightspeed
+representative.
 
 ## Installation
 
@@ -8,94 +13,123 @@
 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')!,
-});
+## Requirements
 
-controller.unmount();
-```
+- A browser environment with `window` and `document`
+- A payment session obtained from your Lightspeed Payments integration
+- An HTML element where the payment widget can be mounted
 
-## Compatibility
-
-- TypeScript/JavaScript
-- Browser runtime (requires `window`)
-
-## Theming
+## Quick start
 
-The SDK supports custom themes. If no theme is specified, Stripe defaults are used.
+Add a mount element to your page:
 
-### Available themes
+```html
+<div id="payment-widget"></div>
+```
 
-- default (no `theme` value)
-- `invoicing`
-- `dark`
+Mount the widget with the payment session from your integration:
 
 ```ts
 import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
 
-await LightspeedPayments.v1.mountPaymentWidget(paymentSession, {
-  mountPoint: document.getElementById('payment-widget')!,
-  theme: 'dark',
+const mountPoint = document.getElementById('payment-widget');
+
+if (!mountPoint) {
+  throw new Error('Payment widget mount point was not found');
+}
+
+const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
 });
 ```
 
-### Container styling
+Keep the returned controller to submit the widget or remove it when the containing page or component is no longer needed.
+
+## Configuration
 
-For dark mode, the SDK styles the mount element you pass in `mountPoint`. If you style a parent wrapper, use `THEME_COLORS`.
+`mountPaymentWidget(session, configuration)` accepts a payment session and the following configuration:
+
+| Option          | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `mountPoint`    | Required `HTMLElement` where the SDK renders the payment widget. |
+| `defaultValues` | Optional initial address values: `country` and `postalCode`.     |
+| `listeners`     | Optional callbacks for widget lifecycle and payment events.      |
+| `theme`         | Optional visual theme: `dark`.                                   |
 
 ```ts
-import {THEME_COLORS} from '@lightspeed/online-payments-sdk';
+const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
+  defaultValues: {
+    country: 'CA',
+    postalCode: 'H1H1H1',
+  },
+  listeners: {
+    onReady: () => {
+      // The widget is ready for payer input.
+    },
+    onChange: event => {
+      submitButton.disabled = event.code !== 'Complete';
+    },
+    onSucceeded: () => {
+      // Continue after a successful payment or payment-method save.
+    },
+    onDeclined: event => {
+      // Show a decline message appropriate for event.code.
+    },
+    onError: event => {
+      // Handle a widget or processing error.
+    },
+  },
+});
 ```
 
-## Documentation
+### Events
 
-- 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`
+Listeners receive an event with a `status` and `code`. Available listener names are `onReady`, `onChange`, `onSucceeded`, `onPending`, `onDeclined`, and `onError`.
 
-## Development
+| Status      | Codes                                                                                                          |
+| ----------- | -------------------------------------------------------------------------------------------------------------- |
+| `Ready`     | `Ready`                                                                                                        |
+| `Change`    | `Complete`, `Incomplete`                                                                                       |
+| `Succeeded` | `Authorized`                                                                                                   |
+| `Pending`   | `Processing`                                                                                                   |
+| `Declined`  | `CardValidation`, `Generic`, `PaymentMethodNotSupported`                                                       |
+| `Error`     | `Unexpected`, `InvalidSession`, `InvalidSessionPayload`, `UnsupportedLocation`, `Processing`, `FormValidation` |
 
-Run SDK checks (same order as CI):
+## Submit and unmount
 
-```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
-```
+Call `submit()` in response to your application's payment action. Call `unmount()` before removing or replacing the mount element.
 
-Build package:
+```ts
+submitButton.addEventListener('click', async () => {
+  await controller.submit();
+});
 
-```sh
-npm run build --workspace @lightspeed/online-payments-sdk
+// For example, during page or component cleanup.
+controller.unmount();
 ```
 
-Inspect publish contents:
+## Theming
 
-```sh
-npm pack --dry-run
-```
+Use `theme` to select a widget appearance:
 
-## Publishing and release flow
+- Omit `theme` to use the default appearance.
+- `dark` uses a dark appearance and styles the mount element with a dark background.
 
-Publishing is handled by CircleCI (not manual local publish).
+Custom themes can be used with support from the Lightspeed Payments team.
 
-- 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`.
+```ts
+await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
+  theme: 'dark',
+});
+```
 
-In practice: bump `version` in `packages/lsp-online-payments-sdk/package.json`, merge to `main`, then approve the release hold in CircleCI.
+For a wrapper around a widget using the `dark` theme, use `THEME_COLORS` to match the SDK's dark container colors:
 
-### Sandbox releases
+```ts
+import {THEME_COLORS} from '@lightspeed/online-payments-sdk';
 
-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.
+wrapper.style.backgroundColor = THEME_COLORS.DARK.BACKGROUND;
+wrapper.style.color = THEME_COLORS.DARK.TEXT;
+```

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.7.2';
+exports.SDK_VERSION = '1.7.3';

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.7.2";
+export declare const SDK_VERSION = "1.7.3";

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed/online-payments-sdk",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Process online-payments with Lightspeed Payments",
   "author": "Lightspeed Commerce Inc.",
   "license": "SEE LICENSE IN LICENSE.md",