@unboundcx/sdk 2.7.7 → 2.8.0

package/services/messaging/EmailSuppressionService.js

@@ -0,0 +1,189 @@
+export class EmailSuppressionService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List email suppression entries for the current account
+   * @param {Object} [params] - Query parameters
+   * @param {string} [params.type] - Filter by suppression type (bounce, complaint, etc.)
+   * @param {string} [params.emailAddress] - Filter by email address (partial match)
+   * @param {string} [params.fromAddress] - Filter by sender address
+   * @param {string} [params.carrierName] - Filter by carrier name
+   * @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 suppression list
+   * @example
+   * // Get all bounce suppressions
+   * const bounces = await sdk.messaging.email.suppression.list({ type: 'bounce', page: 1, limit: 50 });
+   * // Returns: {
+   * //   items: [{ id, emailAddress, type, subType, fromAddress, carrierName, createdAt, requestRemovalReason, requestRemovalBy, requestRemovalAt }],
+   * //   pagination: { page, limit },
+   * //   filters: { type }
+   * // }
+   */
+  async list({
+    type,
+    emailAddress,
+    fromAddress,
+    carrierName,
+    page,
+    limit,
+  } = {}) {
+    const options = { query: {} };
+    if (type) options.query.type = type;
+    if (emailAddress) options.query.emailAddress = emailAddress;
+    if (fromAddress) options.query.fromAddress = fromAddress;
+    if (carrierName) options.query.carrierName = carrierName;
+    if (page !== undefined) options.query.page = page;
+    if (limit !== undefined) options.query.limit = limit;
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/suppression',
+      'GET',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Delete a suppression entry with required reason (soft delete)
+   * @param {string} id - Suppression item ID (required)
+   * @param {string} reason - Reason for deletion (required, max 128 characters)
+   * @returns {Promise<Object>} Deletion confirmation with details
+   * @example
+   * // Delete a suppression entry
+   * const result = await sdk.messaging.email.suppression.delete('supp-123', 'Customer request to remove');
+   * // Returns: {
+   * //   success: true,
+   * //   message: 'Suppression item deleted successfully',
+   * //   deletedItem: { id, emailAddress, deletedBy, deletedReason, deletedAt }
+   * // }
+   */
+  async delete(id, reason) {
+    this.sdk.validateParams(
+      { id, reason },
+      {
+        id: { type: 'string', required: true },
+        reason: { type: 'string', required: true },
+      },
+    );
+
+    if (reason.length > 128) {
+      throw new Error('Deletion reason must be 128 characters or less');
+    }
+
+    const options = {
+      body: { reason },
+    };
+
+    const result = await this.sdk._fetch(
+      `/messaging/email/suppression/${id}`,
+      'DELETE',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Check if an email address is globally suppressed (not limited by account)
+   * @param {string} emailAddress - Email address to check (required)
+   * @returns {Promise<Object>} Suppression status and removal request availability
+   * @example
+   * // Check if email is suppressed globally
+   * const status = await sdk.messaging.email.suppression.checkGlobal('user@example.com');
+   * // Returns: {
+   * //   suppressed: true/false,
+   * //   message: 'Status message',
+   * //   canRequestRemoval: true/false (only if suppressed)
+   * // }
+   */
+  async checkGlobal(emailAddress) {
+    this.sdk.validateParams(
+      { emailAddress },
+      {
+        emailAddress: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/messaging/email/suppression/global/${encodeURIComponent(emailAddress)}`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Request removal of an email address from global suppression list
+   * @param {string} emailAddress - Email address to request removal for (required)
+   * @param {string} reason - Reason for removal request (required, max 128 characters)
+   * @returns {Promise<Object>} Removal request confirmation or existing request details
+   * @example
+   * // Request removal from suppression list
+   * const result = await sdk.messaging.email.suppression.requestRemoval('user@example.com', 'Customer opt-in consent obtained');
+   * // Success: {
+   * //   success: true,
+   * //   message: 'Removal request submitted successfully',
+   * //   emailAddress, requestedBy, reason, requestedAt, recordsUpdated, records
+   * // }
+   * // Already requested: {
+   * //   success: false,
+   * //   message: 'A removal request has already been submitted...',
+   * //   existingRequest: { requestedAt, requestedBy, reason }
+   * // }
+   */
+  async requestRemoval(emailAddress, reason) {
+    this.sdk.validateParams(
+      { emailAddress, reason },
+      {
+        emailAddress: { type: 'string', required: true },
+        reason: { type: 'string', required: true },
+      },
+    );
+
+    if (reason.length > 128) {
+      throw new Error('Removal reason must be 128 characters or less');
+    }
+
+    const options = {
+      body: { reason },
+    };
+
+    const result = await this.sdk._fetch(
+      `/messaging/email/suppression/global/${encodeURIComponent(
+        emailAddress,
+      )}/request-removal`,
+      'POST',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Get bounce suppressions 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 bounce suppressions
+   * @example
+   * // Get all bounce suppressions
+   * const bounces = await sdk.messaging.email.suppression.getBounces({ page: 1, limit: 50 });
+   */
+  async getBounces({ page, limit } = {}) {
+    return this.list({ type: 'bounce', page, limit });
+  }
+
+  /**
+   * Get complaint suppressions 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 complaint suppressions
+   * @example
+   * // Get all complaint suppressions
+   * const complaints = await sdk.messaging.email.suppression.getComplaints({ page: 1, limit: 50 });
+   */
+  async getComplaints({ page, limit } = {}) {
+    return this.list({ type: 'complaint', page, limit });
+  }
+}

package/services/messaging/EmailTemplatesService.js

@@ -0,0 +1,145 @@
+export class EmailTemplatesService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * 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
+   * @returns {Promise<Object>} Created template details with auto-extracted variables
+   * @example
+   * // Create template with variables in the content
+   * const template = await sdk.messaging.email.templates.create({
+   *   name: 'Welcome Email',
+   *   subject: 'Welcome {{firstName}}!',
+   *   html: '<h1>Hello {{firstName}} {{lastName}}</h1>',
+   *   text: 'Hello {{firstName}} {{lastName}}'
+   * });
+   * // Returns: { id, name, variables: ['firstName', 'lastName'] }
+   */
+  async create({ name, subject, html, text }) {
+    this.sdk.validateParams(
+      { name, subject },
+      {
+        name: { type: 'string', required: true },
+        subject: { type: 'string', required: true },
+        html: { type: 'string', required: false },
+        text: { type: 'string', required: false },
+      },
+    );
+
+    const templateData = { name, subject };
+    if (html) templateData.html = html;
+    if (text) templateData.text = text;
+
+    const options = {
+      body: templateData,
+    };
+
+    const result = await this.sdk._fetch(
+      '/messaging/email/template',
+      'POST',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * 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
+   * @returns {Promise<Object>} Updated template details with auto-extracted variables
+   * @example
+   * // Update template - variables are auto-extracted from content
+   * const updated = await sdk.messaging.email.templates.update('tpl_123', {
+   *   subject: 'Hi {{firstName}}, welcome to {{companyName}}!'
+   * });
+   * // Returns updated template with variables: ['firstName', 'companyName']
+   */
+  async update(id, { name, subject, html, text }) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+        name: { type: 'string', required: false },
+        subject: { type: 'string', required: false },
+        html: { type: 'string', required: false },
+        text: { type: 'string', required: false },
+      },
+    );
+
+    const updateData = {};
+    if (name) updateData.name = name;
+    if (subject) updateData.subject = subject;
+    if (html) updateData.html = html;
+    if (text) updateData.text = text;
+
+    const options = {
+      body: updateData,
+    };
+
+    const result = await this.sdk._fetch(
+      `/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 },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/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 },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/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/template', 'GET');
+    return result;
+  }
+}

package/services/messaging/MessagingService.js

@@ -0,0 +1,12 @@
+import { SmsService } from './SmsService.js';
+import { EmailService } from './EmailService.js';
+import { CampaignsService } from './CampaignsService.js';
+
+export class MessagingService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.sms = new SmsService(sdk);
+    this.email = new EmailService(sdk);
+    this.campaigns = new CampaignsService(sdk);
+  }
+}

