@unboundcx/sdk 4.4.0 → 4.5.0

package/README.md

@@ -206,6 +206,42 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.4.0",
+  "version": "4.5.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",
@@ -76,9 +76,9 @@
     "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"

package/schemas/layouts/primitives.js

@@ -26,6 +26,12 @@ export const OrderBySpec = z.object({
   direction: z.enum(['asc', 'desc']).default('asc'),
 });
 
+// Multi-column ordering (2026-08-15): a single {field, direction} object
+// (every stored layout to date) OR an ordered array of them. Consumers
+// normalize via a "wrap in array if not one" step; the builder writes the
+// array shape going forward.
+export const OrderByListSpec = z.union([OrderBySpec, z.array(OrderBySpec)]);
+
 export const HeaderSpec = z.object({
   value: z.string().default(''),
   collapsedValue: z.string().optional(),

package/schemas/layouts/section.js

@@ -1,5 +1,9 @@
 import { z } from 'zod';
-import { HeaderSpec, ConditionSpec, OrderBySpec } from './primitives.js';
+import {
+  HeaderSpec,
+  ConditionSpec,
+  OrderByListSpec,
+} from './primitives.js';
 import { FieldSpec } from './field.js';
 import { JoinSpec } from './join.js';
 import { FormatType } from './format.js';
@@ -36,7 +40,7 @@ const TableSpec = z.object({
     hideOnCreate: z.boolean().default(false),
     cardClick: z.enum(['tab', 'modal']).default('tab'),
   }).default({}),
-  orderBy: OrderBySpec.optional(),
+  orderBy: OrderByListSpec.optional(),
   additionalWhere: z.record(z.string()).optional(),
   hideOnCreate: z.boolean().default(false),
 });

package/services/liveQuery.js

@@ -117,15 +117,20 @@ class LiveQueryHandle {
     filter,
     fields,
     recordTypeId,
+    uoql,
     onEvent,
     onStateChange,
   }) {
     this.manager = manager;
     this.socket = socket;
-    this.object = object;
+    // Internal bookkeeping/log labels need an object-name-shaped string even
+    // in uoql mode - use the literal 'uoql' there (no single object name
+    // exists yet, that's resolved server-side by analyze()).
+    this.object = uoql !== undefined ? 'uoql' : object;
     this.filter = filter;
     this.fields = fields;
     this.recordTypeId = recordTypeId;
+    this.uoql = uoql;
     this.onEvent = onEvent;
     this.onStateChange = onStateChange;
 
@@ -136,7 +141,10 @@ class LiveQueryHandle {
   }
 
   async _subscribe() {
-    const payload = { objectName: this.object, filter: this.filter, fields: this.fields };
+    const payload =
+      this.uoql !== undefined
+        ? { uoql: this.uoql }
+        : { objectName: this.object, filter: this.filter, fields: this.fields };
     if (this.recordTypeId !== undefined) payload.recordTypeId = this.recordTypeId;
 
     const ack = await new Promise((resolve, reject) => {
@@ -249,6 +257,11 @@ class LiveQueryHandle {
  *   this account; falls back to `sdk.socket` if the sdk instance holds one.
  * - object, filter, fields, recordTypeId: subscribe-time query, same shape
  *   as `sdk.objects.query`.
+ * - uoql: subscribe-time query as a UOQL string instead - mutually exclusive
+ *   with object/filter/fields/recordTypeId (throws synchronously if both, or
+ *   neither, are given). Sent to the server as `{ uoql }`; the server runs
+ *   uoql analyze() to resolve it to a fine or coarse subscription. Also
+ *   re-sent verbatim on reconnect resubscribe.
  * - onEvent(frame): called for every 'enter'|'change'|'leave'|'refresh'|
  *   'resync'|'revoked' frame (resync frames are also synthesized locally on
  *   seq gaps and on reconnect).
@@ -257,7 +270,7 @@ class LiveQueryHandle {
  * Resolves to { subscriptionId, mode, unsubscribe() }.
  */
 export async function liveQuery(sdk, args = {}) {
-  const { socket: providedSocket, object, filter, fields, recordTypeId, onEvent, onStateChange } = args;
+  const { socket: providedSocket, object, filter, fields, recordTypeId, uoql, onEvent, onStateChange } = args;
 
   const socket = providedSocket || sdk.socket;
   if (!socket || typeof socket.emit !== 'function' || typeof socket.on !== 'function') {
@@ -267,8 +280,15 @@ export async function liveQuery(sdk, args = {}) {
         'deviation from the locked liveQuery contract, see plan Phase 3',
     );
   }
-  if (!object) {
-    throw new Error('liveQuery :: init :: object is required');
+
+  const hasObjectForm = object !== undefined || filter !== undefined || fields !== undefined || recordTypeId !== undefined;
+  if (uoql !== undefined && hasObjectForm) {
+    throw new Error(
+      'liveQuery :: init :: uoql is mutually exclusive with object/filter/fields/recordTypeId',
+    );
+  }
+  if (uoql === undefined && !object) {
+    throw new Error('liveQuery :: init :: either uoql or object is required');
   }
 
   const manager = getSocketManager(socket);
@@ -279,6 +299,7 @@ export async function liveQuery(sdk, args = {}) {
     filter,
     fields,
     recordTypeId,
+    uoql,
     onEvent,
     onStateChange,
   });

package/services/objects.js

@@ -30,6 +30,8 @@ export class ObjectsService {
    * re-subscribe, revoked teardown).
    *
    * sdk.objects.liveQuery({ socket, object, filter, fields, recordTypeId, onEvent, onStateChange })
+   * sdk.objects.liveQuery({ socket, uoql, onEvent, onStateChange }) // uoql is mutually
+   *   exclusive with object/filter/fields/recordTypeId
    * -> Promise<{ subscriptionId, mode, unsubscribe() }>
    */
   liveQuery(args) {