Auto-generate TypeScript JSDoc with AI

export async function refreshAuthToken(
  token: string,
  options?: { force?: boolean; audience?: string }
): Promise<AuthToken> {
  const decoded = verifyToken(token);
  if (!options?.force && !isNearExpiry(decoded)) return { token, refreshed: false };
  const newToken = await issueToken(decoded.userId, options?.audience);
  await invalidateToken(token);
  return { token: newToken, refreshed: true };
}

/**
 * Refreshes a JWT authentication token if it is near expiry or forced.
 *
 * Verifies the existing token, then checks whether it is within the
 * refresh window (see {@link isNearExpiry}). If not near expiry and
 * `force` is false, returns the original token unchanged. Otherwise,
 * issues a new token scoped to the optional audience, invalidates the
 * old one, and returns the replacement.
 *
 * @param token - The existing JWT to evaluate for refresh.
 * @param options - Optional refresh configuration.
 * @param options.force - If true, refresh unconditionally. Defaults to false.
 * @param options.audience - OAuth audience for the new token. Inherits
 *   from the existing token if omitted.
 * @returns Resolves to an `AuthToken` containing the (possibly new)
 *   token string and a `refreshed` flag indicating whether a new
 *   token was issued.
 */
export async function refreshAuthToken(