@unboundcx/sdk 4.1.3 → 4.2.0

package/schemas/layouts/migrations/normalizeJoin.js

@@ -0,0 +1,44 @@
+// Pure fn, no zod import — this runs before validation inside migrateV1toV2.
+// Mirrors join.js's normalizeJoinSpec() (kept as a standalone duplicate here,
+// not a re-export, so the migrations/ tier stays zod-free per the phase's
+// "migrations run on plain objects" design — see SPEC-PHASE-1.md §2 A14-A18).
+//
+// legacyKind: 'table' | 'component' | 'kanbanChildRecords' — all three raw
+// join shapes observed in the legacy layout builder collapse onto one
+// canonical {childField, parentField} shape:
+//   - table / component: {column, value: "{{parentField}}"}
+//   - kanban child-records: {childField, parentField} (already un-templated)
+//
+// DEVIATION (Phase 5, SPEC-PHASE-5.md §2.1 step 3): returns
+// {relationship, skipped} instead of a bare relationship object. `skipped`
+// is true when `column` is missing/empty or `value` isn't a clean
+// single-token "{{field}}" template — the spec's explicit "leave untouched"
+// carve-out for joins that can't be synthesized 1:1. Both cases appear in
+// real stored data (app1-api/src/services/layouts/examples.json:865,921 —
+// two "Related Contacts"/"Deal Team" tables with `join.column === ""`), not
+// just the hypothetical concatenated-template case the spec called out —
+// an empty FK column can no more produce a valid JoinSpec.childField
+// (min-length 1) than a non-trivial template can, so both are treated as
+// the same carve-out.
+const MUSTACHE_RE = /^\{\{\s*([\w.]+)\s*\}\}$/;
+
+export function normalizeJoin(raw, legacyKind) {
+  if (!raw) return { relationship: undefined, skipped: false };
+
+  // Already canonical (or kanban child-records, which was never templated).
+  if (legacyKind === 'kanbanChildRecords' || (raw.childField && !raw.column)) {
+    if (!raw.childField) return { relationship: undefined, skipped: true };
+    return { relationship: { childField: raw.childField, parentField: raw.parentField || 'id' }, skipped: false };
+  }
+
+  if (!raw.column || typeof raw.value !== 'string') {
+    return { relationship: undefined, skipped: true };
+  }
+
+  const match = raw.value.match(MUSTACHE_RE);
+  if (!match) {
+    return { relationship: undefined, skipped: true };
+  }
+
+  return { relationship: { childField: raw.column, parentField: match[1] }, skipped: false };
+}

package/schemas/layouts/migrations/normalizeKanban.js

@@ -0,0 +1,54 @@
+import { normalizeJoin } from './normalizeJoin.js';
+
+// Pure fn, no zod import. Tolerates/normalizes per-mode kanban keys — the 3
+// kanban modes (simple/related/child-records) are described inconsistently
+// across TableEditor.svelte/KanbanEditor.svelte/ComponentEditor.svelte
+// (maps.md §1.7); this fills in the structural keys KanbanConfigSpec
+// (schemas/layouts/kanban.js) always expects (mode, summaries[], actions{})
+// without dropping or rewriting anything mode-specific — additive only.
+//
+// `changes` (optional, Phase 5 addition) collects human-readable entries for
+// the migration-preview tool / backfill-sweep log, same array threaded
+// through migrateV1toV2.js's other normalizers.
+export function normalizeKanban(raw, changes, sectionId) {
+  if (!raw) return raw;
+
+  const mode = raw.mode
+    || (raw.childObject ? 'child-records' : (raw.configObject ? 'related' : 'simple'));
+  if (!raw.mode && changes) {
+    changes.push(`section "${sectionId}" kanban: mode inferred as "${mode}" (not explicitly set)`);
+  }
+
+  const summaries = Array.isArray(raw.summaries) ? raw.summaries : [];
+  const actions = raw.actions && typeof raw.actions === 'object' ? raw.actions : {};
+
+  const next = {
+    ...raw,
+    mode,
+    summaries,
+    actions: {
+      create: actions.create ?? false,
+      edit: actions.edit ?? true,
+      delete: actions.delete ?? false,
+      cardClick: actions.cardClick || 'modal',
+    },
+  };
+
+  // child-records mode's `join` is KanbanChildRecords's own JoinSpec-typed
+  // field (schemas/layouts/kanban.js) — canonical-only, same as
+  // TableSpec.join. Legacy child-records joins were never templated
+  // (kanbanChildRecords fast-path in normalizeJoin), so this only ever
+  // fills a missing default parentField; kept here (rather than assumed
+  // already-clean) because migrateV1toV2.js can't reach into mode-specific
+  // kanban keys itself without duplicating the mode-inference above.
+  if (mode === 'child-records' && raw.join) {
+    const { relationship, skipped } = normalizeJoin(raw.join, 'kanbanChildRecords');
+    if (relationship) {
+      next.join = relationship;
+    } else if (skipped && changes) {
+      changes.push(`section "${sectionId}" kanban: child-records join left as legacy shape (missing childField)`);
+    }
+  }
+
+  return next;
+}

