@alkemio/matrix-adapter-lib 0.6.2 → 0.8.0

package/README.md

@@ -1,3 +1,211 @@
-# matrix-adapter-lib
+# @alkem-io/matrix-adapter-go-lib
 
-Library of types for working with the Alkemio matrix adapter service.
+TypeScript library providing type-safe DTOs and event types for interacting with the Alkemio Matrix Adapter service.
+
+## Installation
+
+```bash
+# npm
+npm install @alkem-io/matrix-adapter-go-lib
+
+# pnpm
+pnpm add @alkem-io/matrix-adapter-go-lib
+
+# yarn
+yarn add @alkem-io/matrix-adapter-go-lib
+```
+
+## Usage
+
+### Event Types
+
+Use `MatrixAdapterEventType` enum for RabbitMQ topic routing:
+
+```typescript
+import { MatrixAdapterEventType } from '@alkem-io/matrix-adapter-go-lib';
+
+// Subscribe to commands
+consumer.subscribe(MatrixAdapterEventType.COMMUNICATION_ROOM_CREATE);
+consumer.subscribe(MatrixAdapterEventType.COMMUNICATION_SPACE_CREATE);
+
+// Listen for events
+consumer.subscribe(MatrixAdapterEventType.COMMUNICATION_MESSAGE_RECEIVED);
+```
+
+### Request/Response DTOs
+
+All command payloads and responses are fully typed:
+
+```typescript
+import {
+  CreateRoomRequest,
+  CreateRoomResponse,
+  RoomTypeCommunity,
+  JoinRuleInvite,
+  BaseResponse,
+  ErrCodeRoomNotFound,
+} from '@alkem-io/matrix-adapter-go-lib';
+
+// Build a request
+const request: CreateRoomRequest = {
+  alkemio_room_id: 'uuid-v4-or-v7',
+  type: RoomTypeCommunity,
+  name: 'My Room',
+  initial_members: ['actor-uuid-1', 'actor-uuid-2'],
+  join_rule: JoinRuleInvite,
+};
+
+// Handle response
+function handleResponse(response: CreateRoomResponse) {
+  if (response.BaseResponse.success) {
+    console.log('Room created');
+  } else {
+    const error = response.BaseResponse.error;
+    if (error?.code === ErrCodeRoomNotFound) {
+      console.error('Room not found:', error.message);
+    }
+  }
+}
+```
+
+### Space Operations (Protocol V3)
+
+```typescript
+import {
+  CreateSpaceRequest,
+  GetSpaceResponse,
+  SetParentRequest,
+  BatchAddSpaceMemberRequest,
+  JoinRuleRestricted,
+} from '@alkem-io/matrix-adapter-go-lib';
+
+// Create a space with hierarchy
+const spaceRequest: CreateSpaceRequest = {
+  alkemio_context_id: 'context-uuid',
+  name: 'My Space',
+  parent_context_id: 'parent-context-uuid',
+  join_rule: JoinRuleRestricted,
+  initial_members: ['actor-uuid'],
+};
+
+// Set parent-child relationship
+const hierarchyRequest: SetParentRequest = {
+  child_id: 'room-or-space-uuid',
+  is_space: false, // true for subspaces, false for rooms
+  parent_context_id: 'parent-space-uuid',
+};
+
+// Batch membership operations
+const batchRequest: BatchAddSpaceMemberRequest = {
+  actor_id: 'actor-uuid',
+  alkemio_context_ids: ['space-1', 'space-2', 'space-3'],
+};
+```
+
+## API Reference
+
+### Event Types
+
+| Event | Topic | Description |
+|-------|-------|-------------|
+| `COMMUNICATION_ROOM_CREATE` | `communication.room.create` | Create a room |
+| `COMMUNICATION_ROOM_GET` | `communication.room.get` | Get room details |
+| `COMMUNICATION_ROOM_UPDATE` | `communication.room.update` | Update room metadata |
+| `COMMUNICATION_ROOM_DELETE` | `communication.room.delete` | Delete a room |
+| `COMMUNICATION_ROOM_LIST` | `communication.room.list` | List all rooms |
+| `COMMUNICATION_ROOM_MEMBERS_GET` | `communication.room.members.get` | Get room members |
+| `COMMUNICATION_ROOM_MEMBER_BATCH_ADD` | `communication.room.member.batch.add` | Add actor to rooms |
+| `COMMUNICATION_ROOM_MEMBER_BATCH_REMOVE` | `communication.room.member.batch.remove` | Remove actor from rooms |
+| `COMMUNICATION_SPACE_CREATE` | `communication.space.create` | Create a space |
+| `COMMUNICATION_SPACE_GET` | `communication.space.get` | Get space details |
+| `COMMUNICATION_SPACE_UPDATE` | `communication.space.update` | Update space metadata |
+| `COMMUNICATION_SPACE_DELETE` | `communication.space.delete` | Delete a space |
+| `COMMUNICATION_SPACE_LIST` | `communication.space.list` | List all spaces |
+| `COMMUNICATION_SPACE_MEMBER_BATCH_ADD` | `communication.space.member.batch.add` | Add actor to spaces |
+| `COMMUNICATION_SPACE_MEMBER_BATCH_REMOVE` | `communication.space.member.batch.remove` | Remove actor from spaces |
+| `COMMUNICATION_HIERARCHY_SET_PARENT` | `communication.hierarchy.set_parent` | Set parent-child relationship |
+| `COMMUNICATION_MESSAGE_SEND` | `communication.message.send` | Send a message |
+| `COMMUNICATION_MESSAGE_GET` | `communication.message.get` | Get message details |
+| `COMMUNICATION_MESSAGE_DELETE` | `communication.message.delete` | Delete a message |
+| `COMMUNICATION_REACTION_ADD` | `communication.reaction.add` | Add reaction |
+| `COMMUNICATION_REACTION_REMOVE` | `communication.reaction.remove` | Remove reaction |
+| `COMMUNICATION_REACTION_GET` | `communication.reaction.get` | Get reaction details |
+| `COMMUNICATION_THREAD_MESSAGES_GET` | `communication.thread.messages.get` | Get thread messages |
+| `COMMUNICATION_ACTOR_SYNC` | `communication.actor.sync` | Sync actor profile |
+| `COMMUNICATION_MESSAGE_RECEIVED` | `communication.message.received` | Message received event |
+| `COMMUNICATION_ROOM_DM_REQUESTED` | `communication.room.dm.requested` | DM room creation requested (outbound) |
+| `COMMUNICATION_REACTION_ADDED` | `communication.reaction.added` | Reaction added event (outbound) |
+| `COMMUNICATION_REACTION_REMOVED` | `communication.reaction.removed` | Reaction removed event (outbound) |
+| `COMMUNICATION_ROOM_MEMBER_LEFT` | `communication.room.member.left` | Room member left event (outbound) |
+
+### Type Aliases
+
+| Type | Description |
+|------|-------------|
+| `AlkemioRoomID` | UUID identifying a room in Alkemio |
+| `AlkemioActorID` | UUID identifying an actor (user/bot) |
+| `AlkemioContextID` | UUID identifying a context (Space) |
+| `MessageID` | Opaque message identifier |
+| `ReactionID` | Opaque reaction identifier |
+
+### Constants
+
+#### Room Types
+- `RoomTypeCommunity` - General community room
+- `RoomTypeDirect` - Direct message room (exactly 2 actors)
+
+#### Join Rules
+- `JoinRulePublic` - Anyone can join
+- `JoinRuleInvite` - Requires invitation
+- `JoinRuleRestricted` - Members of parent space can join (MSC3083)
+
+#### Error Codes
+- `ErrCodeInvalidParam` - Request validation failed
+- `ErrCodeRoomNotFound` - Room does not exist
+- `ErrCodeSpaceNotFound` - Space does not exist
+- `ErrCodeActorNotFound` - Actor does not exist
+- `ErrCodeMatrixError` - Matrix SDK/homeserver error
+- `ErrCodeInternalError` - Unexpected system error
+- `ErrCodeNotAllowed` - Operation not permitted
+
+## Response Handling
+
+All responses extend `BaseResponse`:
+
+```typescript
+interface BaseResponse {
+  success: boolean;
+  error?: ErrorResponse;
+}
+
+interface ErrorResponse {
+  code: ErrorCode;
+  message: string;
+  details?: string;
+}
+```
+
+Batch operations return per-item results using `BaseResponse`:
+
+```typescript
+interface BatchAddMemberResponse {
+  success: boolean;
+  error?: ErrorResponse;
+  results?: { [roomId: string]: BaseResponse };
+}
+```
+
+## Generation
+
+This library is **auto-generated** from Go source code in `pkg/dto/`. Do not edit `src/dto/generated.ts` directly.
+
+To regenerate after Go DTO changes:
+
+```bash
+# From repository root
+make generate
+```
+
+## License
+
+EUPL-1.2

