Events: Add Category and Custom Arg Support

[jameskbride]

Context

78 previously added support for basic delivered events, but did not include commonly used properties such as category and custom_args. This PR adds support for:

• applying the category from the send categories
• applying custom_args from the send request at the root level
• applying custom_args from the send request at the personalization level

Changes

• Updated the JSON schema to allow and validate categories for /v3/mail/send.
• Updated the JSON schema to allow and validate custom_args at the root level.
• Updated the JSON schema to allow and validate custom_args at the personalization level.
• Updated the MailHandler.sendDeliveryEvents function to apply these properties to events.

Testing

Use the following Python script to start a mini server to receive events:

import http.server
import socketserver

class MyHandler(http.server.SimpleHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(content_length)
        print(f'post_data: {post_data}')

        self.send_response(200)
        self.send_header('Content-type', 'text/plain')
        self.end_headers()

        response = b'POST request received:\n' + post_data
        self.wfile.write(response)

PORT = 8080

with socketserver.TCPServer(("", PORT), MyHandler) as httpd:
    print(f"Serving at port {PORT}")
    httpd.serve_forever()

Start the application with the EVENT_DELIVERY_URL set:

    API_KEY=sendgrid-api-key EVENT_DELIVERY_URL=http://localhost:8080 npm run dev

Categories

1. Send a request that does not include categories:

   curl --request POST \
     --url http://localhost:3000/v3/mail/send \
     --header 'Authorization: Bearer sendgrid-api-key' \
     --header 'Content-Type: application/json' \
     --header 'User-Agent: insomnia/9.3.2' \
     --data '{
     "personalizations": [
       {
         "to": [{
           "email": "to@example.com"
         }, {
           "email": "to2@example.com"
         }]
       }
     ],
     "from": {
       "email": "from@example.com"
     },
       "subject": "Some subject",
       "content": [
       {
         "type": "text/plain",
         "value": "important content"
       }
     ],
     "template_id": "test-template-id"
   }
   '

2. ✅ Validate that an event with a "category": [] property is received.
3. Send the same event with a "categories": ["first", "second"] property.
4. ✅ Validate that an event with a "category": ["first", "second"] property is received.

Custom Args

1. Send a request that includes custom args at the root level as well as at the personalization level:

   curl --request POST \
     --url http://localhost:3000/v3/mail/send \
     --header 'Authorization: Bearer sendgrid-api-key' \
     --header 'Content-Type: application/json' \
     --header 'User-Agent: insomnia/9.3.2' \
     --data '{
     "personalizations": [
       {
         "to": [{
           "email": "to@example.com"
         }, {
           "email": "to2@example.com"
         }],
               "custom_args": {
                   "key1": "value2",
                   "key2": "something else",
                   "key with spaces": "spaces work"
               }
       }
     ],
     "from": {
       "email": "from@example.com"
     },
       "subject": "Some subject",
       "content": [
       {
         "type": "text/plain",
         "value": "important content"
       }
     ],
     "template_id": "test-template-id",
       "categories": ["pets", "animals"],
       "custom_args": {
           "key1": "value1",
           "key3": "from mail",
           "smtp-id": "234234"
       }
   }
   '

2. ✅ Validate that each event contains the key3 property.
3. ✅ Reserved keys: validate that the smtp-id is not the key specified in the root level custom_args. This is a generated value.
4. ✅ Validate that each event contains key1, key2, key with spaces with values taken from the personalization.
5. ✅ Validate that v3/mail/send requests can continue to be made without custom_args at either the root or personalization levels.

[jameskbride]

Hi @janjaali, I have another events-related PR when you get a chance. This one adds event support for category and custom_args. Let me know what you think, and any feedback is welcome. Thanks!

[janjaali]

Hii @jameskbride, thanks for your contribution. I will try to have a look this week.

[janjaali]

Released with https://github.com/janjaali/sendGrid-mock/releases/tag/v1.12.0. Thanks for contribution 👍.

[jameskbride]

Released with https://github.com/janjaali/sendGrid-mock/releases/tag/v1.12.0. Thanks for contribution 👍.

Great, thanks @janjaali!