@unboundcx/sdk 4.6.0 → 4.6.2

package/README.md

@@ -175,6 +175,41 @@ await api.objects.updateById('contacts', 'contact-123', { name: 'Jane' });
 await api.objects.deleteById('contacts', 'contact-123');
 await api.objects.describe('contacts'); // Get schema
 await api.objects.list(); // List all object types
+
+// Skip trigger execution on a write (imports / bulk tools)
+await api.objects.updateById({
+  object: 'people',
+  id: '013…',
+  update: { leadScore: 200 },
+  skipTriggers: true,
+});
+```
+
+#### Triggers (`api.triggers`)
+
+```javascript
+await api.triggers.listObjects();
+await api.triggers.list({ objectName: 'people', status: 'enabled' });
+await api.triggers.create({
+  name: 'Hot lead',
+  objectName: 'people',
+  actions: ['update'],
+  recordFilter: { type: { op: 'eq', value: 'lead' } },
+  changeFilters: [
+    {
+      field: 'leadScore',
+      previous: { op: 'lt', value: 20 },
+      updated: { op: 'gt', value: 100 },
+    },
+  ],
+  actionType: 'workflow',
+  actionConfig: { workflowVersionId: '052…' },
+});
+await api.triggers.get('173…');
+await api.triggers.update('173…', { status: 'paused' });
+await api.triggers.setStatus('173…', 'enabled');
+await api.triggers.listFires('173…', { limit: 20 });
+await api.triggers.delete('173…');
 ```
 
 #### Live Queries (`api.objects.liveQuery`)
@@ -409,7 +444,6 @@ const fileUrl = api.storage.getFileUrl(files[0].storageId);
 await api.storage.deleteFile(files[0].storageId);
 ```
 
-
 #### Documents (`api.documents`)
 
 Generic templates → PDF. Implementation: `services/documents.js`.
@@ -419,7 +453,9 @@ Generic templates → PDF. Implementation: `services/documents.js`.
 const created = await api.documents.templates.create({
   name: 'Fax cover',
   engine: 'generative', // or 'overlay' + sourcePdfStorageId
+  uses: ['fax'], // omit / [] = every surface
 });
+await api.documents.templates.list({ status: 'published', use: 'fax' });
 await api.documents.templates.update(created.id, { draftSchemaJson, draftLayoutJson });
 await api.documents.templates.publish(created.id);
 

package/index.js

@@ -29,6 +29,7 @@ import { KnowledgeBaseService } from './services/knowledgeBase.js';
 import { FaxService } from './services/fax.js';
 import { DocumentsService } from './services/documents.js';
 import { PermissionsService } from './services/permissions.js';
+import { TriggersService } from './services/triggers.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -99,6 +100,7 @@ class UnboundSDK extends BaseSDK {
     this.fax = new FaxService(this);
     this.documents = new DocumentsService(this);
     this.permissions = new PermissionsService(this);
+    this.triggers = new TriggersService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.6.0",
+  "version": "4.6.2",
   "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/documents.js

