Merge cb4b80b into 7f35a5c

lib/controllers/v1/messages_controller.js

@@ -0,0 +1,55 @@
+const { messages } = require( "inaturalistjs" );
+const InaturalistAPI = require( "../../inaturalist_api" );
+const ESModel = require( "../../models/es_model" );
+const Message = require( "../../models/message" );
+const User = require( "../../models/user" );
+
+const MessagesController = class MessagesController {
+  static create( req, callback ) {
+    InaturalistAPI.iNatJSWrap( messages.create, req )
+      .then( r => callback( null, r ) )
+      .catch( callback );
+  }
+
+  static delete( req, callback ) {
+    InaturalistAPI.iNatJSWrap( messages.delete, req )
+      .then( r => callback( null, r ) )
+      .catch( callback );
+  }
+
+  static index( req, callback ) {
+    InaturalistAPI.iNatJSWrap( messages.search, req )
+      .then( r => {
+        Message.preloadInto( r.results, {}, msgPreloadErr => {
+          if ( msgPreloadErr ) { return void callback( msgPreloadErr ); }
+          callback( null, r );
+        } );
+      } )
+      .catch( callback );
+  }
+
+  static show( req, callback ) {
+    InaturalistAPI.iNatJSWrap( messages.fetch, req )
+      .then( r => {
+        Message.preloadInto( r.results, {}, msgPreloadErr => {
+          if ( msgPreloadErr ) { return void callback( msgPreloadErr ); }
+          ESModel.fetchBelongsTo( [r], User, {
+            idFields: { reply_to_user_id: "reply_to_user" }
+          }, fetchUsersErr => {
+            if ( fetchUsersErr ) { return void callback( fetchUsersErr ); }
+            delete r.reply_to_user_id;
+            callback( null, r );
+          } );
+        } );
+      } )
+      .catch( callback );
+  }
+
+  static unread( req, callback ) {
+    InaturalistAPI.iNatJSWrap( messages.unread, req )
+      .then( r => callback( null, r ) )
+      .catch( callback );
+  }
+};
+
+module.exports = MessagesController;

lib/inaturalist_api.js

