@xenterprises/fastify-xtwilio 1.0.0

package/index.d.ts

@@ -0,0 +1,999 @@
+/**
+ * xTwilio - Fastify Plugin for Twilio Communications and SendGrid Email
+ * TypeScript Type Definitions
+ *
+ * @module @xenterprises/fastify-xtwilio
+ * @version 1.0.0
+ */
+
+import { FastifyPluginAsync, FastifyInstance } from 'fastify';
+import { Twilio } from 'twilio';
+import { ClientRequest } from '@sendgrid/client/src/request';
+
+/**
+ * SMS Message Options
+ */
+export interface SMSOptions {
+  /** Custom Twilio account SID (overrides default) */
+  accountSid?: string;
+
+  /** Media URLs for MMS */
+  mediaUrls?: string[];
+
+  /** Custom attributes */
+  attributes?: Record<string, string>;
+
+  /** Attempt number for retry logic */
+  attemptNumber?: number;
+}
+
+/**
+ * SMS Scheduled Send Options
+ */
+export interface ScheduleSMSOptions extends SMSOptions {
+  /** When to send the message */
+  sendAt: Date | string;
+}
+
+/**
+ * Bulk SMS Message
+ */
+export interface BulkSMSMessage {
+  /** Recipient phone number */
+  to: string;
+
+  /** Message body */
+  body: string;
+
+  /** Media URLs (for MMS) */
+  mediaUrls?: string[];
+
+  /** Custom options for this message */
+  options?: SMSOptions;
+}
+
+/**
+ * SMS Send Result
+ */
+export interface SMSResult {
+  /** Twilio message SID */
+  sid: string;
+
+  /** Message status */
+  status: 'queued' | 'sending' | 'sent' | 'failed' | 'delivered' | 'undelivered';
+
+  /** Recipient phone number */
+  to: string;
+
+  /** Message body (first 160 chars) */
+  body: string;
+
+  /** Number of SMS segments */
+  numSegments: number;
+
+  /** Price of the message */
+  price?: number;
+
+  /** Currency */
+  priceUnit?: string;
+
+  /** Error details if failed */
+  errorCode?: string;
+
+  /** Error message if failed */
+  errorMessage?: string;
+
+  /** Timestamp of send */
+  dateCreated: Date;
+}
+
+/**
+ * SMS Status
+ */
+export interface SMSStatus {
+  /** Message SID */
+  sid: string;
+
+  /** Current status */
+  status: string;
+
+  /** Error code if failed */
+  errorCode?: number;
+
+  /** Error message if failed */
+  errorMessage?: string;
+}
+
+/**
+ * Phone Number Validation Result
+ */
+export interface PhoneValidationResult {
+  /** Valid phone number in E.164 format */
+  phoneNumber: string;
+
+  /** Valid format */
+  isValid: boolean;
+
+  /** Country information */
+  countryCode?: string;
+
+  /** Type of number (mobile, fixed-line, etc.) */
+  numberType?: string;
+
+  /** Carrier name */
+  carrier?: string;
+
+  /** Error message if invalid */
+  error?: string;
+}
+
+/**
+ * Conversation Information
+ */
+export interface ConversationInfo {
+  /** Conversation SID */
+  sid: string;
+
+  /** Friendly name */
+  friendlyName: string;
+
+  /** Conversation state: active, inactive, closed */
+  state: 'active' | 'inactive' | 'closed';
+
+  /** Custom attributes */
+  attributes?: Record<string, any>;
+
+  /** Messaging binding address */
+  messagingBindingAddress?: string;
+
+  /** Date created */
+  dateCreated: Date;
+
+  /** Date updated */
+  dateUpdated: Date;
+
+  /** URL of this conversation resource */
+  url?: string;
+}
+
+/**
+ * Conversation Participant
+ */
+export interface ConversationParticipant {
+  /** Participant SID */
+  sid: string;
+
+  /** Conversation SID */
+  conversationSid: string;
+
+  /** Participant identity */
+  identity: string;
+
+  /** Messaging binding address (email, phone, etc.) */
+  messagingBindingAddress?: string;
+
+  /** Role of participant */
+  role: 'guest' | 'agent' | 'supervisor';
+
+  /** Date added */
+  dateCreated: Date;
+
+  /** Custom attributes */
+  attributes?: Record<string, any>;
+}
+
+/**
+ * Conversation Message
+ */
+export interface ConversationMessage {
+  /** Message SID */
+  sid: string;
+
+  /** Conversation SID */
+  conversationSid: string;
+
+  /** Account SID */
+  accountSid: string;
+
+  /** Message body */
+  body: string;
+
+  /** Message author */
+  author: string;
+
+  /** Media URL if message contains media */
+  mediaUrl?: string;
+
+  /** Message index number */
+  index: number;
+
+  /** Date created */
+  dateCreated: Date;
+
+  /** Participant SID of author */
+  participantSid?: string;
+}
+
+/**
+ * RCS Rich Card
+ */
+export interface RCSRichCard {
+  /** Card title */
+  title: string;
+
+  /** Card description */
+  description: string;
+
+  /** Media URL for card */
+  mediaUrl?: string;
+
+  /** Suggested actions */
+  actions?: Array<{
+    /** Action type */
+    type: 'url' | 'phone' | 'open_app' | 'create_calendar_event' | 'reply';
+
+    /** Action text */
+    text: string;
+
+    /** Action target (URL, phone number, etc.) */
+    url?: string;
+
+    /** Phone number for phone action */
+    phoneNumber?: string;
+
+    /** Payload for reply action */
+    payload?: string;
+  }>;
+}
+
+/**
+ * RCS Quick Reply
+ */
+export interface RCSQuickReply {
+  /** Reply text */
+  text: string;
+
+  /** Reply payload */
+  payload: string;
+}
+
+/**
+ * RCS Send Result
+ */
+export interface RCSSendResult {
+  /** Twilio message SID */
+  messageId: string;
+
+  /** Message status */
+  status: 'accepted' | 'queued' | 'sent' | 'delivered' | 'failed' | 'rejected';
+
+  /** Recipient phone number */
+  to: string;
+
+  /** Error details if failed */
+  error?: {
+    code: string;
+    message: string;
+  };
+
+  /** Timestamp */
+  timestamp: Date;
+}
+
+/**
+ * Email Options
+ */
+export interface EmailOptions {
+  /** Email priority */
+  priority?: 'low' | 'normal' | 'high';
+
+  /** Custom headers */
+  headers?: Record<string, string>;
+
+  /** Reply-to address */
+  replyTo?: string;
+
+  /** BCC recipients */
+  bcc?: string[];
+
+  /** Custom categories for tracking */
+  categories?: string[];
+
+  /** Custom metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Email with Attachments Options
+ */
+export interface EmailWithAttachmentsOptions extends EmailOptions {
+  /** Attachments array */
+  attachments: Array<{
+    /** Attachment content (base64) */
+    content: string;
+
+    /** File name */
+    filename: string;
+
+    /** MIME type */
+    type: string;
+
+    /** Content disposition */
+    disposition?: 'inline' | 'attachment';
+
+    /** Content ID for inline attachments */
+    contentId?: string;
+  }>;
+}
+
+/**
+ * Email Send Result
+ */
+export interface EmailSendResult {
+  /** SendGrid message ID */
+  messageId: string;
+
+  /** Send status */
+  status: 'success' | 'failed' | 'bounced' | 'spam' | 'blocked';
+
+  /** Recipient email */
+  to: string;
+
+  /** Subject line */
+  subject: string;
+
+  /** Timestamp of send */
+  timestamp: Date;
+
+  /** Error details if failed */
+  error?: {
+    code: number;
+    message: string;
+  };
+}
+
+/**
+ * Email Contact
+ */
+export interface EmailContact {
+  /** Contact ID */
+  id: string;
+
+  /** Email address */
+  email: string;
+
+  /** First name */
+  firstName?: string;
+
+  /** Last name */
+  lastName?: string;
+
+  /** Phone number */
+  phone?: string;
+
+  /** Company */
+  company?: string;
+
+  /** Custom fields */
+  customFields?: Record<string, string>;
+
+  /** Date added */
+  createdAt: Date;
+
+  /** Unsubscribed status */
+  isUnsubscribed?: boolean;
+}
+
+/**
+ * Email Contact List
+ */
+export interface EmailContactList {
+  /** List ID */
+  id: string;
+
+  /** List name */
+  name: string;
+
+  /** Contact count */
+  contactCount: number;
+
+  /** Date created */
+  createdAt: Date;
+
+  /** Date modified */
+  modifiedAt: Date;
+}
+
+/**
+ * SMS Service Methods
+ */
+export interface SMSService {
+  /**
+   * Send SMS message
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param options Optional SMS options
+   * @returns SMS send result
+   */
+  send(to: string, body: string, options?: SMSOptions): Promise<SMSResult>;
+
+  /**
+   * Send MMS (multimedia message)
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param mediaUrl URL of media to attach
+   * @param options Optional SMS options
+   * @returns SMS send result
+   */
+  sendMMS(
+    to: string,
+    body: string,
+    mediaUrl: string,
+    options?: SMSOptions
+  ): Promise<SMSResult>;
+
+  /**
+   * Schedule SMS for future delivery
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param sendAt When to send message
+   * @param options Optional SMS options
+   * @returns SMS send result
+   */
+  schedule(
+    to: string,
+    body: string,
+    sendAt: Date | string,
+    options?: SMSOptions
+  ): Promise<SMSResult>;
+
+  /**
+   * Cancel scheduled message
+   * @param messageSid SID of scheduled message
+   * @returns Cancellation result
+   */
+  cancelScheduled(messageSid: string): Promise<{ success: boolean }>;
+
+  /**
+   * Get message details
+   * @param messageSid Message SID
+   * @returns SMS message details
+   */
+  get(messageSid: string): Promise<SMSResult>;
+
+  /**
+   * Get message status
+   * @param messageSid Message SID
+   * @returns Message status
+   */
+  getStatus(messageSid: string): Promise<SMSStatus>;
+
+  /**
+   * List messages with optional filters
+   * @param filters Query filters
+   * @returns Array of SMS results
+   */
+  list(filters?: {
+    to?: string;
+    from?: string;
+    status?: string;
+    limit?: number;
+  }): Promise<SMSResult[]>;
+
+  /**
+   * Delete message
+   * @param messageSid Message SID to delete
+   * @returns Deletion result
+   */
+  delete(messageSid: string): Promise<{ success: boolean }>;
+
+  /**
+   * Get media from MMS message
+   * @param messageSid Message SID
+   * @returns Media URLs
+   */
+  getMedia(messageSid: string): Promise<string[]>;
+
+  /**
+   * Validate phone number
+   * @param phoneNumber Phone number to validate
+   * @param options Validation options
+   * @returns Validation result
+   */
+  validatePhoneNumber(
+    phoneNumber: string,
+    options?: { countryCode?: string }
+  ): Promise<PhoneValidationResult>;
+
+  /**
+   * Send bulk SMS messages
+   * @param messages Array of bulk messages
+   * @returns Array of send results
+   */
+  sendBulk(messages: BulkSMSMessage[]): Promise<SMSResult[]>;
+}
+
+/**
+ * Conversations Service Methods
+ */
+export interface ConversationsService {
+  /**
+   * Create new conversation
+   * @param friendlyName Conversation name
+   * @param attributes Optional custom attributes
+   * @returns Conversation info
+   */
+  create(friendlyName: string, attributes?: Record<string, any>): Promise<ConversationInfo>;
+
+  /**
+   * Get conversation details
+   * @param conversationSid Conversation SID
+   * @returns Conversation info
+   */
+  get(conversationSid: string): Promise<ConversationInfo>;
+
+  /**
+   * Update conversation
+   * @param conversationSid Conversation SID
+   * @param updates Fields to update
+   * @returns Updated conversation info
+   */
+  update(
+    conversationSid: string,
+    updates: { friendlyName?: string; state?: string; attributes?: Record<string, any> }
+  ): Promise<ConversationInfo>;
+
+  /**
+   * List conversations
+   * @param filters Optional filters
+   * @returns Array of conversations
+   */
+  list(filters?: {
+    state?: string;
+    limit?: number;
+  }): Promise<ConversationInfo[]>;
+
+  /**
+   * Delete conversation
+   * @param conversationSid Conversation SID
+   * @returns Deletion result
+   */
+  delete(conversationSid: string): Promise<{ success: boolean }>;
+
+  /**
+   * Add participant to conversation
+   * @param conversationSid Conversation SID
+   * @param identity Participant identity (email, user ID, etc.)
+   * @param messagingBindingAddress Optional messaging address (phone, email)
+   * @returns Participant info
+   */
+  addParticipant(
+    conversationSid: string,
+    identity?: string,
+    messagingBindingAddress?: string
+  ): Promise<ConversationParticipant>;
+
+  /**
+   * List conversation participants
+   * @param conversationSid Conversation SID
+   * @returns Array of participants
+   */
+  listParticipants(conversationSid: string): Promise<ConversationParticipant[]>;
+
+  /**
+   * Remove participant from conversation
+   * @param conversationSid Conversation SID
+   * @param participantSid Participant SID to remove
+   * @returns Removal result
+   */
+  removeParticipant(
+    conversationSid: string,
+    participantSid: string
+  ): Promise<{ success: boolean }>;
+
+  /**
+   * Send message to conversation
+   * @param conversationSid Conversation SID
+   * @param body Message body
+   * @param author Message author
+   * @param attributes Optional attributes
+   * @returns Message info
+   */
+  sendMessage(
+    conversationSid: string,
+    body: string,
+    author: string,
+    attributes?: Record<string, any>
+  ): Promise<ConversationMessage>;
+
+  /**
+   * Send media message to conversation
+   * @param conversationSid Conversation SID
+   * @param mediaUrl URL of media
+   * @param body Optional message text
+   * @param author Message author
+   * @returns Message info
+   */
+  sendMediaMessage(
+    conversationSid: string,
+    mediaUrl: string,
+    body?: string,
+    author?: string
+  ): Promise<ConversationMessage>;
+
+  /**
+   * Get conversation messages
+   * @param conversationSid Conversation SID
+   * @param options Query options
+   * @returns Array of messages
+   */
+  getMessages(
+    conversationSid: string,
+    options?: { limit?: number; index?: number }
+  ): Promise<ConversationMessage[]>;
+
+  /**
+   * Get specific message
+   * @param conversationSid Conversation SID
+   * @param messageSid Message SID
+   * @returns Message info
+   */
+  getMessage(conversationSid: string, messageSid: string): Promise<ConversationMessage>;
+
+  /**
+   * Delete message from conversation
+   * @param conversationSid Conversation SID
+   * @param messageSid Message SID to delete
+   * @returns Deletion result
+   */
+  deleteMessage(conversationSid: string, messageSid: string): Promise<{ success: boolean }>;
+
+  /**
+   * Get webhook configuration
+   * @param conversationSid Conversation SID
+   * @returns Webhook config
+   */
+  getWebhooks(conversationSid: string): Promise<Record<string, any>>;
+
+  /**
+   * Update webhook configuration
+   * @param conversationSid Conversation SID
+   * @param webhookConfig New webhook config
+   * @returns Updated config
+   */
+  updateWebhooks(
+    conversationSid: string,
+    webhookConfig: Record<string, any>
+  ): Promise<Record<string, any>>;
+}
+
+/**
+ * RCS Service Methods
+ */
+export interface RCSService {
+  /**
+   * Send basic RCS message
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param options Optional send options
+   * @returns Send result
+   */
+  send(to: string, body: string, options?: SMSOptions): Promise<RCSSendResult>;
+
+  /**
+   * Send RCS message with media
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param mediaUrl URL of media
+   * @returns Send result
+   */
+  sendMedia(to: string, body: string, mediaUrl: string): Promise<RCSSendResult>;
+
+  /**
+   * Send RCS message from template
+   * @param to Recipient phone number
+   * @param contentSid Template SID
+   * @param contentVariables Template variables
+   * @returns Send result
+   */
+  sendTemplate(
+    to: string,
+    contentSid: string,
+    contentVariables: Record<string, string>
+  ): Promise<RCSSendResult>;
+
+  /**
+   * Send rich card
+   * @param to Recipient phone number
+   * @param card Rich card data
+   * @returns Send result
+   */
+  sendRichCard(to: string, card: RCSRichCard): Promise<RCSSendResult>;
+
+  /**
+   * Send carousel of rich cards
+   * @param to Recipient phone number
+   * @param cards Array of rich cards
+   * @returns Send result
+   */
+  sendCarousel(to: string, cards: RCSRichCard[]): Promise<RCSSendResult>;
+
+  /**
+   * Send with quick reply options
+   * @param to Recipient phone number
+   * @param body Message body
+   * @param replies Quick reply options
+   * @returns Send result
+   */
+  sendQuickReplies(to: string, body: string, replies: RCSQuickReply[]): Promise<RCSSendResult>;
+
+  /**
+   * Get message status
+   * @param messageSid Message SID
+   * @returns Message status
+   */
+  getStatus(messageSid: string): Promise<{ status: string; timestamp: Date }>;
+
+  /**
+   * List content templates
+   * @param options Query options
+   * @returns Array of templates
+   */
+  listTemplates(options?: { limit?: number }): Promise<Array<{ sid: string; name: string }>>;
+
+  /**
+   * Get template details
+   * @param contentSid Template SID
+   * @returns Template details
+   */
+  getTemplate(contentSid: string): Promise<Record<string, any>>;
+
+  /**
+   * Delete template
+   * @param contentSid Template SID
+   * @returns Deletion result
+   */
+  deleteTemplate(contentSid: string): Promise<{ success: boolean }>;
+}
+
+/**
+ * Email Service Methods
+ */
+export interface EmailService {
+  /**
+   * Send email
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param html HTML content
+   * @param text Plain text content
+   * @param options Optional email options
+   * @returns Send result
+   */
+  send(
+    to: string,
+    subject: string,
+    html: string,
+    text?: string,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send email from template
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param templateId SendGrid template ID
+   * @param dynamicData Template variable data
+   * @param options Optional email options
+   * @returns Send result
+   */
+  sendTemplate(
+    to: string,
+    subject: string,
+    templateId: string,
+    dynamicData: Record<string, any>,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send email with attachments
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param html HTML content
+   * @param attachments Array of attachments
+   * @param options Optional email options
+   * @returns Send result
+   */
+  sendWithAttachments(
+    to: string,
+    subject: string,
+    html: string,
+    attachments: Array<{ content: string; filename: string; type: string }>,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send bulk email to multiple recipients
+   * @param to Array of recipient emails
+   * @param subject Email subject
+   * @param html HTML content
+   * @param options Optional email options
+   * @returns Array of send results
+   */
+  sendBulk(
+    to: string[],
+    subject: string,
+    html: string,
+    options?: EmailOptions
+  ): Promise<EmailSendResult[]>;
+
+  /**
+   * Send personalized bulk email
+   * @param messages Array of personalized messages
+   * @returns Array of send results
+   */
+  sendPersonalizedBulk(
+    messages: Array<{
+      to: string;
+      subject: string;
+      html: string;
+      personalData?: Record<string, string>;
+    }>
+  ): Promise<EmailSendResult[]>;
+
+  /**
+   * Validate email address
+   * @param email Email to validate
+   * @returns Validation result
+   */
+  validate(
+    email: string
+  ): Promise<{ isValid: boolean; suggestion?: string; error?: string }>;
+
+  /**
+   * Add contact to SendGrid
+   * @param email Contact email
+   * @param data Contact data
+   * @param listIds Optional list IDs
+   * @returns Contact info
+   */
+  addContact(
+    email: string,
+    data: Record<string, string>,
+    listIds?: string[]
+  ): Promise<EmailContact>;
+
+  /**
+   * Search for contact
+   * @param email Contact email
+   * @returns Contact info or null
+   */
+  searchContact(email: string): Promise<EmailContact | null>;
+
+  /**
+   * Delete contact
+   * @param contactId Contact ID
+   * @returns Deletion result
+   */
+  deleteContact(contactId: string): Promise<{ success: boolean }>;
+
+  /**
+   * Create contact list
+   * @param name List name
+   * @returns List info
+   */
+  createList(name: string): Promise<EmailContactList>;
+
+  /**
+   * Get all contact lists
+   * @returns Array of lists
+   */
+  getLists(): Promise<EmailContactList[]>;
+
+  /**
+   * Delete contact list
+   * @param listId List ID
+   * @returns Deletion result
+   */
+  deleteList(listId: string): Promise<{ success: boolean }>;
+}
+
+/**
+ * Plugin Configuration Options
+ */
+export interface XTwilioPluginOptions {
+  /** Twilio configuration */
+  twilio?: {
+    /** Twilio Account SID */
+    accountSid: string;
+
+    /** Twilio Auth Token */
+    authToken: string;
+
+    /** Twilio phone number for SMS */
+    phoneNumber: string;
+
+    /** Messaging Service SID for RCS */
+    messagingServiceSid?: string;
+
+    /** Enable Twilio service */
+    active?: boolean;
+  };
+
+  /** SendGrid configuration */
+  sendgrid?: {
+    /** SendGrid API Key */
+    apiKey: string;
+
+    /** From email address */
+    fromEmail: string;
+
+    /** From name */
+    fromName?: string;
+
+    /** Enable SendGrid service */
+    active?: boolean;
+  };
+
+  /** Enable detailed logging */
+  logRequests?: boolean;
+}
+
+/**
+ * Fastify Instance with xTwilio Decoration
+ */
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** SMS service methods */
+    sms: SMSService;
+
+    /** Conversations service methods */
+    conversations: ConversationsService;
+
+    /** RCS service methods */
+    rcs: RCSService;
+
+    /** Email service methods */
+    email: EmailService;
+
+    /** Raw Twilio client instance */
+    twilio?: Twilio;
+  }
+}
+
+/**
+ * xTwilio Plugin
+ * Registers SMS, Conversations, RCS, and Email services with Fastify
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import xTwilio from '@xenterprises/fastify-xtwilio';
+ *
+ * const fastify = Fastify();
+ *
+ * await fastify.register(xTwilio, {
+ *   twilio: {
+ *     accountSid: process.env.TWILIO_ACCOUNT_SID,
+ *     authToken: process.env.TWILIO_AUTH_TOKEN,
+ *     phoneNumber: process.env.TWILIO_PHONE_NUMBER,
+ *     messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
+ *   },
+ *   sendgrid: {
+ *     apiKey: process.env.SENDGRID_API_KEY,
+ *     fromEmail: process.env.SENDGRID_FROM_EMAIL,
+ *   },
+ * });
+ *
+ * // Send SMS
+ * const result = await fastify.sms.send('+1234567890', 'Hello World!');
+ *
+ * // Send email
+ * await fastify.email.send('user@example.com', 'Welcome', '<h1>Hello</h1>');
+ *
+ * // Create conversation
+ * const convo = await fastify.conversations.create('Support Chat');
+ * ```
+ */
+declare const xTwilio: FastifyPluginAsync<XTwilioPluginOptions>;
+
+export default xTwilio;