@unboundcx/sdk 4.13.5 → 4.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.5",
+  "version": "4.13.6",
   "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/EmailAccountSettingsService.js

@@ -0,0 +1,60 @@
+import { internalRequest } from '../../base.js';
+
+/**
+ * Account-level email settings (plan §3.3) — auto-create-mailbox policy
+ * and the default domain new mailboxes/aliases are suggested on. Exposed
+ * as `sdk.messaging.email.settings`.
+ */
+export class EmailAccountSettingsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get the account's email settings
+   * @returns {Promise<Object>} { autoCreateUserMailbox, userMailboxAddressTemplate, defaultEmailDomainId, updatedAt, updatedBy }
+   * @example
+   * const settings = await sdk.messaging.email.settings.get();
+   */
+  async get() {
+    return internalRequest(this.sdk, '/messaging/email/settings', 'GET');
+  }
+
+  /**
+   * Update the account's email settings (admin only)
+   * @param {boolean} [autoCreateUserMailbox] - Auto-create a dedicated mailbox for new users
+   * @param {string} [userMailboxAddressTemplate] - Address template, e.g. '{first}.{last}' (tokens: {first},{last},{f},{username})
+   * @param {string} [defaultEmailDomainId] - Verified domain used for auto-created mailboxes and alias suggestions
+   * @returns {Promise<Object>} { message }
+   * @example
+   * await sdk.messaging.email.settings.update({
+   *   autoCreateUserMailbox: true,
+   *   defaultEmailDomainId: 'domain123',
+   * });
+   */
+  async update({
+    autoCreateUserMailbox,
+    userMailboxAddressTemplate,
+    defaultEmailDomainId,
+  } = {}) {
+    this.sdk.validateParams(
+      { autoCreateUserMailbox, userMailboxAddressTemplate, defaultEmailDomainId },
+      {
+        autoCreateUserMailbox: { type: 'boolean', required: false },
+        userMailboxAddressTemplate: { type: 'string', required: false },
+        defaultEmailDomainId: { type: 'string', required: false },
+      },
+    );
+    const body = {};
+    if (autoCreateUserMailbox !== undefined)
+      body.autoCreateUserMailbox = autoCreateUserMailbox;
+    if (userMailboxAddressTemplate !== undefined)
+      body.userMailboxAddressTemplate = userMailboxAddressTemplate;
+    if (defaultEmailDomainId !== undefined)
+      body.defaultEmailDomainId = defaultEmailDomainId;
+
+    return internalRequest(this.sdk, '/messaging/email/settings', 'PUT', {
+      body,
+    });
+  }
+}

package/services/messaging/EmailAliasSuggestService.js

