Rules Management API Client

A TypeScript client library for the SPS Commerce Rules Management API. This package provides type-safe HTTP functions to interact with Rules Management endpoints.

Installation

npm install @spscommerce/rules-management-api

Usage

Basic Setup

import {
  RulesManagementClient,
  createRuleTypesApi,
  createRuleOverridesApi,
  createRulesApi,
  createRuleInstancesApi,
  createRuleTypeSchemasApi,
} from "@spscommerce/rules-management-api";

// Initialize the client
const client = new RulesManagementClient({
  prefixUrl: "https://api.sps-internal.com/rules/v2/",
});

// Create API instances
const ruleTypesApi = createRuleTypesApi(client);
const ruleOverridesApi = createRuleOverridesApi(client);
const rulesApi = createRulesApi(client);
const ruleInstancesApi = createRuleInstancesApi(client);
const ruleSchemasApi = createRuleTypeSchemasApi(client);

Working with Rule Types

// Get all rule types
const ruleTypes = await ruleTypesApi.getRuleTypes();

// Create a new rule type
const newRuleType = await ruleTypesApi.createRuleType({
  name: "Pricing Rules",
  description: "Rules for product pricing",
  selectors: [
    { name: "category", type: "STRING", description: "Product category" },
    { name: "priority", type: "NUMBER", description: "Priority level" },
  ],
  selectorCombinations: [
    { selectors: ["category", "priority"], priority: 1 },
    { selectors: ["category"], priority: 2 },
  ],
});

// Get a specific rule type
const ruleType = await ruleTypesApi.getRuleTypeById("rule-type-id");

Working with Rules

// Get rules for a rule type
const rules = await rulesApi.getRules("rule-type-id");

// Create a new rule
const newRule = await rulesApi.createRule("rule-type-id", {
  name: "High Priority Electronics",
  description: "Rules for high priority electronics",
  selectors: {
    category: "electronics",
    priority: 1,
  },
});

Working with Rule Instances

// Create a rule instance
const ruleInstance = await ruleInstancesApi.createRuleInstance("rule-id", {
  ruleTypeSchemaId: "schema-id",
  payload: {
    // Your rule payload data
    discountPercentage: 10,
    conditions: ["in_stock", "premium_customer"],
  },
});

// Evaluate rule instances
const activeInstances = await ruleInstancesApi.evaluateRuleInstances(
  "rule-type-id",
  {
    selectors: {
      category: "electronics",
      priority: 1,
    },
  }
);

Working with Rule Overrides

// Create a rule override for testing
const ruleOverride = await ruleOverridesApi.createRuleOverride({
  name: "Test Override",
  description: "Testing new rule configurations",
  ruleTypeIds: ["rule-type-id"],
  activations: [{ ruleId: "rule-id", ruleInstanceId: "new-instance-id" }],
});

// Compare override with current state
const comparison = await ruleOverridesApi.compareRuleOverride("override-id");

// Activate the override
await ruleOverridesApi.activateRuleOverride("override-id", {
  description: "Activating tested configuration",
});

Environment Configuration

The client supports different environments:

import {
  RulesManagementClient,
  BASE_URLS,
} from "@spscommerce/rules-management-api";

// Use different environments
const prodClient = new RulesManagementClient({
  prefixUrl: BASE_URLS.prod,
});

const testClient = new RulesManagementClient({
  prefixUrl: BASE_URLS.test,
});

const localClient = new RulesManagementClient({
  prefixUrl: BASE_URLS.local,
});

Type Safety

All API functions are fully typed with Zod schemas for runtime validation:

import type {
  RuleType,
  CreateRuleTypeRequest,
  Rule,
  RuleInstance,
  RuleOverride,
} from "@spscommerce/rules-management-api";

Mock Service Worker (MSW) Support

For testing, the package includes MSW handlers:

import {
  createRuleTypesApiHandlers,
  createRuleOverridesApiHandlers,
} from "@spscommerce/rules-management-api/msw";

// Setup MSW handlers
const handlers = [
  ...createRuleTypesApiHandlers(),
  ...createRuleOverridesApiHandlers(),
];

Zod Schemas

Access Zod schemas for validation:

import {
  ruleTypeSchema,
  ruleSchema,
  ruleInstanceSchema,
} from "@spscommerce/rules-management-api/zod";

API Coverage

This client covers all Rules Management API endpoints:

• Rule Types: CRUD operations, activation, archiving, validation
• Rule Type Schemas: CRUD operations for JSON schemas governing rule payloads
• Rules: CRUD operations, activation, archiving, selector-based filtering
• Rule Instances: CRUD operations, evaluation, archiving
• Rule Overrides: CRUD operations, activation, comparison, archiving

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run example
npm run example