@quiltt/vue 5.1.2

package/src/components/QuilttConnector.ts

@@ -0,0 +1,215 @@
+/**
+ * QuilttConnector - Embeds the Quiltt Connector in an iframe
+ *
+ * This component renders the Quiltt Connector directly in your page,
+ * suitable for full-page or embedded connector experiences.
+ *
+ * @example
+ * ```vue
+ * <QuilttConnector
+ *   :connector-id="connectorId"
+ *   @exit-success="handleSuccess"
+ * />
+ * ```
+ */
+
+import type { PropType } from 'vue'
+import { computed, defineComponent, h, onMounted, onUnmounted, ref } from 'vue'
+
+import type { ConnectorSDKCallbackMetadata, ConnectorSDKEventType } from '@quiltt/core'
+
+import { useQuilttSession } from '../composables/useQuilttSession'
+
+export interface QuilttConnectorHandle {
+  handleOAuthCallback: (url: string) => void
+}
+
+export const QuilttConnector = defineComponent({
+  name: 'QuilttConnector',
+
+  props: {
+    /** Quiltt Connector ID */
+    connectorId: {
+      type: String,
+      required: true,
+    },
+    /** Existing connection ID for reconnection */
+    connectionId: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /** Pre-select a specific institution */
+    institution: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /** Deep link URL for OAuth callbacks (mobile apps) */
+    appLauncherUrl: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+  },
+
+  emits: {
+    /** Connector loaded */
+    load: (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Connection successful */
+    'exit-success': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** User cancelled */
+    'exit-abort': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Error occurred */
+    'exit-error': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Any connector event */
+    event: (_type: ConnectorSDKEventType, _metadata: ConnectorSDKCallbackMetadata) => true,
+    /** OAuth URL requested (for native handling) */
+    navigate: (_url: string) => true,
+  },
+
+  setup(props, { emit, expose }) {
+    const iframeRef = ref<HTMLIFrameElement>()
+    const { session } = useQuilttSession()
+
+    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
+      }
+    }
+
+    // Connector origin for secure postMessage targeting
+    const connectorOrigin = computed(() => `https://${props.connectorId}.quiltt.app`)
+
+    // Build connector URL
+    const connectorUrl = computed(() => {
+      const url = new URL(connectorOrigin.value)
+
+      if (session.value?.token) {
+        url.searchParams.set('token', session.value.token)
+      }
+      if (props.connectionId) {
+        url.searchParams.set('connectionId', props.connectionId)
+      }
+      if (props.institution) {
+        url.searchParams.set('institution', props.institution)
+      }
+      if (props.appLauncherUrl) {
+        url.searchParams.set('app_launcher_url', props.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()
+    })
+
+    // Handle messages from the iframe
+    // The platform MessageBus sends: { source: 'quiltt', type: 'Load'|'ExitSuccess'|..., ...metadata }
+    const handleMessage = (event: MessageEvent) => {
+      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, profileId, connectorSession, url } = data
+
+      // Build metadata from message fields
+      const metadata: ConnectorSDKCallbackMetadata = {
+        connectorId: props.connectorId,
+        ...(profileId && { profileId }),
+        ...(connectionId && { connectionId }),
+        ...(connectorSession && { connectorSession }),
+      }
+
+      switch (type) {
+        case 'Load':
+          emit('event', 'Load' as ConnectorSDKEventType, metadata)
+          emit('load', metadata)
+          break
+        case 'ExitSuccess':
+          emit('event', 'ExitSuccess' as ConnectorSDKEventType, metadata)
+          emit('exit-success', metadata)
+          break
+        case 'ExitAbort':
+          emit('event', 'ExitAbort' as ConnectorSDKEventType, metadata)
+          emit('exit-abort', metadata)
+          break
+        case 'ExitError':
+          emit('event', 'ExitError' as ConnectorSDKEventType, metadata)
+          emit('exit-error', metadata)
+          break
+        case 'Navigate':
+          if (url) {
+            emit('navigate', url)
+          }
+          break
+      }
+    }
+
+    // Build OAuth callback message matching React Native SDK format
+    const buildOAuthCallbackMessage = (callbackUrl: string) => {
+      try {
+        const parsedUrl = new URL(callbackUrl)
+        const params: Record<string, string> = {}
+        parsedUrl.searchParams.forEach((value, key) => {
+          params[key] = value
+        })
+        return {
+          source: 'quiltt',
+          type: 'OAuthCallback',
+          data: { url: callbackUrl, params },
+        }
+      } catch {
+        return {
+          source: 'quiltt',
+          type: 'OAuthCallback',
+          data: { url: callbackUrl, params: {} },
+        }
+      }
+    }
+
+    const handleOAuthCallback = (url: string) => {
+      iframeRef.value?.contentWindow?.postMessage(
+        buildOAuthCallbackMessage(url),
+        connectorOrigin.value
+      )
+    }
+
+    expose({ handleOAuthCallback })
+
+    onMounted(() => {
+      window.addEventListener('message', handleMessage)
+    })
+
+    onUnmounted(() => {
+      window.removeEventListener('message', handleMessage)
+    })
+
+    return () =>
+      h('iframe', {
+        ref: iframeRef,
+        src: connectorUrl.value,
+        allow: 'publickey-credentials-get *',
+        class: 'quiltt-connector',
+        style: {
+          border: 'none',
+          width: '100%',
+          height: '100%',
+        },
+      })
+  },
+})

