# JavaScript API
URL: https://www.quiltt.dev/connector/javascript
Description: Unlock the full potential of Quiltt Connector with our JavaScript API. Learn how to authenticate, open, and set up event callbacks for a seamless user experience. Fully typed with TypeScript support.
Navigation: connector → javascript
Tags: Connector
Content Length: 8k characters

For full control over your experience, Quiltt exposes a JavaScript API to programmatically interact with the Connector.

Info - Documentation:
The JavaScript API is written in TypeScript and is fully typed. The complete TypeScript interface is available [on GitHub](https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/src/api/browser.ts).

## Events

The Connector emits a number of events that can be used to customize the user experience and integrate with your application.

| Event Type      | Value                 | Description                                                   |
| --------------- | --------------------- | ------------------------------------------------------------- |
| **Load**        | `"loaded"`            | The Connector has loaded successfully.                        |
| **Open**        | `"opened"`            | The Connector modal has been opened.                          |
| **ExitSuccess** | `"exited.successful"` | The end-user has successfully completed the flow.             |
| **ExitAbort**   | `"exited.aborted"`    | The end-user closed the Connector before completing the flow. |
| **ExitError**   | `"exited.errored"`    | The end-user experienced an error during the flow.            |

### Event Metadata

All events will return a **Metadata** object with the following data:

| Property       | Required | Type   | Description                                              |
| -------------- | -------- | ------ | -------------------------------------------------------- |
| `connectorId`  | Yes      | string | The ID of the Connector emitting the event.              |
| `profileId`    | No       | string | The ID of the Profile using the Connector.               |
| `connectionId` | No       | string | The ID of the succesfully created or updated Connection. |

### Subscribing to Events

To handle these events in your application, you can attach the appropriate callback functions to your Connector instance. See the [HTML5](/connector/sdk/html) and [React](/connector/sdk/react) guides for more information.

| Callback          | Arguments               | Description                                |
| ----------------- | ----------------------- | ------------------------------------------ |
| **OnEvent**       | `eventType`, `metadata` | Called on all events.                      |
| **OnExit**        | `eventType`, `metadata` | Called on all Exit events.                 |
| **OnOpen**        | `metadata`              | Called on the **Open** event (modal only). |
| **OnLoad**        | `metadata`              | Called on the **Load** event.              |
| **OnExitSuccess** | `metadata`              | Called on the **ExitSuccess** event        |
| **OnExitAbort**   | `metadata`              | Called on the **ExitAbort** event.         |
| **OnExitError**   | `metadata`              | Called on the **ExitError** event.         |

## Usage

The below methods are called on the global Quiltt object.

### `Quiltt.authenticate()`

Authenticate an end-user for the Connector. You can generate a Session token using the Auth API or in the Quiltt Dashboard. See the [Issuing Session Tokens guide](/authentication/issuing-session-tokens) for more information.

```js
Quiltt.authenticate('<SESSION_TOKEN_FROM_SERVER>')
```

Pass the Session token as a string. Passing `null` clears the current session. Passing `undefined` is a no-op, while any other type rejects the call with a descriptive console error.

### `Quiltt.connect()`

This method allows you to initialize a Connector instance by passing in the Connector ID.

You can optionally pass a search term to target an Institution, a URL to re-launch your app (only required for certain mobile or embedded webviews), and callbacks for various events.

```js
// Initialize
const connector = Quiltt.connect('<CONNECTOR_ID>', {
  institution: "Chase", // Optionally add a search term to target an Institution
  appLauncherUrl: "<YOUR_APP_LAUNCHER_URL>", // Optionally add a URL to re-launch your mobile app

  // Optionally add callbacks:
  onLoad: (metadata) => console.log("Loaded ", metadata.connectorId),
  onExitSuccess: (metadata) => console.log({metadata}),
})

// Open Connector modal
connector.open()
```

The Connector ID is required and must be a non-empty string. `connect()` throws a descriptive error if you pass an empty or non-string value.

### `Quiltt.reconnect()`

