@centrali-io/centrali-sdk 5.5.1 → 6.0.0

package/src/managers/records.ts

@@ -0,0 +1,186 @@
+// =====================================================
+// Records Manager (canonical query surface — CEN-1194)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type { QueryRecordOptions } from '../types/records';
+import type {
+    QueryDefinition,
+    QueryResult,
+    WhereExpression,
+    SortClause,
+    PageClause,
+    SelectClause,
+} from '../../query-types';
+import { getRecordApiPath } from '../internal/paths';
+import { validateQueryDefinition } from '@centrali/query';
+import { queryErrorsToCentraliError } from './query';
+
+
+/**
+ * RecordsManager exposes the canonical query surface for records.
+ *
+ * All three methods compile to a single canonical `QueryDefinition` server-side
+ * and return the canonical `{ data, meta }` envelope (`QueryResult<T>`).
+ *
+ * - {@link RecordsManager.query | query} — full POST `/records/query`. Use for
+ *   nested boolean trees, `select`, `text`, `include`.
+ * - {@link RecordsManager.list | list} — GET adapter for simple URL-param
+ *   queries. Bookmarkable, cacheable, but cannot express nested `or`/`not`.
+ * - {@link RecordsManager.search | search} — sugar over `query({ text: ... })`.
+ *
+ * Access via `client.records`.
+ *
+ * @example
+ * ```ts
+ * // Canonical query — boolean tree, select, paging
+ * const open = await client.records.query<Order>('orders', {
+ *   resource: 'orders',
+ *   where: {
+ *     and: [
+ *       { 'data.status': { eq: 'open' } },
+ *       { or: [
+ *         { 'data.amount': { gte: 100 } },
+ *         { 'data.priority': { eq: 'high' } }
+ *       ]}
+ *     ]
+ *   },
+ *   sort: [{ field: 'createdAt', direction: 'desc' }],
+ *   page: { limit: 50 },
+ *   select: { fields: ['id', 'data.status', 'data.amount'] }
+ * });
+ * console.log(open.data, open.meta.hasMore);
+ *
+ * // GET adapter — simple cases
+ * const recent = await client.records.list<Order>('orders', {
+ *   'data.status': 'paid',
+ *   sort: '-createdAt',
+ *   pageSize: 25,
+ * });
+ *
+ * // Text search — sugar over { text }
+ * const matches = await client.records.search<Order>('orders', 'urgent shipping');
+ * ```
+ */
+export class RecordsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+
+    /**
+     * Run a canonical query against `POST /records/query`.
+     *
+     * The body **is** a `QueryDefinition`. Returns the canonical `{ data, meta }`
+     * envelope. If `definition.resource` is omitted, `resource` is filled in
+     * from the first argument so the wire shape always matches the contract.
+     *
+     * @example
+     * const open = await client.records.query<Order>('orders', {
+     *   resource: 'orders',
+     *   where: { 'data.status': { eq: 'open' } },
+     *   page: { limit: 100 }
+     * });
+     */
+    public async query<T = any>(
+        resource: string,
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `data/workspace/${this.workspaceId}/api/v1/records/query`;
+        const body: QueryDefinition = { ...definition, resource: definition.resource ?? resource };
+        // Local pre-validation (CEN-1202). The SDK bundles the same
+        // validator the data service runs server-side, so a malformed
+        // body is rejected before the HTTP roundtrip with the same
+        // `CentraliError` shape the server would have returned.
+        const validation = validateQueryDefinition(body);
+        if (!validation.ok) {
+            throw queryErrorsToCentraliError(validation.errors);
+        }
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        // POST /records/query returns canonical `{ data, meta }`. The SDK's
+        // `request()` normalizer leaves objects with a `data` key untouched, so
+        // the runtime shape already matches `QueryResult<T>` — we only need to
+        // re-type the response. `meta` is server-guaranteed for this route.
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * Authoring-time dry-run of a canonical query against `POST /records/query/test`.
+     *
+     * Same input shape as {@link RecordsManager.query | query}. Returns
+     * `422 unreadable_field` on fields the caller can't see (instead of the
+     * runtime privacy-preserving empty-result behavior). Use from query
+     * builders to surface precise errors to the author.
+     */
+    public async test<T = any>(
+        resource: string,
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `data/workspace/${this.workspaceId}/api/v1/records/query/test`;
+        const body: QueryDefinition = { ...definition, resource: definition.resource ?? resource };
+        const validation = validateQueryDefinition(body);
+        if (!validation.ok) {
+            throw queryErrorsToCentraliError(validation.errors);
+        }
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * GET adapter for simple, URL-encodable queries (`?status=paid&sort=-createdAt`).
+     *
+     * Server-side this routes through the same canonical engine as
+     * {@link RecordsManager.query | query} (per CEN-1181 WS3) — the URL
+     * params compile into a `QueryDefinition` before execution. Use this when
+     * a flat AND of field conditions is enough; reach for `query()` when you
+     * need nested booleans, `select`, `text`, or `include`.
+     *
+     * Returns the records-list `ApiResponse<T[]>` envelope unchanged so
+     * callers that read `meta.page` / `meta.pageSize` keep working during
+     * the deprecation window.
+     */
+    public list<T = any>(
+        resource: string,
+        urlOpts?: QueryRecordOptions
+    ): Promise<ApiResponse<T[]>> {
+        const path = getRecordApiPath(this.workspaceId, resource);
+        return this.requestFn<T[]>('GET', path, null, urlOpts);
+    }
+
+    /**
+     * Full-text search sugar — equivalent to `query(resource, { text: ... })`.
+     *
+     * Routes through `RecordsSearchExecutor` (Meilisearch) when only `text` is
+     * provided, or through the hybrid Meili-first path when `where` is also
+     * set. Result envelope is identical across pure-filter, pure-text, and
+     * hybrid (`{ data, meta }`).
+     */
+    public async search<T = any>(
+        resource: string,
+        text: string,
+        opts?: {
+            fields?: string[];
+            typoTolerance?: boolean;
+            where?: WhereExpression;
+            sort?: SortClause[];
+            page?: PageClause;
+            select?: SelectClause;
+        }
+    ): Promise<QueryResult<T>> {
+        return this.query<T>(resource, {
+            resource,
+            text: { query: text, fields: opts?.fields, typoTolerance: opts?.typoTolerance },
+            where: opts?.where,
+            sort: opts?.sort,
+            page: opts?.page,
+            select: opts?.select,
+        });
+    }
+}

