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

package/src/client.ts

@@ -102,6 +102,13 @@ import {
   CandidateListResponsesPageCursorURL,
   Candidates,
 } from './resources/candidates';
+import {
+  CardTransactionListParams,
+  CardTransactionListResponse,
+  CardTransactionListResponsesPageCursorURL,
+  CardTransactionRetrieveResponse,
+  CardTransactions,
+} from './resources/card-transactions';
 import { Companies, CompaniesPageCursorURL, Company, CompanyListParams } from './resources/companies';
 import {
   CompanyLegalEntities,
@@ -501,6 +508,13 @@ import {
   PlatformCapabilityListResponse,
   PlatformCapabilityListResponsesPageCursorURL,
 } from './resources/platform-capabilities';
+import {
+  ReimbursementListParams,
+  ReimbursementListResponse,
+  ReimbursementListResponsesPageCursorURL,
+  ReimbursementRetrieveResponse,
+  Reimbursements,
+} from './resources/reimbursements';
 import {
   ReportRunCreateParams,
   ReportRunCreateResponse,
@@ -595,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,
@@ -750,18 +771,6 @@ import {
   WorkflowActionExecutionCreateResponse,
   WorkflowActionExecutions,
 } from './resources/workflow-action-executions';
-import {
-  WorkflowCreateParams,
-  WorkflowCreateResponse,
-  WorkflowListParams,
-  WorkflowListResponse,
-  WorkflowListResponsesPageCursorURL,
-  WorkflowRetrieveParams,
-  WorkflowRetrieveResponse,
-  WorkflowUpdateParams,
-  WorkflowUpdateResponse,
-  Workflows,
-} from './resources/workflows';
 import {
   AgentCreateParams,
   AgentCreateResponse,
@@ -830,6 +839,18 @@ import {
   Supergroups,
   SupergroupsPageCursorURL,
 } from './resources/supergroups/supergroups';
+import {
+  WorkflowCreateParams,
+  WorkflowCreateResponse,
+  WorkflowListParams,
+  WorkflowListResponse,
+  WorkflowListResponsesPageCursorURL,
+  WorkflowRetrieveParams,
+  WorkflowRetrieveResponse,
+  WorkflowUpdateParams,
+  WorkflowUpdateResponse,
+  Workflows,
+} from './resources/workflows/workflows';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -1731,6 +1752,7 @@ export class RipplingSDK {
    * An application by a candidate to a specific job requisition
    */
   candidateApplications: API.CandidateApplications = new API.CandidateApplications(this);
+  cardTransactions: API.CardTransactions = new API.CardTransactions(this);
   /**
    * Legal entities registered by the company
    */
@@ -1888,6 +1910,7 @@ export class RipplingSDK {
    * Custom objects defined by the company
    */
   platformCapabilities: API.PlatformCapabilities = new API.PlatformCapabilities(this);
+  reimbursements: API.Reimbursements = new API.Reimbursements(this);
   /**
    * Report data for company
    */
@@ -1920,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
    */
@@ -2020,6 +2044,7 @@ RipplingSDK.BreakTypes = BreakTypes;
 RipplingSDK.BusinessStructurePaths = BusinessStructurePaths;
 RipplingSDK.Candidates = Candidates;
 RipplingSDK.CandidateApplications = CandidateApplications;
+RipplingSDK.CardTransactions = CardTransactions;
 RipplingSDK.CompanyLegalEntities = CompanyLegalEntities;
 RipplingSDK.CompanyLegalEntityWorkers = CompanyLegalEntityWorkers;
 RipplingSDK.CompensationBandsDetails = CompensationBandsDetails;
@@ -2061,6 +2086,7 @@ RipplingSDK.PackageVersionComponentUpdates = PackageVersionComponentUpdates;
 RipplingSDK.PayrollPaymentModeChanges = PayrollPaymentModeChanges;
 RipplingSDK.PayrollRuns = PayrollRuns;
 RipplingSDK.PlatformCapabilities = PlatformCapabilities;
+RipplingSDK.Reimbursements = Reimbursements;
 RipplingSDK.Reports = Reports;
 RipplingSDK.ReportRuns = ReportRuns;
 RipplingSDK.Sandboxes = Sandboxes;
@@ -2069,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;
@@ -2476,6 +2503,14 @@ export declare namespace RipplingSDK {
     type CandidateApplicationListParams as CandidateApplicationListParams,
   };
 
+  export {
+    CardTransactions as CardTransactions,
+    type CardTransactionListResponse as CardTransactionListResponse,
+    type CardTransactionRetrieveResponse as CardTransactionRetrieveResponse,
+    type CardTransactionListResponsesPageCursorURL as CardTransactionListResponsesPageCursorURL,
+    type CardTransactionListParams as CardTransactionListParams,
+  };
+
   export {
     CompanyLegalEntities as CompanyLegalEntities,
     type CompanyLegalEntityListResponse as CompanyLegalEntityListResponse,
@@ -2809,6 +2844,14 @@ export declare namespace RipplingSDK {
     type PlatformCapabilityListResponsesPageCursorURL as PlatformCapabilityListResponsesPageCursorURL,
   };
 
+  export {
+    Reimbursements as Reimbursements,
+    type ReimbursementListResponse as ReimbursementListResponse,
+    type ReimbursementRetrieveResponse as ReimbursementRetrieveResponse,
+    type ReimbursementListResponsesPageCursorURL as ReimbursementListResponsesPageCursorURL,
+    type ReimbursementListParams as ReimbursementListParams,
+  };
+
   export { Reports as Reports, type ReportRetrieveResponse as ReportRetrieveResponse };
 
   export {
@@ -2894,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.

package/src/lib/charts/builders.ts

@@ -1,37 +1,48 @@
 import { ChartRuleError } from './errors';
 import {
-  type ComparisonKind,
-  type ComparisonNode,
+  type ConditionNode,
+  type ComparisonOperandNode,
+  type EqualityComparisonNode,
   type IfElseNode,
   type LiteralNode,
+  type NumericComparisonNode,
+  type NumericOperandNode,
   type RefNode,
-  type RuleNode,
   type RulePlaceholder,
   type Scalar,
 } from './types';
 
-/** A rule node, a nested rule (`{$rule}` placeholder), or a bare scalar. */
-export type Operand = RuleNode | RulePlaceholder | Scalar;
+/** A non-recursive comparison operand: `value`, a literal node, or a scalar. */
+export type Operand = ComparisonOperandNode | Scalar;
+export type NumericOperand = NumericOperandNode | number;
 
-function isRuleNode(operand: Operand): operand is RuleNode {
-  return typeof operand === 'object' && operand !== null && 'kind' in operand;
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isOperandNode(operand: Operand): operand is ComparisonOperandNode {
+  return typeof operand === 'object' && operand !== null && hasOwn(operand, 'kind');
 }
 
 /** True when a value is a `{$rule}` placeholder — the marker the builders emit. */
 export function isRulePlaceholder(value: unknown): value is RulePlaceholder {
-  return typeof value === 'object' && value !== null && '$rule' in value;
+  return typeof value === 'object' && value !== null && hasOwn(value, '$rule');
 }
 
 /** Wrap a bare scalar as a literal node. */
-export function literal(value: Scalar): LiteralNode {
+export function literal<const TValue extends Scalar>(value: TValue): LiteralNode<TValue> {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new ChartRuleError('literal(value) requires a finite number');
+  }
   return { kind: 'literal', value };
 }
 
-function toNode(operand: Operand): RuleNode {
-  if (isRulePlaceholder(operand)) {
-    return operand.$rule; // a nested rule — unwrap it, never wrap it as a literal
-  }
-  return isRuleNode(operand) ? operand : literal(operand);
+function toOperandNode(operand: Operand): ComparisonOperandNode {
+  return isOperandNode(operand) ? operand : literal(operand);
+}
+
+function toNumericOperandNode(operand: NumericOperand): NumericOperandNode {
+  return typeof operand === 'number' ? literal(operand) : operand;
 }
 
 /**
@@ -40,36 +51,43 @@ function toNode(operand: Operand): RuleNode {
  */
 export const value: RefNode = Object.freeze({ kind: 'value' });
 
-/* Comparisons — return a condition. */
-function comparison(kind: ComparisonKind): (left: Operand, right: Operand) => ComparisonNode {
-  return (left, right) => ({ kind, left: toNode(left), right: toNode(right) });
+/* Comparisons — return a condition with no nested expressions. */
+function equalityComparison(
+  kind: EqualityComparisonNode['kind'],
+): (left: Operand, right: Operand) => EqualityComparisonNode {
+  return (left, right) => ({ kind, left: toOperandNode(left), right: toOperandNode(right) });
+}
+function numericComparison(
+  kind: NumericComparisonNode['kind'],
+): (left: NumericOperand, right: NumericOperand) => NumericComparisonNode {
+  return (left, right) => ({ kind, left: toNumericOperandNode(left), right: toNumericOperandNode(right) });
 }
-export const equals = comparison('equals');
-export const isNot = comparison('isNot');
-export const lessThan = comparison('lessThan');
-export const greaterThan = comparison('greaterThan');
-export const lessOrEqual = comparison('lessOrEqual');
-export const greaterOrEqual = comparison('greaterOrEqual');
+export const equals = equalityComparison('equals');
+export const isNot = equalityComparison('isNot');
+export const lessThan = numericComparison('lessThan');
+export const greaterThan = numericComparison('greaterThan');
+export const lessOrEqual = numericComparison('lessOrEqual');
+export const greaterOrEqual = numericComparison('greaterOrEqual');
 
 /**
- * A conditional value: pick `ifTrue` when the condition holds, else `ifFalse`.
- * Channel-agnostic — wrap it in a channel builder (`color`) to target something.
+ * A conditional colour: pick `ifTrue` when the condition holds, else `ifFalse`.
  *
  *   when(lessThan(value, 100), '#E24B4A', '#378ADD')
  *   // → '#E24B4A' when this point's value is under 100, '#378ADD' otherwise
  *
  * `ifFalse` is optional and defaults to `null` — for a colour, that means no
- * override (the chart's default is kept). Returns a plain node, not a placeholder.
+ * override (the chart's default is kept). Branches are colour literals only;
+ * nested rules are intentionally unsupported in v1.
  */
-export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): IfElseNode {
+export function when(condition: ConditionNode, ifTrue: string, ifFalse: string | null = null): IfElseNode {
   if (ifTrue === undefined) {
     throw new ChartRuleError('when(condition, ifTrue, ifFalse?) needs a value for the true case');
   }
   return {
     kind: 'ifElse',
     cond: condition,
-    then: toNode(ifTrue),
-    else: toNode(ifFalse ?? null),
+    then: literal(ifTrue),
+    else: literal(ifFalse),
   };
 }
 
@@ -80,11 +98,9 @@ export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): I
  *   color(when(lessThan(value, 100), '#E24B4A', '#378ADD'))
  *   // → red when this point's value is under 100, blue otherwise
  *
- * Takes a conditional value — a `when(...)` (`IfElseNode`) or an already-wrapped
- * rule — not a bare `value` or comparison: those resolve to a number or a
- * boolean, which is not a colour. `evaluate` enforces the same at runtime for a
- * deserialized rule. Returns a `{$rule}` placeholder tagged `channel: 'color'`.
+ * Takes the flat conditional value produced by `when(...)`. Returns a `{$rule}`
+ * placeholder tagged `channel: 'color'`.
  */
-export function color(rule: IfElseNode | RulePlaceholder): RulePlaceholder {
-  return { $rule: isRulePlaceholder(rule) ? rule.$rule : rule, channel: 'color' };
+export function color(rule: IfElseNode): RulePlaceholder {
+  return { $rule: rule, channel: 'color' };
 }

package/src/lib/charts/capabilities.json

@@ -0,0 +1,96 @@
+{
+  "contractVersion": 1,
+  "moduleSpecifier": "npm:@rippling/rippling-sdk/lib/charts",
+  "builders": {
+    "value": {
+      "kind": "input",
+      "returns": "number"
+    },
+    "literal": {
+      "kind": "literal",
+      "parameters": [
+        "scalar"
+      ],
+      "returns": "value"
+    },
+    "equals": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "isNot": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "lessThan": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "greaterThan": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "lessOrEqual": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "greaterOrEqual": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "when": {
+      "kind": "conditional",
+      "parameters": [
+        "condition",
+        "color",
+        "color?"
+      ],
+      "returns": "conditional-color"
+    },
+    "color": {
+      "kind": "channel",
+      "parameters": [
+        "conditional-color"
+      ],
+      "returns": "color-rule",
+      "placeholderChannel": "color"
+    }
+  },
+  "supportedChannels": [
+    "color"
+  ],
+  "supportedNodeKinds": [
+    "literal",
+    "value",
+    "equals",
+    "isNot",
+    "lessThan",
+    "greaterThan",
+    "lessOrEqual",
+    "greaterOrEqual",
+    "ifElse"
+  ]
+}