npm package: @spscommerce/rules-management-api
Description: Rules Management API is a collection of HTTP functions created for Assortment UIs to call Rules Management endpoints
Author: Assortment
Latest version: 2.0.0

# 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

```bash
npm install @spscommerce/rules-management-api
```

## Usage

### Basic Setup

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```typescript
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:

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

## Mock Service Worker (MSW) Support

For testing, the package includes MSW handlers:

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

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

## Zod Schemas

Access Zod schemas for validation:

```typescript
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

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run example
npm run example
```