chore: import upstream snapshot with attribution

integrations/sendgrid/definitions/actions.ts

@@ -0,0 +1,27 @@
+import { z } from '@botpress/sdk'
+import { EMAIL_ADDRESS_DESCRIPTION, EmailAddressSchema, NonBlankString } from './common'
+
+/** The common send email input schema which will be exposed to users in Botpress Studio */
+export const sendMailInputSchema = z.object({
+  from: EmailAddressSchema.describe(EMAIL_ADDRESS_DESCRIPTION).title('Email Sender'),
+  to: EmailAddressSchema.describe(EMAIL_ADDRESS_DESCRIPTION).title('Email Recipient'),
+  cc: z.array(EmailAddressSchema).optional().describe('List of carbon copy recipients').title('Carbon Copy'),
+  bcc: z
+    .array(EmailAddressSchema)
+    .optional()
+    .describe('List of blind carbon copy recipients')
+    .title('Blind Carbon Copy'),
+  subject: NonBlankString.describe('The subject of the email (e.g. How to build a bot with Botpress!)').title(
+    'Email Subject'
+  ),
+  body: NonBlankString.describe('The markdown rich-text body of the email').title('Email Body'), // TODO: Think of an example to place here
+  replyTo: EmailAddressSchema.describe(EMAIL_ADDRESS_DESCRIPTION).title('Reply To').optional(),
+})
+
+/** The response schema for SendGrid's send email endpoint for successful requests. */
+export const sendEmailOutputSchema = z.object({
+  /** The output is empty because in the current SendGrid API
+   *  version, nothing is returned when the request is successful.
+   *
+   *  Observed: 2025-06-24 */
+})

integrations/sendgrid/definitions/common.ts

@@ -0,0 +1,18 @@
+import { z } from '@botpress/sdk'
+
+/** A string that must contain at least 1 non-whitespace character.
+ *
+ *  @remark This can still be an optional field */
+export const NonBlankString = z.string().trim().min(1)
+
+/** A common description that should apply to all Email Address Fields.
+ *
+ *  @remark Using this constant so it can be re-used in multiple other schemas.
+ *   This is because the linter doesn't detect the "describe" if I were to bind
+ *   it to the "EmailAddressSchema" definition */
+export const EMAIL_ADDRESS_DESCRIPTION = 'The email address of the correspondent (e.g. example@example.com)'
+
+/** A string that has been verified to be a valid email address.
+ *
+ *  @remark "correspondent" can refer to both the sender and the receiver of an email. */
+export const EmailAddressSchema = NonBlankString.email()

integrations/sendgrid/definitions/events.ts

@@ -0,0 +1,63 @@
+import { z } from '@botpress/sdk'
+import { EmailAddressSchema } from './common'
+
+const _webhookEmailEventSchema = z.object({
+  eventId: z.string().describe('The ID for the webhook event').title('Webhook event ID'),
+  /** 'messageId' will be present in almost every case where the event is tied to a sent email
+   *   (So account status changed webhook events won't have one). The only exception to a sent
+   *   email webhook event not having a message id is for "[Asynchronous Bounces](https://www.twilio.com/docs/sendgrid/ui/sending-email/bounces#asynchronous-bounces)". */
+  messageId: z.string().optional().describe('The ID for the sent email message').title('Email message ID'),
+  timestamp: z
+    .string()
+    .datetime()
+    .describe('A UTC datetime representing when the event was triggered')
+    .title('Event timestamp'),
+})
+
+export const processedEmailEventSchema = _webhookEmailEventSchema.extend({
+  sendAt: z
+    .string()
+    .datetime()
+    .describe('A UTC datetime representing when the email is scheduled to be sent at')
+    .title('Scheduled send timestamp'),
+})
+
+export const deferredEmailEventSchema = _webhookEmailEventSchema.extend({
+  attempt: z
+    .string()
+    .describe('The delivery attempts that have been made for the sent email')
+    .title('Delivery attempts'),
+})
+
+export const deliveredEmailEventSchema = _webhookEmailEventSchema.extend({
+  email: z.string().describe('The designated recipient of the email').title('Email recipient'),
+})
+
+// So far this has only been seen in Bounce events, but I will check the other error events
+// to see if they also contain this. Otherwise, I will merge into 'BouncedEmailEventPayload'
+const _emailErrorEventSchema = _webhookEmailEventSchema.extend({
+  reason: z.string().optional().describe('The reason this event was triggered').title('Event reason'),
+})
+
+export const bouncedEmailEventSchema = _emailErrorEventSchema.extend({
+  classification: z.string().describe('The SendGrid classification for the bounce').title('Bounce classification'),
+  type: z
+    .string()
+    .describe('The SendGrid type for why the email bounced (e.g. "bounce", "blocked", etc.)')
+    .title('Bounce type'),
+})
+
+export const openedEmailEventSchema = _emailErrorEventSchema.extend({
+  email: EmailAddressSchema.describe('The designated recipient of the email').title('Email recipient'),
+})
+
+export const clickedEmailLinkEventSchema = _emailErrorEventSchema.extend({
+  email: EmailAddressSchema.describe('The designated recipient of the email').title('Email recipient'),
+  url: z.string().describe('The destination URL of the link that was clicked').title('Clicked URL'),
+  urlOffset: z
+    .number()
+    .describe(
+      'A zero-based index, ordered by first appearance, of which link was clicked in an email when it shares a "url" with another link'
+    )
+    .title('URL offset'),
+})