@@ -9,6 +9,7 @@ export class DocumentTemplatesService {
    * @param {string} params.name - Template name (required)
    * @param {string} [params.description]
    * @param {string} [params.tag]
+   * @param {string[]} [params.uses] - Consumer surfaces (`fax`). Empty = all.
    * @param {'generative'|'overlay'} [params.engine='generative']
    * @param {string} [params.sourcePdfStorageId] - Required when engine is overlay
    * @param {Object} [params.draftSchemaJson]
@@ -21,6 +22,7 @@ export class DocumentTemplatesService {
     name,
     description,
     tag,
+    uses,
     engine,
     sourcePdfStorageId,
     draftSchemaJson,
@@ -34,6 +36,7 @@ export class DocumentTemplatesService {
         name: { type: 'string', required: true },
         description: { type: 'string', required: false },
         tag: { type: 'string', required: false },
+        uses: { type: 'object', required: false },
         engine: { type: 'string', required: false },
         sourcePdfStorageId: { type: 'string', required: false },
         draftSchemaJson: { type: 'object', required: false },
@@ -46,6 +49,7 @@ export class DocumentTemplatesService {
     const body = { name };
     if (description !== undefined) body.description = description;
     if (tag !== undefined) body.tag = tag;
+    if (uses !== undefined) body.uses = uses;
     if (engine !== undefined) body.engine = engine;
     if (sourcePdfStorageId !== undefined) {
       body.sourcePdfStorageId = sourcePdfStorageId;
@@ -63,13 +67,15 @@ export class DocumentTemplatesService {
    * @param {Object} [params]
    * @param {string} [params.tag]
    * @param {string} [params.status]
+   * @param {string} [params.use] - Consumer surface (`fax`). Empty uses match all.
    * @param {number} [params.limit]
    * @returns {Promise<{results: Object[]}>}
    */
-  async list({ tag, status, limit } = {}) {
+  async list({ tag, status, use, limit } = {}) {
     const query = {};
     if (tag) query.tag = tag;
     if (status) query.status = status;
+    if (use) query.use = use;
     if (limit) query.limit = limit;
     return this.sdk._fetch('/documents/templates', 'GET', { query });
   }
@@ -91,6 +97,7 @@ export class DocumentTemplatesService {
    * @param {string} [params.name]
    * @param {string} [params.description]
    * @param {string} [params.tag]
+   * @param {string[]} [params.uses]
    * @param {Object} [params.draftSchemaJson]
    * @param {Object} [params.draftLayoutJson]
    * @param {Object} [params.draftPageJson]
@@ -103,6 +110,8 @@ export class DocumentTemplatesService {
       name,
       description,
       tag,
+      uses,
+      recordTypeId,
       draftSchemaJson,
       draftLayoutJson,
       draftPageJson,
@@ -116,6 +125,8 @@ export class DocumentTemplatesService {
         name: { type: 'string', required: false },
         description: { type: 'string', required: false },
         tag: { type: 'string', required: false },
+        uses: { type: 'object', required: false },
+        recordTypeId: { type: 'string', required: false },
         draftSchemaJson: { type: 'object', required: false },
         draftLayoutJson: { type: 'object', required: false },
         draftPageJson: { type: 'object', required: false },
@@ -127,6 +138,8 @@ export class DocumentTemplatesService {
     if (name !== undefined) body.name = name;
     if (description !== undefined) body.description = description;
     if (tag !== undefined) body.tag = tag;
+    if (uses !== undefined) body.uses = uses;
+    if (recordTypeId !== undefined) body.recordTypeId = recordTypeId;
     if (draftSchemaJson !== undefined) body.draftSchemaJson = draftSchemaJson;
     if (draftLayoutJson !== undefined) body.draftLayoutJson = draftLayoutJson;
     if (draftPageJson !== undefined) body.draftPageJson = draftPageJson;

package/services/permissions.js

@@ -408,7 +408,7 @@ export class PermissionsService {
     return this.sdk._fetch(
       `/permissions/groups/${groupId}/settings/${settingKey}`,
       'PUT',
-      { value },
+      { body: { value } },
     );
   }
 
@@ -436,7 +436,7 @@ export class PermissionsService {
   async setGroupPriority(order) {
     this.sdk.validateParams({ order }, { order: { type: 'array', required: true } });
     return this.sdk._fetch('/permissions/groups/priority', 'PUT', {
-      order: order.map(String),
+      body: { order: order.map(String) },
     });
   }
 
@@ -465,7 +465,7 @@ export class PermissionsService {
     return this.sdk._fetch(
       `/permissions/users/${userId}/settings/${settingKey}`,
       'PUT',
-      { value },
+      { body: { value } },
     );
   }
 
@@ -485,4 +485,132 @@ export class PermissionsService {
       'DELETE',
     );
   }
+
+  // ---- Group-assigned skills and queues (§9.5) --------------------------
+  // Set-shaped, not scalar: they union across every group a user belongs to
+  // and never consult group priority. Writes fan out to each member's
+  // materialized userSkills/queueUsers rows and re-push their live worker.
+  //
+  // NOTE for anyone adding a method here: `_fetch`'s third argument is the
+  // params envelope — a request body MUST be passed as `{ body: {...} }`.
+  // Passing the payload bare silently sends no body at all.
+
+  /** Skill + queue vocabulary for the group assignment pickers. */
+  async getTaskRoutingCatalog() {
+    return this.sdk._fetch('/permissions/task-routing/catalog', 'GET');
+  }
+
+  /** Skills this group grants. @returns {Promise<{results: Array<{skillId}>}>} */
+  async listGroupSkills(groupId) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId },
+      { groupId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch(`/permissions/groups/${groupId}/skills`, 'GET');
+  }
+
+  /** Replace the group's full skill list. */
+  async setGroupSkills(groupId, skillIds) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId, skillIds },
+      {
+        groupId: { type: 'string', required: true },
+        skillIds: { type: 'array', required: true },
+      },
+    );
+    return this.sdk._fetch(`/permissions/groups/${groupId}/skills`, 'PUT', {
+      body: { skillIds: skillIds.map(String) },
+    });
+  }
+
+  /** Queues this group grants. @returns {Promise<{results: Array<{queueId, access, autoLogin}>}>} */
+  async listGroupQueues(groupId) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId },
+      { groupId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch(`/permissions/groups/${groupId}/queues`, 'GET');
+  }
+
+  /**
+   * Replace the group's full queue list.
+   * @param {Array<{queueId: string, access?: boolean, autoLogin?: boolean}>} queues
+   *   `autoLogin` seeds the derived membership row and takes effect at the
+   *   agent's next availability transition — it never logs anyone in
+   *   mid-session.
+   */
+  async setGroupQueues(groupId, queues) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId, queues },
+      {
+        groupId: { type: 'string', required: true },
+        queues: { type: 'array', required: true },
+      },
+    );
+    return this.sdk._fetch(`/permissions/groups/${groupId}/queues`, 'PUT', {
+      body: {
+        queues: queues.map((q) => ({
+          queueId: String(q.queueId),
+          access: q.access !== false,
+          autoLogin: Boolean(q.autoLogin),
+        })),
+      },
+    });
+  }
+
+  /**
+   * A user's effective skills/queues with the source of each row, so the UI
+   * can show "granted by group X" instead of offering a control that would
+   * silently no-op.
+   */
+  async getUserTaskRouting(userId) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId },
+      { userId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch(`/permissions/users/${userId}/task-routing`, 'GET');
+  }
+
+  /** Exclude one group-granted skill/queue from this user ("in Sales but not queue X"). */
+  async addTaskRoutingExclusion(userId, settingKey, value) {
+    userId = String(userId);
+    settingKey = String(settingKey);
+    value = String(value);
+    this.sdk.validateParams(
+      { userId, settingKey, value },
+      {
+        userId: { type: 'string', required: true },
+        settingKey: { type: 'string', required: true },
+        value: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch(
+      `/permissions/users/${userId}/task-routing/exclusions/${settingKey}/${value}`,
+      'PUT',
+    );
+  }
+
+  /** Drop an exclusion, letting the group grant apply again. */
+  async removeTaskRoutingExclusion(userId, settingKey, value) {
+    userId = String(userId);
+    settingKey = String(settingKey);
+    value = String(value);
+    this.sdk.validateParams(
+      { userId, settingKey, value },
+      {
+        userId: { type: 'string', required: true },
+        settingKey: { type: 'string', required: true },
+        value: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch(
+      `/permissions/users/${userId}/task-routing/exclusions/${settingKey}/${value}`,
+      'DELETE',
+    );
+  }
 }

package/services/triggers.js

@@ -0,0 +1,245 @@
+/**
+ * Triggers Service — object-change automations (workflow or outbound webhook).
+ *
+ * Watch create/update/delete on a trigger-enabled object, filter on the
+ * current row and/or the field that changed, then run a workflow session
+ * or POST to a URL.
+ *
+ * @example
+ * const { results } = await sdk.triggers.list({ objectName: 'people' });
+ *
+ * @example
+ * await sdk.triggers.create({
+ *   name: 'Hot lead',
+ *   objectName: 'people',
+ *   actions: ['update'],
+ *   recordFilter: { type: { op: 'eq', value: 'lead' } },
+ *   changeFilters: [{
+ *     field: 'leadScore',
+ *     previous: { op: 'lt', value: 20 },
+ *     updated: { op: 'gt', value: 100 },
+ *   }],
+ *   actionType: 'workflow',
+ *   actionConfig: { workflowVersionId: '052…' },
+ * });
+ */
+export class TriggersService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List objects that may have triggers (`objectMetaData.triggersEnabled`).
+   *
+   * @returns {Promise<{results: Array<{id: string, name: string}>}>}
+   *
+   * @example
+   * const { results } = await sdk.triggers.listObjects();
+   */
+  async listObjects() {
+    return this.sdk._fetch('/triggers/objects', 'GET', {});
+  }
+
+  /**
+   * List triggers for the account.
+   *
+   * @param {object} [args]
+   * @param {string} [args.objectName] - Filter to one object (e.g. `'people'`)
+   * @param {('enabled'|'paused'|'disabled')} [args.status]
+   * @param {number} [args.limit=200]
+   * @returns {Promise<{results: object[]}>}
+   *
+   * @example
+   * await sdk.triggers.list({ objectName: 'people', status: 'enabled' });
+   */
+  async list({ objectName, status, limit } = {}) {
+    const query = {};
+    if (objectName) query.objectName = objectName;
+    if (status) query.status = status;
+    if (limit) query.limit = limit;
+    return this.sdk._fetch('/triggers/', 'GET', { query });
+  }
+
+  /**
+   * Get a trigger by id.
+   *
+   * @param {string} id
+   * @returns {Promise<object>}
+   *
+   * @example
+   * const trigger = await sdk.triggers.get('173…');
+   */
+  async get(id) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return this.sdk._fetch(`/triggers/${id}`, 'GET', {});
+  }
+
+  /**
+   * Create a trigger.
+   *
+   * @param {object} args
+   * @param {string} args.name
+   * @param {string} [args.description]
+   * @param {string} args.objectName - Must have `triggersEnabled` (people, company, opportunities, projects, or custom `__c`)
+   * @param {Array<'create'|'update'|'delete'>} args.actions
+   * @param {('enabled'|'paused'|'disabled')} [args.status='enabled']
+   * @param {Object<string, {op: string, value: *}|*>} [args.recordFilter] - Current-row match (new row on create/update, old on delete)
+   * @param {Array<{field: string, previous?: {op: string, value: *}, updated?: {op: string, value: *}}>} [args.changeFilters] - Field must be in `changedFields`; optional previous/updated checks
+   * @param {('workflow'|'webhook')} args.actionType
+   * @param {object} args.actionConfig
+   * @param {string} [args.actionConfig.workflowVersionId] - Required when `actionType` is `'workflow'`
+   * @param {string} [args.actionConfig.workflowId]
+   * @param {string[]} [args.actionConfig.includeValues] - Field values to include (previous + updated). Empty = names only. `['*']` = every non-encrypted field. Encrypted columns are never sent.
+   * @param {string} [args.actionConfig.primaryUrl] - Required when `actionType` is `'webhook'`; must be `https://`
+   * @param {string} [args.actionConfig.secondaryUrl] - Failover URL; must be `https://` if set
+   * @param {string} [args.actionConfig.credentialId] - Stored webhook authorization id
+   * @param {number} [args.timeoutMinutes=15] - Queued-fire TTL, 1–1440
+   * @param {number} [args.retries=3] - Webhook retries, 0–5
+   * @returns {Promise<object>} Created trigger
+   *
+   * @example
+   * await sdk.triggers.create({
+   *   name: 'Notify CRM',
+   *   objectName: 'people',
+   *   actions: ['update'],
+   *   actionType: 'webhook',
+   *   actionConfig: {
+   *     primaryUrl: 'https://example.com/hooks/lead',
+   *     secondaryUrl: 'https://backup.example.com/hooks/lead',
+   *     includeValues: ['leadScore', 'email'],
+   *   },
+   *   timeoutMinutes: 15,
+   *   retries: 3,
+   * });
+   */
+  async create({
+    name,
+    description,
+    objectName,
+    actions,
+    status,
+    recordFilter,
+    changeFilters,
+    actionType,
+    actionConfig,
+    timeoutMinutes,
+    retries,
+    recordTypeId,
+  }) {
+    const body = {
+      name,
+      description,
+      objectName,
+      actions,
+      status,
+      recordFilter,
+      changeFilters,
+      actionType,
+      actionConfig,
+      timeoutMinutes,
+      retries,
+      recordTypeId,
+    };
+
+    this.sdk.validateParams(
+      { name, objectName, actions, actionType, actionConfig },
+      {
+        name: { type: 'string', required: true },
+        objectName: { type: 'string', required: true },
+        actions: { type: 'object', required: true },
+        actionType: { type: 'string', required: true },
+        actionConfig: { type: 'object', required: true },
+      },
+    );
+
+    return this.sdk._fetch('/triggers/', 'POST', { body });
+  }
+
+  /**
+   * Update a trigger. Only provided fields are changed.
+   *
+   * @param {string} id
+   * @param {object} args - Same shape as {@link TriggersService#create}; all keys optional
+   * @returns {Promise<object>} Updated trigger
+   *
+   * @example
+   * await sdk.triggers.update('173…', { status: 'paused' });
+   */
+  async update(id, args = {}) {
+    this.sdk.validateParams(
+      { id, args },
+      {
+        id: { type: 'string', required: true },
+        args: { type: 'object', required: true },
+      },
+    );
+    return this.sdk._fetch(`/triggers/${id}`, 'PUT', { body: args });
+  }
+
+  /**
+   * Soft-delete a trigger.
+   *
+   * @param {string} id
+   * @returns {Promise<{id: string, deleted: boolean}>}
+   *
+   * @example
+   * await sdk.triggers.delete('173…');
+   */
+  async delete(id) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return this.sdk._fetch(`/triggers/${id}`, 'DELETE', {});
+  }
+
+  /**
+   * Alias of {@link TriggersService#delete}.
+   *
+   * @param {string} id
+   * @returns {Promise<{id: string, deleted: boolean}>}
+   */
+  async remove(id) {
+    return this.delete(id);
+  }
+
+  /**
+   * Set trigger status without a full update.
+   *
+   * @param {string} id
+   * @param {('enabled'|'paused'|'disabled')} status
+   * @param {object} [opts]
+   * @param {string} [opts.pausedReason] - Stored when `status` is `'paused'`
+   * @returns {Promise<object>} Updated trigger
+   *
+   * @example
+   * await sdk.triggers.setStatus('173…', 'paused', { pausedReason: 'rate limit' });
+   */
+  async setStatus(id, status, { pausedReason } = {}) {
+    this.sdk.validateParams(
+      { id, status },
+      {
+        id: { type: 'string', required: true },
+        status: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch(`/triggers/${id}/status`, 'POST', {
+      body: { status, pausedReason },
+    });
+  }
+
+  /**
+   * Recent execution log for a trigger (queued / fired / dropped / rejected / timeout).
+   *
+   * @param {string} id
+   * @param {object} [opts]
+   * @param {number} [opts.limit=50]
+   * @returns {Promise<{results: object[]}>}
+   *
+   * @example
+   * const { results } = await sdk.triggers.listFires('173…', { limit: 20 });
+   */
+  async listFires(id, { limit } = {}) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    const query = {};
+    if (limit) query.limit = limit;
+    return this.sdk._fetch(`/triggers/${id}/fires`, 'GET', { query });
+  }
+}

package/test-complete-coverage.js

@@ -41,7 +41,7 @@ async function testPublicSDKCompleteness() {
     'phoneNumbers',
     'recordTypes',
     'generateId',
-    'documents',
+    'triggers',
   ];
 
   console.log(`📊 Checking ${publicServices.length} public services...`);