@centrali-io/centrali-sdk 5.5.1 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "5.5.1",
+  "version": "6.1.0",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,8 @@
   "scripts": {
     "sync:query-types": "node scripts/sync-query-types.mjs",
     "prebuild": "npm run sync:query-types",
-    "build": "tsc --project tsconfig.json",
+    "build": "tsup",
+    "test": "jest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [],
@@ -24,10 +25,16 @@
     "qs": "^6.14.2"
   },
   "devDependencies": {
+    "@centrali/query": "file:../../backend/shared/query",
     "@types/eventsource": "^1.1.15",
+    "@types/jest": "^29.5.12",
     "@types/q": "^1.5.8",
     "@types/qs": "^6.14.0",
-    "typescript": "5.9.3"
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.3.5",
+    "typescript": "5.9.3",
+    "zod": "^3.24.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/query-types.ts

@@ -34,6 +34,7 @@ export type QueryDefinition = {
   page?: PageClause;
   select?: SelectClause;
   include?: IncludeClause[];
+  joins?: JoinClause[];
 };
 
 export type SavedQueryDefinition = {
@@ -299,10 +300,16 @@ export type SortClause = {
  * Two pagination modes. Per contract §6 they are mutually exclusive — `cursor`
  * is forbidden in offset mode and `offset` is forbidden in cursor mode so a
  * caller cannot construct an ambiguous request.
+ *
+ * `withTotal` is opt-in (default false). When omitted, executors skip the
+ * accompanying `count(*)` query and return `meta.total` undefined; `hasMore`
+ * is still accurate (executors fetch `limit + 1` rows). Set `withTotal: true`
+ * when the caller actually renders a total — e.g. page-1 of a numbered
+ * paginator. CEN-1259.
  */
 export type PageClause =
-  | { limit: number; offset?: number; cursor?: never }
-  | { limit: number; cursor?: string; offset?: never };
+  | { limit: number; offset?: number; cursor?: never; withTotal?: boolean }
+  | { limit: number; cursor?: string; offset?: never; withTotal?: boolean };
 
 /**
  * Records Phase 1 page defaults (contract §6).
@@ -320,12 +327,81 @@ export type SelectClause = {
 };
 
 /**
- * Phase 1 reserves the shape but rejects execution with `unsupported_clause`.
+ * Recursive direct-relationship expansion. The executor walks each clause
+ * against reference-typed properties on the parent structure and substitutes
+ * the related row(s) inline under the relation name. Nested `include`
+ * children traverse the next hop on the just-fetched rows. Cycle detection
+ * and depth limits live in the executor (CEN-1192).
+ *
+ * `where` and `select` (CEN-1219) operate on the **target** structure's
+ * namespace — fields are resolved against the included relation's own
+ * properties (e.g. `data.active` on the related `customer`, not the parent's
+ * `data.customer.data.active`). The executor narrows the batched fetch with
+ * `where` and trims the attached row to `select.fields` post-fetch. Nested
+ * `include` children inherit nothing from this clause's `select` — they are
+ * always fetched in full and can carry their own `select`.
  */
 export type IncludeClause = {
   relation: string;
+  where?: WhereExpression;
+  select?: SelectClause;
+  include?: IncludeClause[];
+};
+
+// ---------------------------------------------------------------------------
+// JoinClause (contract §7.5 — added 6.0, CEN-1058)
+//
+// Multi-join saved queries. Each entry compiles to one Knex `.join` /
+// `.leftJoin` / `.rightJoin` / `.fullOuterJoin` against a per-side
+// tenancy-filtered subquery (`SELECT * FROM records WHERE
+// workspaceSlug=? AND recordSlug=? AND ...`). Equi-join predicates
+// remain in the ON clause; tenancy lives in the FROM subquery so
+// outer-join row preservation works correctly across all four join
+// types — see PR 1b commit `dc4fb4fcb` for the SQL-correctness analysis.
+//
+// Identifier slots (`foreignSlug`, `localField`, `foreignField`,
+// `alias`, `joinType`) are literal-only — `${var}` placeholders are
+// rejected by the validator and skipped by every substitution layer.
+// `joins.length` is capped at JOINS_MAX_LENGTH; `text + joins` and
+// `include + joins` are both rejected with `unsupported_combination`.
+// ---------------------------------------------------------------------------
+
+export type JoinType = 'inner' | 'left' | 'right' | 'full';
+
+export type JoinClause = {
+  /** Resource (collection slug) of the joined records table. */
+  foreignSlug: string;
+  /**
+   * Field on the primary or any prior join's alias. Bare names refer to the
+   * primary structure; dotted names (`<alias>.<field>`) reference a prior
+   * join's logical alias.
+   */
+  localField: string;
+  /** Field on the joined table. */
+  foreignField: string;
+  /** SQL join type. Required — no implicit default. */
+  joinType: JoinType;
+  /**
+   * Optional projection on the joined row. Defaults to all readable fields
+   * (subject to field-level auth).
+   */
+  select?: string[];
+  /**
+   * Logical alias used to namespace the joined row in the response under
+   * `_joined[alias]`, and for `localField` references in subsequent joins.
+   * Defaults to `foreignSlug`. Required when joining the same `foreignSlug`
+   * more than once in the same query.
+   */
+  alias?: string;
 };
 
+/**
+ * Maximum number of `joins[]` entries allowed in a single QueryDefinition.
+ * Cap is conservative until we have telemetry on real-world chain lengths;
+ * raise if customers hit it for legitimate reporting use cases.
+ */
+export const JOINS_MAX_LENGTH = 4;
+
 // ---------------------------------------------------------------------------
 // QueryVariableDefinition (contract §8) — Phase 4 (saved queries)
 // ---------------------------------------------------------------------------
@@ -378,7 +454,18 @@ export type QueryErrorCode =
   | 'unsupported_legacy_operator'
   | 'unreadable_field'
   | 'invalid_query'
-  | 'legacy_write_unsupported';
+  | 'legacy_write_unsupported'
+  // Phase 4 — saved-query typed parameters (contract §8). Authoring and
+  // execute-time validation produce these codes; routes thread them through
+  // `queryErrorsToHttp` so the response shape matches the rest of the engine.
+  | 'unknown_variable'
+  | 'variable_type_mismatch'
+  | 'missing_required_variable'
+  | 'extra_variable'
+  // 6.0 — multi-join (CEN-1058).
+  | 'joins_length_exceeded'
+  | 'unsupported_combination'
+  | 'duplicate_join_alias';
 
 export type QueryError = {
   code: QueryErrorCode;

package/scripts/smoke-types.ts

@@ -20,6 +20,9 @@ import {
     type SelectClause,
     type FieldCondition,
     type CanonicalOperator,
+    type ExecuteSavedQueryValues,
+    type QueryVariableDefinition,
+    type SmartQuery,
     CANONICAL_OPERATORS,
     RECORDS_PAGE_DEFAULT_LIMIT,
     RECORDS_PAGE_MAX_LIMIT,
@@ -103,11 +106,73 @@ async function exerciseSdk() {
     });
     console.log(r3.data, r3.meta.mode);
 
-    // (Saved-query SDK surface — `client.savedQueries` — is deliberately not
-    // shipped in 5.5.0. The /saved-queries/* HTTP routes are Phase 4 work
-    // tracked in CEN-1198; the canonical SDK manager lands alongside them.
-    // Today's `client.smartQueries` namespace is the supported way to call
-    // saved queries from the SDK.)
+    // ---- Saved-query typed parameters (CEN-1208 / Phase 4 WS4) ----
+    //
+    // `get()` returns the typed `variables` declarations alongside the
+    // query body so callers can construct invocations programmatically.
+    const savedQuery: SmartQuery = (await client.savedQueries.get('orders', 'qry-uuid')).data;
+    const decls: Record<string, QueryVariableDefinition> | null | undefined = savedQuery.variables;
+    console.log(decls);
+
+    // Untyped execute — accepts ScalarValue | ScalarValue[] | Date | Date[].
+    await client.savedQueries.execute('orders', 'qry-uuid', {
+        variables: {
+            since: new Date('2026-01-01'),
+            statuses: ['open', 'paid'],
+            limit: 25,
+            // array<datetime> binding — matches the shared { array: 'datetime' } variable type.
+            window: [new Date('2026-01-01'), new Date('2026-04-01')],
+        },
+    });
+
+    // Typed execute — generic enforces the parameter shape at the call site.
+    // Plain TS interfaces (no string index signature) are accepted — the
+    // SDK does NOT require `extends ExecuteSavedQueryValues`.
+    interface MonthlyRevenueVars {
+        month: Date;
+        region: string;
+    }
+    await client.savedQueries.executeTyped<MonthlyRevenueVars>('orders', 'monthly-revenue', {
+        month: new Date('2026-04-01'),
+        region: 'us-east',
+    });
+
+    // Canonical authoring — `query: QueryDefinition` + typed `variables`.
+    await client.savedQueries.create('orders', {
+        name: 'Active Orders',
+        query: {
+            resource: 'orders',
+            where: { 'data.status': { eq: '${statusFilter}' } },
+            page: { limit: 100 },
+        },
+        variables: { statusFilter: { type: 'string', required: true } },
+    });
+    await client.savedQueries.update('orders', 'qry-uuid', {
+        query: {
+            resource: 'orders',
+            where: { 'data.amount': { gte: '${minTotal}' } },
+            page: { limit: 50 },
+        },
+        variables: { minTotal: { type: 'number', required: true } },
+    });
+    await client.savedQueries.test('orders', {
+        query: {
+            resource: 'orders',
+            where: { 'data.amount': { gte: '${minTotal}' } },
+            page: { limit: 5 },
+        },
+        variableDeclarations: { minTotal: { type: 'number', required: true } },
+        variables: { minTotal: 100 },
+    });
+
+    // The lines below MUST fail to compile (uncomment to verify):
+    // await client.savedQueries.executeTyped<MonthlyRevenueVars>('orders', 'monthly-revenue', {
+    //     month: 'not-a-date', // wrong type
+    //     region: 'us-east',
+    // });
+    // await client.savedQueries.executeTyped<MonthlyRevenueVars>('orders', 'monthly-revenue', {
+    //     region: 'us-east', // missing required `month`
+    // });
 
     // Top-level canonical overload
     const r4: QueryResult<Order> = await client.queryRecords<Order>('orders', {
@@ -123,6 +188,81 @@ async function exerciseSdk() {
         sort: '-createdAt',
     });
     console.log(r5.data);
+
+    // ---- Function-runs canonical surface (CEN-1216, accessor renamed CEN-1227) ----
+    interface FRow { id: string; functionId: string; status: string; startedAt: string }
+
+    // Canonical accessor: client.functionRuns
+    // Caller can omit `resource` — manager forces 'function-runs'
+    const r6: QueryResult<FRow> = await client.functionRuns.query<FRow>({
+        where: {
+            and: [
+                { functionId: { eq: 'fn-123' } },
+                { status: { eq: 'failure' } },
+            ],
+        },
+        sort: [{ field: 'startedAt', direction: 'desc' }],
+        page: { limit: 50 },
+    });
+    console.log(r6.data, r6.meta);
+
+    // Authoring dry-run
+    const planResp = await client.functionRuns.test({
+        where: { status: { eq: 'completed' } },
+        page: { limit: 10 },
+    });
+    console.log(planResp.plan.executor, planResp.plan.mode);
+
+    // Deprecated alias still type-checks (emits runtime warning)
+    const r6b: QueryResult<FRow> = await client.runs.query<FRow>({
+        where: { status: { eq: 'failure' } },
+        page: { limit: 1 },
+    });
+    console.log(r6b.data.length);
+
+    // ---- Files canonical surface (CEN-1218 / Phase 3) ----
+    interface FilesRow { id: string; name?: string; contentType?: string; size?: number; createdAt?: string }
+
+    // Caller can omit `resource` — manager forces 'files'.
+    const r7: QueryResult<FilesRow> = await client.files.query<FilesRow>({
+        where: {
+            and: [
+                { fileType: { eq: 'image' } },
+                { tags: { hasAny: ['draft', 'review'] } },
+            ],
+        },
+        sort: [{ field: 'createdAt', direction: 'desc' }],
+        page: { limit: 25 },
+        select: { fields: ['name', 'contentType', 'size', 'createdAt'] },
+    });
+    console.log(r7.data, r7.meta);
+
+    // Default row shape (no generic) returns the canonical FileMetadata projection.
+    const r7b = await client.files.query({
+        where: { folderId: { eq: 'folder-uuid' } },
+    });
+    console.log(r7b.data.map((f) => f.name));
+
+    // renderId on the canonical row pairs with getFileRenderUrl /
+    // getFileDownloadUrl — so callers who discover files via query can
+    // build URLs without a separate uploadFile() round-trip.
+    const r7c = await client.files.query({
+        where: { fileType: { eq: 'image' } },
+        select: { fields: ['renderId', 'name', 'contentType'] },
+    });
+    for (const f of r7c.data) {
+        if (f.renderId) {
+            const url = client.getFileRenderUrl(f.renderId, { width: 200 });
+            console.log(f.name, url);
+        }
+    }
+
+    // Authoring dry-run
+    const filesPlan = await client.files.test({
+        where: { isPublic: { eq: true } },
+        page: { limit: 10 },
+    });
+    console.log(filesPlan.plan.executor, filesPlan.plan.resource);
 }
 
 void exerciseSdk;