xendit-components-web 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Unreleased
+
+No unreleased changes.
+
+# 0.0.9
+
+Missing `.d.ts` file is restored.
+
+# 0.0.8
+
+### Notable
+
+- Channels other than `"CARDS"` are disabled for the initial release.
+- `sessionClientKey` is renamed to `componentsSdkKey`
+
+### New features
+
+Support searching channels by channel code to `getActiveChannels`:
+
+```typescript
+const cardsComponent = components.getActiveChannels({ filter: "CARDS" })[0];
+```
+
+The layout of the default action container component and the mock iframe action have been improved.
+
+### Bug fixes
+
+- Prevent channel picker from sometimes collapsing the cards group while typing a card number
+- Fix missing types in the `.d.ts` file
+- In mock mode, mock channels now use an appropriate action type based on their channel type
+- The module can now be imported in Node.js. It asserts it's running on a browser in the `XenditComponents` constructor instead.
+
+# 0.0.7
+
+Initial release.
+
+This release contains credit card payment and tokenization flows.
+
+```typescript
+const components: XenditComponents = new XenditComponents({
+  componentsSdkKey: componentsSdkKeyFromYourServer,
+});
+
+const cardsChannel = components.getActiveChannels({ filter: "CARDS" })[0];
+const channelPicker: HTMLElement =
+  components.createChannelComponent(cardsChannel);
+
+myCheckoutPage.replaceChildren(channelPicker);
+
+mySubmitButton.addEventListener("click", () => {
+  components.submit();
+});
+
+components.addEventListener("session-complete", () => {
+  alert("Payment Success");
+});
+components.addEventListener("session-expired-or-canceled", () => {
+  alert("Payment cancelled or expired");
+});
+```

package/README.md

@@ -15,10 +15,10 @@ npm install xendit-components-web --save
 Or load it directly from our CDN:
 
 ```html
-<script src="https://assets.xendit.co/components/VERSION_NUMBER_HERE/index.umd.js"></script>
+<script src="https://assets.xendit.co/components/0.0.9/index.umd.js"></script>
 ```
 
-Our npm package includes TypeScript types. If you're using the CDN, download type declarations from `https://assets.xendit.co/components/VERSION_NUMBER_HERE/index.d.ts`
+Our npm package includes TypeScript types. If you're using the CDN, download type declarations from `https://assets.xendit.co/components/0.0.9/index.d.ts`
 
 ## Sessions
 
@@ -37,13 +37,13 @@ Two types of sessions are available:
 First, initialize the SDK either with either:
 
 - `XenditComponentsTest` for frontend development or unit tests
-- `XenditComponents`, for production, which requires a `sessionClientKey`, which comes from the Session object, which you need to create on your server. Make an endpoint that creates a session for the user's current transaction, return the `components_sdk_key` to the client, and pass it into the constructor.
+- `XenditComponents`, for production, which requires a `componentsSdkKey`. That key comes from the session object you create on your server. Make an endpoint that creates a session for the user's current transaction, return the `components_sdk_key` to the client, and pass it into the constructor.
 
 ```typescript
 // For frontend development, use XenditComponentsTest
 const components: XenditComponents = new XenditComponentsTest({});
 // For production or e2e testing, use XenditComponents, passing in the components_sdk_key from the Session object
-// const components: XenditComponents = new XenditComponents({ sessionClientKey });
+const components: XenditComponents = new XenditComponents({ componentsSdkKey });
 
 // Create a channel picker component
 const channelPicker: HTMLElement = components.createChannelPickerComponent();
@@ -71,7 +71,7 @@ components.addEventListener("session-expired-or-canceled", () => {
 
 The constructor.
 
-For production and e2e testing, you need to pass the `sessionClientKey`, which you can get when you create a Session on your server.
+For production and e2e testing, you need to pass the `componentsSdkKey`, which you can get when you create a Session on your server.
 
 For development and unit testing, use `XenditComponentsTest`, which uses mock data and doesn't connect to Xendit servers.
 
@@ -110,9 +110,7 @@ your own channel selection UI. Each channel has a `uiGroup` property which match
 ### `createChannelComponent`
 
 ```typescript
