feat: support for multiple module formats, remove default button (#18)

Author: teallarson

.github/workflows/widget-tests.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 jobs:
-  jest:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -20,11 +20,11 @@ jobs:
           cache: "pnpm"
       - name: Install dependencies
         run: pnpm install
-      - name: Run Jest tests
+      - name: Run tests
         run: pnpm test
       - uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: jest-report
+          name: test-coverage
           path: coverage/
           retention-days: 30

README.md

@@ -4,37 +4,63 @@ An embeddable widget for integrating Airbyte's data synchronization capabilities
 
 ## Features
 
-Easy, lightweight integration for Airbyte Embedded customers to enable user configurations with any web application
+Easy, lightweight integration for Airbyte Embedded customers to enable user configurations within any web application
 
-## Installation
+## Usage
 
-```bash
-# Using pnpm (recommended)
-pnpm install
+You can use the widget in two ways:
 
-# Using npm
-npm install
+### Option 1: Via npm (React/Vue/etc.)
 
-# Using yarn
-yarn install
+Install the package:
+
+```bash
+pnpm add @airbyte-embedded/airbyte-embedded-widget
+# or npm install / yarn add
 ```
 
-## Project Structure
+Use it in your application:
 
-- `/src` - The widget library source code
-- `/demo` - A demo application showcasing the widget usage
+```html
 
-## Building the Library
+<button id="open-airbyte">Open Airbyte</button>
 
-To build the widget library:
+<script type="module">
+  import { EmbeddedWidget } from "@airbyte-embedded/airbyte-embedded-widget";
 
-```bash
-pnpm build
+  const widget = new EmbeddedWidget({
+    token: "<your-token-here>",
+    onEvent: (event) => {
+      console.log("Widget event:", event);
+    },
+  });
+
+  document.getElementById("open-airbyte").addEventListener("click", () => widget.open());
+</script>
 ```
 
-The built files will be in the `dist` directory.
+---
 
-## Usage
+### Option 2: Via `<script>` tag (CDN)
+
+Load the widget via a CDN:
+
+```html
+<button id="open-airbyte">Open Airbyte</button>
+
+<script src="https://cdn.jsdelivr.net/npm/@airbyte-embedded/airbyte-embedded-widget"></script>
+<script>
+  const widget = new AirbyteEmbeddedWidget({
+    token: "<your-token-here>",
+    onEvent: (event) => {
+      console.log("Widget event:", event);
+    },
+  });
+
+  document.getElementById("open-airbyte").addEventListener("click", () => widget.open());
+</script>
+
+---
 
 ### Authentication
 
@@ -50,51 +76,55 @@ curl --location '$AIRBYTE_BASE_URL/api/public/v1/embedded/widget' \
 }'
 ```
 
-`AIRBYTE_BASE_URL`: where your Airbyte instance is deployed
-`CUSTOMER_WORKSPACE_ID`: the workspace you have associated with this customer
-`EMBEDDING_ORIGIN` here refers to where you are adding this widget to. It will be used to generate an `allowedOrigin` parameter for the webapp to open communications with the widget.
+- `AIRBYTE_BASE_URL`: where your Airbyte instance is deployed
+- `CUSTOMER_WORKSPACE_ID`: the workspace you have associated with this customer
+- `EMBEDDING_ORIGIN`: the origin where you're embedding the widget (used for CORS validation)
 
-You can also, optionally, send an `externalUserId` in your request and we will attach it to the jwt encoded within the Airbyte Embedded token for provenance purposes.
+You can also, optionally, send an `externalUserId` in your request and we will attach it to the JWT encoded within the Airbyte Embedded token for provenance.
 
-Embedded tokens are short-lived (15-minutes) and only allow an end user to create and edit Airbyte source configurations within the workspace you have created for them.
+Embedded tokens are short-lived (15 minutes) and only allow the user to create/edit configurations within the scoped workspace.
+
+---
 
 ### Event Callbacks
 
-The widget also accepts an `onEvent` function as an argument. This function, if provided, will be executed when a user completes the integration setup or update flow. These events have the following format:
+You can pass an `onEvent` callback to receive messages when the user completes actions in the widget:
 
-```typescript
-// successful events:
+```ts
 {
   type: "end_user_action_result";
   message: "partial_user_config_created" | "partial_user_config_updated";
-  data: PartialUserConfigRead; // an object containing all data related to the user's configuration, including an actorId identifying the source created/updated
+  data: PartialUserConfigRead;
 }
+```
+
+Or, in case of error:
 
-// errored events:
+```ts
 {
   type: "end_user_action_result";
   message: "partial_user_config_update_error" | "partial_user_config_create_error";
-  error: Error; // an error object, including a message property
+  error: Error;
 }
 ```
 
-This allows you to trigger operations based upon different types of results.
+Use this to trigger actions like refreshing your UI or storing source IDs.
 
-### Configuration
+---
 
-These values should be passed to where you initialize the widget like so:
+### Configuration Example
 
-```typescript
-import { EmbeddedWidget } from "airbyte-embedded-widget";
+```html
+<button id="open-airbyte">Open Airbyte</button>
 
-// Initialize the widget
-const widget = new EmbeddedWidget({
-  token: res.token,
-  onEvent: yourEventFunction,
-});
+<script>
+  const widget = new EmbeddedWidget({
+    token: "<your-token-here>",
+    onEvent: handleWidgetEvent,
+  });
 
-// Mount the widget
-widget.mount("#widget-container");
+  document.getElementById("open-airbyte").addEventListener("click", () => widget.open());
+</script>
 ```
 
 ## Demo Application
@@ -105,6 +135,34 @@ The demo application in the `/demo` directory shows a complete example of integr
 - Basic styling and layout
 - API token handling
 
+## Project Structure
+
+- `/src` - The widget library source code
+- `/demo` - A demo application showcasing the widget usage
+
+## Installation
+
+```bash
+# Using pnpm (highly recommended)
+pnpm install
+
+# Using npm
+npm install
+
+# Using yarn
+yarn install
+```
+
+## Building the Library
+
+To build the widget library:
+
+```bash
+pnpm build
+```
+
+The built files will be in the `dist` directory.
+
 ## Publishing
 
 This repository is configured to publish to npmjs.org whenever:

dev/app/api/widget_token/route.ts

@@ -18,7 +18,7 @@ const debugLog = (message: string, data?: any) => {
 };
 
 const BASE_URL = process.env.NEXT_PUBLIC_AIRBYTE_PUBLIC_API_URL || "https://local.airbyte.dev/api/public";
-const AIRBYTE_WIDGET_URL = `${BASE_URL}/v1/embedded/widget`;
+const AIRBYTE_WIDGET_URL = `${BASE_URL}/v1/embedded/widget_token`;
 const AIRBYTE_ACCESS_TOKEN_URL = `${BASE_URL}/v1/applications/token`;
 const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID;
 const CLIENT_SECRET = process.env.NEXT_PUBLIC_CLIENT_SECRET;
@@ -109,9 +109,9 @@ export async function GET(request: NextRequest) {
       return NextResponse.json({ error: "Failed to fetch embedded token" }, { status: 500 });
     }
 
-    const widgetToken = await widgetTokenResponse.text();
-
-    if (!!process.env.WEBAPP_URL) {
+    const widgetTokenJson = await widgetTokenResponse.json();
+    const widgetToken = widgetTokenJson.token;
+    if (!!process.env.NEXT_PUBLIC_WEBAPP_URL) {
       // Decode the base64 token for debugging (it's a JSON object)
       try {
         const decodedToken = JSON.parse(Buffer.from(widgetToken, "base64").toString());

dev/app/components/EmbeddedWidgetComponent.tsx

@@ -17,14 +17,13 @@ export function EmbeddedWidgetComponent({ onEvent, className }: EmbeddedWidgetCo
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [initialized, setInitialized] = useState(false);
-  const containerRef = useRef<HTMLDivElement>(null);
   const widgetRef = useRef<EmbeddedWidget | null>(null);
 
   useEffect(() => {
     let isMounted = true;
 
     const initializeWidget = async () => {
-      if (!containerRef.current || initialized) {
+      if (initialized) {
         return;
       }
 
@@ -44,11 +43,6 @@ export function EmbeddedWidgetComponent({ onEvent, className }: EmbeddedWidgetCo
           throw new Error("Missing token in response");
         }
 
-        // Check again if containerRef is still valid and component still mounted
-        if (!containerRef.current || !isMounted) {
-          return;
-        }
-
         try {
           widgetRef.current = new EmbeddedWidget({
             token: data.token,
@@ -64,9 +58,6 @@ export function EmbeddedWidgetComponent({ onEvent, className }: EmbeddedWidgetCo
             },
           });
 
-          // Mount the widget to the container element
-          widgetRef.current.mount(containerRef.current);
-
           if (isMounted) {
             setInitialized(true);
             setLoading(false);
@@ -93,11 +84,24 @@ export function EmbeddedWidgetComponent({ onEvent, className }: EmbeddedWidgetCo
     };
   }, [onEvent]);
 
+  const handleOpenWidget = () => {
+    if (widgetRef.current) {
+      widgetRef.current.open();
+    }
+  };
+
   return (
     <div className={styles.widgetComponentWrapper}>
       {loading && <div className={styles.loading}>Loading widget...</div>}
       {error && <div className={styles.error}>Error: {error}</div>}
-      <div ref={containerRef} className={`${styles.widgetMount} ${className || ""}`} />
+      {initialized && (
+        <button 
+          onClick={handleOpenWidget}
+          className={`${styles.widgetButton} ${className || ""}`}
+        >
+          Open Airbyte
+        </button>
+      )}
     </div>
   );
 }