@clowdops/tsclient 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,61 @@
1
+ # @flashbacktech/tsclient
2
+
3
+ TypeScript client for the cloud-agent platform API. Speaks the new domain vocabulary (`project` / `sandbox`) regardless of any residual legacy field names on the wire.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @flashbacktech/tsclient
9
+ # Optional, only needed if you use the chat SSE helper in a browser
10
+ npm install event-source-polyfill
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { CloudAgentClient } from '@flashbacktech/tsclient';
17
+
18
+ const client = new CloudAgentClient({
19
+ baseUrl: 'http://localhost:3010',
20
+ getToken: () => localStorage.getItem('access_token'),
21
+ onUnauthorized: async () => {
22
+ // refresh + re-authenticate; SDK does not auto-retry
23
+ },
24
+ });
25
+
26
+ // Auth
27
+ const session = await client.auth.login({ email, password });
28
+
29
+ // Projects + sandboxes
30
+ const projects = await client.projects.list();
31
+ const sandbox = await client.sandboxes.create({ projectId, name: 'demo', storageType: 'S3', mode: 'NORMAL' });
32
+
33
+ // Chat SSE
34
+ const stream = client.chat.openStream({
35
+ scope: { orgId, userId, sandboxId, projectId },
36
+ conversationId,
37
+ onEvent: (e) => console.log(e),
38
+ });
39
+ // later:
40
+ stream.close();
41
+ ```
42
+
43
+ ## Errors
44
+
45
+ Every non-2xx response throws an `HttpError`:
46
+
47
+ ```ts
48
+ import { HttpError } from '@flashbacktech/tsclient';
49
+
50
+ try {
51
+ await client.auth.login({ email, password });
52
+ } catch (err) {
53
+ if (err instanceof HttpError) {
54
+ console.log(err.status, err.errorCode, err.message);
55
+ }
56
+ }
57
+ ```
58
+
59
+ ## Releasing
60
+
61
+ `./patch.sh` from the repo root bumps the patch version, builds, and publishes to npm. Pass `--minor`, `--major`, or `--dry-run` as needed.
@@ -0,0 +1,531 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://flashback.tech/schemas/dashboard/v1",
4
+ "title": "Flashback Dashboard Spec v1",
5
+ "description": "The durable, data-free, PII-free Dashboard Spec authored by the BI agent's compose_dashboard tool. Each panel carries a binding (a parameterized query against one semantic model) OR a compositeBinding (two sub-bindings joined in-engine through a validated cross-dataset link), and a viz (how to draw the result). Data is transient; this spec is forever. Flat and recursion-free by construction so it is safe as a structured-output target and as a validation target (Visual-Dashboards design D1=B / D2=C).",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["schema", "title", "scope", "layout", "panels"],
9
+ "properties": {
10
+ "schema": {
11
+ "description": "Spec major-version discriminator. The validator binds to the major it embeds; forward/back compatibility is handled by upgraders-on-read, not by lax schemas (O7).",
12
+ "const": "flashback.dashboard/v1"
13
+ },
14
+ "title": { "type": "string", "minLength": 1, "maxLength": 200 },
15
+ "description": { "type": "string", "maxLength": 1000 },
16
+ "scope": {
17
+ "type": "object",
18
+ "additionalProperties": false,
19
+ "required": ["repoId"],
20
+ "properties": {
21
+ "repoId": { "type": "string", "minLength": 1 },
22
+ "defaultModelId": {
23
+ "description": "Model used by any panel binding that omits modelId. Panels may bind different models (O3); a plain binding is one model — cross-model joins go through a compositeBinding over a validated link (cross-dataset-links).",
24
+ "type": "string"
25
+ }
26
+ }
27
+ },
28
+ "parameters": {
29
+ "description": "Dashboard-level interactive controls. binding.filters reference these by id, so one control re-filters every panel and re-population just re-reads them. Locked cross-filter-ready now; rung-2 (global controls) ships early.",
30
+ "type": "array",
31
+ "maxItems": 24,
32
+ "items": { "$ref": "#/$defs/parameter" }
33
+ },
34
+ "layout": {
35
+ "description": "react-grid-layout-shaped, 12-column grid. Persisted verbatim; user-editable. Every item.i must match a panels[].id (enforced by the Go integrity check, not the schema).",
36
+ "type": "array",
37
+ "minItems": 1,
38
+ "maxItems": 64,
39
+ "items": { "$ref": "#/$defs/layoutItem" }
40
+ },
41
+ "panels": {
42
+ "type": "array",
43
+ "minItems": 1,
44
+ "maxItems": 64,
45
+ "items": { "$ref": "#/$defs/panel" }
46
+ }
47
+ },
48
+
49
+ "$defs": {
50
+ "dateGrainRef": {
51
+ "description": "A DATE-GRAIN dimension term: groups by a date column BUCKETED to a calendar unit instead of by its raw value. Use it whenever a panel is \"by month\"/\"by quarter\"/\"by year\" — grouping a raw date column buckets by every distinct timestamp, which draws as noise rather than a trend. The bucket is a COMPUTED column, so it comes back keyed \"[as]\" (like an inline aggregate, not like a plain dimension); viz.encoding fields and topN.by reference it exactly that way, and its channel type is \"temporal\". The alias may not contain brackets (un-injectable) and must be unique across the binding's dimensions AND measures (Go integrity check). B3 checks the column is actually a date.",
52
+ "type": "object",
53
+ "additionalProperties": false,
54
+ "required": ["field", "dateGrain", "as"],
55
+ "properties": {
56
+ "field": { "$ref": "#/$defs/fieldRef" },
57
+ "dateGrain": { "enum": ["day", "week", "month", "quarter", "year"] },
58
+ "as": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\[\\]]+$" }
59
+ }
60
+ },
61
+
62
+ "measureRef": {
63
+ "description": "A measure reference, e.g. \"[Efficiency %]\". The bracketed measure name; existence is B3's catalog bind-check, not structural. The name may not contain a bracket ([ or ]) — this keeps the ref un-injectable into DAX (a bracket would break out of the [measure] identifier).",
64
+ "type": "string",
65
+ "pattern": "^\\[[^\\[\\]]+\\]$"
66
+ },
67
+ "fieldRef": {
68
+ "description": "A field/dimension reference in DAX style, e.g. \"Mechanic[MechanicId]\". Entity = entity localKey (table name); Column = field column name. Neither segment may contain a bracket ([ or ]) — this makes the ref structurally un-injectable into DAX (a bracket would break out of the 'Entity'[Column] identifier and splice arbitrary columns/expressions). The synthetic \"__label\" (filled engine-side by B4) is also a legal viz field but is NOT a binding fieldRef.",
69
+ "type": "string",
70
+ "pattern": "^[^\\[\\]]+\\[[^\\[\\]]+\\]$"
71
+ },
72
+ "aggRef": {
73
+ "description": "An INLINE AGGREGATE measure term, for models that define few or no catalog measures: aggregates a raw column with a constrained function. Compiles to AGG('Entity'[Column]) aliased as \"as\"; the result column comes back keyed \"[as]\", so viz.encoding fields and topN.by reference it exactly like a measureRef. Prefer a real catalog measure whenever one computes the value (bind-check doctrine). The alias may not contain brackets (un-injectable into DAX) and must be unique within the binding (Go integrity check).",
74
+ "type": "object",
75
+ "additionalProperties": false,
76
+ "required": ["agg", "field", "as"],
77
+ "properties": {
78
+ "agg": { "enum": ["sum", "avg", "min", "max", "count", "distinctcount"] },
79
+ "field": { "$ref": "#/$defs/fieldRef" },
80
+ "as": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\[\\]]+$" }
81
+ }
82
+ },
83
+ "dateDiffRef": {
84
+ "description": "Closed-form duration measure: AGG of DATEDIFF(from, to, unit) over the rows of the two columns' entity, skipping rows where either date is blank. from/to MUST be Date columns on the SAME entity. Referenced downstream as \"[as]\", exactly like an inline aggregate. Use for lead time / cycle time / aging — a row-level duration that a plain inline aggregate cannot express.",
85
+ "type": "object",
86
+ "additionalProperties": false,
87
+ "required": ["agg", "dateDiff", "as"],
88
+ "properties": {
89
+ "agg": { "enum": ["avg", "min", "max", "sum"] },
90
+ "dateDiff": {
91
+ "type": "object",
92
+ "additionalProperties": false,
93
+ "required": ["from", "to", "unit"],
94
+ "properties": {
95
+ "from": { "$ref": "#/$defs/fieldRef" },
96
+ "to": { "$ref": "#/$defs/fieldRef" },
97
+ "unit": { "enum": ["day", "week", "month", "quarter", "year"] },
98
+ "nonNegative": { "type": "boolean", "description": "Skip rows where to < from (data-entry noise) instead of letting them drag the aggregate." }
99
+ }
100
+ },
101
+ "as": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\[\\]]+$" }
102
+ }
103
+ },
104
+
105
+ "parameter": {
106
+ "type": "object",
107
+ "additionalProperties": false,
108
+ "required": ["id", "type", "label"],
109
+ "properties": {
110
+ "id": { "type": "string", "minLength": 1 },
111
+ "type": { "enum": ["daterange", "dimension", "scalar"] },
112
+ "label": { "type": "string", "minLength": 1 },
113
+ "field": { "$ref": "#/$defs/fieldRef" },
114
+ "multi": { "type": "boolean" },
115
+ "default": {
116
+ "description": "Default control value. Shape depends on type: daterange => {relative} or {from,to}; dimension => null | string | array; scalar => a literal. Left unconstrained on purpose."
117
+ }
118
+ },
119
+ "allOf": [
120
+ {
121
+ "if": { "properties": { "type": { "const": "dimension" } }, "required": ["type"] },
122
+ "then": { "required": ["field"] }
123
+ }
124
+ ]
125
+ },
126
+
127
+ "layoutItem": {
128
+ "type": "object",
129
+ "additionalProperties": false,
130
+ "required": ["i", "x", "y", "w", "h"],
131
+ "properties": {
132
+ "i": { "type": "string", "minLength": 1 },
133
+ "x": { "type": "integer", "minimum": 0, "maximum": 11 },
134
+ "y": { "type": "integer", "minimum": 0 },
135
+ "w": { "type": "integer", "minimum": 1, "maximum": 12 },
136
+ "h": { "type": "integer", "minimum": 1, "maximum": 64 }
137
+ }
138
+ },
139
+
140
+ "filter": {
141
+ "oneOf": [
142
+ {
143
+ "type": "object",
144
+ "additionalProperties": false,
145
+ "required": ["param"],
146
+ "properties": { "param": { "type": "string", "minLength": 1 } }
147
+ },
148
+ {
149
+ "type": "object",
150
+ "additionalProperties": false,
151
+ "required": ["field", "op", "value"],
152
+ "properties": {
153
+ "field": { "$ref": "#/$defs/fieldRef" },
154
+ "op": { "enum": ["eq", "in", "gt", "gte", "lt", "lte", "between"] },
155
+ "value": {
156
+ "description": "Literal filter value. NOTE: a literal filter on a PII field is rejected by B4/B3 bind-check, not structurally."
157
+ }
158
+ }
159
+ }
160
+ ]
161
+ },
162
+
163
+ "topN": {
164
+ "type": "object",
165
+ "additionalProperties": false,
166
+ "required": ["by", "n", "dir"],
167
+ "properties": {
168
+ "by": {
169
+ "description": "The ranking measure: a catalog measureRef, or an inline aggregate's alias in brackets (\"[Avg Worked Hours]\").",
170
+ "$ref": "#/$defs/measureRef"
171
+ },
172
+ "n": { "type": "integer", "minimum": 1, "maximum": 10000 },
173
+ "dir": { "enum": ["asc", "desc"] }
174
+ }
175
+ },
176
+
177
+ "binding": {
178
+ "description": "The durable, data-free, PII-free query. Shape only — DAX compilation (B2) and catalog bind-check (B3: existence, grain in validGrains, cardinality != 'empty', PII labelField) are downstream. A measure term is a catalog measureRef (\"[Efficiency %]\"), an inline aggRef ({agg, field, as}) for models without authored measures, or a dateDiffRef ({agg, dateDiff, as}) for a duration between two date columns (lead time / cycle time / aging). A dimension term is a plain fieldRef, or a dateGrainRef ({field, dateGrain, as}) that buckets a date column to a calendar unit.",
179
+ "type": "object",
180
+ "additionalProperties": false,
181
+ "required": ["measures"],
182
+ "properties": {
183
+ "modelId": { "type": "string" },
184
+ "measures": {
185
+ "type": "array",
186
+ "minItems": 1,
187
+ "items": { "oneOf": [{ "$ref": "#/$defs/measureRef" }, { "$ref": "#/$defs/aggRef" }, { "$ref": "#/$defs/dateDiffRef" }] }
188
+ },
189
+ "dimensions": {
190
+ "type": "array",
191
+ "items": { "oneOf": [{ "$ref": "#/$defs/fieldRef" }, { "$ref": "#/$defs/dateGrainRef" }] }
192
+ },
193
+ "filters": { "type": "array", "items": { "$ref": "#/$defs/filter" } },
194
+ "grain": {
195
+ "description": "Optional. The grouping grain: an entity (table) name — an entity localKey — or the literal \"total\", NEVER a column name. When omitted, it is derived: \"total\" if the binding has no dimensions, else the first dimension's entity. When present but naming a dimension's column, B3 normalizes it to that dimension's entity. B3 checks grain is in the measure's validGrains (itself a list of localKeys + \"total\"). Grain is validated ONCE at authoring and trusted on every refresh (the runtime verifier ignores grain).",
196
+ "type": "string",
197
+ "minLength": 1
198
+ },
199
+ "topN": { "$ref": "#/$defs/topN" }
200
+ }
201
+ },
202
+
203
+ "qualifiedRef": {
204
+ "description": "A joined-row column: 'role.[Alias]' (a source's measure / inline-agg result), '[Alias]' (a derived term), a join-key alias, or an on-pair alias. Bracket-free segments keep the ref structurally un-injectable, exactly like fieldRef.",
205
+ "type": "string",
206
+ "pattern": "^([a-z][a-z0-9_]{0,23}\\.)?(\\[[^\\[\\]]+\\]|[^\\[\\]\\.]+)$"
207
+ },
208
+
209
+ "sourceBinding": {
210
+ "description": "One side of a composite panel: a role handle plus an ordinary single-model binding (the sub-binding is #/$defs/binding VERBATIM — pushed down and executed exactly like a plain panel's query). In entity grain the engine injects the link-key columns into the sub-binding's dimensions; they are never authored. 'carry' declares pass-through attributes of this side (also engine-injected, never authored).",
211
+ "type": "object",
212
+ "additionalProperties": false,
213
+ "required": ["role", "binding"],
214
+ "properties": {
215
+ "role": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,23}$" },
216
+ "binding": { "$ref": "#/$defs/binding" },
217
+ "carry": { "type": "array", "maxItems": 4, "items": { "$ref": "#/$defs/carryField" } }
218
+ }
219
+ },
220
+
221
+ "carryField": {
222
+ "description": "One carried pass-through attribute of a source: a fieldRef in this side's model that is single-valued per join key (e.g. a category of the linked entity). The engine injects it into the side's grouping and VERIFIES the single-valued property at run time — a violated declaration fails the query closed, never fans out the join. The joined row exposes it under the bare alias 'as', usable in output.groupBy / select / derived like a join-key alias. On left/full joins, rows missing the carrying side group under a null (unknown) bucket.",
223
+ "type": "object",
224
+ "additionalProperties": false,
225
+ "required": ["field", "as"],
226
+ "properties": {
227
+ "field": { "$ref": "#/$defs/fieldRef" },
228
+ "as": { "type": "string", "minLength": 1, "pattern": "^[^\\[\\]\\.]+$" }
229
+ }
230
+ },
231
+
232
+ "joinOn": {
233
+ "description": "One visual-grain join pair: conformed dimension fieldRefs on the link's left/right side sources, joined under the bare alias 'as'.",
234
+ "type": "object",
235
+ "additionalProperties": false,
236
+ "required": ["left", "right", "as"],
237
+ "properties": {
238
+ "left": { "$ref": "#/$defs/fieldRef" },
239
+ "right": { "$ref": "#/$defs/fieldRef" },
240
+ "as": { "type": "string", "minLength": 1, "pattern": "^[^\\[\\]\\.]+$" }
241
+ }
242
+ },
243
+
244
+ "derivedTerm": {
245
+ "type": "object",
246
+ "additionalProperties": false,
247
+ "required": ["expr", "as"],
248
+ "properties": {
249
+ "expr": {
250
+ "type": "string",
251
+ "minLength": 1,
252
+ "maxLength": 500,
253
+ "description": "Constrained expression over qualified refs: + - * / ( ), numbers, datediff(day|week|month|year, a, b), coalesce(...), abs(x), round(x, n). Parsed by the engine's closed grammar — never raw DAX/SQL."
254
+ },
255
+ "as": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\[\\]]+$" }
256
+ }
257
+ },
258
+
259
+ "compositeOutput": {
260
+ "description": "The final in-engine projection: mode 'rows' passes joined rows through the select terms; mode 'aggregate' groups by groupBy and folds aggregate terms. 'derived' terms are POST-aggregation expressions over the measure-shaped output columns (\"[as]\"), evaluated after grouping and before topN — use for ratio-of-sums (weighted averages, margin %), which per-joined-row derived terms cannot express. Output column keys follow the panel contract: measure-shaped terms come back keyed \"[as]\", dimension-shaped pass-throughs bare \"as\".",
261
+ "type": "object",
262
+ "additionalProperties": false,
263
+ "required": ["mode", "select"],
264
+ "properties": {
265
+ "mode": { "enum": ["rows", "aggregate"] },
266
+ "groupBy": { "type": "array", "items": { "$ref": "#/$defs/qualifiedRef" } },
267
+ "derived": { "type": "array", "maxItems": 4, "items": { "$ref": "#/$defs/derivedTerm" } },
268
+ "select": {
269
+ "type": "array",
270
+ "minItems": 1,
271
+ "items": {
272
+ "oneOf": [
273
+ {
274
+ "type": "object",
275
+ "additionalProperties": false,
276
+ "required": ["from", "as"],
277
+ "properties": {
278
+ "from": { "$ref": "#/$defs/qualifiedRef" },
279
+ "as": { "type": "string", "minLength": 1, "maxLength": 100 }
280
+ }
281
+ },
282
+ {
283
+ "type": "object",
284
+ "additionalProperties": false,
285
+ "required": ["agg", "of", "as"],
286
+ "properties": {
287
+ "agg": { "enum": ["sum", "avg", "min", "max", "count"] },
288
+ "of": { "$ref": "#/$defs/qualifiedRef" },
289
+ "as": { "type": "string", "minLength": 1, "maxLength": 100 }
290
+ }
291
+ }
292
+ ]
293
+ }
294
+ },
295
+ "topN": { "$ref": "#/$defs/topN" }
296
+ }
297
+ },
298
+
299
+ "compositeBinding": {
300
+ "description": "A cross-dataset panel query (cross-dataset-links): two single-model sub-bindings pushed down as ordinary aggregates, hash-joined in the engine through a validated link ('link' names it), derived terms evaluated by the closed expression grammar, then projected/re-aggregated. Entity grain joins per link key (the engine injects the key columns); visual grain joins visual-sized result sets on conformed 'on' dimensions. A source may 'carry' one-sided attributes that are single-valued per join key (runtime-verified) to group the joined result by them. The join inputs are distinct-per-key by construction (verified at run time), so M:N fan-out is structurally absorbed.",
301
+ "type": "object",
302
+ "additionalProperties": false,
303
+ "required": ["link", "sources", "joinGrain", "output"],
304
+ "properties": {
305
+ "link": { "type": "string", "minLength": 1 },
306
+ "sources": {
307
+ "type": "array",
308
+ "minItems": 2,
309
+ "maxItems": 2,
310
+ "items": { "$ref": "#/$defs/sourceBinding" }
311
+ },
312
+ "joinGrain": { "enum": ["entity", "visual"] },
313
+ "on": { "type": "array", "maxItems": 4, "items": { "$ref": "#/$defs/joinOn" } },
314
+ "join": { "enum": ["inner", "left", "full"] },
315
+ "derived": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/derivedTerm" } },
316
+ "output": { "$ref": "#/$defs/compositeOutput" }
317
+ }
318
+ },
319
+
320
+ "display": {
321
+ "description": "The reserved last-mile PII re-hydration hook. B4 implements the two-query trick: it fills the synthetic __label column from labelField after the LLM is out of the loop. piiTier (a rehydration strategy) is distinct from B0's piiClass (a field classification).",
322
+ "type": "object",
323
+ "additionalProperties": false,
324
+ "required": ["labelField"],
325
+ "properties": {
326
+ "labelField": { "$ref": "#/$defs/fieldRef" },
327
+ "piiTier": { "enum": ["none", "rehydrate"] }
328
+ }
329
+ },
330
+
331
+ "colorScale": {
332
+ "description": "Semantic color contract (D6): the spec picks a role, never a raw hex or vendor palette. B6's theme module maps each role to an indigo-derived palette from the theme tokens (light + dark).",
333
+ "type": "object",
334
+ "additionalProperties": false,
335
+ "required": ["scheme"],
336
+ "properties": {
337
+ "scheme": {
338
+ "type": "object",
339
+ "additionalProperties": false,
340
+ "required": ["role"],
341
+ "properties": { "role": { "enum": ["sequential", "categorical", "diverging", "goodBad"] } }
342
+ },
343
+ "domainMid": { "type": "number" }
344
+ }
345
+ },
346
+
347
+ "channel": {
348
+ "type": "object",
349
+ "additionalProperties": false,
350
+ "required": ["field", "type"],
351
+ "properties": {
352
+ "field": {
353
+ "description": "A measureRef (\"[Efficiency %]\" — incl. an inline aggregate's \"[as]\" alias), a fieldRef, or a synthetic: \"__label\" (the rehydrated display name, B4), or the fold pair \"__measure\"/\"__value\" (the renderer unpivots the panel's measure columns into measure-name/measure-value rows — the way to compare several measures as categories in one chart, e.g. an arc of two averages).",
354
+ "type": "string",
355
+ "minLength": 1
356
+ },
357
+ "type": { "enum": ["nominal", "quantitative", "temporal", "ordinal"] },
358
+ "sort": {
359
+ "anyOf": [
360
+ { "enum": ["-x", "x", "-y", "y", "ascending", "descending"] },
361
+ { "type": "null" }
362
+ ]
363
+ },
364
+ "scale": { "$ref": "#/$defs/colorScale" },
365
+ "axis": {
366
+ "type": "object",
367
+ "additionalProperties": false,
368
+ "properties": {
369
+ "title": { "type": "string" },
370
+ "format": { "type": "string" }
371
+ }
372
+ },
373
+ "format": { "type": "string" }
374
+ }
375
+ },
376
+
377
+ "encoding": {
378
+ "description": "Flat, fixed channel set. No layer/concat/facet/repeat (multi-view is the envelope's job via panels[]+layout[]) and no transform/condition/expression/aggregate (anything computed is precomputed by the binding — the ONLY aggregation surface is the binding's measures). The one renderer-side reshape is the __measure/__value fold (a deterministic unpivot of the measure columns, not a computation). This flatness is what removes Vega-Lite's recursion.",
379
+ "type": "object",
380
+ "additionalProperties": false,
381
+ "properties": {
382
+ "x": { "$ref": "#/$defs/channel" },
383
+ "y": { "$ref": "#/$defs/channel" },
384
+ "color": { "$ref": "#/$defs/channel" },
385
+ "size": { "$ref": "#/$defs/channel" },
386
+ "theta": { "$ref": "#/$defs/channel" },
387
+ "row": { "$ref": "#/$defs/channel" },
388
+ "column": { "$ref": "#/$defs/channel" }
389
+ }
390
+ },
391
+
392
+ "chartViz": {
393
+ "description": "The curated, recursion-stripped Vega-Lite subset for chart panels.",
394
+ "type": "object",
395
+ "additionalProperties": false,
396
+ "required": ["mark", "encoding"],
397
+ "properties": {
398
+ "mark": { "enum": ["bar", "line", "area", "point", "arc", "rule", "tick", "rect"] },
399
+ "encoding": { "$ref": "#/$defs/encoding" }
400
+ }
401
+ },
402
+
403
+ "kpiViz": {
404
+ "type": "object",
405
+ "additionalProperties": false,
406
+ "required": ["format"],
407
+ "properties": {
408
+ "format": { "type": "string", "minLength": 1 },
409
+ "delta": {
410
+ "type": "object",
411
+ "additionalProperties": false,
412
+ "required": ["vs"],
413
+ "properties": { "vs": { "enum": ["previous_period", "prior_year", "none"] } }
414
+ },
415
+ "spark": { "type": "boolean" }
416
+ }
417
+ },
418
+
419
+ "gaugeViz": {
420
+ "type": "object",
421
+ "additionalProperties": false,
422
+ "required": ["format", "min", "max"],
423
+ "properties": {
424
+ "format": { "type": "string", "minLength": 1 },
425
+ "min": { "type": "number" },
426
+ "max": { "type": "number" },
427
+ "thresholds": {
428
+ "type": "array",
429
+ "items": {
430
+ "type": "object",
431
+ "additionalProperties": false,
432
+ "required": ["value", "role"],
433
+ "properties": {
434
+ "value": { "type": "number" },
435
+ "role": { "enum": ["sequential", "categorical", "diverging", "goodBad"] }
436
+ }
437
+ }
438
+ }
439
+ }
440
+ },
441
+
442
+ "tableViz": {
443
+ "type": "object",
444
+ "additionalProperties": false,
445
+ "properties": {
446
+ "columns": {
447
+ "type": "array",
448
+ "items": {
449
+ "type": "object",
450
+ "additionalProperties": false,
451
+ "required": ["field"],
452
+ "properties": {
453
+ "field": { "type": "string", "minLength": 1 },
454
+ "label": { "type": "string" },
455
+ "format": { "type": "string" },
456
+ "conditional": { "type": "boolean" }
457
+ }
458
+ }
459
+ },
460
+ "sort": {
461
+ "type": "object",
462
+ "additionalProperties": false,
463
+ "required": ["field", "dir"],
464
+ "properties": {
465
+ "field": { "type": "string", "minLength": 1 },
466
+ "dir": { "enum": ["asc", "desc"] }
467
+ }
468
+ },
469
+ "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000 }
470
+ }
471
+ },
472
+
473
+ "interaction": {
474
+ "description": "Cross-filter reservation (interactivity rung 3). Reserved in the schema for forward-compat; the runtime (a click writes a param) is B6, not B1.",
475
+ "type": "object",
476
+ "additionalProperties": false,
477
+ "properties": {
478
+ "emits": {
479
+ "type": "array",
480
+ "items": {
481
+ "type": "object",
482
+ "additionalProperties": false,
483
+ "required": ["param", "from"],
484
+ "properties": {
485
+ "param": { "type": "string", "minLength": 1 },
486
+ "from": { "enum": ["x", "y", "color", "size", "theta", "row", "column"] }
487
+ }
488
+ }
489
+ }
490
+ }
491
+ },
492
+
493
+ "panel": {
494
+ "type": "object",
495
+ "additionalProperties": false,
496
+ "required": ["id", "type", "title", "viz"],
497
+ "properties": {
498
+ "id": { "type": "string", "minLength": 1 },
499
+ "type": { "enum": ["kpi", "gauge", "table", "bar", "line", "area", "point", "arc", "rule", "tick", "rect"] },
500
+ "title": { "type": "string", "minLength": 1, "maxLength": 200 },
501
+ "binding": { "$ref": "#/$defs/binding" },
502
+ "compositeBinding": { "$ref": "#/$defs/compositeBinding" },
503
+ "display": { "$ref": "#/$defs/display" },
504
+ "viz": { "type": "object" },
505
+ "interaction": { "$ref": "#/$defs/interaction" }
506
+ },
507
+ "oneOf": [{ "required": ["binding"] }, { "required": ["compositeBinding"] }],
508
+ "allOf": [
509
+ {
510
+ "if": { "properties": { "type": { "const": "kpi" } }, "required": ["type"] },
511
+ "then": { "properties": { "viz": { "$ref": "#/$defs/kpiViz" } } }
512
+ },
513
+ {
514
+ "if": { "properties": { "type": { "const": "gauge" } }, "required": ["type"] },
515
+ "then": { "properties": { "viz": { "$ref": "#/$defs/gaugeViz" } } }
516
+ },
517
+ {
518
+ "if": { "properties": { "type": { "const": "table" } }, "required": ["type"] },
519
+ "then": { "properties": { "viz": { "$ref": "#/$defs/tableViz" } } }
520
+ },
521
+ {
522
+ "if": {
523
+ "properties": { "type": { "enum": ["bar", "line", "area", "point", "arc", "rule", "tick", "rect"] } },
524
+ "required": ["type"]
525
+ },
526
+ "then": { "properties": { "viz": { "$ref": "#/$defs/chartViz" } } }
527
+ }
528
+ ]
529
+ }
530
+ }
531
+ }