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

package/src/lib/charts/errors.ts

@@ -0,0 +1,48 @@
+/** Base class for every error the chart-rule evaluator can throw. */
+export class ChartRuleError extends Error {}
+
+/**
+ * A node whose `kind` is not in the vocabulary. The caller catches this and
+ * shows the setting as "configured in code", read-only.
+ */
+export class UnknownNodeError extends ChartRuleError {
+  constructor(public readonly kind?: string) {
+    super(`Unknown chart-rule node: ${kind ?? '(missing kind)'}`);
+    this.name = 'UnknownNodeError';
+  }
+}
+
+/** A node evaluated to the wrong type of value (e.g. comparing non-numbers). */
+export class RuleTypeError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RuleTypeError';
+  }
+}
+
+/**
+ * A structurally invalid node in a deserialized tree: not an object, no string
+ * `kind`, or a `literal` without a scalar `value`. Distinct from
+ * `UnknownNodeError` (a well-formed node whose `kind` is simply not in the
+ * vocabulary — the intentional escape hatch). Like the others it is a
+ * `ChartRuleError`, so a caller reading an untrusted rule catches it instead of
+ * a native `TypeError` (or, worse, an `undefined` slipping through silently).
+ */
+export class MalformedRuleError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MalformedRuleError';
+  }
+}
+
+/**
+ * A rule nested deeper than the evaluator will walk. Guards against a
+ * stack-overflowing tree from untrusted, deserialized input; like the others it
+ * is a `ChartRuleError`, so the caller's escape hatch catches it.
+ */
+export class RuleDepthError extends ChartRuleError {
+  constructor(maxDepth: number) {
+    super(`chart rule nested deeper than ${maxDepth} levels`);
+    this.name = 'RuleDepthError';
+  }
+}

package/src/lib/charts/evaluate.ts

@@ -0,0 +1,114 @@
+import { isRulePlaceholder } from './builders';
+import { MalformedRuleError, RuleDepthError, RuleTypeError, UnknownNodeError } from './errors';
+import { assertRuleNode, literalValue } from './guards';
+import {
+  MAX_RULE_DEPTH,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RuleValue,
+} from './types';
+
+/**
+ * Resolve a rule to a value against `ctx`. Accepts a `{$rule}` placeholder or a
+ * bare tree. A malformed or unknown node throws a `ChartRuleError` (never a
+ * native `TypeError`), so a caller reading an untrusted, deserialized rule can
+ * catch every failure with one type. When the rule is a colour placeholder, the
+ * result is checked to be a colour (`string | null`) — a rule that resolves to a
+ * number or boolean is a `RuleTypeError`, not something the renderer paints.
+ *
+ * Pure: the only inputs are the node and the context. No clock, no randomness,
+ * no I/O — which is what makes it safe to run on an untrusted, user-edited tree
+ * and identical across the renderer, the panel readout, and a test. A tree
+ * nested past `MAX_RULE_DEPTH` throws `RuleDepthError` rather than overflowing.
+ */
+export function evaluate(rule: Rule, ctx: RuleContext): RuleValue {
+  if (isRulePlaceholder(rule)) {
+    return coerceForChannel(rule.channel, visit(rule.$rule, ctx, 0));
+  }
+  return visit(rule, ctx, 0);
+}
+
+function visit(node: RuleNode, ctx: RuleContext, depth: number): RuleValue {
+  if (depth > MAX_RULE_DEPTH) {
+    throw new RuleDepthError(MAX_RULE_DEPTH);
+  }
+  assertRuleNode(node);
+  const next = depth + 1;
+  switch (node.kind) {
+    case 'value':
+      return ctx.value;
+    case 'literal':
+      return literalValue(node);
+
+    case 'equals':
+      return visit(node.left, ctx, next) === visit(node.right, ctx, next);
+    case 'isNot':
+      return visit(node.left, ctx, next) !== visit(node.right, ctx, next);
+    case 'lessThan':
+      return num(visit(node.left, ctx, next)) < num(visit(node.right, ctx, next));
+    case 'greaterThan':
+      return num(visit(node.left, ctx, next)) > num(visit(node.right, ctx, next));
+    case 'lessOrEqual':
+      return num(visit(node.left, ctx, next)) <= num(visit(node.right, ctx, next));
+    case 'greaterOrEqual':
+      return num(visit(node.left, ctx, next)) >= num(visit(node.right, ctx, next));
+
+    case 'ifElse':
+      return bool(visit(node.cond, ctx, next)) ? visit(node.then, ctx, next) : visit(node.else, ctx, next);
+
+    default:
+      return unreachable(node);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Coercions — narrow a RuleValue, or throw a typed error.                      */
+/* -------------------------------------------------------------------------- */
+
+function num(value: RuleValue): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+  throw new RuleTypeError(`expected a number, got ${typeName(value)}`);
+}
+
+function bool(value: RuleValue): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  throw new RuleTypeError(`expected a boolean, got ${typeName(value)}`);
+}
+
+/** A colour channel must resolve to a colour string, or null for "no override". */
+function asColor(value: RuleValue): RuleValue {
+  if (value === null || typeof value === 'string') {
+    return value;
+  }
+  throw new RuleTypeError(`a colour rule must resolve to a colour string or null, got ${typeName(value)}`);
+}
+
+/**
+ * Coerce a resolved value to what its channel can use. A colour rule must
+ * resolve to a colour; a future channel would add its own case here. A
+ * placeholder whose `channel` is missing or unrecognised (only possible from
+ * untrusted, deserialized input — the type and schema both pin it to `'color'`)
+ * is malformed rather than silently unchecked.
+ */
+function coerceForChannel(channel: RuleChannel, value: RuleValue): RuleValue {
+  switch (channel) {
+    case 'color':
+      return asColor(value);
+    default:
+      throw new MalformedRuleError(`a rule placeholder has an unsupported channel: ${String(channel)}`);
+  }
+}
+
+function typeName(value: RuleValue): string {
+  return value === null ? 'null' : typeof value;
+}
+
+function unreachable(node: never): never {
+  throw new UnknownNodeError((node as { kind?: string }).kind);
+}

