@quiltt/core 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @quiltt/core
 
+## 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
+
+- [#412](https://github.com/quiltt/quiltt-js/pull/412) [`099070b`](https://github.com/quiltt/quiltt-js/commit/099070b984f7375491e1c736bc3fbd35c93c7fd3) Thanks [@rubendinho](https://github.com/rubendinho)! - Improve User Agent telemetry
+
+- [#410](https://github.com/quiltt/quiltt-js/pull/410) [`628887c`](https://github.com/quiltt/quiltt-js/commit/628887cc592b492a1fb38ff5898aeda969140855) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Re-Export Upstream Packages
+
 ## 5.0.2
 
 ### Patch Changes

package/README.md

@@ -38,7 +38,7 @@ The Auth API is used by the Quiltt Connector under the hood and can be used to p
 import { AuthAPI } from '@quiltt/core'
 
 // Set up client instance
-const auth = new AuthAPI('{CONNECTOR_ID}')
+const auth = new AuthAPI()
 
 // Check if a Session token is valid
 await auth.ping('{SESSION_TOKEN}')

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({
@@ -145,6 +201,7 @@ const createVersionLink = (platformInfo)=>{
                 headers: {
                     ...headers,
                     'Quiltt-Client-Version': index_cjs.version,
+                    'Quiltt-SDK-Agent': userAgent,
                     'User-Agent': userAgent
                 }
             }));
@@ -211,6 +268,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({
@@ -140,6 +196,7 @@ const createVersionLink = (platformInfo)=>{
                 headers: {
                     ...headers,
                     'Quiltt-Client-Version': version,
+                    'Quiltt-SDK-Agent': userAgent,
                     'User-Agent': userAgent
                 }
             }));
@@ -181,4 +238,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

@@ -60,6 +60,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){
         /**
    * Response Statuses:
@@ -207,6 +208,7 @@ class ConnectorsAPI {
             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}`);
             return {
                 headers,

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

@@ -48,6 +48,7 @@ type Authenticate = SessionData | UnauthorizedData | UnprocessableData;
 type Revoke = NoContentData | UnauthorizedData;
 type SessionResponse = FetchResponse<SessionData>;
 declare class AuthAPI {
+    /** The Connector ID, required for identify & authenticate calls */
     clientId: string | undefined;
     constructor(clientId?: string | undefined);
     /**

package/dist/api/rest/index.js

@@ -54,6 +54,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){
         /**
    * Response Statuses:
@@ -201,6 +202,7 @@ class ConnectorsAPI {
             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}`);
             return {
                 headers,

package/dist/config/index.cjs

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

package/dist/config/index.js

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

package/dist/index.cjs

@@ -7,7 +7,6 @@ var index_cjs$3 = require('./observables/index.cjs');
 var index_cjs$4 = require('./storage/index.cjs');
 var index_cjs$5 = require('./timing/index.cjs');
 var types_cjs = require('./types.cjs');
-var index_cjs$6 = require('./utils/index.cjs');
 
 
 
@@ -53,9 +52,3 @@ Object.keys(types_cjs).forEach(function (k) {
 		get: function () { return types_cjs[k]; }
 	});
 });
-Object.keys(index_cjs$6).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return index_cjs$6[k]; }
-	});
-});

package/dist/index.d.ts

@@ -5,4 +5,3 @@ export * from './observables/index.js';
 export * from './storage/index.js';
 export * from './timing/index.js';
 export * from './types.js';
-export * from './utils/index.js';

package/dist/index.js

@@ -5,4 +5,3 @@ export * from './observables/index.js';
 export * from './storage/index.js';
 export * from './timing/index.js';
 export * from './types.js';
-export * from './utils/index.js';

package/dist/types.d.ts

@@ -1,26 +1,34 @@
-/** Utility types to extend default TS utilities */
+/** Represents a value that can be T or null */
 type Maybe<T> = T | null;
+/** Input variant of Maybe for function parameters */
 type InputMaybe<T> = Maybe<T>;
+/** Ensures all properties of T are exactly their declared types */
 type Exact<T extends {
     [key: string]: unknown;
 }> = {
     [K in keyof T]: T[K];
 };
+/** Makes specific keys K optional and nullable in type T */
 type MakeOptional<T, K extends keyof T> = Omit<T, K> & {
     [SubKey in K]?: Maybe<T[SubKey]>;
 };
+/** Makes specific keys K nullable (but still required) in type T */
 type MakeMaybe<T, K extends keyof T> = Omit<T, K> & {
     [SubKey in K]: Maybe<T[SubKey]>;
 };
+/** Makes all properties of T nullable */
 type Nullable<T> = {
     [K in keyof T]: T[K] | null;
 };
+/** Removes readonly modifier from all properties of Type */
 type Mutable<Type> = {
     -readonly [Key in keyof Type]: Type[Key];
 };
+/** Recursively makes all properties of T optional */
 type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/** Recursively makes all properties of T readonly */
 type DeepReadonly<T> = T extends object ? {
     [P in keyof T]: DeepReadonly<T[P]>;
 } : T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/core",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Javascript API client and utilities for Quiltt",
   "keywords": [
     "quiltt",
@@ -88,7 +88,7 @@
   ],
   "main": "dist/index.js",
   "dependencies": {
-    "@apollo/client": "^4.1.3",
+    "@apollo/client": "^4.1.4",
     "@rails/actioncable": "^8.1.200",
     "braces": "^3.0.3",
     "cross-fetch": "^4.1.0",
@@ -96,12 +96,12 @@
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.14",
-    "@types/node": "24.10.10",
+    "@biomejs/biome": "2.4.0",
+    "@types/node": "24.10.13",
     "@types/rails__actioncable": "8.0.3",
-    "@types/react": "19.2.11",
+    "@types/react": "19.2.14",
     "bunchee": "6.9.4",
-    "rimraf": "6.1.2",
+    "rimraf": "6.1.3",
     "typescript": "5.9.3"
   },
   "tags": [

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

@@ -12,6 +12,7 @@ export const createVersionLink = (platformInfo: string) => {
       headers: {
         ...headers,
         'Quiltt-Client-Version': version,
+        'Quiltt-SDK-Agent': userAgent,
         'User-Agent': userAgent,
       },
     }))

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

@@ -33,8 +33,11 @@ export type SessionResponse = FetchResponse<SessionData>
 
 // https://www.quiltt.dev/api-reference/auth
 export class AuthAPI {
+  /** The Connector ID, required for identify & authenticate calls */
   clientId: string | undefined
 
+  // @todo userAgent: string | undefined - allow SDKs and callers to set a userAgent
+
   constructor(clientId?: string | undefined) {
     this.clientId = clientId
   }

package/src/api/rest/connectors.ts

@@ -92,6 +92,7 @@ export class ConnectorsAPI {
     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}`)
 
     return {

package/src/index.ts

@@ -1,3 +1,23 @@
+// ============================================================================
+// @quiltt/core - Core Quiltt SDK functionality
+// ============================================================================
+// This package provides the foundational TypeScript primitives for interacting
+// with the Quiltt API. It works across all JavaScript environments (browser,
+// Node.js, React Native) and contains no UI-specific dependencies.
+//
+// Main exports:
+// - API clients (AuthAPI, ConnectorsAPI, QuilttClient)
+// - Authentication utilities (JsonWebTokenParse, AuthStrategies)
+// - Configuration helpers
+// - Observable patterns for reactive data
+// - Storage abstractions (GlobalStorage)
+// - Timeout utilities (Timeoutable)
+// - TypeScript utility types
+//
+// Note: Utils are NOT exported from the main entry point to keep the public
+// API clean. Access utils via subpath import: '@quiltt/core/utils'
+// ============================================================================
+
 export * from './api'
 export * from './auth'
 export * from './config'
@@ -5,4 +25,3 @@ export * from './observables'
 export * from './storage'
 export * from './timing'
 export * from './types'
-export * from './utils'

package/src/types.ts

@@ -1,10 +1,33 @@
-/** Utility types to extend default TS utilities */
+// ============================================================================
+// TypeScript Utility Types
+// ============================================================================
+// Extended utility types to complement TypeScript's built-in utilities.
+// These are commonly used throughout the Quiltt SDK for type safety.
+// ============================================================================
+
+/** Represents a value that can be T or null */
 export type Maybe<T> = T | null
+
+/** Input variant of Maybe for function parameters */
 export type InputMaybe<T> = Maybe<T>
+
+/** Ensures all properties of T are exactly their declared types */
 export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] }
+
+/** Makes specific keys K optional and nullable in type T */
 export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> }
+
+/** Makes specific keys K nullable (but still required) in type T */
 export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> }
+
+/** Makes all properties of T nullable */
 export type Nullable<T> = { [K in keyof T]: T[K] | null }
+
+/** Removes readonly modifier from all properties of Type */
 export type Mutable<Type> = { -readonly [Key in keyof Type]: Type[Key] }
+
+/** Recursively makes all properties of T optional */
 export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T
+
+/** Recursively makes all properties of T readonly */
 export type DeepReadonly<T> = T extends object ? { [P in keyof T]: DeepReadonly<T[P]> } : T