Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Package: chat.api
Type: Package
Title: Transport-Agnostic Chat Contract
Version: 0.2.0
Date: 2026-11-10
Version: 0.2.0.1
Date: 2026-11-18
Authors@R: c(
person("Troy", "Hernandez", role = c("aut", "cre"),
email = "troy@cornball.ai",
Expand Down
12 changes: 12 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# chat.api 0.2.0.1

* `chat_send()` and `chat_edit()` take `content`, a named list of keys
for the message's own content: data a consumer's client reads and
other clients ignore. On Matrix the keys go beside the body, in
cleartext and encrypted rooms alike, and an edit carries them in its
new content. A key chat.api writes itself is refused before anything
is sent. Slack, Telegram and IRC take the argument and ignore it.
* A received Matrix message's `raw` carries the event's whole content in
`raw$content`, for text and pictures, in cleartext and encrypted
rooms. A cleartext message's `raw` had no `content` before.

# chat.api 0.2.0

* Send encrypted Matrix attachments using the adapter's existing crypto
Expand Down
61 changes: 58 additions & 3 deletions R/contract.R
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,22 @@ chat_poll <- function(client, since = NULL, timeout = NULL, ...) {
#' nothing else.
#' @param notify Logical; FALSE requests a silent delivery where
#' supported.
#' @param content Keys of the caller's own for the message's content, as
#' a named list, or NULL. Matrix adds them to the \code{m.room.message}
#' content beside \code{body} and \code{msgtype}, inside the ciphertext
#' in an encrypted room, so a consumer can carry data its own client
#' reads and every other client ignores, under a namespaced key such
#' as \code{"ai.cornball.agent"}. A received message carries its
#' content in \code{raw$content}, and the loopback adapter records
#' these keys there too; the other adapters ignore them, as they
#' ignore \code{rich}, so \code{text} has to stand on its own.
#'
#' A key chat.api writes itself is refused: \code{body},
#' \code{msgtype}, \code{format}, \code{formatted_body},
#' \code{m.relates_to}, \code{m.mentions} and \code{m.new_content}.
#' \code{text}, \code{kind}, \code{rich}, \code{thread} and the
#' \code{mentions} option set those. With \code{files}, the keys go on
#' the text's event, not on the attachments'.
#' @param ... Adapter-specific options.
#' @return Character vector of the message ids this call created, in the
#' order they were sent, invisibly. Usually length one. A platform that
Expand All @@ -78,10 +94,38 @@ chat_poll <- function(client, since = NULL, timeout = NULL, ...) {
chat_send <- function(client, channel, text, markup = c("plain", "markdown"),
thread = NULL, reply_to = NULL, identity = NULL,
files = NULL, kind = "message", notify = TRUE,
rich = NULL, ...) {
rich = NULL, content = NULL, ...) {
UseMethod("chat_send")
}

# The keys chat_send() and chat_edit() write themselves, which a
# caller's content may not name. Each has an argument of its own, and a
# second way to set it would leave the two disagreeing on the wire.
CHAT_CONTENT_RESERVED <- c("body", "msgtype", "format", "formatted_body",
"m.relates_to", "m.mentions", "m.new_content")

# A caller's content keys, checked: NULL for none (an empty list is
# none too), or a named list whose names are distinct, non-empty and
# not chat.api's own.
chat_content_keys <- function(content) {
if (is.null(content) || (is.list(content) && !length(content))) {
return(NULL)
}
nms <- names(content)
if (!is.list(content) || is.null(nms) || anyNA(nms) ||
!all(nzchar(nms)) || anyDuplicated(nms)) {
stop("content must be NULL or a list with distinct names.",
call. = FALSE)
}
taken <- intersect(nms, CHAT_CONTENT_RESERVED)
if (length(taken)) {
stop("content may not set ", paste(taken, collapse = ", "),
", which chat.api writes itself. Use text, kind, rich, thread ",
"or mentions instead.", call. = FALSE)
}
content
}

#' Signal typing state in a channel
#'
#' Capability-gated: the default method is a no-op so adapters without
Expand Down Expand Up @@ -555,6 +599,11 @@ chat_disconnect.default <- function(client, ...) {
#' adapter-specific and may already be normalized by the transport
#' package (Matrix hands over an extracted record, not the timeline
#' event), so it is an escape hatch, not a guarantee of completeness.
#' One part is promised: a Matrix message, cleartext or decrypted,
#' carries its event's whole content in \code{raw$content}, with any
#' keys a sender added of its own (\code{\link{chat_send}}'s
#' \code{content}), and the loopback adapter records those keys
#' there.
#' @param attachments List of \code{\link{chat_attachment}} records,
#' or NULL. Inbound media: what a sent \code{files =} looks like
#' from the receiving side, on adapters whose
Expand Down Expand Up @@ -1186,6 +1235,12 @@ chat_relogin.default <- function(client, ...) {
#' the message was sent as: Matrix carries the msgtype inside the
#' replacement content, so editing an \code{m.notice} without saying so
#' turns it into an ordinary message.
#' @param content Keys of the caller's own for the replacement, as
#' \code{\link{chat_send}}. Matrix puts them in \code{m.new_content},
#' beside the replacement text, and in the fallback copy around it, as
#' it does the formatted text. Like the text, they replace the
#' original's: a key the edit does not repeat is gone from the edited
#' message.
#' @param ... Adapter-specific options.
#' @return The identifier of the event the edit created where the
#' platform makes one (Matrix), or of the edited message where it does
Expand All @@ -1205,14 +1260,14 @@ chat_relogin.default <- function(client, ...) {
#' @export
chat_edit <- function(client, channel, message_id, text,
markup = c("plain", "markdown"), rich = NULL,
kind = "message", ...) {
kind = "message", content = NULL, ...) {
UseMethod("chat_edit")
}

#' @export
chat_edit.default <- function(client, channel, message_id, text,
markup = c("plain", "markdown"), rich = NULL,
kind = "message", ...) {
kind = "message", content = NULL, ...) {
stop("chat_edit() is not supported by this adapter (",
paste(class(client), collapse = "/"),
"). Check chat_capabilities()$edits.", call. = FALSE)
Expand Down
2 changes: 1 addition & 1 deletion R/irc.R
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ chat_send.chat_irc <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE, rich = NULL,
...) {
content = NULL, ...) {
markup <- match.arg(markup)
verb <- if (identical(kind, "notice")) {
"NOTICE"
Expand Down
23 changes: 20 additions & 3 deletions R/loopback.R
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,9 @@ chat_send.chat_loopback <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE,
rich = NULL, ...) {
rich = NULL, content = NULL, ...) {
markup <- match.arg(markup)
content <- chat_content_keys(content)
attachments <- NULL
if (!is.null(files)) {
# A missing file errors rather than sending a message that
Expand All @@ -111,11 +112,22 @@ chat_send.chat_loopback <- function(client, channel, text,
else identity$name,
body = text, ts = Sys.time(), thread = thread,
markup = markup, kind = kind,
attachments = attachments)
attachments = attachments,
raw = loopback_raw(content))
client$env$log[[length(client$env$log) + 1L]] <- msg
invisible(id)
}

# A caller's content keys where a Matrix message carries its content,
# raw$content, so a consumer reads them the same way against the
# reference adapter and a homeserver. NULL when there are none.
loopback_raw <- function(content) {
if (is.null(content)) {
return(NULL)
}
list(content = content)
}

#' @export
chat_download.chat_loopback <- function(client, attachment, dest = NULL, ...) {
dest <- attachment_dest(attachment, dest)
Expand Down Expand Up @@ -224,8 +236,10 @@ chat_history.chat_loopback <- function(client, channel, limit = 50L,
#' @export
chat_edit.chat_loopback <- function(client, channel, message_id, text,
markup = c("plain", "markdown"),
rich = NULL, kind = "message", ...) {
rich = NULL, kind = "message",
content = NULL, ...) {
markup <- match.arg(markup)
content <- chat_content_keys(content)
pos <- which(vapply(client$env$log,
function(m) identical(m$id, message_id), logical(1)))
if (!length(pos)) {
Expand All @@ -238,6 +252,9 @@ chat_edit.chat_loopback <- function(client, channel, message_id, text,
msg <- client$env$log[[pos[[1L]]]]
msg$body <- text
msg$markup <- markup
# The edit's keys replace the original's, as on Matrix, where the
# edited message is m.new_content and nothing else.
msg["raw"] <- list(loopback_raw(content))
client$env$log[[pos[[1L]]]] <- msg
invisible(message_id)
}
Loading
Loading