package/src/lib/charts/guards.ts

@@ -0,0 +1,42 @@
+import { MalformedRuleError } from './errors';
+import { type RuleNode, type Scalar } from './types';
+
+/**
+ * Runtime validation for one node of a deserialized, untrusted rule tree, shared
+ * by `evaluate` and `describe`. A rule can arrive from JSON that TypeScript never
+ * checked, so `null`, a non-object, or a node without a string `kind` would throw
+ * a native `TypeError` on the first field read — skipping the `ChartRuleError`
+ * escape hatch a caller relies on. Validate before reading fields.
+ */
+
+const SCALAR_TYPES: ReadonlySet<string> = new Set(['number', 'string', 'boolean']);
+
+/**
+ * Assert `node` is shaped like a rule node — an object carrying a string `kind`.
+ * An unrecognised `kind` is *not* rejected here; that is the caller's `switch`
+ * default (`UnknownNodeError`), the deliberate "configured in code" signal.
+ */
+export function assertRuleNode(node: unknown): asserts node is RuleNode {
+  if (
+    node === null ||
+    typeof node !== 'object' ||
+    Array.isArray(node) ||
+    typeof (node as { kind?: unknown }).kind !== 'string'
+  ) {
+    throw new MalformedRuleError('a rule node must be an object with a string "kind"');
+  }
+}
+
+/**
+ * Read a `literal` node's `value`, rejecting a missing or non-scalar one. Without
+ * this, `{ kind: 'literal' }` resolves to `undefined` and slips past the caller.
+ */
+export function literalValue(node: { value?: unknown }): Scalar {
+  const { value } = node;
+  if (value === null || SCALAR_TYPES.has(typeof value)) {
+    return value as Scalar;
+  }
+  throw new MalformedRuleError(
+    `a literal must carry a scalar value, got ${value === undefined ? 'undefined' : typeof value}`,
+  );
+}

