mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Install matrix-bot-sdk and create MatrixService skeleton #378

New Issue
Closed
opened 2026-02-15 07:00:32 +00:00 by jason.woltje · 1 comment
jason.woltje commented 2026-02-15 07:00:32 +00:00
Owner
Copy Link

Summary

Add matrix-bot-sdk dependency and create MatrixService implementing IChatProvider interface.

Implementation

Install dependency

cd apps/api && npm install matrix-bot-sdk

Create files

  • apps/api/src/bridge/matrix/matrix.service.ts — Implements IChatProvider
  • apps/api/src/bridge/matrix/matrix.service.spec.ts — Unit tests

MatrixService must implement:

export class MatrixService implements IChatProvider {
  connect(): Promise<void>;        // Login to homeserver via access token
  disconnect(): Promise<void>;     // Graceful shutdown
  isConnected(): boolean;          // Connection status
  sendMessage(roomId, content);    // Send to Matrix room
  createThread(options);           // Create Matrix thread (or use room)
  sendThreadMessage(options);      // Reply in thread
  parseCommand(message);           // Delegate to shared CommandParser
}

Environment variables

  • MATRIX_HOMESERVER_URL — e.g., https://matrix.mosaicstack.dev
  • MATRIX_ACCESS_TOKEN — Bot account access token
  • MATRIX_BOT_USER_ID — e.g., @mosaic:mosaicstack.dev
  • MATRIX_CONTROL_ROOM_ID — Room to listen for commands

Connection pattern

  • Use MatrixClient from matrix-bot-sdk
  • Auto-join on invite (for workspace rooms)
  • Sync loop for receiving messages
  • Filter for @mosaic or !mosaic command prefix

Acceptance Criteria

  • matrix-bot-sdk installed in apps/api
  • MatrixService implements IChatProvider interface
  • Unit tests with mocked Matrix client
  • Service connects/disconnects cleanly
  • Environment variables documented in .env.example

Refs

## Summary Add `matrix-bot-sdk` dependency and create `MatrixService` implementing `IChatProvider` interface. ## Implementation ### Install dependency ```bash cd apps/api && npm install matrix-bot-sdk ``` ### Create files - `apps/api/src/bridge/matrix/matrix.service.ts` — Implements `IChatProvider` - `apps/api/src/bridge/matrix/matrix.service.spec.ts` — Unit tests ### MatrixService must implement: ```typescript export class MatrixService implements IChatProvider { connect(): Promise<void>; // Login to homeserver via access token disconnect(): Promise<void>; // Graceful shutdown isConnected(): boolean; // Connection status sendMessage(roomId, content); // Send to Matrix room createThread(options); // Create Matrix thread (or use room) sendThreadMessage(options); // Reply in thread parseCommand(message); // Delegate to shared CommandParser } ``` ### Environment variables - `MATRIX_HOMESERVER_URL` — e.g., `https://matrix.mosaicstack.dev` - `MATRIX_ACCESS_TOKEN` — Bot account access token - `MATRIX_BOT_USER_ID` — e.g., `@mosaic:mosaicstack.dev` - `MATRIX_CONTROL_ROOM_ID` — Room to listen for commands ### Connection pattern - Use `MatrixClient` from matrix-bot-sdk - Auto-join on invite (for workspace rooms) - Sync loop for receiving messages - Filter for `@mosaic` or `!mosaic` command prefix ## Acceptance Criteria - [ ] `matrix-bot-sdk` installed in apps/api - [ ] MatrixService implements IChatProvider interface - [ ] Unit tests with mocked Matrix client - [ ] Service connects/disconnects cleanly - [ ] Environment variables documented in .env.example ## Refs - Existing pattern: `apps/api/src/bridge/discord/discord.service.ts` - Interface: `apps/api/src/bridge/interfaces/chat-provider.interface.ts` - EPIC: #377
jason.woltje added the apiapi labels 2026-02-15 07:00:32 +00:00
jason.woltje added this to the M12-MatrixBridge (0.0.12) milestone 2026-02-15 07:01:51 +00:00
jason.woltje commented 2026-02-15 08:30:12 +00:00
Author
Owner
Copy Link

Completed in commit 5b5d381 on branch feature/m12-matrix-bridge.

  • Installed matrix-bot-sdk v0.8.0
  • Created MatrixService implementing IChatProvider
  • Connection management, thread support (MSC3440), command parsing
  • 20+ unit tests passing
Completed in commit 5b5d381 on branch feature/m12-matrix-bridge. - Installed matrix-bot-sdk v0.8.0 - Created MatrixService implementing IChatProvider - Connection management, thread support (MSC3440), command parsing - 20+ unit tests passing
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ai
AI/LLM integration
 api
Backend/API work
 api
auth
Authentication
 database
database
Database/schema work
 devops
Docker/deployment
 docs
Documentation
 frontend
graph
knowledge-module
migration
Data migration
 orchestrator
Orchestrator service (apps/orchestrator/)
 p0
Critical priority
 p1
High priority
 p2
Medium priority
 p3
Low priority
 performance
Performance work
 phase-1
phase-2
phase-3
phase-4
phase-5
plugin
MoltBot plugin work
 search
security
Security-related
 setup
Initial setup
 testing
Testing/QA
 web
Frontend work
No Label api api
Milestone
No items
No Milestone M12-MatrixBridge (0.0.12)
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaic/stack#378
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?