@mxenabled/web-connect-widget-sdk 0.0.4 → 0.0.5

package/API.md

@@ -0,0 +1,172 @@
+# API Documentation
+
+## ConnectWidget factory function
+
+The `ConnectWidget` factory function returns an object that allows you to mount and unmount an MX connect widget into a web application. It provides easy access to MX connect widget events.
+
+### Props
+
+#### `containerSelector` (required)
+
+**Type:** `string`
+
+A CSS selector used to find the DOM element where the widget iframe will be mounted when `mount` is called.
+
+**Example:**
+
+```typescript
+ConnectWidget({
+  containerSelector: '#widget-container',
+  onEvent,
+  url: 'https://.....',
+});
+```
+
+#### `url` (required)
+
+**Type:** `string`
+
+The generated connect widget url. This URL will be loaded in the underlying iframe.
+
+#### `onEvent` (required)
+
+**Type:** `(event: Event) => void`
+
+A callback function that handles post message events emitted by the iframed connect widget. This function is called whenever an event occurs within the widget.
+
+| Parameter | Type    | Description                            |
+| --------- | ------- | -------------------------------------- |
+| `event`   | `Event` | The event object emitted by the widget |
+
+**Event Object Structure:**
+
+```typescript
+type Event = {
+  type: string; // Event type identifier (e.g., "mx/connect/oauthRequested")
+  metadata: Record<string, unknown>; // Event-specific data and context
+};
+```
+
+**Event Types:**
+
+Event types can be found within the MX docs [here](https://docs.mx.com/connect/guides/handling-events/).
+
+**Example:**
+
+```typescript
+const handleEvent = (event: Event) => {
+  switch (event.type) {
+    case 'mx/connect/memberConnected':
+      console.log('OAuth requested with URL:', event.metadata);
+      break;
+
+    default:
+      console.log('Received event:', event.type, event.metadata);
+  }
+};
+
+const widget = ConnectWidget({
+  containerSelector: '#widget-container',
+  onEvent,
+  url: 'https://.....',
+});
+```
+
+#### `iframeProps` (optional)
+
+Additional props to pass to the underlying iframe. This allows customization of iframe behavior and styling. Any prop that can be passed to an iframe element can be passed here.
+
+**Default:** iframe will be styled with `{ height: "100%", width: "100%" }` if no `iframeProps.style` is provided.
+
+**Example:**
+
+```typescript
+ConnectWidget({
+  containerSelector: '#widget-container',
+  iframeProps: {
+    id: 'exampleId',
+    style: {
+      border: 'solid 1px black',
+    },
+    // other iframe props...
+  },
+  onEvent,
+  url: 'https://.....',
+});
+```
+
+### Methods
+
+#### `mount`
+
+**Type:** `() => void`
+
+Mounts the connect widget iframe into the element matched by `containerSelector` and starts listening for widget events via `window.postMessage`.
+
+Throws an error if the container element cannot be found.
+
+**Example:**
+
+```typescript
+const widget = ConnectWidget({
+  containerSelector: '#widget-container',
+  onEvent,
+  url: 'https://.....',
+});
+
+widget.mount();
+```
+
+#### `unmount`
+
+**Type:** `() => void`
+
+Removes the widget iframe from the DOM and unregisters the message event listener added by `mount`.
+
+**Example:**
+
+```typescript
+const widget = ConnectWidget({
+  containerSelector: '#widget-container',
+  onEvent,
+  url: 'https://.....',
+});
+
+widget.mount();
+
+// Later, when done with the widget:
+widget.unmount();
+```
+
+### Usage Example
+
+```typescript
+import { ConnectWidget, type Event } from '@mxenabled/web-connect-widget-sdk';
+
+const handleEvent = (event: Event) => {
+  switch (event.type) {
+    case 'mx/connect/memberConnected':
+      console.log('OAuth requested with URL:', event.metadata);
+      break;
+
+    default:
+      console.log('Received event:', event.type, event.metadata);
+  }
+};
+
+const widget = ConnectWidget({
+  containerSelector: '#widget-container',
+  iframeProps: {
+    style: {
+      border: 'solid 1px black',
+    },
+  },
+  onEvent,
+  url: 'https://.....',
+});
+
+widget.mount();
+
+// Later, when done with the widget:
+widget.unmount();
+```

package/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+## What is in this repo
+
+1. An sdk that exports a `ConnectWidget` that mounts/unmounts a connect widget iframe to the dom.
+1. An example app built with React that uses the `ConnectWidget`
+
+## Setting up a local development environment
+
+Read the [Local Development](./LOCAL_DEVELOPMENT.md) guide in order to get the example app running.

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@mxenabled/web-connect-widget-sdk",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "MX Connect Web Widget SDK",
   "files": [
-    "dist"
+    "dist",
+    "API.md",
+    "CONTRIBUTING.md"
   ],
   "main": "dist/index.js",
   "type": "module",