@quiltt/core 5.0.3 → 5.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @quiltt/core
 
+## 5.1.1
+
+### Patch Changes
+
+- [#419](https://github.com/quiltt/quiltt-js/pull/419) [`5f5846a`](https://github.com/quiltt/quiltt-js/commit/5f5846a1d807f517c156bbebe60d639256a7db1e) Thanks [@rubendinho](https://github.com/rubendinho)! - Update telemetry headers
+
+- [#421](https://github.com/quiltt/quiltt-js/pull/421) [`0756cb5`](https://github.com/quiltt/quiltt-js/commit/0756cb59d3fb55208cc2d1bdc10a2a8d5b66b595) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Ensure custom Headers are passed to all API calls
+
+## 5.1.0
+
+### Minor Changes
+
+- [#406](https://github.com/quiltt/quiltt-js/pull/406) [`177a4fc`](https://github.com/quiltt/quiltt-js/commit/177a4fc3d70fa3f313f6586396719dae9763cf4b) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Add OAuth redirect URL support to React SDK
+
+### Patch Changes
+
+- [#418](https://github.com/quiltt/quiltt-js/pull/418) [`2d918a0`](https://github.com/quiltt/quiltt-js/commit/2d918a089f8546bb7d20db1eefd958beca296ee0) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Internal: Add `headers` prop to QuilttProvider
+
+  For Quiltt internal usage. Not intended for public use.
+
 ## 5.0.3
 
 ### Patch Changes

package/dist/api/browser.d.ts

@@ -101,6 +101,8 @@ type ConnectorSDKCallbackMetadata = {
 type ConnectorSDKConnectOptions = ConnectorSDKCallbacks & {
     /** The Institution ID or search term to connect */
     institution?: string;
+    /** The OAuth redirect URL for mobile or embedded webview flows */
+    oauthRedirectUrl?: string;
 };
 /**
  * Options for the Reconnect flow
@@ -109,6 +111,8 @@ type ConnectorSDKConnectOptions = ConnectorSDKCallbacks & {
 type ConnectorSDKReconnectOptions = ConnectorSDKCallbacks & {
     /** The ID of the Connection to reconnect */
     connectionId: string;
+    /** The OAuth redirect URL for mobile or embedded webview flows */
+    oauthRedirectUrl?: string;
 };
 /** Options to initialize Connector
  *
@@ -122,6 +126,8 @@ type ConnectorSDKConnectorOptions = ConnectorSDKCallbacks & {
     connectionId?: string;
     /** The nonce to use for the script tag */
     nonce?: string;
+    /** The OAuth redirect URL for mobile or embedded webview flows */
+    oauthRedirectUrl?: string;
 };
 
 export { ConnectorSDKEventType };

package/dist/api/graphql/{SubscriptionLink-12s-wjkChfxO.cjs → SubscriptionLink-12s-DUvHs5WL.cjs}

@@ -99,6 +99,7 @@ class ActionCableLink extends core.ApolloLink {
             this.cables[token] = actioncable.createConsumer(index_cjs$1.endpointWebsockets + (token ? `?token=${token}` : ''));
         }
         return new rxjs.Observable((observer)=>{
+            let cancelled = false;
             const channelId = Math.round(Date.now() + Math.random() * 100000).toString(16);
             const actionName = this.actionName;
             const connectionParams = typeof this.connectionParams === 'function' ? this.connectionParams(operation) : this.connectionParams;
@@ -108,6 +109,7 @@ class ActionCableLink extends core.ApolloLink {
                 channelId: channelId
             }, connectionParams), {
                 connected: (args)=>{
+                    if (cancelled) return;
                     channel.perform(actionName, {
                         query: operation.query ? graphql.print(operation.query) : null,
                         variables: operation.variables,
@@ -118,6 +120,7 @@ class ActionCableLink extends core.ApolloLink {
                     callbacks.connected?.(args);
                 },
                 received: (payload)=>{
+                    if (cancelled) return;
                     if (payload?.result?.data || payload?.result?.errors) {
                         observer.next(payload.result);
                     }
@@ -126,14 +129,18 @@ class ActionCableLink extends core.ApolloLink {
                     }
                     callbacks.received?.(payload);
                 },
+                // Intentionally not guarded by `cancelled` - disconnected represents
+                // the WebSocket connection state which users may want to know about
+                // for cleanup/status purposes, even after the observable completes.
                 disconnected: ()=>{
                     callbacks.disconnected?.();
                 }
             });
-            // Make the ActionCable subscription behave like an Apollo subscription
-            return Object.assign(channel, {
-                closed: false
-            });
+            // Return teardown logic
+            return ()=>{
+                cancelled = true;
+                channel.unsubscribe();
+            };
         });
     }
 }

package/dist/api/graphql/{SubscriptionLink-12s-ufJBKwu1.js → SubscriptionLink-12s-UDBUsy8w.js}

@@ -99,6 +99,7 @@ class ActionCableLink extends ApolloLink {
             this.cables[token] = createConsumer(endpointWebsockets + (token ? `?token=${token}` : ''));
         }
         return new Observable((observer)=>{
+            let cancelled = false;
             const channelId = Math.round(Date.now() + Math.random() * 100000).toString(16);
             const actionName = this.actionName;
             const connectionParams = typeof this.connectionParams === 'function' ? this.connectionParams(operation) : this.connectionParams;
@@ -108,6 +109,7 @@ class ActionCableLink extends ApolloLink {
                 channelId: channelId
             }, connectionParams), {
                 connected: (args)=>{
+                    if (cancelled) return;
                     channel.perform(actionName, {
                         query: operation.query ? print(operation.query) : null,
                         variables: operation.variables,
@@ -118,6 +120,7 @@ class ActionCableLink extends ApolloLink {
                     callbacks.connected?.(args);
                 },
                 received: (payload)=>{
+                    if (cancelled) return;
                     if (payload?.result?.data || payload?.result?.errors) {
                         observer.next(payload.result);
                     }
@@ -126,14 +129,18 @@ class ActionCableLink extends ApolloLink {
                     }
                     callbacks.received?.(payload);
                 },
+                // Intentionally not guarded by `cancelled` - disconnected represents
+                // the WebSocket connection state which users may want to know about
+                // for cleanup/status purposes, even after the observable completes.
                 disconnected: ()=>{
                     callbacks.disconnected?.();
                 }
             });
-            // Make the ActionCable subscription behave like an Apollo subscription
-            return Object.assign(channel, {
-                closed: false
-            });
+            // Return teardown logic
+            return ()=>{
+                cancelled = true;
+                channel.unsubscribe();
+            };
         });
     }
 }

package/dist/api/graphql/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var core = require('@apollo/client/core');
 var index_cjs = require('../../config/index.cjs');
 var rxjs = require('rxjs');
-var SubscriptionLink12s = require('./SubscriptionLink-12s-wjkChfxO.cjs');
+var SubscriptionLink12s = require('./SubscriptionLink-12s-DUvHs5WL.cjs');
 var batchHttp = require('@apollo/client/link/batch-http');
 var crossfetch = require('cross-fetch');
 var error = require('@apollo/client/link/error');
@@ -88,6 +88,62 @@ const ErrorLink = new error.ErrorLink(({ error, result })=>{
 
 const ForwardableLink = new core.ApolloLink((operation, forward)=>forward(operation));
 
+/**
+ * Apollo Link that adds custom headers to GraphQL requests.
+ *
+ * Headers can be provided statically or dynamically via a function.
+ * These headers are added before the AuthLink, so they will be preserved
+ * alongside the authorization header.
+ */ class HeadersLink extends core.ApolloLink {
+    constructor(options = {}){
+        super();
+        this.headers = options.headers ?? {};
+        this.getHeaders = options.getHeaders;
+    }
+    request(operation, forward) {
+        // If we have a dynamic headers function, handle it
+        if (this.getHeaders) {
+            return new rxjs.Observable((observer)=>{
+                let innerSubscription;
+                let cancelled = false;
+                Promise.resolve(this.getHeaders()).then((dynamicHeaders)=>{
+                    // Guard against late resolution after unsubscribe
+                    if (cancelled) return;
+                    operation.setContext(({ headers = {} })=>({
+                            headers: {
+                                ...headers,
+                                ...this.headers,
+                                ...dynamicHeaders
+                            }
+                        }));
+                    innerSubscription = forward(operation).subscribe({
+                        next: (value)=>!cancelled && observer.next(value),
+                        error: (err)=>!cancelled && observer.error(err),
+                        complete: ()=>!cancelled && observer.complete()
+                    });
+                }).catch((error)=>{
+                    if (!cancelled) {
+                        observer.error(error);
+                    }
+                });
+                // Return teardown logic
+                return ()=>{
+                    cancelled = true;
+                    innerSubscription?.unsubscribe();
+                };
+            });
+        }
+        // Static headers only
+        operation.setContext(({ headers = {} })=>({
+                headers: {
+                    ...headers,
+                    ...this.headers
+                }
+            }));
+        return forward(operation);
+    }
+}
+
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch__default.default : fetch;
 const HttpLink = new http.HttpLink({
@@ -131,22 +187,21 @@ const TerminatingLink = new core.ApolloLink(()=>{
     return `${major}.${minor}.${patch}`;
 };
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
     return `Quiltt/${sdkVersion} (${platformInfo})`;
 };
 
 const createVersionLink = (platformInfo)=>{
     const versionNumber = extractVersionNumber(index_cjs.version);
-    const userAgent = getUserAgent(versionNumber, platformInfo);
+    const sdkAgent = getSDKAgent(versionNumber, platformInfo);
     return new core.ApolloLink((operation, forward)=>{
         operation.setContext(({ headers = {} })=>({
                 headers: {
                     ...headers,
                     'Quiltt-Client-Version': index_cjs.version,
-                    'Quiltt-SDK-Agent': userAgent,
-                    'User-Agent': userAgent
+                    'Quiltt-SDK-Agent': sdkAgent
                 }
             }));
         return forward(operation);
@@ -212,6 +267,7 @@ exports.AuthLink = AuthLink;
 exports.BatchHttpLink = BatchHttpLink;
 exports.ErrorLink = ErrorLink;
 exports.ForwardableLink = ForwardableLink;
+exports.HeadersLink = HeadersLink;
 exports.HttpLink = HttpLink;
 exports.QuilttClient = QuilttClient;
 exports.RetryLink = RetryLink;

package/dist/api/graphql/index.d.ts

@@ -38,6 +38,26 @@ declare const ErrorLink: ErrorLink$1;
 
 declare const ForwardableLink: ApolloLink;
 
+type HeadersLinkOptions = {
+    /** Static headers to add to every request */
+    headers?: Record<string, string>;
+    /** Dynamic headers function called on each request */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+};
+/**
+ * Apollo Link that adds custom headers to GraphQL requests.
+ *
+ * Headers can be provided statically or dynamically via a function.
+ * These headers are added before the AuthLink, so they will be preserved
+ * alongside the authorization header.
+ */
+declare class HeadersLink extends ApolloLink {
+    private headers;
+    private getHeaders?;
+    constructor(options?: HeadersLinkOptions);
+    request(operation: ApolloLink.Operation, forward: ApolloLink.ForwardFunction): Observable<ApolloLink.Result>;
+}
+
 declare const HttpLink: HttpLink$1;
 
 declare const RetryLink: RetryLink$1;
@@ -78,5 +98,5 @@ declare const TerminatingLink: ApolloLink;
 
 declare const createVersionLink: (platformInfo: string) => ApolloLink;
 
-export { AuthLink, BatchHttpLink, ErrorLink, ForwardableLink, HttpLink, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, createVersionLink };
-export type { QuilttClientOptions };
+export { AuthLink, BatchHttpLink, ErrorLink, ForwardableLink, HeadersLink, HttpLink, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, createVersionLink };
+export type { HeadersLinkOptions, QuilttClientOptions };

package/dist/api/graphql/index.js

@@ -2,7 +2,7 @@ import { ApolloLink, ApolloClient } from '@apollo/client/core';
 export { gql } from '@apollo/client/core';
 import { endpointGraphQL, version, debugging } from '../../config/index.js';
 import { Observable } from 'rxjs';
-import { v as validateSessionToken, S as SubscriptionLink } from './SubscriptionLink-12s-ufJBKwu1.js';
+import { v as validateSessionToken, S as SubscriptionLink } from './SubscriptionLink-12s-UDBUsy8w.js';
 import { BatchHttpLink as BatchHttpLink$1 } from '@apollo/client/link/batch-http';
 import crossfetch from 'cross-fetch';
 import { ErrorLink as ErrorLink$1 } from '@apollo/client/link/error';
@@ -83,6 +83,62 @@ const ErrorLink = new ErrorLink$1(({ error, result })=>{
 
 const ForwardableLink = new ApolloLink((operation, forward)=>forward(operation));
 
+/**
+ * Apollo Link that adds custom headers to GraphQL requests.
+ *
+ * Headers can be provided statically or dynamically via a function.
+ * These headers are added before the AuthLink, so they will be preserved
+ * alongside the authorization header.
+ */ class HeadersLink extends ApolloLink {
+    constructor(options = {}){
+        super();
+        this.headers = options.headers ?? {};
+        this.getHeaders = options.getHeaders;
+    }
+    request(operation, forward) {
+        // If we have a dynamic headers function, handle it
+        if (this.getHeaders) {
+            return new Observable((observer)=>{
+                let innerSubscription;
+                let cancelled = false;
+                Promise.resolve(this.getHeaders()).then((dynamicHeaders)=>{
+                    // Guard against late resolution after unsubscribe
+                    if (cancelled) return;
+                    operation.setContext(({ headers = {} })=>({
+                            headers: {
+                                ...headers,
+                                ...this.headers,
+                                ...dynamicHeaders
+                            }
+                        }));
+                    innerSubscription = forward(operation).subscribe({
+                        next: (value)=>!cancelled && observer.next(value),
+                        error: (err)=>!cancelled && observer.error(err),
+                        complete: ()=>!cancelled && observer.complete()
+                    });
+                }).catch((error)=>{
+                    if (!cancelled) {
+                        observer.error(error);
+                    }
+                });
+                // Return teardown logic
+                return ()=>{
+                    cancelled = true;
+                    innerSubscription?.unsubscribe();
+                };
+            });
+        }
+        // Static headers only
+        operation.setContext(({ headers = {} })=>({
+                headers: {
+                    ...headers,
+                    ...this.headers
+                }
+            }));
+        return forward(operation);
+    }
+}
+
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch : fetch;
 const HttpLink = new HttpLink$1({
@@ -126,22 +182,21 @@ const TerminatingLink = new ApolloLink(()=>{
     return `${major}.${minor}.${patch}`;
 };
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
     return `Quiltt/${sdkVersion} (${platformInfo})`;
 };
 
 const createVersionLink = (platformInfo)=>{
     const versionNumber = extractVersionNumber(version);
-    const userAgent = getUserAgent(versionNumber, platformInfo);
+    const sdkAgent = getSDKAgent(versionNumber, platformInfo);
     return new ApolloLink((operation, forward)=>{
         operation.setContext(({ headers = {} })=>({
                 headers: {
                     ...headers,
                     'Quiltt-Client-Version': version,
-                    'Quiltt-SDK-Agent': userAgent,
-                    'User-Agent': userAgent
+                    'Quiltt-SDK-Agent': sdkAgent
                 }
             }));
         return forward(operation);
@@ -182,4 +237,4 @@ class QuilttClient extends ApolloClient {
     }
 }
 
-export { AuthLink, BatchHttpLink, ErrorLink, ForwardableLink, HttpLink, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, createVersionLink };
+export { AuthLink, BatchHttpLink, ErrorLink, ForwardableLink, HeadersLink, HttpLink, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, createVersionLink };

package/dist/api/rest/index.cjs

@@ -7,6 +7,32 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var crossfetch__default = /*#__PURE__*/_interopDefault(crossfetch);
 
+/**
+ * Extracts version number from formatted version string
+ * @param formattedVersion - Formatted version like "@quiltt/core: v4.5.1"
+ * @returns Version number like "4.5.1" or "unknown" if not found
+ */ const extractVersionNumber = (formattedVersion)=>{
+    // Find the 'v' prefix and extract version after it
+    const vIndex = formattedVersion.indexOf('v');
+    if (vIndex === -1) return 'unknown';
+    const versionPart = formattedVersion.substring(vIndex + 1);
+    const parts = versionPart.split('.');
+    // Validate we have at least major.minor.patch
+    if (parts.length < 3) return 'unknown';
+    // Extract numeric parts (handles cases like "4.5.1-beta")
+    const major = parts[0].match(/^\d+/)?.[0];
+    const minor = parts[1].match(/^\d+/)?.[0];
+    const patch = parts[2].match(/^\d+/)?.[0];
+    if (!major || !minor || !patch) return 'unknown';
+    return `${major}.${minor}.${patch}`;
+};
+/**
+ * Generates a custom SDK Agent string following standard format
+ * Format: Quiltt/<version> (<platform-info>)
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
+    return `Quiltt/${sdkVersion} (${platformInfo})`;
+};
+
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch__default.default : fetch;
 const RETRY_DELAY = 150 // ms
@@ -60,8 +86,7 @@ var AuthStrategies = /*#__PURE__*/ function(AuthStrategies) {
 }({});
 // https://www.quiltt.dev/api-reference/auth
 class AuthAPI {
-    // @todo userAgent: string | undefined - allow SDKs and callers to set a userAgent
-    constructor(clientId){
+    constructor(clientId, customHeaders, sdkAgent = getSDKAgent(extractVersionNumber(index_cjs.version), 'Unknown')){
         /**
    * Response Statuses:
    *  - 200: OK           -> Session is Valid
@@ -114,6 +139,13 @@ class AuthAPI {
             const headers = new Headers();
             headers.set('Content-Type', 'application/json');
             headers.set('Accept', 'application/json');
+            headers.set('Quiltt-SDK-Agent', this.sdkAgent);
+            // Apply custom headers
+            if (this.customHeaders) {
+                Object.entries(this.customHeaders).forEach(([key, value])=>{
+                    headers.set(key, value);
+                });
+            }
             if (token) {
                 headers.set('Authorization', `Bearer ${token}`);
             }
@@ -136,37 +168,13 @@ class AuthAPI {
             };
         };
         this.clientId = clientId;
+        this.customHeaders = customHeaders;
+        this.sdkAgent = sdkAgent;
     }
 }
 
-/**
- * Extracts version number from formatted version string
- * @param formattedVersion - Formatted version like "@quiltt/core: v4.5.1"
- * @returns Version number like "4.5.1" or "unknown" if not found
- */ const extractVersionNumber = (formattedVersion)=>{
-    // Find the 'v' prefix and extract version after it
-    const vIndex = formattedVersion.indexOf('v');
-    if (vIndex === -1) return 'unknown';
-    const versionPart = formattedVersion.substring(vIndex + 1);
-    const parts = versionPart.split('.');
-    // Validate we have at least major.minor.patch
-    if (parts.length < 3) return 'unknown';
-    // Extract numeric parts (handles cases like "4.5.1-beta")
-    const major = parts[0].match(/^\d+/)?.[0];
-    const minor = parts[1].match(/^\d+/)?.[0];
-    const patch = parts[2].match(/^\d+/)?.[0];
-    if (!major || !minor || !patch) return 'unknown';
-    return `${major}.${minor}.${patch}`;
-};
-/**
- * Generates a User-Agent string following standard format
- * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
-    return `Quiltt/${sdkVersion} (${platformInfo})`;
-};
-
 class ConnectorsAPI {
-    constructor(clientId, userAgent = getUserAgent(extractVersionNumber(index_cjs.version), 'Unknown')){
+    constructor(clientId, sdkAgent = getSDKAgent(extractVersionNumber(index_cjs.version), 'Unknown'), customHeaders){
         /**
    * Response Statuses:
    *  - 200: OK           -> Institutions Found
@@ -207,9 +215,16 @@ class ConnectorsAPI {
             const headers = new Headers();
             headers.set('Content-Type', 'application/json');
             headers.set('Accept', 'application/json');
-            headers.set('User-Agent', this.userAgent);
-            headers.set('Quiltt-SDK-Agent', this.userAgent);
-            headers.set('Authorization', `Bearer ${token}`);
+            headers.set('Quiltt-SDK-Agent', this.sdkAgent);
+            // Apply custom headers
+            if (this.customHeaders) {
+                Object.entries(this.customHeaders).forEach(([key, value])=>{
+                    headers.set(key, value);
+                });
+            }
+            if (token) {
+                headers.set('Authorization', `Bearer ${token}`);
+            }
             return {
                 headers,
                 validateStatus: this.validateStatus,
@@ -218,7 +233,8 @@ class ConnectorsAPI {
         };
         this.validateStatus = (status)=>status < 500 && status !== 429;
         this.clientId = clientId;
-        this.userAgent = userAgent;
+        this.sdkAgent = sdkAgent;
+        this.customHeaders = customHeaders;
     }
 }
 

package/dist/api/rest/index.d.ts

@@ -50,7 +50,15 @@ type SessionResponse = FetchResponse<SessionData>;
 declare class AuthAPI {
     /** The Connector ID, required for identify & authenticate calls */
     clientId: string | undefined;
-    constructor(clientId?: string | undefined);
+    /** The SDK Agent string for telemetry */
+    sdkAgent: string;
+    /**
+     * Custom headers to include with every request.
+     * For Quiltt internal usage. Not intended for public use.
+     * @internal
+     */
+    customHeaders: Record<string, string> | undefined;
+    constructor(clientId?: string | undefined, customHeaders?: Record<string, string>, sdkAgent?: string);
     /**
      * Response Statuses:
      *  - 200: OK           -> Session is Valid
@@ -96,8 +104,14 @@ type SearchResponse = FetchResponse<InstitutionsData>;
 type ResolvableResponse = FetchResponse<ResolvableData>;
 declare class ConnectorsAPI {
     clientId: string;
-    userAgent: string;
-    constructor(clientId: string, userAgent?: string);
+    sdkAgent: string;
+    /**
+     * Custom headers to include with every request.
+     * For Quiltt internal usage. Not intended for public use.
+     * @internal
+     */
+    customHeaders: Record<string, string> | undefined;
+    constructor(clientId: string, sdkAgent?: string, customHeaders?: Record<string, string>);
     /**
      * Response Statuses:
      *  - 200: OK           -> Institutions Found

package/dist/api/rest/index.js

@@ -1,6 +1,32 @@
-import { endpointAuth, endpointRest, version } from '../../config/index.js';
+import { endpointAuth, version, endpointRest } from '../../config/index.js';
 import crossfetch from 'cross-fetch';
 
+/**
+ * Extracts version number from formatted version string
+ * @param formattedVersion - Formatted version like "@quiltt/core: v4.5.1"
+ * @returns Version number like "4.5.1" or "unknown" if not found
+ */ const extractVersionNumber = (formattedVersion)=>{
+    // Find the 'v' prefix and extract version after it
+    const vIndex = formattedVersion.indexOf('v');
+    if (vIndex === -1) return 'unknown';
+    const versionPart = formattedVersion.substring(vIndex + 1);
+    const parts = versionPart.split('.');
+    // Validate we have at least major.minor.patch
+    if (parts.length < 3) return 'unknown';
+    // Extract numeric parts (handles cases like "4.5.1-beta")
+    const major = parts[0].match(/^\d+/)?.[0];
+    const minor = parts[1].match(/^\d+/)?.[0];
+    const patch = parts[2].match(/^\d+/)?.[0];
+    if (!major || !minor || !patch) return 'unknown';
+    return `${major}.${minor}.${patch}`;
+};
+/**
+ * Generates a custom SDK Agent string following standard format
+ * Format: Quiltt/<version> (<platform-info>)
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
+    return `Quiltt/${sdkVersion} (${platformInfo})`;
+};
+
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch : fetch;
 const RETRY_DELAY = 150 // ms
@@ -54,8 +80,7 @@ var AuthStrategies = /*#__PURE__*/ function(AuthStrategies) {
 }({});
 // https://www.quiltt.dev/api-reference/auth
 class AuthAPI {
-    // @todo userAgent: string | undefined - allow SDKs and callers to set a userAgent
-    constructor(clientId){
+    constructor(clientId, customHeaders, sdkAgent = getSDKAgent(extractVersionNumber(version), 'Unknown')){
         /**
    * Response Statuses:
    *  - 200: OK           -> Session is Valid
@@ -108,6 +133,13 @@ class AuthAPI {
             const headers = new Headers();
             headers.set('Content-Type', 'application/json');
             headers.set('Accept', 'application/json');
+            headers.set('Quiltt-SDK-Agent', this.sdkAgent);
+            // Apply custom headers
+            if (this.customHeaders) {
+                Object.entries(this.customHeaders).forEach(([key, value])=>{
+                    headers.set(key, value);
+                });
+            }
             if (token) {
                 headers.set('Authorization', `Bearer ${token}`);
             }
@@ -130,37 +162,13 @@ class AuthAPI {
             };
         };
         this.clientId = clientId;
+        this.customHeaders = customHeaders;
+        this.sdkAgent = sdkAgent;
     }
 }
 
-/**
- * Extracts version number from formatted version string
- * @param formattedVersion - Formatted version like "@quiltt/core: v4.5.1"
- * @returns Version number like "4.5.1" or "unknown" if not found
- */ const extractVersionNumber = (formattedVersion)=>{
-    // Find the 'v' prefix and extract version after it
-    const vIndex = formattedVersion.indexOf('v');
-    if (vIndex === -1) return 'unknown';
-    const versionPart = formattedVersion.substring(vIndex + 1);
-    const parts = versionPart.split('.');
-    // Validate we have at least major.minor.patch
-    if (parts.length < 3) return 'unknown';
-    // Extract numeric parts (handles cases like "4.5.1-beta")
-    const major = parts[0].match(/^\d+/)?.[0];
-    const minor = parts[1].match(/^\d+/)?.[0];
-    const patch = parts[2].match(/^\d+/)?.[0];
-    if (!major || !minor || !patch) return 'unknown';
-    return `${major}.${minor}.${patch}`;
-};
-/**
- * Generates a User-Agent string following standard format
- * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
-    return `Quiltt/${sdkVersion} (${platformInfo})`;
-};
-
 class ConnectorsAPI {
-    constructor(clientId, userAgent = getUserAgent(extractVersionNumber(version), 'Unknown')){
+    constructor(clientId, sdkAgent = getSDKAgent(extractVersionNumber(version), 'Unknown'), customHeaders){
         /**
    * Response Statuses:
    *  - 200: OK           -> Institutions Found
@@ -201,9 +209,16 @@ class ConnectorsAPI {
             const headers = new Headers();
             headers.set('Content-Type', 'application/json');
             headers.set('Accept', 'application/json');
-            headers.set('User-Agent', this.userAgent);
-            headers.set('Quiltt-SDK-Agent', this.userAgent);
-            headers.set('Authorization', `Bearer ${token}`);
+            headers.set('Quiltt-SDK-Agent', this.sdkAgent);
+            // Apply custom headers
+            if (this.customHeaders) {
+                Object.entries(this.customHeaders).forEach(([key, value])=>{
+                    headers.set(key, value);
+                });
+            }
+            if (token) {
+                headers.set('Authorization', `Bearer ${token}`);
+            }
             return {
                 headers,
                 validateStatus: this.validateStatus,
@@ -212,7 +227,8 @@ class ConnectorsAPI {
         };
         this.validateStatus = (status)=>status < 500 && status !== 429;
         this.clientId = clientId;
-        this.userAgent = userAgent;
+        this.sdkAgent = sdkAgent;
+        this.customHeaders = customHeaders;
     }
 }
 

package/dist/config/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var name = "@quiltt/core";
-var version$1 = "5.0.3";
+var version$1 = "5.1.1";
 
 const QUILTT_API_INSECURE = (()=>{
     try {

package/dist/config/index.js

@@ -1,5 +1,5 @@
 var name = "@quiltt/core";
-var version$1 = "5.0.3";
+var version$1 = "5.1.1";
 
 const QUILTT_API_INSECURE = (()=>{
     try {

package/dist/utils/index.cjs

@@ -20,13 +20,13 @@ Object.defineProperty(exports, '__esModule', { value: true });
     return `${major}.${minor}.${patch}`;
 };
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
     return `Quiltt/${sdkVersion} (${platformInfo})`;
 };
 /**
- * Detects browser information from user agent string
+ * Detects browser information from Browser's user agent string
  * Returns browser name and version, or 'Unknown' if not detected
  */ const getBrowserInfo = ()=>{
     if (typeof navigator === 'undefined' || !navigator.userAgent) {
@@ -58,4 +58,4 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 exports.extractVersionNumber = extractVersionNumber;
 exports.getBrowserInfo = getBrowserInfo;
-exports.getUserAgent = getUserAgent;
+exports.getSDKAgent = getSDKAgent;

package/dist/utils/index.d.ts

@@ -5,14 +5,14 @@
  */
 declare const extractVersionNumber: (formattedVersion: string) => string;
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
  */
-declare const getUserAgent: (sdkVersion: string, platformInfo: string) => string;
+declare const getSDKAgent: (sdkVersion: string, platformInfo: string) => string;
 /**
- * Detects browser information from user agent string
+ * Detects browser information from Browser's user agent string
  * Returns browser name and version, or 'Unknown' if not detected
  */
 declare const getBrowserInfo: () => string;
 
-export { extractVersionNumber, getBrowserInfo, getUserAgent };
+export { extractVersionNumber, getBrowserInfo, getSDKAgent };

package/dist/utils/index.js

@@ -18,13 +18,13 @@
     return `${major}.${minor}.${patch}`;
 };
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
- */ const getUserAgent = (sdkVersion, platformInfo)=>{
+ */ const getSDKAgent = (sdkVersion, platformInfo)=>{
     return `Quiltt/${sdkVersion} (${platformInfo})`;
 };
 /**
- * Detects browser information from user agent string
+ * Detects browser information from Browser's user agent string
  * Returns browser name and version, or 'Unknown' if not detected
  */ const getBrowserInfo = ()=>{
     if (typeof navigator === 'undefined' || !navigator.userAgent) {
@@ -54,4 +54,4 @@
     return 'Unknown';
 };
 
-export { extractVersionNumber, getBrowserInfo, getUserAgent };
+export { extractVersionNumber, getBrowserInfo, getSDKAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/core",
-  "version": "5.0.3",
+  "version": "5.1.1",
   "description": "Javascript API client and utilities for Quiltt",
   "keywords": [
     "quiltt",

package/src/api/browser.ts

@@ -125,6 +125,8 @@ export type ConnectorSDKCallbackMetadata = {
 export type ConnectorSDKConnectOptions = ConnectorSDKCallbacks & {
   /** The Institution ID or search term to connect */
   institution?: string
+  /** The OAuth redirect URL for mobile or embedded webview flows */
+  oauthRedirectUrl?: string
 }
 
 /**
@@ -134,6 +136,8 @@ export type ConnectorSDKConnectOptions = ConnectorSDKCallbacks & {
 export type ConnectorSDKReconnectOptions = ConnectorSDKCallbacks & {
   /** The ID of the Connection to reconnect */
   connectionId: string
+  /** The OAuth redirect URL for mobile or embedded webview flows */
+  oauthRedirectUrl?: string
 }
 
 /** Options to initialize Connector
@@ -148,4 +152,6 @@ export type ConnectorSDKConnectorOptions = ConnectorSDKCallbacks & {
   connectionId?: string
   /** The nonce to use for the script tag */
   nonce?: string
+  /** The OAuth redirect URL for mobile or embedded webview flows */
+  oauthRedirectUrl?: string
 }

package/src/api/graphql/links/ActionCableLink.ts

@@ -39,7 +39,7 @@ class ActionCableLink extends ApolloLink {
 
   // Interestingly, this link does _not_ call through to `next` because
   // instead, it sends the request to ActionCable.
-  request(
+  override request(
     operation: ApolloLink.Operation,
     _next: ApolloLink.ForwardFunction
   ): Observable<RequestResult> {
@@ -58,6 +58,7 @@ class ActionCableLink extends ApolloLink {
     }
 
     return new Observable((observer) => {
+      let cancelled = false
       const channelId = Math.round(Date.now() + Math.random() * 100000).toString(16)
       const actionName = this.actionName
       const connectionParams =
@@ -77,6 +78,7 @@ class ActionCableLink extends ApolloLink {
         ),
         {
           connected: (args?: { reconnected: boolean }) => {
+            if (cancelled) return
             channel.perform(actionName, {
               query: operation.query ? print(operation.query) : null,
               variables: operation.variables,
@@ -88,6 +90,8 @@ class ActionCableLink extends ApolloLink {
           },
 
           received: (payload: { result: RequestResult; more: any }) => {
+            if (cancelled) return
+
             if (payload?.result?.data || payload?.result?.errors) {
               observer.next(payload.result)
             }
@@ -98,13 +102,20 @@ class ActionCableLink extends ApolloLink {
 
             callbacks.received?.(payload)
           },
+          // Intentionally not guarded by `cancelled` - disconnected represents
+          // the WebSocket connection state which users may want to know about
+          // for cleanup/status purposes, even after the observable completes.
           disconnected: () => {
             callbacks.disconnected?.()
           },
         }
       )
-      // Make the ActionCable subscription behave like an Apollo subscription
-      return Object.assign(channel, { closed: false })
+
+      // Return teardown logic
+      return () => {
+        cancelled = true
+        channel.unsubscribe()
+      }
     })
   }
 }

package/src/api/graphql/links/AuthLink.ts

@@ -13,7 +13,7 @@ import { validateSessionToken } from '@/utils/token-validation'
  * - Emits GraphQL errors for consistent Apollo error handling
  */
 export class AuthLink extends ApolloLink {
-  request(
+  override request(
     operation: ApolloLink.Operation,
     forward: ApolloLink.ForwardFunction
   ): Observable<ApolloLink.Result> {

package/src/api/graphql/links/HeadersLink.ts

@@ -0,0 +1,84 @@
+import { ApolloLink } from '@apollo/client/core'
+import type { Subscription } from 'rxjs'
+import { Observable } from 'rxjs'
+
+export type HeadersLinkOptions = {
+  /** Static headers to add to every request */
+  headers?: Record<string, string>
+  /** Dynamic headers function called on each request */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+}
+
+/**
+ * Apollo Link that adds custom headers to GraphQL requests.
+ *
+ * Headers can be provided statically or dynamically via a function.
+ * These headers are added before the AuthLink, so they will be preserved
+ * alongside the authorization header.
+ */
+export class HeadersLink extends ApolloLink {
+  private headers: Record<string, string>
+  private getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+
+  constructor(options: HeadersLinkOptions = {}) {
+    super()
+    this.headers = options.headers ?? {}
+    this.getHeaders = options.getHeaders
+  }
+
+  override request(
+    operation: ApolloLink.Operation,
+    forward: ApolloLink.ForwardFunction
+  ): Observable<ApolloLink.Result> {
+    // If we have a dynamic headers function, handle it
+    if (this.getHeaders) {
+      return new Observable((observer) => {
+        let innerSubscription: Subscription | undefined
+        let cancelled = false
+
+        Promise.resolve(this.getHeaders!())
+          .then((dynamicHeaders) => {
+            // Guard against late resolution after unsubscribe
+            if (cancelled) return
+
+            operation.setContext(({ headers = {} }) => ({
+              headers: {
+                ...headers,
+                ...this.headers,
+                ...dynamicHeaders,
+              },
+            }))
+
+            innerSubscription = forward(operation).subscribe({
+              next: (value) => !cancelled && observer.next(value),
+              error: (err) => !cancelled && observer.error(err),
+              complete: () => !cancelled && observer.complete(),
+            })
+          })
+          .catch((error) => {
+            if (!cancelled) {
+              observer.error(error)
+            }
+          })
+
+        // Return teardown logic
+        return () => {
+          cancelled = true
+          innerSubscription?.unsubscribe()
+        }
+      })
+    }
+
+    // Static headers only
+    operation.setContext(({ headers = {} }) => ({
+      headers: {
+        ...headers,
+        ...this.headers,
+      },
+    }))
+
+    return forward(operation)
+  }
+}
+
+export default HeadersLink

package/src/api/graphql/links/VersionLink.ts

@@ -1,19 +1,18 @@
 import { ApolloLink } from '@apollo/client/core'
 
 import { version } from '@/config'
-import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
+import { extractVersionNumber, getSDKAgent } from '@/utils/telemetry'
 
 export const createVersionLink = (platformInfo: string) => {
   const versionNumber = extractVersionNumber(version)
-  const userAgent = getUserAgent(versionNumber, platformInfo)
+  const sdkAgent = getSDKAgent(versionNumber, platformInfo)
 
   return new ApolloLink((operation, forward) => {
     operation.setContext(({ headers = {} }) => ({
       headers: {
         ...headers,
         'Quiltt-Client-Version': version,
-        'Quiltt-SDK-Agent': userAgent,
-        'User-Agent': userAgent,
+        'Quiltt-SDK-Agent': sdkAgent,
       },
     }))
     return forward(operation)

package/src/api/graphql/links/index.ts

@@ -2,6 +2,7 @@ export * from './AuthLink'
 export * from './BatchHttpLink'
 export * from './ErrorLink'
 export * from './ForwardableLink'
+export * from './HeadersLink'
 export * from './HttpLink'
 export * from './RetryLink'
 export * from './SubscriptionLink'

package/src/api/rest/auth.ts

@@ -1,4 +1,5 @@
-import { endpointAuth } from '@/config'
+import { endpointAuth, version } from '@/config'
+import { extractVersionNumber, getSDKAgent } from '@/utils/telemetry'
 
 import type { FetchResponse } from './fetchWithRetry'
 import { fetchWithRetry } from './fetchWithRetry'
@@ -35,11 +36,23 @@ export type SessionResponse = FetchResponse<SessionData>
 export class AuthAPI {
   /** The Connector ID, required for identify & authenticate calls */
   clientId: string | undefined
+  /** The SDK Agent string for telemetry */
+  sdkAgent: string
+  /**
+   * Custom headers to include with every request.
+   * For Quiltt internal usage. Not intended for public use.
+   * @internal
+   */
+  customHeaders: Record<string, string> | undefined
 
-  // @todo userAgent: string | undefined - allow SDKs and callers to set a userAgent
-
-  constructor(clientId?: string | undefined) {
+  constructor(
+    clientId?: string | undefined,
+    customHeaders?: Record<string, string>,
+    sdkAgent: string = getSDKAgent(extractVersionNumber(version), 'Unknown')
+  ) {
     this.clientId = clientId
+    this.customHeaders = customHeaders
+    this.sdkAgent = sdkAgent
   }
 
   /**
@@ -102,6 +115,14 @@ export class AuthAPI {
     const headers = new Headers()
     headers.set('Content-Type', 'application/json')
     headers.set('Accept', 'application/json')
+    headers.set('Quiltt-SDK-Agent', this.sdkAgent)
+
+    // Apply custom headers
+    if (this.customHeaders) {
+      Object.entries(this.customHeaders).forEach(([key, value]) => {
+        headers.set(key, value)
+      })
+    }
 
     if (token) {
       headers.set('Authorization', `Bearer ${token}`)

package/src/api/rest/connectors.ts

@@ -1,5 +1,5 @@
 import { endpointRest, version } from '@/config'
-import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
+import { extractVersionNumber, getSDKAgent } from '@/utils/telemetry'
 
 import type { FetchResponse } from './fetchWithRetry'
 import { fetchWithRetry } from './fetchWithRetry'
@@ -18,14 +18,22 @@ export type ResolvableResponse = FetchResponse<ResolvableData>
 
 export class ConnectorsAPI {
   clientId: string
-  userAgent: string
+  sdkAgent: string
+  /**
+   * Custom headers to include with every request.
+   * For Quiltt internal usage. Not intended for public use.
+   * @internal
+   */
+  customHeaders: Record<string, string> | undefined
 
   constructor(
     clientId: string,
-    userAgent: string = getUserAgent(extractVersionNumber(version), 'Unknown')
+    sdkAgent: string = getSDKAgent(extractVersionNumber(version), 'Unknown'),
+    customHeaders?: Record<string, string>
   ) {
     this.clientId = clientId
-    this.userAgent = userAgent
+    this.sdkAgent = sdkAgent
+    this.customHeaders = customHeaders
   }
 
   /**
@@ -91,9 +99,18 @@ export class ConnectorsAPI {
     const headers = new Headers()
     headers.set('Content-Type', 'application/json')
     headers.set('Accept', 'application/json')
-    headers.set('User-Agent', this.userAgent)
-    headers.set('Quiltt-SDK-Agent', this.userAgent)
-    headers.set('Authorization', `Bearer ${token}`)
+    headers.set('Quiltt-SDK-Agent', this.sdkAgent)
+
+    // Apply custom headers
+    if (this.customHeaders) {
+      Object.entries(this.customHeaders).forEach(([key, value]) => {
+        headers.set(key, value)
+      })
+    }
+
+    if (token) {
+      headers.set('Authorization', `Bearer ${token}`)
+    }
 
     return {
       headers,

package/src/config/configuration.ts

@@ -1,4 +1,4 @@
-import { name as packageName, version as packageVersion } from '../../package.json'
+import { name as PACKAGE_NAME, version as PACKAGE_VERSION } from '../../package.json'
 
 const QUILTT_API_INSECURE = (() => {
   try {
@@ -29,7 +29,7 @@ const protocolHttp = `http${QUILTT_API_INSECURE ? '' : 's'}`
 const protocolWebsockets = `ws${QUILTT_API_INSECURE ? '' : 's'}`
 
 export const debugging = QUILTT_DEBUG
-export const version = `${packageName}: v${packageVersion}`
+export const version = `${PACKAGE_NAME}: v${PACKAGE_VERSION}`
 
 export const cdnBase = `${protocolHttp}://cdn.${domain}`
 export const endpointAuth = `${protocolHttp}://auth.${domain}/v1/users/session`

package/src/utils/telemetry.ts

@@ -25,15 +25,15 @@ export const extractVersionNumber = (formattedVersion: string): string => {
 }
 
 /**
- * Generates a User-Agent string following standard format
+ * Generates a custom SDK Agent string following standard format
  * Format: Quiltt/<version> (<platform-info>)
  */
-export const getUserAgent = (sdkVersion: string, platformInfo: string): string => {
+export const getSDKAgent = (sdkVersion: string, platformInfo: string): string => {
   return `Quiltt/${sdkVersion} (${platformInfo})`
 }
 
 /**
- * Detects browser information from user agent string
+ * Detects browser information from Browser's user agent string
  * Returns browser name and version, or 'Unknown' if not detected
  */
 export const getBrowserInfo = (): string => {