@@ -169,6 +169,7 @@ InaturalistAPI.server = ( ) => {
   const ControlledTermsController = require( "./controllers/v1/controlled_terms_controller" );
   const FlagsController = require( "./controllers/v1/flags_controller" );
   const IdentificationsController = require( "./controllers/v1/identifications_controller" );
+  const MessagesController = require( "./controllers/v1/messages_controller" );
   const ObservationFieldsController = require( "./controllers/v1/observation_fields_controller" );
   const ObservationFieldValuesController = require( "./controllers/v1/observation_field_values_controller" );
   const ObservationPhotosController = require( "./controllers/v1/observation_photos_controller" );
@@ -429,6 +430,13 @@ InaturalistAPI.server = ( ) => {
   dfault( "put", "/v1/identifications/:id", IdentificationsController.update );
   dfault( "delete", "/v1/identifications/:id", IdentificationsController.delete );
 
+  // Messages
+  dfault( "post", "/v1/messages", MessagesController.create );
+  dfault( "delete", "/v1/messages/:id", MessagesController.delete );
+  dfault( "get", "/v1/messages", MessagesController.index );
+  dfault( "get", "/v1/messages/unread", MessagesController.unread );
+  dfault( "get", "/v1/messages/:id", MessagesController.show );
+
   // ObservationFields
   dfault( "get", "/v1/observation_fields/autocomplete", ObservationFieldsController.autocomplete );
   dfault( "post", "/v1/observation_field_values", ObservationFieldValuesController.create );

lib/models/message.js

@@ -0,0 +1,20 @@
+const Model = require( "./model" );
+const ESModel = require( "./es_model" );
+const User = require( "./user" );
+
+const Message = class Message extends Model {
+  static preloadInto( arr, localeOpts, callback ) {
+    ESModel.fetchBelongsTo( arr, User, {
+      idFields: { to_user_id: "to_user", from_user_id: "from_user" }
+    }, fetchUsersErr => {
+      if ( fetchUsersErr ) { return void callback( fetchUsersErr ); }
+      arr.forEach( m => {
+        delete m.from_user_id;
+        delete m.to_user_id;
+      } );
+      callback( null, arr );
+    } );
+  }
+};
+
+module.exports = Message;

lib/views/swagger_v1.yml.ejs

@@ -85,6 +85,8 @@ tags:
     description: Create and delete flags
   - name: Identifications
     description: Create, update, and delete
+  - name: Messages
+    description: Create, fetch, delete
   - name: Observation Field Values
     description: Create, update, and delete
   - name: Observation Photos
@@ -502,6 +504,143 @@ paths:
       responses:
         200:
           description: OK
+  /messages:
+    get:
+      summary: Retrieve messages for the authenticated user. This does not mark them as read.
+      description:
+        Show the user's inbox or sent box
+      parameters:
+        - $ref: "#/parameters/page"
+        - name: box
+          in: query
+          type: string
+          description: Whether to view messages the user has received (default) or messages the user has sent
+          default: inbox
+          enum: [inbox, sent]
+        - name: q
+          in: query
+          type: string
+          description: Search query for subject and body
+        - name: user_id
+          in: query
+          type: string
+          description: User ID or username of correspondent to filter by
+      tags:
+        - Messages
+      security:
+        - api_token: []
+      responses:
+        200:
+          description: |
+            Returns an object with metadata and an array of messages
+          schema:
+            $ref: "#/definitions/MessagesResponse"
+        default:
+          description: Unexpected error
+          schema:
+            $ref: "#/definitions/Error"
+    post:
+      summary: Create a new message
+      description: Create and deliver a new message to another user
+      tags:
+        - Messages
+      security:
+        - api_token: []
+      parameters:
+        - name: from_user_id
+          in: body
+          type: integer
+          description: User ID of the recipient
+        - name: thread_id
+          in: body
+          type: integer
+          description: |
+            Identifier for the thread. Should be blank for new threads, but when
+            replying to an existing message, it should be set to the thread_id
+            of the message being replied to.
+        - name: subject
+          in: body
+          type: string
+          description: Subject of the message
+        - name: body
+          in: body
+          type: string
+          description: Body of the message
+  /messages/{id}:
+    get:
+      summary: Retrieve messages in a thread
+      description: |
+        Retrieves all messages in the thread the specified message belongs to
+        and marks them all as read.
+      tags:
+        - Messages
+      security:
+        - api_token: []
+      responses:
+        200:
+          description: |
+            Returns an object with metadata and an array of messages
+          schema:
+            properties:
+              reply_to_user:
+                description: User to reply to
+                $ref: "#/definitions/User"
+              thread_id:
+                description: Identifier for this thread
+                type: integer
+              flaggable_message_id:
+                description: |
+                  Identifier for the message that should be flagged if the user
+                  chooses to flag this thread
+                type: integer
+              results:
+                type: array
+                items:
+                  $ref: "#/definitions/Message"
+        default:
+          description: Unexpected error
+          schema:
+            $ref: "#/definitions/Error"
+    delete:
+      summary: Delete a message / thread
+      description: |
+        This will all of the authenticated user's copies of the messages in tha
+        thread to which the specified message belongs.
+      tags:
+        - Messages
+      security:
+        - api_token: []
+      responses:
+        200:
+          description: |
+            No return data, 200 just means deletion was successful
+        404:
+          description: |
+            Specified message doesn't exist
+        default:
+          description: Unexpected error
+          schema:
+            $ref: "#/definitions/Error"
+  /messages/unread:
+    get:
+      summary: Gets a count of messages the authenticated user has not read
+      summary: Simple response to get the unread messages count
+      tags:
+        - Messages
+      security:
+        - api_token: []
+      responses:
+        200:
+          description: Number of unread messages
+          schema:
+            properties:
+              count:
+                type: integer
+                description: Number of unread messages
+        default:
+          description: Unexpected error
+          schema:
+            $ref: "#/definitions/Error"
   /observations/{id}:
     get:
       summary: Observation Details
@@ -3289,6 +3428,28 @@ definitions:
         type: boolean
       taxon:
         $ref: "#/definitions/ObservationTaxon"
+  Message:
+    type: object
+    properties:
+      id:
+        type: integer
+      subject:
+        type: string
+      body:
+        type: string
+      user_id:
+        type: integer
+        description: |
+          ID of the user to whom this message belongs. Messages work like email, so the
+          sender gets a copy and the recipient gets a copy of each message. This
+          is always the authenticated user, so there's no real need for a full
+          user object.
+      to_user:
+        definition: Message recipient
+        $ref: "#/definitions/User"
+      from_user:
+        definition: Message sender
+        $ref: "#/definitions/User"
   NonOwnerIdentification:
     type: object
     properties:
@@ -3662,6 +3823,16 @@ definitions:
       name:
         type: string
   # Responses
+  MessagesResponse:
+    allOf:
+      - $ref: "#/definitions/BaseResponse"
+      - required:
+        - results
+        properties:
+          results:
+            type: array
+            items:
+              $ref: "#/definitions/Message"
   NearbyPlacesResponse:
     allOf:
       - $ref: "#/definitions/BaseResponse"