@quiltt/vue 5.1.2

package/dist/index.js

@@ -0,0 +1,10 @@
+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';
+export * from './components/index.js';
+export * from './composables/index.js';
+export * from './plugin/index.js';

package/dist/plugin/index.cjs

@@ -0,0 +1,176 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var vue = require('vue');
+var core = require('@quiltt/core');
+
+/**
+ * Injection keys and types for Quiltt Vue plugin
+ */ // Injection keys for Quiltt state
+const QuilttSessionKey = Symbol.for('quiltt-session');
+const QuilttSetSessionKey = Symbol.for('quiltt-set-session');
+const QuilttClientIdKey = Symbol.for('quiltt-client-id');
+
+// Initialize JWT parser with our specific claims type
+const parse = core.JsonWebTokenParse;
+// Storage key for session persistence
+const STORAGE_KEY = 'quiltt:session';
+/**
+ * Get stored token from localStorage (browser only)
+ */ const getStoredToken = ()=>{
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return null;
+    }
+    try {
+        return localStorage.getItem(STORAGE_KEY);
+    } catch  {
+        return null;
+    }
+};
+/**
+ * Store token in localStorage (browser only)
+ */ const setStoredToken = (token)=>{
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return;
+    }
+    try {
+        if (token) {
+            localStorage.setItem(STORAGE_KEY, token);
+        } else {
+            localStorage.removeItem(STORAGE_KEY);
+        }
+    } catch  {
+    // Storage not available
+    }
+};
+/**
+ * Quiltt Vue Plugin
+ *
+ * Provides session management across your Vue application.
+ * Use with `app.use(QuilttPlugin, options)`.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'vue'
+ * import { QuilttPlugin } from '@quiltt/vue'
+ *
+ * const app = createApp(App)
+ * app.use(QuilttPlugin, { token: '<SESSION_TOKEN>' })
+ * app.mount('#app')
+ * ```
+ */ const QuilttPlugin = {
+    install (app, options) {
+        // Instance-scoped timeout for session expiration
+        let sessionTimeout;
+        let isCleanedUp = false;
+        let stopSessionWatcher;
+        /**
+     * Clear the session timeout for this app instance
+     */ const clearSessionTimeout = ()=>{
+            if (sessionTimeout) {
+                clearTimeout(sessionTimeout);
+                sessionTimeout = undefined;
+            }
+        };
+        // Initialize with provided token or stored token
+        const initialToken = options?.token ?? getStoredToken();
+        const initialSession = parse(initialToken);
+        // Reactive session state
+        const session = vue.ref(initialSession);
+        const clientId = vue.ref(options?.clientId);
+        /**
+     * Set session token
+     * Parses token, updates storage, and sets expiration timer
+     */ const setSession = (token)=>{
+            const parsed = parse(token);
+            session.value = parsed;
+            setStoredToken(token ?? null);
+            // Clear any existing expiration timer
+            clearSessionTimeout();
+            // Set new expiration timer if session is valid
+            if (parsed) {
+                const expirationMS = parsed.claims.exp * 1000;
+                const timeUntilExpiry = expirationMS - Date.now();
+                if (timeUntilExpiry > 0) {
+                    sessionTimeout = setTimeout(()=>{
+                        session.value = null;
+                        setStoredToken(null);
+                    }, timeUntilExpiry);
+                } else {
+                    // Token already expired
+                    session.value = null;
+                    setStoredToken(null);
+                }
+            }
+        };
+        // Storage event handler for cross-tab synchronization
+        let storageHandler;
+        // Listen for storage changes from other tabs/windows
+        if (typeof window !== 'undefined') {
+            storageHandler = (event)=>{
+                if (event.key === STORAGE_KEY) {
+                    const newSession = parse(event.newValue);
+                    session.value = newSession;
+                }
+            };
+            window.addEventListener('storage', storageHandler);
+        }
+        // Cleanup function for when the app is unmounted
+        const cleanup = ()=>{
+            if (isCleanedUp) {
+                return;
+            }
+            isCleanedUp = true;
+            clearSessionTimeout();
+            if (stopSessionWatcher) {
+                stopSessionWatcher();
+                stopSessionWatcher = undefined;
+            }
+            if (typeof window !== 'undefined' && storageHandler) {
+                window.removeEventListener('storage', storageHandler);
+                storageHandler = undefined;
+            }
+        };
+        // Register cleanup on app unmount (Vue 3.5+)
+        if (typeof app.onUnmount === 'function') {
+            app.onUnmount(cleanup);
+        }
+        // Ensure cleanup runs on all supported Vue versions (3.3+)
+        if (typeof app.unmount === 'function') {
+            const originalUnmount = app.unmount.bind(app);
+            app.unmount = (...args)=>{
+                cleanup();
+                return originalUnmount(...args);
+            };
+        }
+        // Watch for session changes to update expiration timer
+        stopSessionWatcher = vue.watch(()=>session.value, (newSession)=>{
+            if (!newSession) {
+                clearSessionTimeout();
+                return;
+            }
+            const expirationMS = newSession.claims.exp * 1000;
+            const timeUntilExpiry = expirationMS - Date.now();
+            if (timeUntilExpiry <= 0) {
+                session.value = null;
+                setStoredToken(null);
+                return;
+            }
+            clearSessionTimeout();
+            sessionTimeout = setTimeout(()=>{
+                session.value = null;
+                setStoredToken(null);
+            }, timeUntilExpiry);
+        }, {
+            immediate: true
+        });
+        // Provide session state to all components
+        app.provide(QuilttSessionKey, session);
+        app.provide(QuilttSetSessionKey, setSession);
+        app.provide(QuilttClientIdKey, clientId);
+    }
+};
+
+exports.QuilttClientIdKey = QuilttClientIdKey;
+exports.QuilttPlugin = QuilttPlugin;
+exports.QuilttSessionKey = QuilttSessionKey;
+exports.QuilttSetSessionKey = QuilttSetSessionKey;