-const channel = components
-  .getActiveChannels()
-  .find((channel) => channel.channelCode === "CARDS");
+const channel = components.getActiveChannels({ filter: "CARDS" })[0];
 if (channel) {
   const htmlElement = components.createChannelPickerComponent(channel);
   myContainer.replaceChildren(htmlElement);
@@ -220,9 +218,7 @@ The current channel:
 ### `setCurrentChannel`
 
 ```typescript
-const channel = components
-  .getActiveChannels()
-  .find((channel) => channel.channelCode === "CARDS");
+const channel = components.getActiveChannels({ filter: "CARDS" })[0];
 if (channel) {
   components.setCurrentChannel(channel);
 }
@@ -283,10 +279,8 @@ The following variables are available:
 | --xendit-color-text-placeholder | Placeholder color |
 | --xendit-color-disabled | Background color of disabled elements |
 | --xendit-color-danger | Border color of elements with validation errors and text color of validation errors |
-| --xendit-color-border | TODO: remove this |
-| --xendit-color-border-subtle | TODO: rename this |
-| --xendit-color-border-default | TODO: rename this |
-| --xendit-color-background | Background color of elements |
+| --xendit-color-border | Border color used on accordions, input fields, and logos |
+| --xendit-color-background | Background color of input fields |
 | --xendit-focus-shadow | Box-shadow applied to elements with focus |
 | --xendit-animation-duration | Duration of animations (affects the channel picker accordion) |
 | --xendit-animation-ease | Ease function of animations |
@@ -297,13 +291,25 @@ The following variables are available:
 
 Some form fields (credit card inputs) are implemented inside iframes to protect the user's information.
 
-Regular CSS doesn't apply inside iframes. The SDK instead provides overrides in the constructor which
-it applies to the iframe fields.
+You can't override the CSS inside the iframe fields. Instead, you can pass some limited styles to the constructor
+which we'll pass along to the iframes.
 
 ```typescript
 const sdk = new XenditComponents({
-  appearance: {
-    // TODO
+  iframeFieldAppearance: {
+    inputStyles: {
+      // apply styles to inputs within iframe fields
+      color: "#000",
+    },
+    placeholderStyles: {
+      // apply styles to input placeholders in iframe fields
+      color: "#ccc",
+    },
+    fontFace: {
+      // insert a @font-face rule inside iframe fields
+      source: "url(https://example.com/my-font-file) format(woff2)",
+      descriptors: { display: "swap" },
+    },
   },
 });
 ```

package/README.md.bak

@@ -0,0 +1,315 @@
+# xendit-components-web
+
+Xendit Components allows you to accept payments directly on your website using the Xendit Sessions API.
+
+This SDK's role is to take a Session (created on your server using the Xendit Sessions API) and render a payment UI, and allow you to customize the UI to match your site's look & feel.
+
+## Installation
+
+Install using npm:
+
+```sh
+npm install xendit-components-web --save
+```
+
+Or load it directly from our CDN:
+
+```html
+<script src="https://assets.xendit.co/components/0.0.9/index.umd.js"></script>
+```
+
+Our npm package includes TypeScript types. If you're using the CDN, download type declarations from `https://assets.xendit.co/components/0.0.9/index.d.ts`
+
+## Sessions
+
+The Xendit Session API is an abstraction over the Xendit Payments API, representing one transaction (or tokenization). Using one session, a user can make any number
+of attempts to pay, one of which can be successful. A successful payment completes the session.
+
+Sessions also abstract away any differences between channels, allowing you to write once, and accept payments from any channel Xendit supports.
+
+Two types of sessions are available:
+
+- `PAY` sessions collect a payment and optionally save a payment token for later use
+- `SAVE` sessions save a payment token
+
+## Quick Start
+
+First, initialize the SDK either with either:
+
+- `XenditComponentsTest` for frontend development or unit tests
+- `XenditComponents`, for production, which requires a `componentsSdkKey`. That key comes from the session object you create on your server. Make an endpoint that creates a session for the user's current transaction, return the `components_sdk_key` to the client, and pass it into the constructor.
+
+```typescript
+// For frontend development, use XenditComponentsTest
+const components: XenditComponents = new XenditComponentsTest({});
+// For production or e2e testing, use XenditComponents, passing in the components_sdk_key from the Session object
+const components: XenditComponents = new XenditComponents({ componentsSdkKey });
+
+// Create a channel picker component
+const channelPicker: HTMLElement = components.createChannelPickerComponent();
+
+// Insert the channel picker into your document
+myCheckoutPage.replaceChildren(channelPicker);
+
+// Call submit() when the user clicks your submit button
+mySubmitButton.addEventListener("click", () => {
+  components.submit();
+});
+
+// Listen to the status of the session
+components.addEventListener("session-complete", () => {
+  alert("Payment Success");
+});
+components.addEventListener("session-expired-or-canceled", () => {
+  alert("Payment cancelled or expired");
+});
+```
+
+## Components API
+
+### `XenditComponents` and `XenditComponentsTest`
+
+The constructor.
+
+For production and e2e testing, you need to pass the `componentsSdkKey`, which you can get when you create a Session on your server.
+
+For development and unit testing, use `XenditComponentsTest`, which uses mock data and doesn't connect to Xendit servers.
+
+### `createChannelPickerComponent`
+
+```typescript
+const htmlElement = components.createChannelPickerComponent();
+myContainer.replaceChildren(htmlElement);
+```
+
+Creates a UI for the user to select a payment channel and fill any required information.
+
+This returns a `HTMLElement`, which you need to insert into your document.
+
+This method uses caching, it will always return the same channel picker element.
+Changing the current channel will update the channel picker UI, even if it's unmounted.
+If you don't want this, use `destroyComponent.`
+
+### `getActiveChannels`
+
+```typescript
+const channels = components.getActiveChannels();
+```
+
+Returns the list of channels available in this session.
+
+### `getActiveChannelGroups`
+
+```typescript
+const groups = components.getActiveChannelGroups();
+```
+
+Returns a list of channel groups. This can be used to categorize channels by type, if you want to build
+your own channel selection UI. Each channel has a `uiGroup` property which matches one group's `id` property.
+
+### `createChannelComponent`
+
+```typescript
+const channel = components.getActiveChannels({ filter: "CARDS" })[0];
+if (channel) {
+  const htmlElement = components.createChannelPickerComponent(channel);
+  myContainer.replaceChildren(htmlElement);
+}
+```
+
+Selects a payment channel and creates a UI for the user to fill any required information. You
+need to pass in the channel you want to use, as returned from getActiveChannels.
+
+This returns a `HTMLElement`, which you need to insert into your document.
+
+This method uses caching, it will always return the same element for the same channel, to preserve the
+values the user enters into any form fields. If you don't want that, use `destroyComponent`.
+
+### `createActionContainerComponent`
+
+```typescript
+components.addEventListener("action-begin", () => {
+  const htmlElement = components.createActionContainerComponent();
+  myActionContainer.replaceChildren(htmlElement);
+});
+```
+
+Creates a container into which any additional actions (e.g. 3DS, QR Codes) will be rendered.
+
+This is optional, if you don't create one, the SDK will create a modal with an action container for you.
+You cannot create an action container during an action (i.e. after the `action-begin` event).
+
+This returns a `HTMLElement`, which you need to insert into your document.
+
+This method does not use caching.
+
+### `submit`
+
+```typescript
+function onSubmitButtonClick() {
+  components.submit();
+}
+```
+
+Begins submission for the active payment channel.
+
+Call this from the click event of your submit button.
+
+Submission is only available when the session is active, a channel is made current by creating a channel component, any required information is collected, and
+another submission is not in progress. Use the `submission-ready` and `submission-not-ready` events to know when submission is available.
+
+This calls the [create payment request](https://docs.xendit.co/apidocs/create-payment-request)
+or [create payment token](https://docs.xendit.co/apidocs/create-payment-token) endpoint depending on the session type. You
+may listen to the corresponding webhooks on your server.
+
+### `simulatePayment`
+
+```typescript
+components.simulatePayment();
+```
+
+Calls the [simulate payment](https://docs.xendit.co/apidocs/simulate-payment-test-mode) endpoint.
+
+This is only available in test mode sessions. It also requires the payment channel to be a QR, OTC, or VA channel, and it requires an action
+to be in-progress.
+
+### `abortSubmission`
+
+```typescript
+components.abortSubmission();
+```
+
+Cancels the current submission, if any.
+
+### `destroyComponent`
+
+```typescript
+components.destroyComponent(htmlElement);
+```
+
+Destroys a component, deleting any cached data and removing the element from the document. Manual cleanup is not normally required,
+but is made available if you want it.
+
+### `showValidationErrors`
+
+```typescript
+components.showValidationErrors();
+```
+
+Reveals hidden validation errors in the current channel's form, if any.
+
+Validation errors are normally hidden until the user changes and unfocusses the input.
+
+### `getCurrentChannel`
+
+```typescript
+const channel: XenditChannel = components.getCurrentChannel();
+```
+
+Returns the current channel.
+
+The current channel is the one you or the channel picker component selected by calling `createChannelComponent` or `setCurrentChannel`.
+
+The current channel:
+
+- Will be used for submission when you call `submit()`
+- Is interactive (other channel components are disabled)
+
+### `setCurrentChannel`
+
+```typescript
+const channel = components.getActiveChannels({ filter: "CARDS" })[0];
+if (channel) {
+  components.setCurrentChannel(channel);
+}
+```
+
+Makes the provided channel the current channel.
+
+## Events
+
+### `init`
+
+Notifies you when the session information is loaded. Most SDK functions require the session to be loaded and can only be called after this event.
+
+`createChannelPickerComponent` is available before the init event.
+
+### `session-complete` and `session-expired-or-canceled`
+
+Notifies you when the session is in a terminal state.
+
+`session-complete` means the session was successful, `session-expired-or-canceled` means the session was cancelled or expired.
+
+### `submission-ready` and `submission-not-ready`
+
+Notifies you when the user is ready to submit the payment, meaning a channel is selected and all required information is collected.
+
+`submit` will only work in the ready state, or it will throw. Calling it when there are form validation errors will also reveal those errors
+to the user.
+
+You might want to disable your submit button when not in the ready state.
+
+### `submission-begin` and `submission-end`
+
+Notifies you when a submission is in progress.
+
+You might want to show a pending state UI when in the submission state.
+
+### `action-begin` and `action-end`
+
+Notifies you when an action is in progress.
+
+You might want to create an action container in the action-begin event.
+
+## Appearance
+
+### CSS Variables
+
+The Xendit Components SDK is customizable by overriding its CSS. The SDK inserts its CSS above any other CSS at the time of loading to allow it to be easily overridden.
+
+CSS variables can be overridden to change styles across all components.
+
+The following variables are available:
+| Variable | Description |
+| :- | -: |
+| --xendit-font-family | Font applied to all xendit components |
+| --xendit-color-primary | Accent color |
+| --xendit-color-text | Base text color |
+| --xendit-color-text-secondary | Lighter text color |
+| --xendit-color-text-placeholder | Placeholder color |
+| --xendit-color-disabled | Background color of disabled elements |
+| --xendit-color-danger | Border color of elements with validation errors and text color of validation errors |
+| --xendit-color-border | Border color used on accordions, input fields, and logos |
+| --xendit-color-background | Background color of input fields |
+| --xendit-focus-shadow | Box-shadow applied to elements with focus |
+| --xendit-animation-duration | Duration of animations (affects the channel picker accordion) |
+| --xendit-animation-ease | Ease function of animations |
+| --xendit-radius-1 | Border radius applied to some components |
+| --xendit-z-index-focus | Z-index applied to focused fields |
+
+### Appearance of Iframe fields
+
+Some form fields (credit card inputs) are implemented inside iframes to protect the user's information.
+
+You can't override the CSS inside the iframe fields. Instead, you can pass some limited styles to the constructor
+which we'll pass along to the iframes.
+
+```typescript
+const sdk = new XenditComponents({
+  iframeFieldAppearance: {
+    inputStyles: {
+      // apply styles to inputs within iframe fields
+      color: "#000",
+    },
+    placeholderStyles: {
+      // apply styles to input placeholders in iframe fields
+      color: "#ccc",
+    },
+    fontFace: {
+      // insert a @font-face rule inside iframe fields
+      source: "url(https://example.com/my-font-file) format(woff2)",
+      descriptors: { display: "swap" },
+    },
+  },
+});
+```

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "xendit-components-web",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Xendit frontend payment components SDK",
   "type": "module",
   "author": "Xendit",
-  "license": "UNLICENSED",
+  "license": "MIT",
+  "keywords": [
+    "xendit",
+    "payment",
+    "payments",
+    "payment processing",
+    "credit cards",
+    "checkout",
+    "components"
+  ],
   "files": [
     "./sdk/dist/index.umd.js",
     "./sdk/dist/index.umd.js.map",
     "./sdk/dist/index.esm.js",
     "./sdk/dist/index.esm.js.map",
-    "./sdk/dist/index.d.ts"
+    "./sdk/dist/index.d.ts",
+    "./README.md",
+    "./CHANGELOG.md"
   ],
   "types": "./sdk/dist/index.d.ts",
   "exports": {
@@ -23,19 +34,6 @@
       "default": "./sdk/dist/index.umd.js"
     }
   },
-  "scripts": {
-    "dev": "./build.ts dev",
-    "build": "./build.ts prod",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:run": "vitest run",
-    "test:debug": "vitest run --printConsoleTrace=true --silent=false",
-    "lint": "eslint . --ext .ts,.tsx",
-    "lint:fix": "eslint . --fix --ext .ts,.tsx",
-    "prettier": "prettier . --check",
-    "prettier:fix": "prettier . --check --write",
-    "prepare": "husky"
-  },
   "dependencies": {
     "card-validator": "^10.0.3",
     "classnames": "^2.5.1",
@@ -76,5 +74,16 @@
     "typescript-eslint": "^8.48.0",
     "vitest": "^4.0.14"
   },
-  "packageManager": "pnpm@10.15.1"
-}
+  "scripts": {
+    "dev": "./build.ts dev",
+    "build": "./build.ts prod",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:run": "vitest run",
+    "test:debug": "vitest run --printConsoleTrace=true --silent=false",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --fix --ext .ts,.tsx",
+    "prettier": "prettier . --check",
+    "prettier:fix": "prettier . --check --write"
+  }
+}

package/sdk/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { IframeAppearanceOptions } from '../../shared/types';
-
 /**
  * @public
  * Channel properties for a payment method or payment token.
@@ -11,7 +9,45 @@ export declare interface ChannelProperties {
 /**
  * @public
  */
-declare type ChannelPropertyPrimative = string | number | boolean | undefined;
+export declare type ChannelPropertyPrimative = string | number | boolean | undefined;
+
+/**
+ * @public
+ */
+export declare type IframeAppearanceOptions = {
+    /**
+     * Limited styles applied to iframe inputs.
+     */
+    inputStyles?: {
+        fontFamily?: string;
+        fontSize?: string;
+        fontWeight?: string;
+        lineHeight?: string;
+        letterSpacing?: string;
+        color?: string;
+        backgroundColor?: string;
+    };
+    /**
+     * Limited styles applied to iframe input placeholders.
+     */
+    placeholderStyles?: {
+        color?: string;
+    };
+    /**
+     * Custom font face to load within iframe fields.
+     * If you use this, you don't need to specify fontFamily or fontWeight.
+     */
+    fontFace?: {
+        /**
+         * CSS font-face source descriptor (e.g. `url(...) format(...)`)
+         */
+        source: string;
+        /**
+         * Font face options. Font family and weight are set automatically.
+         */
+        descriptors?: Pick<FontFaceDescriptors, "display" | "style" | "stretch">;
+    };
+};
 
 /**
  * @public
@@ -50,7 +86,7 @@ export declare class XenditComponents extends EventTarget {
      * ```
      * // initialize
      * const components = new XenditComponents({
-     *   sessionClientKey: "your-session-client-key",
+     *   componentsSdkKey: "your-session-client-key",
      * });
      * ```
      */
@@ -118,7 +154,7 @@ export declare class XenditComponents extends EventTarget {
      *
      * @example
      * ```
-     * const cardsChannel = components.getActiveChannels().find(ch => ch.channelCode === "CARDS");
+     * const cardsChannel = components.getActiveChannels({ filter: "CARDS" })[0];
      * const paymentComponent = components.createChannelComponent(cardsChannel);
      * document.querySelector(".payment-container").appendChild(paymentComponent);
      * ```
@@ -331,7 +367,7 @@ export declare class XenditComponents extends EventTarget {
  * Test version of XenditComponents that uses mock data instead of API calls.
  * Use this class for testing and development purposes.
  *
- * The sessionClientKey option is ignored.
+ * The componentsSdkKey option is ignored.
  *
  * @example
  * ```
@@ -341,10 +377,10 @@ export declare class XenditComponents extends EventTarget {
 export declare class XenditComponentsTest extends XenditComponents {
     /**
      * @public
-     * Test SDK ignores sessionClientKey and uses a mock key.
+     * Test SDK ignores componentsSdkKey and uses a mock key.
      */
-    constructor(options: Omit<XenditSdkOptions, "sessionClientKey"> & {
-        sessionClientKey?: string;
+    constructor(options: Omit<XenditSdkOptions, "componentsSdkKey"> & {
+        componentsSdkKey?: string;
     });
 }
 
@@ -403,9 +439,16 @@ export declare type XenditEventMap = {
  * Event fired when the SDK fails in an unrecoverable way.
  */
 export declare class XenditFatalErrorEvent extends Event {
+    /**
+     * A detailed error message for developers. Don't show this to users.
+     */
     message: string;
     static type: "fatal-error";
-    constructor(message: string);
+    constructor(
+    /**
+     * A detailed error message for developers. Don't show this to users.
+     */
+    message: string);
 }
 
 /**
@@ -566,7 +609,7 @@ export declare interface XenditSdkOptions {
      * Your server should retrieve this from the Xendit API and pass it directly to the
      * client without saving or logging it anywhere.
      */
-    sessionClientKey: string;
+    componentsSdkKey: string;
     iframeFieldAppearance?: IframeAppearanceOptions;
 }