@unboundcx/sdk 4.6.2 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.6.2",
+  "version": "4.7.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/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);

package/services/permissions.js

@@ -486,6 +486,50 @@ export class PermissionsService {
     );
   }
 
+  /**
+   * Per-user, per-account JSON app state (UI state such as saved tab-sets).
+   * Distinct from settings: free-form JSON, not catalog-validated.
+   * @param {string|number} userId - User ID (required)
+   * @param {string} stateKey - State key, /^[a-zA-Z0-9_-]{1,64}$/ (required)
+   * @returns {Promise<Object>} { value } (value is null if unset)
+   */
+  async getUserAppState(userId, stateKey) {
+    userId = String(userId);
+    stateKey = String(stateKey);
+    this.sdk.validateParams(
+      { userId, stateKey },
+      {
+        userId: { type: 'string', required: true },
+        stateKey: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch(
+      `/permissions/users/${userId}/app-state/${stateKey}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Upsert one app-state value for a user (JSON-serializable, ≤256KB serialized).
+   * @returns {Promise<Object>} { userId, stateKey, value, updatedAt }
+   */
+  async setUserAppState(userId, stateKey, value) {
+    userId = String(userId);
+    stateKey = String(stateKey);
+    this.sdk.validateParams(
+      { userId, stateKey },
+      {
+        userId: { type: 'string', required: true },
+        stateKey: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch(
+      `/permissions/users/${userId}/app-state/${stateKey}`,
+      'PUT',
+      { body: { value } },
+    );
+  }
+
   // ---- 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