aerosync-web-sdk/README.md

This WEB SDK provides an interface to load Aerosync-UI in javascript or typescript application. Securely link your bank account through your bank’s website. Log in with a fast, secure, and tokenized connection. Your information is never shared or sold.

# ⚠️ NPM Versioning Notice

> For all Aeropay integrations, please use the 1.1.0 Version of our web npm package.
> Any versions 2.0 and later are still in beta and may be unstable. Version 2.0 and above are intended for Aerosync-only integrations. (not using Aeropay to process payments)

# Aerosync Web SDK

This Web SDK provides an interface to load Aerosync-UI in Javascript/typescript application. Securely link your bank account through your bank’s website. Log in with a fast, secure, and tokenized connection. Your information is never shared or sold.

## Installation

```sh
npm i aerosync-web-sdk
```

## Usage

##### 1. Create the necessary HTML elements to trigger and host the AeroSync widget.

##

```html
<!-- Button to launch the AeroSync widget -->
<!-- 'id' is optional but useful for CSS/JS targeting -->
<!-- Vue syntax, replace with onclick="openAerosyncWidget()" if using plain JS -->
<button
  id="openBank"
  class="button"
  role="button"
  @click="openAerosyncWidget()"
>
  Connect Bank
</button>

<!-- This div is where the AeroSync widget iframe will be embedded -->
<!-- Make sure the 'id' here matches the 'elementId' passed during initialization -->
<div id="widget"></div>
```

##### 2. Import and Configure the AeroSync Widget

##

```typescript
/**
 * Step-by-step integration of AeroSync AddBank widget
 */
import type {
  AerosyncWidget,
  WidgetEventSuccessType,
  WidgetEventType,
} from "aerosync-web-sdk";
import { initAeroSyncWidget } from "aerosync-web-sdk";

function openAerosyncWidget() {
  // Initialize the widget with configuration options
  let widgetControls = initAeroSyncWidget({
    elementId: "widget", // 👈 ID of the target div in your HTML
    iframeTitle: "Connect", // 🔒 Used for accessibility
    environment: "production", // 🌍 Set to 'sandbox' for testing, 'production' for live
    token: "xxxx", // 🔑 Your secure AeroSync token
    theme: "light", // 🎨 Choose between 'light' or 'dark' theme

    // 📦 Event listener for all widget events
    onEvent(event: WidgetEventType) {
      console.log("event", event);
    },

    // 🚀 Fires when the widget is fully loaded
    onLoad() {
      console.log("onload");
    },

    // ✅ Called after the user successfully connects a bank and closes the widget
    onSuccess(event: WidgetEventSuccessType) {
      console.log("onSuccess", event);
      // ...
      // Handle success (e.g., update UI, send data to backend, etc.)
    },

    // ❌ Fires when the widget is closed manually by the user
    onClose() {
      console.log("widget closed");
    },

    // ⚠️ Catch and handle widget errors
    onError(event: string) {
      console.log("onError", event);
    },
  });

  // 🧭 Launch the widget
  widgetControls.launch();
}
```

## Readme.io document

For more information check the complete guide here: https://api-aerosync.readme.io/docs/web-npm-sdk

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT

---

This project is licensed under the MIT License.