@quiltt/capacitor 5.1.2

package/src/components/QuilttConnector.tsx

@@ -0,0 +1,349 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import type { ConnectorSDKCallbackMetadata, ConnectorSDKCallbacks } from '@quiltt/react'
+import { ConnectorSDKEventType, useQuilttSession } from '@quiltt/react'
+
+import { QuilttConnector as QuilttConnectorPlugin } from '../plugin'
+
+export type QuilttConnectorHandle = {
+  handleOAuthCallback: (url: string) => void
+}
+
+type QuilttConnectorProps = {
+  connectorId: string
+  connectionId?: string
+  institution?: string
+  /**
+   * The app launcher URL for mobile OAuth flows.
+   * This URL should be a Universal Link (iOS) or App Link (Android) that redirects back to your app.
+   */
+  appLauncherUrl?: string
+  style?: React.CSSProperties
+  className?: string
+} & ConnectorSDKCallbacks
+
+const trustedQuilttHostSuffixes = ['quiltt.io', 'quiltt.dev', 'quiltt.app']
+
+const isTrustedQuilttOrigin = (origin: string): boolean => {
+  try {
+    const originUrl = new URL(origin)
+    if (originUrl.protocol !== 'https:') {
+      return false
+    }
+
+    const hostname = originUrl.hostname.toLowerCase()
+    return trustedQuilttHostSuffixes.some(
+      (suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`)
+    )
+  } catch {
+    return false
+  }
+}
+
+const decodeIfEncoded = (value: string): string => {
+  try {
+    const decoded = decodeURIComponent(value)
+    return decoded === value ? value : decoded
+  } catch {
+    return value
+  }
+}
+
+const normalizeUrlValue = (value: string): string => decodeIfEncoded(value.trim())
+
+/**
+ * QuilttConnector component for Capacitor apps
+ * Embeds the Quiltt Connector in an iframe and handles OAuth flows via native plugins
+ */
+export const QuilttConnector = forwardRef<QuilttConnectorHandle, QuilttConnectorProps>(
+  (
+    {
+      connectorId,
+      connectionId,
+      institution,
+      appLauncherUrl,
+      style,
+      className,
+      onEvent,
+      onLoad,
+      onExit,
+      onExitSuccess,
+      onExitAbort,
+      onExitError,
+    },
+    ref
+  ) => {
+    const iframeRef = useRef<HTMLIFrameElement>(null)
+    const { session } = useQuilttSession()
+    const [isLoaded, setIsLoaded] = useState(false)
+    const [loadError, setLoadError] = useState<string | null>(null)
+
+    // Connector origin for secure postMessage targeting
+    const connectorOrigin = useMemo(() => `https://${connectorId}.quiltt.app`, [connectorId])
+
+    // Build connector URL
+    const connectorUrl = useMemo(() => {
+      const url = new URL(connectorOrigin)
+
+      if (session?.token) {
+        url.searchParams.set('token', session.token)
+      }
+      if (connectionId) {
+        url.searchParams.set('connectionId', connectionId)
+      }
+      if (institution) {
+        url.searchParams.set('institution', institution)
+      }
+      if (appLauncherUrl) {
+        url.searchParams.set('app_launcher_url', normalizeUrlValue(appLauncherUrl))
+      }
+
+      if (typeof window !== 'undefined') {
+        url.searchParams.set('embed_location', window.location.href)
+      }
+
+      // Set mode for inline iframe embedding
+      url.searchParams.set('mode', 'INLINE')
+
+      return url.toString()
+    }, [connectorOrigin, session?.token, connectionId, institution, appLauncherUrl])
+
+    useEffect(() => {
+      setIsLoaded(false)
+      setLoadError(null)
+
+      const abortController = new AbortController()
+
+      const runPreflight = async () => {
+        try {
+          await fetch(connectorUrl, {
+            method: 'GET',
+            mode: 'no-cors',
+            credentials: 'omit',
+            signal: abortController.signal,
+          })
+        } catch {
+          setLoadError('Unable to reach Quiltt Connector. Check network and connector settings.')
+        }
+      }
+
+      void runPreflight()
+
+      return () => {
+        abortController.abort()
+      }
+    }, [connectorUrl])
+
+    useEffect(() => {
+      if (isLoaded || loadError) {
+        return
+      }
+
+      const timeoutId = window.setTimeout(() => {
+        setLoadError('Connector took too long to load. Please retry.')
+      }, 15000)
+
+      return () => {
+        window.clearTimeout(timeoutId)
+      }
+    }, [isLoaded, loadError])
+
+    const postOAuthCallbackToIframe = useCallback(
+      (callbackUrl: string) => {
+        if (!iframeRef.current?.contentWindow) {
+          return
+        }
+
+        const normalizedCallbackUrl = normalizeUrlValue(callbackUrl)
+
+        try {
+          const callback = new URL(normalizedCallbackUrl)
+          const params: Record<string, string> = {}
+          callback.searchParams.forEach((value, key) => {
+            params[key] = value
+          })
+
+          iframeRef.current.contentWindow.postMessage(
+            {
+              source: 'quiltt',
+              type: 'OAuthCallback',
+              data: {
+                url: normalizedCallbackUrl,
+                params,
+              },
+            },
+            connectorOrigin
+          )
+        } catch {
+          iframeRef.current.contentWindow.postMessage(
+            {
+              source: 'quiltt',
+              type: 'OAuthCallback',
+              data: {
+                url: normalizedCallbackUrl,
+                params: {},
+              },
+            },
+            connectorOrigin
+          )
+        }
+      },
+      [connectorOrigin]
+    )
+
+    // Handle messages from the iframe
+    // The platform MessageBus sends: { source: 'quiltt', type: 'Load'|'ExitSuccess'|..., ...metadata }
+    const handleMessage = useCallback(
+      (event: MessageEvent) => {
+        // Validate origin
+        if (!isTrustedQuilttOrigin(event.origin)) {
+          return
+        }
+
+        const data = event.data || {}
+        // Validate message is from Quiltt MessageBus
+        if (data.source !== 'quiltt' || !data.type) return
+
+        const { type, connectionId: msgConnectionId, profileId, connectorSession, url } = data
+
+        // Build metadata from message fields
+        const metadata: ConnectorSDKCallbackMetadata = {
+          connectorId,
+          ...(profileId && { profileId }),
+          ...(msgConnectionId && { connectionId: msgConnectionId }),
+          ...(connectorSession && { connectorSession }),
+        }
+
+        switch (type) {
+          case 'Load':
+            setIsLoaded(true)
+            setLoadError(null)
+            onEvent?.(ConnectorSDKEventType.Load, metadata)
+            onLoad?.(metadata)
+            break
+
+          case 'ExitSuccess':
+            onEvent?.(ConnectorSDKEventType.ExitSuccess, metadata)
+            onExit?.(ConnectorSDKEventType.ExitSuccess, metadata)
+            onExitSuccess?.(metadata)
+            break
+
+          case 'ExitAbort':
+            onEvent?.(ConnectorSDKEventType.ExitAbort, metadata)
+            onExit?.(ConnectorSDKEventType.ExitAbort, metadata)
+            onExitAbort?.(metadata)
+            break
+
+          case 'ExitError':
+            onEvent?.(ConnectorSDKEventType.ExitError, metadata)
+            onExit?.(ConnectorSDKEventType.ExitError, metadata)
+            onExitError?.(metadata)
+            break
+
+          case 'Navigate':
+            // OAuth URL - open in system browser
+            if (url) {
+              QuilttConnectorPlugin.openUrl({ url })
+            }
+            break
+
+          default:
+            // console.log(`Unhandled event: ${eventType}`)
+            break
+        }
+      },
+      [connectorId, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError]
+    )
+
+    // Set up message listener
+    useEffect(() => {
+      window.addEventListener('message', handleMessage)
+      return () => window.removeEventListener('message', handleMessage)
+    }, [handleMessage])
+
+    // Listen for OAuth callbacks via deep links
+    useEffect(() => {
+      const listener = QuilttConnectorPlugin.addListener('deepLink', (event) => {
+        if (event.url) {
+          postOAuthCallbackToIframe(event.url)
+        }
+      })
+
+      // Check if app was launched with a URL
+      QuilttConnectorPlugin.getLaunchUrl().then((result) => {
+        if (result?.url) {
+          postOAuthCallbackToIframe(result.url)
+        }
+      })
+
+      return () => {
+        listener.then((l) => l.remove())
+      }
+    }, [postOAuthCallbackToIframe])
+
+    // Expose method to handle OAuth callbacks from parent component
+    useImperativeHandle(
+      ref,
+      () => ({
+        handleOAuthCallback: (callbackUrl: string) => {
+          postOAuthCallbackToIframe(callbackUrl)
+        },
+      }),
+      [postOAuthCallbackToIframe]
+    )
+
+    return (
+      <div
+        className={className}
+        style={{
+          width: '100%',
+          height: '100%',
+          position: 'relative',
+          ...style,
+        }}
+      >
+        <iframe
+          ref={iframeRef}
+          src={connectorUrl}
+          title="Quiltt Connector"
+          allow="publickey-credentials-get *"
+          style={{
+            border: 'none',
+            width: '100%',
+            height: '100%',
+          }}
+          onError={() => {
+            setLoadError('Unable to load Quiltt Connector iframe.')
+          }}
+        />
+
+        {loadError ? (
+          <div
+            style={{
+              position: 'absolute',
+              inset: 0,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              padding: '16px',
+              textAlign: 'center',
+              backgroundColor: '#fff',
+            }}
+          >
+            {loadError}
+          </div>
+        ) : null}
+      </div>
+    )
+  }
+)
+
+QuilttConnector.displayName = 'QuilttConnector'

package/src/components/index.ts

@@ -0,0 +1 @@
+export * from './QuilttConnector'

package/src/definitions.ts

@@ -0,0 +1,81 @@
+import type { PluginListenerHandle } from '@capacitor/core'
+
+/**
+ * Options for opening a URL in the system browser
+ */
+export interface OpenUrlOptions {
+  /**
+   * The URL to open in the system browser
+   */
+  url: string
+}
+
+/**
+ * Event data when a deep link is received
+ */
+export interface DeepLinkEvent {
+  /**
+   * The full URL that was used to open the app, or null if no URL was present
+   */
+  url: string | null
+}
+
+/**
+ * Listener function for deep link events
+ */
+export type DeepLinkListener = (event: DeepLinkEvent) => void
+
+/**
+ * The Quiltt Connector Capacitor plugin interface.
+ *
+ * This plugin handles native functionality required for the Quiltt Connector:
+ * - Opening OAuth URLs in the system browser
+ * - Handling deep links / App Links / Universal Links for OAuth callbacks
+ */
+export interface QuilttConnectorPlugin {
+  /**
+   * Open a URL in the system browser.
+   *
+   * This is used for OAuth flows where the user needs to authenticate
+   * with their financial institution in an external browser.
+   *
+   * @param options - The options containing the URL to open
+   * @returns A promise that resolves when the browser is opened
+   *
+   * @since 5.0.3
+   */
+  openUrl(options: OpenUrlOptions): Promise<{ completed: boolean }>
+
+  /**
+   * Get the URL that was used to launch the app, if any.
+   *
+   * This is useful for handling OAuth callbacks when the app is opened
+   * from a Universal Link (iOS) or App Link (Android).
+   *
+   * @returns A promise that resolves with the launch URL, or undefined if none
+   *
+   * @since 5.0.3
+   */
+  getLaunchUrl(): Promise<DeepLinkEvent>
+
+  /**
+   * Listen for deep link events.
+   *
+   * This is called when the app is opened via a Universal Link (iOS)
+   * or App Link (Android), typically during OAuth callback flows.
+   *
+   * @param eventName - The event name ('deepLink')
+   * @param listenerFunc - The callback function to handle the event
+   * @returns A promise that resolves with a handle to remove the listener
+   *
+   * @since 5.0.3
+   */
+  addListener(eventName: 'deepLink', listenerFunc: DeepLinkListener): Promise<PluginListenerHandle>
+
+  /**
+   * Remove all listeners for this plugin.
+   *
+   * @since 5.0.3
+   */
+  removeAllListeners(): Promise<void>
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @quiltt/capacitor - Framework-agnostic Capacitor plugin for Quiltt Connector
+ *
+ * This entry point provides the native Capacitor plugin without any
+ * framework dependencies. Works with Vue, Angular, Svelte, vanilla JS, etc.
+ *
+ * For React apps, import from '@quiltt/capacitor/react' instead.
+ *
+ * @example
+ * ```typescript
+ * import { QuilttConnector } from '@quiltt/capacitor'
+ *
+ * // Open OAuth URL in system browser
+ * await QuilttConnector.openUrl({ url: 'https://...' })
+ *
+ * // Listen for deep link callbacks
+ * await QuilttConnector.addListener('deepLink', ({ url }) => {
+ *   console.log('OAuth callback:', url)
+ * })
+ * ```
+ */
+
+// Export type definitions
+export type {
+  DeepLinkEvent,
+  DeepLinkListener,
+  OpenUrlOptions,
+  QuilttConnectorPlugin,
+} from './definitions'
+// Export native plugin
+export { QuilttConnector } from './plugin'

package/src/plugin.ts

@@ -0,0 +1,11 @@
+import { registerPlugin } from '@capacitor/core'
+
+import type { QuilttConnectorPlugin } from './definitions'
+
+/**
+ * Native Capacitor plugin for deep link handling and URL opening
+ * Used internally by QuilttConnector component for OAuth flows
+ */
+export const QuilttConnector = registerPlugin<QuilttConnectorPlugin>('QuilttConnector', {
+  web: () => import('./web').then((m) => new m.QuilttConnectorWeb()),
+})

package/src/react.ts

@@ -0,0 +1,33 @@
+/**
+ * @quiltt/capacitor/react - React components for Quiltt Connector in Capacitor apps
+ *
+ * This entry point provides React components and hooks for Capacitor apps.
+ * Requires React 16.8+ and @quiltt/react as peer dependencies.
+ *
+ * For non-React apps (Vue, Angular, Svelte), import from '@quiltt/capacitor' instead.
+ *
+ * @example
+ * ```tsx
+ * import { QuilttConnector, useQuilttSession } from '@quiltt/capacitor/react'
+ *
+ * function App() {
+ *   return (
+ *     <QuilttConnector
+ *       connectorId="<CONNECTOR_ID>"
+ *       onExitSuccess={({ connectionId }) => console.log(connectionId)}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+
+// Re-export all @quiltt/react functionality for convenience
+export * from '@quiltt/react'
+
+// Export Capacitor-specific QuilttConnector component
+export type { QuilttConnectorHandle } from './components'
+export { QuilttConnector } from './components'
+// Export plugin type definitions
+export * from './definitions'
+// Export native plugin for advanced use cases
+export { QuilttConnector as QuilttConnectorPlugin } from './plugin'

package/src/vue.ts

@@ -0,0 +1,42 @@
+/**
+ * @quiltt/capacitor/vue - Vue 3 components for Quiltt Connector in Capacitor apps
+ *
+ * This entry point provides Vue 3 components and composables for Capacitor apps.
+ * Requires Vue 3.3+ and @quiltt/vue as peer dependencies.
+ *
+ * For non-framework apps in plain JS (Vue, Angular, Svelte, etc.), you can also use
+ * the framework-agnostic import from '@quiltt/capacitor' directly.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'vue'
+ * import { QuilttPlugin } from '@quiltt/capacitor/vue'
+ *
+ * const app = createApp(App)
+ * app.use(QuilttPlugin, { token: '<SESSION_TOKEN>' })
+ * app.mount('#app')
+ * ```
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { QuilttConnector, useQuilttSession } from '@quiltt/capacitor/vue'
+ * </script>
+ *
+ * <template>
+ *   <QuilttConnector
+ *     connector-id="<CONNECTOR_ID>"
+ *     @exit-success="handleSuccess"
+ *     @navigate="handleNavigate"
+ *   />
+ * </template>
+ * ```
+ */
+
+// Re-export all @quiltt/vue functionality
+export * from '@quiltt/vue'
+
+// Export plugin type definitions
+export * from './definitions'
+// Export native plugin for OAuth handling
+export { QuilttConnector as QuilttConnectorPlugin } from './plugin'

package/src/web.ts

@@ -0,0 +1,44 @@
+import { WebPlugin } from '@capacitor/core'
+
+import type { DeepLinkEvent, OpenUrlOptions, QuilttConnectorPlugin } from './definitions'
+
+/**
+ * Web implementation of the Quiltt Connector plugin.
+ *
+ * On web, OAuth flows typically work without special handling since
+ * the browser handles redirects automatically. This implementation
+ * provides basic functionality for web compatibility.
+ */
+export class QuilttConnectorWeb extends WebPlugin implements QuilttConnectorPlugin {
+  /**
+   * Open a URL in a new browser tab/window.
+   *
+   * On web, this simply opens the URL in a new tab using window.open.
+   */
+  async openUrl(options: OpenUrlOptions): Promise<{ completed: boolean }> {
+    window.open(options.url, '_blank', 'noopener,noreferrer')
+    return { completed: true }
+  }
+
+  /**
+   * Get the launch URL on web.
+   *
+   * On web, we check the current URL for any OAuth callback parameters.
+   * This is useful when the user is redirected back to the app after OAuth.
+   */
+  async getLaunchUrl(): Promise<DeepLinkEvent> {
+    const currentUrl = window.location.href
+
+    // Check if the current URL contains OAuth callback parameters
+    // Common patterns include: code=, state=, error=
+    const url = new URL(currentUrl)
+    const hasOAuthParams =
+      url.searchParams.has('code') || url.searchParams.has('state') || url.searchParams.has('error')
+
+    if (hasOAuthParams) {
+      return { url: currentUrl }
+    }
+
+    return { url: null }
+  }
+}