package/src/components/QuilttContainer.ts

@@ -0,0 +1,130 @@
+/**
+ * QuilttContainer - Container component that renders Quiltt Connector inline
+ *
+ * Renders a container element where the Quiltt Connector will be displayed.
+ * The connector opens automatically when the component mounts.
+ *
+ * @example
+ * ```vue
+ * <QuilttContainer
+ *   :connector-id="connectorId"
+ *   @exit-success="handleSuccess"
+ * />
+ * ```
+ */
+
+import { computed, defineComponent, h, onMounted, onUnmounted, type PropType, watch } from 'vue'
+
+import type { ConnectorSDKCallbackMetadata, ConnectorSDKEventType } from '@quiltt/core'
+
+import { useQuilttConnector } from '../composables/useQuilttConnector'
+import { oauthRedirectUrlDeprecationWarning } from '../constants/deprecation-warnings'
+
+export const QuilttContainer = defineComponent({
+  name: 'QuilttContainer',
+
+  props: {
+    /** Quiltt Connector ID */
+    connectorId: {
+      type: String,
+      required: true,
+    },
+    /** Existing connection ID for reconnection */
+    connectionId: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /** Pre-select a specific institution */
+    institution: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /** Deep link URL for OAuth callbacks (mobile apps) */
+    appLauncherUrl: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /**
+     * @deprecated Use `appLauncherUrl` instead. This property will be removed in a future version.
+     * The OAuth redirect URL for mobile or embedded webview flows.
+     */
+    oauthRedirectUrl: {
+      type: String as PropType<string | undefined>,
+      default: undefined,
+    },
+    /** Render as a different element */
+    as: {
+      type: String,
+      default: 'div',
+    },
+  },
+
+  emits: {
+    /** Connector loaded */
+    load: (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Connection successful */
+    'exit-success': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** User cancelled */
+    'exit-abort': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Error occurred */
+    'exit-error': (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Connector exited (any reason) */
+    exit: (_type: ConnectorSDKEventType, _metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Any connector event */
+    event: (_type: ConnectorSDKEventType, _metadata: ConnectorSDKCallbackMetadata) => true,
+  },
+
+  setup(props, { emit, slots }) {
+    watch(
+      () => props.oauthRedirectUrl,
+      (value) => {
+        if (value !== undefined) {
+          console.warn(oauthRedirectUrlDeprecationWarning)
+        }
+      },
+      { immediate: true }
+    )
+
+    const effectiveAppLauncherUri = computed(() => props.appLauncherUrl ?? props.oauthRedirectUrl)
+    let openTimeout: ReturnType<typeof setTimeout> | undefined
+
+    const { open } = useQuilttConnector(() => props.connectorId, {
+      connectionId: () => props.connectionId,
+      institution: () => props.institution,
+      appLauncherUrl: effectiveAppLauncherUri,
+      onEvent: (type, metadata) => emit('event', type, metadata),
+      onLoad: (metadata) => emit('load', metadata),
+      onExit: (type, metadata) => emit('exit', type, metadata),
+      onExitSuccess: (metadata) => emit('exit-success', metadata),
+      onExitAbort: (metadata) => emit('exit-abort', metadata),
+      onExitError: (metadata) => emit('exit-error', metadata),
+    })
+
+    onMounted(() => {
+      // Short delay to ensure SDK is loaded
+      openTimeout = setTimeout(() => {
+        open()
+      }, 100)
+    })
+
+    onUnmounted(() => {
+      if (openTimeout) {
+        clearTimeout(openTimeout)
+        openTimeout = undefined
+      }
+    })
+
+    return () =>
+      h(
+        props.as,
+        {
+          class: 'quiltt-container',
+          style: {
+            width: '100%',
+            height: '100%',
+          },
+        },
+        slots.default?.()
+      )
+  },
+})

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export { QuilttButton } from './QuilttButton'
+export { QuilttConnector, type QuilttConnectorHandle } from './QuilttConnector'
+export { QuilttContainer } from './QuilttContainer'

package/src/composables/index.ts

@@ -0,0 +1,7 @@
+export * from './useQuilttConnector'
+export * from './useQuilttInstitutions'
+export * from './useQuilttResolvable'
+export * from './useQuilttSession'
+export * from './useQuilttSettings'
+export * from './useSession'
+export * from './useStorage'

package/src/composables/useQuilttConnector.ts

@@ -0,0 +1,312 @@
+/**
+ * Quiltt Connector Composable
+ *
+ * Provides connector management functionality for Vue 3 applications.
+ * Loads the Quiltt Connector SDK and manages connector state.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useQuilttConnector } from '@quiltt/vue'
+ *
+ * const { open } = useQuilttConnector('conn_xxx', {
+ *   onExitSuccess: (metadata) => {
+ *     console.log('Connected:', metadata.connectionId)
+ *   }
+ * })
+ * </script>
+ *
+ * <template>
+ *   <button @click="open">Connect Bank Account</button>
+ * </template>
+ * ```
+ */
+
+import type { MaybeRefOrGetter } from 'vue'
+import { onMounted, onUnmounted, ref, toValue, watch } from 'vue'
+
+import type {
+  ConnectorSDK,
+  ConnectorSDKCallbacks,
+  ConnectorSDKConnector,
+  Maybe,
+  QuilttJWT,
+} from '@quiltt/core'
+import { cdnBase } from '@quiltt/core'
+import { extractVersionNumber } from '@quiltt/core/utils'
+
+import { oauthRedirectUrlDeprecationWarning } from '../constants/deprecation-warnings'
+import { getSDKAgent } from '../utils'
+import { version } from '../version'
+import { useQuilttSession } from './useQuilttSession'
+
+declare const Quiltt: ConnectorSDK
+
+export interface UseQuilttConnectorOptions extends ConnectorSDKCallbacks {
+  connectionId?: MaybeRefOrGetter<string | undefined>
+  institution?: MaybeRefOrGetter<string | undefined>
+  appLauncherUrl?: MaybeRefOrGetter<string | undefined>
+  /**
+   * @deprecated Use `appLauncherUrl` instead. This property will be removed in a future version.
+   * The OAuth redirect URL for mobile or embedded webview flows.
+   */
+  oauthRedirectUrl?: MaybeRefOrGetter<string | undefined>
+  nonce?: string
+}
+
+export interface UseQuilttConnectorReturn {
+  /** Open the connector modal */
+  open: () => void
+}
+
+/**
+ * Load the Quiltt SDK script
+ */
+const loadScript = (src: string, nonce?: string): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    // Check if already loaded
+    if (typeof Quiltt !== 'undefined') {
+      resolve()
+      return
+    }
+
+    // Check if script is already in DOM
+    const existing = document.querySelector(`script[src^="${src.split('?')[0]}"]`)
+    if (existing) {
+      existing.addEventListener('load', () => resolve())
+      existing.addEventListener('error', () => reject(new Error('Failed to load Quiltt SDK')))
+      return
+    }
+
+    const script = document.createElement('script')
+    script.src = src
+    script.async = true
+    if (nonce) script.nonce = nonce
+    script.onload = () => resolve()
+    script.onerror = () => reject(new Error('Failed to load Quiltt SDK'))
+    document.head.appendChild(script)
+  })
+}
+
+/**
+ * Composable for managing Quiltt Connector
+ *
+ * Loads the Quiltt SDK script and provides methods to open/manage connectors.
+ * This composable can run without QuilttPlugin session context; when unavailable,
+ * it logs a warning and continues without authenticated session state.
+ */
+export const useQuilttConnector = (
+  connectorId?: MaybeRefOrGetter<string | undefined>,
+  options?: UseQuilttConnectorOptions
+): UseQuilttConnectorReturn => {
+  const getConnectorId = (): string | undefined => toValue(connectorId)
+  const getConnectionId = (): string | undefined => toValue(options?.connectionId)
+  const getInstitution = (): string | undefined => toValue(options?.institution)
+  const getOauthRedirectUrl = (): string | undefined => toValue(options?.oauthRedirectUrl)
+  const getAppLauncherUri = (): string | undefined =>
+    toValue(options?.appLauncherUrl) ?? getOauthRedirectUrl()
+
+  const session = ref<Maybe<QuilttJWT | undefined>>()
+
+  try {
+    const quilttSession = useQuilttSession()
+    session.value = quilttSession.session.value
+
+    watch(
+      () => quilttSession.session.value,
+      (nextSession) => {
+        session.value = nextSession
+      },
+      { immediate: true }
+    )
+  } catch (error) {
+    console.warn(
+      '[Quiltt] useQuilttConnector: QuilttPlugin not found in the current app context. ' +
+        'Continuing without session authentication.',
+      error
+    )
+  }
+
+  const connector = ref<ConnectorSDKConnector | undefined>()
+  const isLoaded = ref(false)
+  const isOpening = ref(false)
+  const isConnectorOpen = ref(false)
+
+  // Track previous values
+  let prevConnectionId = getConnectionId()
+  let prevConnectorId = getConnectorId()
+  let prevInstitution = getInstitution()
+  let prevAppLauncherUri = getAppLauncherUri()
+  let connectorCreated = false
+
+  // Load SDK script on mount
+  onMounted(async () => {
+    const sdkVersion = extractVersionNumber(version)
+    const userAgent = getSDKAgent(sdkVersion)
+    const scriptUrl = `${cdnBase}/v1/connector.js?agent=${encodeURIComponent(userAgent)}`
+
+    try {
+      await loadScript(scriptUrl, options?.nonce)
+      isLoaded.value = true
+    } catch (error) {
+      console.error('[Quiltt] Failed to load SDK:', error)
+    }
+  })
+
+  // Update authentication when session changes
+  watch(
+    () => session.value?.token,
+    (token) => {
+      if (typeof Quiltt !== 'undefined') {
+        Quiltt.authenticate(token)
+      }
+    },
+    { immediate: true }
+  )
+
+  // Handle script loaded
+  watch(
+    isLoaded,
+    (loaded) => {
+      if (!loaded || typeof Quiltt === 'undefined') return
+
+      // Authenticate with current session
+      Quiltt.authenticate(session.value?.token)
+    },
+    { immediate: true }
+  )
+
+  watch(
+    getOauthRedirectUrl,
+    (oauthRedirectUrl) => {
+      if (oauthRedirectUrl !== undefined) {
+        console.warn(oauthRedirectUrlDeprecationWarning)
+      }
+    },
+    { immediate: true }
+  )
+
+  // Create/update connector when needed
+  const updateConnector = () => {
+    const currentConnectorId = getConnectorId()
+    if (!isLoaded.value || typeof Quiltt === 'undefined' || !currentConnectorId) return
+
+    const currentConnectionId = getConnectionId()
+    const currentInstitution = getInstitution()
+    const currentAppLauncherUri = getAppLauncherUri()
+
+    // Check for changes
+    const connectionIdChanged = prevConnectionId !== currentConnectionId
+    const connectorIdChanged = prevConnectorId !== currentConnectorId
+    const institutionChanged = prevInstitution !== currentInstitution
+    const appLauncherUrlChanged = prevAppLauncherUri !== currentAppLauncherUri
+    const hasChanges =
+      connectionIdChanged ||
+      connectorIdChanged ||
+      institutionChanged ||
+      appLauncherUrlChanged ||
+      !connectorCreated
+
+    if (hasChanges) {
+      if (currentConnectionId) {
+        // Reconnect mode
+        connector.value = Quiltt.reconnect(currentConnectorId, {
+          connectionId: currentConnectionId,
+          appLauncherUrl: currentAppLauncherUri,
+        })
+      } else {
+        // Connect mode
+        connector.value = Quiltt.connect(currentConnectorId, {
+          institution: currentInstitution,
+          appLauncherUrl: currentAppLauncherUri,
+        })
+      }
+
+      connectorCreated = true
+      prevConnectionId = currentConnectionId
+      prevConnectorId = currentConnectorId
+      prevInstitution = currentInstitution
+      prevAppLauncherUri = currentAppLauncherUri
+    }
+  }
+
+  // Watch for changes that require connector update
+  watch(
+    [isLoaded, getConnectorId, getConnectionId, getInstitution, getAppLauncherUri],
+    updateConnector,
+    {
+      immediate: true,
+    }
+  )
+
+  // Register event handlers when connector changes
+  watch(
+    connector,
+    (newConnector, oldConnector) => {
+      // Cleanup old handlers
+      if (oldConnector) {
+        // Note: Quiltt SDK handles cleanup internally
+      }
+
+      if (!newConnector) return
+
+      // Register handlers
+      if (options?.onEvent) {
+        newConnector.onEvent(options.onEvent)
+      }
+      newConnector.onOpen((metadata) => {
+        isConnectorOpen.value = true
+        options?.onOpen?.(metadata)
+      })
+      if (options?.onLoad) {
+        newConnector.onLoad(options.onLoad)
+      }
+      newConnector.onExit((type, metadata) => {
+        isConnectorOpen.value = false
+        options?.onExit?.(type, metadata)
+      })
+      if (options?.onExitSuccess) {
+        newConnector.onExitSuccess(options.onExitSuccess)
+      }
+      if (options?.onExitAbort) {
+        newConnector.onExitAbort(options.onExitAbort)
+      }
+      if (options?.onExitError) {
+        newConnector.onExitError(options.onExitError)
+      }
+    },
+    { immediate: true }
+  )
+
+  // Handle deferred opening
+  watch([connector, isOpening], ([conn, opening]) => {
+    if (conn && opening) {
+      isOpening.value = false
+      conn.open()
+    }
+  })
+
+  // Warn on unmount if connector is still open
+  onUnmounted(() => {
+    if (isConnectorOpen.value) {
+      console.error(
+        '[Quiltt] useQuilttConnector: Component unmounted while Connector is still open. ' +
+          'This may lead to memory leaks or unexpected behavior.'
+      )
+    }
+  })
+
+  /**
+   * Open the connector modal
+   */
+  const open = (): void => {
+    if (getConnectorId()) {
+      isOpening.value = true
+      updateConnector()
+    } else {
+      throw new Error('Must provide connectorId to open Quiltt Connector')
+    }
+  }
+
+  return { open }
+}