@unboundcx/sdk 2.8.7 → 2.8.8

package/index.js

@@ -25,6 +25,8 @@ import { RecordTypesService } from './services/recordTypes.js';
 import { GenerateIdService } from './services/generateId.js';
 import { EngagementMetricsService } from './services/engagementMetrics.js';
 import { TaskRouterService } from './services/taskRouter.js';
+import { KnowledgeBaseService } from './services/knowledgeBase.js';
+import { FaxService } from './services/fax.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -91,6 +93,8 @@ class UnboundSDK extends BaseSDK {
     this.generateId = new GenerateIdService(this);
     this.engagementMetrics = new EngagementMetricsService(this);
     this.taskRouter = new TaskRouterService(this);
+    this.knowledgeBase = new KnowledgeBaseService(this);
+    this.fax = new FaxService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();
@@ -268,4 +272,6 @@ export { GenerateIdService } from './services/generateId.js';
 export { EngagementMetricsService } from './services/engagementMetrics.js';
 export { TaskRouterService } from './services/taskRouter.js';
 export { WorkerService } from './services/taskRouter/WorkerService.js';
+export { KnowledgeBaseService } from './services/knowledgeBase.js';
+export { FaxService } from './services/fax.js';
 export { BaseSDK } from './base.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "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/ai.js

@@ -20,39 +20,81 @@ export class GenerativeService {
     prompt,
     messages,
     systemPrompt,
+    appendSystemPrompt,
     relatedId,
+    peopleId,
+    companyId,
     provider,
     model,
     temperature,
+    maxTokens,
     subscriptionId,
     stream,
     isPlayground = false,
     responseFormat,
+    sessionId,
+    scope,
+    manageSession,
+    tools,
+    toolConfig,
+    maxToolRounds,
+    recordTypeId,
+    meta,
+    qualityCheck,
+    isPublic,
   }) {
     this.sdk.validateParams(
       {
         stream,
         temperature,
+        maxTokens,
         subscriptionId,
         provider,
         model,
         prompt,
         messages,
         systemPrompt,
+        appendSystemPrompt,
         isPlayground,
         responseFormat,
+        sessionId,
+        scope,
+        manageSession,
+        tools,
+        toolConfig,
+        maxToolRounds,
+        recordTypeId,
+        peopleId,
+        companyId,
+        meta,
+        qualityCheck,
+        isPublic,
       },
       {
         prompt: { type: 'string', required: false },
         messages: { type: 'array', required: false },
         systemPrompt: { type: 'string', required: false },
+        appendSystemPrompt: { type: 'string', required: false },
         provider: { type: 'string', required: false },
         model: { type: 'string', required: false },
         temperature: { type: 'number', required: false },
+        maxTokens: { type: 'number', required: false },
         subscriptionId: { type: 'string', required: false },
         stream: { type: 'boolean', required: false },
         isPlayground: { type: 'boolean', required: false },
         responseFormat: { type: 'object', required: false },
+        sessionId: { type: 'string', required: false },
+        scope: { type: 'string', required: false },
+        manageSession: { type: 'boolean', required: false },
+        tools: { type: 'array', required: false },
+        toolConfig: { type: 'object', required: false },
+        maxToolRounds: { type: 'number', required: false },
+        recordTypeId: { type: 'string', required: false },
+        peopleId: { type: 'string', required: false },
+        companyId: { type: 'string', required: false },
+        meta: { type: 'object', required: false },
+        qualityCheck: { type: 'boolean', required: false },
+        isPublic: { type: 'boolean', required: false },
       },
     );
 
@@ -62,20 +104,44 @@ export class GenerativeService {
         prompt,
         messages,
         systemPrompt,
+        appendSystemPrompt,
         relatedId,
+        peopleId,
+        companyId,
         provider,
         model,
         temperature,
+        maxTokens,
         subscriptionId,
         stream,
         responseFormat,
+        sessionId,
+        scope,
+        manageSession,
+        tools,
+        toolConfig,
+        maxToolRounds,
+        recordTypeId,
+        meta,
+        qualityCheck,
+        isPublic,
       },
       // Return raw response for streaming to allow client-side stream handling
       returnRawResponse: stream === true,
     };
 
