[NEW] Added Invite Links API docs (#1551)

.github/workflows/build_and_test.yml

@@ -2,20 +2,39 @@ name: Build and test with Rake
 
 on: [push]
 
+# env:
+#   NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer
+
 jobs:
   build:
 
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v1
+
     - name: Set up Ruby 2.6
       uses: actions/setup-ruby@v1
       with:
         ruby-version: 2.6.x
-    - name: Build and test with Rake
+
+    - uses: actions/cache@v1
+      id: gem-cache
+      with:
+        path: vendor/bundle
+        key: ${{ runner.os }}-gem-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-gem-
+
+    - name: Install dependencies
       run: |
         gem install bundler
         bundle install --jobs 4 --retry 3 --deployment
+
+    - name: Lint
+      run: |
         bundle exec mdl ./ -r ~MD004 -i -g
+
+    - name: Build and test with Rake
+      run: |
         bundle exec "rake test"

_data/toc.yml

@@ -403,6 +403,12 @@
         - history
         - list
         - remove
+      - Invites:
+        - findOrCreateInvite
+        - listInvites
+        - removeInvite
+        - useInviteToken
+        - validateInviteToken
       - Livechat:
         - agent
         - appearance

contributing/documentation/documentation-map/README.md

@@ -397,6 +397,12 @@ Here you can also find what articles are incomplete and missing.
             - history
             - list
             - remove
+        - Invites:
+            - findOrCreateInvite
+            - listInvites
+            - removeInvite
+            - useInviteToken
+            - validateInviteToken
         - Livechat:
             - agent
             - appearance

developer-guides/rest-api/README.md

@@ -224,13 +224,23 @@ When calling a production Rocket.Chat server, ensure it is running via HTTPS and
 | `/api/v1/integrations.list`    | Lists all of the integrations.                                | [Link](integration/list/)   |
 | `/api/v1/integrations.remove`  | Removes an integration.                                       | [Link](integration/remove/) |
 
+### Invites
+
+| Url                             | Short Description                                                          | Details Page                         |
+| :------------------------------ | :------------------------------------------------------------------------- | :----------------------------------- |
+| `/api/v1/findOrCreateInvite`    | Created a new Invite or returns an existing one with the same parameters.  | [Link](invites/findOrCreateInvite/)  |
+| `/api/v1/listInvites`           | Lists all of the invite tokens.                                            | [Link](invites/listInvites/)         |
+| `/api/v1/removeInvite`          | Removes an invite.                                                         | [Link](invites/removeInvite/)        |
+| `/api/v1/useInviteToken`        | Report to the server that an invite token was used.                        | [Link](invites/useInviteToken/)      |
+| `/api/v1/validateInviteToken`   | Checks if an invite token is valid.                                        | [Link](invites/validateInviteToken/) |
+
 ### Livechat
 
-| Url                              | Short Description                                             | Details Page                     |
-| :------------------------------- | :------------------------------------------------------------ | :------------------------------- |
-| `/api/v1/livechat/inquiries.list`| Retrieves a list of open inquiries.                           | [Link](livechat/inquiries-list/) |
-| `/api/v1/livechat/inquiries.take`| Take an open inquiry.                                         | [Link](livechat/inquiries-take/) |
-| `/api/v1/livechat/rooms`         | Retrieves a list of livechat rooms.                           | [Link](livechat/rooms/)          |
+| Url                              | Short Description                   | Details Page                                      |
+| :------------------------------- | :-----------------------------------| :------------------------------------------------ |
+| `/api/v1/livechat/inquiries.list`| Retrieves a list of open inquiries. | [Link](livechat/inquiries/#inquiries-list)        |
+| `/api/v1/livechat/inquiries.take`| Take an open inquiry.               | [Link](livechat/inquiries/#livechat-take-inquiry) |
+| `/api/v1/livechat/rooms`         | Retrieves a list of livechat rooms. | [Link](livechat/rooms/)                           |
 
 ### OAuthApps
 

developer-guides/rest-api/invites/README.md

@@ -0,0 +1,9 @@
+# Invite Methods
+
+| Url                             | Short Description                                                          | Details Page                 |
+| :------------------------------ | :------------------------------------------------------------------------- | :--------------------------- |
+| `/api/v1/findOrCreateInvite`    | Created a new Invite or returns an existing one with the same parameters.  | [Link](findOrCreateInvite/)  |
+| `/api/v1/listInvites`           | Lists all of the invite tokens.                                            | [Link](listInvites/)         |
+| `/api/v1/removeInvite`          | Removes an invite.                                                         | [Link](removeInvite/)        |
+| `/api/v1/useInviteToken`        | Report to the server that an invite token was used.                        | [Link](useInviteToken/)      |
+| `/api/v1/validateInviteToken`   | Checks if an invite token is valid.                                        | [Link](validateInviteToken/) |

developer-guides/rest-api/invites/findOrCreateInvite/README.md

@@ -0,0 +1,43 @@
+# Find or Create Invite
+
+Creates or return an existing invite with the specified parameters. Requires the `create-invite-links` permission.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/findOrCreateInvite` | `yes` | `POST` |
+
+## Payload
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `rid` | `'csFYrDeixJG7PnrAh'` | Required | The id of the room that the invite is being created for. |
+| `days` | `0` | Required | The number of days that the invite will be valid for. Send 0 for unlimited. |
+| `maxUses` | `20` | Required | The number of times that the invite can be used. Send 0 for unlimited. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
+     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/findOrCreateInvite \
+     -d '{ "rid": "csFYrDeixJG7PnrAh", "days": 10, "maxUses": 0 }'
+```
+
+## Example Result
+
+```json
+{
+    "_id": "kDKQ3H",
+    "days": 10,
+    "maxUses": 0,
+    "rid": "csFYrDeixJG7PnrAh",
+    "userId": "sNiDqHit5nGAGFg8X",
+    "createdAt": "2017-01-06T13:23:46.018Z",
+    "expires": "2017-01-16T13:23:46.018Z",
+    "_updatedAt": "2017-01-06T13:23:46.018Z",
+    "uses": 0,
+    "url": "http://open.rocket.chat/invite/kDKQ3H",
+    "success": true
+}
+```

developer-guides/rest-api/invites/listInvites/README.md

@@ -0,0 +1,56 @@
+# List Invites
+
+Lists all of the invites on the server. Requires the `create-invite-links` permission.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/listInvites` | `yes` | `GET` |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
+     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/listInvites
+```
+
+## Example Result
+
+```json
+[
+  {
+    "_id": "kDKQ3H",
+    "days": 1,
+    "maxUses": 1,
+    "rid": "s7CE842q9WtvLctD7",
+    "userId": "sNiDqHit5nGAGFg8X",
+    "createdAt": "2019-12-20T03:31:56.774Z",
+    "expires": "2019-12-21T03:31:56.774Z",
+    "uses": 1,
+    "_updatedAt": "2019-12-20T03:33:40.065Z"
+  },
+  {
+    "_id": "99ScEP",
+    "days": 1,
+    "maxUses": 0,
+    "rid": "s7CE842q9WtvLctD7",
+    "userId": "sNiDqHit5nGAGFg8X",
+    "createdAt": "2019-12-20T03:38:20.485Z",
+    "expires": "2019-12-21T03:38:20.485Z",
+    "uses": 0,
+    "_updatedAt": "2019-12-20T03:38:20.485Z"
+  },
+  {
+    "_id": "Y5JKM4",
+    "days": 0,
+    "maxUses": 1,
+    "rid": "s7CE842q9WtvLctD7",
+    "userId": "sNiDqHit5nGAGFg8X",
+    "createdAt": "2019-12-20T03:38:25.313Z",
+    "expires": null,
+    "uses": 1,
+    "_updatedAt": "2019-12-20T03:38:40.116Z"
+  }
+]
+```

developer-guides/rest-api/invites/removeInvite/README.md

@@ -0,0 +1,28 @@
+# Remove Invite
+
+Removes an invite from the server. Requires the `create-invite-links` permission.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/removeInvite` | `yes` | `DELETE` |
+
+## Payload
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `_id` | `'kDKQ3H'` | Required | The id of the invite to remove. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
+     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
+     -X DELETE \
+     http://localhost:3000/api/v1/removeInvite/kDKQ3H
+```
+
+## Example Result
+
+```json
+true
+```

developer-guides/rest-api/invites/useInviteToken/README.md

@@ -0,0 +1,37 @@
+# Use Invite Token
+
+Report to the server that an invite token was used. No permissions are required.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/useInviteToken` | `yes` | `POST` |
+
+## Payload
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `token` | `iS7pza` | Required | The id of the invite being used. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
+     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/useInviteToken \
+     -d '{ "token": "iS7pza" }'
+```
+
+## Example Result
+
+```json
+{
+    "room": {
+        "rid": "QqsWiqNH2TnxtvZQq",
+        "fname": "a-room-name",
+        "name": "a-room-name",
+        "t": "p"
+    },
+    "success": true
+}
+```

developer-guides/rest-api/invites/validateInviteToken/README.md

@@ -0,0 +1,32 @@
+# Validate Invite Token
+
+Checks if an invite token is valid. No permissions are required.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/validateInviteToken` | `no` | `POST` |
+
+## Payload
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `token` | `iS7pza` | Required | The id of the invite being validated. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
+     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/validateInviteToken \
+     -d '{ "token": "iS7pza" }'
+```
+
+## Example Result
+
+```json
+{
+  "valid": true,
+  "success": true
+}
+```