package/schemas/layouts/migrations/promoteRelatedLists.js

@@ -0,0 +1,67 @@
+// Pure fn, no zod import. SPEC-PHASE-5.md §2.1 step 5: promotes qualifying
+// TableSpec entries (already join-normalized by migrateV1toV2.js) to
+// RelatedListSpec, additive alongside `tables[]` — NOT a replacement.
+// `tables[]` stays fully intact so the section keeps validating and nothing
+// is lost if a table doesn't qualify; `relatedLists[]` is a new, parallel
+// key (schemas/layouts/section.js) for the Phase 4 engine's related-list
+// component to read instead of re-deriving the same shape from `tables[]`
+// itself. See section.js's comment at TableSection/TableKanbanSection for
+// why this resolves relatedList.js's "Open Decision #5" as additive rather
+// than folding tables[] away.
+//
+// Promotion criteria (ALL required, per spec):
+//   a. table.object differs from the layout's own objectName — a table
+//      entry matching the primary object is a plain table, not a related
+//      list of itself.
+//   b. table.join was normalized to a canonical relationship (i.e. NOT
+//      dropped by normalizeJoin's "leave untouched" carve-out).
+//   c. table.fields is non-empty — RelatedListSpec.columns.inline requires
+//      at least one column (min(1)); an empty fields[] can't produce a
+//      valid columns block. Not explicitly named in the spec's 3 criteria,
+//      but required by RelatedListSpec's actual zod shape.
+// table.hideRowNumber / `table.header`-style overrides are NOT a gate (per
+// spec: "keep columns: {inline: [...]} verbatim rather than failing the
+// promotion") — this function always emits `columns: {inline: table.fields}`
+// unconditionally, so criterion (c) is the only fields-related check.
+export function promoteRelatedLists(section, objectName, changes) {
+  const relatedLists = [];
+  const createActions = [];
+  const promotedIds = new Set();
+
+  for (const table of section.tables || []) {
+    if (table.object === objectName) continue;
+    if (!table.join) continue;
+    if (!table.fields || table.fields.length === 0) continue;
+
+    relatedLists.push({
+      id: table.id,
+      object: table.object,
+      relationship: table.join,
+      columns: { inline: table.fields },
+      rowActions: {
+        open: 'modal',
+        quickEdit: table.actions?.edit ? 'modal' : undefined,
+        delete: !!table.actions?.delete,
+        custom: [],
+      },
+      defaultSort: table.orderBy,
+      filters: table.additionalWhere,
+    });
+    promotedIds.add(table.id);
+    changes.push(
+      `section "${section.id}" table "${table.id}": promoted to RelatedListSpec (object="${table.object}")`,
+    );
+
+    if (table.actions?.create) {
+      createActions.push({
+        id: `${table.id}-related-create`,
+        type: 'create',
+        target: table.object,
+        mode: 'modal',
+        placement: 'section',
+      });
+    }
+  }
+
+  return { relatedLists, createActions, promotedIds };
+}