-    // Force HTTP transport when streaming is enabled since NATS doesn't support streaming responses
-    const forceFetch = stream === true;
+    // Force HTTP transport when streaming or when messages contain large content (too large for NATS)
+    const hasLargeContent = messages?.some(
+      (m) =>
+        Array.isArray(m.content) &&
+        m.content.some(
+          (c) =>
+            c.type === 'image' ||
+            c.type === 'image_url' ||
+            c.type === 'document',
+        ),
+    );
+    const forceFetch = stream === true || hasLargeContent;
     const result = await this.sdk._fetch(
       '/ai/generative/chat',
       'POST',
@@ -85,6 +151,180 @@ export class GenerativeService {
     return result;
   }
 
+  /**
+   * Clone an existing chat session into a new one, importing conversation context.
+   * Filters out system prompts and tool calls, keeps user/assistant turns.
+   * If the transcript exceeds ~50k tokens it is summarized automatically.
+   *
+   * @param {Object} options
+   * @param {string} options.sourceSessionId - Session to clone from (required)
+   * @param {string} [options.systemPrompt] - New system prompt (appended after conversation context)
+   * @param {string} [options.provider] - LLM provider (falls back to source session)
+   * @param {string} [options.model] - Model ID (falls back to source session)
+   * @param {Array}  [options.tools] - Tool names (falls back to source session)
+   * @param {Object} [options.toolConfig] - Tool config (falls back to source session)
+   * @param {string} [options.scope] - 'user' or 'account'
+   * @param {string} [options.userId] - Owner user ID
+   * @param {string} [options.peopleId] - Linked people record
+   * @param {string} [options.companyId] - Linked company record
+   * @param {string} [options.relatedId] - Linked related record
+   * @returns {Promise<Object>} { id, sourceSessionId, wasSummarized }
+   */
+  async cloneSession({
+    sourceSessionId,
+    systemPrompt,
+    provider,
+    model,
+    tools,
+    toolConfig,
+    scope,
+    userId,
+    peopleId,
+    companyId,
+    relatedId,
+  }) {
+    this.sdk.validateParams(
+      { sourceSessionId },
+      {
+        sourceSessionId: { type: 'string', required: true },
+        systemPrompt: { type: 'string', required: false },
+        provider: { type: 'string', required: false },
+        model: { type: 'string', required: false },
+        tools: { type: 'array', required: false },
+        toolConfig: { type: 'object', required: false },
+        scope: { type: 'string', required: false },
+        userId: { type: 'string', required: false },
+        peopleId: { type: 'string', required: false },
+        companyId: { type: 'string', required: false },
+        relatedId: { type: 'string', required: false },
+      },
+    );
+
+    const params = {
+      body: {
+        sourceSessionId,
+        systemPrompt,
+        provider,
+        model,
+        tools,
+        toolConfig,
+        scope,
+        userId,
+        peopleId,
+        companyId,
+        relatedId,
+      },
+    };
+
+    const result = await this.sdk._fetch(
+      '/ai/generative/chat/clone',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * List available chat tools and their metadata
+   * @returns {Promise<Object>} { tools: Array<{ name, label, description, configRequirements }>, count: number }
+   */
+  async listTools() {
+    return await this.sdk._fetch('/ai/generative/tools', 'GET');
+  }
+
+  /**
+   * List chat sessions visible to the current user
+   * @param {Object} [options] - Filter options
+   * @param {string} [options.relatedId] - Filter by related object ID
+   * @param {string} [options.scope] - Filter by scope ('user' or 'account')
+   * @param {number} [options.limit=25] - Results limit
+   * @param {number} [options.offset=0] - Pagination offset
+   * @returns {Promise<Object>} { sessions: Array }
+   */
+  async listSessions({ relatedId, scope, limit, offset } = {}) {
+    this.sdk.validateParams(
+      { relatedId, scope, limit, offset },
+      {
+        relatedId: { type: 'string', required: false },
+        scope: { type: 'string', required: false },
+        limit: { type: 'number', required: false },
+        offset: { type: 'number', required: false },
+      },
+    );
+
+    const params = { query: { relatedId, scope, limit, offset } };
+    const result = await this.sdk._fetch(
+      '/ai/generative/sessions',
+      'GET',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Get a chat session with its message history
+   * @param {Object} options
+   * @param {string} options.sessionId - Session ID to retrieve
+   * @returns {Promise<Object>} { session: { id, name, scope, relatedId, provider, model, messages, messageCount, lastMessageAt, createdAt } }
+   */
+  async getSession({ sessionId }) {
+    this.sdk.validateParams(
+      { sessionId },
+      { sessionId: { type: 'string', required: true } },
+    );
+
+    const result = await this.sdk._fetch(
+      `/ai/generative/sessions/${sessionId}`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Update a chat session (name, scope)
+   * @param {Object} options
+   * @param {string} options.sessionId - Session ID to update
+   * @param {string} [options.name] - New session name
+   * @param {string} [options.scope] - New scope ('user' or 'account')
+   * @returns {Promise<Object>} { success: true }
+   */
+  async updateSession({ sessionId, name, scope }) {
+    this.sdk.validateParams(
+      { sessionId, name, scope },
+      {
+        sessionId: { type: 'string', required: true },
+        name: { type: 'string', required: false },
+        scope: { type: 'string', required: false },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/ai/generative/sessions/${sessionId}`,
+      'PUT',
+      { body: { name, scope } },
+    );
+    return result;
+  }
+
+  /**
+   * Delete a chat session
+   * @param {Object} options
+   * @param {string} options.sessionId - Session ID to delete
+   * @returns {Promise<Object>} { success: true }
+   */
+  async deleteSession({ sessionId }) {
+    this.sdk.validateParams(
+      { sessionId },
+      { sessionId: { type: 'string', required: true } },
+    );
+
+    const result = await this.sdk._fetch(
+      `/ai/generative/sessions/${sessionId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
   async playbook({
     prompt,
     messages,

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);
+  }
+}