@quiltt/vue 5.1.2

package/src/composables/useQuilttInstitutions.ts

@@ -0,0 +1,114 @@
+import { computed, onUnmounted, ref, shallowRef, watch } from 'vue'
+
+import type { ErrorData, InstitutionsData } from '@quiltt/core'
+import { ConnectorsAPI } from '@quiltt/core'
+import { extractVersionNumber } from '@quiltt/core/utils'
+
+import { getSDKAgent } from '../utils'
+import { version } from '../version'
+import { useQuilttSession } from './useQuilttSession'
+
+/**
+ * Search institutions for a connector.
+ * Requires QuilttPlugin session context and throws when used without it.
+ */
+export const useQuilttInstitutions = (
+  connectorId: string,
+  onErrorCallback?: (msg: string) => void
+) => {
+  const { session } = useQuilttSession()
+
+  const searchTermInput = ref('')
+  const searchTerm = ref('')
+  const searchResults = ref<InstitutionsData>([])
+  const isSearching = ref(false)
+
+  const debounceTimer = ref<ReturnType<typeof setTimeout> | undefined>()
+  const abortController = shallowRef<AbortController | undefined>()
+
+  const sdkVersion = extractVersionNumber(version)
+  const connectorsAPI = new ConnectorsAPI(connectorId, getSDKAgent(sdkVersion))
+
+  const handleError = (message: string) => {
+    const errorMessage = message || 'Unknown error occurred while searching institutions'
+    console.error('Quiltt Institutions Search Error:', errorMessage)
+    onErrorCallback?.(errorMessage)
+  }
+
+  const setSearchTerm = (term: string) => {
+    searchTermInput.value = term
+
+    if (debounceTimer.value) {
+      clearTimeout(debounceTimer.value)
+    }
+
+    if (term.trim().length < 2) {
+      abortController.value?.abort()
+      abortController.value = undefined
+      searchTerm.value = ''
+      searchResults.value = []
+      isSearching.value = false
+      return
+    }
+
+    isSearching.value = true
+    debounceTimer.value = setTimeout(() => {
+      searchTerm.value = term
+    }, 350)
+  }
+
+  watch(
+    [() => session.value?.token, searchTerm],
+    async ([token, term]) => {
+      if (!token || !connectorId || !term || term.trim().length < 2) {
+        return
+      }
+
+      abortController.value?.abort()
+      const controller = new AbortController()
+      abortController.value = controller
+
+      try {
+        const response = await connectorsAPI.searchInstitutions(
+          token,
+          connectorId,
+          term,
+          controller.signal
+        )
+
+        if (abortController.value !== controller || controller.signal.aborted) {
+          return
+        }
+
+        if (response.status === 200) {
+          searchResults.value = response.data as InstitutionsData
+        } else {
+          handleError((response.data as ErrorData).message || 'Failed to fetch institutions')
+        }
+      } catch (error: any) {
+        if (abortController.value === controller && !controller.signal.aborted) {
+          handleError(error?.message)
+        }
+      } finally {
+        if (abortController.value === controller && !controller.signal.aborted) {
+          isSearching.value = false
+        }
+      }
+    },
+    { immediate: false }
+  )
+
+  onUnmounted(() => {
+    if (debounceTimer.value) {
+      clearTimeout(debounceTimer.value)
+    }
+    abortController.value?.abort()
+  })
+
+  return {
+    searchTerm: computed(() => searchTerm.value),
+    searchResults: computed(() => searchResults.value),
+    isSearching: computed(() => isSearching.value),
+    setSearchTerm,
+  }
+}

package/src/composables/useQuilttResolvable.ts

