@ocusell/playground-link

Build deep-link URLs to the Rulesetta Playground for debugging RCP-019 validation rules with prefilled data.

Install

npm install @ocusell/playground-link

Usage

import { createPlaygroundUrl } from "@ocusell/playground-link";

const url = createPlaygroundUrl("http://localhost:3000/playground", {
  expression: "PropertyType = 'RESI' .AND. ListPrice > 0",
  action: "REJECT",
  data: {
    PropertyType: "RESI",
    ListPrice: 250000,
    Status: "Active",
  },
  previousData: {
    PropertyType: null,
    ListPrice: 100000,
  },
  meta: {
    ruleId: "R-42",
    fieldName: "ListPrice",
    errorText: "ListPrice must be greater than zero",
  },
});

// Open the playground with everything prefilled
window.open(url, "_blank");

The playground opens with the expression, action, data, and previous data already loaded. If meta is provided, a context bar is shown with the rule ID, field name, and error text.

API

createPlaygroundUrl(baseUrl, state)

Returns a full URL string (https://host/play#<encoded>) pointing to the playground with the given state encoded in the URL fragment.

| Parameter | Type | Description | |---|---|---| | baseUrl | string | Base URL of the Rulesetta server (e.g. http://localhost:3000/playground) | | state | PlaygroundState | State to prefill in the playground |

encodeFragment(state)

Encodes a PlaygroundState into a base64url fragment string (without the # prefix).

parsePlaygroundFragment(fragment)

Decodes a fragment string back into a PlaygroundState. Returns null if the fragment is invalid. Accepts fragments with or without a leading #.

PlaygroundState

interface PlaygroundState {
  expression: string;
  action: string;
  data: Record<string, unknown>;
  previousData?: Record<string, unknown>;
  fieldName?: string;
  autoTidy?: boolean;
  meta?: {
    ruleId?: string;
    fieldName?: string;
    errorText?: string;
    warningText?: string;
    description?: string;
  };
}

How It Works

The state is JSON-serialized and base64-encoded into the URL fragment (#). Since fragments are never sent to the server, there is no persistence, no server-side storage, and no data leakage in server logs. The playground's client-side JavaScript decodes the fragment on page load and populates the editors.