feat(clerk-js): Improve getToken offline handling

.changeset/fresh-tigers-hunt.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Add proactive session token refresh. Tokens are now automatically refreshed in the background before they expire. The `leewayInSeconds` option controls how far in advance refresh is triggered (default: 15 seconds, minimum: 5 seconds).

.changeset/sparkly-aliens-see.md

@@ -0,0 +1,30 @@
+---
+'@clerk/tanstack-react-start': major
+'@clerk/react-router': major
+'@clerk/clerk-js': major
+'@clerk/upgrade': major
+'@clerk/nextjs': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nuxt': major
+'@clerk/vue': major
+---
+
+`getToken()` now throws `ClerkOfflineError` instead of returning `null` when the client is offline.
+
+This makes it explicit that a token fetch failure was due to network conditions, not authentication state. Previously, returning `null` could be misinterpreted as "user is signed out," potentially causing the cached token to be cleared.
+
+To handle this change, catch `ClerkOfflineError` from `getToken()` calls:
+
+```typescript
+import { ClerkOfflineError } from '@clerk/react/errors';
+
+try {
+  const token = await session.getToken();
+} catch (error) {
+  if (ClerkOfflineError.is(error)) {
+    // Handle offline scenario - show offline UI, retry later, etc.
+  }
+  throw error;
+}
+```

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -1,4 +1,4 @@
-import { EmailLinkErrorCodeStatus } from '@clerk/shared/error';
+import { ClerkOfflineError, EmailLinkErrorCodeStatus } from '@clerk/shared/error';
 import type {
   ActiveSessionResource,
   PendingSessionResource,
@@ -570,6 +570,73 @@ describe('Clerk singleton', () => {
         expect(sut.session).toMatchObject(mockSessionWithOrganization);
       });
     });
+
+    describe('when offline', () => {
+      const mockSession = {
+        id: '1',
+        remove: vi.fn(),
+        status: 'active',
+        user: {},
+        touch: vi.fn(() => Promise.resolve()),
+        getToken: vi.fn(),
+        lastActiveToken: { getRawString: () => 'mocked-token' },
+      };
+      let eventBusSpy: ReturnType<typeof vi.spyOn>;
+
+      beforeEach(() => {
+        eventBusSpy = vi.spyOn(eventBus, 'emit');
+      });
+
+      afterEach(() => {
+        mockSession.remove.mockReset();
+        mockSession.touch.mockReset();
+        mockSession.getToken.mockReset();
+        eventBusSpy?.mockRestore();
+      });
+
+      it('does not emit TokenUpdate with null when getToken throws ClerkOfflineError', async () => {
+        mockSession.touch.mockReturnValue(Promise.resolve());
+        mockSession.getToken.mockRejectedValue(new ClerkOfflineError('Network request failed while offline.'));
+        mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockSession] }));
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        await sut.setActive({ session: mockSession as any as ActiveSessionResource });
+
+        expect(eventBusSpy).toHaveBeenCalledWith('token:update', { token: mockSession.lastActiveToken });
+
+        const tokenUpdateCalls = eventBusSpy.mock.calls.filter(call => call[0] === 'token:update');
+        const nullTokenCalls = tokenUpdateCalls.filter(call => call[1]?.token === null);
+        expect(nullTokenCalls.length).toBe(0);
+      });
+
+      it('preserves existing auth state when offline during setActive', async () => {
+        mockSession.touch.mockReturnValue(Promise.resolve());
+        mockSession.getToken.mockRejectedValue(new ClerkOfflineError('Network request failed while offline.'));
+        mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockSession] }));
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        await sut.setActive({ session: mockSession as any as ActiveSessionResource });
+
+        expect(sut.session).toBeDefined();
+      });
+
+      it('re-throws non-offline errors from getToken', async () => {
+        mockSession.touch.mockReturnValue(Promise.resolve());
+        mockSession.getToken.mockRejectedValue(new Error('Some other error'));
+        mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockSession] }));
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        await expect(sut.setActive({ session: mockSession as any as ActiveSessionResource })).rejects.toThrow(
+          'Some other error',
+        );
+      });
+    });
   });
 
   describe('.load()', () => {