@quiltt/core 4.5.1 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @quiltt/core
 
+## 5.0.0
+
+### Major Changes
+
+- [#394](https://github.com/quiltt/quiltt-js/pull/394) [`2ba646a`](https://github.com/quiltt/quiltt-js/commit/2ba646a2efcb7bef7949dab74778ab1c3babdb84) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Migrate Apollo Client to v4
+
+### Minor Changes
+
+- [#395](https://github.com/quiltt/quiltt-js/pull/395) [`f635500`](https://github.com/quiltt/quiltt-js/commit/f635500f17ab8a76aa0fb87ed7f4971e63a93f12) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Enhanced SDK telemetry with standardized User-Agent headers
+
 ## 4.5.1
 
 ### Patch Changes

package/README.md

@@ -41,10 +41,10 @@ import { AuthAPI } from '@quiltt/core'
 const auth = new AuthAPI('{CONNECTOR_ID}')
 
 // Check if a Session token is valid
-auth.ping('{SESSION_TOKEN}')
+await auth.ping('{SESSION_TOKEN}')
 
 // Revoke a Session token
-auth.revoke('{SESSION_TOKEN}')
+await auth.revoke('{SESSION_TOKEN}')
 ```
 
 ## Modules
@@ -76,7 +76,15 @@ The `types` module provides a collection of TypeScript type definitions and inte
 ## Usage
 
 ```javascript
-import { JsonWebToken, Observable, Storage, Timeoutable, api, types } from '@quiltt/core'
+import { 
+  AuthAPI,
+  JsonWebToken, 
+  Observable, 
+  Storage,
+  Timeoutable, 
+  ConnectorSDK,
+  ConnectorSDKEventType
+} from '@quiltt/core'
 
 // Example usage of the library modules
 // ...

package/dist/{SubscriptionLink-12s-B8qxyDXC.js → SubscriptionLink-12s-C2VbF8Tf.js}

@@ -1,11 +1,11 @@
 'use client';
-import { ApolloLink } from '@apollo/client/core/index.js';
-import { Observable as Observable$1 } from '@apollo/client/utilities/index.js';
+import { ApolloLink } from '@apollo/client/core';
 import { createConsumer } from '@rails/actioncable';
 import { print } from 'graphql';
+import { Observable as Observable$1 } from 'rxjs';
 
 var name = "@quiltt/core";
-var version$1 = "4.5.1";
+var version$1 = "5.0.0";
 
 const QUILTT_API_INSECURE = (()=>{
     try {
@@ -330,6 +330,7 @@ const endpointWebsockets = `${protocolWebsockets}://api.${domain}/websockets`;
  * basically acts like shared memory when there is no localStorage.
  */ const GlobalStorage = new Storage();
 
+// Adapted from https://github.com/rmosolgo/graphql-ruby/blob/master/javascript_client/src/subscriptions/ActionCableLink.ts
 class ActionCableLink extends ApolloLink {
     constructor(options){
         super();
@@ -337,6 +338,7 @@ class ActionCableLink extends ApolloLink {
         this.channelName = options.channelName || 'GraphqlChannel';
         this.actionName = options.actionName || 'execute';
         this.connectionParams = options.connectionParams || {};
+        this.callbacks = options.callbacks || {};
     }
     // Interestingly, this link does _not_ call through to `next` because
     // instead, it sends the request to ActionCable.
@@ -344,7 +346,9 @@ class ActionCableLink extends ApolloLink {
         const token = GlobalStorage.get('session');
         if (!token) {
             console.warn('QuilttClient attempted to send an unauthenticated Subscription');
-            return null;
+            return new Observable$1((observer)=>{
+                observer.error(new Error('No authentication token available'));
+            });
         }
         if (!this.cables[token]) {
             this.cables[token] = createConsumer(endpointWebsockets + (token ? `?token=${token}` : ''));
@@ -353,11 +357,12 @@ class ActionCableLink extends ApolloLink {
             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;
+            const callbacks = this.callbacks;
             const channel = this.cables[token].subscriptions.create(Object.assign({}, {
                 channel: this.channelName,
                 channelId: channelId
             }, connectionParams), {
-                connected: ()=>{
+                connected: (args)=>{
                     channel.perform(actionName, {
                         query: operation.query ? print(operation.query) : null,
                         variables: operation.variables,
@@ -365,6 +370,7 @@ class ActionCableLink extends ApolloLink {
                         operationId: operation.operationId,
                         operationName: operation.operationName
                     });
+                    callbacks.connected?.(args);
                 },
                 received: (payload)=>{
                     if (payload?.result?.data || payload?.result?.errors) {
@@ -373,6 +379,10 @@ class ActionCableLink extends ApolloLink {
                     if (!payload.more) {
                         observer.complete();
                     }
+                    callbacks.received?.(payload);
+                },
+                disconnected: ()=>{
+                    callbacks.disconnected?.();
                 }
             });
             // Make the ActionCable subscription behave like an Apollo subscription
@@ -391,4 +401,4 @@ class SubscriptionLink extends ActionCableLink {
     }
 }
 
-export { GlobalStorage as G, LocalStorage as L, MemoryStorage as M, Observable as O, SubscriptionLink as S, endpointAuth as a, endpointRest as b, cdnBase as c, debugging as d, endpointGraphQL as e, endpointWebsockets as f, Storage as g, version as v };
+export { GlobalStorage as G, LocalStorage as L, MemoryStorage as M, Observable as O, SubscriptionLink as S, endpointAuth as a, endpointRest as b, Storage as c, debugging as d, endpointGraphQL as e, cdnBase as f, endpointWebsockets as g, version as v };

package/dist/index.d.ts

@@ -1,18 +1,14 @@
-import * as _apollo_client_core from '@apollo/client/core';
-import { ApolloClientOptions, NormalizedCacheObject, Operation, NextLink, FetchResult } from '@apollo/client/core';
-export { ApolloError, OperationVariables } from '@apollo/client/core';
-import { ApolloLink, ApolloClient } from '@apollo/client/core/index.js';
-export { gql } from '@apollo/client/core/index.js';
-import { Observable as Observable$1 } from '@apollo/client/utilities';
-import { BatchHttpLink as BatchHttpLink$1 } from '@apollo/client/link/batch-http/index.js';
-import { HttpLink as HttpLink$1 } from '@apollo/client/link/http/index.js';
-import { RetryLink as RetryLink$1 } from '@apollo/client/link/retry/index.js';
-import { Observable as Observable$2 } from '@apollo/client/utilities/index.js';
+import { ApolloClient, ApolloLink } from '@apollo/client/core';
+export { OperationVariables, gql } from '@apollo/client/core';
+import { Observable as Observable$1 } from 'rxjs';
+import { BatchHttpLink as BatchHttpLink$1 } from '@apollo/client/link/batch-http';
+import { ErrorLink as ErrorLink$1 } from '@apollo/client/link/error';
+import { HttpLink as HttpLink$1 } from '@apollo/client/link/http';
+import { RetryLink as RetryLink$1 } from '@apollo/client/link/retry';
 import { Consumer } from '@rails/actioncable';
 import { Dispatch, SetStateAction } from 'react';
-export { NormalizedCacheObject } from '@apollo/client/cache';
-export { InMemoryCache } from '@apollo/client/cache/index.js';
-export { useMutation, useQuery, useSubscription } from '@apollo/client/react/hooks/index.js';
+export { InMemoryCache, NormalizedCacheObject } from '@apollo/client/cache';
+export { useMutation, useQuery, useSubscription } from '@apollo/client/react';
 
 interface CallbackManager {
     onEvent(callback: ConnectorSDKOnEventCallback): void;
@@ -140,12 +136,14 @@ type ConnectorSDKConnectorOptions = ConnectorSDKCallbacks & {
     nonce?: string;
 };
 
-type QuilttClientOptions<T> = Omit<ApolloClientOptions<T>, 'link'> & {
+type QuilttClientOptions = Omit<ApolloClient.Options, 'link'> & {
     /** An array of initial links to inject before the default Quiltt Links */
     customLinks?: ApolloLink[];
+    /** Platform-specific version link (required) */
+    versionLink: ApolloLink;
 };
-declare class QuilttClient extends ApolloClient<NormalizedCacheObject> {
-    constructor(options: QuilttClientOptions<NormalizedCacheObject>);
+declare class QuilttClient extends ApolloClient {
+    constructor(options: QuilttClientOptions);
 }
 
 /**
@@ -155,12 +153,12 @@ declare class QuilttClient extends ApolloClient<NormalizedCacheObject> {
  * valid sessions during rotation and networking weirdness.
  */
 declare class AuthLink extends ApolloLink {
-    request(operation: Operation, forward: NextLink): Observable$1<FetchResult> | null;
+    request(operation: ApolloLink.Operation, forward: ApolloLink.ForwardFunction): Observable$1<ApolloLink.Result>;
 }
 
 declare const BatchHttpLink: BatchHttpLink$1;
 
-declare const ErrorLink: _apollo_client_core.ApolloLink;
+declare const ErrorLink: ErrorLink$1;
 
 declare const ForwardableLink: ApolloLink;
 
@@ -168,10 +166,17 @@ declare const HttpLink: HttpLink$1;
 
 declare const RetryLink: RetryLink$1;
 
-type RequestResult = FetchResult<{
+type RequestResult = ApolloLink.Result<{
     [key: string]: unknown;
-}, Record<string, unknown>, Record<string, unknown>>;
-type ConnectionParams = object | ((operation: Operation) => object);
+}>;
+type ConnectionParams = object | ((operation: ApolloLink.Operation) => object);
+type SubscriptionCallbacks = {
+    connected?: (args?: {
+        reconnected: boolean;
+    }) => void;
+    disconnected?: () => void;
+    received?: (payload: unknown) => void;
+};
 declare class ActionCableLink extends ApolloLink {
     cables: {
         [id: string]: Consumer;
@@ -179,12 +184,14 @@ declare class ActionCableLink extends ApolloLink {
     channelName: string;
     actionName: string;
     connectionParams: ConnectionParams;
+    callbacks: SubscriptionCallbacks;
     constructor(options: {
         channelName?: string;
         actionName?: string;
         connectionParams?: ConnectionParams;
+        callbacks?: SubscriptionCallbacks;
     });
-    request(operation: Operation, _next: NextLink): Observable$2<RequestResult> | null;
+    request(operation: ApolloLink.Operation, _next: ApolloLink.ForwardFunction): Observable$1<RequestResult>;
 }
 
 declare class SubscriptionLink extends ActionCableLink {
@@ -193,7 +200,7 @@ declare class SubscriptionLink extends ActionCableLink {
 
 declare const TerminatingLink: ApolloLink;
 
-declare const VersionLink: ApolloLink;
+declare const createVersionLink: (platformInfo: string) => ApolloLink;
 
 type FetchResponse<T> = {
     data: T;
@@ -292,8 +299,8 @@ type SearchResponse = FetchResponse<InstitutionsData>;
 type ResolvableResponse = FetchResponse<ResolvableData>;
 declare class ConnectorsAPI {
     clientId: string;
-    agent: string;
-    constructor(clientId: string, agent?: string);
+    userAgent: string;
+    constructor(clientId: string, userAgent?: string);
     /**
      * Response Statuses:
      *  - 200: OK           -> Institutions Found
@@ -496,5 +503,22 @@ declare class Timeoutable {
     private broadcast;
 }
 
-export { AuthAPI, AuthLink, AuthStrategies, BatchHttpLink, ConnectorSDKEventType, ConnectorsAPI, ErrorLink, ForwardableLink, GlobalStorage, HttpLink, JsonWebTokenParse, LocalStorage, MemoryStorage, Observable, QuilttClient, RetryLink, Storage, SubscriptionLink, TerminatingLink, Timeoutable, VersionLink, cdnBase, debugging, endpointAuth, endpointGraphQL, endpointRest, endpointWebsockets, version };
+/**
+ * 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
+ */
+declare const extractVersionNumber: (formattedVersion: string) => string;
+/**
+ * Generates a User-Agent string following standard format
+ * Format: Quiltt/<version> (<platform-info>)
+ */
+declare const getUserAgent: (sdkVersion: string, platformInfo: string) => string;
+/**
+ * Detects browser information from user agent string
+ * Returns browser name and version, or 'Unknown' if not detected
+ */
+declare const getBrowserInfo: () => string;
+
+export { AuthAPI, AuthLink, AuthStrategies, BatchHttpLink, ConnectorSDKEventType, ConnectorsAPI, ErrorLink, ForwardableLink, GlobalStorage, HttpLink, JsonWebTokenParse, LocalStorage, MemoryStorage, Observable, QuilttClient, RetryLink, Storage, SubscriptionLink, TerminatingLink, Timeoutable, cdnBase, createVersionLink, debugging, endpointAuth, endpointGraphQL, endpointRest, endpointWebsockets, extractVersionNumber, getBrowserInfo, getUserAgent, version };
 export type { BadRequestResponse, Claims, ConnectorSDK, ConnectorSDKCallbackMetadata, ConnectorSDKCallbacks, ConnectorSDKConnectOptions, ConnectorSDKConnector, ConnectorSDKConnectorOptions, ConnectorSDKOnEventCallback, ConnectorSDKOnEventExitCallback, ConnectorSDKOnExitAbortCallback, ConnectorSDKOnExitErrorCallback, ConnectorSDKOnExitSuccessCallback, ConnectorSDKOnLoadCallback, ConnectorSDKOnOpenCallback, ConnectorSDKReconnectOptions, DeepPartial, DeepReadonly, ErrorData, Exact, InputMaybe, InstitutionData, InstitutionsData, JsonWebToken, MakeMaybe, MakeOptional, Maybe, Mutable, NoContentData, Nullable, Observer, PasscodePayload, PrivateClaims, QuilttClientOptions, QuilttJWT, RegisteredClaims, ResolvableData, ResolvableResponse, SearchResponse, SessionResponse, UnauthorizedData, UnauthorizedResponse, UnprocessableData, UnprocessableResponse, UsernamePayload };

package/dist/index.js

@@ -1,14 +1,15 @@
-import { ApolloLink, ApolloClient } from '@apollo/client/core/index.js';
-export { gql } from '@apollo/client/core/index.js';
-import { G as GlobalStorage, e as endpointGraphQL, v as version, d as debugging, S as SubscriptionLink, a as endpointAuth, b as endpointRest } from './SubscriptionLink-12s-B8qxyDXC.js';
-export { L as LocalStorage, M as MemoryStorage, O as Observable, g as Storage, c as cdnBase, f as endpointWebsockets } from './SubscriptionLink-12s-B8qxyDXC.js';
-import { BatchHttpLink as BatchHttpLink$1 } from '@apollo/client/link/batch-http/index.js';
+import { ApolloLink, ApolloClient } from '@apollo/client/core';
+export { gql } from '@apollo/client/core';
+import { G as GlobalStorage, e as endpointGraphQL, v as version, d as debugging, S as SubscriptionLink, a as endpointAuth, b as endpointRest } from './SubscriptionLink-12s-C2VbF8Tf.js';
+export { L as LocalStorage, M as MemoryStorage, O as Observable, c as Storage, f as cdnBase, g as endpointWebsockets } from './SubscriptionLink-12s-C2VbF8Tf.js';
+import { Observable } from 'rxjs';
+import { BatchHttpLink as BatchHttpLink$1 } from '@apollo/client/link/batch-http';
 import crossfetch from 'cross-fetch';
-import { onError } from '@apollo/client/link/error/index.js';
-import { HttpLink as HttpLink$1 } from '@apollo/client/link/http/index.js';
-import { RetryLink as RetryLink$1 } from '@apollo/client/link/retry/index.js';
-export { InMemoryCache } from '@apollo/client/cache/index.js';
-export { useMutation, useQuery, useSubscription } from '@apollo/client/react/hooks/index.js';
+import { ErrorLink as ErrorLink$1 } from '@apollo/client/link/error';
+import { HttpLink as HttpLink$1 } from '@apollo/client/link/http';
+import { RetryLink as RetryLink$1 } from '@apollo/client/link/retry';
+export { InMemoryCache } from '@apollo/client/cache';
+export { useMutation, useQuery, useSubscription } from '@apollo/client/react';
 
 /**
  * Enum representing the different types of events emitted by the Connector.
@@ -31,7 +32,9 @@ export { useMutation, useQuery, useSubscription } from '@apollo/client/react/hoo
         const token = GlobalStorage.get('session');
         if (!token) {
             console.warn('QuilttLink attempted to send an unauthenticated Query');
-            return null;
+            return new Observable((observer)=>{
+                observer.error(new Error('No authentication token available'));
+            });
         }
         operation.setContext(({ headers = {} })=>({
                 headers: {
@@ -50,9 +53,12 @@ const BatchHttpLink = new BatchHttpLink$1({
     fetch: effectiveFetch$2
 });
 
-const ErrorLink = onError(({ graphQLErrors, networkError })=>{
-    if (graphQLErrors) {
-        graphQLErrors.forEach(({ message, path, extensions })=>{
+const ErrorLink = new ErrorLink$1(({ error, result })=>{
+    // In Apollo Client 4, errors are consolidated to the 'error' and 'result' properties
+    // Handle GraphQL errors from result
+    if (result?.errors) {
+        result.errors.forEach((graphQLError)=>{
+            const { message, path, extensions } = graphQLError;
             const formattedPath = Array.isArray(path) ? path.join('.') : path ?? 'N/A';
             const parts = [
                 `[Quiltt][GraphQL Error]: ${message}`,
@@ -65,12 +71,15 @@ const ErrorLink = onError(({ graphQLErrors, networkError })=>{
             console.warn(parts.join(' | '));
         });
     }
-    if (networkError) {
-        if (networkError.statusCode === 401) {
-            console.warn('[Quiltt][Authentication Error]:', networkError);
+    // Handle network/server errors
+    if (error) {
+        if ('statusCode' in error && error.statusCode === 401) {
+            console.warn('[Quiltt][Authentication Error]:', error);
             GlobalStorage.set('session', null);
+        } else if ('statusCode' in error) {
+            console.warn('[Quiltt][Server Error]:', error);
         } else {
-            console.warn('[Quiltt][Network Error]:', networkError);
+            console.warn('[Quiltt][Network Error]:', error);
         }
     }
 });
@@ -86,22 +95,91 @@ const HttpLink = new HttpLink$1({
 
 const RetryLink = new RetryLink$1({
     attempts: {
-        retryIf: (error, _operation)=>!!error && (!error.statusCode || error.statusCode >= 500)
+        retryIf: (error, _operation)=>{
+            if (!error) return false;
+            const statusCode = 'statusCode' in error ? error.statusCode : undefined;
+            return !statusCode || statusCode >= 500;
+        }
     }
 });
 
-const TerminatingLink = new ApolloLink(()=>null);
-
-const VersionLink = new ApolloLink((operation, forward)=>{
-    operation.setContext(({ headers = {} })=>({
-            headers: {
-                ...headers,
-                'Quiltt-Client-Version': version
-            }
-        }));
-    return forward(operation);
+const TerminatingLink = new ApolloLink(()=>{
+    return new Observable((observer)=>{
+        observer.complete();
+    });
 });
 
+/**
+ * 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})`;
+};
+/**
+ * Detects browser information from user agent string
+ * Returns browser name and version, or 'Unknown' if not detected
+ */ const getBrowserInfo = ()=>{
+    if (typeof navigator === 'undefined' || !navigator.userAgent) {
+        return 'Unknown';
+    }
+    const ua = navigator.userAgent;
+    // Edge (must be checked before Chrome)
+    if (ua.includes('Edg/')) {
+        const version = ua.match(/Edg\/(\d+)/)?.[1] || 'Unknown';
+        return `Edge/${version}`;
+    }
+    // Chrome
+    if (ua.includes('Chrome/') && !ua.includes('Edg/')) {
+        const version = ua.match(/Chrome\/(\d+)/)?.[1] || 'Unknown';
+        return `Chrome/${version}`;
+    }
+    // Safari (must be checked after Chrome)
+    if (ua.includes('Safari/') && !ua.includes('Chrome/')) {
+        const version = ua.match(/Version\/(\d+)/)?.[1] || 'Unknown';
+        return `Safari/${version}`;
+    }
+    // Firefox
+    if (ua.includes('Firefox/')) {
+        const version = ua.match(/Firefox\/(\d+)/)?.[1] || 'Unknown';
+        return `Firefox/${version}`;
+    }
+    return 'Unknown';
+};
+
+const createVersionLink = (platformInfo)=>{
+    const versionNumber = extractVersionNumber(version);
+    const userAgent = getUserAgent(versionNumber, platformInfo);
+    return new ApolloLink((operation, forward)=>{
+        operation.setContext(({ headers = {} })=>({
+                headers: {
+                    ...headers,
+                    'Quiltt-Client-Version': version,
+                    'User-Agent': userAgent
+                }
+            }));
+        return forward(operation);
+    });
+};
+
 class QuilttClient extends ApolloClient {
     constructor(options){
         const finalOptions = {
@@ -124,7 +202,7 @@ class QuilttClient extends ApolloClient {
         const subscriptionsLink = new SubscriptionLink();
         const quilttLink = ApolloLink.from([
             ...initialLinks,
-            VersionLink,
+            options.versionLink,
             authLink,
             ErrorLink,
             RetryLink
@@ -268,7 +346,7 @@ class AuthAPI {
 }
 
 class ConnectorsAPI {
-    constructor(clientId, agent = 'web'){
+    constructor(clientId, userAgent = getUserAgent(extractVersionNumber(version), 'Unknown')){
         /**
    * Response Statuses:
    *  - 200: OK           -> Institutions Found
@@ -309,7 +387,7 @@ class ConnectorsAPI {
             const headers = new Headers();
             headers.set('Content-Type', 'application/json');
             headers.set('Accept', 'application/json');
-            headers.set('Quiltt-SDK-Agent', this.agent);
+            headers.set('User-Agent', this.userAgent);
             headers.set('Authorization', `Bearer ${token}`);
             return {
                 headers,
@@ -319,7 +397,7 @@ class ConnectorsAPI {
         };
         this.validateStatus = (status)=>status < 500 && status !== 429;
         this.clientId = clientId;
-        this.agent = agent;
+        this.userAgent = userAgent;
     }
 }
 
@@ -368,4 +446,4 @@ const JsonWebTokenParse = (token)=>{
     }
 }
 
-export { AuthAPI, AuthLink, AuthStrategies, BatchHttpLink, ConnectorSDKEventType, ConnectorsAPI, ErrorLink, ForwardableLink, GlobalStorage, HttpLink, JsonWebTokenParse, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, Timeoutable, VersionLink, debugging, endpointAuth, endpointGraphQL, endpointRest, version };
+export { AuthAPI, AuthLink, AuthStrategies, BatchHttpLink, ConnectorSDKEventType, ConnectorsAPI, ErrorLink, ForwardableLink, GlobalStorage, HttpLink, JsonWebTokenParse, QuilttClient, RetryLink, SubscriptionLink, TerminatingLink, Timeoutable, createVersionLink, debugging, endpointAuth, endpointGraphQL, endpointRest, extractVersionNumber, getBrowserInfo, getUserAgent, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/core",
-  "version": "4.5.1",
+  "version": "5.0.0",
   "description": "Javascript API client and utilities for Quiltt",
   "keywords": [
     "quiltt",
@@ -32,19 +32,19 @@
   ],
   "main": "dist/index.js",
   "dependencies": {
-    "@apollo/client": "^3.14.0",
-    "@rails/actioncable": "^8.0.300",
+    "@apollo/client": "^4.1.3",
+    "@rails/actioncable": "^8.1.200",
     "braces": "^3.0.3",
-    "cross-fetch": "^4.0.0",
-    "graphql": "^16.10.0",
-    "graphql-ruby-client": "^1.14.5"
+    "cross-fetch": "^4.1.0",
+    "graphql": "^16.12.0",
+    "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.8",
-    "@types/node": "22.19.2",
-    "@types/rails__actioncable": "6.1.11",
-    "@types/react": "19.2.7",
-    "bunchee": "6.6.2",
+    "@biomejs/biome": "2.3.13",
+    "@types/node": "24.10.9",
+    "@types/rails__actioncable": "8.0.3",
+    "@types/react": "19.2.10",
+    "bunchee": "6.9.4",
     "rimraf": "6.1.2",
     "typescript": "5.9.3"
   },

package/src/api/graphql/client.ts

@@ -1,5 +1,4 @@
-import type { ApolloClientOptions, NormalizedCacheObject, Operation } from '@apollo/client/core'
-import { ApolloClient, ApolloLink } from '@apollo/client/core/index.js'
+import { ApolloClient, ApolloLink } from '@apollo/client/core'
 import type { DefinitionNode, OperationDefinitionNode } from 'graphql'
 
 import { debugging } from '@/configuration'
@@ -12,16 +11,17 @@ import {
   HttpLink,
   RetryLink,
   SubscriptionLink,
-  VersionLink,
 } from './links'
 
-export type QuilttClientOptions<T> = Omit<ApolloClientOptions<T>, 'link'> & {
+export type QuilttClientOptions = Omit<ApolloClient.Options, 'link'> & {
   /** An array of initial links to inject before the default Quiltt Links */
   customLinks?: ApolloLink[]
+  /** Platform-specific version link (required) */
+  versionLink: ApolloLink
 }
 
-export class QuilttClient extends ApolloClient<NormalizedCacheObject> {
-  constructor(options: QuilttClientOptions<NormalizedCacheObject>) {
+export class QuilttClient extends ApolloClient {
+  constructor(options: QuilttClientOptions) {
     const finalOptions = {
       ...options,
       devtools: {
@@ -34,13 +34,13 @@ export class QuilttClient extends ApolloClient<NormalizedCacheObject> {
     const isOperationDefinition = (def: DefinitionNode): def is OperationDefinitionNode =>
       def.kind === 'OperationDefinition'
 
-    const isSubscriptionOperation = (operation: Operation) => {
+    const isSubscriptionOperation = (operation: ApolloLink.Operation) => {
       return operation.query.definitions.some(
         (definition) => isOperationDefinition(definition) && definition.operation === 'subscription'
       )
     }
 
-    const isBatchable = (operation: Operation) => {
+    const isBatchable = (operation: ApolloLink.Operation) => {
       return operation.getContext().batchable ?? true
     }
 
@@ -49,12 +49,12 @@ export class QuilttClient extends ApolloClient<NormalizedCacheObject> {
 
     const quilttLink = ApolloLink.from([
       ...initialLinks,
-      VersionLink,
+      options.versionLink,
       authLink,
       ErrorLink,
       RetryLink,
-    ])
-      .split(isSubscriptionOperation, subscriptionsLink, ForwardableLink)
+    ] as ApolloLink[])
+      .split(isSubscriptionOperation, subscriptionsLink as ApolloLink, ForwardableLink)
       .split(isBatchable, BatchHttpLink, HttpLink)
 
     super({
@@ -71,8 +71,8 @@ export class QuilttClient extends ApolloClient<NormalizedCacheObject> {
 
 /** Client and Tooling */
 export type { NormalizedCacheObject } from '@apollo/client/cache'
-export { InMemoryCache } from '@apollo/client/cache/index.js'
-export type { ApolloError, OperationVariables } from '@apollo/client/core'
-export { gql } from '@apollo/client/core/index.js'
+export { InMemoryCache } from '@apollo/client/cache'
+export type { OperationVariables } from '@apollo/client/core'
+export { gql } from '@apollo/client/core'
 /** React hooks used by @quiltt/react-native and @quiltt/react */
-export { useMutation, useQuery, useSubscription } from '@apollo/client/react/hooks/index.js'
+export { useMutation, useQuery, useSubscription } from '@apollo/client/react'

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

@@ -1,46 +1,55 @@
-import type { FetchResult, NextLink, Operation } from '@apollo/client/core'
-import { ApolloLink } from '@apollo/client/core/index.js'
-import { Observable } from '@apollo/client/utilities/index.js'
+// Adapted from https://github.com/rmosolgo/graphql-ruby/blob/master/javascript_client/src/subscriptions/ActionCableLink.ts
+import { ApolloLink } from '@apollo/client/core'
 import type { Consumer } from '@rails/actioncable'
 import { createConsumer } from '@rails/actioncable'
 import { print } from 'graphql'
+import { Observable } from 'rxjs'
 
 import { endpointWebsockets } from '@/configuration'
 import { GlobalStorage } from '@/storage'
 
-type RequestResult = FetchResult<
-  { [key: string]: unknown },
-  Record<string, unknown>,
-  Record<string, unknown>
->
-type ConnectionParams = object | ((operation: Operation) => object)
+type RequestResult = ApolloLink.Result<{ [key: string]: unknown }>
+type ConnectionParams = object | ((operation: ApolloLink.Operation) => object)
+type SubscriptionCallbacks = {
+  connected?: (args?: { reconnected: boolean }) => void
+  disconnected?: () => void
+  received?: (payload: unknown) => void
+}
 
 class ActionCableLink extends ApolloLink {
   cables: { [id: string]: Consumer }
   channelName: string
   actionName: string
   connectionParams: ConnectionParams
+  callbacks: SubscriptionCallbacks
 
   constructor(options: {
     channelName?: string
     actionName?: string
     connectionParams?: ConnectionParams
+    callbacks?: SubscriptionCallbacks
   }) {
     super()
     this.cables = {}
     this.channelName = options.channelName || 'GraphqlChannel'
     this.actionName = options.actionName || 'execute'
     this.connectionParams = options.connectionParams || {}
+    this.callbacks = options.callbacks || {}
   }
 
   // Interestingly, this link does _not_ call through to `next` because
   // instead, it sends the request to ActionCable.
-  request(operation: Operation, _next: NextLink): Observable<RequestResult> | null {
+  request(
+    operation: ApolloLink.Operation,
+    _next: ApolloLink.ForwardFunction
+  ): Observable<RequestResult> {
     const token = GlobalStorage.get('session')
 
     if (!token) {
       console.warn('QuilttClient attempted to send an unauthenticated Subscription')
-      return null
+      return new Observable((observer) => {
+        observer.error(new Error('No authentication token available'))
+      })
     }
 
     if (!this.cables[token]) {
@@ -55,6 +64,7 @@ class ActionCableLink extends ApolloLink {
           ? this.connectionParams(operation)
           : this.connectionParams
 
+      const callbacks = this.callbacks
       const channel = this.cables[token].subscriptions.create(
         Object.assign(
           {},
@@ -65,7 +75,7 @@ class ActionCableLink extends ApolloLink {
           connectionParams
         ),
         {
-          connected: () => {
+          connected: (args?: { reconnected: boolean }) => {
             channel.perform(actionName, {
               query: operation.query ? print(operation.query) : null,
               variables: operation.variables,
@@ -73,6 +83,7 @@ class ActionCableLink extends ApolloLink {
               operationId: (operation as { operationId?: string }).operationId,
               operationName: operation.operationName,
             })
+            callbacks.connected?.(args)
           },
 
           received: (payload: { result: RequestResult; more: any }) => {
@@ -83,6 +94,11 @@ class ActionCableLink extends ApolloLink {
             if (!payload.more) {
               observer.complete()
             }
+
+            callbacks.received?.(payload)
+          },
+          disconnected: () => {
+            callbacks.disconnected?.()
           },
         }
       )

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

@@ -1,6 +1,5 @@
-import type { FetchResult, NextLink, Operation } from '@apollo/client/core'
-import { ApolloLink } from '@apollo/client/core/index.js'
-import type { Observable } from '@apollo/client/utilities'
+import { ApolloLink } from '@apollo/client/core'
+import { Observable } from 'rxjs'
 
 import { GlobalStorage } from '@/storage'
 
@@ -11,12 +10,17 @@ import { GlobalStorage } from '@/storage'
  * valid sessions during rotation and networking weirdness.
  */
 export class AuthLink extends ApolloLink {
-  request(operation: Operation, forward: NextLink): Observable<FetchResult> | null {
+  request(
+    operation: ApolloLink.Operation,
+    forward: ApolloLink.ForwardFunction
+  ): Observable<ApolloLink.Result> {
     const token = GlobalStorage.get('session')
 
     if (!token) {
       console.warn('QuilttLink attempted to send an unauthenticated Query')
-      return null
+      return new Observable((observer) => {
+        observer.error(new Error('No authentication token available'))
+      })
     }
 
     operation.setContext(({ headers = {} }) => ({

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

@@ -1,4 +1,4 @@
-import { BatchHttpLink as ApolloBatchHttpLink } from '@apollo/client/link/batch-http/index.js'
+import { BatchHttpLink as ApolloBatchHttpLink } from '@apollo/client/link/batch-http'
 import crossfetch from 'cross-fetch'
 
 import { endpointGraphQL } from '@/configuration'

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

@@ -1,11 +1,15 @@
-import type { ServerError } from '@apollo/client/core'
-import { onError } from '@apollo/client/link/error/index.js'
+import { ErrorLink as ApolloErrorLink } from '@apollo/client/link/error'
+import type { GraphQLFormattedError } from 'graphql'
 
 import { GlobalStorage } from '@/storage'
 
-export const ErrorLink = onError(({ graphQLErrors, networkError }) => {
-  if (graphQLErrors) {
-    graphQLErrors.forEach(({ message, path, extensions }) => {
+export const ErrorLink = new ApolloErrorLink(({ error, result }) => {
+  // In Apollo Client 4, errors are consolidated to the 'error' and 'result' properties
+
+  // Handle GraphQL errors from result
+  if (result?.errors) {
+    result.errors.forEach((graphQLError: GraphQLFormattedError) => {
+      const { message, path, extensions } = graphQLError
       const formattedPath = Array.isArray(path) ? path.join('.') : (path ?? 'N/A')
       const parts = [`[Quiltt][GraphQL Error]: ${message}`, `Path: ${formattedPath}`]
 
@@ -18,12 +22,15 @@ export const ErrorLink = onError(({ graphQLErrors, networkError }) => {
     })
   }
 
-  if (networkError) {
-    if ((networkError as ServerError).statusCode === 401) {
-      console.warn('[Quiltt][Authentication Error]:', networkError)
+  // Handle network/server errors
+  if (error) {
+    if ('statusCode' in error && error.statusCode === 401) {
+      console.warn('[Quiltt][Authentication Error]:', error)
       GlobalStorage.set('session', null)
+    } else if ('statusCode' in error) {
+      console.warn('[Quiltt][Server Error]:', error)
     } else {
-      console.warn('[Quiltt][Network Error]:', networkError)
+      console.warn('[Quiltt][Network Error]:', error)
     }
   }
 })

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

@@ -1,4 +1,4 @@
-import { ApolloLink } from '@apollo/client/core/index.js'
+import { ApolloLink } from '@apollo/client/core'
 
 export const ForwardableLink = new ApolloLink((operation, forward) => forward(operation))
 

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

@@ -1,4 +1,4 @@
-import { HttpLink as ApolloHttpLink } from '@apollo/client/link/http/index.js'
+import { HttpLink as ApolloHttpLink } from '@apollo/client/link/http'
 import crossfetch from 'cross-fetch'
 
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object

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

@@ -1,8 +1,12 @@
-import { RetryLink as ApolloRetryLink } from '@apollo/client/link/retry/index.js'
+import { RetryLink as ApolloRetryLink } from '@apollo/client/link/retry'
 
 export const RetryLink = new ApolloRetryLink({
   attempts: {
-    retryIf: (error, _operation) => !!error && (!error.statusCode || error.statusCode >= 500),
+    retryIf: (error, _operation) => {
+      if (!error) return false
+      const statusCode = 'statusCode' in error ? (error as any).statusCode : undefined
+      return !statusCode || statusCode >= 500
+    },
   },
 })
 

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

@@ -1,5 +1,10 @@
-import { ApolloLink } from '@apollo/client/core/index.js'
+import { ApolloLink } from '@apollo/client/core'
+import { Observable } from 'rxjs'
 
-export const TerminatingLink = new ApolloLink(() => null)
+export const TerminatingLink = new ApolloLink(() => {
+  return new Observable((observer) => {
+    observer.complete()
+  })
+})
 
 export default TerminatingLink

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

@@ -1,15 +1,20 @@
-import { ApolloLink } from '@apollo/client/core/index.js'
+import { ApolloLink } from '@apollo/client/core'
 
 import { version } from '@/configuration'
+import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
 
-export const VersionLink = new ApolloLink((operation, forward) => {
-  operation.setContext(({ headers = {} }) => ({
-    headers: {
-      ...headers,
-      'Quiltt-Client-Version': version,
-    },
-  }))
-  return forward(operation)
-})
+export const createVersionLink = (platformInfo: string) => {
+  const versionNumber = extractVersionNumber(version)
+  const userAgent = getUserAgent(versionNumber, platformInfo)
 
-export default VersionLink
+  return new ApolloLink((operation, forward) => {
+    operation.setContext(({ headers = {} }) => ({
+      headers: {
+        ...headers,
+        'Quiltt-Client-Version': version,
+        'User-Agent': userAgent,
+      },
+    }))
+    return forward(operation)
+  })
+}

package/src/api/rest/connectors.ts

@@ -1,4 +1,5 @@
-import { endpointRest } from '@/configuration'
+import { endpointRest, version } from '@/configuration'
+import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
 
 import type { FetchResponse } from './fetchWithRetry'
 import { fetchWithRetry } from './fetchWithRetry'
@@ -17,11 +18,14 @@ export type ResolvableResponse = FetchResponse<ResolvableData>
 
 export class ConnectorsAPI {
   clientId: string
-  agent: string
+  userAgent: string
 
-  constructor(clientId: string, agent = 'web') {
+  constructor(
+    clientId: string,
+    userAgent: string = getUserAgent(extractVersionNumber(version), 'Unknown')
+  ) {
     this.clientId = clientId
-    this.agent = agent
+    this.userAgent = userAgent
   }
 
   /**
@@ -87,7 +91,7 @@ export class ConnectorsAPI {
     const headers = new Headers()
     headers.set('Content-Type', 'application/json')
     headers.set('Accept', 'application/json')
-    headers.set('Quiltt-SDK-Agent', this.agent)
+    headers.set('User-Agent', this.userAgent)
     headers.set('Authorization', `Bearer ${token}`)
 
     return {

package/src/index.ts

@@ -5,3 +5,4 @@ export * from './Observable'
 export * from './storage'
 export * from './Timeoutable'
 export * from './types'
+export * from './utils/telemetry'

package/src/utils/telemetry.ts

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+export const extractVersionNumber = (formattedVersion: string): string => {
+  // 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>)
+ */
+export const getUserAgent = (sdkVersion: string, platformInfo: string): string => {
+  return `Quiltt/${sdkVersion} (${platformInfo})`
+}
+
+/**
+ * Detects browser information from user agent string
+ * Returns browser name and version, or 'Unknown' if not detected
+ */
+export const getBrowserInfo = (): string => {
+  if (typeof navigator === 'undefined' || !navigator.userAgent) {
+    return 'Unknown'
+  }
+
+  const ua = navigator.userAgent
+
+  // Edge (must be checked before Chrome)
+  if (ua.includes('Edg/')) {
+    const version = ua.match(/Edg\/(\d+)/)?.[1] || 'Unknown'
+    return `Edge/${version}`
+  }
+
+  // Chrome
+  if (ua.includes('Chrome/') && !ua.includes('Edg/')) {
+    const version = ua.match(/Chrome\/(\d+)/)?.[1] || 'Unknown'
+    return `Chrome/${version}`
+  }
+
+  // Safari (must be checked after Chrome)
+  if (ua.includes('Safari/') && !ua.includes('Chrome/')) {
+    const version = ua.match(/Version\/(\d+)/)?.[1] || 'Unknown'
+    return `Safari/${version}`
+  }
+
+  // Firefox
+  if (ua.includes('Firefox/')) {
+    const version = ua.match(/Firefox\/(\d+)/)?.[1] || 'Unknown'
+    return `Firefox/${version}`
+  }
+
+  return 'Unknown'
+}