Add Session Refresh Callbacks

[nicknisi]

Summary

This PR adds callbacks for session refresh success and failure in the AuthKit React Router SDK, providing a more flexible and developer-friendly approach to handling session refreshes.

Note: This is a port of workos/authkit-remix#58 to the React Router library.

Problem

Previously, when a session refresh failed, the SDK would simply delete the cookie and redirect the user to the root path (/). This hard-coded behavior provided no visibility into why the refresh failed and no way for developers to customize the error handling flow.

Solution

This PR introduces:

• onSessionRefreshSuccess callback - Called when a session is successfully refreshed
• onSessionRefreshError callback - Called when a session refresh fails

These callbacks allow developers to implement custom error handling, logging, analytics, and user messaging around session lifecycle events.

Implementation Details

• Created a SessionRefreshError class to properly identify refresh failures
• Modified the session refresh flow to use try/catch pattern

Example Usage

export const loader = async ({ request }) => 
  authkitLoader({ request }, async ({ auth }) => {
    return json({ user: auth.user });
  }, {
    onSessionRefreshError: async ({ error, request, sessionData }) => {
      // Log the error to your monitoring service
      console.error("Session refresh failed:", error);
      
      // You can throw a redirect to a custom error page
      throw redirect("/auth/session-expired");
      
      // Or return a custom response
      // return data({ error: "Your session expired" }, { status: 401 });
    },
    
    onSessionRefreshSuccess: async ({ accessToken, user, organizationId }) => {
      // Track successful refresh
      console.log("Session refreshed for user:", user.id);
    }
  });

Backward Compatibility

To maintain backward compatibility, the default behavior (redirect to / and delete cookie) is preserved when no onSessionRefreshError callback is provided.

[Copilot]

Pull Request Overview

This PR introduces session refresh callbacks to provide developers with greater flexibility in handling session refresh events in the AuthKit React Router SDK, while preserving backward compatibility with the default behavior. Key changes include adding the SessionRefreshError class, integrating onSessionRefreshSuccess and onSessionRefreshError callbacks in authkitLoader, and updating related interfaces and tests.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/session.ts	Introduces SessionRefreshError, updates session refresh flow to use callbacks, and adjusts error handling in authkitLoader.
src/session.spec.ts	Adds tests to ensure the new session refresh callbacks are called appropriately.
src/interfaces.ts	Adds interfaces for refresh callbacks to support type safety and improve readability.

Comments suppressed due to low confidence (1)

src/session.ts:392

• [nitpick] It may be helpful to document that this fallback redirect along with cookie destruction represents the backward-compatible default behavior when no onSessionRefreshError callback is provided or does not yield a Response.

throw redirect('/', {