@rmdes/indiekit-endpoint-conversations

Conversation aggregation endpoint for Indiekit. Polls Mastodon, Bluesky, and ActivityPub notifications, stores interactions in MongoDB, and serves them as a JF2-compatible API — including threaded owner replies.

Features

• Multi-platform polling — Mastodon, Bluesky, and native ActivityPub (via Fedify)
• JF2 API — serves likes, reposts, and replies in webmention-compatible format
• Owner reply threading — enriches API responses with the site owner's replies from the posts collection, with threading metadata
• Webmention ingestion — accepts incoming webmentions from Bridgy or external services
• Admin dashboard — connection status, polling stats, platform health
• Syndication URL matching — resolves canonical post URLs from syndicated copies

Installation

npm install @rmdes/indiekit-endpoint-conversations

// indiekit.config.js
import ConversationsEndpoint from "@rmdes/indiekit-endpoint-conversations";

export default {
  plugins: [
    new ConversationsEndpoint({
      mountPath: "/conversations",
    }),
  ],
};

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MASTODON_ACCESS_TOKEN | For Mastodon | Mastodon API access token | | MASTODON_URL or MASTODON_INSTANCE | For Mastodon | Mastodon instance URL | | BLUESKY_IDENTIFIER or BLUESKY_HANDLE | For Bluesky | Bluesky account identifier | | BLUESKY_PASSWORD | For Bluesky | Bluesky app password | | AUTHOR_NAME | Optional | Owner display name (falls back to site hostname) | | AUTHOR_AVATAR | Optional | Owner avatar URL |

ActivityPub polling is auto-detected when @rmdes/indiekit-endpoint-activitypub is installed.

API

GET /conversations/api/mentions

Returns interactions for a target URL in JF2 feed format. Compatible with the webmention.io API shape used by @chrisburnell/eleventy-cache-webmentions.

Parameters:

| Param | Type | Description | |-------|------|-------------| | target | string | Target URL to fetch interactions for | | wm-property | string | Filter by type: like-of, repost-of, in-reply-to | | per-page | number | Results per page (default: 50, max: 100) | | page | number | Page number (default: 0) |

Response:

{
  "type": "feed",
  "name": "Conversations",
  "children": [
    {
      "type": "entry",
      "wm-id": "conv-mastodon:12345",
      "wm-property": "in-reply-to",
      "wm-target": "https://example.com/posts/hello",
      "author": {
        "type": "card",
        "name": "Jane Doe",
        "url": "https://mastodon.social/@jane",
        "photo": "https://..."
      },
      "url": "https://mastodon.social/@jane/67890",
      "published": "2026-03-11T16:19:52.652Z",
      "platform": "mastodon",
      "content": {
        "html": "<p>Great post!</p>",
        "text": "Great post!"
      }
    },
    {
      "type": "entry",
      "wm-id": "owner-reply-abc123",
      "wm-property": "in-reply-to",
      "wm-target": "https://example.com/posts/hello",
      "author": {
        "type": "card",
        "name": "Site Owner",
        "url": "https://example.com",
        "photo": "https://..."
      },
      "url": "https://example.com/replies/2026/03/11/65e12",
      "published": "2026-03-11T17:00:00.000Z",
      "content": {
        "html": "<p>Thanks!</p>",
        "text": "Thanks!"
      },
      "is_owner": true,
      "parent_url": "https://mastodon.social/@jane/67890"
    }
  ]
}

Owner Reply Enrichment

When the API returns replies (wm-property: "in-reply-to"), it checks the Indiekit posts collection for owner posts whose properties.in-reply-to matches any reply's url. Matching owner posts are appended to the response with two extra fields:

| Field | Type | Description | |-------|------|-------------| | is_owner | boolean | Always true for owner replies | | parent_url | string | The URL of the interaction this reply responds to |

The frontend uses parent_url to thread the owner's reply under the correct parent interaction. See indiekit-eleventy-theme for the client-side threading implementation.

GET /conversations/api/status

Returns connection health and platform status.

POST /conversations/ingest

Accepts incoming webmentions. Body: { source, target }.

POST /conversations/poll (authenticated)

Triggers an immediate poll of all configured platforms.

Architecture

Mastodon API ──┐
Bluesky API  ──┼──> Scheduler ──> conversation_items (MongoDB)
ActivityPub  ──┘                         │
                                         v
               GET /api/mentions ──> JF2 response
                                    + owner reply enrichment
                                      (from posts collection)

Collections

| Collection | Purpose | |------------|---------| | conversation_items | Stored interactions (likes, reposts, replies) | | conversation_state | Polling state (last poll timestamps, cursors) |

Dependencies

• @rmdes/indiekit-endpoint-activitypub — Optional. When installed, the scheduler also polls native ActivityPub interactions from the ap_interactions collection.
• indiekit-eleventy-theme — The theme's webmentions.js consumes the /api/mentions endpoint and threads owner replies using the is_owner and parent_url fields.
• @rmdes/indiekit-endpoint-comments — Handles native comment replies (not platform interactions). Owner replies to native comments go through the comments API, not this plugin.

License

MIT