@unboundcx/sdk 2.7.7 → 2.8.0

package/services/messaging/EmailAnalyticsService.js

@@ -0,0 +1,109 @@
+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'
+   * @param {string} [params.timezone='UTC'] - Timezone for data grouping (e.g., 'America/New_York', 'UTC')
+   * @returns {Promise<Object>} Time series data with summary statistics
+   * @example
+   * // Get hourly analytics for last 24 hours in EST
+   * const analytics = await sdk.messaging.email.analytics.timeSeries({
+   *   period: '24h',
+   *   granularity: 'hour',
+   *   timezone: 'America/New_York'
+   * });
+   * // Returns: { period, granularity, timezone, data: [{ timestamp, sent, delivered, failed, queued }], summary }
+   */
+  async timeSeries({ period, granularity, timezone } = {}) {
+    const options = { query: {} };
+    if (period) options.query.period = period;
+    if (granularity) options.query.granularity = granularity;
+    if (timezone) options.query.timezone = timezone;
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/analytics/timeseries',
+      'GET',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Get email queue summary statistics including engagement metrics
+   * @param {Object} [params] - Summary parameters
+   * @param {string} [params.period='24h'] - Time period: '1h', '6h', '24h', '7d', '30d'
+   * @param {string} [params.timezone='UTC'] - Timezone for data calculation (e.g., 'America/New_York', 'UTC')
+   * @returns {Promise<Object>} Summary statistics with engagement metrics
+   * @example
+   * // Get comprehensive summary stats for last 24 hours in PST
+   * const summary = await sdk.messaging.email.analytics.summary({
+   *   period: '24h',
+   *   timezone: 'America/Los_Angeles'
+   * });
+   * // Returns: {
+   * //   totalSent, totalDelivered, totalFailed, totalQueued,
+   * //   deliveryRate, errorRate, avgProcessingSeconds, avgEmailsPerHour, avgEmailsPerMinute,
+   * //   totalReceived, avgReceivedPerHour, avgReceivedPerMinute,
+   * //   totalOpened, totalOpenEvents, openRate,
+   * //   totalClicked, totalClickEvents, clickRate,
+   * //   totalBounced, totalBounceEvents, bounceRate,
+   * //   totalComplained, totalComplaintEvents, complaintRate,
+   * //   outboundErrors: [{ id, errorMessage, toEmail, createdAt }]
+   * // }
+   */
+  async summary({ period, timezone } = {}) {
+    const options = { query: {} };
+    if (period) options.query.period = period;
+    if (timezone) options.query.timezone = timezone;
+
+    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;
+  }
+}

package/services/messaging/EmailDomainsService.js

@@ -0,0 +1,252 @@
+export class EmailDomainsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * 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: domainData,
+    };
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/validate/domain',
+      'POST',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Delete domain verification
+   * @param {string} domainId - Domain ID (required)
+   * @returns {Promise<Object>} Deletion confirmation
+   */
+  async delete(domainId) {
+    this.sdk.validateParams(
+      { domainId },
+      {
+        domainId: { type: 'string', required: true },
+      },
+    );
+
+    const options = {
+      body: { domainId },
+    };
+
+    const result = await this.sdk._fetch(
+      '/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/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 },
+      {
+        domain: { type: 'string', required: true },
+      },
+    );
+
+    const options = {
+      query: { domain },
+    };
+
+    const result = await this.sdk._fetch(
+      '/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 },
+      {
+        domain: { type: 'string', required: true },
+      },
+    );
+
+    const options = {
+      query: { domain },
+    };
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/validate/domain/status',
+      'GET',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * 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(
+      { domainId },
+      {
+        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 = { domainId };
+    if (primaryRegion) updateData.primaryRegion = primaryRegion;
+    if (secondaryRegion) updateData.secondaryRegion = secondaryRegion;
+    if (dkimEnabled !== undefined) updateData.dkimEnabled = dkimEnabled;
+    if (customDkim) updateData.customDkim = customDkim;
+
+    const options = {
+      body: updateData,
+    };
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/validate/domain',
+      'PUT',
+      options,
+    );
+    return result;
+  }
+}