@unboundcx/sdk 2.7.3 → 2.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
   "main": "index.js",
   "type": "module",

package/services/messaging.js

@@ -212,39 +212,64 @@ export class EmailService {
     this.templates = new EmailTemplatesService(sdk);
     this.domains = new EmailDomainsService(sdk);
     this.addresses = new EmailAddressesService(sdk);
+    this.analytics = new EmailAnalyticsService(sdk);
   }
 
+  /**
+   * Send an email message
+   * @param {Object} params - Email parameters
+   * @param {string} params.from - Sender email address (required)
+   * @param {string|Array<string>} params.to - Recipient email address(es) (required)
+   * @param {string} params.subject - Email subject (required)
+   * @param {string|Array<string>} [params.cc] - CC recipients
+   * @param {string|Array<string>} [params.bcc] - BCC recipients
+   * @param {string} [params.html] - HTML email body
+   * @param {string} [params.text] - Plain text email body
+   * @param {string} [params.templateId] - Email template ID to use
+   * @param {Object} [params.variables] - Template variables for substitution
+   * @param {Array} [params.storageId] - Array of storage IDs for attachments
+   * @param {string} [params.replyTo] - Reply-to email address
+   * @param {string} [params.replyToEmailId] - ID of email this is replying to
+   * @param {string} [params.relatedId] - Related record ID
+   * @param {string} [params.emailType='marketing'] - Email type: 'marketing' or 'transactional'
+   * @param {boolean} [params.tracking=true] - Enable email tracking (opens, clicks)
+   * @returns {Promise<Object>} Email send result with ID
+   */
   async send({
     from,
     to,
     cc,
     bcc,
     subject,
-    htmlBody,
-    textBody,
+    html,
+    text,
     templateId,
     variables,
-    attachments,
+    storageId,
     replyTo,
-    priority,
-    tags,
+    replyToEmailId,
+    relatedId,
+    emailType,
+    tracking,
   }) {
     this.sdk.validateParams(
       { from, to, subject },
       {
         from: { type: 'string', required: true },
-        to: { type: 'string', required: true },
+        to: { type: ['string', 'array'], required: true },
         subject: { type: 'string', required: true },
-        cc: { type: 'string', required: false },
-        bcc: { type: 'string', required: false },
-        htmlBody: { type: 'string', required: false },
-        textBody: { type: 'string', required: false },
+        cc: { type: ['string', 'array'], required: false },
+        bcc: { type: ['string', 'array'], required: false },
+        html: { type: 'string', required: false },
+        text: { type: 'string', required: false },
         templateId: { type: 'string', required: false },
         variables: { type: 'object', required: false },
-        attachments: { type: 'array', required: false },
+        storageId: { type: 'array', required: false },
         replyTo: { type: 'string', required: false },
-        priority: { type: 'string', required: false },
-        tags: { type: 'array', required: false },
+        replyToEmailId: { type: 'string', required: false },
+        relatedId: { type: 'string', required: false },
+        emailType: { type: 'string', required: false },
+        tracking: { type: 'boolean', required: false },
       },
     );
 
@@ -256,14 +281,16 @@ export class EmailService {
 
     if (cc) emailData.cc = cc;
     if (bcc) emailData.bcc = bcc;
-    if (htmlBody) emailData.htmlBody = htmlBody;
-    if (textBody) emailData.textBody = textBody;
+    if (html) emailData.html = html;
+    if (text) emailData.text = text;
     if (templateId) emailData.templateId = templateId;
     if (variables) emailData.variables = variables;
-    if (attachments) emailData.attachments = attachments;
+    if (storageId) emailData.storageId = storageId;
     if (replyTo) emailData.replyTo = replyTo;
-    if (priority) emailData.priority = priority;
-    if (tags) emailData.tags = tags;
+    if (replyToEmailId) emailData.replyToEmailId = replyToEmailId;
+    if (relatedId) emailData.relatedId = relatedId;
+    if (emailType) emailData.emailType = emailType;
+    if (tracking !== undefined) emailData.tracking = tracking;
 
     const options = {
       body: emailData,
@@ -273,6 +300,11 @@ export class EmailService {
     return result;
   }
 
+  /**
+   * Get email message by ID
+   * @param {string} id - Email message ID (required)
+   * @returns {Promise<Object>} Email message details
+   */
   async get(id) {
     this.sdk.validateParams(
       { id },
@@ -285,11 +317,19 @@ export class EmailService {
     return result;
   }
 
-  async updateDomain(domain, { dkimEnabled, customDkim }) {
+  /**
+   * Update domain email settings
+   * @param {string} id - Domain ID (required)
+   * @param {Object} params - Update parameters
+   * @param {boolean} [params.dkimEnabled] - Enable DKIM signing
+   * @param {Object} [params.customDkim] - Custom DKIM configuration
+   * @returns {Promise<Object>} Updated domain details
+   */
+  async updateDomain(id, { dkimEnabled, customDkim }) {
     this.sdk.validateParams(
-      { domain },
+      { id },
       {
-        domain: { type: 'string', required: true },
+        id: { type: 'string', required: true },
         dkimEnabled: { type: 'boolean', required: false },
         customDkim: { type: 'object', required: false },
       },
@@ -304,7 +344,7 @@ export class EmailService {
     };
 
     const result = await this.sdk._fetch(
-      `/messaging/email/domain/${domain}`,
+      `/messaging/email/${id}`,
       'PUT',
       options,
     );
@@ -317,21 +357,31 @@ export class EmailTemplatesService {
     this.sdk = sdk;
   }
 
-  async create({ name, subject, htmlBody, textBody, variables }) {
+  /**
+   * Create email template
+   * @param {Object} params - Template parameters
+   * @param {string} params.name - Template name (required)
+   * @param {string} params.subject - Template subject (required)
+   * @param {string} [params.html] - HTML template body
+   * @param {string} [params.text] - Plain text template body
+   * @param {Object} [params.variables] - Template variable definitions
+   * @returns {Promise<Object>} Created template details
+   */
+  async create({ name, subject, html, text, variables }) {
     this.sdk.validateParams(
       { name, subject },
       {
         name: { type: 'string', required: true },
         subject: { type: 'string', required: true },
-        htmlBody: { type: 'string', required: false },
-        textBody: { type: 'string', required: false },
+        html: { type: 'string', required: false },
+        text: { type: 'string', required: false },
         variables: { type: 'object', required: false },
       },
     );
 
     const templateData = { name, subject };
-    if (htmlBody) templateData.htmlBody = htmlBody;
-    if (textBody) templateData.textBody = textBody;
+    if (html) templateData.html = html;
+    if (text) templateData.text = text;
     if (variables) templateData.variables = variables;
 
     const options = {
@@ -339,22 +389,33 @@ export class EmailTemplatesService {
     };
 
     const result = await this.sdk._fetch(
-      '/messaging/email/templates',
+      '/messaging/email/template',
       'POST',
       options,
     );
     return result;
   }
 
-  async update(id, { name, subject, htmlBody, textBody, variables }) {
+  /**
+   * Update email template
+   * @param {string} id - Template ID (required)
+   * @param {Object} params - Update parameters
+   * @param {string} [params.name] - Template name
+   * @param {string} [params.subject] - Template subject
+   * @param {string} [params.html] - HTML template body
+   * @param {string} [params.text] - Plain text template body
+   * @param {Object} [params.variables] - Template variable definitions
+   * @returns {Promise<Object>} Updated template details
+   */
+  async update(id, { name, subject, html, text, variables }) {
     this.sdk.validateParams(
       { id },
       {
         id: { type: 'string', required: true },
         name: { type: 'string', required: false },
         subject: { type: 'string', required: false },
-        htmlBody: { type: 'string', required: false },
-        textBody: { type: 'string', required: false },
+        html: { type: 'string', required: false },
+        text: { type: 'string', required: false },
         variables: { type: 'object', required: false },
       },
     );
@@ -362,8 +423,8 @@ export class EmailTemplatesService {
     const updateData = {};
     if (name) updateData.name = name;
     if (subject) updateData.subject = subject;
-    if (htmlBody) updateData.htmlBody = htmlBody;
-    if (textBody) updateData.textBody = textBody;
+    if (html) updateData.html = html;
+    if (text) updateData.text = text;
     if (variables) updateData.variables = variables;
 
     const options = {
@@ -371,13 +432,18 @@ export class EmailTemplatesService {
     };
 
     const result = await this.sdk._fetch(
-      `/messaging/email/templates/${id}`,
+      `/messaging/email/template/${id}`,
       'PUT',
       options,
     );
     return result;
   }
 
+  /**
+   * Delete email template
+   * @param {string} id - Template ID (required)
+   * @returns {Promise<Object>} Deletion confirmation
+   */
   async delete(id) {
     this.sdk.validateParams(
       { id },
@@ -387,12 +453,17 @@ export class EmailTemplatesService {
     );
 
     const result = await this.sdk._fetch(
-      `/messaging/email/templates/${id}`,
+      `/messaging/email/template/${id}`,
       'DELETE',
     );
     return result;
   }
 
+  /**
+   * Get email template by ID
+   * @param {string} id - Template ID (required)
+   * @returns {Promise<Object>} Template details
+   */
   async get(id) {
     this.sdk.validateParams(
       { id },
@@ -402,14 +473,18 @@ export class EmailTemplatesService {
     );
 
     const result = await this.sdk._fetch(
-      `/messaging/email/templates/${id}`,
+      `/messaging/email/template/${id}`,
       'GET',
     );
     return result;
   }
 
+  /**
+   * List all email templates
+   * @returns {Promise<Array>} List of email templates
+   */
   async list() {
-    const result = await this.sdk._fetch('/messaging/email/templates', 'GET');
+    const result = await this.sdk._fetch('/messaging/email/template', 'GET');
     return result;
   }
 }
@@ -419,46 +494,159 @@ export class EmailDomainsService {
     this.sdk = sdk;
   }
 
-  async create(domain) {
+  /**
+   * Create domain verification
+   * @param {Object} params - Domain parameters
+   * @param {string} params.domain - Domain name (required)
+   * @param {string} [params.primaryRegion] - Primary AWS region
+   * @param {string} [params.secondaryRegion] - Secondary AWS region
+   * @param {string} [params.mailFromSubdomain='mail'] - Mail-from subdomain
+   * @returns {Promise<Object>} Created domain with DNS records to configure
+   */
+  async create({ domain, primaryRegion, secondaryRegion, mailFromSubdomain }) {
     this.sdk.validateParams(
       { domain },
       {
         domain: { type: 'string', required: true },
+        primaryRegion: { type: 'string', required: false },
+        secondaryRegion: { type: 'string', required: false },
+        mailFromSubdomain: { type: 'string', required: false },
       },
     );
 
+    const domainData = { domain };
+    if (primaryRegion) domainData.primaryRegion = primaryRegion;
+    if (secondaryRegion) domainData.secondaryRegion = secondaryRegion;
+    if (mailFromSubdomain) domainData.mailFromSubdomain = mailFromSubdomain;
+
     const options = {
-      body: { domain },
+      body: domainData,
     };
 
     const result = await this.sdk._fetch(
-      '/messaging/email/domains',
+      '/messaging/email/validate/domain',
       'POST',
       options,
     );
     return result;
   }
 
-  async delete(domain) {
+  /**
+   * Delete domain verification
+   * @param {string} domainId - Domain ID (required)
+   * @returns {Promise<Object>} Deletion confirmation
+   */
+  async delete(domainId) {
     this.sdk.validateParams(
-      { domain },
+      { domainId },
       {
-        domain: { type: 'string', required: true },
+        domainId: { type: 'string', required: true },
       },
     );
 
+    const options = {
+      body: { domainId },
+    };
+
     const result = await this.sdk._fetch(
-      `/messaging/email/domains/${domain}`,
+      '/messaging/email/validate/domain',
       'DELETE',
+      options,
     );
     return result;
   }
 
+  /**
+   * List all verified domains
+   * @returns {Promise<Array>} List of verified domains with status, regions, and portal information
+   * @example
+   * // Returns array of domain objects:
+   * // {
+   * //   id: 'domain-id',
+   * //   domain: 'mydomain.com', 
+   * //   primaryRegion: 'us-east-1',
+   * //   secondaryRegion: 'us-west-2',
+   * //   primaryRegionStatus: 'active',
+   * //   secondaryRegionStatus: 'active',
+   * //   portalId: 'portal-id',
+   * //   portalName: 'My Portal',
+   * //   recordTypeId: 'record-type-id',
+   * //   isDeleted: false,
+   * //   createdAt: '2023-...'
+   * // }
+   */
   async list() {
-    const result = await this.sdk._fetch('/messaging/email/domains', 'GET');
+    const result = await this.sdk._fetch('/messaging/email/validate/domain', 'GET');
     return result;
   }
 
+  /**
+   * Get domain details by ID including DNS configuration
+   * @param {string} domainId - Domain ID (required)
+   * @returns {Promise<Object>} Domain details with DNS records to configure
+   * @example
+   * // Returns domain object with DNS records:
+   * // {
+   * //   id: 'domain-id',
+   * //   domain: 'mydomain.com',
+   * //   primaryRegion: 'us-east-1',
+   * //   secondaryRegion: 'us-west-2', 
+   * //   primaryRegionStatus: 'active',
+   * //   secondaryRegionStatus: 'active',
+   * //   mailFrom: 'mail.mydomain.com',
+   * //   portalId: 'portal-id',
+   * //   portalName: 'My Portal',
+   * //   brandId: 'brand-id',
+   * //   recordTypeId: 'record-type-id',
+   * //   createdAt: '2023-...',
+   * //   dns: [
+   * //     {
+   * //       type: 'CNAME',
+   * //       name: 'domainid._domainkey.mydomain.com',
+   * //       value: 'domainid.dkim.example.com',
+   * //       description: 'DKIM signature verification'
+   * //     },
+   * //     {
+   * //       type: 'CNAME', 
+   * //       name: 'mail.mydomain.com',
+   * //       value: 'mail.ses.amazonaws.com',
+   * //       description: 'MAIL FROM domain routing'
+   * //     },
+   * //     {
+   * //       type: 'TXT',
+   * //       name: 'mydomain.com',
+   * //       value: '"v=spf1 include:mail.mydomain.com ~all"',
+   * //       description: 'SPF record for email authentication'
+   * //     },
+   * //     {
+   * //       type: 'TXT',
+   * //       name: '_dmarc.mydomain.com', 
+   * //       value: '"v=DMARC1; p=quarantine; rua=mailto:dmarc@...',
+   * //       description: 'DMARC policy for email authentication and reporting'
+   * //     }
+   * //   ]
+   * // }
+   */
+  async get(domainId) {
+    this.sdk.validateParams(
+      { domainId },
+      {
+        domainId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/messaging/email/validate/domain/${domainId}`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Validate DNS records for domain
+   * @param {string} domain - Domain name (required)
+   * @returns {Promise<Object>} DNS validation results
+   */
   async validateDns(domain) {
     this.sdk.validateParams(
       { domain },
@@ -467,13 +655,23 @@ export class EmailDomainsService {
       },
     );
 
+    const options = {
+      query: { domain },
+    };
+
     const result = await this.sdk._fetch(
-      `/messaging/email/domains/${domain}/validate`,
-      'POST',
+      '/messaging/email/validate/domain/dns',
+      'GET',
+      options,
     );
     return result;
   }
 
+  /**
+   * Check domain verification status
+   * @param {string} domain - Domain name (required)
+   * @returns {Promise<Object>} Domain verification status
+   */
   async checkStatus(domain) {
     this.sdk.validateParams(
       { domain },
@@ -482,24 +680,43 @@ export class EmailDomainsService {
       },
     );
 
+    const options = {
+      query: { domain },
+    };
+
     const result = await this.sdk._fetch(
-      `/messaging/email/domains/${domain}/status`,
+      '/messaging/email/validate/domain/status',
       'GET',
+      options,
     );
     return result;
   }
 
-  async update(domain, { dkimEnabled, customDkim }) {
+  /**
+   * Update domain settings
+   * @param {Object} params - Update parameters
+   * @param {string} params.domainId - Domain ID (required)
+   * @param {string} [params.primaryRegion] - Primary AWS region
+   * @param {string} [params.secondaryRegion] - Secondary AWS region
+   * @param {boolean} [params.dkimEnabled] - Enable DKIM signing
+   * @param {Object} [params.customDkim] - Custom DKIM configuration
+   * @returns {Promise<Object>} Updated domain details
+   */
+  async update({ domainId, primaryRegion, secondaryRegion, dkimEnabled, customDkim }) {
     this.sdk.validateParams(
-      { domain },
+      { domainId },
       {
-        domain: { type: 'string', required: true },
+        domainId: { type: 'string', required: true },
+        primaryRegion: { type: 'string', required: false },
+        secondaryRegion: { type: 'string', required: false },
         dkimEnabled: { type: 'boolean', required: false },
         customDkim: { type: 'object', required: false },
       },
     );
 
-    const updateData = {};
+    const updateData = { domainId };
+    if (primaryRegion) updateData.primaryRegion = primaryRegion;
+    if (secondaryRegion) updateData.secondaryRegion = secondaryRegion;
     if (dkimEnabled !== undefined) updateData.dkimEnabled = dkimEnabled;
     if (customDkim) updateData.customDkim = customDkim;
 
@@ -508,7 +725,7 @@ export class EmailDomainsService {
     };
 
     const result = await this.sdk._fetch(
-      `/messaging/email/domains/${domain}`,
+      '/messaging/email/validate/domain',
       'PUT',
       options,
     );
@@ -521,57 +738,81 @@ export class EmailAddressesService {
     this.sdk = sdk;
   }
 
-  async create(email) {
+  /**
+   * Create email address verification
+   * @param {string} emailAddress - Email address to verify (required)
+   * @returns {Promise<Object>} Email verification details
+   */
+  async create(emailAddress) {
     this.sdk.validateParams(
-      { email },
+      { emailAddress },
       {
-        email: { type: 'string', required: true },
+        emailAddress: { type: 'string', required: true },
       },
     );
 
     const options = {
-      body: { email },
+      body: { emailAddress },
     };
 
     const result = await this.sdk._fetch(
-      '/messaging/email/addresses',
+      '/messaging/email/validate/emailAddress',
       'POST',
       options,
     );
     return result;
   }
 
-  async delete(email) {
+  /**
+   * Delete email address verification
+   * @param {string} emailAddress - Email address to remove (required)
+   * @returns {Promise<Object>} Deletion confirmation
+   */
+  async delete(emailAddress) {
     this.sdk.validateParams(
-      { email },
+      { emailAddress },
       {
-        email: { type: 'string', required: true },
+        emailAddress: { type: 'string', required: true },
       },
     );
 
     const result = await this.sdk._fetch(
-      `/messaging/email/addresses/${encodeURIComponent(email)}`,
+      `/messaging/email/validate/emailAddress/${encodeURIComponent(emailAddress)}`,
       'DELETE',
     );
     return result;
   }
 
+  /**
+   * List all verified email addresses
+   * @returns {Promise<Array>} List of verified email addresses
+   */
   async list() {
-    const result = await this.sdk._fetch('/messaging/email/addresses', 'GET');
+    const result = await this.sdk._fetch('/messaging/email/validate/emailAddress', 'GET');
     return result;
   }
 
-  async checkStatus(email) {
+  /**
+   * Check email address verification status
+   * @param {string} emailAddress - Email address to check (required)
+   * @returns {Promise<Object>} Email verification status
+   */
+  async checkStatus(emailAddress) {
     this.sdk.validateParams(
-      { email },
+      { emailAddress },
       {
-        email: { type: 'string', required: true },
+        emailAddress: { type: 'string', required: true },
       },
     );
 
+    const options = {
+      query: { emailAddress },
+    };
+
     const result = await this.sdk._fetch(
-      `/messaging/email/addresses/${encodeURIComponent(email)}/status`,
+      '/messaging/email/validate/emailAddress/status',
       'GET',
+      options,
     );
     return result;
   }
@@ -1668,3 +1909,78 @@ export class TenDlcCampaignManagementService {
     return result;
   }
 }
+
+export class EmailAnalyticsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get email queue time series analytics
+   * @param {Object} [params] - Analytics parameters
+   * @param {string} [params.period='24h'] - Time period: '1h', '6h', '24h', '7d', '30d'
+   * @param {string} [params.granularity='hour'] - Data granularity: 'minute', 'hour', 'day'
+   * @returns {Promise<Object>} Time series data with summary statistics
+   * @example
+   * // Get hourly analytics for last 24 hours
+   * const analytics = await sdk.messaging.email.analytics.timeSeries({ period: '24h', granularity: 'hour' });
+   * // Returns: { period, granularity, data: [{ timestamp, sent, delivered, failed, queued }], summary }
+   */
+  async timeSeries({ period, granularity } = {}) {
+    const options = { query: {} };
+    if (period) options.query.period = period;
+    if (granularity) options.query.granularity = granularity;
+
+    const result = await this.sdk._fetch('/messaging/email/analytics/timeseries', 'GET', options);
+    return result;
+  }
+
+  /**
+   * Get email queue summary statistics
+   * @param {Object} [params] - Summary parameters
+   * @param {string} [params.period='24h'] - Time period: '1h', '6h', '24h', '7d', '30d'
+   * @returns {Promise<Object>} Summary statistics
+   * @example
+   * // Get summary stats for last 24 hours
+   * const summary = await sdk.messaging.email.analytics.summary({ period: '24h' });
+   * // Returns: { totalSent, deliveryRate, errorRate, avgEmailsPerMinute, avgProcessingSeconds }
+   */
+  async summary({ period } = {}) {
+    const options = { query: {} };
+    if (period) options.query.period = period;
+
+    const result = await this.sdk._fetch('/messaging/email/analytics/summary', 'GET', options);
+    return result;
+  }
+
+  /**
+   * Get real-time email queue metrics
+   * @returns {Promise<Object>} Real-time queue statistics
+   * @example
+   * // Get current queue status
+   * const realtime = await sdk.messaging.email.analytics.realtime();
+   * // Returns: { queueDepth, currentSendRatePerMinute, last5Minutes: { sent, delivered, failed } }
+   */
+  async realtime() {
+    const result = await this.sdk._fetch('/messaging/email/analytics/realtime', 'GET');
+    return result;
+  }
+
+  /**
+   * Get email error analysis by domain
+   * @param {Object} [params] - Error analysis parameters  
+   * @param {string} [params.period='7d'] - Time period: '24h', '7d', '30d'
+   * @returns {Promise<Object>} Error analysis with domain breakdown
+   * @example
+   * // Get error analysis for last 7 days
+   * const errors = await sdk.messaging.email.analytics.errors({ period: '7d' });
+   * // Returns: { overallErrorRate, topErrorDomains: [{ domain, errorRate, totalErrors }] }
+   */
+  async errors({ period } = {}) {
+    const options = { query: {} };
+    if (period) options.query.period = period;
+
+    const result = await this.sdk._fetch('/messaging/email/analytics/errors', 'GET', options);
+    return result;
+  }
+}