@centrali-io/centrali-sdk 5.5.1 → 6.0.0

package/README.md

@@ -407,15 +407,126 @@ const results = await centrali.savedQueries.execute('employee', query.data.id);
 console.log('Found:', results.data.length, 'employees');
 
 // Execute with variables (canonical operators — no `$` prefix)
-// Saved query body: { where: { 'data.status': { eq: '{{statusFilter}}' } } }
+// Saved query body: { where: { 'data.status': { eq: '${statusFilter}' } } }
 const filteredResults = await centrali.savedQueries.execute('orders', query.data.id, {
   variables: {
     statusFilter: 'active',
-    startDate: '2024-01-01'
-  }
+    startDate: new Date('2024-01-01'),
+  },
 });
 ```
 
+#### Typed parameters (Phase 4)
+
+Saved queries persist typed parameter declarations alongside the query body
+(`SmartQuery.variables`). `get()` returns them so callers can introspect the
+required shape, and `executeTyped<TVars>()` enforces it at the call site:
+
+```typescript
+const query = await centrali.savedQueries.get('orders', 'monthly-revenue');
+console.log(query.data.variables);
+// { month: { type: 'datetime', required: true }, region: { type: 'string', required: true } }
+
+interface MonthlyRevenueVars {
+  month: Date;
+  region: string;
+}
+
+const rows = await centrali.savedQueries.executeTyped<MonthlyRevenueVars>(
+  'orders',
+  'monthly-revenue',
+  { month: new Date('2026-04-01'), region: 'us-east' },
+);
+
+// Compile error — wrong type for `month`:
+// await centrali.savedQueries.executeTyped<MonthlyRevenueVars>('orders', 'monthly-revenue', {
+//   month: 'not-a-date',
+//   region: 'us-east',
+// });
+```
+
+`executeTyped<TVars>` accepts any object — there is no `extends ExecuteSavedQueryValues` constraint, so plain TS interfaces (no string index signature) work.
+
+The untyped `execute()` form accepts `Record<string, ScalarValue | ScalarValue[] | Date | Date[]>` for callers that don't have a typed shape — including arrays of dates for `array<datetime>` declarations.
+
+#### Authoring saved queries with canonical syntax
+
+To author a saved query that uses canonical operators (`eq`/`gte`/…) and typed parameters, pass `query` (a canonical `QueryDefinition`) and `variables` (typed declarations). The SDK routes those calls to the canonical `/saved-queries` endpoints:
+
+```typescript
+const created = await centrali.savedQueries.create('orders', {
+  name: 'Active Orders',
+  query: {
+    resource: 'orders',
+    where: { 'data.status': { eq: '${statusFilter}' } },
+    sort: [{ field: 'createdAt', direction: 'desc' }],
+    page: { limit: 100 },
+  },
+  variables: {
+    statusFilter: { type: 'string', required: true },
+  },
+});
+
+await centrali.savedQueries.update('orders', created.data.id, {
+  query: {
+    resource: 'orders',
+    where: { 'data.amount': { gte: '${minTotal}' } },
+    page: { limit: 50 },
+  },
+  variables: { minTotal: { type: 'number', required: true } },
+});
+
+// Dry-run a draft — exercises the same typed validator as a saved execute.
+await centrali.savedQueries.test('orders', {
+  query: {
+    resource: 'orders',
+    where: { 'data.amount': { gte: '${minTotal}' } },
+    page: { limit: 5 },
+  },
+  variableDeclarations: { minTotal: { type: 'number', required: true } },
+  variables: { minTotal: 100 },
+});
+```
+
+Pre-Phase-4 callers may still pass `queryDefinition` (legacy `$eq`/`$gte` shape) instead of `query`; those calls route to the legacy slug-based endpoints and cannot carry typed `variables` declarations.
+
+#### Promoting an untyped saved query to typed
+
+Saved queries that predate Phase 4 carry `variables: null` and substitute placeholders as plain strings. To promote one to typed validation:
+
+```typescript
+// 1. Load the row to see what placeholders are referenced
+const existing = await centrali.savedQueries.get('orders', 'monthly-revenue');
+
+// 2. Update with a `variables` declaration map. Every `${name}` referenced
+//    in the body must be declared, otherwise the server returns
+//    `unknown_variable`.
+await centrali.savedQueries.update('orders', existing.data.id, {
+  variables: {
+    month:  { type: 'datetime', required: true, description: 'Month bucket (UTC)' },
+    region: { type: 'string',   required: true },
+  },
+});
+
+// 3. Subsequent executes are validated against the declarations server-side
+//    (no coercion — "123" is rejected for `number`, etc.). Type mismatches
+//    surface as `variable_type_mismatch`, missing required keys as
+//    `missing_required_variable`, extras as `extra_variable`.
+//
+//    `Date` works for `datetime` because axios JSON-serializes it to an
+//    ISO-8601 string before the request — the server itself only ever sees
+//    the string and parses it via `Date.parse()`.
+await centrali.savedQueries.executeTyped<{ month: Date; region: string }>(
+  'orders',
+  existing.data.id,
+  { month: new Date('2026-04-01'), region: 'us-east' },
+);
+```
+
+Sending `variables: null` on `update()` reverts a typed row to untyped (legacy) substitution. Sending `{}` would put it into strict zero-variable mode and reject any remaining `${name}` placeholder in the body.
+
+Legacy `{{name}}` substitution still works on untyped rows during the deprecation window, but new saved queries — and any row being promoted to typed — must use canonical `${name}` placeholders.
+
 `centrali.savedQueries.*` is the canonical namespace, routed through the `/saved-queries/*` HTTP endpoints (Phase 4 of the [query foundation](https://github.com/blueinit/centrali/blob/main/docs/maintainers/overview/query-foundation.md), CEN-1198). New code should always use it.
 
 #### Migration from `centrali.smartQueries.*` (deprecated alias)
@@ -675,7 +786,7 @@ console.log('Job queued:', job.data);
 
 // Poll for the result using function runs
 // (The job ID maps to a function run — query by trigger to find it)
-const runs = await centrali.runs.listByTrigger('trigger-id', { limit: 1 });
+const runs = await centrali.functionRuns.listByTrigger('trigger-id', { limit: 1 });
 const latestRun = runs.data.data[0];
 console.log('Status:', latestRun.status);       // pending | running | completed | failure | timeout
 console.log('Result:', latestRun.runData);       // execution output (once completed)
@@ -684,24 +795,63 @@ console.log('Error:', latestRun.errorMessage);   // error details (if failed)
 
 #### Function Runs (Execution History)
 
-Query execution history for debugging and observability:
+Query execution history for debugging and observability. Access via
+`client.functionRuns` (canonical, since 5.6.0). The legacy `client.runs`
+accessor remains as a deprecated alias and emits a one-shot deprecation
+warning.
+
+The canonical `functionRuns.query()` surface (CEN-1216, since 5.6.0) is the
+recommended way for new code — same operator vocabulary as `records.query()`,
+returns the canonical `{ data, meta }` envelope.
 
 ```typescript
+// Recent failures for a function
+const failures = await centrali.functionRuns.query({
+  where: {
+    and: [
+      { functionId: { eq: 'fn-123' } },
+      { status: { eq: 'failure' } },
+    ],
+  },
+  sort: [{ field: 'startedAt', direction: 'desc' }],
+  page: { limit: 50 },
+});
+
+// Workspace-wide activity in a date window with field projection
+const activity = await centrali.functionRuns.query({
+  where: {
+    and: [
+      { startedAt: { gte: '2026-04-01' } },
+      { startedAt: { lt: '2026-05-01' } },
+    ],
+  },
+  sort: [{ field: 'startedAt', direction: 'desc' }],
+  page: { limit: 100 },
+  select: { fields: ['id', 'functionId', 'status', 'startedAt', 'endedAt', 'errorCode'] },
+});
+
+// Authoring dry-run — validate a query without executing it
+const plan = await centrali.functionRuns.test({
+  where: { status: { eq: 'completed' } },
+  page: { limit: 10 },
+});
+
 // Get a specific run by ID
-const run = await centrali.runs.get('run-uuid');
+const run = await centrali.functionRuns.get('run-uuid');
 console.log('Status:', run.data.status);
 console.log('Output:', run.data.runData);
 console.log('Duration:', run.data.startedAt, '→', run.data.endedAt);
+```
 
-// List runs for a trigger (most recent first)
-const triggerRuns = await centrali.runs.listByTrigger('trigger-uuid', {
-  status: 'failure',  // Filter by status
-  limit: 10
-});
+The legacy `functionRuns.listByTrigger()` / `functionRuns.listByFunction()` GET surfaces
+still work and are retained for back-compat — prefer `functionRuns.query()` with
+a `where: { triggerId: { eq: ... } }` or `{ functionId: { eq: ... } }` clause
+for new code.
 
-// List runs for a function
-const functionRuns = await centrali.runs.listByFunction('function-uuid');
-```
+Queryable fields are the fixed-schema columns: `id`, `functionId`, `triggerId`,
+`status`, `startedAt`, `endedAt`, `executionSource`, `errorCode`, `errorMessage`,
+etc. The `runData` and `executionContext` JSONB columns are intentionally not
+queryable — use `functionRuns.get(runId)` to fetch a specific run's payload.
 
 Run statuses: `pending` → `running` → `completed` | `failure` | `timeout`