@mxenabled/web-connect-widget-sdk 0.0.3 → 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/README.md

@@ -0,0 +1,25 @@
+# MX Web Connect Widget SDK
+
+## Purpose
+
+The purpose of this project is to be able to easily integrate the MX connect widget into a web app.
+
+## Implementation guide
+
+The implementation guide lives in the MX docs [here](Add something here when it exists).
+
+## How it works
+
+This package mounts an connect widget iframe to the DOM, listens for post messages, and provides callbacks for handling MX events.
+
+## API Documentation
+
+The api documentation is [here](./API.md)
+
+## Contributing
+
+Read the [contributing guide](./CONTRIBUTING.md) to learn about the development process.
+
+## License
+
+This project is lincensed under the terms of the [MIT license](LICENSE).

package/dist/ConnectWidget.d.ts

@@ -2,7 +2,7 @@ import { Event } from './consts';
 interface ConnectWidgetProps {
     containerSelector: string;
     iframeProps?: Record<string, unknown>;
-    onEvent?: (event: Event) => void;
+    onEvent: (event: Event) => void;
     url: string;
 }
 export declare const ConnectWidget: ({ containerSelector, iframeProps, onEvent, url, }: ConnectWidgetProps) => {

package/dist/index.js

@@ -4,11 +4,7 @@ const g = ({
   onEvent: a,
   url: o
 }) => {
-  const t = document.createElement("iframe"), { style: c, ...d } = i || {}, m = {
-    height: "100%",
-    width: "100%",
-    ...c ?? {}
-  };
+  const t = document.createElement("iframe"), { style: c, ...d } = i || {}, m = c || { height: "100%", width: "100%" };
   Object.assign(t.style, m);
   for (const [e, n] of Object.entries(d))
     e.startsWith("data-") ? t.setAttribute(e, String(n)) : Object.assign(t, { [e]: n });
@@ -17,7 +13,7 @@ const g = ({
     if (e.origin !== new URL(o).origin)
       return;
     const { data: n } = e, { metadata: f, type: u } = n;
-    a?.({
+    a({
       metadata: f,
       type: u
     });

package/dist/index.umd.cjs

@@ -1 +1 @@
-(function(t,o){typeof exports=="object"&&typeof module<"u"?o(exports):typeof define=="function"&&define.amd?define(["exports"],o):(t=typeof globalThis<"u"?globalThis:t||self,o(t.index={}))})(this,(function(t){"use strict";const o=({containerSelector:s,iframeProps:a,onEvent:c,url:r})=>{const n=document.createElement("iframe"),{style:f,...u}=a||{},m={height:"100%",width:"100%",...f??{}};Object.assign(n.style,m);for(const[e,i]of Object.entries(u))e.startsWith("data-")?n.setAttribute(e,String(i)):Object.assign(n,{[e]:i});n.src=r;const d=e=>{if(e.origin!==new URL(r).origin)return;const{data:i}=e,{metadata:l,type:g}=i;c?.({metadata:l,type:g})};return{mount:()=>{const e=document.querySelector(s);if(!e)throw new Error(`Container with selector "${s}" not found.`);e.appendChild(n),window.addEventListener("message",d)},unmount:()=>{n.remove(),window.removeEventListener("message",d)}}};t.ConnectWidget=o,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})}));
+(function(t,o){typeof exports=="object"&&typeof module<"u"?o(exports):typeof define=="function"&&define.amd?define(["exports"],o):(t=typeof globalThis<"u"?globalThis:t||self,o(t.index={}))})(this,(function(t){"use strict";const o=({containerSelector:s,iframeProps:a,onEvent:c,url:r})=>{const n=document.createElement("iframe"),{style:f,...u}=a||{},m=f||{height:"100%",width:"100%"};Object.assign(n.style,m);for(const[e,i]of Object.entries(u))e.startsWith("data-")?n.setAttribute(e,String(i)):Object.assign(n,{[e]:i});n.src=r;const d=e=>{if(e.origin!==new URL(r).origin)return;const{data:i}=e,{metadata:l,type:g}=i;c({metadata:l,type:g})};return{mount:()=>{const e=document.querySelector(s);if(!e)throw new Error(`Container with selector "${s}" not found.`);e.appendChild(n),window.addEventListener("message",d)},unmount:()=>{n.remove(),window.removeEventListener("message",d)}}};t.ConnectWidget=o,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})}));

package/package.json

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