@@ -0,0 +1,94 @@
+import { computed, ref } from 'vue'
+
+import type { ErrorData, ResolvableData } from '@quiltt/core'
+import { ConnectorsAPI } from '@quiltt/core'
+import { extractVersionNumber } from '@quiltt/core/utils'
+
+import { getSDKAgent } from '../utils'
+import { version } from '../version'
+import { useQuilttSession } from './useQuilttSession'
+
+type ProviderId = {
+  plaid?: string
+  mock?: string
+  mx?: string
+  finicity?: string
+  akoya?: string
+}
+
+/**
+ * Check whether a provider link is resolvable for a connector.
+ * Requires QuilttPlugin session context and throws when used without it.
+ */
+export const useQuilttResolvable = (
+  connectorId: string,
+  onErrorCallback?: (msg: string) => void
+) => {
+  const { session } = useQuilttSession()
+  const sdkVersion = extractVersionNumber(version)
+  const connectorsAPI = new ConnectorsAPI(connectorId, getSDKAgent(sdkVersion))
+
+  const isLoading = ref(false)
+  const isResolvable = ref<boolean | null>(null)
+  const error = ref<string | null>(null)
+
+  const handleError = (message: string) => {
+    const errorMessage = message || 'Unknown error occurred while checking resolvability'
+
+    error.value = errorMessage
+    console.error('Quiltt Connector Resolvable Error:', errorMessage)
+    onErrorCallback?.(errorMessage)
+  }
+
+  const checkResolvable = async (providerId: ProviderId): Promise<boolean | null> => {
+    if (!session.value?.token) {
+      handleError('Missing session token')
+      return null
+    }
+
+    if (!connectorId) {
+      handleError('Missing connector ID')
+      return null
+    }
+
+    const hasProviderId = Object.values(providerId).some((id) => !!id)
+    if (!hasProviderId) {
+      handleError('No provider ID specified')
+      return null
+    }
+
+    isLoading.value = true
+    error.value = null
+
+    try {
+      const response = await connectorsAPI.checkResolvable(
+        session.value.token,
+        connectorId,
+        providerId
+      )
+
+      if (response.status === 200) {
+        const result = (response.data as ResolvableData).resolvable
+        isResolvable.value = result
+        return result
+      }
+
+      handleError((response.data as ErrorData).message || 'Failed to check resolvability')
+      isResolvable.value = null
+      return null
+    } catch (caught: any) {
+      handleError(caught?.message)
+      isResolvable.value = null
+      return null
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  return {
+    checkResolvable,
+    isLoading: computed(() => isLoading.value),
+    isResolvable: computed(() => isResolvable.value),
+    error: computed(() => error.value),
+  }
+}

package/src/composables/useQuilttSession.ts

@@ -0,0 +1,239 @@
+/**
+ * Quiltt Session Composable
+ *
+ * Provides session management functionality for Vue 3 applications.
+ * Must be used within a component tree where QuilttPlugin is installed.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useQuilttSession } from '@quiltt/vue'
+ *
+ * const { session, importSession, revokeSession } = useQuilttSession()
+ *
+ * // Import a session token
+ * await importSession('<SESSION_TOKEN>')
+ *
+ * // Access session data
+ * console.log(session.value?.token)
+ *
+ * // Revoke the session
+ * await revokeSession()
+ * </script>
+ * ```
+ */
+
+import { type ComputedRef, computed, inject } from 'vue'
+
+import type {
+  Maybe,
+  PasscodePayload,
+  PrivateClaims,
+  QuilttJWT,
+  SessionResponse,
+  UnprocessableData,
+  UnprocessableResponse,
+  UsernamePayload,
+} from '@quiltt/core'
+import { AuthAPI, JsonWebTokenParse } from '@quiltt/core'
+
+import { QuilttClientIdKey, QuilttSessionKey, QuilttSetSessionKey } from '../plugin/keys'
+
+// Initialize JWT parser
+const parse = JsonWebTokenParse<PrivateClaims>
+
+/**
+ * Callbacks for identify session operation
+ */
+export interface IdentifySessionCallbacks {
+  onSuccess?: () => unknown
+  onChallenged?: () => unknown
+  onError?: (errors: UnprocessableData) => unknown
+  onForbidden?: () => unknown
+}
+
+/**
+ * Callbacks for authenticate session operation
+ */
+export interface AuthenticateSessionCallbacks {
+  onSuccess?: () => unknown
+  onFailure?: () => unknown
+  onError?: (errors: UnprocessableData) => unknown
+}
+
+export type ImportSession = (token: string, environmentId?: string) => Promise<boolean>
+export type IdentifySession = (
+  payload: UsernamePayload,
+  callbacks: IdentifySessionCallbacks
+) => Promise<unknown>
+export type AuthenticateSession = (
+  payload: PasscodePayload,
+  callbacks: AuthenticateSessionCallbacks
+) => Promise<unknown>
+export type RevokeSession = () => Promise<void>
+export type ForgetSession = (token?: string) => void
+
+export interface UseQuilttSessionReturn {
+  /** Current session (reactive) */
+  session: ComputedRef<Maybe<QuilttJWT> | undefined>
+  /** Import an existing session token */
+  importSession: ImportSession
+  /** Start authentication flow with username/email/phone */
+  identifySession: IdentifySession
+  /** Complete authentication with passcode */
+  authenticateSession: AuthenticateSession
+  /** Revoke the current session (invalidates token on server) */
+  revokeSession: RevokeSession
+  /** Forget the current session locally (without server call) */
+  forgetSession: ForgetSession
+}
+
+/**
+ * Composable for managing Quiltt session state
+ *
+ * Provides methods for importing, creating, and revoking sessions.
+ * Session state is automatically synchronized across components.
+ * Requires QuilttPlugin provider context and throws when used without it.
+ */
+export const useQuilttSession = (): UseQuilttSessionReturn => {
+  const sessionRef = inject(QuilttSessionKey)
+  const setSession = inject(QuilttSetSessionKey)
+  const clientIdRef = inject(QuilttClientIdKey)
+
+  if (!sessionRef || !setSession) {
+    throw new Error(
+      '[Quiltt] useQuilttSession must be used within a component where QuilttPlugin is installed. ' +
+        'Make sure to call app.use(QuilttPlugin) before mounting your app.'
+    )
+  }
+
+  // Create a computed ref for the session
+  const session = computed(() => sessionRef.value)
+
+  // Create AuthAPI instance (memoized based on clientId)
+  const getAuth = () => new AuthAPI(clientIdRef?.value)
+
+  /**
+   * Import an existing session token
+   * Validates the token and sets it as the current session
+   */
+  const importSession: ImportSession = async (token, environmentId) => {
+    const auth = getAuth()
+
+    // Is there a token?
+    if (!token) return !!sessionRef.value
+
+    // Is this token already imported?
+    if (sessionRef.value && sessionRef.value.token === token) return true
+
+    const jwt = parse(token)
+
+    // Is this token a valid JWT?
+    if (!jwt) return false
+
+    // Is this token within the expected environment?
+    if (environmentId && jwt.claims.eid !== environmentId) return false
+
+    // Is this token active?
+    const response = await auth.ping(token)
+    switch (response.status) {
+      case 200:
+        setSession(token)
+        return true
+
+      case 401:
+        return false
+
+      default:
+        throw new Error(`AuthAPI.ping: Unexpected response status ${response.status}`)
+    }
+  }
+
+  /**
+   * Start authentication flow with username/email/phone
+   * Returns a session token or challenges for passcode
+   */
+  const identifySession: IdentifySession = async (payload, callbacks) => {
+    const auth = getAuth()
+    const response = await auth.identify(payload)
+
+    switch (response.status) {
+      case 201: // Created
+        setSession((response as SessionResponse).data.token)
+        if (callbacks.onSuccess) return callbacks.onSuccess()
+        break
+
+      case 202: // Accepted (needs passcode)
+        if (callbacks.onChallenged) return callbacks.onChallenged()
+        break
+
+      case 403: // Forbidden (signups disabled)
+        if (callbacks.onForbidden) return callbacks.onForbidden()
+        break
+
+      case 422: // Unprocessable Content
+        if (callbacks.onError) return callbacks.onError((response as UnprocessableResponse).data)
+        break
+
+      default:
+        throw new Error(`AuthAPI.identify: Unexpected response status ${response.status}`)
+    }
+  }
+
+  /**
+   * Complete authentication with passcode
+   */
+  const authenticateSession: AuthenticateSession = async (payload, callbacks) => {
+    const auth = getAuth()
+    const response = await auth.authenticate(payload)
+
+    switch (response.status) {
+      case 201:
+        setSession((response as SessionResponse).data.token)
+        if (callbacks.onSuccess) return callbacks.onSuccess()
+        break
+
+      case 401:
+        if (callbacks.onFailure) return callbacks.onFailure()
+        break
+
+      case 422:
+        if (callbacks.onError) return callbacks.onError((response as UnprocessableResponse).data)
+        break
+
+      default:
+        throw new Error(`AuthAPI.authenticate: Unexpected response status ${response.status}`)
+    }
+  }
+
+  /**
+   * Revoke the current session
+   * Invalidates the token on the server and clears local state
+   */
+  const revokeSession: RevokeSession = async () => {
+    if (!sessionRef.value) return
+
+    const auth = getAuth()
+    await auth.revoke(sessionRef.value.token)
+    setSession(null)
+  }
+
+  /**
+   * Forget the current session locally without server call
+   * Optionally pass a specific token to guard against async processes clearing wrong session
+   */
+  const forgetSession: ForgetSession = (token) => {
+    if (!token || (sessionRef.value && token === sessionRef.value.token)) {
+      setSession(null)
+    }
+  }
+
+  return {
+    session,
+    importSession,
+    identifySession,
+    authenticateSession,
+    revokeSession,
+    forgetSession,
+  }
+}

package/src/composables/useQuilttSettings.ts

@@ -0,0 +1,15 @@
+import { computed, inject } from 'vue'
+
+import { QuilttClientIdKey } from '../plugin/keys'
+
+/**
+ * Read plugin-provided Quiltt settings.
+ * When used without QuilttPlugin context, values are undefined.
+ */
+export const useQuilttSettings = () => {
+  const clientIdRef = inject(QuilttClientIdKey)
+
+  return {
+    clientId: computed(() => clientIdRef?.value),
+  }
+}

package/src/composables/useSession.ts

@@ -0,0 +1,74 @@
+import { computed, onUnmounted, ref, watch } from 'vue'
+
+import type { Maybe, PrivateClaims, QuilttJWT } from '@quiltt/core'
+import { JsonWebTokenParse, Timeoutable } from '@quiltt/core'
+
+import { useStorage } from './useStorage'
+
+const parse = JsonWebTokenParse<PrivateClaims>
+const sessionTimer = new Timeoutable()
+
+export const useSession = (storageKey = 'session') => {
+  const { storage: token, setStorage } = useStorage<string>(storageKey)
+  const session = ref<Maybe<QuilttJWT> | undefined>(parse(token.value))
+  let currentExpire: (() => void) | null = null
+
+  watch(
+    token,
+    (newToken) => {
+      session.value = parse(newToken)
+    },
+    { immediate: true }
+  )
+
+  watch(
+    () => session.value,
+    (nextSession) => {
+      if (currentExpire) {
+        sessionTimer.clear(currentExpire)
+        currentExpire = null
+      }
+
+      if (!nextSession) {
+        return
+      }
+
+      const expirationMS = nextSession.claims.exp * 1000
+      const expire = () => setStorage(null)
+      currentExpire = expire
+
+      if (Date.now() >= expirationMS) {
+        expire()
+        return
+      }
+
+      sessionTimer.set(expire, expirationMS - Date.now())
+    },
+    { immediate: true }
+  )
+
+  const setSession = (
+    nextState:
+      | Maybe<string>
+      | undefined
+      | ((prev: Maybe<string> | undefined) => Maybe<string> | undefined)
+  ) => {
+    const resolved = nextState instanceof Function ? nextState(token.value) : nextState
+
+    if (token.value !== resolved && (!resolved || parse(resolved))) {
+      setStorage(resolved)
+    }
+  }
+
+  onUnmounted(() => {
+    if (currentExpire) {
+      sessionTimer.clear(currentExpire)
+      currentExpire = null
+    }
+  })
+
+  return {
+    session: computed(() => session.value),
+    setSession,
+  }
+}

package/src/composables/useStorage.ts

@@ -0,0 +1,47 @@
+import { computed, getCurrentScope, onScopeDispose, ref } from 'vue'
+
+import type { Maybe } from '@quiltt/core'
+import { GlobalStorage } from '@quiltt/core'
+
+export const useStorage = <T>(key: string, initialState?: Maybe<T>) => {
+  const readStorage = () => {
+    const current = GlobalStorage.get(key)
+    if (current !== undefined) {
+      return current as Maybe<T>
+    }
+
+    return initialState
+  }
+
+  const state = ref<Maybe<T> | undefined>(readStorage())
+
+  const setStorage = (
+    nextState: Maybe<T> | undefined | ((prev: Maybe<T> | undefined) => Maybe<T> | undefined)
+  ) => {
+    const resolved = nextState instanceof Function ? nextState(state.value) : nextState
+
+    if (state.value !== resolved) {
+      GlobalStorage.set(key, resolved)
+      state.value = resolved
+    }
+  }
+
+  const handleStorageChange = (newValue: Maybe<T> | undefined) => {
+    state.value = newValue
+  }
+
+  GlobalStorage.subscribe(key, handleStorageChange)
+
+  // Use onScopeDispose for cleanup in any effect scope (components, effectScope(), etc.)
+  // This safely handles cases where composable is called outside a scope
+  if (getCurrentScope()) {
+    onScopeDispose(() => {
+      GlobalStorage.unsubscribe(key, handleStorageChange)
+    })
+  }
+
+  return {
+    storage: computed(() => state.value),
+    setStorage,
+  }
+}

package/src/constants/deprecation-warnings.ts

@@ -0,0 +1,2 @@
+export const oauthRedirectUrlDeprecationWarning =
+  '[Quiltt] `oauthRedirectUrl` is deprecated. Use `appLauncherUrl` instead. `oauthRedirectUrl` will be removed in the next major release.'

package/src/index.ts

@@ -0,0 +1,34 @@
+// ============================================================================
+// @quiltt/vue - Vue 3 Composables and Components for Quiltt
+// ============================================================================
+// This package provides Vue 3-specific composables and components for
+// integrating Quiltt's financial data platform into Vue applications.
+// It re-exports all @quiltt/core functionality plus Vue-specific features.
+//
+// Main exports:
+// - All @quiltt/core modules (API clients, auth, config, storage, types)
+// - Vue plugin (QuilttPlugin) for app-wide session management
+// - Vue composables (useQuilttSession, useQuilttConnector)
+// - Vue components (QuilttConnector, QuilttButton, QuilttContainer)
+// ============================================================================
+
+// ============================================================================
+// Quiltt Core - Re-export all modules from @quiltt/core
+// ============================================================================
+// Re-export all core Quiltt functionality so users only need to install
+// @quiltt/vue instead of both @quiltt/core and @quiltt/vue.
+export * from '@quiltt/core/api'
+export * from '@quiltt/core/auth'
+export * from '@quiltt/core/config'
+export * from '@quiltt/core/observables'
+export * from '@quiltt/core/storage'
+export * from '@quiltt/core/timing'
+export * from '@quiltt/core/types'
+
+// ============================================================================
+// Vue-specific exports
+// ============================================================================
+// Quiltt Vue plugin, composables, and components for Vue 3 applications.
+export * from './components'
+export * from './composables'
+export * from './plugin'