@unboundcx/sdk 4.1.2 → 4.1.3

package/README.md

@@ -176,6 +176,36 @@ await api.objects.describe('contacts'); // Get schema
 await api.objects.list(); // List all object types
 ```
 
+#### Live Queries (`api.objects.liveQuery`)
+
+Real-time, server-evaluated subscriptions over App1 Database objects. The
+server matches every mutation against your filter and pushes only relevant
+events — no client-side polling or firehose filtering.
+
+```javascript
+const handle = await api.objects.liveQuery({
+  socket, // an authed socket.io-client instance (required until the SDK ships its own transport)
+  object: 'contacts',
+  filter: { companyId: 'company-123' }, // bare value = equals; 'op::term' strings for other operators
+  onEvent: (frame) => {
+    // frame.type: 'enter' | 'change' | 'leave' | 'refresh' | 'resync' | 'revoked'
+    // 'enter'  -> frame.record (full row now matches your filter)
+    // 'change' -> frame.changedFields ONLY (patch, never the full row)
+    // 'leave'  -> frame.recordId no longer matches (or was deleted)
+    // 'refresh'/'resync' -> re-run your query (coarse mode or gap recovery)
+  },
+  onStateChange: (state) => {}, // 'active' | 'resubscribing' | 'revoked'
+});
+
+handle.unsubscribe(); // always tear down when done
+```
+
+Notes: the resolved `handle.mode` is `'fine'` (row-level events) or
+`'coarse'` (debounced refresh hints — used when the filter isn't
+row-evaluable). Heartbeats, reconnect-resubscribe, and sequence-gap resync
+are handled internally. Server caps: 25 subscriptions per socket, 500 per
+account.
+
 #### Messaging (`api.messaging`)
 
 ```javascript

package/index.js

@@ -27,6 +27,7 @@ import { EngagementMetricsService } from './services/engagementMetrics.js';
 import { TaskRouterService } from './services/taskRouter.js';
 import { KnowledgeBaseService } from './services/knowledgeBase.js';
 import { FaxService } from './services/fax.js';
+import { PermissionsService } from './services/permissions.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -95,6 +96,7 @@ class UnboundSDK extends BaseSDK {
     this.taskRouter = new TaskRouterService(this);
     this.knowledgeBase = new KnowledgeBaseService(this);
     this.fax = new FaxService(this);
+    this.permissions = new PermissionsService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();
@@ -274,4 +276,5 @@ 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 { PermissionsService } from './services/permissions.js';
 export { BaseSDK } from './base.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "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/permissions.js

