@unboundcx/sdk 2.8.6 → 2.8.8

package/services/engagementMetrics.js

@@ -139,7 +139,11 @@ export class EngagementMetricsService {
    * @param {string[]} [options.userIds] - Array of user IDs to filter by
    * @returns {Promise<Object>} All metrics
    */
-  async getDashboardMetrics({ queueIds = [], statuses = [], userIds = [] } = {}) {
+  async getDashboardMetrics({
+    queueIds = [],
+    statuses = [],
+    userIds = [],
+  } = {}) {
     return this.getMetrics({
       queueIds,
       statuses,
@@ -150,4 +154,4 @@ export class EngagementMetricsService {
       includeAgentPerformance: true,
     });
   }
-}
+}

package/services/externalOAuth.js

@@ -122,4 +122,49 @@ export class ExternalOAuthService {
     const result = await this.sdk._fetch('/externalOAuth', 'GET');
     return result;
   }
+
+  async listUnified() {
+    const result = await this.sdk._fetch('/externalOAuth/unified', 'GET');
+    return result;
+  }
+
+  async providers() {
+    const result = await this.sdk._fetch('/externalOAuth/providers', 'GET');
+    return result;
+  }
+
+  async authorize({
+    name,
+    provider,
+    clientId,
+    clientSecret,
+    scopes,
+    authorizationUrl,
+    tokenUrl,
+  }) {
+    this.sdk.validateParams(
+      { name, provider },
+      {
+        name: { type: 'string', required: true },
+        provider: { type: 'string', required: true },
+        clientId: { type: 'string', required: false },
+        clientSecret: { type: 'string', required: false },
+        scopes: { type: 'array', required: false },
+        authorizationUrl: { type: 'string', required: false },
+        tokenUrl: { type: 'string', required: false },
+      },
+    );
+
+    const body = { name, provider };
+    if (clientId) body.clientId = clientId;
+    if (clientSecret) body.clientSecret = clientSecret;
+    if (scopes) body.scopes = scopes;
+    if (authorizationUrl) body.authorizationUrl = authorizationUrl;
+    if (tokenUrl) body.tokenUrl = tokenUrl;
+
+    const result = await this.sdk._fetch('/externalOAuth/authorize', 'POST', {
+      body,
+    });
+    return result;
+  }
 }

package/services/fax.js

