Commit 5e134f39 authored by timkinnane's avatar timkinnane
Browse files

fix(send): Simplify message sending interfaces

+ Update send methods to reduce variation and deprecated methods to reduce confusion.
+ Add tests for all send methods and updated docs.

BREAKING CHANGE: sendMessageByRoomId and sendMessageByRoom replaced with sendToRoomId and sendToRoom. sendMessage is now semantically used for the endpoint that sends a message object, where other send methods are abstractions of that and accept strings instead that are converted to a
message.
parent 1b799a94
......@@ -23,7 +23,10 @@ or platform of choice.
## API
See full API documentation links in the generated docs. Below is just a summary:
Full API documentation can be generated locally using `yarn docs`.
This isn't in a format we can publish yet, but can be useful for development.
Below is just a summary:
---
......@@ -239,25 +242,26 @@ Structure message content for sending
- Optionally addressing to room ID with second param
- Returns a message object
### `driver.sendMessageByRoomId(content, roomId)`
### `driver.sendMessage(message)`
Prepare and send message/s to specified room ID
- Content can be message object, message text string or array of strings
- Returns a promise
- Resolves when all sent
Send a prepared message object (with pre-defined room ID)
- Accepts a message object
- Returns a promise that resolves to sent message object
### `driver.sendToRoomId(content, roomId)`
### `driver.sendMessageByRoom(content, room)`
Prepare and send string/s to specified room ID
- Accepts message text string or array of strings
- Returns a promise or array of promises that resolve to sent message object/s
### `driver.sendToRoom(content, room)`
As above, with room name instead of ID
### `driver.sendDirectToUser(content, username)`
As above, with username for DM instead of ID
### `driver.sendMessage(content, roomId?)`
Send a prepared message object (with pre-defined room ID)
- Optional argument allows redirecting message to different room
- Creates DM room if it doesn't exist
---
......@@ -396,8 +400,9 @@ Do `npm install -g yarn` if you don't have it. Then setup the project:
- `yarn test` runs tests and coverage locally (pretest does lint)
- `yarn test:debug` runs tests without coverage, breaking for debug attach
- `yarn docs` generates docs
- `yarn build` runs tests, coverage, compiles, tests package, generates docs
- `yarn start` run locally from source, to allow manual testing of streams
- `yarn docs` generates API docs locally, then `open docs/index.html`
- `yarn build` runs tests, coverage, compiles, and tests package for publishing
- `yarn test:package` uses package-preview to make sure the published node
package can be required and run only with defined dependencies, to avoid errors
that might pass locally due to existing global dependencies or symlinks.
......
......@@ -46,72 +46,68 @@ FN:466,(anonymous_50)
FN:470,joinRooms
FN:471,(anonymous_52)
FN:478,prepareMessage
FN:489,sendMessageByRoomId
FN:492,(anonymous_55)
FN:496,(anonymous_56)
FN:504,sendMessageByRoom
FN:505,(anonymous_58)
FN:511,sendDirectToUser
FN:512,(anonymous_60)
FN:521,sendMessage
FN:530,customMessage
FNF:55
FNH:28
FNDA:15,connectDefaults
FN:488,sendMessage
FN:497,sendToRoomId
FN:501,(anonymous_56)
FN:512,sendToRoom
FN:513,(anonymous_58)
FN:521,sendDirectToUser
FN:522,(anonymous_60)
FNF:53
FNH:35
FNDA:20,connectDefaults
FNDA:10,respondDefaults
FNDA:0,useLog
FNDA:15,connect
FNDA:15,(anonymous_12)
FNDA:15,(anonymous_13)
FNDA:20,connect
FNDA:20,(anonymous_12)
FNDA:20,(anonymous_13)
FNDA:0,(anonymous_14)
FNDA:0,(anonymous_15)
FNDA:15,(anonymous_16)
FNDA:20,(anonymous_16)
FNDA:0,disconnect
FNDA:0,(anonymous_18)
FNDA:15,setupMethodCache
FNDA:2,asyncCall
FNDA:20,setupMethodCache
FNDA:10,asyncCall
FNDA:0,(anonymous_21)
FNDA:2,(anonymous_22)
FNDA:10,(anonymous_22)
FNDA:0,callMethod
FNDA:5,cacheCall
FNDA:9,cacheCall
FNDA:0,(anonymous_25)
FNDA:5,(anonymous_26)
FNDA:15,login
FNDA:15,(anonymous_28)
FNDA:9,(anonymous_26)
FNDA:20,login
FNDA:20,(anonymous_28)
FNDA:0,(anonymous_29)
FNDA:0,logout
FNDA:0,(anonymous_31)
FNDA:12,subscribe
FNDA:12,(anonymous_33)
FNDA:12,(anonymous_34)
FNDA:17,subscribe
FNDA:17,(anonymous_33)
FNDA:17,(anonymous_34)
FNDA:0,unsubscribe
FNDA:0,unsubscribeAll
FNDA:0,(anonymous_37)
FNDA:12,subscribeToMessages
FNDA:12,(anonymous_39)
FNDA:17,subscribeToMessages
FNDA:17,(anonymous_39)
FNDA:10,reactToMessages
FNDA:67,(anonymous_41)
FNDA:83,(anonymous_41)
FNDA:8,respondToMessages
FNDA:13,(anonymous_43)
FNDA:13,(anonymous_44)
FNDA:0,getRoomId
FNDA:2,getRoomId
FNDA:5,getRoomName
FNDA:0,getDirectMessageRoomId
FNDA:0,(anonymous_48)
FNDA:2,getDirectMessageRoomId
FNDA:2,(anonymous_48)
FNDA:0,joinRoom
FNDA:0,(anonymous_50)
FNDA:0,joinRooms
FNDA:0,(anonymous_52)
FNDA:2,prepareMessage
FNDA:2,sendMessageByRoomId
FNDA:0,(anonymous_55)
FNDA:2,(anonymous_56)
FNDA:0,sendMessageByRoom
FNDA:0,(anonymous_58)
FNDA:0,sendDirectToUser
FNDA:0,(anonymous_60)
FNDA:2,sendMessage
FNDA:0,customMessage
FNDA:10,prepareMessage
FNDA:10,sendMessage
FNDA:7,sendToRoomId
FNDA:6,(anonymous_56)
FNDA:2,sendToRoom
FNDA:2,(anonymous_58)
FNDA:2,sendDirectToUser
FNDA:2,(anonymous_60)
DA:1,1
DA:2,1
DA:10,1
......@@ -120,7 +116,7 @@ DA:15,1
DA:18,1
DA:19,1
DA:36,1
DA:37,15
DA:37,20
DA:45,1
DA:46,10
DA:62,1
......@@ -129,56 +125,56 @@ DA:83,1
DA:98,1
DA:99,0
DA:119,1
DA:120,15
DA:121,15
DA:122,15
DA:123,15
DA:124,15
DA:132,15
DA:133,15
DA:134,15
DA:136,15
DA:120,20
DA:121,20
DA:122,20
DA:123,20
DA:124,20
DA:132,20
DA:133,20
DA:134,20
DA:136,20
DA:137,0
DA:139,0
DA:140,0
DA:142,15
DA:143,15
DA:145,15
DA:146,15
DA:147,15
DA:142,20
DA:143,20
DA:145,20
DA:146,20
DA:147,20
DA:155,1
DA:156,0
DA:157,0
DA:158,0
DA:169,15
DA:170,15
DA:178,15
DA:169,20
DA:170,20
DA:178,20
DA:189,1
DA:190,2
DA:191,2
DA:192,2
DA:190,10
DA:191,10
DA:192,10
DA:194,0
DA:195,0
DA:198,2
DA:201,2
DA:198,10
DA:201,10
DA:210,1
DA:211,0
DA:221,1
DA:222,5
DA:222,9
DA:224,0
DA:225,0
DA:228,5
DA:231,5
DA:228,9
DA:231,9
DA:239,1
DA:240,15
DA:242,15
DA:240,20
DA:242,20
DA:243,0
DA:248,0
DA:250,15
DA:251,15
DA:253,15
DA:255,15
DA:256,15
DA:250,20
DA:251,20
DA:253,20
DA:255,20
DA:256,20
DA:259,0
DA:260,0
DA:265,1
......@@ -186,13 +182,13 @@ DA:266,0
DA:267,0
DA:268,0
DA:277,1
DA:278,12
DA:279,12
DA:280,12
DA:281,12
DA:282,12
DA:283,12
DA:284,12
DA:278,17
DA:279,17
DA:280,17
DA:281,17
DA:282,17
DA:283,17
DA:284,17
DA:304,1
DA:305,0
DA:306,0
......@@ -202,19 +198,19 @@ DA:310,0
DA:314,1
DA:315,0
DA:322,1
DA:323,12
DA:325,12
DA:328,12
DA:323,17
DA:325,17
DA:328,17
DA:344,1
DA:345,10
DA:346,10
DA:347,67
DA:348,67
DA:349,67
DA:350,67
DA:351,20
DA:352,20
DA:354,47
DA:347,83
DA:348,83
DA:349,83
DA:350,83
DA:351,26
DA:352,26
DA:354,57
DA:357,0
DA:371,1
DA:372,8
......@@ -240,39 +236,35 @@ DA:411,5
DA:414,5
DA:417,5
DA:446,1
DA:447,0
DA:447,2
DA:451,1
DA:452,5
DA:460,1
DA:461,0
DA:461,2
DA:465,1
DA:466,0
DA:470,1
DA:471,0
DA:478,1
DA:479,2
DA:480,2
DA:481,2
DA:489,1
DA:490,2
DA:491,2
DA:492,0
DA:494,2
DA:496,2
DA:504,1
DA:505,0
DA:511,1
DA:512,0
DA:479,10
DA:480,10
DA:481,10
DA:488,1
DA:489,10
DA:497,1
DA:498,7
DA:499,4
DA:501,3
DA:502,6
DA:512,1
DA:513,2
DA:521,1
DA:522,2
DA:523,2
DA:530,1
DA:531,0
LF:156
LH:120
BRDA:38,0,0,15
LF:152
LH:122
BRDA:38,0,0,20
BRDA:38,0,1,0
BRDA:39,1,0,15
BRDA:39,1,0,20
BRDA:39,1,1,0
BRDA:47,2,0,10
BRDA:47,2,1,9
......@@ -284,46 +276,46 @@ BRDA:50,5,0,10
BRDA:50,5,1,9
BRDA:62,6,0,1
BRDA:62,6,1,1
BRDA:119,7,0,15
BRDA:119,7,0,20
BRDA:140,8,0,0
BRDA:140,8,1,0
BRDA:146,9,0,0
BRDA:146,9,1,15
BRDA:171,10,0,15
BRDA:171,10,1,15
BRDA:172,11,0,15
BRDA:172,11,1,15
BRDA:175,12,0,15
BRDA:175,12,1,15
BRDA:176,13,0,15
BRDA:176,13,1,15
BRDA:179,14,0,15
BRDA:179,14,1,15
BRDA:180,15,0,15
BRDA:180,15,1,15
BRDA:190,16,0,2
BRDA:146,9,1,20
BRDA:171,10,0,20
BRDA:171,10,1,20
BRDA:172,11,0,20
BRDA:172,11,1,20
BRDA:175,12,0,20
BRDA:175,12,1,20
BRDA:176,13,0,20
BRDA:176,13,1,20
BRDA:179,14,0,20
BRDA:179,14,1,20
BRDA:180,15,0,20
BRDA:180,15,1,20
BRDA:190,16,0,10
BRDA:190,16,1,0
BRDA:199,17,0,2
BRDA:199,17,0,10
BRDA:199,17,1,0
BRDA:212,18,0,0
BRDA:212,18,1,0
BRDA:229,19,0,4
BRDA:229,19,0,8
BRDA:229,19,1,1
BRDA:240,20,0,15
BRDA:240,20,0,20
BRDA:240,20,1,0
BRDA:242,21,0,0
BRDA:242,21,1,15
BRDA:250,22,0,15
BRDA:242,21,1,20
BRDA:250,22,0,20
BRDA:250,22,1,0
BRDA:250,22,2,0
BRDA:306,23,0,0
BRDA:306,23,1,0
BRDA:348,24,0,67
BRDA:348,24,0,83
BRDA:348,24,1,0
BRDA:348,25,0,67
BRDA:348,25,1,67
BRDA:350,26,0,20
BRDA:350,26,1,47
BRDA:348,25,0,83
BRDA:348,25,1,83
BRDA:350,26,0,26
BRDA:350,26,1,57
BRDA:371,27,0,4
BRDA:375,28,0,0
BRDA:375,28,1,13
......@@ -356,13 +348,11 @@ BRDA:414,41,0,3
BRDA:414,41,1,2
BRDA:414,42,0,5
BRDA:414,42,1,3
BRDA:480,43,0,2
BRDA:480,43,0,10
BRDA:480,43,1,0
BRDA:491,44,0,0
BRDA:491,44,1,2
BRDA:522,45,0,0
BRDA:522,45,1,2
BRF:92
BRDA:498,44,0,4
BRDA:498,44,1,3
BRF:90
BRH:67
end_of_record
TN:
......@@ -388,8 +378,8 @@ FNDA:0,(anonymous_3)
FNDA:0,(anonymous_4)
FNDA:1,replaceLog
FNDA:1,silence
FNDA:82,(anonymous_7)
FNDA:111,(anonymous_8)
FNDA:108,(anonymous_7)
FNDA:150,(anonymous_8)
FNDA:0,(anonymous_9)
FNDA:0,(anonymous_10)
FNDA:0,(anonymous_11)
......@@ -401,8 +391,8 @@ DA:18,0
DA:22,1
DA:25,1
DA:29,1
DA:30,82
DA:31,111
DA:30,108
DA:31,150
DA:32,0
DA:33,0
DA:34,0
......@@ -420,17 +410,17 @@ FN:14,(anonymous_0)
FN:19,(anonymous_1)
FNF:2
FNH:2
FNDA:8,(anonymous_0)
FNDA:5,(anonymous_1)
FNDA:16,(anonymous_0)
FNDA:13,(anonymous_1)
DA:13,1
DA:15,8
DA:15,16
DA:16,2
DA:17,8
DA:20,5
DA:21,5
DA:17,16
DA:20,13
DA:21,13
LF:6
LH:6
BRDA:15,0,0,6
BRDA:15,0,0,14
BRDA:15,0,1,2
BRF:2
BRH:2
......@@ -447,9 +437,9 @@ FN:88,resetAll
FN:89,(anonymous_8)
FNF:8
FNH:8
FNDA:31,use
FNDA:52,create
FNDA:28,call
FNDA:36,use
FNDA:67,create
FNDA:32,call
FNDA:3,has
FNDA:4,get
FNDA:3,reset
......@@ -460,21 +450,21 @@ DA:2,1
DA:6,1
DA:7,1
DA:16,1
DA:17,31
DA:17,36
DA:26,1
DA:27,52
DA:28,52
DA:29,52
DA:27,67
DA:28,67
DA:29,67
DA:37,1
DA:38,28
DA:39,28
DA:42,28
DA:38,32
DA:39,32
DA:42,32
DA:43,2
DA:45,2
DA:48,26
DA:49,26
DA:50,24
DA:52,26
DA:48,30
DA:49,30
DA:50,28
DA:52,30
DA:60,1
DA:61,3
DA:69,1
......@@ -489,9 +479,9 @@ LF:30
LH:30
BRDA:26,0,0,5
BRDA:38,1,0,3
BRDA:38,1,1,25
BRDA:38,1,1,29
BRDA:42,2,0,2
BRDA:42,2,1,26
BRDA:42,2,1,30
BRDA:70,3,0,4
BRDA:70,3,1,0
BRDA:79,4,0,3
......
......@@ -160,30 +160,25 @@ export declare function joinRooms(rooms: string[]): Promise<void[]>;
*/
export declare function prepareMessage(content: string | IMessage, roomId?: string): Message;
/**
* Prepare and send message/s to specified room ID.
* Accepts message text string, array of strings or a structured message object.
* Will create one or more send calls collected into promise.
*/
export declare function sendMessageByRoomId(content: string | string[] | IMessage, roomId: string): Promise<any>;
/**
* Prepare and send message/s to specified room name (or ID).
* Accepts message text string, array of strings or a structured message object.
* Will create one or more send calls collected into promise.
* Send a prepared message object (with pre-defined room ID).
* Usually prepared and called by sendMessageByRoomId or sendMessageByRoom.
*/
export declare function sendMessageByRoom(content: string | string[] | IMessage, room: string): Promise<any>;
export declare function sendMessage(message: IMessage): Promise<IMessage>;
/**
* Send a message to a user in a DM.
* Prepare and send string/s to specified room ID.
* @param content Accepts message text string or array of strings.
* @param roomId ID of the target room to use in send.
*/
export declare function sendDirectToUser(message: string | string[] | IMessage, username: string): Promise<any>;
export declare function sendToRoomId(content: string | string[], roomId: string): Promise<IMessage[] | IMessage>;
/**
* Send a prepared message object (with pre-defined room ID).
* Usually prepared and called by sendMessageByRoomId or sendMessageByRoom.
* In the Hubot adapter, this method accepted a room ID, which was not semantic,
* such usage should be replaced by `sendMessageByRoom(content, roomId)`
* Prepare and send string/s to specified room name (or ID).
* @param content Accepts message text string or array of strings.
* @param room A name (or ID) to resolve as ID to use in send.
*/
export declare function sendMessage(message: IMessage, roomId?: string): Promise<any>;
export declare function sendToRoom(content: string | string[], room: string): Promise<IMessage[] | IMessage>;
/**
* Legacy method for older adapters - sendMessage now accepts all properties
* @deprecated since 0.0.0
* Prepare and send string/s to a user in a DM.
* @param content Accepts message text string or array of strings.
* @param username Name to create (or get) DM for room ID to use in send.
*/
export declare function customMessage(message: IMessage): Promise<any>;
export declare function sendDirectToUser(content: string | string[], username: string): Promise<IMessage[] | IMessage>;
......@@ -472,55 +472,45 @@ function prepareMessage(content, roomId) {
}
exports.prepareMessage = prepareMessage;
/**
* Prepare and send message/s to specified room ID.
* Accepts message text string, array of strings or a structured message object.
* Will create one or more send calls collected into promise.
* Send a prepared message object (with pre-defined room ID).
* Usually prepared and called by sendMessageByRoomId or sendMessageByRoom.
*/
function sendMessageByRoomId(content, roomId) {
let messages = [];
if (Array.isArray(content)) {
content.forEach((text) => messages.push(prepareMessage(text, roomId)));
function sendMessage(message) {
return asyncCall('sendMessage', message);
}
exports.sendMessage = sendMessage;
/**
* Prepare and send string/s to specified room ID.
* @param content Accepts message text string or array of strings.
* @param roomId ID of the target room to use in send.
*/
function sendToRoomId(content, roomId) {
if (!Array.isArray(content)) {
return sendMessage(prepareMessage(content, roomId));
}
else {
messages.push(prepareMessage(content, roomId));
return Promise.all(content.map((text) => {
return sendMessage(prepareMessage(text, roomId));
}));
}
return Promise.all(messages.map((message) => sendMessage(message)));
}
exports.sendMessageByRoomId = sendMessageByRoomId;
exports.sendToRoomId = sendToRoomId;
/**
* Prepare and send message/s to specified room name (or ID).
* Accepts message text string, array of strings or a structured message object.
* Will create one or more send calls collected into promise.
* Prepare and send string/s to specified room name (or ID).