Documentation
¶
Overview ¶
Package format converts Microsoft Teams message bodies into the markdown the CLI renders.
PLAN.md puts both directions here, but only the read half exists: Phase 3 needs HTML -> markdown, which is what this file implements as a port of the MCP's htmlToMarkdown (refs/teams-mcp/src/utils/html-to-markdown.ts) on top of github.com/JohannesKaufmann/html-to-markdown/v2 (PLAN.md "Toolchain and local workflow" — it replaces Turndown). markdown -> HTML and mention *generation* are Phase 4 (PLAN.md line 179, "sanitize before inserting <at>") and are deliberately absent: nothing here writes a body for Graph.
Three kinds of element need handling before or during the conversion, because no HTML specification knows them:
- <at id="N">mentionText</at>, the tag that carries a chatMessageMention (refs/graph/api-reference/v1.0/resources/chatmessagemention.md),
- <attachment id="...">, which references a chatMessageAttachment (refs/graph/api-reference/v1.0/resources/chatmessageattachment.md),
- <systemEventMessage/>, the body of a messageType "systemEventMessage" (refs/graph/api-reference/v1.0/resources/chatmessage.md).
Where a behaviour comes from the MCP rather than from a reference document, the comment says so and marks it as observed, not documented (PLAN.md line 222). Nothing in this package is global state: every conversion builds its own converter.
Index ¶
- Constants
- func BodyToMarkdown(content, contentType string, names map[int]string) (string, error)
- func DetectContentType(name string, data []byte) string
- func EscapeText(text string) string
- func HTMLToMarkdown(raw string) (string, error)
- func HTMLToMarkdownWithMentions(raw string, names map[int]string) (string, error)
- func ImageExtension(contentType string) string
- func IsImageContentType(contentType string) bool
- func MarkdownToHTML(markdown string) (string, error)
- func MentionNames(mentions []Mention) map[int]string
- func ParagraphHTML(text string) string
- func SanitizeHTML(html string) string
- type Mention
- type MentionEntry
- type MentionTarget
- type UnmatchedMentionError
Constants ¶
const DefaultContentType = "application/octet-stream"
DefaultContentType is what an unrecognised file is sent as, which is also what the MCP falls back to (refs/teams-mcp/src/utils/content-type.ts:50).
Variables ¶
This section is empty.
Functions ¶
func BodyToMarkdown ¶
BodyToMarkdown converts either itemBody shape ("html" or "text").
The contentType is matched case-insensitively and tolerantly: it is an enum of the two values above, and a body whose type we do not recognise is converted as HTML, the form that carries mentions.
A "text" body is not markup, so nothing in it is translated; only whitespace is normalised, and — like every other path out of this package — the words "<at" and "<attachment" are kept from looking like an element. The reference documents do not describe mentions in a text body, and by the rule quoted above they cannot be there.
func DetectContentType ¶
DetectContentType names the type of a file, from its bytes and then its name.
The magic bytes are checked first, on the first 12 bytes at most; an unrecognised file falls back to its extension and then to DefaultContentType. Nothing here is a security decision: the type only says what a reader should do with the file, and Graph stores whatever it is told.
func EscapeText ¶
EscapeText escapes plain text so it can be embedded in an HTML body, the port of the MCP's escapeHtml (refs/teams-mcp/src/utils/file-upload.ts:337-344).
It is used for the `text` half of a message that is being posted with attachments: a file post always sends contentType "html", so the words the user typed as plain text have to be escaped into it, and `--text` plus `--file` is therefore not "no HTML conversion at all" but "the text, escaped and wrapped".
func HTMLToMarkdown ¶
HTMLToMarkdown converts a Teams message body with contentType "html".
It is HTMLToMarkdownWithMentions with no mentions[] array, which is all the body itself gives you: an <at> tag is named from its own text.
func HTMLToMarkdownWithMentions ¶
HTMLToMarkdownWithMentions is HTMLToMarkdown with the message's mentions[] array, which names <at id="N"> tags the body text does not.
names maps a mention id to a display name (see MentionNames) and is the only identity this direction gets. That matters for the merge port below: the MCP groups consecutive <at> tags by mentioned.user.id, which the body does not carry, so equal display names stand in for "same person".
The body is expected to be the HTML form. itemBody.contentType has two possible values, text and html (refs/graph/api-reference/v1.0/resources/itembody.md), and "The content is always in HTML if the chat message contains a chatMessageMention" (refs/graph/api-reference/v1.0/resources/chatmessage.md); BodyToMarkdown is the entry point that makes that choice.
The output is markdown, never HTML: a raw <at> or <attachment> tag cannot survive (both are rendered, not passed through), and malformed input is not an error, because an HTML parser recovers from anything. An empty or whitespace-only body is "".
func ImageExtension ¶
ImageExtension returns the file extension for an image type, used to name an inline image that arrived without a usable name (refs/teams-mcp/src/utils/attachments.ts:86-98).
func IsImageContentType ¶
IsImageContentType reports whether a type can be sent as an inline image (hosted content) rather than as a file attachment.
func MarkdownToHTML ¶
MarkdownToHTML converts markdown to the sanitized HTML a Teams message body carries, with contentType "html".
The result has no `<at>` tags: mentions are applied afterwards, to the sanitized body, because the sanitizer would drop them (PLAN.md:179).
A markdown string that is empty or only whitespace returns "", which the caller turns into the documented minimum of an empty body (Graph requires the `body` property to be present, but not its content to be non-empty).
func MentionNames ¶
MentionNames indexes mentions by their <at id="N"> id.
The result is the map HTMLToMarkdownWithMentions expects. Mentions whose display name is empty are skipped, because the body's own tag text is a better name than nothing; a later entry with the same id wins (the id is an index into mentions[], so duplicates are not expected).
An input without a usable name returns a nil map, which is the same "no mentions[] at all" case HTMLToMarkdown covers.
func ParagraphHTML ¶
ParagraphHTML wraps already-escaped text in a paragraph, so a plain-text message that carries an attachment reference still reads as prose.
func SanitizeHTML ¶
SanitizeHTML applies the Teams allow-list to an HTML body.
It is the path `--html` input takes, and it is also the step MarkdownToHTML ends with, so both spellings of a body go through exactly one policy. The result keeps every allowed element, drops the rest while keeping their text, and drops the content of script and style outright.
The output is not guaranteed to be well-formed for every input (bluemonday sanitizes a parsed tree and re-serializes it, so in practice it is), and the caller that needs well-formed HTML is ApplyMentions, which parses and re-renders the body anyway.
Types ¶
type Mention ¶
type Mention struct {
// ID is the mention's id property, which the body's <at> tag repeats.
ID int
// DisplayName is the name to render for that mention. Use the mentioned
// entity's display name (mentioned.user.displayName): it identifies the
// person, so two <at> tags that share it are one mention, and it also names
// a tag whose body text is empty.
DisplayName string
}
Mention is one chatMessageMention worth naming in the body.
The id is what ties a mention to the body: "Matches the {index} value in the corresponding <at id="{index}"> tag in the message body" (refs/graph/api-reference/v1.0/resources/chatmessagemention.md).
type MentionEntry ¶
type MentionEntry struct {
// ID is the mention's id, which is also the index inside the body's
// `<at id="N">` tag.
ID int
// UserID is mentioned.user.id.
UserID string
// DisplayName is both mentionText and mentioned.user.displayName.
DisplayName string
// TenantID is mentioned.user.tenantId, when known.
TenantID string
// Matched is the spelling found in the body. It is diagnostics only: it is
// what the user typed, and it is not sent to Graph.
Matched string
}
MentionEntry is one element of a message's `mentions[]` array (refs/graph/api-reference/v1.0/resources/chatmessagemention.md).
The caller renders it as the Graph payload; the field names here describe the values, and the JSON shape lives in internal/graph.
func ApplyMentions ¶
func ApplyMentions(body string, targets []MentionTarget) (string, []MentionEntry, error)
ApplyMentions replaces the targets' text with `<at id="N">` tags and returns the body plus the `mentions[]` entries in id order.
A body that names nobody gets "", nil and no error, and the caller then sends no `mentions` property at all: the array is optional (refs/graph/api-reference/v1.0/api/chatmessage-post.md:47).
type MentionTarget ¶
type MentionTarget struct {
// UserID is the mentioned user's id. It is required: it is the only thing
// in the payload that identifies the person.
UserID string
// DisplayName is the name Teams shows for the mention and the text the
// `<at>` tag carries.
DisplayName string
// TenantID is optional; the documented example omits it.
TenantID string
// Handles are the spellings to match, without the "@".
Handles []string
}
MentionTarget is one person a body should mention.
Handles are the spellings to look for, most specific first, each *without* the leading "@" ("alice@example.com", "Alice Example", "alice"). The first one that occurs in the body wins; the others are then irrelevant for that person. A handle is matched case-insensitively, and only as a whole token: `@alice` does not match inside `@alicebob` or inside an e-mail address.
type UnmatchedMentionError ¶
type UnmatchedMentionError struct {
// DisplayName names the person, for the message.
DisplayName string
// UserID is the person's id, for when the display name is empty.
UserID string
// Handles lists the spellings that were tried.
Handles []string
}
UnmatchedMentionError reports a mention target whose text is nowhere in the body. It is a usage mistake (the user asked to mention someone the body does not name), so the CLI turns it into exit code 2.
func (*UnmatchedMentionError) Error ¶
func (e *UnmatchedMentionError) Error() string
Error implements error.