@unboundcx/sdk 2.7.4 → 2.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.7.4",
+  "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,6 +212,7 @@ export class EmailService {
     this.templates = new EmailTemplatesService(sdk);
     this.domains = new EmailDomainsService(sdk);
     this.addresses = new EmailAddressesService(sdk);
+    this.analytics = new EmailAnalyticsService(sdk);
   }
 
   /**
@@ -557,13 +558,90 @@ export class EmailDomainsService {
 
   /**
    * List all verified domains
-   * @returns {Promise<Array>} List of verified domains with status
+   * @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/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)
@@ -1831,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;
+  }
+}