@centrali-io/centrali-mcp 5.4.0 → 5.5.0

package/src/tools/records.ts

@@ -3,6 +3,187 @@ import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import axios, { AxiosInstance } from "axios";
 import { z } from "zod";
 import { registerTool, formatError } from "./_register.js";
+
+// ── Legacy 5.4.0 query_records translator (Sunset 2026-10-28) ──────────────
+//
+// 5.4.0 MCP clients call query_records with:
+//   { recordSlug, filters: { 'data.x[gte]': 1 }, sort: '-createdAt',
+//     page: 2, pageSize: 50, expand: 'customer', dateWindow: {...},
+//     includeDeleted, includeTotal }
+//
+// Canonical (Phase 1) accepts:
+//   { resource, where, sort: [{field, direction}], page: { limit, offset } }
+//
+// We accept BOTH on the wire and rewrite legacy → canonical before calling the
+// SDK, matching the data-service contract promise of long-lived legacy reads.
+
+const LEGACY_OP_MAP: Record<string, string> = {
+  $eq: "eq", $ne: "ne", $gt: "gt", $gte: "gte", $lt: "lt", $lte: "lte",
+  $in: "in", $nin: "nin", $contains: "contains",
+  $startsWith: "startsWith", $endsWith: "endsWith", $exists: "exists",
+  eq: "eq", ne: "ne", gt: "gt", gte: "gte", lt: "lt", lte: "lte",
+  in: "in", nin: "nin", contains: "contains",
+  startswith: "startsWith", endswith: "endsWith",
+  hasany: "hasAny", hasall: "hasAll",
+};
+
+let legacyWarned = false;
+function warnLegacyOnce() {
+  if (!legacyWarned) {
+    legacyWarned = true;
+    console.warn(
+      "[centrali-mcp] query_records called with the legacy 5.4.0 schema " +
+        "(recordSlug/filters/sort:string/pageSize). It still works but will be " +
+        "removed after 2026-10-28. Migrate to: { resource, where, " +
+        "sort: [{field,direction}], page: { limit, offset } }.",
+    );
+  }
+}
+
+function parseLegacyFilters(filters: unknown): unknown {
+  if (filters == null || typeof filters !== "object" || Array.isArray(filters)) {
+    return undefined;
+  }
+  const conditions: Array<Record<string, unknown>> = [];
+  for (const [rawKey, value] of Object.entries(filters as Record<string, unknown>)) {
+    const m = rawKey.match(/^(.+?)\[\$?([a-zA-Z]+)\]$/);
+    if (m) {
+      const [, field, op] = m;
+      const canonOp = LEGACY_OP_MAP[op] ?? LEGACY_OP_MAP[op.toLowerCase()] ?? op;
+      conditions.push({ [field]: { [canonOp]: value } });
+    } else {
+      conditions.push({ [rawKey]: { eq: value } });
+    }
+  }
+  if (conditions.length === 0) return undefined;
+  if (conditions.length === 1) return conditions[0];
+  return { and: conditions };
+}
+
+function parseLegacySort(sort: string): Array<{ field: string; direction: "asc" | "desc" }> {
+  return sort
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) =>
+      s.startsWith("-")
+        ? { field: s.slice(1), direction: "desc" as const }
+        : { field: s, direction: "asc" as const },
+    );
+}
+
+function dateWindowToWhere(dw: { field: string; from?: string; to?: string }): unknown {
+  const conds: Array<Record<string, unknown>> = [];
+  if (dw.from !== undefined) conds.push({ [dw.field]: { gte: dw.from } });
+  if (dw.to !== undefined) conds.push({ [dw.field]: { lte: dw.to } });
+  if (conds.length === 0) return undefined;
+  if (conds.length === 1) return conds[0];
+  return { and: conds };
+}
+
+type QueryRecordsArgs = {
+  resource?: string;
+  recordSlug?: string;
+  where?: unknown;
+  text?: unknown;
+  sort?: unknown;
+  page?: unknown;
+  pageSize?: number;
+  select?: unknown;
+  include?: unknown;
+  filters?: Record<string, unknown>;
+  expand?: string;
+  dateWindow?: { field: string; from?: string; to?: string };
+  includeDeleted?: boolean;
+  includeTotal?: boolean;
+};
+
+function translateQueryRecordsArgs(args: QueryRecordsArgs): {
+  resource: string;
+  definition: Record<string, unknown>;
+} {
+  const isLegacy =
+    args.recordSlug !== undefined ||
+    args.filters !== undefined ||
+    typeof args.sort === "string" ||
+    typeof args.page === "number" ||
+    args.pageSize !== undefined ||
+    args.expand !== undefined ||
+    args.dateWindow !== undefined ||
+    args.includeDeleted !== undefined ||
+    args.includeTotal !== undefined;
+
+  if (isLegacy) warnLegacyOnce();
+
+  const resource = args.resource ?? args.recordSlug;
+  if (!resource) {
+    throw new Error(
+      "query_records requires either `resource` (canonical) or `recordSlug` (legacy)",
+    );
+  }
+
+  // POST /records/query Phase 1 has no soft-delete plumbing — silently dropping
+  // `includeDeleted: true` would be a privacy regression vs 5.4.0 GET behavior
+  // (caller asks for tombstones, gets only live rows). Surface a clear error.
+  if (args.includeDeleted === true) {
+    throw new Error(
+      "query_records `includeDeleted: true` is not supported in Phase 1. " +
+        "Use the GET /records/slug/:rs endpoint with ?includeDeleted=true until Phase 2 lands.",
+    );
+  }
+
+  const definition: Record<string, unknown> = { resource };
+
+  const whereParts: unknown[] = [];
+  if (args.where !== undefined) whereParts.push(args.where);
+  if (args.filters !== undefined) {
+    const fw = parseLegacyFilters(args.filters);
+    if (fw !== undefined) whereParts.push(fw);
+  }
+  if (args.dateWindow !== undefined) {
+    const dw = dateWindowToWhere(args.dateWindow);
+    if (dw !== undefined) whereParts.push(dw);
+  }
+  if (whereParts.length === 1) definition.where = whereParts[0];
+  else if (whereParts.length > 1) definition.where = { and: whereParts };
+
+  if (args.text !== undefined) definition.text = args.text;
+
+  if (args.sort !== undefined) {
+    definition.sort = typeof args.sort === "string" ? parseLegacySort(args.sort) : args.sort;
+  }
+
+  if (args.page !== undefined || args.pageSize !== undefined) {
+    if (typeof args.page === "object" && args.page !== null) {
+      definition.page = args.page;
+    } else {
+      const limit = args.pageSize ?? 50;
+      const pageNum = typeof args.page === "number" ? args.page : 1;
+      const offset = (pageNum - 1) * limit;
+      definition.page = offset > 0 ? { limit, offset } : { limit };
+    }
+  }
+
+  if (args.select !== undefined) definition.select = args.select;
+
+  if (args.include !== undefined) {
+    definition.include = args.include;
+  } else if (args.expand !== undefined) {
+    const relations = args.expand
+      .split(",")
+      .map((s) => ({ relation: s.trim() }))
+      .filter((r) => r.relation.length > 0);
+    if (relations.length > 0) definition.include = relations;
+  }
+
+  // `includeTotal` is dropped — `meta.total` is always returned for offset
+  // pagination on POST /records/query. `includeDeleted` is rejected above.
+
+  return { resource, definition };
+}
+
+// Exposed for tests
+export const _internal = { translateQueryRecordsArgs, parseLegacyFilters, parseLegacySort };
 /**
  * Ensures the SDK has a valid token.
  */
