@unboundcx/sdk 4.1.2 → 4.2.0

package/README.md

@@ -176,6 +176,72 @@ 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.
+
+**UOQL form** — pass a `uoql` string instead of `object`/`filter`/`fields`/
+`recordTypeId` (mutually exclusive; the SDK throws synchronously if both, or
+neither, are given). The server parses and classifies the query for you:
+
+```javascript
+// Simple single-object query with a flat WHERE -> classifies FINE, same
+// row-level 'enter'/'change'/'leave' events as the object/filter form above.
+const handle = await api.objects.liveQuery({
+  socket,
+  uoql: "SELECT id, name, status FROM contacts WHERE companyId = 'company-123'",
+  onEvent: (frame) => {},
+});
+
+// Relationship paths / aggregates -> classifies COARSE: you only get
+// debounced 'refresh' hints (no row-level frames), so re-run the query
+// yourself each time onEvent fires with frame.type === 'refresh'.
+// (UOQL expresses joins as dot-notation relationship paths, not JOIN syntax.)
+const relatedUoql =
+  "SELECT name, companyId.name FROM contacts WHERE companyId.industry = 'tech'";
+const relatedHandle = await api.objects.liveQuery({
+  socket,
+  uoql: relatedUoql,
+  onEvent: async (frame) => {
+    if (frame.type === 'refresh' || frame.type === 'resync') {
+      const results = await api.objects.queryV2({ query: relatedUoql });
+    }
+  },
+});
+
+relatedHandle.unsubscribe();
+```
+
+Resubscribe-on-reconnect re-sends the same `uoql` string verbatim, so the
+server re-classifies it fresh each time (mode can't drift out from under a
+long-lived handle).
+
 #### 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.2.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",
@@ -42,6 +42,8 @@
     "transports/**/*.js",
     "types/**/*.d.ts",
     "proto/**/*.proto",
+    "schemas/**/*.js",
+    "schemas/**/*.md",
     "README.md",
     "LICENSE"
   ],
@@ -55,19 +57,28 @@
     },
     "./services/*": {
       "import": "./services/*.js"
+    },
+    "./schemas/layouts": {
+      "import": "./schemas/layouts/index.js"
+    },
+    "./schemas/*": {
+      "import": "./schemas/*.js"
     }
   },
   "scripts": {
     "build": "echo 'Build complete - ESM modules ready'",
     "test": "node --test 'test/*.test.js'",
     "lint": "echo 'Linting would run here'",
+    "docs:layouts": "node scripts/generate-layout-schema-docs.js",
     "prepublishOnly": "npm run build"
   },
-  "dependencies": {},
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
   "optionalDependencies": {
-    "mime-types": "^2.1.35",
     "@grpc/grpc-js": "^1.14.1",
-    "@grpc/proto-loader": "^0.7.15"
+    "@grpc/proto-loader": "^0.7.15",
+    "mime-types": "^2.1.35"
   },
   "peerDependencies": {
     "socket.io-client": "^4.0.0"
@@ -77,7 +88,9 @@
       "optional": true
     }
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "zod-to-json-schema": "^3.23.0"
+  },
   "browserslist": [
     "defaults",
     "not IE 11",