@cowprotocol/widget-lib 0.22.1 → 1.1.1

package/README.md

@@ -18,10 +18,6 @@ You can find a detailed description of all widget parameters in the [documentati
 npm install @cowprotocol/widget-lib --save
 ```
 
-```
-yarn add @cowprotocol/widget-lib
-```
-
 Create a container somewhere in your website, the widget will be rendered inside it:
 
 ```html

package/jest.config.ts

@@ -0,0 +1,10 @@
+export default {
+  displayName: 'widget-lib',
+  preset: '../../jest.preset.js',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  setupFilesAfterEnv: ['../../jest.setup.ts'],
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/libs/widget-lib',
+}

package/package.json

@@ -1,27 +1,17 @@
 {
   "name": "@cowprotocol/widget-lib",
-  "version": "0.22.1",
-  "type": "commonjs",
+  "version": "1.1.1",
   "description": "CoW Swap Widget Library. Allows you to easily embed a CoW Swap widget on your website.",
-  "main": "index.js",
-  "exports": {
-    "import": "./index.js",
-    "require": "./index.mjs"
-  },
+  "type": "commonjs",
+  "main": "./src/index.ts",
+  "types": "./src/index.d.ts",
   "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/cowprotocol/cowswap"
+  "publishConfig": {
+    "access": "public"
   },
-  "keywords": [
-    "cowprotocol",
-    "widget",
-    "cowswap",
-    "dex",
-    "widget-lib"
-  ],
   "dependencies": {
-    "@cowprotocol/events": "^2.1.0",
-    "@cowprotocol/iframe-transport": "^1.1.1"
+    "@cowprotocol/cow-sdk": "7.3.4",
+    "@cowprotocol/events": "3.1.0",
+    "@cowprotocol/iframe-transport": "2.0.2"
   }
-}
+}

package/project.json

@@ -0,0 +1,51 @@
+{
+  "name": "widget-lib",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/widget-lib/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/widget-lib",
+        "main": "libs/widget-lib/src/index.ts",
+        "tsConfig": "libs/widget-lib/tsconfig.lib.json",
+        "assets": ["libs/widget-lib/*.md"],
+        "updateBuildableProjectDepsInPackageJson": true,
+        "buildableProjectDepsInPackageJsonType": "dependencies"
+      }
+    },
+    "serve": {
+      "executor": "@nx/vite:dev-server",
+      "defaultConfiguration": "development",
+      "options": {
+        "buildTarget": "widget-lib:build",
+        "port": 3012
+      },
+      "configurations": {}
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/widget-lib/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/widget-lib/jest.config.ts",
+        "passWithNoTests": true
+      },
+      "configurations": {
+        "ci": {
+          "ci": true,
+          "codeCoverage": true
+        }
+      }
+    }
+  },
+  "tags": []
+}

package/src/IframeCowEventEmitter.ts

@@ -0,0 +1,47 @@
+import {
+  SimpleCowEventEmitter,
+  CowWidgetEventListeners,
+  CowWidgetEvents,
+  CowWidgetEventPayloadMap,
+} from '@cowprotocol/events'
+
+import { WindowListener, WidgetMethodsEmit } from './types'
+import { widgetIframeTransport } from './widgetIframeTransport'
+
+export class IframeCowEventEmitter {
+  private eventEmitter = new SimpleCowEventEmitter<CowWidgetEventPayloadMap, CowWidgetEvents>()
+  private listeners: CowWidgetEventListeners = []
+  private widgetListener: WindowListener
+
+  constructor(
+    private contentWindow: Window,
+    listeners: CowWidgetEventListeners = [],
+  ) {
+    // Subscribe listeners to local event emitter
+    this.updateListeners(listeners)
+
+    // Listen to iFrame, and forward to local event emitter
+    this.widgetListener = widgetIframeTransport.listenToMessageFromWindow(
+      this.contentWindow,
+      WidgetMethodsEmit.EMIT_COW_EVENT,
+      (cowEvent) => this.eventEmitter.emit(cowEvent.event, cowEvent.payload),
+    )
+  }
+
+  public stopListeningIframe(): void {
+    widgetIframeTransport.stopListeningWindowListener(this.contentWindow, this.widgetListener)
+  }
+
+  public updateListeners(listeners?: CowWidgetEventListeners): void {
+    // Unsubscribe from previous listeners
+    for (const listener of this.listeners) {
+      this.eventEmitter.off(listener)
+    }
+
+    // Subscribe to events
+    this.listeners = listeners || []
+    for (const listener of this.listeners) {
+      this.eventEmitter.on(listener)
+    }
+  }
+}