package/dist/commands.d.ts

@@ -0,0 +1,121 @@
+import type { AddReactionRequest, AddReactionResponse, BaseResponse, BatchAddMemberRequest, BatchAddMemberResponse, BatchAddSpaceMemberRequest, BatchAddSpaceMemberResponse, BatchRemoveMemberRequest, BatchRemoveMemberResponse, BatchRemoveSpaceMemberRequest, BatchRemoveSpaceMemberResponse, CreateRoomRequest, CreateSpaceRequest, DMRequestedEvent, DeleteMessageRequest, DeleteRoomRequest, DeleteSpaceRequest, GetMessageRequest, GetMessageResponse, GetReactionRequest, GetReactionResponse, GetRoomMembersRequest, GetRoomMembersResponse, GetRoomRequest, GetRoomResponse, GetSpaceRequest, GetSpaceResponse, GetThreadMessagesRequest, GetThreadMessagesResponse, ListRoomsRequest, ListRoomsResponse, ListSpacesRequest, ListSpacesResponse, MessageReceivedPayload, ReactionAddedEvent, ReactionRemovedEvent, RemoveReactionRequest, RoomMemberLeftEvent, SendMessageRequest, SendMessageResponse, SetParentRequest, SyncActorRequest, UpdateRoomRequest, UpdateSpaceRequest } from './dto';
+export declare const Commands: {
+    readonly 'communication.actor.sync': {
+        readonly request: SyncActorRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.hierarchy.set_parent': {
+        readonly request: SetParentRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.message.delete': {
+        readonly request: DeleteMessageRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.message.get': {
+        readonly request: GetMessageRequest;
+        readonly response: GetMessageResponse;
+    };
+    readonly 'communication.message.send': {
+        readonly request: SendMessageRequest;
+        readonly response: SendMessageResponse;
+    };
+    readonly 'communication.reaction.add': {
+        readonly request: AddReactionRequest;
+        readonly response: AddReactionResponse;
+    };
+    readonly 'communication.reaction.get': {
+        readonly request: GetReactionRequest;
+        readonly response: GetReactionResponse;
+    };
+    readonly 'communication.reaction.remove': {
+        readonly request: RemoveReactionRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.room.create': {
+        readonly request: CreateRoomRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.room.delete': {
+        readonly request: DeleteRoomRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.room.get': {
+        readonly request: GetRoomRequest;
+        readonly response: GetRoomResponse;
+    };
+    readonly 'communication.room.list': {
+        readonly request: ListRoomsRequest;
+        readonly response: ListRoomsResponse;
+    };
+    readonly 'communication.room.member.batch.add': {
+        readonly request: BatchAddMemberRequest;
+        readonly response: BatchAddMemberResponse;
+    };
+    readonly 'communication.room.member.batch.remove': {
+        readonly request: BatchRemoveMemberRequest;
+        readonly response: BatchRemoveMemberResponse;
+    };
+    readonly 'communication.room.members.get': {
+        readonly request: GetRoomMembersRequest;
+        readonly response: GetRoomMembersResponse;
+    };
+    readonly 'communication.room.update': {
+        readonly request: UpdateRoomRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.space.create': {
+        readonly request: CreateSpaceRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.space.delete': {
+        readonly request: DeleteSpaceRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.space.get': {
+        readonly request: GetSpaceRequest;
+        readonly response: GetSpaceResponse;
+    };
+    readonly 'communication.space.list': {
+        readonly request: ListSpacesRequest;
+        readonly response: ListSpacesResponse;
+    };
+    readonly 'communication.space.member.batch.add': {
+        readonly request: BatchAddSpaceMemberRequest;
+        readonly response: BatchAddSpaceMemberResponse;
+    };
+    readonly 'communication.space.member.batch.remove': {
+        readonly request: BatchRemoveSpaceMemberRequest;
+        readonly response: BatchRemoveSpaceMemberResponse;
+    };
+    readonly 'communication.space.update': {
+        readonly request: UpdateSpaceRequest;
+        readonly response: BaseResponse;
+    };
+    readonly 'communication.thread.messages.get': {
+        readonly request: GetThreadMessagesRequest;
+        readonly response: GetThreadMessagesResponse;
+    };
+};
+export declare const OutgoingEvents: {
+    readonly 'communication.message.received': {
+        readonly payload: MessageReceivedPayload;
+    };
+    readonly 'communication.reaction.added': {
+        readonly payload: ReactionAddedEvent;
+    };
+    readonly 'communication.reaction.removed': {
+        readonly payload: ReactionRemovedEvent;
+    };
+    readonly 'communication.room.dm.requested': {
+        readonly payload: DMRequestedEvent;
+    };
+    readonly 'communication.room.member.left': {
+        readonly payload: RoomMemberLeftEvent;
+    };
+};
+export type CommandTopic = keyof typeof Commands;
+export type RequestFor<T extends CommandTopic> = (typeof Commands)[T]['request'];
+export type ResponseFor<T extends CommandTopic> = (typeof Commands)[T]['response'];
+export type OutgoingEventTopic = keyof typeof OutgoingEvents;
+export type PayloadFor<T extends OutgoingEventTopic> = (typeof OutgoingEvents)[T]['payload'];

