@quiltt/core 5.0.0 → 5.0.2

package/dist/utils/index.cjs

@@ -0,0 +1,61 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 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';
+};
+
+exports.extractVersionNumber = extractVersionNumber;
+exports.getBrowserInfo = getBrowserInfo;
+exports.getUserAgent = getUserAgent;

package/dist/utils/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { extractVersionNumber, getBrowserInfo, getUserAgent };

package/dist/utils/index.js

@@ -0,0 +1,57 @@
+/**
+ * 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';
+};
+
+export { extractVersionNumber, getBrowserInfo, getUserAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/core",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Javascript API client and utilities for Quiltt",
   "keywords": [
     "quiltt",
@@ -20,8 +20,64 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "require": "./dist/api/index.cjs",
+      "import": "./dist/api/index.js"
+    },
+    "./api/browser": {
+      "types": "./dist/api/browser.d.ts",
+      "require": "./dist/api/browser.cjs",
+      "import": "./dist/api/browser.js"
+    },
+    "./api/graphql": {
+      "types": "./dist/api/graphql/index.d.ts",
+      "require": "./dist/api/graphql/index.cjs",
+      "import": "./dist/api/graphql/index.js"
+    },
+    "./api/rest": {
+      "types": "./dist/api/rest/index.d.ts",
+      "require": "./dist/api/rest/index.cjs",
+      "import": "./dist/api/rest/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "require": "./dist/auth/index.cjs",
+      "import": "./dist/auth/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "require": "./dist/config/index.cjs",
+      "import": "./dist/config/index.js"
+    },
+    "./observables": {
+      "types": "./dist/observables/index.d.ts",
+      "require": "./dist/observables/index.cjs",
+      "import": "./dist/observables/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "require": "./dist/storage/index.cjs",
+      "import": "./dist/storage/index.js"
+    },
+    "./timing": {
+      "types": "./dist/timing/index.d.ts",
+      "require": "./dist/timing/index.cjs",
+      "import": "./dist/timing/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "require": "./dist/types.cjs",
+      "import": "./dist/types.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "require": "./dist/utils/index.cjs",
+      "import": "./dist/utils/index.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -40,10 +96,10 @@
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.13",
-    "@types/node": "24.10.9",
+    "@biomejs/biome": "2.3.14",
+    "@types/node": "24.10.10",
     "@types/rails__actioncable": "8.0.3",
-    "@types/react": "19.2.10",
+    "@types/react": "19.2.11",
     "bunchee": "6.9.4",
     "rimraf": "6.1.2",
     "typescript": "5.9.3"

package/src/api/graphql/client.ts

@@ -1,7 +1,7 @@
 import { ApolloClient, ApolloLink } from '@apollo/client/core'
 import type { DefinitionNode, OperationDefinitionNode } from 'graphql'
 
-import { debugging } from '@/configuration'
+import { debugging } from '@/config'
 
 import {
   AuthLink,

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

@@ -5,8 +5,8 @@ import { createConsumer } from '@rails/actioncable'
 import { print } from 'graphql'
 import { Observable } from 'rxjs'
 
-import { endpointWebsockets } from '@/configuration'
-import { GlobalStorage } from '@/storage'
+import { endpointWebsockets } from '@/config'
+import { validateSessionToken } from '@/utils/token-validation'
 
 type RequestResult = ApolloLink.Result<{ [key: string]: unknown }>
 type ConnectionParams = object | ((operation: ApolloLink.Operation) => object)
@@ -43,15 +43,16 @@ class ActionCableLink extends ApolloLink {
     operation: ApolloLink.Operation,
     _next: ApolloLink.ForwardFunction
   ): Observable<RequestResult> {
-    const token = GlobalStorage.get('session')
+    const validation = validateSessionToken('for subscription')
 
-    if (!token) {
-      console.warn('QuilttClient attempted to send an unauthenticated Subscription')
+    if (!validation.valid) {
       return new Observable((observer) => {
-        observer.error(new Error('No authentication token available'))
+        observer.error(validation.error)
       })
     }
 
+    const { token } = validation
+
     if (!this.cables[token]) {
       this.cables[token] = createConsumer(endpointWebsockets + (token ? `?token=${token}` : ''))
     }

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

@@ -1,28 +1,32 @@
 import { ApolloLink } from '@apollo/client/core'
 import { Observable } from 'rxjs'
 
-import { GlobalStorage } from '@/storage'
+import { validateSessionToken } from '@/utils/token-validation'
 
 /**
- * unauthorizedCallback only triggers in the event the token is present, and
- * returns the token; This allows sessions to be forgotten without race conditions
- * causing null sessions to kill valid sessions, or invalid sessions for killing
- * valid sessions during rotation and networking weirdness.
+ * Apollo Link that handles authentication and session expiration for GraphQL requests.
+ *
+ * Features:
+ * - Automatically adds Bearer token to request headers
+ * - Detects expired tokens and triggers proper error handling
+ * - Clears expired sessions from storage (triggers React re-renders via observers)
+ * - Emits GraphQL errors for consistent Apollo error handling
  */
 export class AuthLink extends ApolloLink {
   request(
     operation: ApolloLink.Operation,
     forward: ApolloLink.ForwardFunction
   ): Observable<ApolloLink.Result> {
-    const token = GlobalStorage.get('session')
+    const validation = validateSessionToken()
 
-    if (!token) {
-      console.warn('QuilttLink attempted to send an unauthenticated Query')
+    if (!validation.valid) {
       return new Observable((observer) => {
-        observer.error(new Error('No authentication token available'))
+        observer.error(validation.error)
       })
     }
 
+    const { token } = validation
+
     operation.setContext(({ headers = {} }) => ({
       headers: {
         ...headers,

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

@@ -1,7 +1,7 @@
 import { BatchHttpLink as ApolloBatchHttpLink } from '@apollo/client/link/batch-http'
 import crossfetch from 'cross-fetch'
 
-import { endpointGraphQL } from '@/configuration'
+import { endpointGraphQL } from '@/config'
 
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch : fetch

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

@@ -16,6 +16,10 @@ export const ErrorLink = new ApolloErrorLink(({ error, result }) => {
       if (extensions) {
         if (extensions.code) parts.push(`Code: ${extensions.code}`)
         if (extensions.errorId) parts.push(`Error ID: ${extensions.errorId}`)
+        if (extensions.instruction) parts.push(`Instruction: ${extensions.instruction}`)
+        if (extensions.documentationUrl) {
+          parts.push(`Docs: ${extensions.documentationUrl}`)
+        }
       }
 
       console.warn(parts.join(' | '))

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

@@ -4,7 +4,7 @@ import crossfetch from 'cross-fetch'
 // Use `cross-fetch` only if `fetch` is not available on the `globalThis` object
 const effectiveFetch = typeof fetch === 'undefined' ? crossfetch : fetch
 
-import { endpointGraphQL } from '@/configuration'
+import { endpointGraphQL } from '@/config'
 
 export const HttpLink = new ApolloHttpLink({
   uri: endpointGraphQL,

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

@@ -1,6 +1,6 @@
 import { ApolloLink } from '@apollo/client/core'
 
-import { version } from '@/configuration'
+import { version } from '@/config'
 import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
 
 export const createVersionLink = (platformInfo: string) => {

package/src/api/rest/auth.ts

@@ -1,4 +1,4 @@
-import { endpointAuth } from '@/configuration'
+import { endpointAuth } from '@/config'
 
 import type { FetchResponse } from './fetchWithRetry'
 import { fetchWithRetry } from './fetchWithRetry'

package/src/api/rest/connectors.ts

@@ -1,4 +1,4 @@
-import { endpointRest, version } from '@/configuration'
+import { endpointRest, version } from '@/config'
 import { extractVersionNumber, getUserAgent } from '@/utils/telemetry'
 
 import type { FetchResponse } from './fetchWithRetry'

package/src/auth/index.ts

@@ -0,0 +1 @@
+export * from './json-web-token'

package/src/{JsonWebToken.ts → auth/json-web-token.ts}

@@ -1,4 +1,4 @@
-import type { Maybe } from './types'
+import type { Maybe } from '../types'
 
 export type RegisteredClaims = {
   iss: string // (issuer): Issuer of the JWT

package/src/{configuration.ts → config/configuration.ts}

@@ -1,4 +1,4 @@
-import { name as packageName, version as packageVersion } from '../package.json'
+import { name as packageName, version as packageVersion } from '../../package.json'
 
 const QUILTT_API_INSECURE = (() => {
   try {

package/src/config/index.ts

@@ -0,0 +1 @@
+export * from './configuration'

package/src/index.ts

@@ -1,8 +1,8 @@
 export * from './api'
-export * from './configuration'
-export * from './JsonWebToken'
-export * from './Observable'
+export * from './auth'
+export * from './config'
+export * from './observables'
 export * from './storage'
-export * from './Timeoutable'
+export * from './timing'
 export * from './types'
-export * from './utils/telemetry'
+export * from './utils'

package/src/observables/index.ts

@@ -0,0 +1 @@
+export * from './observable'

package/src/{Observable.ts → observables/observable.ts}

@@ -1,6 +1,6 @@
 import type { Dispatch, SetStateAction } from 'react'
 
-import type { Maybe } from './types'
+import type { Maybe } from '../types'
 
 export type Observer<T> = Dispatch<SetStateAction<Maybe<T> | undefined>>
 

package/src/storage/Local.ts

@@ -1,4 +1,4 @@
-import type { Observer } from '@/Observable'
+import type { Observer } from '@/observables'
 import type { Maybe } from '@/types'
 
 /**

package/src/storage/Memory.ts

@@ -1,5 +1,5 @@
-import type { Observer } from '@/Observable'
-import { Observable } from '@/Observable'
+import type { Observer } from '@/observables'
+import { Observable } from '@/observables'
 import type { Maybe } from '@/types'
 
 /**

package/src/storage/Storage.ts

@@ -1,4 +1,4 @@
-import type { Observer } from '@/Observable'
+import type { Observer } from '@/observables'
 import { LocalStorage } from '@/storage/Local'
 import { MemoryStorage } from '@/storage/Memory'
 import type { Maybe } from '@/types'

package/src/timing/index.ts

@@ -0,0 +1 @@
+export * from './timeoutable'

package/src/{Timeoutable.ts → timing/timeoutable.ts}

@@ -1,4 +1,4 @@
-import type { Observer } from './Observable'
+import type { Observer } from '../observables'
 
 /**
  * This is designed to support singletons to timeouts that can broadcast

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './telemetry'

package/src/utils/token-validation.ts

@@ -0,0 +1,67 @@
+import { GraphQLError } from 'graphql'
+
+import { JsonWebTokenParse } from '@/auth/json-web-token'
+import { GlobalStorage } from '@/storage'
+
+/**
+ * Result of token validation
+ */
+export type TokenValidationResult =
+  | { valid: true; token: string }
+  | { valid: false; error: GraphQLError }
+
+/**
+ * Validates the session token from GlobalStorage.
+ *
+ * This function:
+ * - Checks if a session token exists
+ * - Validates token expiration
+ * - Clears expired tokens from storage (triggers observers and React re-renders)
+ * - Returns appropriate GraphQL errors for authentication failures
+ *
+ * @param errorMessagePrefix - Optional prefix for error messages (e.g., "for subscription")
+ * @returns TokenValidationResult indicating whether the token is valid or providing an error
+ */
+export function validateSessionToken(errorMessagePrefix = ''): TokenValidationResult {
+  const token = GlobalStorage.get('session')
+
+  if (!token) {
+    return {
+      valid: false,
+      error: new GraphQLError(
+        `No session token available${errorMessagePrefix ? ` ${errorMessagePrefix}` : ''}`,
+        {
+          extensions: {
+            code: 'UNAUTHENTICATED',
+            reason: 'NO_TOKEN',
+            documentationUrl: 'https://www.quiltt.dev/authentication#session-tokens',
+          },
+        }
+      ),
+    }
+  }
+
+  // Check if token is expired
+  const jwt = JsonWebTokenParse(token)
+  if (jwt?.claims.exp) {
+    const nowInSeconds = Math.floor(Date.now() / 1000)
+    if (jwt.claims.exp < nowInSeconds) {
+      // Clear expired token - this triggers observers and React re-renders
+      GlobalStorage.set('session', null)
+
+      return {
+        valid: false,
+        error: new GraphQLError('Session token has expired', {
+          extensions: {
+            code: 'UNAUTHENTICATED',
+            reason: 'TOKEN_EXPIRED',
+            expiredAt: jwt.claims.exp,
+            documentationUrl: 'https://www.quiltt.dev/authentication#session-tokens',
+          },
+        }),
+      }
+    }
+  }
+
+  return { valid: true, token }
+}