@centrali-io/centrali-sdk 5.4.0 → 5.5.1

package/query-types.ts

@@ -0,0 +1,394 @@
+// ---------------------------------------------------------------------------
+// AUTO-GENERATED — DO NOT EDIT BY HAND.
+//
+// Source: services/backend/shared/query/src/types.ts (@centrali/query)
+// Regenerate: `npm run sync:query-types` (also runs on prebuild).
+//
+// The shared package is the single source of truth for canonical query types.
+// This file is a types-only port so the published SDK stays a single npm
+// install. See CEN-1194 for the alignment, CEN-1202 for runtime bundling.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Top-level QueryDefinition (contract §3)
+// ---------------------------------------------------------------------------
+
+export type QueryDefinition = {
+  /**
+   * Logical resource being queried.
+   *
+   * - For records: the collection (a.k.a. structure) slug — e.g. `"orders"`,
+   *   `"customers"`. The records executor treats this as the collection slug.
+   * - For other queryable resources: the resource type identifier — e.g.
+   *   `"audit-log"`, `"function-runs"`, `"files"`, `"webhook-deliveries"`.
+   *
+   * Named `resource` (not `collection`) because "collection" is overloaded in
+   * Centrali — it's the renamed records-bucket entity, so `collection: "audit-log"`
+   * would read as a category error. `resource` is REST-canonical and reads
+   * truthfully across every executor.
+   */
+  resource: string;
+  where?: WhereExpression;
+  text?: TextSearchClause;
+  sort?: SortClause[];
+  page?: PageClause;
+  select?: SelectClause;
+  include?: IncludeClause[];
+};
+
+export type SavedQueryDefinition = {
+  name: string;
+  description?: string;
+  query: QueryDefinition;
+  variables?: Record<string, QueryVariableDefinition>;
+};
+
+// ---------------------------------------------------------------------------
+// WhereExpression / FieldCondition (contract §4)
+// ---------------------------------------------------------------------------
+
+export type WhereExpression =
+  | FieldConditionMap
+  | { and: WhereExpression[] }
+  | { or: WhereExpression[] }
+  | { not: WhereExpression };
+
+export type FieldConditionMap = {
+  [field: string]: FieldCondition;
+};
+
+/**
+ * Exactly-one helper: for a record of operator → value-type, produces a union
+ * where each variant has exactly one of the keys present and all the others
+ * forbidden via `?: never`. This enforces the contract's "exactly one operator
+ * per FieldCondition" rule at the type level — `{ eq: 1, ne: 2 }` fails to
+ * type-check.
+ */
+type ExactlyOneOperator<T> = {
+  [K in keyof T]: { [P in K]: T[P] } & { [P in Exclude<keyof T, K>]?: never };
+}[keyof T];
+
+type FieldOperatorMap = {
+  eq: ScalarValue;
+  ne: ScalarValue;
+  gt: number | string;
+  gte: number | string;
+  lt: number | string;
+  lte: number | string;
+  in: ScalarValue[];
+  nin: ScalarValue[];
+  contains: string;
+  startsWith: string;
+  endsWith: string;
+  hasAny: ScalarValue[];
+  hasAll: ScalarValue[];
+  exists: boolean;
+};
+
+export type FieldCondition = ExactlyOneOperator<FieldOperatorMap>;
+
+export type ScalarValue = string | number | boolean | null;
+
+export type CanonicalOperator =
+  | 'eq'
+  | 'ne'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  | 'nin'
+  | 'contains'
+  | 'startsWith'
+  | 'endsWith'
+  | 'hasAny'
+  | 'hasAll'
+  | 'exists';
+
+export const CANONICAL_OPERATORS: readonly CanonicalOperator[] = [
+  'eq',
+  'ne',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'in',
+  'nin',
+  'contains',
+  'startsWith',
+  'endsWith',
+  'hasAny',
+  'hasAll',
+  'exists',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Operator UI metadata (single source of truth for query builders)
+//
+// Centrali's console builders historically maintained their own operator
+// dropdowns — every drift produced a real bug (CEN-1110: visual builder
+// offered `$like`, which the engine never supported, so saved filters
+// silently returned everything). Surfaces consume this map to render labels
+// + value affordances; backends consume it to keep the canonical operator
+// set + UI dropdowns in lock-step.
+// ---------------------------------------------------------------------------
+
+/** Argument shape an operator expects in a `FieldCondition`. */
+export type OperatorValueShape =
+  /** Single scalar input (string/number/boolean/null). */
+  | 'scalar'
+  /** Array of scalars — UI typically renders a chip / comma input. */
+  | 'array'
+  /** Boolean toggle — `exists`. */
+  | 'boolean';
+
+/**
+ * Logical type families an operator applies to. The visual builder narrows
+ * the dropdown to the operators valid for the selected field's type.
+ *
+ * `any` means the operator is type-agnostic (`eq`, `ne`, `exists`).
+ */
+export type OperatorTypeApplicability =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'datetime'
+  | 'array'
+  | 'any';
+
+export type OperatorMeta = {
+  /** Canonical bare operator name. */
+  operator: CanonicalOperator;
+  /** Human-readable label for dropdowns. */
+  label: string;
+  /** Short, symbol-style label suitable for compact number/datetime UIs. */
+  shortLabel?: string;
+  /** Argument shape — drives the value input affordance. */
+  valueShape: OperatorValueShape;
+  /** Field types this operator applies to. */
+  applicableTypes: OperatorTypeApplicability[];
+};
+
+export const OPERATOR_METADATA: Readonly<Record<CanonicalOperator, OperatorMeta>> = {
+  eq: {
+    operator: 'eq',
+    label: 'equals',
+    shortLabel: '=',
+    valueShape: 'scalar',
+    applicableTypes: ['any'],
+  },
+  ne: {
+    operator: 'ne',
+    label: 'not equals',
+    shortLabel: '≠',
+    valueShape: 'scalar',
+    applicableTypes: ['any'],
+  },
+  gt: {
+    operator: 'gt',
+    label: 'greater than',
+    shortLabel: '>',
+    valueShape: 'scalar',
+    applicableTypes: ['number', 'datetime'],
+  },
+  gte: {
+    operator: 'gte',
+    label: 'greater or equal',
+    shortLabel: '≥',
+    valueShape: 'scalar',
+    applicableTypes: ['number', 'datetime'],
+  },
+  lt: {
+    operator: 'lt',
+    label: 'less than',
+    shortLabel: '<',
+    valueShape: 'scalar',
+    applicableTypes: ['number', 'datetime'],
+  },
+  lte: {
+    operator: 'lte',
+    label: 'less or equal',
+    shortLabel: '≤',
+    valueShape: 'scalar',
+    applicableTypes: ['number', 'datetime'],
+  },
+  in: {
+    operator: 'in',
+    label: 'in',
+    valueShape: 'array',
+    applicableTypes: ['string', 'number', 'datetime'],
+  },
+  nin: {
+    operator: 'nin',
+    label: 'not in',
+    valueShape: 'array',
+    applicableTypes: ['string', 'number', 'datetime'],
+  },
+  contains: {
+    operator: 'contains',
+    label: 'contains',
+    valueShape: 'scalar',
+    applicableTypes: ['string'],
+  },
+  startsWith: {
+    operator: 'startsWith',
+    label: 'starts with',
+    valueShape: 'scalar',
+    applicableTypes: ['string'],
+  },
+  endsWith: {
+    operator: 'endsWith',
+    label: 'ends with',
+    valueShape: 'scalar',
+    applicableTypes: ['string'],
+  },
+  hasAny: {
+    operator: 'hasAny',
+    label: 'has any of',
+    valueShape: 'array',
+    applicableTypes: ['array'],
+  },
+  hasAll: {
+    operator: 'hasAll',
+    label: 'has all of',
+    valueShape: 'array',
+    applicableTypes: ['array'],
+  },
+  exists: {
+    operator: 'exists',
+    label: 'exists',
+    valueShape: 'boolean',
+    applicableTypes: ['any'],
+  },
+};
+
+/**
+ * Operators applicable to a given field-type. Used by builder UIs to narrow
+ * the dropdown when the user selects a field; falls back to `any`-applicable
+ * operators when the type is unknown.
+ */
+export function operatorsForFieldType(
+  type: OperatorTypeApplicability | string,
+): readonly OperatorMeta[] {
+  const t = type as OperatorTypeApplicability;
+  return CANONICAL_OPERATORS.map((op) => OPERATOR_METADATA[op]).filter((meta) =>
+    meta.applicableTypes.includes('any') || meta.applicableTypes.includes(t),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TextSearchClause (contract §5) — accepted in type, rejected by Phase 1 engine
+// ---------------------------------------------------------------------------
+
+export type TextSearchClause = {
+  query: string;
+  fields?: string[];
+  typoTolerance?: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// SortClause / PageClause (contract §6)
+// ---------------------------------------------------------------------------
+
+export type SortClause = {
+  field: string;
+  direction: 'asc' | 'desc';
+};
+
+/**
+ * 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.
+ */
+export type PageClause =
+  | { limit: number; offset?: number; cursor?: never }
+  | { limit: number; cursor?: string; offset?: never };
+
+/**
+ * Records Phase 1 page defaults (contract §6).
+ * Same default and cap for GET adapter and POST query body.
+ */
+export const RECORDS_PAGE_DEFAULT_LIMIT = 50;
+export const RECORDS_PAGE_MAX_LIMIT = 500;
+
+// ---------------------------------------------------------------------------
+// SelectClause / IncludeClause (contract §7)
+// ---------------------------------------------------------------------------
+
+export type SelectClause = {
+  fields: string[];
+};
+
+/**
+ * Phase 1 reserves the shape but rejects execution with `unsupported_clause`.
+ */
+export type IncludeClause = {
+  relation: string;
+};
+
+// ---------------------------------------------------------------------------
+// QueryVariableDefinition (contract §8) — Phase 4 (saved queries)
+// ---------------------------------------------------------------------------
+
+export type VariableType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'datetime'
+  | 'id'
+  | { array: VariableType }
+  | { reference: string };
+
+export type QueryVariableDefinition = {
+  type: VariableType;
+  required?: boolean;
+  default?: ScalarValue;
+  description?: string;
+};
+
+// ---------------------------------------------------------------------------
+// QueryResult envelope (contract §9)
+// ---------------------------------------------------------------------------
+
+export type QueryExecutionMode = 'filter' | 'search' | 'hybrid';
+
+export type QueryResultMeta = {
+  total?: number;
+  limit: number;
+  offset?: number;
+  cursor?: string;
+  nextCursor?: string;
+  hasMore?: boolean;
+  processingTimeMs?: number;
+  mode?: QueryExecutionMode;
+};
+
+export type QueryResult<T> = {
+  data: T[];
+  meta: QueryResultMeta;
+};
+
+// ---------------------------------------------------------------------------
+// Error codes (contract §10–12, §13 reserved-clause behavior)
+// ---------------------------------------------------------------------------
+
+export type QueryErrorCode =
+  | 'unsupported_clause'
+  | 'unsupported_operator'
+  | 'unsupported_legacy_operator'
+  | 'unreadable_field'
+  | 'invalid_query'
+  | 'legacy_write_unsupported';
+
+export type QueryError = {
+  code: QueryErrorCode;
+  message: string;
+  /** Dotted path inside the QueryDefinition where the error was detected, e.g. "where.data.status.eq". */
+  path?: string;
+  /** For `unsupported_clause` / `unsupported_operator`, the offending name. */
+  clause?: string;
+};
+
+export type ValidationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; errors: QueryError[] };

package/scripts/smoke-types.ts

@@ -0,0 +1,128 @@
+/**
+ * Type-only smoke for the canonical query surface added in 5.5.0 (CEN-1194).
+ *
+ * Runs as part of `npm run build` because it lives in the same project as
+ * `index.ts`. Compiling means the canonical types and new methods type-check
+ * end-to-end. There is no runtime assertion — when the SDK has a real test
+ * harness (separate ticket), these calls will turn into integration tests.
+ *
+ * To run manually:
+ *   npx tsc --noEmit scripts/smoke-types.ts
+ */
+
+import {
+    CentraliSDK,
+    type QueryDefinition,
+    type QueryResult,
+    type WhereExpression,
+    type SortClause,
+    type PageClause,
+    type SelectClause,
+    type FieldCondition,
+    type CanonicalOperator,
+    CANONICAL_OPERATORS,
+    RECORDS_PAGE_DEFAULT_LIMIT,
+    RECORDS_PAGE_MAX_LIMIT,
+} from '../index';
+
+// ---- Canonical type ergonomics ----
+
+const _operators: readonly CanonicalOperator[] = CANONICAL_OPERATORS;
+const _defaultLimit: number = RECORDS_PAGE_DEFAULT_LIMIT;
+const _maxLimit: number = RECORDS_PAGE_MAX_LIMIT;
+
+const _eqOnly: FieldCondition = { eq: 'paid' };
+// Uncommenting the next line MUST fail to compile (exactly-one-operator rule):
+// const _twoOps: FieldCondition = { eq: 'paid', ne: 'cancelled' };
+
+const _where: WhereExpression = {
+    and: [
+        { 'data.status': { eq: 'open' } },
+        { or: [
+            { 'data.amount': { gte: 100 } },
+            { 'data.priority': { eq: 'high' } }
+        ]},
+        { not: { 'data.archived': { eq: true } } }
+    ]
+};
+
+const _sort: SortClause[] = [
+    { field: 'createdAt', direction: 'desc' },
+    { field: 'data.amount', direction: 'asc' }
+];
+
+const _pageOffset: PageClause = { limit: 50, offset: 100 };
+const _pageCursor: PageClause = { limit: 50, cursor: 'abc' };
+// Uncommenting must fail (offset and cursor are mutually exclusive):
+// const _pageBoth: PageClause = { limit: 50, offset: 0, cursor: 'abc' };
+
+const _select: SelectClause = { fields: ['id', 'data.status', 'data.customer'] };
+
+const _def: QueryDefinition = {
+    resource: 'orders',
+    where: _where,
+    sort: _sort,
+    page: _pageOffset,
+    select: _select,
+};
+
+// ---- New SDK surface ----
+
+interface Order {
+    id: string;
+    data: { status: string; amount: number };
+}
+
+async function exerciseSdk() {
+    const client = new CentraliSDK({
+        baseUrl: 'http://localhost',
+        workspaceId: 'demo',
+        token: 'test',
+    });
+
+    // RecordsManager.query → QueryResult<T>
+    const r1: QueryResult<Order> = await client.records.query<Order>('orders', _def);
+    console.log(r1.data.length, r1.meta.limit);
+
+    // Resource backfill — caller can omit `resource` and we fill it from arg1
+    await client.records.query<Order>('orders', { where: _where });
+
+    // RecordsManager.test → QueryResult<T>
+    await client.records.test<Order>('orders', { resource: 'orders' });
+
+    // RecordsManager.list → ApiResponse<T[]> (legacy GET adapter envelope kept)
+    const r2 = await client.records.list<Order>('orders', {
+        'data.status': 'paid',
+        sort: '-createdAt',
+    });
+    console.log(r2.data.length);
+
+    // RecordsManager.search — text sugar, returns QueryResult<T>
+    const r3 = await client.records.search<Order>('orders', 'urgent shipping', {
+        page: { limit: 25 },
+    });
+    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.)
+
+    // Top-level canonical overload
+    const r4: QueryResult<Order> = await client.queryRecords<Order>('orders', {
+        resource: 'orders',
+        where: { 'data.status': { eq: 'paid' } },
+        page: { limit: 100 },
+    });
+    console.log(r4.data, r4.meta);
+
+    // Legacy GET-adapter form still type-checks (and emits a one-shot warn at runtime)
+    const r5 = await client.queryRecords<Order>('orders', {
+        'data.status': 'paid',
+        sort: '-createdAt',
+    });
+    console.log(r5.data);
+}
+
+void exerciseSdk;

package/scripts/sync-query-types.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sdkRoot = resolve(__dirname, '..');
+const sharedQueryTypes = resolve(
+    sdkRoot,
+    '../../backend/shared/query/src/types.ts'
+);
+const outputFile = resolve(sdkRoot, 'query-types.ts');
+
+const HEADER = `// ---------------------------------------------------------------------------
+// AUTO-GENERATED — DO NOT EDIT BY HAND.
+//
+// Source: services/backend/shared/query/src/types.ts (@centrali/query)
+// Regenerate: \`npm run sync:query-types\` (also runs on prebuild).
+//
+// The shared package is the single source of truth for canonical query types.
+// This file is a types-only port so the published SDK stays a single npm
+// install. See CEN-1194 for the alignment, CEN-1202 for runtime bundling.
+// ---------------------------------------------------------------------------
+
+`;
+
+const source = readFileSync(sharedQueryTypes, 'utf8');
+
+// Drop the original file's leading docblock (kept inside HEADER's pointer).
+const stripped = source.replace(/^\/\*\*[\s\S]*?\*\/\s*\n/, '');
+
+mkdirSync(dirname(outputFile), { recursive: true });
+writeFileSync(outputFile, HEADER + stripped, 'utf8');
+
+console.log(
+    `[sync-query-types] wrote ${outputFile.replace(sdkRoot + '/', '')} from ${sharedQueryTypes.replace(
+        resolve(sdkRoot, '../../..') + '/',
+        ''
+    )}`
+);