package/src/IframeSafeSdkBridge.ts

@@ -0,0 +1,77 @@
+export class IframeSafeSdkBridge {
+  forwardSdkMessage: (event: MessageEvent<unknown>) => void
+
+  constructor(
+    private appWindow: Window,
+    private iframeWidow: Window,
+  ) {
+    this.forwardSdkMessage = (event: MessageEvent<unknown>) => {
+      if (!isSafeMessage(event.data)) {
+        return
+      }
+
+      if (typeof window !== 'undefined' && event.origin === window.location.origin) {
+        return
+      }
+
+      if (isSafeMessageRequest(event.data)) {
+        this.appWindow.parent.postMessage(event.data, '*')
+      } else if (isSafeMessageResponse(event.data)) {
+        this.iframeWidow.postMessage(event.data, '*')
+      }
+    }
+
+    this.startListening()
+  }
+
+  private startListening(): void {
+    this.appWindow.addEventListener('message', this.forwardSdkMessage)
+  }
+
+  public stopListening(): void {
+    this.appWindow.removeEventListener('message', this.forwardSdkMessage)
+  }
+}
+
+function isSafeMessage(obj: unknown): obj is SafeMessage {
+  return typeof obj === 'object' && obj !== null && 'id' in obj && typeof obj.id === 'string'
+}
+
+function isSafeMessageRequest(message: SafeMessage): message is SafeMessageRequest {
+  return (
+    'method' in message &&
+    typeof message.method === 'string' &&
+    'params' in message &&
+    'env' in message &&
+    typeof message.env === 'object' &&
+    message.env !== null &&
+    'sdkVersion' in message.env
+  )
+}
+
+function isSafeMessageResponse(message: SafeMessage): message is SafeMessageResponse {
+  return (
+    'success' in message &&
+    typeof message.success === 'boolean' &&
+    'version' in message &&
+    typeof message.version === 'string'
+  )
+}
+
+interface SafeMessage {
+  id: string
+}
+
+interface SafeMessageRequest extends SafeMessage {
+  method: string
+  params: unknown
+  env: {
+    sdkVersion: string
+  }
+}
+
+interface SafeMessageResponse extends SafeMessage {
+  id: string
+  success: boolean
+  version: string
+}

package/src/cowSwapWidget.ts