package/dist/plugin/index.d.ts

@@ -0,0 +1,48 @@
+import { InjectionKey, Ref, Plugin } from 'vue';
+import { Maybe, QuilttJWT } from '@quiltt/core';
+
+/**
+ * Injection keys and types for Quiltt Vue plugin
+ */
+
+declare const QuilttSessionKey: InjectionKey<Ref<Maybe<QuilttJWT> | undefined>>;
+declare const QuilttSetSessionKey: InjectionKey<(token: Maybe<string>) => void>;
+declare const QuilttClientIdKey: InjectionKey<Ref<string | undefined>>;
+interface QuilttPluginOptions {
+    /**
+     * Initial session token
+     */
+    token?: string;
+    /**
+     * Quiltt Client ID (Environment ID)
+     */
+    clientId?: string;
+}
+
+/**
+ * Quiltt Vue Plugin implementation
+ *
+ * Provides session state management via Vue's provide/inject system.
+ * Handles token parsing, storage synchronization, and automatic expiration.
+ */
+
+/**
+ * Quiltt Vue Plugin
+ *
+ * Provides session management across your Vue application.
+ * Use with `app.use(QuilttPlugin, options)`.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'vue'
+ * import { QuilttPlugin } from '@quiltt/vue'
+ *
+ * const app = createApp(App)
+ * app.use(QuilttPlugin, { token: '<SESSION_TOKEN>' })
+ * app.mount('#app')
+ * ```
+ */
+declare const QuilttPlugin: Plugin<[QuilttPluginOptions?]>;
+
+export { QuilttClientIdKey, QuilttPlugin, QuilttSessionKey, QuilttSetSessionKey };
+export type { QuilttPluginOptions };

package/dist/plugin/index.js

