@unboundcx/sdk 2.7.6 → 2.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.7.6",
+  "version": "2.7.7",
   "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

@@ -213,6 +213,7 @@ export class EmailService {
     this.domains = new EmailDomainsService(sdk);
     this.addresses = new EmailAddressesService(sdk);
     this.analytics = new EmailAnalyticsService(sdk);
+    this.queue = new EmailQueueService(sdk);
   }
 
   /**
@@ -1920,34 +1921,54 @@ export class EmailAnalyticsService {
    * @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
-   * const analytics = await sdk.messaging.email.analytics.timeSeries({ period: '24h', granularity: 'hour' });
-   * // Returns: { period, granularity, data: [{ timestamp, sent, delivered, failed, queued }], summary }
+   * // 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 } = {}) {
+  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
+   * 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'
-   * @returns {Promise<Object>} Summary statistics
+   * @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 summary stats for last 24 hours
-   * const summary = await sdk.messaging.email.analytics.summary({ period: '24h' });
-   * // Returns: { totalSent, deliveryRate, errorRate, avgEmailsPerMinute, avgProcessingSeconds }
+   * // 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 } = {}) {
+  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;
@@ -1984,3 +2005,96 @@ export class EmailAnalyticsService {
     return result;
   }
 }
+
+export class EmailQueueService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get email queue items with pagination and status filtering
+   * @param {Object} [params] - Queue query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.limit=50] - Number of items per page (max 100)
+   * @param {string} [params.status='queued'] - Filter by status: 'queued', 'sent', 'delivered', 'failed'
+   * @returns {Promise<Object>} Paginated queue items with metadata
+   * @example
+   * // Get first page of queued emails
+   * const queue = await sdk.messaging.email.queue.list({ page: 1, limit: 25, status: 'queued' });
+   * // Returns: { 
+   * //   items: [{ 
+   * //     id, status, to, from, subject, carrier, carrierId, 
+   * //     createdAt, lastStatusUpdatedAt, processingTimeSeconds 
+   * //   }],
+   * //   pagination: { 
+   * //     page, limit, totalItems, totalPages, hasNextPage, hasPreviousPage 
+   * //   },
+   * //   filter: { status }
+   * // }
+   */
+  async list({ page, limit, status } = {}) {
+    const options = { query: {} };
+    if (page !== undefined) options.query.page = page;
+    if (limit !== undefined) options.query.limit = limit;
+    if (status) options.query.status = status;
+
+    const result = await this.sdk._fetch('/messaging/email/queue', 'GET', options);
+    return result;
+  }
+
+  /**
+   * Get queued emails only (convenience method)
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.limit=50] - Number of items per page (max 100)
+   * @returns {Promise<Object>} Paginated queued emails
+   * @example
+   * // Get pending emails waiting to be sent
+   * const pending = await sdk.messaging.email.queue.getQueued({ page: 1, limit: 50 });
+   */
+  async getQueued({ page, limit } = {}) {
+    return this.list({ page, limit, status: 'queued' });
+  }
+
+  /**
+   * Get failed emails only (convenience method)
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.limit=50] - Number of items per page (max 100)
+   * @returns {Promise<Object>} Paginated failed emails
+   * @example
+   * // Get emails that failed to send
+   * const failed = await sdk.messaging.email.queue.getFailed({ page: 1, limit: 50 });
+   */
+  async getFailed({ page, limit } = {}) {
+    return this.list({ page, limit, status: 'failed' });
+  }
+
+  /**
+   * Get sent emails only (convenience method)
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.limit=50] - Number of items per page (max 100)
+   * @returns {Promise<Object>} Paginated sent emails
+   * @example
+   * // Get emails that have been sent successfully
+   * const sent = await sdk.messaging.email.queue.getSent({ page: 1, limit: 50 });
+   */
+  async getSent({ page, limit } = {}) {
+    return this.list({ page, limit, status: 'sent' });
+  }
+
+  /**
+   * Get delivered emails only (convenience method)
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.limit=50] - Number of items per page (max 100)
+   * @returns {Promise<Object>} Paginated delivered emails
+   * @example
+   * // Get emails that have been delivered to recipients
+   * const delivered = await sdk.messaging.email.queue.getDelivered({ page: 1, limit: 50 });
+   */
+  async getDelivered({ page, limit } = {}) {
+    return this.list({ page, limit, status: 'delivered' });
+  }
+}