package/src/lib/charts/schema.ts

@@ -0,0 +1,72 @@
+import { CHART_RULE_CONTRACT_VERSION } from './types';
+
+/** Stable identifier for the published contract, versioned by the tag. */
+export const CHART_RULE_SCHEMA_ID = `https://rippling.com/schemas/${CHART_RULE_CONTRACT_VERSION}.json`;
+
+/**
+ * JSON Schema (2020-12) for the `{$rule}` placeholder and its closed node set.
+ *
+ * This is the contract. A consumer that keeps its own rule evaluator (rather
+ * than importing `evaluate`) can validate against this so the two never drift —
+ * every kind and operand shape the builders can emit is described here.
+ */
+export const chartRuleSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: CHART_RULE_SCHEMA_ID,
+  title: 'Chart rule placeholder',
+  description: 'A rule tree the chart agent emits into a chart option, marked with $rule.',
+  type: 'object',
+  required: ['$rule', 'channel'],
+  additionalProperties: false,
+  properties: {
+    // A colour rule's top-level tree is the conditional-value form (`when(...)`),
+    // matching what `color()` builds and accepts. A bare ref/comparison/literal
+    // resolves to a number/boolean/constant, not a colour decision.
+    $rule: { $ref: '#/$defs/ifElse' },
+    channel: { const: 'color' },
+  },
+  $defs: {
+    scalar: { type: ['number', 'string', 'boolean', 'null'] },
+    node: {
+      oneOf: [
+        { $ref: '#/$defs/ref' },
+        { $ref: '#/$defs/literal' },
+        { $ref: '#/$defs/comparison' },
+        { $ref: '#/$defs/ifElse' },
+      ],
+    },
+    ref: {
+      type: 'object',
+      required: ['kind'],
+      additionalProperties: false,
+      properties: { kind: { const: 'value' } },
+    },
+    literal: {
+      type: 'object',
+      required: ['kind', 'value'],
+      additionalProperties: false,
+      properties: { kind: { const: 'literal' }, value: { $ref: '#/$defs/scalar' } },
+    },
+    comparison: {
+      type: 'object',
+      required: ['kind', 'left', 'right'],
+      additionalProperties: false,
+      properties: {
+        kind: { enum: ['equals', 'isNot', 'lessThan', 'greaterThan', 'lessOrEqual', 'greaterOrEqual'] },
+        left: { $ref: '#/$defs/node' },
+        right: { $ref: '#/$defs/node' },
+      },
+    },
+    ifElse: {
+      type: 'object',
+      required: ['kind', 'cond', 'then', 'else'],
+      additionalProperties: false,
+      properties: {
+        kind: { const: 'ifElse' },
+        cond: { $ref: '#/$defs/node' },
+        then: { $ref: '#/$defs/node' },
+        else: { $ref: '#/$defs/node' },
+      },
+    },
+  },
+} as const;