@@ -0,0 +1,171 @@
+import { ref, watch } from 'vue';
+import { JsonWebTokenParse } from '@quiltt/core';
+
+/**
+ * Injection keys and types for Quiltt Vue plugin
+ */ // Injection keys for Quiltt state
+const QuilttSessionKey = Symbol.for('quiltt-session');
+const QuilttSetSessionKey = Symbol.for('quiltt-set-session');
+const QuilttClientIdKey = Symbol.for('quiltt-client-id');
+
+// Initialize JWT parser with our specific claims type
+const parse = JsonWebTokenParse;
+// Storage key for session persistence
+const STORAGE_KEY = 'quiltt:session';
+/**
+ * Get stored token from localStorage (browser only)
+ */ const getStoredToken = ()=>{
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return null;
+    }
+    try {
+        return localStorage.getItem(STORAGE_KEY);
+    } catch  {
+        return null;
+    }
+};
+/**
+ * Store token in localStorage (browser only)
+ */ const setStoredToken = (token)=>{
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return;
+    }
+    try {
+        if (token) {
+            localStorage.setItem(STORAGE_KEY, token);
+        } else {
+            localStorage.removeItem(STORAGE_KEY);
+        }
+    } catch  {
+    // Storage not available
+    }
+};
+/**
+ * Quiltt Vue Plugin
+ *
+ * Provides session management across your Vue application.
+ * Use with `app.use(QuilttPlugin, options)`.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'vue'
+ * import { QuilttPlugin } from '@quiltt/vue'
+ *
+ * const app = createApp(App)
+ * app.use(QuilttPlugin, { token: '<SESSION_TOKEN>' })
+ * app.mount('#app')
+ * ```
+ */ const QuilttPlugin = {
+    install (app, options) {
+        // Instance-scoped timeout for session expiration
+        let sessionTimeout;
+        let isCleanedUp = false;
+        let stopSessionWatcher;
+        /**
+     * Clear the session timeout for this app instance
+     */ const clearSessionTimeout = ()=>{
+            if (sessionTimeout) {
+                clearTimeout(sessionTimeout);
+                sessionTimeout = undefined;
+            }
+        };
+        // Initialize with provided token or stored token
+        const initialToken = options?.token ?? getStoredToken();
+        const initialSession = parse(initialToken);
+        // Reactive session state
+        const session = ref(initialSession);
+        const clientId = ref(options?.clientId);
+        /**
+     * Set session token
+     * Parses token, updates storage, and sets expiration timer
+     */ const setSession = (token)=>{
+            const parsed = parse(token);
+            session.value = parsed;
+            setStoredToken(token ?? null);
+            // Clear any existing expiration timer
+            clearSessionTimeout();
+            // Set new expiration timer if session is valid
+            if (parsed) {
+                const expirationMS = parsed.claims.exp * 1000;
+                const timeUntilExpiry = expirationMS - Date.now();
+                if (timeUntilExpiry > 0) {
+                    sessionTimeout = setTimeout(()=>{
+                        session.value = null;
+                        setStoredToken(null);
+                    }, timeUntilExpiry);
+                } else {
+                    // Token already expired
+                    session.value = null;
+                    setStoredToken(null);
+                }
+            }
+        };
+        // Storage event handler for cross-tab synchronization
+        let storageHandler;
+        // Listen for storage changes from other tabs/windows
+        if (typeof window !== 'undefined') {
+            storageHandler = (event)=>{
+                if (event.key === STORAGE_KEY) {
+                    const newSession = parse(event.newValue);
+                    session.value = newSession;
+                }
+            };
+            window.addEventListener('storage', storageHandler);
+        }
+        // Cleanup function for when the app is unmounted
+        const cleanup = ()=>{
+            if (isCleanedUp) {
+                return;
+            }
+            isCleanedUp = true;
+            clearSessionTimeout();
+            if (stopSessionWatcher) {
+                stopSessionWatcher();
+                stopSessionWatcher = undefined;
+            }
+            if (typeof window !== 'undefined' && storageHandler) {
+                window.removeEventListener('storage', storageHandler);
+                storageHandler = undefined;
+            }
+        };
+        // Register cleanup on app unmount (Vue 3.5+)
+        if (typeof app.onUnmount === 'function') {
+            app.onUnmount(cleanup);
+        }
+        // Ensure cleanup runs on all supported Vue versions (3.3+)
+        if (typeof app.unmount === 'function') {
+            const originalUnmount = app.unmount.bind(app);
+            app.unmount = (...args)=>{
+                cleanup();
+                return originalUnmount(...args);
+            };
+        }
+        // Watch for session changes to update expiration timer
+        stopSessionWatcher = watch(()=>session.value, (newSession)=>{
+            if (!newSession) {
+                clearSessionTimeout();
+                return;
+            }
+            const expirationMS = newSession.claims.exp * 1000;
+            const timeUntilExpiry = expirationMS - Date.now();
+            if (timeUntilExpiry <= 0) {
+                session.value = null;
+                setStoredToken(null);
+                return;
+            }
+            clearSessionTimeout();
+            sessionTimeout = setTimeout(()=>{
+                session.value = null;
+                setStoredToken(null);
+            }, timeUntilExpiry);
+        }, {
+            immediate: true
+        });
+        // Provide session state to all components
+        app.provide(QuilttSessionKey, session);
+        app.provide(QuilttSetSessionKey, setSession);
+        app.provide(QuilttClientIdKey, clientId);
+    }
+};
+
+export { QuilttClientIdKey, QuilttPlugin, QuilttSessionKey, QuilttSetSessionKey };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@quiltt/vue",
+  "version": "5.1.2",
+  "description": "Vue 3 Composables and Components for Quiltt Connector",
+  "keywords": [
+    "quiltt",
+    "quiltt-connector",
+    "vue",
+    "vue3",
+    "typescript"
+  ],
+  "homepage": "https://github.com/quiltt/quiltt-js/tree/main/packages/vue#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quiltt/quiltt-js.git",
+    "directory": "packages/vue"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/quiltt/quiltt-js/issues"
+  },
+  "sideEffects": [],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./composables": {
+      "types": "./dist/composables/index.d.ts",
+      "require": "./dist/composables/index.cjs",
+      "import": "./dist/composables/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "require": "./dist/components/index.cjs",
+      "import": "./dist/components/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "require": "./dist/plugin/index.cjs",
+      "import": "./dist/plugin/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "src/**",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/index.js",
+  "dependencies": {
+    "@quiltt/core": "5.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.3",
+    "@types/node": "24.11.0",
+    "bunchee": "6.9.4",
+    "rimraf": "6.1.3",
+    "typescript": "5.9.3",
+    "vue": "3.5.28"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "tags": [
+    "quiltt",
+    "vue"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bunchee",
+    "clean": "rimraf .turbo dist",
+    "dev": "bunchee --watch",
+    "lint": "TIMING=1 biome check src/ tests/ --fix",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}

package/src/components/QuilttButton.ts

@@ -0,0 +1,121 @@
+/**
+ * QuilttButton - Button component that opens Quiltt Connector modal
+ *
+ * Wraps a button (or custom element) that opens the Quiltt Connector
+ * in a modal overlay when clicked.
+ *
+ * @example
+ * ```vue
+ * <QuilttButton
+ *   :connector-id="connectorId"
+ *   @exit-success="handleSuccess"
+ * >
+ *   Add Bank Account
+ * </QuilttButton>
+ * ```
+ */
+
+import { computed, defineComponent, h, 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 QuilttButton = defineComponent({
+  name: 'QuilttButton',
+
+  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: 'button',
+    },
+  },
+
+  emits: {
+    /** Connector loaded */
+    load: (_metadata: ConnectorSDKCallbackMetadata) => true,
+    /** Connector opened */
+    open: (_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)
+
+    const { open } = useQuilttConnector(() => props.connectorId, {
+      connectionId: () => props.connectionId,
+      institution: () => props.institution,
+      appLauncherUrl: effectiveAppLauncherUri,
+      onEvent: (type, metadata) => emit('event', type, metadata),
+      onOpen: (metadata) => emit('open', 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),
+    })
+
+    const handleClick = () => {
+      open()
+    }
+
+    return () =>
+      h(
+        props.as,
+        {
+          class: 'quiltt-button',
+          onClick: handleClick,
+        },
+        slots.default?.()
+      )
+  },
+})