@@ -0,0 +1,259 @@
+import { CowWidgetEventListeners } from '@cowprotocol/events'
+import { IframeRpcProviderBridge } from '@cowprotocol/iframe-transport'
+
+import { IframeCowEventEmitter } from './IframeCowEventEmitter'
+import { IframeSafeSdkBridge } from './IframeSafeSdkBridge'
+import {
+  CowSwapWidgetParams,
+  CowSwapWidgetProps,
+  EthereumProvider,
+  WidgetMethodsEmit,
+  WidgetMethodsListen,
+  WindowListener,
+} from './types'
+import { buildWidgetPath, buildWidgetUrl, buildWidgetUrlQuery } from './urlUtils'
+import { widgetIframeTransport } from './widgetIframeTransport'
+
+const DEFAULT_HEIGHT = '640px'
+const DEFAULT_WIDTH = '450px'
+
+/**
+ * Reference: IframeResizer (apps/cowswap-frontend/src/modules/injectedWidget/updaters/IframeResizer.ts)
+ * Sometimes MutationObserver doesn't trigger when the height of the widget changes and the widget displays with a scrollbar.
+ * To avoid this we add a threshold to the height.
+ * 20px
+ */
+const HEIGHT_THRESHOLD = 20
+
+const noopHandler: CowSwapWidgetHandler = {
+  updateParams: () => void 0,
+  updateListeners: () => void 0,
+  updateProvider: () => void 0,
+  destroy: () => void 0,
+}
+
+/**
+ * Callback function signature for updating the CoW Swap Widget.
+ */
+export interface CowSwapWidgetHandler {
+  updateParams: (params: CowSwapWidgetParams) => void
+  updateListeners: (newListeners?: CowWidgetEventListeners) => void
+  updateProvider: (newProvider?: EthereumProvider) => void
+  destroy: () => void
+}
+
+/**
+ * Generates and injects a CoW Swap Widget into the provided container.
+ * @param container - The HTML element to inject the widget into.
+ * @param params - Parameters for configuring the widget.
+ * @returns A callback function to update the widget with new settings.
+ */
+export function createCowSwapWidget(container: HTMLElement, props: CowSwapWidgetProps): CowSwapWidgetHandler {
+  const { params, provider: providerAux, listeners } = props
+  let provider = providerAux
+  let currentParams = params
+
+  if (typeof window === 'undefined') return noopHandler
+
+  // 1. Create a brand new iframe
+  const iframe = createIframe(params)
+
+  // 2. Clear the content (delete any previous iFrame if it exists)
+  container.innerHTML = ''
+  container.appendChild(iframe)
+
+  const { contentWindow: iframeWindow } = iframe
+  if (!iframeWindow) {
+    console.error('Iframe does not contain a window', iframe)
+    throw new Error('Iframe does not contain a window!')
+  }
+
+  // 3. Send appCode (once the widget posts the ACTIVATE message)
+  const windowListeners: WindowListener[] = []
+  windowListeners.push(sendAppCodeOnActivation(iframeWindow, params.appCode))
+
+  // 4. Handle widget height changes
+  windowListeners.push(...listenToHeightChanges(iframe, params.height, params.maxHeight))
+
+  // 5. Intercept deeplinks navigation in the iframe
+  windowListeners.push(interceptDeepLinks())
+
+  // 6. Handle and forward widget events to the listeners
+  const iFrameCowEventEmitter = new IframeCowEventEmitter(window, listeners)
+
+  // 7. Wire up the iframeRpcProviderBridge with the provider (so RPC calls flow back and forth)
+  let iframeRpcProviderBridge = updateProvider(iframeWindow, null, provider)
+
+  // 8. Schedule the uploading of the params, once the iframe is loaded
+  iframe.addEventListener('load', () => updateParams(iframeWindow, currentParams, provider))
+
+  // 9. Listen for messages from the iframe
+  const iframeSafeSdkBridge = new IframeSafeSdkBridge(window, iframeWindow)
+
+  // 10. Return the handler, so the widget, listeners, and provider can be updated
+  return {
+    updateParams: (newParams: CowSwapWidgetParams) => {
+      currentParams = newParams
+      updateParams(iframeWindow, currentParams, provider)
+    },
+    updateListeners: (newListeners?: CowWidgetEventListeners) => iFrameCowEventEmitter.updateListeners(newListeners),
+    updateProvider: (newProvider) => {
+      provider = newProvider
+      iframeRpcProviderBridge = updateProvider(iframeWindow, iframeRpcProviderBridge, newProvider)
+    },
+
+    destroy: () => {
+      // Disconnect rpc provider and unsubscribe to events
+      iframeRpcProviderBridge.disconnect()
+      // Stop listening for cow events
+      iFrameCowEventEmitter.stopListeningIframe()
+
+      // Disconnect all listeners
+      windowListeners.forEach((listener) => window.removeEventListener('message', listener))
+
+      // Stop listening for SDK messages
+      iframeSafeSdkBridge.stopListening()
+
+      // Destroy the iframe
+      container.removeChild(iframe)
+    },
+  }
+}
+
+/**
+ * Update the provider for the iframeRpcProviderBridge.
+ *
+ * It will disconnect from the previous provider and connect to the new one.
+ *
+ * @param iframe iframe window
+ * @param iframeRpcProviderBridge iframe RPC manager
+ * @param newProvider new provider
+ *
+ * @returns the iframeRpcProviderBridge
+ */
+function updateProvider(
+  iframe: Window,
+  iframeRpcProviderBridge: IframeRpcProviderBridge | null,
+  newProvider?: EthereumProvider,
+): IframeRpcProviderBridge {
+  // Disconnect from the previous provider bridge
+  if (iframeRpcProviderBridge) {
+    iframeRpcProviderBridge.disconnect()
+  }
+
+  const providerBridge = iframeRpcProviderBridge || new IframeRpcProviderBridge(iframe)
+
+  // Connect to the new provider
+  if (newProvider) {
+    providerBridge.onConnect(newProvider)
+  }
+
+  return providerBridge
+}
+
+/**
+ * Creates an iframe element for the CoW Swap Widget based on provided parameters and settings.
+ * @param params - Parameters for the widget.
+ * @returns The generated HTMLIFrameElement.
+ */
+function createIframe(params: CowSwapWidgetParams): HTMLIFrameElement {
+  const { width = DEFAULT_WIDTH, height = DEFAULT_HEIGHT } = params
+
+  const iframe = document.createElement('iframe')
+
+  iframe.src = buildWidgetUrl(params)
+  iframe.width = width
+  iframe.height = height
+  iframe.style.border = '0'
+  iframe.allow = 'clipboard-read; clipboard-write'
+
+  return iframe
+}
+
+/**
+ * Updates the CoW Swap Widget based on the new settings provided.
+ * @param params - New params for the widget.
+ * @param contentWindow - Window object of the widget's iframe.
+ */
+function updateParams(
+  contentWindow: Window,
+  params: CowSwapWidgetParams,
+  provider: EthereumProvider | undefined,
+): void {
+  const hasProvider = !!provider
+
+  const pathname = buildWidgetPath(params)
+  const search = buildWidgetUrlQuery(params).toString()
+
+  // Omit theme from appParams
+  const { theme: _theme, ...appParams } = params
+
+  widgetIframeTransport.postMessageToWindow(contentWindow, WidgetMethodsListen.UPDATE_PARAMS, {
+    urlParams: {
+      pathname,
+      search,
+    },
+    appParams,
+    hasProvider,
+  })
+}
+
+/**
+ * Sends appCode to the contentWindow of the widget once the widget is activated.
+ *
+ * @param contentWindow - Window object of the widget's iframe.
+ * @param appCode - A unique identifier for the app.
+ */
+function sendAppCodeOnActivation(
+  contentWindow: Window,
+  appCode: string | undefined,
+): (payload: MessageEvent<unknown>) => void {
+  return widgetIframeTransport.listenToMessageFromWindow(window, WidgetMethodsEmit.ACTIVATE, () => {
+    // Update the appData
+    widgetIframeTransport.postMessageToWindow(contentWindow, WidgetMethodsListen.UPDATE_APP_DATA, {
+      metaData: appCode ? { appCode } : undefined,
+    })
+  })
+}
+
+/**
+ * Since deeplinks are not supported in iframes, this function intercepts the window.open calls from the widget and opens
+ */
+function interceptDeepLinks(): (payload: MessageEvent<unknown>) => void {
+  return widgetIframeTransport.listenToMessageFromWindow(
+    window,
+    WidgetMethodsEmit.INTERCEPT_WINDOW_OPEN,
+    ({ href, rel, target }) => {
+      const url = href.toString()
+
+      if (!url.startsWith('http') && url.match(/^[a-zA-Z0-9]+:\/\//)) {
+        window.open(url, target, rel)
+        return
+      }
+    },
+  )
+}
+
+/**
+ * Listens for iframeHeight emitted by the widget, and applies dynamic height adjustments to the widget's iframe.
+ *
+ * @param iframe - The HTMLIFrameElement of the widget.
+ * @param defaultHeight - Default height for the widget.
+ * @param maxHeight - Maximum height for the widget.
+ */
+function listenToHeightChanges(
+  iframe: HTMLIFrameElement,
+  defaultHeight = DEFAULT_HEIGHT,
+  maxHeight?: number,
+): WindowListener[] {
+  return [
+    widgetIframeTransport.listenToMessageFromWindow(window, WidgetMethodsEmit.UPDATE_HEIGHT, (data) => {
+      const newHeight = data.height ? data.height + HEIGHT_THRESHOLD : undefined
+
+      iframe.style.height = newHeight ? `${maxHeight ? Math.min(newHeight, maxHeight) : newHeight}px` : defaultHeight
+    }),
+    widgetIframeTransport.listenToMessageFromWindow(window, WidgetMethodsEmit.SET_FULL_HEIGHT, ({ isUpToSmall }) => {
+      iframe.style.height = isUpToSmall ? defaultHeight : `${maxHeight || document.body.offsetHeight}px`
+    }),
+  ]
+}

package/src/flexibleConfig.ts

@@ -0,0 +1,39 @@
+import type { SupportedChainId } from '@cowprotocol/cow-sdk'
+
+import { FlexibleConfig, PerNetworkConfig, PerTradeTypeConfig, TradeType } from './types'
+
+const TradeTypes = Object.values(TradeType)
+
+export function resolveFlexibleConfig<T>(
+  config: FlexibleConfig<T>,
+  chainId: SupportedChainId,
+  tradeType: TradeType,
+): T | undefined {
+  if (isPerTradeTypeConfig(config)) {
+    const value = config[tradeType]
+
+    return isPerNetworkConfig(value) ? value[chainId] : value
+  }
+
+  if (isPerNetworkConfig(config)) {
+    const value = config[chainId]
+
+    return isPerTradeTypeConfig(value) ? value[tradeType] : value
+  }
+
+  return config as T
+}
+
+export function isPerTradeTypeConfig<T>(config: FlexibleConfig<T>): config is PerTradeTypeConfig<T> {
+  if (typeof config !== 'object') return false
+
+  return Object.keys(config as object).every((key) => TradeTypes.includes(key as TradeType))
+}
+
+const D_REGEX = /^\d+$/
+
+export function isPerNetworkConfig<T>(config: FlexibleConfig<T>): config is PerNetworkConfig<T> {
+  if (typeof config !== 'object') return false
+
+  return Object.keys(config as object).every((key) => D_REGEX.test(key))
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { createCowSwapWidget } from './cowSwapWidget'
+export { widgetIframeTransport } from './widgetIframeTransport'
+export type { CowSwapWidgetHandler } from './cowSwapWidget'
+export * from './types'
+export * from './themeUtils'
+export * from './flexibleConfig'
+export { resolveFlexibleConfigValues } from './resolveFlexibleConfigValues'

package/src/resolveFlexibleConfigValues.ts

@@ -0,0 +1,14 @@
+import { isPerNetworkConfig, isPerTradeTypeConfig } from './flexibleConfig'
+import { FlexibleConfig } from './types'
+
+export function resolveFlexibleConfigValues<T>(config: FlexibleConfig<T>): T[] {
+  if (isPerTradeTypeConfig(config)) {
+    return Object.values(config).flatMap((value) => (isPerNetworkConfig(value) ? Object.values(value) : [value]))
+  }
+
+  if (isPerNetworkConfig(config)) {
+    return Object.values(config).flatMap((value) => (isPerTradeTypeConfig(value) ? Object.values(value) : [value]))
+  }
+
+  return [config] as T[]
+}

package/src/themeUtils.ts

@@ -0,0 +1,7 @@
+import { CowSwapTheme, CowSwapWidgetPalette } from './types'
+
+export function isCowSwapWidgetPalette(
+  palette: CowSwapTheme | CowSwapWidgetPalette | undefined,
+): palette is CowSwapWidgetPalette {
+  return Boolean(palette && typeof palette === 'object')
+}