package/schemas/layouts/primitives.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+// Not resolved here — just shape-checked. Resolution ({{field}} substitution
+// against a record) stays a client/renderer concern (existing replaceVariables()
+// in app1-client/src/utils/index.js), unchanged in this phase.
+export const MustacheTemplate = z.string().min(1);
+
+// Matches Section.svelte / TableEditor.svelte conditional-visibility operators
+// (maps.md §1.5) — verified against Row.svelte:79-116's operator switch.
+export const ConditionOperator = z.enum([
+  'eq', 'neq', 'contains', 'startsWith', 'endsWith',
+  'gt', 'gte', 'lt', 'lte', 'isNull', 'isNotNull',
+]);
+
+export const ConditionSpec = z.object({
+  field: z.string().min(1),
+  operator: ConditionOperator.default('eq'),
+  value: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+}).refine(
+  (v) => ['isNull', 'isNotNull'].includes(v.operator) || v.value !== undefined,
+  { message: 'value is required unless operator is isNull/isNotNull', path: ['value'] },
+);
+
+export const OrderBySpec = z.object({
+  field: z.string().min(1),
+  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(),
+  hidden: z.boolean().default(false),
+  size: z.enum(['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl']).optional(),
+  weight: z.enum(['thin', 'light', 'normal', 'medium', 'semibold', 'bold', 'black']).optional(),
+  icon: z.string().optional(),
+  level: z.enum(['1', '2', '3', '4', '5', '6']).optional(),
+  collapsible: z.boolean().optional(),
+});

package/schemas/layouts/relatedList.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { JoinSpec } from './join.js';
+import { OrderBySpec } from './primitives.js';
+import { FormatType } from './format.js';
+
+// New primitive, per V2-PLAN's exact definition. Wired into
+// TableSection/TableKanbanSection as `relatedLists[]` (section.js) —
+// additive alongside `tables[]`, not a replacement (SectionSpec.tables[]
+// stays on the legacy-derived TableSpec/JoinSpec shape; RelatedListSpec is a
+// parallel, promoted-subset view). Resolves Open Decision #5 (Phase 5,
+// SPEC-PHASE-5.md §2.1 step 5, migrations/promoteRelatedLists.js) as
+// additive: folding tables[] away entirely would break the old renderer's
+// byte-identical read contract during the v1/v2 soak window.
+const RelatedListInlineColumn = z.object({
+  field: z.string().min(1),
+  display: z.string().optional(),
+  formatType: FormatType.optional(),
+  format: z.string().optional(),
+});
+
+const RelatedListColumnsSpec = z.union([
+  z.object({ compactLayoutRef: z.string().min(1) }),
+  z.object({ inline: z.array(RelatedListInlineColumn).min(1) }),
+]);
+
+const RowActionCustomSpec = z.object({
+  label: z.string().min(1),
+  icon: z.string().optional(),
+  action: z.enum(['open', 'edit', 'delete', 'custom']),
+  target: z.string().optional(),   // custom: workflow/route id resolved by the Phase 4 action registry
+});
+
+export const RelatedListSpec = z.object({
+  id: z.string().min(1),
+  object: z.string().min(1),
+  relationship: JoinSpec,           // ONE FK declaration — replaces the 3 join semantics for this primitive
+  columns: RelatedListColumnsSpec,
+  rowActions: z.object({
+    open: z.enum(['tab', 'modal', 'peek']).default('modal'),
+    quickEdit: z.enum(['inline', 'modal']).optional(), // 'modal' = opens this object's compact layout
+    delete: z.boolean().default(false),
+    custom: z.array(RowActionCustomSpec).default([]),
+  }).default({ open: 'modal', delete: false, custom: [] }),
+  emptyState: z.object({ message: z.string().optional(), icon: z.string().optional() }).optional(),
+  defaultSort: OrderBySpec.optional(),
+  filters: z.record(z.string()).optional(),   // "<operator>::<term>" DSL — same as buildObjectQuery.js
+  pageSize: z.number().int().positive().max(200).default(25),
+});

