@unboundcx/sdk 4.6.3 → 4.8.0

package/index.js

@@ -30,6 +30,8 @@ import { FaxService } from './services/fax.js';
 import { DocumentsService } from './services/documents.js';
 import { PermissionsService } from './services/permissions.js';
 import { TriggersService } from './services/triggers.js';
+import { InboxService } from './services/inbox.js';
+import { DirectoryService } from './services/directory.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -101,6 +103,8 @@ class UnboundSDK extends BaseSDK {
     this.documents = new DocumentsService(this);
     this.permissions = new PermissionsService(this);
     this.triggers = new TriggersService(this);
+    this.inbox = new InboxService(this);
+    this.directory = new DirectoryService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();
@@ -281,4 +285,6 @@ 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 { InboxService } from './services/inbox.js';
+export { DirectoryService } from './services/directory.js';
 export { BaseSDK } from './base.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.6.3",
+  "version": "4.8.0",
   "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/schemas/layouts/homeLayoutDoc.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { WidgetSection } from './widgetSection.js';
+
+// Home-dashboard layout doc (Phase 2). Validated via validateLayoutDoc when
+// type === 'home' — see validate.js. No objectName: home layouts are not
+// object-scoped (assignments use objectName: '' by convention, matching the
+// table's existing wildcard pattern for recordTypeId/audienceId).
+export const HomeLayoutDoc = z.object({
+  schemaVersion: z.literal(2).default(2),
+  type: z.literal('home'),
+  name: z.string().default('Home'),
+  tabIcon: z.string().default('fa-home'),
+  sections: z.array(WidgetSection).default([]),
+});

package/schemas/layouts/index.js

@@ -6,9 +6,11 @@ export * from './field.js';
 export * from './kanban.js';
 export * from './relatedList.js';
 export * from './action.js';
+export * from './widgetSection.js';
 export * from './section.js';
 export * from './compact.js';
 export * from './layoutDoc.js';