@@ -0,0 +1,377 @@
+export class PermissionsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List permission groups
+   * @returns {Promise<Object>} Object with results: Array of permission groups
+   * @example
+   * const { results } = await sdk.permissions.listGroups();
+   */
+  async listGroups() {
+    const result = await this.sdk._fetch('/permissions/groups', 'GET');
+    return result;
+  }
+
+  /**
+   * Create a new permission group
+   * @param {Object} group - Group configuration
+   * @param {string} group.name - Group name (required)
+   * @param {string} group.description - Group description
+   * @returns {Promise<Object>} Created group
+   * @example
+   * await sdk.permissions.createGroup({
+   *   name: 'Support Leads',
+   *   description: 'Escalation-tier support agents',
+   * });
+   */
+  async createGroup({ name, description }) {
+    this.sdk.validateParams(
+      { name, description },
+      {
+        name: { type: 'string', required: true },
+        description: { type: 'string', required: false },
+      },
+    );
+
+    const groupData = { name };
+    if (description !== undefined) groupData.description = description;
+
+    const params = {
+      body: groupData,
+    };
+
+    const result = await this.sdk._fetch('/permissions/groups', 'POST', params);
+    return result;
+  }
+
+  /**
+   * Update an existing permission group
+   * @param {string} groupId - Group ID to update
+   * @param {Object} data - Fields to update (e.g. name, description)
+   * @returns {Promise<Object>} Updated group
+   * @example
+   * await sdk.permissions.updateGroup('group-123', { description: 'Updated' });
+   */
+  async updateGroup(groupId, data) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId },
+      {
+        groupId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: data,
+    };
+
+    const result = await this.sdk._fetch(
+      `/permissions/groups/${groupId}`,
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Delete a permission group
+   * @param {string} groupId - Group ID to delete
+   * @returns {Promise<Object>} Deletion confirmation
+   * @example
+   * await sdk.permissions.deleteGroup('group-123');
+   */
+  async deleteGroup(groupId) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId },
+      {
+        groupId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/permissions/groups/${groupId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * Add a user to a permission group
+   * @param {string} groupId - Group ID
+   * @param {string} userId - User ID to add
+   * @returns {Promise<Object>} Membership confirmation
+   * @example
+   * await sdk.permissions.addGroupMember('group-123', 'user-456');
+   */
+  async addGroupMember(groupId, userId) {
+    groupId = String(groupId);
+    userId = String(userId);
+    this.sdk.validateParams(
+      { groupId, userId },
+      {
+        groupId: { type: 'string', required: true },
+        userId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { userId },
+    };
+
+    const result = await this.sdk._fetch(
+      `/permissions/groups/${groupId}/members`,
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Remove a user from a permission group
+   * @param {string} groupId - Group ID
+   * @param {string} userId - User ID to remove
+   * @returns {Promise<Object>} Removal confirmation
+   * @example
+   * await sdk.permissions.removeGroupMember('group-123', 'user-456');
+   */
+  async removeGroupMember(groupId, userId) {
+    groupId = String(groupId);
+    userId = String(userId);
+    this.sdk.validateParams(
+      { groupId, userId },
+      {
+        groupId: { type: 'string', required: true },
+        userId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/permissions/groups/${groupId}/members/${userId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * List permission sets (system defaults are returned first)
+   * @returns {Promise<Object>} Object with results: Array of permission sets
+   * @example
+   * const { results } = await sdk.permissions.listPermissionSets();
+   */
+  async listPermissionSets() {
+    const result = await this.sdk._fetch('/permissions/sets', 'GET');
+    return result;
+  }
+
+  /**
+   * Create a new permission set
+   * @param {Object} set - Permission set configuration
+   * @param {string} set.name - Permission set name (required)
+   * @param {Array<string>} set.scopes - Scopes granted by this set (required)
+   * @returns {Promise<Object>} Created permission set
+   * @example
+   * await sdk.permissions.createPermissionSet({
+   *   name: 'Voice Admin',
+   *   scopes: ['voice:calls:read', 'voice:calls:write'],
+   * });
+   */
+  async createPermissionSet({ name, scopes }) {
+    this.sdk.validateParams(
+      { name, scopes },
+      {
+        name: { type: 'string', required: true },
+        scopes: { type: 'array', required: true },
+      },
+    );
+
+    const params = {
+      body: { name, scopes },
+    };
+
+    const result = await this.sdk._fetch('/permissions/sets', 'POST', params);
+    return result;
+  }
+
+  /**
+   * Update an existing permission set
+   * @param {string} setId - Permission set ID to update
+   * @param {Object} data - Fields to update (e.g. name, scopes)
+   * @returns {Promise<Object>} Updated permission set
+   * @example
+   * await sdk.permissions.updatePermissionSet('set-123', { scopes: ['voice:calls:read'] });
+   */
+  async updatePermissionSet(setId, data) {
+    setId = String(setId);
+    this.sdk.validateParams(
+      { setId },
+      {
+        setId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: data,
+    };
+
+    const result = await this.sdk._fetch(
+      `/permissions/sets/${setId}`,
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Delete a permission set
+   * @param {string} setId - Permission set ID to delete
+   * @returns {Promise<Object>} Deletion confirmation
+   * @example
+   * await sdk.permissions.deletePermissionSet('set-123');
+   */
+  async deletePermissionSet(setId) {
+    setId = String(setId);
+    this.sdk.validateParams(
+      { setId },
+      {
+        setId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/permissions/sets/${setId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * Assign a permission set to a principal (user or group)
+   * @param {Object} assignment - Assignment configuration
+   * @param {string} assignment.permissionSetId - Permission set ID (required)
+   * @param {string} assignment.principalType - Principal type, e.g. 'user' or 'group' (required)
+   * @param {string} assignment.principalId - Principal ID (required)
+   * @param {string} assignment.grantType - Grant type, e.g. 'allow' or 'deny' (required)
+   * @returns {Promise<Object>} Created assignment
+   * @example
+   * await sdk.permissions.assignPermissionSet({
+   *   permissionSetId: 'set-123',
+   *   principalType: 'user',
+   *   principalId: 'user-456',
+   *   grantType: 'allow',
+   * });
+   */
+  async assignPermissionSet({
+    permissionSetId,
+    principalType,
+    principalId,
+    grantType,
+  }) {
+    permissionSetId = String(permissionSetId);
+    principalId = String(principalId);
+    this.sdk.validateParams(
+      { permissionSetId, principalType, principalId, grantType },
+      {
+        permissionSetId: { type: 'string', required: true },
+        principalType: { type: 'string', required: true },
+        principalId: { type: 'string', required: true },
+        grantType: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { permissionSetId, principalType, principalId, grantType },
+    };
+
+    const result = await this.sdk._fetch(
+      '/permissions/assignments',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Remove a permission set assignment from a principal
+   * @param {string} permissionSetId - Permission set ID
+   * @param {string} principalType - Principal type, e.g. 'user' or 'group'
+   * @param {string} principalId - Principal ID
+   * @returns {Promise<Object>} Removal confirmation
+   * @example
+   * await sdk.permissions.unassignPermissionSet('set-123', 'user', 'user-456');
+   */
+  async unassignPermissionSet(permissionSetId, principalType, principalId) {
+    permissionSetId = String(permissionSetId);
+    principalId = String(principalId);
+    this.sdk.validateParams(
+      { permissionSetId, principalType, principalId },
+      {
+        permissionSetId: { type: 'string', required: true },
+        principalType: { type: 'string', required: true },
+        principalId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/permissions/assignments/${permissionSetId}/${principalType}/${principalId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * Get a user's effective scopes, resolved from all assigned permission sets
+   * @param {string} userId - User ID
+   * @returns {Promise<Object>} Object with userId, scopes, breakdown ({scope, sources}[]), deniedScopes
+   * @example
+   * const { scopes, breakdown, deniedScopes } = await sdk.permissions.getEffectiveScopes('user-456');
+   */
+  /**
+   * Effective scopes contributed by membership in a group.
+   * @param {string|number} groupId - Group ID (required)
+   * @returns {Promise<Object>} { groupId, scopes, breakdown, deniedScopes }
+   */
+  async getGroupEffectiveScopes(groupId) {
+    groupId = String(groupId);
+    this.sdk.validateParams(
+      { groupId },
+      {
+        groupId: { type: 'string', required: true },
+      },
+    );
+    const result = await this.sdk._fetch(
+      `/permissions/groups/${groupId}/effective-scopes`,
+      'GET',
+    );
+    return result;
+  }
+
+  async getEffectiveScopes(userId) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId },
+      {
+        userId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/permissions/users/${userId}/effective-scopes`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Get the full catalog of available scopes, grouped by pillar
+   * @returns {Promise<Object>} Object with pillars: Array of {pillar, scopes: [{scope, label}]}
+   * @example
+   * const { pillars } = await sdk.permissions.getScopeCatalog();
+   */
+  async getScopeCatalog() {
+    const result = await this.sdk._fetch('/permissions/scope-catalog', 'GET');
+    return result;
+  }
+}