This methods allows you to repair or reconnect an existing Connection using the Reconnect Flow. See the [Reconnect Flow guide](/connector/reconnect) for more information.

```js
Quiltt.reconnect('<CONNECTOR_ID>', [connectionId: '<CONNECTION_ID>']).open()
```

Similarly to `connect()`, you can pass `appLauncherUrl` to re-launch your mobile app, and callbacks for various events. The Connector ID is required and must be a non-empty string.

## Callbacks

Callbacks can be registered globally on the `Quiltt` object, or on a specific Connector instance.

For example, to register the `onLoad` event globally, bind the callback directly to the `Quiltt` object:

```js
Quiltt.onLoad((metadata) => [console.log('Loaded!', metadata.connectorId)])
```

To register on a specific Connector instance, bind the callback to that instance:

```js
const connector = Quiltt.connect('<CONNECTOR_ID>')
connector.onLoad((metadata) => [console.log('Loaded!', metadata.connectorId)])
```

### `onEvent()`

This method allows you to subscribe to all Connector events. All events will return a `type` **Metadata** object with additional context.

```js
Quiltt.onEvent((type, metadata) => {
  console.log(`Triggered ${type} event`, {metadata})
})
```

### `onOpen()`

This method allows you to pass a callback for the `opened` event. This event will only be emitted when using the Connector modal.

```js
Quiltt.onOpen((metadata) => {
  const [connectorId, profileId, connectionId] = metadata

  console.log('Opened!', [connectorId, profileId, connectionId])
})
```

### `onLoad()`

This method allows you to pass a callback for the `loaded` event.

```js
Quiltt.onLoad((metadata) => {
  const [connectorId, profileId, connectionId] = metadata

  console.log('Loaded!', [connectorId, profileId, connectionId])
})
```

### `onExit()`

This method allows you to pass a callback for all `exited` events.

```js
Quiltt.onExit((type, metadata) => {
  const [connectorId, profileId, connectionId] = metadata

  console.log('Exited!', [type, connectorId, profileId, connectionId])
})
```

### `onExitAbort()`

This method allows you to pass a callback for the `exited.aborted` event. This event will not be emitted when using the Inline Container.

```js
Quiltt.onExitAbort(([connectorId, profileId, connectionId]) => {
  console.log('User aborted!', [connectorId, profileId, connectionId])
})
```

### `onExitError()`

This method allows you to pass a callback for the `exited.errored` event.

```js
Quiltt.onExitError(([connectorId, profileId, connectionId]) => {
  console.log('Error connecting!', [connectorId, profileId, connectionId])
})
```

### `onExitSuccess()`

This method allows you to pass a callback for the `exited.success` event.

```js
Quiltt.onExitSuccess(([connectorId, profileId, connectionId]) => {
  console.log('Connected!', [connectorId, profileId, connectionId])
})
```

## Typescript

The complete list of functions, types and event callbacks is [available on GitHub](https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/src/api/browser.ts).

You can also import the typings from any of the Quiltt Javascript packages. For example, to get typings for the `onExitSuccess` event:

Code Examples:

  ```ts
    import type {ConnectorSDKOnExitSuccessCallback} from '@quiltt/core'

    const onExitSuccessHandler: ConnectorSDKOnExitSuccessCallback = (metadata) => [console.log('fired `onExitSuccess` with Connection:', metadata.connectionId)]
    ```
  ```ts
    import type {ConnectorSDKOnExitSuccessCallback} from '@quiltt/react'

    const onExitSuccessHandler: ConnectorSDKOnExitSuccessCallback = (metadata) => [console.log('fired `onExitSuccess` with Connection:', metadata.connectionId)]
    ```
  ```ts
    import type {ConnectorSDKOnExitSuccessCallback} from '@quiltt/react-native'

    const onExitSuccessHandler: ConnectorSDKOnExitSuccessCallback = (metadata) => [console.log('fired `onExitSuccess` with Connection:', metadata.connectionId)]
    ```