package/schemas/layouts/section.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import {
+  HeaderSpec,
+  ConditionSpec,
+  OrderByListSpec,
+} from './primitives.js';
+import { FieldSpec } from './field.js';
+import { JoinSpec } from './join.js';
+import { FormatType } from './format.js';
+import { KanbanConfigSpec } from './kanban.js';
+import { RelatedListSpec } from './relatedList.js';
+
+const TableFieldSpec = z.object({
+  field: z.string().min(1),
+  display: z.string().default(''),
+  hidden: z.boolean().default(false),
+  sortable: z.boolean().default(true),
+  type: z.enum(['link']).optional(),
+  link: z.string().optional(),
+  linkField: z.string().optional(),
+  linkObject: z.string().optional(),
+  formatType: FormatType.optional(),
+  format: z.string().optional(),
+  relatedKey: z.string().optional(),
+  relatedObject: z.string().optional(),
+}).refine((v) => v.type !== 'link' || (v.link && v.linkField && v.linkObject), {
+  message: 'type:"link" requires link, linkField, and linkObject',
+});
+
+const TableSpec = z.object({
+  id: z.string().min(1),
+  object: z.string().min(1),
+  join: JoinSpec.optional(),   // absent = top-level list table (no parent record)
+  fields: z.array(TableFieldSpec).default([]),
+  header: HeaderSpec.partial().optional(),
+  actions: z.object({
+    edit: z.boolean().default(true),
+    create: z.boolean().default(false),
+    delete: z.boolean().default(false),
+    hideOnCreate: z.boolean().default(false),
+    cardClick: z.enum(['tab', 'modal']).default('tab'),
+  }).default({}),
+  orderBy: OrderByListSpec.optional(),
+  additionalWhere: z.record(z.string()).optional(),
+  hideOnCreate: z.boolean().default(false),
+});
+
+const RowSpec = z.object({
+  id: z.string().min(1),
+  columns: z.array(FieldSpec),
+});
+
+const BaseSection = z.object({
+  id: z.string().min(1),
+  header: HeaderSpec.default({}),
+  editable: z.boolean().default(true),
+  hideOnCreate: z.boolean().default(false),
+  autoCollapse: z.boolean().default(false),
+  showCollapse: z.boolean().default(false),
+  conditions: ConditionSpec.optional(),
+});
+
+const ContentSection = BaseSection.extend({
+  type: z.literal('content'),
+  rows: z.array(RowSpec).default([]),
+});
+
+// `relatedLists` (Phase 5 addition, SPEC-PHASE-5.md §2.1 step 5): resolves
+// relatedList.js's "Open Decision #5" as ADDITIVE, not a fold — `tables[]`
+// stays the full, unmodified source of truth (old renderer + Phase 4's
+// plain-table view both read it); `relatedLists[]` is a parallel,
+// promoted-subset view for Phase 4's dedicated related-list component,
+// populated by migrations/promoteRelatedLists.js for qualifying entries
+// only. Never required, defaults empty.
+const TableSection = BaseSection.extend({
+  type: z.literal('table'),
+  tableLayout: z.enum(['full-width', 'two-columns']).default('full-width'),
+  tables: z.array(TableSpec).min(1),
+  relatedLists: z.array(RelatedListSpec).default([]),
+});
+
+const KanbanSection = BaseSection.extend({
+  type: z.literal('kanban'),
+  kanban: KanbanConfigSpec,
+});
+
+const TableKanbanSection = BaseSection.extend({
+  type: z.literal('table-kanban'),
+  defaultView: z.enum(['table', 'kanban']).default('table'),
+  tableLayout: z.enum(['full-width', 'two-columns']).default('full-width'),
+  tables: z.array(TableSpec).min(1),
+  kanban: KanbanConfigSpec,
+  relatedLists: z.array(RelatedListSpec).default([]),
+});
+
+// Note: this schema has no branch for legacy single-table
+// section.object/fields/join/actions (no tables[]) — those docs must pass
+// through migrateV1toV2 (which auto-wraps them into tables:[{...}], per
+// V2-PLAN §6) before they'll validate. This is deliberate: it gives Phase 3's
+// "delete TableEditor's legacy code path" work a schema-level forcing
+// function.
+export const SectionSpec = z.discriminatedUnion('type', [
+  ContentSection, TableSection, KanbanSection, TableKanbanSection,
+]);

