@auth-gate/core 0.15.0 → 0.15.2

package/dist/index.cjs

@@ -727,13 +727,31 @@ var AuthGateClient = class {
 	/**
 	* Exchange a refresh token for a new JWT.
 	*
-	* Refresh tokens are single-use — each call returns a new JWT and
-	* invalidates the previous refresh token (rotation).
+	* Refresh tokens are single-use: each call invalidates the token it was
+	* given, so callers must store the `refresh_token` it returns or their next
+	* refresh fails.
+	*
+	* Returns `null` for any failure. To end a session, use
+	* {@link attemptRefresh}, which separates a rejected token from a temporary
+	* failure.
 	*
 	* @param refreshToken - The opaque refresh token.
-	* @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
+	* @returns A new JWT, its `expires_in` (seconds) and the rotated
+	* `refresh_token`, or `null` if the refresh failed.
 	*/
 	async refreshToken(refreshToken) {
+		const outcome = await this.attemptRefresh(refreshToken);
+		return outcome.status === "refreshed" ? outcome : null;
+	}
+	/**
+	* Exchange a refresh token for a new JWT and report why it failed, if it did.
+	*
+	* @param refreshToken - The opaque refresh token.
+	* @returns `refreshed` with the new tokens, `rejected` when the server refused
+	* the token, or `unavailable` when it gave no verdict (408, 429, 5xx, network
+	* error). Only `rejected` should end a session.
+	*/
+	async attemptRefresh(refreshToken) {
 		try {
 			const response = await fetch(`${this.config.baseUrl}/api/proxy/token/refresh`, {
 				method: "POST",
@@ -743,10 +761,13 @@ var AuthGateClient = class {
 				},
 				body: JSON.stringify({ refresh_token: refreshToken })
 			});
-			if (!response.ok) return null;
-			return response.json();
+			if (response.ok) return {
+				status: "refreshed",
+				...await response.json()
+			};
+			return { status: response.status === 408 || response.status === 429 || response.status >= 500 ? "unavailable" : "rejected" };
 		} catch {
-			return null;
+			return { status: "unavailable" };
 		}
 	}
 	/**

package/dist/index.d.cts

@@ -158,6 +158,17 @@ interface BackupCodesResponse {
 }
 //#endregion
 //#region src/client.d.ts
+/** The result of {@link AuthGateClient.attemptRefresh}. */
+type TokenRefreshOutcome = {
+  status: "refreshed";
+  token: string;
+  refresh_token?: string;
+  expires_in: number;
+} | {
+  status: "rejected";
+} | {
+  status: "unavailable";
+};
 /**
  * Core client for interacting with the AuthGate authentication proxy.
  *
@@ -360,16 +371,32 @@ declare class AuthGateClient {
   /**
    * Exchange a refresh token for a new JWT.
    *
-   * Refresh tokens are single-use — each call returns a new JWT and
-   * invalidates the previous refresh token (rotation).
+   * Refresh tokens are single-use: each call invalidates the token it was
+   * given, so callers must store the `refresh_token` it returns or their next
+   * refresh fails.
+   *
+   * Returns `null` for any failure. To end a session, use
+   * {@link attemptRefresh}, which separates a rejected token from a temporary
+   * failure.
    *
    * @param refreshToken - The opaque refresh token.
-   * @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
+   * @returns A new JWT, its `expires_in` (seconds) and the rotated
+   * `refresh_token`, or `null` if the refresh failed.
    */
   refreshToken(refreshToken: string): Promise<{
     token: string;
+    refresh_token?: string;
     expires_in: number;
   } | null>;
+  /**
+   * Exchange a refresh token for a new JWT and report why it failed, if it did.
+   *
+   * @param refreshToken - The opaque refresh token.
+   * @returns `refreshed` with the new tokens, `rejected` when the server refused
+   * the token, or `unavailable` when it gave no verdict (408, 429, 5xx, network
+   * error). Only `rejected` should end a session.
+   */
+  attemptRefresh(refreshToken: string): Promise<TokenRefreshOutcome>;
   /**
    * Exchange a single-use authorization code (delivered on the callback URL)
    * for the JWT + refresh token. Codes are one-shot and expire after ~60s.
@@ -1034,4 +1061,4 @@ declare function mergePermissions(projectRole: UserRoleAssignment | null | undef
  */
 declare function hasMergedPermission(projectRole: UserRoleAssignment | null | undefined, orgMembership: OrgMembership | null | undefined, permission: string): boolean;
 //#endregion
-export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };
+export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, type TokenRefreshOutcome, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };

package/dist/index.d.ts