+export * from './homeLayoutDoc.js';
 export { validateLayoutDoc } from './validate.js';
 export {
   migrateLayoutSchema, migrateToLatest, MIGRATIONS, CURRENT_SCHEMA_VERSION,

package/schemas/layouts/section.js

@@ -9,6 +9,7 @@ import { JoinSpec } from './join.js';
 import { FormatType } from './format.js';
 import { KanbanConfigSpec } from './kanban.js';
 import { RelatedListSpec } from './relatedList.js';
+import { WidgetSection } from './widgetSection.js';
 
 const TableFieldSpec = z.object({
   field: z.string().min(1),
@@ -100,5 +101,5 @@ const TableKanbanSection = BaseSection.extend({
 // "delete TableEditor's legacy code path" work a schema-level forcing
 // function.
 export const SectionSpec = z.discriminatedUnion('type', [
-  ContentSection, TableSection, KanbanSection, TableKanbanSection,
+  ContentSection, TableSection, KanbanSection, TableKanbanSection, WidgetSection,
 ]);

package/schemas/layouts/validate.js

@@ -1,11 +1,17 @@
 import { LayoutDoc } from './layoutDoc.js';
 import { CompactLayoutDoc } from './compact.js';
+import { HomeLayoutDoc } from './homeLayoutDoc.js';
 
 // type: explicit override; falls back to doc.type. Compact docs (type:'compact')
-// validate against CompactLayoutDoc; everything else against LayoutDoc.
+// validate against CompactLayoutDoc; home docs (type:'home') against
+// HomeLayoutDoc; everything else against LayoutDoc.
 export function validateLayoutDoc(rawDoc, { type } = {}) {
   const docType = type || rawDoc?.type;
-  const schema = docType === 'compact' ? CompactLayoutDoc : LayoutDoc;
+  const schema = docType === 'compact'
+    ? CompactLayoutDoc
+    : docType === 'home'
+      ? HomeLayoutDoc
+      : LayoutDoc;
   const result = schema.safeParse(rawDoc);
   if (result.success) {
     return { valid: true, errors: [], data: result.data };

package/schemas/layouts/widgetSection.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+// Home-dashboard widget placement (Phase 2 'home' layout kind). Standalone
+// importable schema, also folded into SectionSpec's discriminated union
+// (section.js) as an open widget kind alongside content/table/kanban.
+export const WidgetSection = z.object({
+  id: z.string().min(1),
+  type: z.literal('widget'),
+  widgetId: z.string().min(1),
+  x: z.number().int().min(0).max(11),
+  y: z.number().int().min(0),
+  w: z.number().int().min(1).max(12),
+  h: z.number().int().min(1).max(8),
+  title: z.string().optional(),
+  settings: z.record(z.any()).default({}),
+});

package/services/directory.js

@@ -0,0 +1,124 @@
+export class DirectoryService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List the current user's directory favorites, hydrated with the
+   * favorited record and its channels.
+   *
+   * @returns {Promise<{favorites: Object[]}>}
+   */
+  async listFavorites() {
+    const result = await this.sdk._fetch('/directory/favorites', 'GET');
+    return result;
+  }
+
+  /**
+   * Add a person or company to directory favorites. Reactivates a
+   * soft-deleted favorite on unique conflict.
+   *
+   * @param {Object} params
+   * @param {string} params.objectType - 'person' or 'company' (required).
+   * @param {string} params.objectId - Id of the favorited record (required).
+   * @param {string[]} [params.channelIds] - Channel ids to pin for this favorite.
+   * @returns {Promise<Object>} The created (or reactivated) favorite.
+   */
+  async addFavorite({ objectType, objectId, channelIds }) {
+    this.sdk.validateParams(
+      { objectType, objectId, channelIds },
+      {
+        objectType: { type: 'string', required: true },
+        objectId: { type: 'string', required: true },
+        channelIds: { type: 'array', required: false },
+      },
+    );
+
+    const body = { objectType, objectId };
+    if (channelIds !== undefined) body.channelIds = channelIds;
+
+    const params = { body };
+
+    const result = await this.sdk._fetch('/directory/favorites', 'POST', params);
+    return result;
+  }
+
+  /**
+   * Update a directory favorite's pinned channels and/or sort order.
+   *
+   * @param {string} favoriteId - Id of the favorite to update (required).
+   * @param {Object} params
+   * @param {string[]} [params.channelIds]
+   * @param {number} [params.sortOrder]
+   * @returns {Promise<Object>} The updated favorite.
+   */
+  async updateFavorite(favoriteId, { channelIds, sortOrder } = {}) {
+    this.sdk.validateParams(
+      { favoriteId, channelIds, sortOrder },
+      {
+        favoriteId: { type: 'string', required: true },
+        channelIds: { type: 'array', required: false },
+        sortOrder: { type: 'number', required: false },
+      },
+    );
+
+    const body = {};
+    if (channelIds !== undefined) body.channelIds = channelIds;
+    if (sortOrder !== undefined) body.sortOrder = sortOrder;
+
+    const params = { body };
+
+    const result = await this.sdk._fetch(
+      `/directory/favorites/${favoriteId}`,
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Soft delete a directory favorite.
+   *
+   * @param {string} favoriteId - Id of the favorite to remove (required).
+   * @returns {Promise<Object>}
+   */
+  async removeFavorite(favoriteId) {
+    this.sdk.validateParams(
+      { favoriteId },
+      {
+        favoriteId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/directory/favorites/${favoriteId}`,
+      'DELETE',
+    );
+    return result;
+  }
+
+  /**
+   * Reorder directory favorites.
+   *
+   * @param {Object} params
+   * @param {string[]} params.order - Favorite ids in the desired order (required).
+   * @returns {Promise<{ok: boolean}>}
+   */
+  async reorderFavorites({ order }) {
+    this.sdk.validateParams(
+      { order },
+      {
+        order: { type: 'array', required: true },
+      },
+    );
+
+    const params = { body: { order } };
+
+    const result = await this.sdk._fetch(
+      '/directory/favorites/reorder',
+      'PUT',
+      params,
+    );
+    return result;
+  }
+}

package/services/inbox.js

@@ -0,0 +1,83 @@
+export class InboxService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * List unified inbox items merged across call/voicemail/fax/sms sources,
+   * sorted descending by timestamp.
+   *
+   * @param {Object} params
+   * @param {string|string[]} [params.types] - Source kinds to include
+   *   ('call','voicemail','fax','sms'). Pass an array or a comma-joined
+   *   string; omit to include all kinds.
+   * @param {number} [params.limit] - Max items to return.
+   * @param {string} [params.before] - UTC cursor 'YYYY-MM-DD HH:mm:ss';
+   *   only items strictly older than this are returned.
+   * @param {boolean} [params.unreadOnly] - When true, only unread items.
+   * @returns {Promise<{items: Object[], nextCursor: string|null}>}
+   */
+  async list({ types, limit, before, unreadOnly } = {}) {
+    this.sdk.validateParams(
+      { limit, before, unreadOnly },
+      {
+        limit: { type: 'number', required: false },
+        before: { type: 'string', required: false },
+        unreadOnly: { type: 'boolean', required: false },
+      },
+    );
+
+    if (
+      types !== undefined &&
+      typeof types !== 'string' &&
+      !Array.isArray(types)
+    ) {
+      throw new Error('types must be a string or an array of strings');
+    }
+
+    const query = {};
+    if (types !== undefined) {
+      query.types = Array.isArray(types) ? types.join(',') : types;
+    }
+    if (limit !== undefined) query.limit = limit;
+    if (before !== undefined) query.before = before;
+    if (unreadOnly !== undefined) query.unreadOnly = unreadOnly;
+
+    const params = { query };
+
+    const result = await this.sdk._fetch('/inbox', 'GET', params);
+    return result;
+  }
+
+  /**
+   * Fetch a paginated SMS/MMS thread for a phone number + counterparty pair.
+   *
+   * @param {Object} params
+   * @param {string} params.phoneNumberId - Our phone number id (required).
+   * @param {string} params.counterparty - Counterparty phone number (required).
+   * @param {number} [params.limit] - Max messages to return.
+   * @param {string} [params.before] - UTC cursor 'YYYY-MM-DD HH:mm:ss';
+   *   only messages strictly older than this are returned.
+   * @returns {Promise<{messages: Object[], nextCursor: string|null}>}
+   */
+  async smsThread({ phoneNumberId, counterparty, limit, before }) {
+    this.sdk.validateParams(
+      { phoneNumberId, counterparty, limit, before },
+      {
+        phoneNumberId: { type: 'string', required: true },
+        counterparty: { type: 'string', required: true },
+        limit: { type: 'number', required: false },
+        before: { type: 'string', required: false },
+      },
+    );
+
+    const query = { phoneNumberId, counterparty };
+    if (limit !== undefined) query.limit = limit;
+    if (before !== undefined) query.before = before;
+
+    const params = { query };
+
+    const result = await this.sdk._fetch('/inbox/smsThread', 'GET', params);
+    return result;
+  }
+}

package/services/layouts.js

@@ -97,21 +97,29 @@ export class LayoutsService {
     return result;
   }
 
-  async resolve({ object, kind, recordId, recordTypeId, asUser } = {}) {
+  // `object` is required for object-scoped kinds ('list'/'detail'/'compact')
+  // but omitted for kind:'home' (home layouts are not object-scoped).
+  async resolve({
+    object, kind, recordId, recordTypeId, asUser, preset,
+  } = {}) {
     this.sdk.validateParams(
-      { object, kind },
+      { object, kind, preset },
       {
-        object: { type: 'string', required: true },
+        object: { type: 'string', required: kind !== 'home' },
         kind: { type: 'string', required: true },
         recordId: { type: 'string', required: false },
         recordTypeId: { type: 'string', required: false },
         asUser: { type: 'string', required: false },
+        preset: { type: 'string', required: false },
       },
     );
 
-    const params = {
-      query: { object, kind, recordId, recordTypeId, asUser },
-    };
+    const query = { kind, recordId, recordTypeId, asUser, preset };
+    if (object) {
+      query.object = object;
+    }
+
+    const params = { query };
 
     const result = await this.sdk._fetch('/layouts/resolve', 'GET', params);
     return result;
@@ -174,9 +182,13 @@ export class LayoutAssignmentsService {
     this.sdk = sdk;
   }
 
+  // objectName defaults to '' for kind:'home' — matches the assignments
+  // table's existing "empty string = wildcard" convention for
+  // recordTypeId/audienceId; not a new pattern.
   async list({ objectName, kind } = {}) {
+    const resolvedObjectName = objectName ?? (kind === 'home' ? '' : objectName);
     this.sdk.validateParams(
-      { objectName, kind },
+      { objectName: resolvedObjectName, kind },
       {
         objectName: { type: 'string', required: true },
         kind: { type: 'string', required: true },
@@ -184,7 +196,7 @@ export class LayoutAssignmentsService {
     );
 
     const params = {
-      query: { objectName, kind },
+      query: { objectName: resolvedObjectName, kind },
     };
 
     const result = await this.sdk._fetch('/layouts/assignments', 'GET', params);
@@ -192,8 +204,9 @@ export class LayoutAssignmentsService {
   }
 
   async create({ objectName, kind, recordTypeId, audienceType, audienceId, layoutId, priority } = {}) {
+    const resolvedObjectName = objectName ?? (kind === 'home' ? '' : objectName);
     this.sdk.validateParams(
-      { objectName, kind, audienceType, layoutId },
+      { objectName: resolvedObjectName, kind, audienceType, layoutId },
       {
         objectName: { type: 'string', required: true },
         kind: { type: 'string', required: true },
@@ -203,7 +216,9 @@ export class LayoutAssignmentsService {
     );
 
     const params = {
-      body: { objectName, kind, recordTypeId, audienceType, audienceId, layoutId, priority },
+      body: {
+        objectName: resolvedObjectName, kind, recordTypeId, audienceType, audienceId, layoutId, priority,
+      },
     };
 
     const result = await this.sdk._fetch('/layouts/assignments', 'POST', params);