package/src/lib/charts/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Chart rule vocabulary — shared types.
+ *
+ * A rule is a small, serializable tree of nodes discriminated by `kind`. The
+ * agent builds it with the helpers in `builders.ts`, which emit it wrapped in a
+ * `{$rule}` placeholder — the same idea as the `{$fn}` placeholders a chart
+ * already emits. The renderer resolves it with `evaluate`; the settings panel
+ * reads it with `describe`. All three agree because a node can only ever be one
+ * of the kinds defined here — the closed set the `chartRuleSchema` describes.
+ *
+ * v1 is scoped to conditional formatting: compare this datum's `value` against a
+ * constant, and (optionally) pick between two values. Richer pieces — aggregates,
+ * logic, more refs — are the documented roadmap in the README.
+ */
+
+export const CHART_RULE_CONTRACT_VERSION = 'chart_rule.v1' as const;
+export type ChartRuleContractVersion = typeof CHART_RULE_CONTRACT_VERSION;
+
+/** A leaf value a rule can carry or resolve to. */
+export type Scalar = number | string | boolean | null;
+
+/* -------------------------------------------------------------------------- */
+/* Nodes — the closed set, discriminated by `kind`. Each appears in every face. */
+/* -------------------------------------------------------------------------- */
+
+/** Reads a value out of the evaluation context — this datum's plotted value. */
+export type RefNode = { kind: 'value' };
+
+export interface LiteralNode {
+  kind: 'literal';
+  value: Scalar;
+}
+
+export type ComparisonKind =
+  | 'equals'
+  | 'isNot'
+  | 'lessThan'
+  | 'greaterThan'
+  | 'lessOrEqual'
+  | 'greaterOrEqual';
+export interface ComparisonNode {
+  kind: ComparisonKind;
+  left: RuleNode;
+  right: RuleNode;
+}
+
+/** The conditional-value form produced by `when(cond, then, else)`. */
+export interface IfElseNode {
+  kind: 'ifElse';
+  cond: RuleNode;
+  then: RuleNode;
+  else: RuleNode;
+}
+
+/** Any node of a rule tree. */
+export type RuleNode = RefNode | LiteralNode | ComparisonNode | IfElseNode;
+
+/* -------------------------------------------------------------------------- */
+/* The placeholder — how a rule is embedded in a chart option (like {$fn}).     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The chart channel a rule drives. v1 supports colour only — a rule decides the
+ * colour of a series/datum. Other channels (opacity, label visibility, …) are
+ * the documented roadmap and would be added here.
+ */
+export type RuleChannel = 'color';
+
+/**
+ * What a builder returns: a rule tree, marked so the renderer can find it, and
+ * tagged with the channel it targets. `channel: 'color'` says this resolves to a
+ * colour — so a reader sees the target without inferring it from where it sits.
+ */
+export interface RulePlaceholder {
+  $rule: RuleNode;
+  channel: RuleChannel;
+}
+
+/** A placeholder, or the bare tree — what `evaluate` and `describe` accept. */
+export type Rule = RulePlaceholder | RuleNode;
+
+/* -------------------------------------------------------------------------- */
+/* Evaluation                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** What a rule is evaluated against: the current datum's value. */
+export interface RuleContext {
+  value: number;
+}
+
+/** The result of evaluating a node. */
+export type RuleValue = Scalar;
+
+/**
+ * The deepest a rule may nest before `evaluate`/`describe` refuse it. Real rules
+ * are a handful of levels; this only stops a pathological deserialized tree from
+ * overflowing the stack. Far below the JS call-stack limit.
+ */
+export const MAX_RULE_DEPTH = 256;
+
+/* -------------------------------------------------------------------------- */
+/* Description — what the settings panel renders                                */
+/* -------------------------------------------------------------------------- */
+
+export type ControlRole = 'rule' | 'comparison' | 'ref' | 'literal';
+
+/** A node as the panel should show it: a label, its editable value, its parts. */
+export interface Control {
+  role: ControlRole;
+  label: string;
+  value?: Scalar;
+  parts?: Control[];
+}

package/src/lib/charts.ts

@@ -0,0 +1,43 @@
+export {
+  color,
+  equals,
+  greaterOrEqual,
+  greaterThan,
+  isNot,
+  isRulePlaceholder,
+  lessOrEqual,
+  lessThan,
+  literal,
+  value,
+  when,
+  type Operand,
+} from './charts/builders';
+export { evaluate } from './charts/evaluate';
+export { describe } from './charts/describe';
+export { chartRuleSchema, CHART_RULE_SCHEMA_ID } from './charts/schema';
+export {
+  ChartRuleError,
+  MalformedRuleError,
+  RuleDepthError,
+  RuleTypeError,
+  UnknownNodeError,
+} from './charts/errors';
+export {
+  CHART_RULE_CONTRACT_VERSION,
+  MAX_RULE_DEPTH,
+  type ChartRuleContractVersion,
+  type ComparisonKind,
+  type ComparisonNode,
+  type Control,
+  type ControlRole,
+  type IfElseNode,
+  type LiteralNode,
+  type RefNode,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RulePlaceholder,
+  type RuleValue,
+  type Scalar,
+} from './charts/types';