@@ -0,0 +1,69 @@
+import { internalRequest } from '../../base.js';
+
+/**
+ * Alias suggestion/availability helpers for mailbox creation (plan §4) —
+ * mirrors the Extension field UX in UserCreateFormFields.svelte. Exposed
+ * as `sdk.messaging.email.mailboxes.aliasSuggest` /
+ * `sdk.messaging.email.mailboxes.aliasAvailable`.
+ */
+export class EmailAliasSuggestService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Suggest an available localpart for a user's mailbox on the account's default domain
+   * @param {string} [firstName] - User's first name
+   * @param {string} [lastName] - User's last name
+   * @param {string} [username] - Fallback token source when name parts are missing
+   * @returns {Promise<Object>} { localpart, domain, domainId, available: true }
+   * @example
+   * const suggestion = await sdk.messaging.email.mailboxes.aliasSuggest({
+   *   firstName: 'Jane',
+   *   lastName: 'Doe',
+   * });
+   */
+  async suggest({ firstName, lastName, username } = {}) {
+    this.sdk.validateParams(
+      { firstName, lastName, username },
+      {
+        firstName: { type: 'string', required: false },
+        lastName: { type: 'string', required: false },
+        username: { type: 'string', required: false },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      '/messaging/email/mailbox/alias-suggest',
+      'GET',
+      { query: { firstName, lastName, username } },
+    );
+  }
+
+  /**
+   * Check whether a localpart is available on a given domain
+   * @param {string} localpart - Localpart to check (part before @)
+   * @param {string} domainId - Email domain ID
+   * @returns {Promise<Object>} { localpart, domainId, available }
+   * @example
+   * const { available } = await sdk.messaging.email.mailboxes.aliasAvailable({
+   *   localpart: 'jane.doe',
+   *   domainId: 'domain123',
+   * });
+   */
+  async available({ localpart, domainId } = {}) {
+    this.sdk.validateParams(
+      { localpart, domainId },
+      {
+        localpart: { type: 'string', required: true },
+        domainId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      '/messaging/email/mailbox/alias-available',
+      'GET',
+      { query: { localpart, domainId } },
+    );
+  }
+}

package/services/messaging/EmailMailboxAccessService.js

@@ -0,0 +1,165 @@
+import { internalRequest } from '../../base.js';
+
+const VALID_ROLES = ['owner', 'full', 'send', 'read'];
+const VALID_PRINCIPAL_TYPES = ['user', 'group'];
+const VALID_NOTIFY_MODES = ['all', 'important', 'mute'];
+
+/**
+ * Mailbox access grants (mailboxUsers_acct) — plan §3.2/§4.
+ * Exposed on the SDK as `sdk.messaging.email.mailboxes.access`.
+ */
+export class EmailMailboxAccessService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List access grants (users and groups) for a mailbox
+   * @param {string} mailboxId - Mailbox ID
+   * @returns {Promise<Object>} { mailboxId, access: [{ principalType, principalId, role, name, email?, notifyMode?, ... }] }
+   * @example
+   * const { access } = await sdk.messaging.email.mailboxes.access.list('mbx123');
+   */
+  async list(mailboxId) {
+    this.sdk.validateParams(
+      { mailboxId },
+      { mailboxId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/${mailboxId}/access`,
+      'GET',
+    );
+  }
+
+  /**
+   * Grant (or update) a user's or group's access to a mailbox
+   * @param {string} mailboxId - Mailbox ID
+   * @param {string} principalType - 'user' or 'group'
+   * @param {string} principalId - User ID or group ID
+   * @param {string} role - 'owner', 'full', 'send', or 'read'
+   * @param {string} [notifyMode] - 'all', 'important', or 'mute' (user rows only)
+   * @param {boolean} [notifyPush] - Push notifications on (user rows only, default true)
+   * @param {boolean} [notifyBadge] - Badge count on (user rows only, default true)
+   * @param {boolean} [notifySound] - Sound on (user rows only, default false)
+   * @returns {Promise<Object>} { mailboxId, principalType, principalId, role }
+   * @example
+   * await sdk.messaging.email.mailboxes.access.set('mbx123', 'user', 'user456', 'full');
+   */
+  async set(
+    mailboxId,
+    principalType,
+    principalId,
+    role,
+    { notifyMode, notifyPush, notifyBadge, notifySound } = {},
+  ) {
+    this.sdk.validateParams(
+      {
+        mailboxId,
+        principalType,
+        principalId,
+        role,
+        notifyMode,
+        notifyPush,
+        notifyBadge,
+        notifySound,
+      },
+      {
+        mailboxId: { type: 'string', required: true },
+        principalType: {
+          type: 'string',
+          required: true,
+          enum: VALID_PRINCIPAL_TYPES,
+        },
+        principalId: { type: 'string', required: true },
+        role: { type: 'string', required: true, enum: VALID_ROLES },
+        notifyMode: { type: 'string', required: false, enum: VALID_NOTIFY_MODES },
+        notifyPush: { type: 'boolean', required: false },
+        notifyBadge: { type: 'boolean', required: false },
+        notifySound: { type: 'boolean', required: false },
+      },
+    );
+
+    const body = { role };
+    if (notifyMode !== undefined) body.notifyMode = notifyMode;
+    if (notifyPush !== undefined) body.notifyPush = notifyPush;
+    if (notifyBadge !== undefined) body.notifyBadge = notifyBadge;
+    if (notifySound !== undefined) body.notifySound = notifySound;
+
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/${mailboxId}/access/${principalType}/${principalId}`,
+      'PUT',
+      { body },
+    );
+  }
+
+  /**
+   * Remove a user's or group's access grant from a mailbox
+   * @param {string} mailboxId - Mailbox ID
+   * @param {string} principalType - 'user' or 'group'
+   * @param {string} principalId - User ID or group ID
+   * @returns {Promise<Object>} { mailboxId, principalType, principalId, message }
+   * @example
+   * await sdk.messaging.email.mailboxes.access.remove('mbx123', 'user', 'user456');
+   */
+  async remove(mailboxId, principalType, principalId) {
+    this.sdk.validateParams(
+      { mailboxId, principalType, principalId },
+      {
+        mailboxId: { type: 'string', required: true },
+        principalType: {
+          type: 'string',
+          required: true,
+          enum: VALID_PRINCIPAL_TYPES,
+        },
+        principalId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/${mailboxId}/access/${principalType}/${principalId}`,
+      'DELETE',
+    );
+  }
+
+  /**
+   * Set the caller's own notification preferences for a mailbox
+   * @param {string} mailboxId - Mailbox ID
+   * @param {string} [notifyMode] - 'all', 'important', or 'mute'
+   * @param {boolean} [notifyPush] - Push notifications on
+   * @param {boolean} [notifyBadge] - Badge count on
+   * @param {boolean} [notifySound] - Sound on
+   * @returns {Promise<Object>} Updated access row for the caller
+   * @example
+   * await sdk.messaging.email.mailboxes.access.setMyNotifications('mbx123', { notifyMode: 'important' });
+   */
+  async setMyNotifications(
+    mailboxId,
+    { notifyMode, notifyPush, notifyBadge, notifySound } = {},
+  ) {
+    this.sdk.validateParams(
+      { mailboxId, notifyMode, notifyPush, notifyBadge, notifySound },
+      {
+        mailboxId: { type: 'string', required: true },
+        notifyMode: { type: 'string', required: false, enum: VALID_NOTIFY_MODES },
+        notifyPush: { type: 'boolean', required: false },
+        notifyBadge: { type: 'boolean', required: false },
+        notifySound: { type: 'boolean', required: false },
+      },
+    );
+
+    const body = {};
+    if (notifyMode !== undefined) body.notifyMode = notifyMode;
+    if (notifyPush !== undefined) body.notifyPush = notifyPush;
+    if (notifyBadge !== undefined) body.notifyBadge = notifyBadge;
+    if (notifySound !== undefined) body.notifySound = notifySound;
+
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/${mailboxId}/access/me/notifications`,
+      'PUT',
+      { body },
+    );
+  }
+}

package/services/messaging/EmailMailboxGroupAccessService.js

@@ -0,0 +1,67 @@
+import { internalRequest } from '../../base.js';
+
+const VALID_ROLES = ['owner', 'full', 'send', 'read'];
+
+/**
+ * Shared mailboxes granted to a group (plan §3.2/§4/§6) — backs
+ * Setup → Groups → [id] → Shared mailboxes card. Exposed as
+ * `sdk.messaging.email.mailboxes.groupAccess`.
+ */
+export class EmailMailboxGroupAccessService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List mailboxes a group has access to
+   * @param {string} groupId - Group ID
+   * @returns {Promise<Array>} [{ mailboxId, name, mailbox, role }]
+   * @example
+   * const mailboxes = await sdk.messaging.email.mailboxes.groupAccess.list('group123');
+   */
+  async list(groupId) {
+    this.sdk.validateParams(
+      { groupId },
+      { groupId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/group/${groupId}/mailboxes`,
+      'GET',
+    );
+  }
+
+  /**
+   * Replace the full set of mailboxes a group has access to
+   * @param {string} groupId - Group ID
+   * @param {Array<{mailboxId: string, role: string}>} mailboxes - Desired mailbox/role pairs (role: owner|full|send|read); entries omitted are removed
+   * @returns {Promise<Array>} [{ mailboxId, name, mailbox, role }]
+   * @example
+   * await sdk.messaging.email.mailboxes.groupAccess.set('group123', [
+   *   { mailboxId: 'mbx1', role: 'full' },
+   *   { mailboxId: 'mbx2', role: 'read' },
+   * ]);
+   */
+  async set(groupId, mailboxes) {
+    this.sdk.validateParams(
+      { groupId, mailboxes },
+      {
+        groupId: { type: 'string', required: true },
+        mailboxes: { type: 'array', required: true },
+      },
+    );
+    for (const entry of mailboxes) {
+      if (!entry?.mailboxId || !VALID_ROLES.includes(entry.role)) {
+        throw new Error(
+          `Each mailbox entry requires mailboxId and role in ${VALID_ROLES.join('|')}`,
+        );
+      }
+    }
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/group/${groupId}/mailboxes`,
+      'PUT',
+      { body: { mailboxes } },
+    );
+  }
+}

package/services/messaging/EmailMailboxUserService.js

@@ -0,0 +1,56 @@
+import { internalRequest } from '../../base.js';
+
+/**
+ * A user's dedicated mailbox (plan §4/§6) — backs Setup → Users →
+ * [userId] → Email tab. Exposed as `sdk.messaging.email.mailboxes.forUser`.
+ */
+export class EmailMailboxUserService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get a user's dedicated mailbox
+   * @param {string} userId - User ID
+   * @returns {Promise<Object>} Mailbox details, or a 404 if none exists
+   * @example
+   * const mailbox = await sdk.messaging.email.mailboxes.forUser.get('user123');
+   */
+  async get(userId) {
+    this.sdk.validateParams(
+      { userId },
+      { userId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/for-user/${userId}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Create a dedicated mailbox for a user (manual create / backfill)
+   * @param {string} userId - User ID
+   * @param {string} [emailAlias] - Localpart to use; defaults to the account's address template
+   * @returns {Promise<Object>} { id, userId, type, systemAddress }
+   * @example
+   * await sdk.messaging.email.mailboxes.forUser.create('user123', { emailAlias: 'j.doe' });
+   */
+  async create(userId, { emailAlias } = {}) {
+    this.sdk.validateParams(
+      { userId, emailAlias },
+      {
+        userId: { type: 'string', required: true },
+        emailAlias: { type: 'string', required: false },
+      },
+    );
+    const body = {};
+    if (emailAlias !== undefined) body.emailAlias = emailAlias;
+    return internalRequest(
+      this.sdk,
+      `/messaging/email/mailbox/for-user/${userId}`,
+      'POST',
+      { body },
+    );
+  }
+}

package/services/messaging/EmailMailboxesService.js

@@ -1,7 +1,40 @@
 import { internalRequest } from '../../base.js';
+import { EmailMailboxAccessService } from './EmailMailboxAccessService.js';
+import { EmailMailboxUserService } from './EmailMailboxUserService.js';
+import { EmailMailboxGroupAccessService } from './EmailMailboxGroupAccessService.js';
+import { EmailAliasSuggestService } from './EmailAliasSuggestService.js';
+
 export class EmailMailboxesService {
   constructor(sdk) {
     this.sdk = sdk;
+    // Access grants (mailboxUsers_acct) — plan §3.2/§4.
+    this.access = new EmailMailboxAccessService(sdk);
+    // A user's dedicated mailbox — plan §4/§6.
+    this.forUser = new EmailMailboxUserService(sdk);
+    // Shared mailboxes granted to a group — plan §3.2/§4/§6.
+    this.groupAccess = new EmailMailboxGroupAccessService(sdk);
+    this._aliasSuggestService = new EmailAliasSuggestService(sdk);
+  }
+
+  /**
+   * Suggest an available mailbox localpart for a user on the account's default domain
+   * @param {string} [firstName]
+   * @param {string} [lastName]
+   * @param {string} [username]
+   * @returns {Promise<Object>} { localpart, domain, domainId, available: true }
+   */
+  aliasSuggest(params) {
+    return this._aliasSuggestService.suggest(params);
+  }
+
+  /**
+   * Check whether a localpart is available on a given domain
+   * @param {string} localpart
+   * @param {string} domainId
+   * @returns {Promise<Object>} { localpart, domainId, available }
+   */
+  aliasAvailable(params) {
+    return this._aliasSuggestService.available(params);
   }
 
   /**
@@ -15,6 +48,7 @@ export class EmailMailboxesService {
    * @param {string} [ticketPrefix] - Ticket prefix for engagement sessions (e.g., 'SUP', 'TECH') (optional)
    * @param {string} [ticketCreateEmailTemplateId] - Email template ID for auto-reply on new tickets (optional)
    * @param {string} [ticketCreateEmailFrom] - From address for auto-reply emails (optional, defaults to received address)
+   * @param {string} [type] - Mailbox type: 'dedicated' (has a primary user) or 'shared' (default)
    * @returns {Promise<Object>} Created mailbox with system address
    * @example
    * // Create basic mailbox
@@ -46,6 +80,7 @@ export class EmailMailboxesService {
         ticketPrefix,
         ticketCreateEmailTemplateId,
         ticketCreateEmailFrom,
+        type,
       ] = arguments;
       mailboxData = {};
       if (mailbox !== undefined) mailboxData.mailbox = mailbox;
@@ -60,6 +95,7 @@ export class EmailMailboxesService {
         mailboxData.ticketCreateEmailTemplateId = ticketCreateEmailTemplateId;
       if (ticketCreateEmailFrom !== undefined)
         mailboxData.ticketCreateEmailFrom = ticketCreateEmailFrom;
+      if (type !== undefined) mailboxData.type = type;
     } else {
       // New API: options object
       mailboxData = { ...options };
@@ -75,6 +111,7 @@ export class EmailMailboxesService {
       ticketPrefix: { type: 'string', required: false },
       ticketCreateEmailTemplateId: { type: 'string', required: false },
       ticketCreateEmailFrom: { type: 'string', required: false },
+      type: { type: 'string', required: false },
     });
 
     const result = await internalRequest(this.sdk, '/messaging/email/mailbox', 'POST', {
@@ -212,6 +249,7 @@ export class EmailMailboxesService {
    * @param {string} [updates.ticketCreateEmailTemplateId] - Email template ID for auto-reply
    * @param {string} [updates.ticketCreateEmailFrom] - From address for auto-reply emails
    * @param {boolean} [updates.isActive] - Whether mailbox is active
+   * @param {string} [updates.type] - Mailbox type: 'dedicated' or 'shared'
    * @returns {Promise<Object>} Update result
    * @example
    * // Update mailbox with engagement sessions and queue
@@ -242,6 +280,7 @@ export class EmailMailboxesService {
         ticketPrefix,
         ticketCreateEmailTemplateId,
         ticketCreateEmailFrom,
+        type,
       ] = Array.from(arguments).slice(1);
       updateData = {};
       if (mailbox !== undefined) updateData.mailbox = mailbox;
@@ -257,6 +296,7 @@ export class EmailMailboxesService {
         updateData.ticketCreateEmailTemplateId = ticketCreateEmailTemplateId;
       if (ticketCreateEmailFrom !== undefined)
         updateData.ticketCreateEmailFrom = ticketCreateEmailFrom;
+      if (type !== undefined) updateData.type = type;
     } else {
       // New API: options object
       updateData = { ...updates };
@@ -276,10 +316,11 @@ export class EmailMailboxesService {
         ticketCreateEmailTemplateId: { type: 'string', required: false },
         ticketCreateEmailFrom: { type: 'string', required: false },
         isActive: { type: 'boolean', required: false },
+        type: { type: 'string', required: false },
       },
     );
 
-    const result = await internalRequest(this.sdk, 
+    const result = await internalRequest(this.sdk,
       `/messaging/email/mailbox/${id}`,
       'PUT',
       {

package/services/messaging/EmailService.js

@@ -5,6 +5,7 @@ import { EmailMailboxesService } from './EmailMailboxesService.js';
 import { EmailAnalyticsService } from './EmailAnalyticsService.js';
 import { EmailQueueService } from './EmailQueueService.js';
 import { EmailSuppressionService } from './EmailSuppressionService.js';
+import { EmailAccountSettingsService } from './EmailAccountSettingsService.js';
 
 import { internalRequest } from '../../base.js';
 export class EmailService {
@@ -17,6 +18,27 @@ export class EmailService {
     this.analytics = new EmailAnalyticsService(sdk);
     this.queue = new EmailQueueService(sdk);
     this.suppression = new EmailSuppressionService(sdk);
+    // Account-level email settings (plan §3.3).
+    this.settings = new EmailAccountSettingsService(sdk);
+  }
+
+  /**
+   * Assign (or unassign) an email message to a user — shared-inbox "claim" (plan §2b/§4)
+   * @param {string} messageId - Email message ID
+   * @param {string|null} userId - User ID to assign to, or null to unassign
+   * @returns {Promise<Object>} { id, assignedUserId, assignedAt, message }
+   * @example
+   * await sdk.messaging.email.assign('emailId123', 'user456');
+   * await sdk.messaging.email.assign('emailId123', null); // unassign
+   */
+  async assign(messageId, userId = null) {
+    this.sdk.validateParams(
+      { messageId },
+      { messageId: { type: 'string', required: true } },
+    );
+    return internalRequest(this.sdk, `/messaging/email/${messageId}/assign`, 'PUT', {
+      body: { userId },
+    });
   }
 
   /**
@@ -538,6 +560,7 @@ export class EmailService {
    * @param {string} [filters.sortOrder='desc'] - Sort order: 'asc', 'desc'
    * @param {number} [filters.limit=25] - Number of results per page (max 200)
    * @param {number} [filters.offset=0] - Offset for pagination
+   * @param {string} [filters.assignedUserId] - Filter by assignment: 'me', 'none', or a specific user ID (plan §2b)
    * @returns {Promise<Object>} List of email messages with their threads
    * @example
    * // Returns messages with nested threads for Gmail-like UI:
@@ -577,6 +600,7 @@ export class EmailService {
       sortOrder = 'desc',
       limit = 25,
       offset = 0,
+      assignedUserId,
     } = {},
   ) {
     this.sdk.validateParams(
@@ -589,6 +613,7 @@ export class EmailService {
         sortOrder,
         limit,
         offset,
+        assignedUserId,
       },
       {
         mailboxId: { type: 'string', required: true },
@@ -599,11 +624,13 @@ export class EmailService {
         sortOrder: { type: 'string', required: false },
         limit: { type: 'number', required: false },
         offset: { type: 'number', required: false },
+        assignedUserId: { type: 'string', required: false },
       },
     );
 
     const query = { folder, includeDrafts, sortBy, sortOrder, limit, offset };
     if (search) query.search = search;
+    if (assignedUserId) query.assignedUserId = assignedUserId;
 
     const params = {
       query,