@@ -158,6 +158,17 @@ interface BackupCodesResponse {
 }
 //#endregion
 //#region src/client.d.ts
+/** The result of {@link AuthGateClient.attemptRefresh}. */
+type TokenRefreshOutcome = {
+  status: "refreshed";
+  token: string;
+  refresh_token?: string;
+  expires_in: number;
+} | {
+  status: "rejected";
+} | {
+  status: "unavailable";
+};
 /**
  * Core client for interacting with the AuthGate authentication proxy.
  *
@@ -360,16 +371,32 @@ declare class AuthGateClient {
   /**
    * Exchange a refresh token for a new JWT.
    *
-   * Refresh tokens are single-use — each call returns a new JWT and
-   * invalidates the previous refresh token (rotation).
+   * Refresh tokens are single-use: each call invalidates the token it was
+   * given, so callers must store the `refresh_token` it returns or their next
+   * refresh fails.
+   *
+   * Returns `null` for any failure. To end a session, use
+   * {@link attemptRefresh}, which separates a rejected token from a temporary
+   * failure.
    *
    * @param refreshToken - The opaque refresh token.
-   * @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
+   * @returns A new JWT, its `expires_in` (seconds) and the rotated
+   * `refresh_token`, or `null` if the refresh failed.
    */
   refreshToken(refreshToken: string): Promise<{
     token: string;
+    refresh_token?: string;
     expires_in: number;
   } | null>;
+  /**
+   * Exchange a refresh token for a new JWT and report why it failed, if it did.
+   *
+   * @param refreshToken - The opaque refresh token.
+   * @returns `refreshed` with the new tokens, `rejected` when the server refused
+   * the token, or `unavailable` when it gave no verdict (408, 429, 5xx, network
+   * error). Only `rejected` should end a session.
+   */
+  attemptRefresh(refreshToken: string): Promise<TokenRefreshOutcome>;
   /**
    * Exchange a single-use authorization code (delivered on the callback URL)
    * for the JWT + refresh token. Codes are one-shot and expire after ~60s.
@@ -1034,4 +1061,4 @@ declare function mergePermissions(projectRole: UserRoleAssignment | null | undef
  */
 declare function hasMergedPermission(projectRole: UserRoleAssignment | null | undefined, orgMembership: OrgMembership | null | undefined, permission: string): boolean;
 //#endregion
-export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };
+export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, type TokenRefreshOutcome, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };

package/dist/index.mjs

@@ -726,13 +726,31 @@ var AuthGateClient = class {
 	/**
 	* Exchange a refresh token for a new JWT.
 	*
-	* Refresh tokens are single-use — each call returns a new JWT and
-	* invalidates the previous refresh token (rotation).
+	* Refresh tokens are single-use: each call invalidates the token it was
+	* given, so callers must store the `refresh_token` it returns or their next
+	* refresh fails.
+	*
+	* Returns `null` for any failure. To end a session, use
+	* {@link attemptRefresh}, which separates a rejected token from a temporary
+	* failure.
 	*
 	* @param refreshToken - The opaque refresh token.
-	* @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
+	* @returns A new JWT, its `expires_in` (seconds) and the rotated
+	* `refresh_token`, or `null` if the refresh failed.
 	*/
 	async refreshToken(refreshToken) {
+		const outcome = await this.attemptRefresh(refreshToken);
+		return outcome.status === "refreshed" ? outcome : null;
+	}
+	/**
+	* Exchange a refresh token for a new JWT and report why it failed, if it did.
+	*
+	* @param refreshToken - The opaque refresh token.
+	* @returns `refreshed` with the new tokens, `rejected` when the server refused
+	* the token, or `unavailable` when it gave no verdict (408, 429, 5xx, network
+	* error). Only `rejected` should end a session.
+	*/
+	async attemptRefresh(refreshToken) {
 		try {
 			const response = await fetch(`${this.config.baseUrl}/api/proxy/token/refresh`, {
 				method: "POST",
@@ -742,10 +760,13 @@ var AuthGateClient = class {
 				},
 				body: JSON.stringify({ refresh_token: refreshToken })
 			});
-			if (!response.ok) return null;
-			return response.json();
+			if (response.ok) return {
+				status: "refreshed",
+				...await response.json()
+			};
+			return { status: response.status === 408 || response.status === 429 || response.status >= 500 ? "unavailable" : "rejected" };
 		} catch {
-			return null;
+			return { status: "unavailable" };
 		}
 	}
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/core",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Core client library for AuthGate — the OAuth proxy that handles provider configuration, token exchange, and user normalization so you don't have to.",
   "type": "module",
   "exports": {