package/schemas/layouts/selectDynamic.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { MustacheTemplate } from './primitives.js';
+
+// Canonicalizes away the `url` string / `queryConfig` object duplication and
+// the `response` vs `responseMapping` dual mapping (maps.md §1.9). Design
+// decision: v2 canonical docs store `queryConfig` only — `url` is never
+// authored or persisted; the client's shared selectDynamic resolver (Phase 4,
+// src/lib/layout-engine/) regenerates the request URL from `queryConfig` at
+// render time, replacing the 3x-duplicated buildSelectDynamicUrl logic
+// (Column.svelte:196-245, ModernField.svelte:222-269, WorkflowField.svelte:174-214).
+// This is a schema-level decision Phase 4 must honor; flagged in Risks.
+export const ResponseMappingSpec = z.object({
+  name: z.string().min(1),
+  value: z.string().min(1),
+});
+
+export const SelectDynamicQueryConfig = z.object({
+  object: z.string().min(1),
+  select: z.array(z.string()).default(['id', 'name']),
+  searchField: z.string().default('name'),
+  searchOperator: z.enum(['contains', 'startsWith', 'endsWith', 'eq']).default('contains'),
+  valueField: z.string().default('id'),          // canonical name for legacy valueColumn
+  displayTemplate: MustacheTemplate.default('{{name}}'),
+  limit: z.number().int().positive().max(200).default(25),
+  additionalWhere: z.record(z.string()).optional(),  // "<operator>::<term>" DSL, same as buildObjectQuery.js
+  orderByField: z.string().optional(),
+  orderByDirection: z.enum(['asc', 'desc']).default('asc'),
+});
+
+export const SelectDynamicSpec = z.object({
+  queryConfig: SelectDynamicQueryConfig,
+  responseMapping: ResponseMappingSpec.default({ name: 'name', value: 'id' }),
+  multiple: z.boolean().default(false),
+  clearable: z.boolean().default(true),
+  searchable: z.boolean().default(true),
+  preloadOptions: z.boolean().default(false),
+  initialSearchQuery: z.string().optional(),
+  initialLoadLimit: z.number().int().positive().optional(),
+  fetchOptions: z.object({ credentials: z.string().optional() }).optional(),
+});

package/schemas/layouts/validate.js

@@ -0,0 +1,18 @@
+import { LayoutDoc } from './layoutDoc.js';
+import { CompactLayoutDoc } from './compact.js';
+
+// type: explicit override; falls back to doc.type. Compact docs (type:'compact')
+// validate against CompactLayoutDoc; everything else against LayoutDoc.
+export function validateLayoutDoc(rawDoc, { type } = {}) {
+  const docType = type || rawDoc?.type;
+  const schema = docType === 'compact' ? CompactLayoutDoc : LayoutDoc;
+  const result = schema.safeParse(rawDoc);
+  if (result.success) {
+    return { valid: true, errors: [], data: result.data };
+  }
+  return {
+    valid: false,
+    errors: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
+    data: null,
+  };
+}

package/services/layouts.js