package/src/resources/custom-settings.ts

@@ -12,7 +12,7 @@ export class CustomSettings extends APIResource {
   /**
    * A list of Setting.
    *
-   * - Requires: `Functions API`
+   * - Requires: `API Tier 1`
    * - Sortable fields: `id`, `created_at`, `updated_at`
    *
    * @example HTTP

package/src/resources/hire-requirements.ts

@@ -9,8 +9,9 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class HireRequirements extends APIResource {
   /**
-   * Return baseline required fields for a country and hire type. POST /hires/
-   * remains authoritative for company-specific validation.
+   * Return baseline required fields for a country and hire type.
+   * requirements_version identifies this catalog snapshot. POST /hires/ does not
+   * accept it. POST /hires/ remains authoritative for company-specific validation.
    *
    * @example HTTP
    * Representative request and response shapes.
@@ -30,23 +31,6 @@ export class HireRequirements extends APIResource {
    *   "required_groups": [
    *     "string"
    *   ],
-   *   "top_level_fields": [
-   *     {
-   *       "field": "string",
-   *       "type": {},
-   *       "requiredness": "string",
-   *       "required_when": {
-   *         "field": "string",
-   *         "operator": "string",
-   *         "value": {}
-   *       },
-   *       "format": "string",
-   *       "items": null,
-   *       "fields": [
-   *         "string"
-   *       ]
-   *     }
-   *   ],
    *   "fields_by_group": [
    *     null
    *   ],
@@ -79,12 +63,13 @@ export interface HireRequirementListResponse {
   fields_by_group: Array<unknown>;
 
   /**
-   * Hire type used for the lookup.
+   * Hire type for this catalog. POST /hires/ uses the same value. An omitted POST
+   * value defaults to direct_hire.
    */
   hire_type: string;
 
   /**
-   * Catalog groups that apply for this selector tuple.
+   * Groups you must send for this country.
    */
   required_groups: Array<string>;
 
@@ -93,11 +78,6 @@ export interface HireRequirementListResponse {
    */
   requirements_version: string;
 
-  /**
-   * Item-level fields such as client_request_id.
-   */
-  top_level_fields?: Array<HireRequirementListResponse.TopLevelField>;
-
   /**
    * Public field paths that are not writable for this selector tuple.
    */
@@ -109,67 +89,10 @@ export interface HireRequirementListResponse {
   warnings?: Array<string>;
 }
 
-export namespace HireRequirementListResponse {
-  export interface TopLevelField {
-    /**
-     * JSON type string, or a list of allowed types for custom-field values.
-     */
-    type: unknown;
-
-    /**
-     * Public field name relative to its group, or omitted for array item descriptors.
-     */
-    field?: string;
-
-    /**
-     * Nested object fields when type is object.
-     */
-    fields?: Array<unknown>;
-
-    /**
-     * date means YYYY-MM-DD.
-     */
-    format?: string;
-
-    items?: unknown;
-
-    /**
-     * Sibling-field condition when requiredness is dependent.
-     */
-    required_when?: TopLevelField.RequiredWhen;
-
-    /**
-     * required, optional, or dependent.
-     */
-    requiredness?: string;
-  }
-
-  export namespace TopLevelField {
-    /**
-     * Sibling-field condition when requiredness is dependent.
-     */
-    export interface RequiredWhen {
-      /**
-       * Sibling field in the same object that this condition inspects.
-       */
-      field: string;
-
-      /**
-       * equals, not_equals, present, or absent.
-       */
-      operator: string;
-
-      /**
-       * Comparison value for equals and not_equals. Omitted for present and absent.
-       */
-      value?: unknown;
-    }
-  }
-}
-
 export interface HireRequirementListParams {
   /**
-   * ISO 3166-1 alpha-2 country code. First milestone supports US and CA.
+   * ISO 3166-1 alpha-2 country code. Direct hire is supported in AU, CA, CH, CN, DE,
+   * ES, FR, GB, HK, IE, IN, NL, NZ, and US.
    */
   country_code: string;