package/src/managers/smartQueries.ts

@@ -0,0 +1,374 @@
+// =====================================================
+// Smart Queries Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    SmartQuery,
+    ListSmartQueryOptions,
+    ExecuteSmartQueryOptions,
+    ExecuteSavedQueryValues,
+    CreateSmartQueryInput,
+    UpdateSmartQueryInput,
+    TestSmartQueryInput,
+} from '../types/smartQueries';
+import {
+    getSmartQueriesApiPath,
+    getSmartQueriesStructureApiPath,
+    getSmartQueryByNameApiPath,
+    getSavedQueryCanonicalCollectionPath,
+    getSavedQueryCanonicalByIdPath,
+    getSavedQueryCanonicalExecutePath,
+    getSavedQueryCanonicalTestPath,
+    getSmartQueryTestApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// Smart Queries Manager
+// =====================================================
+
+/**
+ * SmartQueriesManager — reusable, parameterized saved queries. Access via
+ * `client.savedQueries` (canonical) or `client.smartQueries` (deprecated alias).
+ *
+ * Phase 4 of the query foundation (CEN-1198) shipped the canonical
+ * `/saved-queries/*` HTTP routes; this manager now routes through them. The
+ * data service dual-mounts the deprecated `/smart-queries/*` alias for the
+ * deprecation window. New code that doesn't need saved queries should still
+ * prefer `client.records.query()` for ad-hoc queries.
+ *
+ * Usage:
+ * ```ts
+ * // List saved queries for a structure
+ * const queries = await client.savedQueries.list('employee');
+ *
+ * // Execute a saved query by ID
+ * const results = await client.savedQueries.execute('employee', 'query-uuid');
+ *
+ * // Get a saved query by name
+ * const query = await client.savedQueries.getByName('employee', 'Active Employees');
+ * ```
+ */
+export class SmartQueriesManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+
+    /**
+     * List all smart queries in the workspace.
+     *
+     * @param options - Optional list parameters (pagination, search, etc.)
+     * @returns List of smart queries with pagination metadata
+     *
+     * @example
+     * ```ts
+     * // List all smart queries
+     * const queries = await client.smartQueries.listAll();
+     *
+     * // With pagination
+     * const queries = await client.smartQueries.listAll({ page: 1, limit: 20 });
+     * ```
+     */
+    public listAll(options?: ListSmartQueryOptions): Promise<ApiResponse<SmartQuery[]>> {
+        const path = getSmartQueriesApiPath(this.workspaceId);
+        return this.requestFn<SmartQuery[]>('GET', path, null, options);
+    }
+
+    /**
+     * List smart queries for a specific structure.
+     *
+     * @param structureSlug - The structure's record slug (e.g., "employee")
+     * @param options - Optional list parameters (pagination, search, etc.)
+     * @returns List of smart queries for the structure
+     *
+     * @example
+     * ```ts
+     * // List queries for employee structure
+     * const queries = await client.smartQueries.list('employee');
+     *
+     * // With pagination and search
+     * const queries = await client.smartQueries.list('employee', {
+     *   page: 1,
+     *   limit: 10,
+     *   search: 'active'
+     * });
+     * ```
+     */
+    public list(structureSlug: string, options?: ListSmartQueryOptions): Promise<ApiResponse<SmartQuery[]>> {
+        const path = getSmartQueriesStructureApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<SmartQuery[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a smart query by ID.
+     *
+     * @param structureSlug - The structure's record slug
+     * @param queryId - The smart query UUID
+     * @returns The smart query details
+     *
+     * @example
+     * ```ts
+     * const query = await client.smartQueries.get('employee', 'query-uuid');
+     * console.log('Query name:', query.data.name);
+     * ```
+     */
+    public get(structureSlug: string, queryId: string): Promise<ApiResponse<SmartQuery>> {
+        const path = getSmartQueriesStructureApiPath(this.workspaceId, structureSlug, queryId);
+        return this.requestFn<SmartQuery>('GET', path);
+    }
+
+    /**
+     * Get a smart query by name.
+     *
+     * @param structureSlug - The structure's record slug
+     * @param name - The smart query name
+     * @returns The smart query details
+     *
+     * @example
+     * ```ts
+     * const query = await client.smartQueries.getByName('employee', 'Active Employees');
+     * console.log('Query ID:', query.data.id);
+     * ```
+     */
+    public getByName(structureSlug: string, name: string): Promise<ApiResponse<SmartQuery>> {
+        const path = getSmartQueryByNameApiPath(this.workspaceId, structureSlug, name);
+        return this.requestFn<SmartQuery>('GET', path);
+    }
+
+    /**
+     * Execute a saved query and return results.
+     *
+     * Pagination (`limit` / `offset`) is defined inside the persisted
+     * `queryDefinition`, not at execution time.
+     *
+     * Variables in the query body use canonical `${var}` placeholders. Phase 4
+     * saved queries declare types for each placeholder via `variables` (see
+     * `get()`); the server validates each value against the declared type by
+     * JS `typeof` (no coercion — `"123"` is rejected for `number`). Legacy
+     * untyped rows accept the same `variables` map but stringify each value
+     * before substitution.
+     *
+     * @param structureSlug - The collection's record slug
+     * @param queryId - The saved query UUID
+     * @param options - Optional execution options including variables
+     * @returns Query results
+     *
+     * @example
+     * ```ts
+     * // Simple execution without variables
+     * const results = await client.savedQueries.execute('employee', 'query-uuid');
+     * console.log('Found:', results.data.length, 'records');
+     *
+     * // Execution with variables
+     * // Query definition: { where: { status: { eq: "${statusFilter}" } } }
+     * const filtered = await client.savedQueries.execute('orders', 'query-id', {
+     *   variables: { statusFilter: 'active' }
+     * });
+     *
+     * // Accessing joined data (nested under _joined)
+     * // Query with join: { join: { foreignSlug: "products", ... } }
+     * const items = await client.savedQueries.execute('order-items', 'items-with-products');
+     * items.data.forEach(item => {
+     *   console.log('Item:', item.name);
+     *   console.log('Product:', item._joined?.products?.title);
+     * });
+     * ```
+     */
+    public execute<T = any>(
+        _structureSlug: string,
+        queryId: string,
+        options?: ExecuteSmartQueryOptions
+    ): Promise<ApiResponse<T[]>> {
+        // CEN-1245 — route through the canonical `/saved-queries/:id/execute`
+        // endpoint, which returns the contract §9 envelope (`{ data, meta }`).
+        // The slug segment is unused by the canonical path; the data service
+        // resolves the resource from the saved-query row. The previous legacy
+        // slug path returned `{ result: { rows, rowCount } }` and the SDK had
+        // to unwrap through `request()`'s `{ result } -> { data: result }`
+        // handler — we now stay on the canonical envelope end-to-end.
+        const path = getSavedQueryCanonicalExecutePath(this.workspaceId, queryId);
+        // Use POST to support variables, with empty body if no options
+        const body = options?.variables ? { variables: options.variables } : undefined;
+        return this.requestFn<T[]>('POST', path, body);
+    }
+
+    /**
+     * Type-safe variant of {@link execute}. The caller passes a generic
+     * `TVars` type that describes the saved query's parameter shape, and the
+     * compiler enforces that every required key is provided with the right
+     * scalar type.
+     *
+     * Use this when the saved query declares typed `variables` (Phase 4) and
+     * the caller has — or can derive — a TypeScript type for the parameter
+     * map. For untyped callers, prefer {@link execute}.
+     *
+     * @example
+     * ```ts
+     * type MonthlyRevenueVars = { month: Date; region: string };
+     *
+     * const rows = await client.savedQueries.executeTyped<MonthlyRevenueVars>(
+     *   'orders',
+     *   'monthly-revenue',
+     *   { month: new Date('2026-04-01'), region: 'us-east' },
+     * );
+     *
+     * // Compile error — missing required key:
+     * // await client.savedQueries.executeTyped<MonthlyRevenueVars>('orders', 'monthly-revenue', { region: 'us-east' });
+     * ```
+     */
+    public executeTyped<TVars extends object, TRow = any>(
+        structureSlug: string,
+        queryId: string,
+        values: TVars,
+    ): Promise<ApiResponse<TRow[]>> {
+        // Cast to the runtime-values type at the boundary: the network call
+        // serializes whatever shape the caller passes (axios JSON-encodes
+        // Date as ISO-8601), and the server enforces the typed contract via
+        // declarations on the saved-query row. The generic exists purely for
+        // call-site type safety, so we deliberately don't constrain `TVars`
+        // to `ExecuteSavedQueryValues` — that constraint requires a string
+        // index signature that ordinary TS interfaces don't have.
+        return this.execute<TRow>(structureSlug, queryId, {
+            variables: values as unknown as ExecuteSavedQueryValues,
+        });
+    }
+
+    /**
+     * Create a new saved query.
+     *
+     * Routing: when `input.query` (canonical `QueryDefinition`) is provided
+     * the SDK calls the canonical `POST /saved-queries` endpoint, which
+     * accepts typed `variables` declarations and `${var}` placeholders. When
+     * only legacy `input.queryDefinition` is provided the SDK falls back to
+     * the slug-based legacy endpoint.
+     *
+     * @param structureSlug - The collection's record slug. Required for the
+     *   legacy path; on the canonical path the resource is read from
+     *   `query.resource` and this slug is currently ignored on the wire.
+     * @param input - Canonical (`query`) or legacy (`queryDefinition`) body.
+     * @returns The created saved query.
+     *
+     * @example
+     * ```ts
+     * // Canonical (Phase 4) — typed parameters + canonical operators
+     * const query = await client.savedQueries.create('orders', {
+     *   name: 'Active Orders',
+     *   description: 'All orders with active status',
+     *   query: {
+     *     resource: 'orders',
+     *     where: { 'data.status': { eq: '${statusFilter}' } },
+     *     sort: [{ field: 'createdAt', direction: 'desc' }],
+     *     page: { limit: 100 },
+     *   },
+     *   variables: {
+     *     statusFilter: { type: 'string', required: true },
+     *   },
+     * });
+     * ```
+     */
+    public create(structureSlug: string, input: CreateSmartQueryInput): Promise<ApiResponse<SmartQuery>> {
+        if (input.query) {
+            const path = getSavedQueryCanonicalCollectionPath(this.workspaceId);
+            const body = {
+                name: input.name,
+                description: input.description,
+                query: input.query,
+                variables: input.variables,
+            };
+            return this.requestFn<SmartQuery>('POST', path, body);
+        }
+        const path = getSmartQueriesStructureApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<SmartQuery>('POST', path, input);
+    }
+
+    /**
+     * Update an existing saved query.
+     *
+     * Routing: when `input.query` is provided the SDK calls canonical
+     * `PUT /saved-queries/:id`; otherwise it falls back to the legacy
+     * slug-based PUT.
+     *
+     * @example
+     * ```ts
+     * const updated = await client.savedQueries.update('orders', 'query-uuid', {
+     *   name: 'Active Orders v2',
+     *   query: {
+     *     resource: 'orders',
+     *     where: { 'data.status': { in: ['active', 'processing'] } },
+     *     page: { limit: 200 },
+     *   },
+     * });
+     * ```
+     */
+    public update(structureSlug: string, queryId: string, input: UpdateSmartQueryInput): Promise<ApiResponse<SmartQuery>> {
+        if (input.query || input.variables !== undefined) {
+            const path = getSavedQueryCanonicalByIdPath(this.workspaceId, queryId);
+            const body: Record<string, unknown> = {};
+            if (input.name !== undefined) body.name = input.name;
+            if (input.description !== undefined) body.description = input.description;
+            if (input.query !== undefined) body.query = input.query;
+            if (input.variables !== undefined) body.variables = input.variables;
+            return this.requestFn<SmartQuery>('PUT', path, body);
+        }
+        const path = getSmartQueriesStructureApiPath(this.workspaceId, structureSlug, queryId);
+        return this.requestFn<SmartQuery>('PUT', path, input);
+    }
+
+    /**
+     * Delete a smart query.
+     *
+     * @param structureSlug - The structure's record slug
+     * @param queryId - The smart query UUID
+     *
+     * @example
+     * ```ts
+     * await client.smartQueries.delete('orders', 'query-uuid');
+     * ```
+     */
+    public delete(structureSlug: string, queryId: string): Promise<ApiResponse<void>> {
+        const path = getSmartQueriesStructureApiPath(this.workspaceId, structureSlug, queryId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * Test-execute a query definition without saving it. Useful for
+     * validating syntax, previewing results, and dry-running a draft's
+     * typed `variableDeclarations` against runtime `variables`.
+     *
+     * Routing: when `input.query` (canonical) is provided the SDK calls
+     * `POST /saved-queries/test`; otherwise it falls back to the legacy
+     * slug-based test endpoint.
+     *
+     * @example
+     * ```ts
+     * // Canonical (Phase 4) — typed variable declarations dry-run
+     * const result = 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 },
+     * });
+     * ```
+     */
+    public test<T = any>(structureSlug: string, input: TestSmartQueryInput): Promise<ApiResponse<T[]>> {
+        if (input.query) {
+            const path = getSavedQueryCanonicalTestPath(this.workspaceId);
+            return this.requestFn<T[]>('POST', path, input);
+        }
+        const path = getSmartQueryTestApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<T[]>('POST', path, input);
+    }
+}