@@ -0,0 +1,249 @@
+export class FaxService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Create an inbound fax document record with status 'receiving'.
+   * Called by the media manager when an inbound fax is first detected.
+   * After the fax is fully received, call sdk.fax.status() to update
+   * with the final storage IDs and completion metadata.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.faxMailboxId - ID of the fax mailbox receiving the fax (required)
+   * @param {string} [options.sipCallId] - SIP call correlation ID
+   * @param {string} [options.name] - Display name for the fax document
+   * @param {string} [options.faxHeader] - TSI header string from the sender
+   * @param {string} [options.resolution] - Fax resolution (e.g. 'fine', 'standard')
+   * @param {string} [options.toNumber] - Destination number in E.164 format
+   * @param {string} [options.fromNumber] - Sender number in E.164 format
+   * @returns {Promise<Object>} Created fax document
+   * @returns {string} result.id - The fax document ID (use in subsequent status calls)
+   * @returns {string} result.status - 'receiving'
+   *
+   * @example
+   * const { id } = await sdk.fax.receive({
+   *   faxMailboxId: '157abc123...',
+   *   sipCallId: 'sip-call-uuid',
+   *   name: 'Fax from +15551234567',
+   *   toNumber: '+15559876543',
+   *   fromNumber: '+15551234567',
+   * });
+   * // Save id for use with sdk.fax.status() after reception completes
+   */
+  async receive({
+    faxMailboxId,
+    sipCallId,
+    name,
+    faxHeader,
+    resolution,
+    toNumber,
+    fromNumber,
+    cId,
+  }) {
+    this.sdk.validateParams(
+      { faxMailboxId },
+      {
+        faxMailboxId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: {
+        faxMailboxId,
+        sipCallId,
+        name,
+        faxHeader,
+        resolution,
+        toNumber,
+        fromNumber,
+        cId,
+      },
+    };
+
+    return await this.sdk._fetch('/fax/receive', 'POST', params);
+  }
+
+  /**
+   * Send an outbound fax.
+   * Creates a fax document record, retrieves the document from storage,
+   * and publishes to the media manager via NATS to initiate the fax call.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.faxMailboxId - ID of the fax mailbox to send from (required)
+   * @param {string} options.toNumber - Destination number in E.164 format (required)
+   * @param {string} options.fromNumber - Caller ID number in E.164 format (required)
+   * @param {string} [options.storageId] - Storage ID of a PDF or TIFF file to fax. The server will
+   *   automatically convert it to the missing format so both PDF and TIFF are stored.
+   *   Required if pdfStorageId and tiffStorageId are not provided.
+   * @param {string} [options.pdfStorageId] - Storage ID of the PDF version. Required if storageId is not provided.
+   * @param {string} [options.tiffStorageId] - Storage ID of the TIFF version. Required if storageId is not provided.
+   * @param {string} [options.faxHeader] - TSI header text (defaults to mailbox faxHeader)
+   * @param {string} [options.resolution] - Fax resolution (defaults to mailbox resolution)
+   * @param {boolean} [options.ecm] - Enable Error Correction Mode (default: true)
+   * @param {number} [options.timeout] - Dial timeout in seconds (defaults to mailbox dialTimeout)
+   * @returns {Promise<Object>} Send result
+   * @returns {string} result.id - The fax document ID
+   * @returns {string} result.status - 'sending' on success, 'failed' on NATS error
+   * @returns {string} [result.requestId] - NATS request ID (on success)
+   * @returns {string} [result.error] - Error message (on failure)
+   *
+   * @example
+   * // Send using a single storageId (PDF or TIFF — server auto-converts the missing format)
+   * const result = await sdk.fax.send({
+   *   faxMailboxId: '157abc123...',
+   *   toNumber: '+15551234567',
+   *   fromNumber: '+15559876543',
+   *   storageId: '017xyz788...',
+   * });
+   * console.log(result.id);     // '158def456...'
+   * console.log(result.status); // 'sending'
+   *
+   * @example
+   * // Send using explicit PDF and TIFF storage IDs
+   * const result = await sdk.fax.send({
+   *   faxMailboxId: '157abc123...',
+   *   toNumber: '+15551234567',
+   *   fromNumber: '+15559876543',
+   *   pdfStorageId: '017xyz789...',
+   *   tiffStorageId: '017xyz788...',
+   *   faxHeader: 'My Company',
+   *   resolution: 'fine',
+   *   ecm: true,
+   *   timeout: 90,
+   * });
+   */
+  async send({
+    faxMailboxId,
+    toNumber,
+    fromNumber,
+    storageId,
+    pdfStorageId,
+    tiffStorageId,
+    faxHeader,
+    resolution,
+    ecm,
+    timeout,
+  }) {
+    this.sdk.validateParams(
+      { faxMailboxId, toNumber, fromNumber },
+      {
+        faxMailboxId: { type: 'string', required: true },
+        toNumber: { type: 'string', required: true },
+        fromNumber: { type: 'string', required: true },
+        storageId: { type: 'string', required: false },
+        pdfStorageId: { type: 'string', required: false },
+        tiffStorageId: { type: 'string', required: false },
+      },
+    );
+
+    if (!storageId && (!pdfStorageId || !tiffStorageId)) {
+      throw new Error(
+        'Either storageId or both pdfStorageId and tiffStorageId are required.',
+      );
+    }
+
+    const params = {
+      body: {
+        faxMailboxId,
+        toNumber,
+        fromNumber,
+        storageId,
+        pdfStorageId,
+        tiffStorageId,
+        faxHeader,
+        resolution,
+        ecm,
+        timeout,
+      },
+    };
+
+    return await this.sdk._fetch('/fax/send', 'POST', params);
+  }
+
+  /**
+   * Update the status and metadata of a fax document.
+   * Called by the media manager to report progress and completion
+   * of both inbound and outbound faxes.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.faxDocumentId - ID of the fax document to update (required)
+   * @param {string} options.status - New status (required): 'receiving', 'sending', 'sent', 'completed', 'failed'
+   * @param {string} [options.sipCallId] - SIP call correlation ID
+   * @param {number} [options.pages] - Number of pages transmitted/received
+   * @param {number} [options.duration] - Call duration in seconds
+   * @param {number} [options.transferRate] - Baud rate (e.g. 14400)
+   * @param {number} [options.ecmUsed] - Whether ECM was used (1 or 0)
+   * @param {number} [options.isError] - Whether an error occurred (1 or 0)
+   * @param {string} [options.errorMessage] - Error description
+   * @param {number} [options.sendAttempts] - Number of send attempts made
+   * @param {string} [options.pdfStorageId] - Storage ID of the PDF version
+   * @param {string} [options.tiffStorageId] - Storage ID of the TIFF version
+   * @returns {Promise<Object>} Updated fields
+   * @returns {string} result.id - The fax document ID
+   *
+   * @example
+   * // Complete an inbound fax with storage files and metadata
+   * await sdk.fax.status({
+   *   faxDocumentId: '158abc123...',
+   *   status: 'completed',
+   *   pdfStorageId: '017pdf456...',
+   *   tiffStorageId: '017tiff789...',
+   *   pages: 3,
+   *   duration: 45,
+   *   transferRate: 14400,
+   *   ecmUsed: 1,
+   * });
+   *
+   * @example
+   * // Report a fax failure
+   * await sdk.fax.status({
+   *   faxDocumentId: '158abc123...',
+   *   status: 'failed',
+   *   isError: 1,
+   *   errorMessage: 'Remote side disconnected',
+   *   sendAttempts: 2,
+   * });
+   */
+  async status({
+    faxDocumentId,
+    status,
+    sipCallId,
+    pages,
+    duration,
+    transferRate,
+    ecmUsed,
+    isError,
+    errorMessage,
+    sendAttempts,
+    pdfStorageId,
+    tiffStorageId,
+  }) {
+    this.sdk.validateParams(
+      { faxDocumentId, status },
+      {
+        faxDocumentId: { type: 'string', required: true },
+        status: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: {
+        faxDocumentId,
+        status,
+        sipCallId,
+        pages,
+        duration,
+        transferRate,
+        ecmUsed,
+        isError,
+        errorMessage,
+        sendAttempts,
+        pdfStorageId,
+        tiffStorageId,
+      },
+    };
+
+    return await this.sdk._fetch('/fax/status', 'POST', params);
+  }
+}

package/services/knowledgeBase.js

@@ -0,0 +1,229 @@
+export class KnowledgeBaseService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Hybrid search across knowledge base content
+   * Combines keyword (FULLTEXT) and semantic (vector) search with optional LLM reranking
+   *
+   * @param {Object} params
+   * @param {string} params.query - Search query text
+   * @param {string} [params.knowledgeBaseId] - Specific KB to search (omit to search all)
+   * @param {number} [params.limit] - Max results to return
+   * @param {Object} [params.filters] - Optional filters
+   * @param {string} [params.filters.categoryId] - Filter by category
+   * @param {string} [params.filters.sourceType] - Filter by source type (article, document, source)
+   * @param {Array} [params.filters.tags] - Filter by tags
+   * @param {boolean} [params.rerank] - Whether to apply LLM reranking (default: true)
+   * @returns {Promise<Object>} Search results with source attribution
+   */
+  async search({ query, knowledgeBaseId, limit, filters, rerank }) {
+    this.sdk.validateParams(
+      { query },
+      {
+        query: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { query, knowledgeBaseId, limit, filters, rerank },
+    };
+
+    const result = await this.sdk._fetch(
+      '/knowledgeBase/search',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Discover pages available at a URL
+   * Checks for sitemaps (auto-discovery + direct sitemap URLs) and returns
+   * a list of pages the user can select from before ingesting.
+   *
+   * @param {Object} params
+   * @param {string} params.url - URL to discover (base URL or sitemap URL)
+   * @returns {Promise<Object>} { url, type, sitemapUrl, pages[], pageCount }
+   */
+  async discoverUrl({ url }) {
+    this.sdk.validateParams(
+      { url },
+      {
+        url: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { url },
+    };
+
+    const result = await this.sdk._fetch(
+      '/knowledgeBase/discover-url',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Ingest a URL into a knowledge base
+   * Creates a kbSources record and triggers async crawl + processing
+   *
+   * @param {Object} params
+   * @param {string} params.knowledgeBaseId - Target knowledge base
+   * @param {string} params.url - URL to crawl and ingest
+   * @param {string} [params.categoryId] - Category to assign
+   * @param {string} [params.title] - Display title (auto-detected from page if omitted)
+   * @param {string} [params.refreshInterval] - Recrawl interval: manual, daily, weekly, monthly
+   * @returns {Promise<Object>} Created kbSources record
+   */
+  async ingestUrl({ knowledgeBaseId, url, categoryId, title, refreshInterval }) {
+    this.sdk.validateParams(
+      { knowledgeBaseId, url },
+      {
+        knowledgeBaseId: { type: 'string', required: true },
+        url: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { knowledgeBaseId, url, categoryId, title, refreshInterval },
+    };
+
+    const result = await this.sdk._fetch(
+      '/knowledgeBase/ingest/url',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Trigger (re)processing of a knowledge base source
+   * Sets processingStatus to pending and publishes NATS event
+   *
+   * @param {Object} params
+   * @param {string} params.sourceType - Type: article, document, or source
+   * @param {string} params.id - Source record ID
+   * @returns {Promise<Object>} Updated source record
+   */
+  async processSource({ sourceType, id }) {
+    this.sdk.validateParams(
+      { sourceType, id },
+      {
+        sourceType: { type: 'string', required: true },
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/knowledgeBase/process/${sourceType}/${id}`,
+      'POST',
+    );
+    return result;
+  }
+
+  /**
+   * Check the processing status of a source
+   *
+   * @param {Object} params
+   * @param {string} params.id - Source record ID
+   * @returns {Promise<Object>} Processing status { id, processingStatus, processingError }
+   */
+  async checkProcessingStatus({ id }) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/knowledgeBase/process/${id}/status`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Publish a draft article
+   * Changes status to published, creates version snapshot, triggers processing
+   *
+   * @param {Object} params
+   * @param {string} params.id - Article ID
+   * @returns {Promise<Object>} Updated article record
+   */
+  async publishArticle({ id }) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/knowledgeBase/articles/${id}/publish`,
+      'POST',
+    );
+    return result;
+  }
+
+  /**
+   * Get analytics for a knowledge base
+   *
+   * @param {Object} params
+   * @param {string} params.knowledgeBaseId - Knowledge base ID
+   * @param {Object} [params.filters] - Optional date range, source type filters
+   * @returns {Promise<Object>} Analytics data
+   */
+  async getAnalytics({ knowledgeBaseId, ...filters }) {
+    this.sdk.validateParams(
+      { knowledgeBaseId },
+      {
+        knowledgeBaseId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      query: filters,
+    };
+
+    const result = await this.sdk._fetch(
+      `/knowledgeBase/${knowledgeBaseId}/analytics`,
+      'GET',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Get content gap analysis for a knowledge base
+   * Identifies failed/low-result searches that indicate missing content
+   *
+   * @param {Object} params
+   * @param {string} params.knowledgeBaseId - Knowledge base ID
+   * @param {Object} [params.filters] - Optional date range filters
+   * @returns {Promise<Object>} Gap analysis data
+   */
+  async getGaps({ knowledgeBaseId, ...filters }) {
+    this.sdk.validateParams(
+      { knowledgeBaseId },
+      {
+        knowledgeBaseId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      query: filters,
+    };
+
+    const result = await this.sdk._fetch(
+      `/knowledgeBase/${knowledgeBaseId}/analytics/gaps`,
+      'GET',
+      params,
+    );
+    return result;
+  }
+}

package/services/messaging/EmailTemplatesService.js

@@ -10,18 +10,26 @@ export class EmailTemplatesService {
    * @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
+   * @param {Array<Object>} [params.variables] - Variable metadata definitions
+   * @param {string} params.variables[].key - Variable key (unique, alphanumeric + underscores)
+   * @param {string} params.variables[].label - Human-readable display name
+   * @param {string} params.variables[].type - One of: text, textarea, url, image, richtext
+   * @param {string} [params.variables[].defaultValue] - Default value
+   * @param {boolean} [params.variables[].required] - Whether variable is required
+   * @returns {Promise<Object>} Created template details with merged 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}}'
+   *   html: '<h1>Hello {{firstName}}</h1><p>{{body}}</p>',
+   *   text: 'Hello {{firstName}}',
+   *   variables: [
+   *     { key: 'firstName', label: 'First Name', type: 'text', required: true },
+   *     { key: 'body', label: 'Email Body', type: 'richtext' },
+   *   ],
    * });
-   * // Returns: { id, name, variables: ['firstName', 'lastName'] }
    */
-  async create({ name, subject, html, text }) {
+  async create({ name, subject, html, text, variables }) {
     this.sdk.validateParams(
       { name, subject },
       {
@@ -29,12 +37,14 @@ export class EmailTemplatesService {
         subject: { type: 'string', required: true },
         html: { type: 'string', required: false },
         text: { type: 'string', required: false },
+        variables: { type: 'array', required: false },
       },
     );
 
     const templateData = { name, subject };
     if (html) templateData.html = html;
     if (text) templateData.text = text;
+    if (variables) templateData.variables = variables;
 
     const options = {
       body: templateData,
@@ -56,15 +66,23 @@ export class EmailTemplatesService {
    * @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
+   * @param {Array<Object>} [params.variables] - Variable metadata definitions
+   * @param {string} params.variables[].key - Variable key (unique, alphanumeric + underscores)
+   * @param {string} params.variables[].label - Human-readable display name
+   * @param {string} params.variables[].type - One of: text, textarea, url, image, richtext
+   * @param {string} [params.variables[].defaultValue] - Default value
+   * @param {boolean} [params.variables[].required] - Whether variable is required
+   * @returns {Promise<Object>} Updated template details with merged 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}}!'
+   *   subject: 'Hi {{firstName}}, welcome to {{companyName}}!',
+   *   variables: [
+   *     { key: 'firstName', label: 'First Name', type: 'text', required: true },
+   *     { key: 'companyName', label: 'Company Name', type: 'text' },
+   *   ],
    * });
-   * // Returns updated template with variables: ['firstName', 'companyName']
    */
-  async update(id, { name, subject, html, text }) {
+  async update(id, { name, subject, html, text, variables }) {
     this.sdk.validateParams(
       { id },
       {
@@ -73,6 +91,7 @@ export class EmailTemplatesService {
         subject: { type: 'string', required: false },
         html: { type: 'string', required: false },
         text: { type: 'string', required: false },
+        variables: { type: 'array', required: false },
       },
     );
 
@@ -81,6 +100,7 @@ export class EmailTemplatesService {
     if (subject) updateData.subject = subject;
     if (html) updateData.html = html;
     if (text) updateData.text = text;
+    if (variables) updateData.variables = variables;
 
     const options = {
       body: updateData,