@@ -10,7 +191,7 @@ async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
   let token = sdk.getToken();
   if (token) return token;
   try {
-    await sdk.queryRecords("__noop__", { limit: 1 });
+    await sdk.records.query("__noop__", { resource: "__noop__", page: { limit: 1 } });
   } catch { /* token refresh side effect */ }
   return sdk.getToken();
 }
@@ -44,7 +225,7 @@ function createRecordsClient(sdk: CentraliSDK, centraliUrl: string, workspaceId:
       if (isAuthError && !originalRequest._hasRetried) {
         originalRequest._hasRetried = true;
         try {
-          await sdk.queryRecords("__noop__", { limit: 1 });
+          await sdk.records.query("__noop__", { resource: "__noop__", page: { limit: 1 } });
         } catch { /* token refresh side effect */ }
 
         const token = sdk.getToken();
@@ -61,73 +242,113 @@ function createRecordsClient(sdk: CentraliSDK, centraliUrl: string, workspaceId:
 }
 
 export function registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "query_records",
-    "Query records from a collection with optional filters, sorting, pagination, and date range filtering. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100). Use dateWindow for date range queries.",
+    `Query records from a collection using the canonical Centrali query language (POST /records/query).
+
+The body is a QueryDefinition. Field paths use dotted strings ('data.status', 'data.customer.email'); the field operators (no '$' prefix) are: eq, ne, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, hasAny, hasAll, exists. Boolean trees use 'and', 'or', 'not'.
+
+Example body:
+  {
+    "where": {
+      "and": [
+        { "data.status": { "eq": "open" } },
+        { "data.amount": { "gte": 100 } }
+      ]
+    },
+    "sort": [{ "field": "createdAt", "direction": "desc" }],
+    "page": { "limit": 50 },
+    "select": { "fields": ["id", "data.status", "data.amount"] }
+  }
+
+Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' are all accepted by the engine.`,
     {
-      recordSlug: z
+      // Canonical fields (Phase 1)
+      resource: z
         .string()
-        .describe("The collection's record slug (e.g., 'orders')"),
-      filters: z
-        .record(z.string(), z.any())
+        .optional()
+        .describe("Collection slug to query (e.g. 'orders'). Required unless legacy `recordSlug` is provided."),
+      where: z
+        .any()
         .optional()
         .describe(
-          "Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll"
+          "WhereExpression — either a FieldConditionMap ({ 'data.status': { eq: 'open' } }) or a boolean tree ({ and: [...] } | { or: [...] } | { not: ... }). Each FieldCondition must use exactly one operator."
         ),
+      text: z
+        .object({
+          query: z.string().describe("Search string"),
+          fields: z.array(z.string()).optional().describe("Restrict to these fields"),
+          typoTolerance: z.boolean().optional(),
+        })
+        .optional()
+        .describe("Full-text search clause. Routes to the search executor when set."),
       sort: z
+        .any()
+        .optional()
+        .describe(
+          "Canonical: array of { field, direction: 'asc'|'desc' }. Legacy: string '-createdAt' (deprecated, translated automatically)."
+        ),
+      page: z
+        .any()
+        .optional()
+        .describe(
+          "Canonical: { limit, offset|cursor }. Legacy: page number (deprecated; combine with `pageSize`)."
+        ),
+      select: z
+        .object({
+          fields: z.array(z.string()).describe("Field paths to return"),
+        })
+        .optional()
+        .describe("Field projection. Example: { fields: ['id', 'data.status'] }."),
+      include: z
+        .array(z.object({ relation: z.string() }))
+        .optional()
+        .describe("Relation expansion. Each entry names a relation declared on the collection."),
+
+      // Legacy 5.4.0 fields — accepted, translated to canonical, removed after 2026-10-28
+      recordSlug: z
         .string()
         .optional()
+        .describe("[Deprecated 2026-10-28] Legacy alias for `resource`."),
+      filters: z
+        .record(z.string(), z.any())
+        .optional()
         .describe(
-          "Sort field with optional '-' prefix for descending (e.g., '-createdAt')"
+          "[Deprecated 2026-10-28] Legacy filter map (e.g. { 'data.status': 'open', 'data.price[lte]': 100 }). Translated to `where`."
         ),
-      page: z.number().optional().describe("Page number (1-indexed, default: 1)"),
       pageSize: z
         .number()
         .optional()
-        .describe("Records per page (default: 50, max: 500)"),
+        .describe("[Deprecated 2026-10-28] Legacy page size. Translated to `page.limit`."),
       expand: z
         .string()
         .optional()
         .describe(
-          "Comma-separated reference fields to expand (e.g., 'customer,product')"
+          "[Deprecated 2026-10-28] Comma-separated relation names (e.g. 'customer,product'). Translated to `include`."
         ),
       dateWindow: z
         .object({
-          field: z.string().describe("Date field to filter on (e.g., 'createdAt', 'updatedAt')"),
-          from: z.string().optional().describe("ISO 8601 lower bound (inclusive)"),
-          to: z.string().optional().describe("ISO 8601 upper bound (inclusive)"),
+          field: z.string(),
+          from: z.string().optional(),
+          to: z.string().optional(),
         })
         .optional()
-        .describe(
-          "Date range filter. Restricts results to records where the specified date field falls within the given range."
-        ),
+        .describe("[Deprecated 2026-10-28] Date range filter. Translated to `where` with gte/lte."),
       includeDeleted: z
         .boolean()
         .optional()
-        .describe("Include soft-deleted records (default: false)"),
+        .describe("[Deprecated 2026-10-28] Ignored — POST /records/query does not surface deleted rows in Phase 1."),
       includeTotal: z
         .boolean()
         .optional()
-        .describe("Include total record count in response metadata (default: false)"),
+        .describe("[Deprecated 2026-10-28] Ignored — `meta.total` is always returned for offset pagination."),
     },
-    async ({ recordSlug, filters, sort, page, pageSize, expand, dateWindow, includeDeleted, includeTotal }) => {
+    async (args) => {
+      let resource = "<unknown>";
       try {
-        const params: Record<string, any> = {
-          ...filters,
-          sort,
-          page,
-          pageSize,
-          expand,
-          dateWindow,
-          includeDeleted,
-          includeTotal,
-        };
-        // Remove undefined values
-        Object.keys(params).forEach(
-          (key) => params[key] === undefined && delete params[key]
-        );
-
-        const result = await sdk.queryRecords(recordSlug, params);
+        const translated = translateQueryRecordsArgs(args as QueryRecordsArgs);
+        resource = translated.resource;
+        const result = await sdk.records.query(resource, translated.definition as any);
         return {
           content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -138,7 +359,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
           content: [
             {
               type: "text",
-              text: formatError(error, `querying records from '${recordSlug}'`),
+              text: formatError(error, `querying records from '${resource}'`),
             },
           ],
           isError: true,
@@ -147,7 +368,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "get_record",
     "Get a single record by its ID from a collection. Optionally expand reference fields.",
     {
@@ -181,7 +402,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "create_record",
     "Create a new record in a collection. Pass the record data as a JSON object with field names matching the collection's properties.",
     {
@@ -214,7 +435,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "update_record",
     "Update an existing record by ID. Only include the fields you want to change.",
     {
@@ -246,7 +467,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "delete_record",
     "Delete a record by ID. Performs a soft delete by default (can be restored). Set hard=true for permanent deletion.",
     {
@@ -286,7 +507,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "upsert_record",
     "Create or update a record atomically. Matches on the provided fields to find an existing record — updates it if found, creates it if not. Returns the record and whether it was 'created' or 'updated'.",
     {
@@ -324,7 +545,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "get_records_by_ids",
     "Fetch multiple records by their IDs in a single request. Returns an array of records.",
     {
@@ -348,7 +569,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "restore_record",
     "Restore a soft-deleted record by ID. Only works on records deleted without hard=true.",
     {
@@ -376,7 +597,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
 
   // ── Bulk Operations (1 aggregate event per operation) ───────────────
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "bulk_create_records",
     `Bulk create multiple records in a collection. All records are created in a single transaction. Publishes ONE aggregate 'records_bulk_created' event (not one per record). Use this when downstream triggers should process all records together as a batch. Max 1000 records per call. For individual events per record, use batch_create_records instead.`,
     {
@@ -401,7 +622,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "bulk_update_records",
     `Bulk update multiple records with the same data. All records are updated in a single transaction. Publishes ONE aggregate 'records_bulk_updated' event (not one per record). Use this when all records need the same change and downstream triggers should process them together. For different data per record or individual events, use batch_update_records instead.`,
     {
@@ -427,7 +648,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "bulk_delete_records",
     `Bulk delete multiple records. All records are deleted in a single transaction. Publishes ONE aggregate 'records_bulk_deleted' event (not one per record). Use this when downstream triggers should process all deletions together. For individual events per deletion, use batch_delete_records instead.`,
     {
@@ -464,7 +685,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
 
   // ── Batch Operations (1 event per record) ──────────────────────────
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "batch_create_records",
     `Create multiple records individually. Each record gets its own 'record_created' event. Use this when downstream triggers (functions, webhooks, orchestrations) should process each record separately. Supports partial failure — some records can succeed even if others fail. For a single aggregate event, use bulk_create_records instead.`,
     {
@@ -495,7 +716,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "batch_update_records",
     `Update multiple records individually with different data per record. Each record gets its own 'record_updated' event. Use this when each record needs different changes and downstream triggers should process each update separately. For the same change applied to all records with a single event, use bulk_update_records instead.`,
     {
@@ -527,7 +748,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "batch_delete_records",
     `Delete multiple records individually. Each record gets its own 'record_deleted' event. Use this when downstream triggers should process each deletion separately. For a single aggregate event, use bulk_delete_records instead.`,
     {