@rippling/rippling-sdk 0.2.0-alpha.108 → 0.2.0-alpha.109

package/resources/spend-categories.d.ts

@@ -0,0 +1,140 @@
+import { APIResource } from "../core/resource.js";
+import * as BusinessPartnersAPI from "./business-partners.js";
+import { APIPromise } from "../core/api-promise.js";
+import { PageCursorURL, PagePromise } from "../core/pagination.js";
+import { RequestOptions } from "../internal/request-options.js";
+export declare class SpendCategories extends APIResource {
+    /**
+     * A list of spend categories.
+     *
+     * - Requires: `Internal Testing`
+     * - Filterable fields: `name`
+     * - Sortable fields: `id`, `created_at`, `updated_at`
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/?filter=filter&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {
+     *         "name": "date_of_birth",
+     *         "reason": "Insufficient entitlements"
+     *       }
+     *     ]
+     *   },
+     *   "results": [
+     *     {
+     *       "id": "string",
+     *       "created_at": "string",
+     *       "updated_at": "string",
+     *       "name": "string",
+     *       "active": false
+     *     }
+     *   ],
+     *   "next_link": "string"
+     * }
+     * ```
+     */
+    list(query?: SpendCategoryListParams | null | undefined, options?: RequestOptions): PagePromise<SpendCategoryListResponsesPageCursorURL, SpendCategoryListResponse>;
+    /**
+     * Retrieve a specific spend category
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/{id}/ HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {}
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): APIPromise<SpendCategoryRetrieveResponse>;
+}
+export type SpendCategoryListResponsesPageCursorURL = PageCursorURL<SpendCategoryListResponse>;
+/**
+ * A Spend category used to classify transaction line items.
+ *
+ *     Inactive categories are included so historical transactions can still resolve their category.
+ */
+export interface SpendCategoryListResponse {
+    /**
+     * Identifier field
+     */
+    id: string;
+    /**
+     * Record creation date
+     */
+    created_at: string;
+    /**
+     * Record update date
+     */
+    updated_at: string;
+    /**
+     * Whether the category is active. Inactive categories remain available for
+     * historical references.
+     */
+    active?: boolean;
+    /**
+     * Name of the Spend category.
+     */
+    name?: string;
+}
+/**
+ * Meta information for the response.
+ */
+export interface SpendCategoryRetrieveResponse extends BusinessPartnersAPI.Meta {
+    /**
+     * Identifier field
+     */
+    id: string;
+    /**
+     * Record creation date
+     */
+    created_at: string;
+    /**
+     * Record update date
+     */
+    updated_at: string;
+    /**
+     * Whether the category is active. Inactive categories remain available for
+     * historical references.
+     */
+    active?: boolean;
+    /**
+     * Name of the Spend category.
+     */
+    name?: string;
+}
+export interface SpendCategoryListParams {
+    cursor?: string;
+    filter?: string;
+    /**
+     * The maximum number of results to return. Defaults to 50. Maximum is 100.
+     */
+    limit?: number;
+    order_by?: string;
+}
+export declare namespace SpendCategories {
+    export { type SpendCategoryListResponse as SpendCategoryListResponse, type SpendCategoryRetrieveResponse as SpendCategoryRetrieveResponse, type SpendCategoryListResponsesPageCursorURL as SpendCategoryListResponsesPageCursorURL, type SpendCategoryListParams as SpendCategoryListParams, };
+}
+//# sourceMappingURL=spend-categories.d.ts.map

package/resources/spend-categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-categories.d.ts","sourceRoot":"","sources":["../src/resources/spend-categories.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,4BAAyB;AAC/C,OAAO,KAAK,mBAAmB,+BAA4B;AAC3D,OAAO,EAAE,UAAU,EAAE,+BAA4B;AACjD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,8BAA2B;AAChE,OAAO,EAAE,cAAc,EAAE,uCAAoC;AAG7D,qBAAa,eAAgB,SAAQ,WAAW;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,IAAI,CACF,KAAK,GAAE,uBAAuB,GAAG,IAAI,GAAG,SAAc,EACtD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,uCAAuC,EAAE,yBAAyB,CAAC;IAOlF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,6BAA6B,CAAC;CAG1F;AAED,MAAM,MAAM,uCAAuC,GAAG,aAAa,CAAC,yBAAyB,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB,CAAC,IAAI;IAC7E;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,CAAC,OAAO,WAAW,eAAe,CAAC;IACvC,OAAO,EACL,KAAK,yBAAyB,IAAI,yBAAyB,EAC3D,KAAK,6BAA6B,IAAI,6BAA6B,EACnE,KAAK,uCAAuC,IAAI,uCAAuC,EACvF,KAAK,uBAAuB,IAAI,uBAAuB,GACxD,CAAC;CACH"}

package/resources/spend-categories.js

@@ -0,0 +1,83 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpendCategories = void 0;
+const resource_1 = require("../core/resource.js");
+const pagination_1 = require("../core/pagination.js");
+const path_1 = require("../internal/utils/path.js");
+class SpendCategories extends resource_1.APIResource {
+    /**
+     * A list of spend categories.
+     *
+     * - Requires: `Internal Testing`
+     * - Filterable fields: `name`
+     * - Sortable fields: `id`, `created_at`, `updated_at`
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/?filter=filter&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {
+     *         "name": "date_of_birth",
+     *         "reason": "Insufficient entitlements"
+     *       }
+     *     ]
+     *   },
+     *   "results": [
+     *     {
+     *       "id": "string",
+     *       "created_at": "string",
+     *       "updated_at": "string",
+     *       "name": "string",
+     *       "active": false
+     *     }
+     *   ],
+     *   "next_link": "string"
+     * }
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.getAPIList('/spend-categories/', (pagination_1.PageCursorURL), {
+            query,
+            ...options,
+        });
+    }
+    /**
+     * Retrieve a specific spend category
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/{id}/ HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {}
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    retrieve(id, options) {
+        return this._client.get((0, path_1.path) `/spend-categories/${id}/`, options);
+    }
+}
+exports.SpendCategories = SpendCategories;
+//# sourceMappingURL=spend-categories.js.map

package/resources/spend-categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-categories.js","sourceRoot":"","sources":["../src/resources/spend-categories.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,sDAAgE;AAEhE,oDAA8C;AAE9C,MAAa,eAAgB,SAAQ,sBAAW;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,IAAI,CACF,QAAoD,EAAE,EACtD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAA,0BAAwC,CAAA,EAAE;YAC7F,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,qBAAqB,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;CACF;AA7ED,0CA6EC"}

package/resources/spend-categories.mjs

@@ -0,0 +1,79 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../core/resource.mjs";
+import { PageCursorURL } from "../core/pagination.mjs";
+import { path } from "../internal/utils/path.mjs";
+export class SpendCategories extends APIResource {
+    /**
+     * A list of spend categories.
+     *
+     * - Requires: `Internal Testing`
+     * - Filterable fields: `name`
+     * - Sortable fields: `id`, `created_at`, `updated_at`
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/?filter=filter&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {
+     *         "name": "date_of_birth",
+     *         "reason": "Insufficient entitlements"
+     *       }
+     *     ]
+     *   },
+     *   "results": [
+     *     {
+     *       "id": "string",
+     *       "created_at": "string",
+     *       "updated_at": "string",
+     *       "name": "string",
+     *       "active": false
+     *     }
+     *   ],
+     *   "next_link": "string"
+     * }
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.getAPIList('/spend-categories/', (PageCursorURL), {
+            query,
+            ...options,
+        });
+    }
+    /**
+     * Retrieve a specific spend category
+     *
+     * @example HTTP
+     * Representative request and response shapes.
+     * ```
+     * GET /spend-categories/{id}/ HTTP/1.1
+     * Host: rest.ripplingapis.com
+     * Accept: application/json
+     * Rippling-Api-Version: 2024-08-01
+     *
+     * HTTP/1.1 200 OK
+     * Content-Type: application/json
+     *
+     * {
+     *   "__meta": {
+     *     "redacted_fields": [
+     *       {}
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    retrieve(id, options) {
+        return this._client.get(path `/spend-categories/${id}/`, options);
+    }
+}
+//# sourceMappingURL=spend-categories.mjs.map

package/resources/spend-categories.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-categories.mjs","sourceRoot":"","sources":["../src/resources/spend-categories.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EAAE,aAAa,EAAe,+BAA2B;AAEhE,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,IAAI,CACF,QAAoD,EAAE,EACtD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAA,aAAwC,CAAA,EAAE;YAC7F,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,qBAAqB,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;CACF"}

package/src/client.ts

@@ -609,6 +609,13 @@ import {
   SoftwareDeploymentUpdateResponse,
   SoftwareDeployments,
 } from './resources/software-deployments';
+import {
+  SpendCategories,
+  SpendCategoryListParams,
+  SpendCategoryListResponse,
+  SpendCategoryListResponsesPageCursorURL,
+  SpendCategoryRetrieveResponse,
+} from './resources/spend-categories';
 import { SSOMe, SSOMeListParams, SSOMeResource } from './resources/sso-me';
 import {
   Team,
@@ -1936,6 +1943,7 @@ export class RipplingSDK {
    * Software deployed to company devices
    */
   softwareDeployments: API.SoftwareDeployments = new API.SoftwareDeployments(this);
+  spendCategories: API.SpendCategories = new API.SpendCategories(this);
   /**
    * Job titles used by the company
    */
@@ -2087,6 +2095,7 @@ RipplingSDK.ScheduledJobAssignments = ScheduledJobAssignments;
 RipplingSDK.Shiftassignments = Shiftassignments;
 RipplingSDK.Sites = Sites;
 RipplingSDK.SoftwareDeployments = SoftwareDeployments;
+RipplingSDK.SpendCategories = SpendCategories;
 RipplingSDK.Titles = Titles;
 RipplingSDK.Unassignedshifts = Unassignedshifts;
 RipplingSDK.VariableCompensationPayouts = VariableCompensationPayouts;
@@ -2928,6 +2937,14 @@ export declare namespace RipplingSDK {
     type SoftwareDeploymentUpdateParams as SoftwareDeploymentUpdateParams,
   };
 
+  export {
+    SpendCategories as SpendCategories,
+    type SpendCategoryListResponse as SpendCategoryListResponse,
+    type SpendCategoryRetrieveResponse as SpendCategoryRetrieveResponse,
+    type SpendCategoryListResponsesPageCursorURL as SpendCategoryListResponsesPageCursorURL,
+    type SpendCategoryListParams as SpendCategoryListParams,
+  };
+
   export {
     Titles as Titles,
     type TitleListResponse as TitleListResponse,

package/src/lib/charts/README.md

@@ -21,11 +21,10 @@ by comparing its value against a constant.
 - **`value`** — this data point's plotted numeric value (a bar's height, a
   point's y, a slice's amount). It is what the rule compares.
 - **Comparisons** — `equals`, `isNot`, `lessThan`, `greaterThan`, `lessOrEqual`, `greaterOrEqual`.
-- **`when(condition, ifTrue, ifFalse?)`** — a conditional value (channel-agnostic).
-  `ifFalse` is optional and defaults to `null` — for a colour, no override (default kept).
+- **`when(condition, ifTrue, ifFalse?)`** — a conditional colour. Both results
+  are colour strings; `ifFalse` defaults to `null` (keep the chart default).
 - **`color(rule)`** — target the colour channel. Wrapping `when(...)` in `color(...)`
-  is what says "this rule sets the colour"; the channel is separate from the condition,
-  so more channels (opacity, label visibility) are just more wrappers later.
+  is what says "this rule sets the colour".
 - **`literal`** — bare constants (`100`, `'#E24B4A'`) are wrapped automatically.
 
 ```ts
@@ -46,7 +45,7 @@ Agent writes a rule with these builders (the only consumer that imports the SDK)
   -> the placeholder is emitted into the chart option, like the {$fn} placeholders
      a chart already emits, and crosses to the app as plain JSON
   -> renderer resolves {$rule} against the point's value -> a colour, drawn
-  -> settings panel reads the same {$rule} tree -> controls the user can edit
+  -> settings panel reads the same flat {$rule} value -> controls the user can edit
 ```
 
 ```json
@@ -64,28 +63,38 @@ Agent writes a rule with these builders (the only consumer that imports the SDK)
 `channel: 'color'` says what the rule targets, so a reader sees it without
 inferring from where it sits. `evaluate(rule, { value })` resolves it to a colour
 for the renderer; `describe(rule)` turns it into the controls the settings panel
-shows. Both accept the placeholder or the bare tree. A node can only ever be one
-of a fixed set of kinds, so the three faces never drift — the `chartRuleSchema`
-export describes that closed set.
+shows. Both accept the placeholder or a bare node. A node can only ever be one
+of a fixed set of kinds. `chartRuleSchema` is the executable Valibot schema for
+that closed set, and `parseChartRule(unknown)` is the SDK-owned runtime boundary
+for persisted or agent-authored JSON.
 
 ## How it is consumed
 
-The app never has to import this package. The rule crosses as data — a `{$rule}`
-placeholder alongside the `{$fn}` ones — and the app's own rehydrator resolves it
-at render time. Two ways, and only the first is needed:
+The rule crosses as data — a `{$rule}` placeholder alongside the `{$fn}` ones.
+Consumers have two integration choices:
 
-1. **Contract-only** — the app keeps its own small evaluator and validates it
-   against `chartRuleSchema` (published here) with a contract test, so the two
-   can't drift without CI noticing. No dependency on this package.
-2. **Shared** — the app imports `evaluate`/`describe` from here, so the closed
-   set is defined exactly once. A no-drift choice, not a requirement.
+1. **Shared (preferred)** — import `evaluate`, `describe`, and
+   `parseChartRule` from the SDK. Parse once when the chart option is hydrated,
+   then pass that parsed value to `evaluate` for every datum. The parsed value is
+   an immutable validated clone, so repeated evaluation does not re-run schema
+   validation.
+2. **Serialized contract** — another language/runtime may interpret the JSON
+   independently. It must maintain parity tests against SDK builder output and
+   fail closed when the package-level `capabilities.json` contract version is
+   unsupported or a serialized rule contains an unknown node kind. Individual
+   serialized rules do not carry a version field.
+
+Valibot is a production dependency because validation executes in shipped SDK
+code. Node and Deno npm consumers resolve it transitively from the package; it
+is not duplicated in the agent reference or capability manifest.
 
 ## Where it is going
 
-The vocabulary starts small on purpose and is built to grow. Each addition is a
-new kind (or channel) — one builder, one `evaluate` case, one `describe` case,
-one `schema` entry — and it becomes editable in the panel the moment it lands,
-with no change to charts already using it. Planned next, roughly in order:
+The vocabulary starts small on purpose. The v1 schema stays flat; features that
+require nesting or a different expression shape must use a new contract version
+rather than silently widening v1. A compatible channel or leaf addition still
+requires one builder, evaluator case, description case, and schema entry.
+Potential future versions may add:
 
 - **More channels** — opacity, label visibility (`show`), and the like, added
   alongside `channel: 'color'`.
@@ -104,11 +113,9 @@ with no change to charts already using it. Planned next, roughly in order:
 
 ## Safety
 
-A rule is data, not code, so evaluating one is not running code. The vocabulary
-has no primitive with a side effect, so an untrusted, user-edited tree is safe
-to evaluate: the worst a malformed tree can do is throw a `ChartRuleError`, which
-the caller catches and turns into the read-only "configured in code" state. There
-are no loops or recursion, and a tree nested past `MAX_RULE_DEPTH` throws
-`RuleDepthError` (also a `ChartRuleError`) rather than overflowing the stack.
-Catch `ChartRuleError` — every failure mode is a subclass of it (`UnknownNodeError`,
-`RuleTypeError`, `RuleDepthError`).
+A rule is data, not code: its vocabulary has no callbacks, loops, or side
+effects. The v1 schema is non-recursive, so rule input cannot create recursive
+validation or evaluation work. Runtime parsing also rejects inherited rule
+fields before Valibot reads them, preventing prototype data from supplying
+operands. Malformed rules throw a `ChartRuleError`; callers can use that one
+base class for every rule-specific failure.

package/src/lib/charts/agent-reference.md

@@ -0,0 +1,73 @@
+# Visualization grammar authoring reference
+
+Use these builders only when a chart property must change according to the
+current data point's numeric value. They produce JSON-safe rule data; they do not
+execute callbacks or render a chart.
+
+## Import
+
+In the Deno TypeScript sandbox, import from the module specifier published in
+`capabilities.json`:
+
+```ts
+import { color, greaterThan, value, when } from 'npm:@rippling/rippling-sdk/lib/charts';
+```
+
+## Builders
+
+- `value` reads the current data point's plotted numeric value.
+- `literal(scalar)` explicitly creates a constant. Bare numbers, strings,
+  booleans, and `null` are converted to literals automatically.
+- `equals(left, right)`, `isNot(left, right)`, `lessThan(left, right)`,
+  `greaterThan(left, right)`, `lessOrEqual(left, right)`, and
+  `greaterOrEqual(left, right)` return a condition.
+- `when(condition, ifTrue, ifFalse?)` returns `ifTrue` when the condition is true
+  and `ifFalse` otherwise. Both results are colour strings; the omitted false
+  branch becomes `null` to preserve the chart's default colour.
+- `color(when(...))` marks the conditional result as a color rule.
+
+Example: highlight values over 20 and otherwise preserve the chart's default
+color.
+
+```ts
+const conditionalColor = color(when(greaterThan(value, 20), '$token:categorical.series-5'));
+```
+
+The builders return plain data that renderers and editors can read. Always use
+the builders above. Do not hand-author the serialized `$rule` object shown here:
+
+```json
+{
+  "channel": "color",
+  "$rule": {
+    "kind": "ifElse",
+    "cond": {
+      "kind": "greaterThan",
+      "left": { "kind": "value" },
+      "right": { "kind": "literal", "value": 20 }
+    },
+    "then": { "kind": "literal", "value": "$token:categorical.series-5" },
+    "else": { "kind": "literal", "value": null }
+  }
+}
+```
+
+## Current limits
+
+The current contract supports only the `color` channel and per-point `value`.
+It has one fixed, non-recursive shape: comparisons contain only `value` or
+literal operands, and `when` contains one comparison plus two colour literals.
+Do not place comparisons, `when(...)`, or `color(...)` inside another operand or
+branch.
+
+Rules do not calculate aggregates such as maximum, average, or percentile. Chart
+code may calculate a finite scalar threshold from its data first and then use
+that scalar in a rule. For example, after computing an 80th-percentile
+`threshold`, use
+`color(when(greaterOrEqual(value, threshold), highlightColor))` to highlight the
+top 20%. The rule remains a per-point comparison; the surrounding chart code
+owns the aggregate calculation.
+
+Other data fields, compound boolean logic, opacity, label visibility, and other
+output channels are not supported. Keep static colors as ordinary chart values
+rather than wrapping them in rules.