mx_set_displayname: client-level profile rename with relogin

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: mx.client
 Type: Package
 Title: Stateful Matrix Client Helpers
-Version: 0.1.1
+Version: 0.1.1.1
 Date: 2026-06-13
 Authors@R: c(
     person("Troy", "Hernandez", role = c("aut", "cre"),

NAMESPACE

@@ -37,5 +37,6 @@ export(mx_room_lookup_by_name)
 export(mx_send_encrypted)
 export(mx_send_media)
 export(mx_send_text)
+export(mx_set_displayname)
 export(mx_sync_update)
 export(mx_with_relogin)

NEWS.md

@@ -1,3 +1,13 @@
+# mx.client 0.1.1.1
+
+* New `mx_set_displayname(client, name)`: client-level wrapper over
+  `mx.api::mx_set_displayname()` that builds the session from the
+  client config and retries once through `mx_with_relogin()` on a
+  rejected token, so long-running bots can rename themselves without
+  hand-rolling session or relogin plumbing. Extracted from corteza's
+  Matrix model badge (corteza#155), which keeps the badge policy and
+  calls this for the profile update.
+
 # mx.client 0.1.1
 
 * First release. Stateful client layer over 'mx.api': configuration

R/profile.R

@@ -0,0 +1,34 @@
+# Profile operations: client-level wrappers over mx.api's profile
+# endpoints, so callers hand in the client config and get token
+# rotation handled instead of building sessions by hand.
+
+#' Set the account's profile display name
+#'
+#' Client-level wrapper over \code{mx.api::mx_set_displayname()}: builds
+#' the session from the client config and retries once through
+#' \code{\link{mx_with_relogin}} when the homeserver rejects a rotated
+#' token. The display name is account-global and shows in the sender
+#' line of every message the account posts.
+#'
+#' @param client Matrix client config.
+#' @param name Character. New display name.
+#' @param save Logical. On a relogin, persist the refreshed token to the
+#'   client's config path (see \code{\link{mx_client_relogin}}).
+#' @return TRUE, invisibly.
+#' @examples
+#' \dontrun{
+#' # A real rename needs a live homeserver session:
+#' client <- mx_client_load("myapp")
+#' mx_set_displayname(client, "mybot (maintenance)")
+#' }
+#' @export
+mx_set_displayname <- function(client, name, save = TRUE) {
+    if (!is.character(name) || length(name) != 1L || is.na(name) ||
+            !nzchar(name)) {
+        stop("name must be a single non-empty string", call. = FALSE)
+    }
+    mx_with_relogin(client, function(cl) {
+        mx.api::mx_set_displayname(mx_client_session(cl), name)
+    }, save = save)
+    invisible(TRUE)
+}

inst/tinytest/test_relogin.R

@@ -35,3 +35,10 @@ expect_message(
   "dry-run"
 )
 expect_null(out)
+
+# mx_set_displayname: signature, validation, and relogin plumbing
+expect_equal(names(formals(mx.client::mx_set_displayname)),
+             c("client", "name", "save"))
+expect_error(mx.client::mx_set_displayname(cl, ""), "non-empty")
+expect_error(mx.client::mx_set_displayname(cl, c("a", "b")), "single")
+expect_error(mx.client::mx_set_displayname(cl, NA_character_), "non-empty")

man/mx_set_displayname.Rd

@@ -0,0 +1,32 @@
+% tinyrox says don't edit this manually, but it can't stop you!
+\name{mx_set_displayname}
+\alias{mx_set_displayname}
+\title{Set the account's profile display name}
+\usage{
+mx_set_displayname(client, name, save = TRUE)
+}
+\arguments{
+\item{client}{Matrix client config.}
+
+\item{name}{Character. New display name.}
+
+\item{save}{Logical. On a relogin, persist the refreshed token to the
+client's config path (see \code{\link{mx_client_relogin}}).}
+}
+\value{
+TRUE, invisibly.
+}
+\description{
+Client-level wrapper over \code{mx.api::mx_set_displayname()}: builds
+the session from the client config and retries once through
+\code{\link{mx_with_relogin}} when the homeserver rejects a rotated
+token. The display name is account-global and shows in the sender
+line of every message the account posts.
+}
+\examples{
+\dontrun{
+# A real rename needs a live homeserver session:
+client <- mx_client_load("myapp")
+mx_set_displayname(client, "mybot (maintenance)")
+}
+}