@unboundcx/sdk 2.8.7 → 2.8.8

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,