package/services/messaging/SmsService.js

@@ -0,0 +1,75 @@
+import { SmsTemplatesService } from './SmsTemplatesService.js';
+
+export class SmsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.templates = new SmsTemplatesService(sdk);
+  }
+
+  /**
+   * Send an SMS/MMS message
+   * @param {Object} params - Message parameters
+   * @param {string} params.to - Recipient phone number (required)
+   * @param {string} [params.from] - Sender phone number
+   * @param {string} [params.message] - Message text
+   * @param {string} [params.templateId] - Template ID to use
+   * @param {Object} [params.variables] - Template variables
+   * @param {Array<string>} [params.mediaUrls] - Media URLs for MMS
+   * @param {string} [params.webhookUrl] - Webhook URL for delivery status
+   * @returns {Promise<Object>} Message details
+   */
+  async send({
+    from,
+    to,
+    message,
+    templateId,
+    variables,
+    mediaUrls,
+    webhookUrl,
+  }) {
+    const messageData = {};
+    if (from) messageData.from = from;
+    if (message) messageData.message = message;
+    if (templateId) messageData.templateId = templateId;
+    if (variables) messageData.variables = variables;
+    if (mediaUrls) messageData.mediaUrls = mediaUrls;
+    if (webhookUrl) messageData.webhookUrl = webhookUrl;
+
+    this.sdk.validateParams(
+      { to, ...messageData },
+      {
+        to: { type: 'string', required: true },
+        from: { type: 'string', required: false },
+        message: { type: 'string', required: false },
+        templateId: { type: 'string', required: false },
+        variables: { type: 'object', required: false },
+        mediaUrls: { type: 'array', required: false },
+        webhookUrl: { type: 'string', required: false },
+      },
+    );
+
+    const options = {
+      body: { to, ...messageData },
+    };
+
+    const result = await this.sdk._fetch('/messaging/sms', 'POST', options);
+    return result;
+  }
+
+  /**
+   * Get SMS/MMS message by ID
+   * @param {string} id - Message ID
+   * @returns {Promise<Object>} Message details
+   */
+  async get(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(`/messaging/sms/${id}`, 'GET');
+    return result;
+  }
+}