@@ -1,6 +1,10 @@
+import * as layoutSchemas from '../schemas/layouts/index.js';
+
 export class LayoutsService {
   constructor(sdk) {
     this.sdk = sdk;
+    this.schema = layoutSchemas;   // sdk.layouts.schema.{LayoutDoc, validateLayoutDoc, migrateLayoutSchema, ...}
+    this.assignments = new LayoutAssignmentsService(sdk);   // sdk.layouts.assignments.{list,create,update,delete}
   }
 
   async get(objectName, id, query = {}) {
@@ -86,10 +90,147 @@ export class LayoutsService {
     };
 
     const result = await this.sdk._fetch(
-      '/layouts/dynamic-select-search',
+      '/layouts/selectDynamic/search',
       'GET',
       params,
     );
     return result;
   }
+
+  async resolve({ object, kind, recordId, recordTypeId, asUser } = {}) {
+    this.sdk.validateParams(
+      { object, kind },
+      {
+        object: { type: 'string', required: true },
+        kind: { type: 'string', required: true },
+        recordId: { type: 'string', required: false },
+        recordTypeId: { type: 'string', required: false },
+        asUser: { type: 'string', required: false },
+      },
+    );
+
+    const params = {
+      query: { object, kind, recordId, recordTypeId, asUser },
+    };
+
+    const result = await this.sdk._fetch('/layouts/resolve', 'GET', params);
+    return result;
+  }
+
+  async getVersions(layoutId) {
+    this.sdk.validateParams(
+      { layoutId },
+      { layoutId: { type: 'string', required: true } },
+    );
+
+    const result = await this.sdk._fetch(`/layouts/${layoutId}/versions`, 'GET', {});
+    return result;
+  }
+
+  async getForEdit(layoutId) {
+    this.sdk.validateParams(
+      { layoutId },
+      { layoutId: { type: 'string', required: true } },
+    );
+
+    const result = await this.sdk._fetch(`/layouts/${layoutId}/edit`, 'GET', {});
+    return result;
+  }
+
+  async publish(layoutId, { changeNote } = {}) {
+    this.sdk.validateParams(
+      { layoutId },
+      { layoutId: { type: 'string', required: true } },
+    );
+
+    const params = {
+      body: { changeNote },
+    };
+
+    const result = await this.sdk._fetch(`/layouts/${layoutId}/publish`, 'POST', params);
+    return result;
+  }
+
+  async rollback(layoutId, version) {
+    this.sdk.validateParams(
+      { layoutId, version },
+      {
+        layoutId: { type: 'string', required: true },
+        version: { type: 'number', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/layouts/${layoutId}/versions/${version}/rollback`,
+      'POST',
+      {},
+    );
+    return result;
+  }
+}
+
+export class LayoutAssignmentsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  async list({ objectName, kind } = {}) {
+    this.sdk.validateParams(
+      { objectName, kind },
+      {
+        objectName: { type: 'string', required: true },
+        kind: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      query: { objectName, kind },
+    };
+
+    const result = await this.sdk._fetch('/layouts/assignments', 'GET', params);
+    return result;
+  }
+
+  async create({ objectName, kind, recordTypeId, audienceType, audienceId, layoutId, priority } = {}) {
+    this.sdk.validateParams(
+      { objectName, kind, audienceType, layoutId },
+      {
+        objectName: { type: 'string', required: true },
+        kind: { type: 'string', required: true },
+        audienceType: { type: 'string', required: true },
+        layoutId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { objectName, kind, recordTypeId, audienceType, audienceId, layoutId, priority },
+    };
+
+    const result = await this.sdk._fetch('/layouts/assignments', 'POST', params);
+    return result;
+  }
+
+  async update(id, updates) {
+    this.sdk.validateParams(
+      { id },
+      { id: { type: 'string', required: true } },
+    );
+
+    const params = {
+      body: updates,
+    };
+
+    const result = await this.sdk._fetch(`/layouts/assignments/${id}`, 'PUT', params);
+    return result;
+  }
+
+  async delete(id) {
+    this.sdk.validateParams(
+      { id },
+      { id: { type: 'string', required: true } },
+    );
+
+    const result = await this.sdk._fetch(`/layouts/assignments/${id}`, 'DELETE', {});
+    return result;
+  }
 }

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) {