package/dist/commands.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutgoingEvents = exports.Commands = void 0;
+exports.Commands = {
+    'communication.actor.sync': {
+        request: {},
+        response: {},
+    },
+    'communication.hierarchy.set_parent': {
+        request: {},
+        response: {},
+    },
+    'communication.message.delete': {
+        request: {},
+        response: {},
+    },
+    'communication.message.get': {
+        request: {},
+        response: {},
+    },
+    'communication.message.send': {
+        request: {},
+        response: {},
+    },
+    'communication.reaction.add': {
+        request: {},
+        response: {},
+    },
+    'communication.reaction.get': {
+        request: {},
+        response: {},
+    },
+    'communication.reaction.remove': {
+        request: {},
+        response: {},
+    },
+    'communication.room.create': {
+        request: {},
+        response: {},
+    },
+    'communication.room.delete': {
+        request: {},
+        response: {},
+    },
+    'communication.room.get': {
+        request: {},
+        response: {},
+    },
+    'communication.room.list': {
+        request: {},
+        response: {},
+    },
+    'communication.room.member.batch.add': {
+        request: {},
+        response: {},
+    },
+    'communication.room.member.batch.remove': {
+        request: {},
+        response: {},
+    },
+    'communication.room.members.get': {
+        request: {},
+        response: {},
+    },
+    'communication.room.update': {
+        request: {},
+        response: {},
+    },
+    'communication.space.create': {
+        request: {},
+        response: {},
+    },
+    'communication.space.delete': {
+        request: {},
+        response: {},
+    },
+    'communication.space.get': {
+        request: {},
+        response: {},
+    },
+    'communication.space.list': {
+        request: {},
+        response: {},
+    },
+    'communication.space.member.batch.add': {
+        request: {},
+        response: {},
+    },
+    'communication.space.member.batch.remove': {
+        request: {},
+        response: {},
+    },
+    'communication.space.update': {
+        request: {},
+        response: {},
+    },
+    'communication.thread.messages.get': {
+        request: {},
+        response: {},
+    },
+};
+exports.OutgoingEvents = {
+    'communication.message.received': {
+        payload: {},
+    },
+    'communication.reaction.added': {
+        payload: {},
+    },
+    'communication.reaction.removed': {
+        payload: {},
+    },
+    'communication.room.dm.requested': {
+        payload: {},
+    },
+    'communication.room.member.left': {
+        payload: {},
+    },
+};
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":";;;AAqDa,QAAA,QAAQ,GAAG;IACtB,0BAA0B,EAAE;QAC1B,OAAO,EAAE,EAAsB;QAC/B,QAAQ,EAAE,EAAkB;KAC7B;IACD,oCAAoC,EAAE;QACpC,OAAO,EAAE,EAAsB;QAC/B,QAAQ,EAAE,EAAkB;KAC7B;IACD,8BAA8B,EAAE;QAC9B,OAAO,EAAE,EAA0B;QACnC,QAAQ,EAAE,EAAkB;KAC7B;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,EAAuB;QAChC,QAAQ,EAAE,EAAwB;KACnC;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAyB;KACpC;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAyB;KACpC;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAyB;KACpC;IACD,+BAA+B,EAAE;QAC/B,OAAO,EAAE,EAA2B;QACpC,QAAQ,EAAE,EAAkB;KAC7B;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,EAAuB;QAChC,QAAQ,EAAE,EAAkB;KAC7B;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,EAAuB;QAChC,QAAQ,EAAE,EAAkB;KAC7B;IACD,wBAAwB,EAAE;QACxB,OAAO,EAAE,EAAoB;QAC7B,QAAQ,EAAE,EAAqB;KAChC;IACD,yBAAyB,EAAE;QACzB,OAAO,EAAE,EAAsB;QAC/B,QAAQ,EAAE,EAAuB;KAClC;IACD,qCAAqC,EAAE;QACrC,OAAO,EAAE,EAA2B;QACpC,QAAQ,EAAE,EAA4B;KACvC;IACD,wCAAwC,EAAE;QACxC,OAAO,EAAE,EAA8B;QACvC,QAAQ,EAAE,EAA+B;KAC1C;IACD,gCAAgC,EAAE;QAChC,OAAO,EAAE,EAA2B;QACpC,QAAQ,EAAE,EAA4B;KACvC;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,EAAuB;QAChC,QAAQ,EAAE,EAAkB;KAC7B;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAkB;KAC7B;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAkB;KAC7B;IACD,yBAAyB,EAAE;QACzB,OAAO,EAAE,EAAqB;QAC9B,QAAQ,EAAE,EAAsB;KACjC;IACD,0BAA0B,EAAE;QAC1B,OAAO,EAAE,EAAuB;QAChC,QAAQ,EAAE,EAAwB;KACnC;IACD,sCAAsC,EAAE;QACtC,OAAO,EAAE,EAAgC;QACzC,QAAQ,EAAE,EAAiC;KAC5C;IACD,yCAAyC,EAAE;QACzC,OAAO,EAAE,EAAmC;QAC5C,QAAQ,EAAE,EAAoC;KAC/C;IACD,4BAA4B,EAAE;QAC5B,OAAO,EAAE,EAAwB;QACjC,QAAQ,EAAE,EAAkB;KAC7B;IACD,mCAAmC,EAAE;QACnC,OAAO,EAAE,EAA8B;QACvC,QAAQ,EAAE,EAA+B;KAC1C;CACO,CAAC;AAKE,QAAA,cAAc,GAAG;IAC5B,gCAAgC,EAAE;QAChC,OAAO,EAAE,EAA4B;KACtC;IACD,8BAA8B,EAAE;QAC9B,OAAO,EAAE,EAAwB;KAClC;IACD,gCAAgC,EAAE;QAChC,OAAO,EAAE,EAA0B;KACpC;IACD,iCAAiC,EAAE;QACjC,OAAO,EAAE,EAAsB;KAChC;IACD,gCAAgC,EAAE;QAChC,OAAO,EAAE,EAAyB;KACnC;CACO,CAAC"}