chat 4.13.0 → 4.13.2

package/docs/api/markdown.mdx

@@ -0,0 +1,235 @@
+---
+title: Markdown
+description: AST builder functions and utilities for programmatic message formatting.
+type: reference
+---
+
+The SDK uses [mdast](https://github.com/syntax-tree/mdast) (Markdown AST) as the canonical format for message formatting. Each adapter converts the AST to the platform's native format.
+
+```typescript
+import {
+  root, paragraph, text, strong, emphasis, strikethrough,
+  inlineCode, codeBlock, link, blockquote,
+  parseMarkdown, stringifyMarkdown, toPlainText, walkAst,
+} from "chat";
+```
+
+## Node builders
+
+### root
+
+Root node — the required top-level wrapper for an AST.
+
+```typescript
+root([
+  paragraph([text("Hello, world!")]),
+])
+```
+
+<TypeTable
+  type={{
+    children: {
+      description: 'Top-level content nodes (paragraphs, code blocks, blockquotes, lists).',
+      type: 'Content[]',
+    },
+  }}
+/>
+
+### paragraph
+
+A paragraph block.
+
+```typescript
+paragraph([text("Hello "), strong([text("world")])])
+```
+
+### text
+
+Plain text node.
+
+```typescript
+text("Hello, world!")
+```
+
+### strong
+
+**Bold** text.
+
+```typescript
+strong([text("important")])
+```
+
+### emphasis
+
+_Italic_ text.
+
+```typescript
+emphasis([text("emphasized")])
+```
+
+### strikethrough
+
+~~Strikethrough~~ text.
+
+```typescript
+strikethrough([text("removed")])
+```
+
+### inlineCode
+
+`Inline code` span.
+
+```typescript
+inlineCode("const x = 1")
+```
+
+### codeBlock
+
+Fenced code block with optional language.
+
+```typescript
+codeBlock("const x = 1;", "typescript")
+```
+
+<TypeTable
+  type={{
+    value: {
+      description: 'Code content.',
+      type: 'string',
+    },
+    lang: {
+      description: 'Language identifier for syntax highlighting.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+### link
+
+Hyperlink.
+
+```typescript
+link("https://example.com", [text("click here")])
+link("https://example.com", [text("click here")], "tooltip title")
+```
+
+<TypeTable
+  type={{
+    url: {
+      description: 'Link URL.',
+      type: 'string',
+    },
+    children: {
+      description: 'Link text content.',
+      type: 'Content[]',
+    },
+    title: {
+      description: 'Optional tooltip text.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+### blockquote
+
+Block quotation.
+
+```typescript
+blockquote([paragraph([text("Quoted text")])])
+```
+
+## Parsing and stringifying
+
+### parseMarkdown
+
+Parse a markdown string into an mdast AST.
+
+```typescript
+const ast = parseMarkdown("**Hello** world");
+```
+
+### stringifyMarkdown
+
+Convert an mdast AST back to a markdown string.
+
+```typescript
+const md = stringifyMarkdown(ast); // "**Hello** world"
+```
+
+### toPlainText
+
+Strip all formatting and return plain text.
+
+```typescript
+const plain = toPlainText(ast); // "Hello world"
+```
+
+### markdownToPlainText
+
+Shorthand for parsing markdown and extracting plain text.
+
+```typescript
+const plain = markdownToPlainText("**Hello** world"); // "Hello world"
+```
+
+## AST utilities
+
+### walkAst
+
+Transform an AST by visiting each node. Return a new value to replace the node, or `undefined` to keep it unchanged.
+
+```typescript
+const transformed = walkAst(ast, (node) => {
+  if (isStrongNode(node)) {
+    return emphasis(getNodeChildren(node));
+  }
+  return undefined;
+});
+```
+
+### Type guards
+
+Functions for checking node types:
+
+| Guard | Matches |
+|-------|---------|
+| `isTextNode(node)` | Plain text |
+| `isParagraphNode(node)` | Paragraph |
+| `isStrongNode(node)` | Bold |
+| `isEmphasisNode(node)` | Italic |
+| `isDeleteNode(node)` | Strikethrough |
+| `isInlineCodeNode(node)` | Inline code |
+| `isCodeNode(node)` | Code block |
+| `isLinkNode(node)` | Link |
+| `isBlockquoteNode(node)` | Blockquote |
+| `isListNode(node)` | List |
+| `isListItemNode(node)` | List item |
+
+### getNodeChildren / getNodeValue
+
+Safely access node properties without type narrowing.
+
+```typescript
+const children = getNodeChildren(node); // Content[] | undefined
+const value = getNodeValue(node);       // string | undefined
+```
+
+## Platform formatting
+
+The SDK uses mdast as the canonical format and each adapter converts it to the platform's native syntax. You write standard markdown and the SDK handles the translation — but it helps to know how each platform renders common formatting.
+
+| Feature | Slack | Teams | Google Chat |
+|---------|-------|-------|-------------|
+| Bold | `*text*` | `**text**` | `*text*` |
+| Italic | `_text_` | `_text_` | `_text_` |
+| Strikethrough | `~text~` | `~~text~~` | `~text~` |
+| Code | `` `code` `` | `` `code` `` | `` `code` `` |
+| Code blocks | ```` ``` ```` | ```` ``` ```` | ```` ``` ```` |
+| Links | `<url\|text>` | `[text](url)` | `[text](url)` |
+| Lists | Supported | Supported | Supported |
+| Blockquotes | `>` | `>` | Simulated with `>` prefix |
+| Mentions | `<@USER>` | `<at>name</at>` | `<users/{id}>` |
+
+<Callout type="info">
+You don't need to worry about these differences when using the SDK — the AST builders and `parseMarkdown` handle conversion automatically. This table is useful if you're working with `raw` platform payloads or debugging formatting issues.
+</Callout>

package/docs/api/message.mdx

@@ -0,0 +1,163 @@
+---
+title: Message
+description: Normalized message format with text, AST, author, and metadata.
+type: reference
+---
+
+Incoming messages are normalized across all platforms into a consistent `Message` object.
+
+```typescript
+import { Message } from "chat";
+```
+
+## Properties
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Platform-specific message ID.',
+      type: 'string',
+    },
+    threadId: {
+      description: 'Thread ID in adapter:channel:thread format.',
+      type: 'string',
+    },
+    text: {
+      description: 'Plain text content with all formatting stripped.',
+      type: 'string',
+    },
+    formatted: {
+      description: 'mdast AST representation — the canonical format for processing.',
+      type: 'Root',
+    },
+    raw: {
+      description: 'Original platform-specific payload (escape hatch).',
+      type: 'unknown',
+    },
+    author: {
+      description: 'Message author info.',
+      type: 'Author',
+    },
+    metadata: {
+      description: 'Timestamps and edit status.',
+      type: 'MessageMetadata',
+    },
+    attachments: {
+      description: 'File attachments.',
+      type: 'Attachment[]',
+    },
+    isMention: {
+      description: 'Whether the bot was @-mentioned in this message.',
+      type: 'boolean | undefined',
+    },
+  }}
+/>
+
+## Author
+
+<TypeTable
+  type={{
+    userId: {
+      description: 'Platform-specific user ID.',
+      type: 'string',
+    },
+    userName: {
+      description: 'Username/handle for @-mentions.',
+      type: 'string',
+    },
+    fullName: {
+      description: 'Display name.',
+      type: 'string',
+    },
+    isBot: {
+      description: 'Whether the author is a bot.',
+      type: 'boolean | "unknown"',
+    },
+    isMe: {
+      description: 'Whether the author is this bot.',
+      type: 'boolean',
+    },
+  }}
+/>
+
+### How `isMe` works
+
+Each adapter detects whether a message came from the bot itself. The detection logic varies by platform:
+
+| Platform | Detection method |
+|----------|-----------------|
+| Slack | Checks `event.user === botUserId` (primary), then `event.bot_id === botId` (for `bot_message` subtypes). Both IDs are fetched during initialization via `auth.test`. |
+| Teams | Checks `activity.from.id === appId` (exact match), then checks if `activity.from.id` ends with `:{appId}` (handles `28:{appId}` format). |
+| Google Chat | Checks `message.sender.name === botUserId`. The bot user ID is learned dynamically from message annotations when the bot is first @-mentioned. |
+
+<Callout type="info">
+All adapters return `false` if the bot ID isn't known yet. This is a safe default that prevents the bot from ignoring messages it should process.
+</Callout>
+
+## MessageMetadata
+
+<TypeTable
+  type={{
+    dateSent: {
+      description: 'When the message was sent.',
+      type: 'Date',
+    },
+    edited: {
+      description: 'Whether the message has been edited.',
+      type: 'boolean',
+    },
+    editedAt: {
+      description: 'When the message was last edited.',
+      type: 'Date | undefined',
+    },
+  }}
+/>
+
+## Attachment
+
+<TypeTable
+  type={{
+    type: {
+      description: 'Attachment type.',
+      type: '"image" | "file" | "video" | "audio"',
+    },
+    url: {
+      description: 'URL to the file.',
+      type: 'string | undefined',
+    },
+    data: {
+      description: 'Binary data (if already fetched).',
+      type: 'Buffer | Blob | undefined',
+    },
+    name: {
+      description: 'Filename.',
+      type: 'string | undefined',
+    },
+    mimeType: {
+      description: 'MIME type.',
+      type: 'string | undefined',
+    },
+    size: {
+      description: 'File size in bytes.',
+      type: 'number | undefined',
+    },
+    'fetchData()': {
+      description: 'Fetch the attachment data. Handles platform auth automatically.',
+      type: '() => Promise<Buffer> | undefined',
+    },
+  }}
+/>
+
+## Serialization
+
+Messages can be serialized for workflow engines and external systems.
+
+```typescript
+// Serialize
+const json = message.toJSON();
+
+// Deserialize
+const restored = Message.fromJSON(json);
+```
+
+The serialized format converts `Date` fields to ISO strings and omits non-serializable fields like `data` buffers and `fetchData` functions.

package/docs/api/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "API Reference",
+  "pages": [
+    "index",
+    "chat",
+    "thread",
+    "channel",
+    "message",
+    "postable-message",
+    "cards",
+    "markdown",
+    "modals"
+  ]
+}

package/docs/api/modals.mdx

@@ -0,0 +1,222 @@
+---
+title: Modals
+description: Modal form components for collecting user input.
+type: reference
+---
+
+Modals display form dialogs that collect structured user input. Currently supported on Slack.
+
+```typescript
+import { Modal, TextInput, Select, RadioSelect, SelectOption } from "chat";
+```
+
+## Modal
+
+Top-level container for a form dialog. Open a modal from an `onAction` or `onSlashCommand` handler using `event.openModal()`.
+
+```typescript
+bot.onAction("open-form", async (event) => {
+  await event.openModal(
+    Modal({
+      callbackId: "feedback",
+      title: "Submit Feedback",
+      submitLabel: "Send",
+      children: [
+        TextInput({ id: "comment", label: "Comment", multiline: true }),
+      ],
+    })
+  );
+});
+```
+
+<TypeTable
+  type={{
+    callbackId: {
+      description: 'Unique ID for routing to onModalSubmit/onModalClose handlers.',
+      type: 'string',
+    },
+    title: {
+      description: 'Modal title displayed in the header.',
+      type: 'string',
+    },
+    submitLabel: {
+      description: 'Label for the submit button.',
+      type: 'string',
+      default: '"Submit"',
+    },
+    closeLabel: {
+      description: 'Label for the close/cancel button.',
+      type: 'string',
+      default: '"Cancel"',
+    },
+    notifyOnClose: {
+      description: 'Whether to fire onModalClose when the user dismisses the modal.',
+      type: 'boolean',
+      default: 'false',
+    },
+    privateMetadata: {
+      description: 'Arbitrary string passed through the modal lifecycle (e.g., JSON context).',
+      type: 'string',
+    },
+    children: {
+      description: 'Form input elements.',
+      type: 'ModalChild[]',
+    },
+  }}
+/>
+
+## TextInput
+
+A text input field.
+
+```typescript
+TextInput({
+  id: "name",
+  label: "Your name",
+  placeholder: "Enter your name",
+})
+
+TextInput({
+  id: "description",
+  label: "Description",
+  multiline: true,
+  maxLength: 500,
+  optional: true,
+})
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Input ID — used as the key in event.values.',
+      type: 'string',
+    },
+    label: {
+      description: 'Label displayed above the input.',
+      type: 'string',
+    },
+    placeholder: {
+      description: 'Placeholder text.',
+      type: 'string',
+    },
+    initialValue: {
+      description: 'Pre-filled value.',
+      type: 'string',
+    },
+    multiline: {
+      description: 'Render as a textarea.',
+      type: 'boolean',
+      default: 'false',
+    },
+    optional: {
+      description: 'Whether the field can be left empty.',
+      type: 'boolean',
+      default: 'false',
+    },
+    maxLength: {
+      description: 'Maximum character length.',
+      type: 'number',
+    },
+  }}
+/>
+
+## Select
+
+Dropdown menu.
+
+```typescript
+Select({
+  id: "priority",
+  label: "Priority",
+  placeholder: "Select priority",
+  options: [
+    SelectOption({ label: "High", value: "high", description: "Urgent tasks" }),
+    SelectOption({ label: "Medium", value: "medium" }),
+    SelectOption({ label: "Low", value: "low" }),
+  ],
+})
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Input ID — used as the key in event.values.',
+      type: 'string',
+    },
+    label: {
+      description: 'Label displayed above the select.',
+      type: 'string',
+    },
+    placeholder: {
+      description: 'Placeholder text.',
+      type: 'string',
+    },
+    initialOption: {
+      description: 'Pre-selected option value.',
+      type: 'string',
+    },
+    optional: {
+      description: 'Whether the field can be left empty.',
+      type: 'boolean',
+      default: 'false',
+    },
+    options: {
+      description: 'Select options.',
+      type: 'SelectOptionElement[]',
+    },
+  }}
+/>
+
+## RadioSelect
+
+Radio button group for mutually exclusive choices.
+
+```typescript
+RadioSelect({
+  id: "status",
+  label: "Status",
+  options: [
+    SelectOption({ label: "Open", value: "open" }),
+    SelectOption({ label: "Closed", value: "closed" }),
+  ],
+})
+```
+
+Same props as `Select` (except `placeholder`).
+
+## SelectOption
+
+An option used inside `Select` and `RadioSelect`.
+
+```typescript
+SelectOption({ label: "High", value: "high", description: "Urgent tasks" })
+```
+
+<TypeTable
+  type={{
+    label: {
+      description: 'Display text.',
+      type: 'string',
+    },
+    value: {
+      description: 'Value sent in event.values when selected.',
+      type: 'string',
+    },
+    description: {
+      description: 'Optional description shown below the label.',
+      type: 'string',
+    },
+  }}
+/>
+
+## ModalChild types
+
+The `children` array in `Modal` accepts these element types:
+
+| Type | Created by |
+|------|-----------|
+| `TextInputElement` | `TextInput()` |
+| `SelectElement` | `Select()` |
+| `RadioSelectElement` | `RadioSelect()` |
+| `TextElement` | `Text()` — static text content |
+| `FieldsElement` | `Fields()` — key-value display |