API v1.1 Direct Message endpoint wrappers

doc/v1.md

@@ -331,6 +331,366 @@ const loggedUser = await client.v1.verifyCredentials();
 const loggedUser = await client.currentUser();
 ```
 
+## Direct Messages (DMs)
+
+### Send a new direct message to someone
+
+**Method**: `.sendDm()`
+
+**Endpoint**: `direct_messages/events/new.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `options: SendDMV1Params`
+
+**Returns**: `DirectMessageCreateV1Result`
+
+**Example**
+```ts
+const recipientId = '12';
+
+const dmSent = await client.v1.sendDm({
+  // Mandatory
+  recipient_id: recipientId,
+  // Other parameters are collapsed into {message_data} of payload
+  text: 'Hello Jack!',
+  attachment: {
+    type: 'media',
+    media: { id: '24024092' },
+  },
+});
+
+dmSent.event[EDirectMessageEventTypeV1.Create].message_data.text === 'Hello Jack!'; // true!
+```
+
+### Get a single DM by ID
+
+**Method**: `.getDmEvent()`
+
+**Endpoint**: `direct_messages/events/show.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `ReceivedDMEventV1`
+
+**Example**
+```ts
+const directMessage = await client.v1.getDmEvent('<DM-ID>');
+
+const messageSender = directMessage.event[EDirectMessageEventTypeV1.Create].sender_id;
+```
+
+### Delete / hide a DM
+
+**Method**: `.deleteDm()`
+
+**Endpoint**: `direct_messages/events/destroy.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `void`
+
+**Example**
+```ts
+await client.v1.deleteDm('<DM-ID>');
+```
+
+### List sent and received DMs
+
+This isn't sorted by conversation, you will get all events *sent* and *received* in any conversation.
+
+**Method**: `.listDmEvents()`
+
+**Endpoint**: `direct_messages/events/list.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**: None.
+
+**Returns**: `DmEventsV1Paginator`
+
+**Example**
+```ts
+const eventsPaginator = await client.v1.listDmEvents();
+
+for await (const event of eventsPaginator) {
+  if (event.type === EDirectMessageEventTypeV1.Create) {
+    console.log('Sender ID is', event[EDirectMessageEventTypeV1.Create].sender_id);
+  }
+}
+```
+
+### Create a welcome direct message
+
+A welcome direct message is a message that will automatically greet users who want to
+interact with the logged account. You must "activate" the welcome direct message by creating
+a "welcome direct message rule" (see below).
+
+**Method**: `.newWelcomeDm()`
+
+**Endpoint**: `direct_messages/welcome_messages/new.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `name: string`
+  - `data: MessageCreateDataV1`: The `message_data` property of the payload.
+
+**Returns**: `WelcomeDirectMessageCreateV1Result`
+
+**Example**
+```ts
+const welcomeDm = await client.v1.newWelcomeDm('welcome dm 1', {
+  text: 'Welcome! Please tell us whats the problem? You can also view your support page.',
+  ctas: [{
+    type: 'web_url',
+    url: 'https://example.com/your_support.php',
+    label: 'Our support page',
+  }],
+});
+
+console.log(welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].message_data.text);
+```
+
+### Get a welcome direct message (that you own)
+
+A welcome direct message is a message that will automatically greet users who want to
+interact with the logged account.
+
+**Method**: `.getWelcomeDm()`
+
+**Endpoint**: `direct_messages/welcome_messages/show.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `WelcomeDirectMessageCreateV1Result`
+
+**Example**
+```ts
+const welcomeDm = await client.v1.getWelcomeDm('<DM-ID>');
+```
+
+### Delete a welcome direct message (that you own)
+
+**Method**: `.deleteWelcomeDm()`
+
+**Endpoint**: `direct_messages/welcome_messages/destroy.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `void`
+
+**Example**
+```ts
+await client.v1.deleteWelcomeDm(welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].id);
+```
+
+### Update a welcome direct message (that you own)
+
+**Method**: `.updateWelcomeDm()`
+
+**Endpoint**: `direct_messages/welcome_messages/update.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+  - `data: MessageCreateDataV1`: The `message_data` property of the payload.
+
+**Returns**: `WelcomeDirectMessageCreateV1Result`
+
+**Example**
+```ts
+await client.v1.updateWelcomeDm(welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].id, {
+  ...welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].message_data,
+  text: 'Another text for welcome Dm.',
+});
+```
+
+### List your welcome DMs
+
+**Method**: `.listWelcomeDms()`
+
+**Endpoint**: `direct_messages/welcome_messages/list.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**: None.
+
+**Returns**: `WelcomeDmV1Paginator`
+
+**Example**
+```ts
+const welcomeDms = await client.v1.listWelcomeDms();
+
+for await (const welcomeDm of welcomeDms) {
+  console.log(welcomeDm.id, welcomeDm.message_data.text, welcomeDm.name);
+}
+```
+
+---------
+
+### Create a welcome direct message rule
+
+This will "enable" a desired welcome direct message. The related message will automatically show up on new conversations.
+
+***A rule shouldn't already exist!***.
+
+**Method**: `.newWelcomeDmRule()`
+
+**Endpoint**: `direct_messages/welcome_messages/rules/new.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `welcomeMessageId: string`
+
+**Returns**: `WelcomeDmRuleV1Result`
+
+**Example**
+```ts
+const rule = await client.v1.newWelcomeDmRule(welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].id);
+console.log(rule.welcome_message_rule.id, rule.welcome_message_rule.welcome_message_id);
+```
+
+### Get a welcome direct message rule
+
+**Method**: `.getWelcomeDmRule()`
+
+**Endpoint**: `direct_messages/welcome_messages/rules/show.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `WelcomeDmRuleV1Result`
+
+**Example**
+```ts
+const rule = await client.v1.getWelcomeDmRule(rule.welcome_message_rule.id);
+```
+
+### Delete a welcome direct message rule
+
+**Method**: `.deleteWelcomeDmRule()`
+
+**Endpoint**: `direct_messages/welcome_messages/rules/destroy.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `id: string`
+
+**Returns**: `void`
+
+**Example**
+```ts
+await client.v1.deleteWelcomeDmRule(rule.welcome_message_rule.id);
+```
+
+### List your welcome DM rules
+
+In fact, you can only have one unique rule set. So this endpoint will either return a empty object,
+or an object with a single-element array.
+
+**Method**: `.listWelcomeDmRules()`
+
+**Endpoint**: `direct_messages/welcome_messages/rules/list.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**: None.
+
+**Returns**: `WelcomeDmRuleListV1Result`
+
+**Example**
+```ts
+const rules = await client.v1.listWelcomeDmRules();
+
+if (rules.welcome_message_rules?.length) {
+  const activeRule = rules.welcome_message_rules[0];
+}
+```
+
+### Set the active visible welcome DM
+
+This helper will do the job for you if you want to properly set an active rule given a created welcome message.
+
+It will:
+- List the existing welcome DM rules
+- For each rule, delete the rule *and the associated welcome DM if `deleteAssociatedWelcomeDmWhenDeletingRule` is `true` (default)*.
+- Then, create the new welcome DM rule with the given welcome DM ID.
+
+**Method**: `.setWelcomeDm()`
+
+**Endpoint**: Combinaison of multiple endpoints
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `welcomeMessageId: string`
+  - `deleteAssociatedWelcomeDmWhenDeletingRule?: boolean = true`
+
+**Returns**: `WelcomeDmRuleV1Result`
+
+**Example**
+```ts
+await client.v1.setWelcomeDm(welcomeDm[EDirectMessageEventTypeV1.WelcomeCreate].id);
+```
+
+### Mark a received DM as read in a conversation
+
+**Method**: `.markDmAsRead()`
+
+**Endpoint**: `direct_messages/mark_read.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `lastEventId: string`
+  - `recipientId: string` (recipient of the conversation, not the message!)
+
+**Returns**: `void`
+
+**Example**
+```ts
+const eventData = directMessage.event[EDirectMessageEventTypeV1.Create];
+await client.v1.markDmAsRead(directMessage.event.id, eventData.sender_id);
+```
+
+### Indicate that user is typing in a conversation
+
+**Method**: `.indicateDmTyping()`
+
+**Endpoint**: `direct_messages/indicate_typing.json`
+
+**Right level**: `Read-write + DM`
+
+**Arguments**:
+  - `recipientId: string` (recipient of the conversation)
+
+**Returns**: `void`
+
+**Example**
+```ts
+const eventData = directMessage.event[EDirectMessageEventTypeV1.Create];
+await client.v1.indicateDmTyping(eventData.sender_id);
+```
+
 
 ## Trends