package/services/messaging/SmsTemplatesService.js

@@ -0,0 +1,124 @@
+export class SmsTemplatesService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Create SMS template
+   * @param {Object} params - Template parameters
+   * @param {string} params.name - Template name (required)
+   * @param {string} params.message - Template message (required)
+   * @param {Object} [params.variables] - Template variables
+   * @returns {Promise<Object>} Created template details
+   */
+  async create({ name, message, variables }) {
+    this.sdk.validateParams(
+      { name, message },
+      {
+        name: { type: 'string', required: true },
+        message: { type: 'string', required: true },
+        variables: { type: 'object', required: false },
+      },
+    );
+
+    const templateData = { name, message };
+    if (variables) templateData.variables = variables;
+
+    const options = {
+      body: templateData,
+    };
+
+    const result = await this.sdk._fetch(
+      '/messaging/sms/templates',
+      'POST',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Update SMS template
+   * @param {string} id - Template ID
+   * @param {Object} params - Update parameters
+   * @param {string} [params.name] - Template name
+   * @param {string} [params.message] - Template message
+   * @param {Object} [params.variables] - Template variables
+   * @returns {Promise<Object>} Updated template details
+   */
+  async update(id, { name, message, variables }) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+        name: { type: 'string', required: false },
+        message: { type: 'string', required: false },
+        variables: { type: 'object', required: false },
+      },
+    );
+
+    const updateData = {};
+    if (name) updateData.name = name;
+    if (message) updateData.message = message;
+    if (variables) updateData.variables = variables;
+
+    const options = {
+      body: updateData,
+    };
+
+    const result = await this.sdk._fetch(
+      `/messaging/sms/templates/${id}`,
+      'PUT',
+      options,
+    );
+    return result;
+  }
+
+  /**
+   * Delete SMS template
+   * @param {string} id - Template ID
+   * @returns {Promise<Object>} Deletion result
+   */
+  async delete(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/messaging/sms/templates/${id}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * Get SMS template by ID
+   * @param {string} id - Template ID
+   * @returns {Promise<Object>} Template details
+   */
+  async get(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/messaging/sms/templates/${id}`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * List all SMS templates
+   * @returns {Promise<Array>} List of templates
+   */
+  async list() {
+    const result = await this.sdk._fetch('/messaging/sms/templates', 'GET');
+    return result;
+  }
+}